diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 285ff8e072..c14e060e0f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -56,7 +56,7 @@ jobs:
           filters: .github/ci-paths.yml
 
       - name: Validate CI contracts
-        run: node --test scripts/ci-workflow.test.mjs scripts/daemon-launch-contract.test.mjs scripts/sync-fdroid-changelogs.test.mjs scripts/upload-release-assets.test.mjs
+        run: node --test scripts/ci-workflow.test.mjs scripts/daemon-launch-contract.test.mjs scripts/changelog-utils.test.mjs scripts/sync-fdroid-changelogs.test.mjs scripts/sync-release-notes-from-changelog.test.mjs scripts/upload-release-assets.test.mjs
 
   quality:
     name: quality
diff --git a/.oxlintrc.json b/.oxlintrc.json
index c82b517844..ae335c0e48 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -406,10 +406,7 @@
     {
       "files": [
         "packages/app/src/app/_layout.tsx",
-        "packages/app/src/app/pair-scan.tsx",
         "packages/app/src/components/adaptive-modal-sheet.tsx",
-        "packages/app/src/components/add-host-method-modal.tsx",
-        "packages/app/src/components/add-host-modal.tsx",
         "packages/app/src/components/agent-list.tsx",
         "packages/app/src/components/agent-status-dot.tsx",
         "packages/app/src/components/attachment-lightbox.tsx",
@@ -428,7 +425,6 @@
         "packages/app/src/components/hosts/host-picker.tsx",
         "packages/app/src/components/icons/paseo-logo.tsx",
         "packages/app/src/components/left-sidebar.tsx",
-        "packages/app/src/components/pair-link-modal.tsx",
         "packages/app/src/components/plan-card.tsx",
         "packages/app/src/components/provider-diagnostic-sheet.tsx",
         "packages/app/src/components/question-form-card.tsx",
@@ -543,14 +539,10 @@
         "packages/app/src/agent-skills/selection-sheet.tsx",
         "packages/app/src/agent-stream/chat-outline/rail.web.tsx",
         "packages/app/src/agent-stream/view.tsx",
-        "packages/app/src/app/pair-scan.tsx",
         "packages/app/src/changelog/internal/changelog-sheet.tsx",
         "packages/app/src/command-center/command-center.tsx",
         "packages/app/src/components/adaptive-modal-sheet.tsx",
-        "packages/app/src/components/add-host-method-modal.tsx",
-        "packages/app/src/components/add-host-modal.tsx",
         "packages/app/src/components/add-project-flow.tsx",
-        "packages/app/src/components/add-remote-ssh-host-modal.tsx",
         "packages/app/src/components/agent-list.tsx",
         "packages/app/src/components/app-diagnostic-sheet.tsx",
         "packages/app/src/components/attachment-lightbox.tsx",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e47984dbf7..1a037034b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,15 +1,246 @@
 # Changelog
 
-Not released yet. These changes are on `main` but not in 0.14.0; the next release entry includes them.
+## 0.16.0-beta.1 - 2026-11-10
 
-Added:
+- **Background tasks:** Paseo now shows the background tasks an agent is running, such as shells and monitors, above the composer, with a Stop button for each. Works with Claude Code, Codex and OpenCode v2. ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162) by [@fxlelouarn](https://github.com/fxlelouarn))
+- **Faster diff loading:** Opening Changes shows the file tree right away while file contents load. Large diffs arrive in batches, so the rest of the app keeps responding while they load, and diffs take priority over the daemon's background worktree scans. ([#8907](https://github.com/getpaseo/paseo/pull/8907), [#9241](https://github.com/getpaseo/paseo/pull/9241), [#9243](https://github.com/getpaseo/paseo/pull/9243))
+- **Fewer reconnects on return:** Returning to the app keeps a working connection, including one in the middle of a large response, and reconnects once when it has to. On a host with several saved connections, Paseo stays on the one that works. ([#8651](https://github.com/getpaseo/paseo/pull/8651), [#9086](https://github.com/getpaseo/paseo/pull/9086), [#8855](https://github.com/getpaseo/paseo/pull/8855), [#9116](https://github.com/getpaseo/paseo/pull/9116))
+- **Keyboard shortcuts on mobile:** With a keyboard connected, iPad and Android now run the same shortcuts as desktop, including your custom bindings. Shortcut hints and Settings → Shortcuts appear when a keyboard is detected. Shortcuts also work in narrow desktop and browser windows. ([#8625](https://github.com/getpaseo/paseo/pull/8625) by [@jeroenfrenken](https://github.com/jeroenfrenken), [@lstroud](https://github.com/lstroud))
+- **Touch-sized tablet controls:** On iPad and other touch-screen devices, the wide layout now has touch-sized buttons, rows and bars. The composer toolbar folds its controls into the model menu when space runs out, and swiping right on the workspace reveals a collapsed sidebar as an overlay. ([#8748](https://github.com/getpaseo/paseo/pull/8748), [#8885](https://github.com/getpaseo/paseo/pull/8885), [#8891](https://github.com/getpaseo/paseo/pull/8891), [#8909](https://github.com/getpaseo/paseo/pull/8909), [#9151](https://github.com/getpaseo/paseo/pull/9151), [#9238](https://github.com/getpaseo/paseo/pull/9238), [#8739](https://github.com/getpaseo/paseo/pull/8739) by [@zeyugao](https://github.com/zeyugao))
+- **Plugin sidebar views:** A plugin can replace the sidebar's content with its own layout of workspaces, agents, projects and terminals across every connected host. Pick the view per device under Settings → Sidebar; Paseo's sidebar header and footer stay in place. ([#8906](https://github.com/getpaseo/paseo/pull/8906))
+- **Plugin composer controls:** Plugins can add their own controls to the composer, and read and set its prompt, attachments, provider, model, mode and thinking. They can also put the cursor in any agent's composer, add items to New workspace, and store their own metadata on agents and workspaces. ([#8744](https://github.com/getpaseo/paseo/pull/8744), [#9209](https://github.com/getpaseo/paseo/pull/9209), [#9207](https://github.com/getpaseo/paseo/pull/9207))
+- **Polish:** The chat stays still when a turn ends, and returning to a chat that has not changed shows it as it is with no refresh. Tool rows show their final title and icon from the first frame, the context window popover opens with usage already loaded, and sidebar hover cards open one at a time. ([#8944](https://github.com/getpaseo/paseo/pull/8944), [#9175](https://github.com/getpaseo/paseo/pull/9175), [#9242](https://github.com/getpaseo/paseo/pull/9242), [#9248](https://github.com/getpaseo/paseo/pull/9248), [#9212](https://github.com/getpaseo/paseo/pull/9212), [#9071](https://github.com/getpaseo/paseo/pull/9071))
+- **Rebuilt mobile chat timeline:** The chat timeline on iOS and Android was rebuilt. Expanding or collapsing a turn summary, todo card or tool-call group keeps the line you tapped in place, and on Android so do Show more, Show less and plan cards. ([#8717](https://github.com/getpaseo/paseo/pull/8717), [#9085](https://github.com/getpaseo/paseo/pull/9085))
+- **Undo workspace archive:** Archiving a workspace in the app now shows a "Workspace archived" toast for six seconds. Undo, or Cmd/Ctrl+Z, restores the workspace with its tabs and agents. On desktop, sidebar workspace rows also get an archive button on hover. ([#8904](https://github.com/getpaseo/paseo/pull/8904), [#9104](https://github.com/getpaseo/paseo/pull/9104))
 
-- Copy gitignored files selected by `.worktreeinclude` into new worktrees before setup and agents, using the built-in `worktree-include` plugin ([#8100](https://github.com/getpaseo/paseo/pull/8100))
-- Let plugins choose worktree paths and creation options through `worktree.create.before`, with listing, archive, deletion, and recovery at custom locations; includes a sibling-directory placement example ([#8117](https://github.com/getpaseo/paseo/pull/8117))
+### Added
 
-Improved:
+- Added a Change base picker in Changes for worktree workspaces, so diffs, the commit list and Git actions can use another branch ([#8642](https://github.com/getpaseo/paseo/pull/8642), [#8934](https://github.com/getpaseo/paseo/pull/8934) by [@Myasuka](https://github.com/Myasuka))
+- Added links for issue and pull request references such as `#123` and `owner/repo#123` in agent replies, plans, the pull request panel and file previews, for GitHub, GitLab, Gitea, Forgejo and Codeberg ([#8636](https://github.com/getpaseo/paseo/pull/8636))
+- Added iPhone Duo layout support: workspace actions sit in the system vertical bar, and the sidebar and workspace split on either side of the fold ([#8741](https://github.com/getpaseo/paseo/pull/8741), [#8901](https://github.com/getpaseo/paseo/pull/8901) by [@zeyugao](https://github.com/zeyugao))
+- Added fx as a provider you can add from the provider catalog in Settings → Hosts → Providers ([#9160](https://github.com/getpaseo/paseo/pull/9160))
+- Added background agents: an agent or plugin can create a helper with `background: true` that opens no tab, sends no notification and stays out of the sidebar and default agent lists ([#8683](https://github.com/getpaseo/paseo/pull/8683))
+- Added syntax highlighting for Terraform and HCL files (`.tf`, `.tfvars`, `.hcl`) ([#9106](https://github.com/getpaseo/paseo/pull/9106))
+- Added `PASEO_WORKSPACE_ID` to each agent's environment so an agent can identify, rename or archive its own workspace ([#8939](https://github.com/getpaseo/paseo/pull/8939) by [@DTTerastar](https://github.com/DTTerastar))
 
-- Added `server.addHook` with `subject.operation.position` names and the awaited `worktree.create.after` hook before setup and agents; deprecated the previous plugin hook registration methods without changing their behavior ([#8081](https://github.com/getpaseo/paseo/pull/8081))
+### Changed
+
+- Changed opening a workspace to restore the tab you left instead of jumping to the agent that needs attention ([#8935](https://github.com/getpaseo/paseo/pull/8935))
+- Changed question cards so picking an option no longer advances automatically; continue with Next or Submit ([#8525](https://github.com/getpaseo/paseo/pull/8525))
+- Changed the slash command menu to show loading and error states with Retry, and to stop selecting `/exit` by default ([#8905](https://github.com/getpaseo/paseo/pull/8905))
+- Changed the workspace header and tabs to switch to compact controls when Explorer or a split pane narrows the workspace ([#8740](https://github.com/getpaseo/paseo/pull/8740), [#9088](https://github.com/getpaseo/paseo/pull/9088) by [@zeyugao](https://github.com/zeyugao))
+- Changed sending a message to a Pi agent whose process has exited to fail immediately with an instruction to reload the agent ([#8718](https://github.com/getpaseo/paseo/pull/8718))
+
+### Fixed
+
+- Fixed the working indicator disappearing when returning to a chat whose agent finished while you were away ([#9170](https://github.com/getpaseo/paseo/pull/9170))
+- Fixed chats with short collapsed turns opening with empty space until you scrolled ([#8358](https://github.com/getpaseo/paseo/pull/8358), [#9083](https://github.com/getpaseo/paseo/pull/9083))
+- Fixed Collapse turns hiding an earlier reply inside a later turn's summary line after an idle Claude, Codex or OpenCode agent was resumed ([#9098](https://github.com/getpaseo/paseo/pull/9098))
+- Fixed the missing space between a prompt and the reply or collapsed-turn summary line below it ([#9009](https://github.com/getpaseo/paseo/pull/9009))
+- Fixed Markdown tables showing as literal pipes when written directly below a paragraph with no blank line ([#8485](https://github.com/getpaseo/paseo/pull/8485) by [@ragokan](https://github.com/ragokan), [@suk-6](https://github.com/suk-6), [@thsrite](https://github.com/thsrite))
+- Fixed linked badge images that share a line with text rendering as full-width blocks on web and desktop ([#8530](https://github.com/getpaseo/paseo/pull/8530))
+- Fixed View diagram opening fullscreen instead of returning to the inline Mermaid diagram after View source ([#8932](https://github.com/getpaseo/paseo/pull/8932) by [@luoph](https://github.com/luoph))
+- Fixed mouse-wheel scrolling running in the opposite direction in chats on Android ([#8693](https://github.com/getpaseo/paseo/pull/8693) by [@sjeon87](https://github.com/sjeon87))
+- Fixed unsent composer text and attachments being deleted when an agent tab was closed ([#9079](https://github.com/getpaseo/paseo/pull/9079))
+- Fixed pasting text with hyperlinks into the composer dropping the link URLs; links now paste as Markdown ([#8972](https://github.com/getpaseo/paseo/pull/8972))
+- Fixed the composer losing focus after clicking Send with a mouse ([#9015](https://github.com/getpaseo/paseo/pull/9015))
+- Fixed the composer resting 50pt above the bottom edge on iPhone ([#8823](https://github.com/getpaseo/paseo/pull/8823) by [@zeyugao](https://github.com/zeyugao))
+- Fixed Add host sending you to Settings from the sidebar and New workspace ([#8512](https://github.com/getpaseo/paseo/pull/8512))
+- Fixed a failed agent's red dot and Failed grouping staying in the sidebar after opening the agent or choosing Mark as read ([#8831](https://github.com/getpaseo/paseo/pull/8831))
+- Fixed a workspace's unread indicator staying on after it was cleared while the agent's runtime was closed ([#9087](https://github.com/getpaseo/paseo/pull/9087))
+- Fixed the context window popover closing by itself whenever the chat scrolled during a streaming reply ([#8742](https://github.com/getpaseo/paseo/pull/8742) by [@3ae3ae](https://github.com/3ae3ae))
+- Fixed the sidebar usage summary updating only when Usage was opened ([#7806](https://github.com/getpaseo/paseo/pull/7806) by [@ragokan](https://github.com/ragokan))
+- Fixed tooltips and menus above their trigger briefly covering it on Android when their content grew after opening ([#9247](https://github.com/getpaseo/paseo/pull/9247))
+- Fixed History showing "Could not load history" after reloading the web app on the History screen ([#9029](https://github.com/getpaseo/paseo/pull/9029))
+- Fixed section links in an HTML file preview replacing the preview with the Paseo app instead of scrolling within the file ([#8559](https://github.com/getpaseo/paseo/pull/8559) by [@3ae3ae](https://github.com/3ae3ae))
+- Fixed Files Refresh leaving a newly created file hidden when its folder was collapsed during the refresh ([#8582](https://github.com/getpaseo/paseo/pull/8582) by [@hadan8977](https://github.com/hadan8977))
+- Fixed the branch switcher showing "No branches found" while branches are still loading or after the request fails ([#8938](https://github.com/getpaseo/paseo/pull/8938))
+- Fixed commit history showing a doubled slash, no rename status and no diff for a file moved up a directory ([#8509](https://github.com/getpaseo/paseo/pull/8509) by [@hadan8977](https://github.com/hadan8977))
+- Fixed a merged pull request disappearing from its workspace when the checkout was behind the pull request's head
+- Fixed workspace Git watchers staying in fallback polling after a watcher setup timeout
+- Fixed abandoned connections staying open for up to 45 seconds after the web or desktop app reconnected ([#9067](https://github.com/getpaseo/paseo/pull/9067))
+- Fixed a connection routed through another host closing with "The receiving client cannot keep up with host output" while fetching a very large timeline ([#9109](https://github.com/getpaseo/paseo/pull/9109))
+- Fixed a connected host staying in error after it was updated to a supported version ([#8423](https://github.com/getpaseo/paseo/pull/8423) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed handshake retries and a once-per-second `relay_e2ee_channel_error` warning continuing after a connection attempt to an unreachable host had timed out ([#9025](https://github.com/getpaseo/paseo/pull/9025), [#9038](https://github.com/getpaseo/paseo/pull/9038))
+- Fixed app diagnostics reporting `Last online: never` for a host that had connected and then disconnected ([#9054](https://github.com/getpaseo/paseo/pull/9054), [#9058](https://github.com/getpaseo/paseo/pull/9058))
+- Fixed shell commands started by a Codex turn continuing to run after the turn is stopped or interrupted ([#7525](https://github.com/getpaseo/paseo/pull/7525) by [@thomasvan](https://github.com/thomasvan))
+- Fixed Claude turns that stop on an API error, such as a session limit or an invalid API key, being reported as completed instead of failed ([#8480](https://github.com/getpaseo/paseo/pull/8480) by [@RRD-dev](https://github.com/RRD-dev), [@luoph](https://github.com/luoph))
+- Fixed Claude processes staying in memory until the daemon restarted when an idle chat was reopened without sending a prompt ([#9019](https://github.com/getpaseo/paseo/pull/9019) by [@Brandon168](https://github.com/Brandon168))
+- Fixed Claude agents not resuming after a graceful daemon stop or restart when agent recovery is turned on ([#8686](https://github.com/getpaseo/paseo/pull/8686) by [@babo-jeonguk](https://github.com/babo-jeonguk))
+- Fixed the effort control missing in the composer for Claude models that come from Claude's `settings.json` ([#8699](https://github.com/getpaseo/paseo/pull/8699) by [@ragokan](https://github.com/ragokan), [@yahao123](https://github.com/yahao123))
+- Fixed importing a Claude session failing with `Invalid string length` when its transcript is very large ([#8457](https://github.com/getpaseo/paseo/pull/8457) by [@qwist1233-cpu](https://github.com/qwist1233-cpu))
+- Fixed Claude turns that end at the maximum-turn limit losing their final token counts and cost ([#8519](https://github.com/getpaseo/paseo/pull/8519))
+- Fixed Codex "Apply file changes" approvals showing no file name or diff before you accept ([#8585](https://github.com/getpaseo/paseo/pull/8585) by [@ragokan](https://github.com/ragokan))
+- Fixed the timeline showing only the first file's diff when Codex edits several files in one patch ([#8613](https://github.com/getpaseo/paseo/pull/8613) by [@ragokan](https://github.com/ragokan))
+- Fixed Codex session discovery and startup intermittently failing with a SQLite initialization error when several Codex operations start at once ([#9008](https://github.com/getpaseo/paseo/pull/9008) by [@colonelpanic8](https://github.com/colonelpanic8), [@michaelmwu](https://github.com/michaelmwu))
+- Fixed OpenCode conversations that were mid-turn during a daemon restart showing idle and ignoring Stop ([#8698](https://github.com/getpaseo/paseo/pull/8698))
+- Fixed OpenCode being told you declined a tool call when you sent a message while its approval was pending ([#8477](https://github.com/getpaseo/paseo/pull/8477))
+- Fixed reopened Pi conversations missing the messages from before a context compaction ([#8523](https://github.com/getpaseo/paseo/pull/8523))
+- Fixed archived Pi chats failing to open with `spawn pi ENOENT` after their working folder was removed ([#8442](https://github.com/getpaseo/paseo/pull/8442) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed reading an archived Pi chat leaving a Pi process running when idle runtime cleanup is disabled ([#8554](https://github.com/getpaseo/paseo/pull/8554) by [@rylwin](https://github.com/rylwin))
+- Fixed a prompt sent to an ACP agent whose process has exited staying in running forever instead of failing with an error ([#8406](https://github.com/getpaseo/paseo/pull/8406) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed an ACP agent staying stuck on "waiting for permission" after it abandoned an approval request and ended its turn ([#8548](https://github.com/getpaseo/paseo/pull/8548) by [@3ae3ae](https://github.com/3ae3ae))
+- Fixed changing the mode of an ACP agent failing with `invalid_params` after the agent sends a config update ([#8912](https://github.com/getpaseo/paseo/pull/8912) by [@a-sh](https://github.com/a-sh))
+- Fixed Paseo showing and saving an unavailable model after selecting it on a running ACP agent ([#8957](https://github.com/getpaseo/paseo/pull/8957))
+- Fixed importing a session switching it from its own model to the provider's default model ([#8948](https://github.com/getpaseo/paseo/pull/8948))
+- Fixed a message from another agent cancelling the recipient's pending question or approval before you could answer it ([#8453](https://github.com/getpaseo/paseo/pull/8453) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed an agent never being notified of completion after sending a prompt to a closed or archived agent on a connected host ([#8575](https://github.com/getpaseo/paseo/pull/8575))
+- Fixed creating a child agent failing with "Caller agent not found" after a daemon restart until the parent chat had been opened ([#8714](https://github.com/getpaseo/paseo/pull/8714))
+- Fixed an agent still showing as failed after it resumed from a provider error and completed its next turn ([#8083](https://github.com/getpaseo/paseo/pull/8083) by [@luoph](https://github.com/luoph))
+- Fixed a detached subagent still showing under its archived parent until refresh ([#8903](https://github.com/getpaseo/paseo/pull/8903) by [@luoph](https://github.com/luoph))
+- Fixed opening an agent failing with "Working directory does not exist" instead of showing its saved conversation ([#8737](https://github.com/getpaseo/paseo/pull/8737))
+- Fixed the daemon re-reading all archived agent and workspace history on every workspace update ([#8735](https://github.com/getpaseo/paseo/pull/8735))
+- Fixed the daemon repeatedly running Git commands in a workspace folder that was deleted while its file watcher was in fallback polling ([#8462](https://github.com/getpaseo/paseo/pull/8462) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed workspace service connections staying open after the browser tab closes or reloads ([#8421](https://github.com/getpaseo/paseo/pull/8421) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed the daemon web UI answering missing `/.well-known/*` requests with the app page instead of a 404 ([#8622](https://github.com/getpaseo/paseo/pull/8622) by [@HomicideZero](https://github.com/HomicideZero))
+- Fixed schedules accepting cron steps after a single number, such as `0/15 * * * *`, and running them hourly; they are now rejected ([#8607](https://github.com/getpaseo/paseo/pull/8607) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed cron schedules that set both day-of-month and day-of-week running only when both matched instead of when either matches ([#8611](https://github.com/getpaseo/paseo/pull/8611) by [@Mar-garet](https://github.com/Mar-garet))
+- Fixed `paseo logs --json` printing the plain-text transcript instead of JSON ([#8589](https://github.com/getpaseo/paseo/pull/8589) by [@hadan8977](https://github.com/hadan8977))
+- Fixed the `create_agent` tool not telling agents that creating an agent on another provider needs a mode ([#8483](https://github.com/getpaseo/paseo/pull/8483) by [@guerinnoah](https://github.com/guerinnoah))
+- Fixed terminals failing to open on Windows machines where Windows PowerShell cannot run `Get-CimInstance` ([#8818](https://github.com/getpaseo/paseo/pull/8818))
+- Fixed the terminal typing its version reply into the shell when a program queries the terminal version ([#8419](https://github.com/getpaseo/paseo/pull/8419) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed a finger drag in the web terminal scrolling history about twice as far as the drag ([#8776](https://github.com/getpaseo/paseo/pull/8776) by [@sinomoe](https://github.com/sinomoe))
+- Fixed mouse scrolling in terminal programs such as Copilot CLI stopping after switching away from the terminal and back ([#9004](https://github.com/getpaseo/paseo/pull/9004) by [@imink](https://github.com/imink))
+- Fixed dropping several files onto a remote terminal pasting their paths with no space between them ([#8946](https://github.com/getpaseo/paseo/pull/8946) by [@sebastianarena](https://github.com/sebastianarena))
+- Fixed the `browser_fill` tool reporting success without updating React-controlled inputs and textareas ([#9022](https://github.com/getpaseo/paseo/pull/9022))
+- Fixed `browser_evaluate` failing on pages whose Content Security Policy omits `unsafe-eval` ([#8973](https://github.com/getpaseo/paseo/pull/8973) by [@amustapha](https://github.com/amustapha))
+- Fixed `browser_logs` omitting the HTTP status of each network request ([#8956](https://github.com/getpaseo/paseo/pull/8956) by [@amustapha](https://github.com/amustapha))
+
+### Plugins
+
+- Added plugin subscriptions, which stream live events from the daemon to a plugin's panels, and binary (`Uint8Array`) payloads for plugin RPCs and events ([#8527](https://github.com/getpaseo/paseo/pull/8527))
+- Changed Settings → Plugins to open a plugin's settings from a cog button, with a tab per settings screen ([#8675](https://github.com/getpaseo/paseo/pull/8675))
+- Added an upward chevron to plugin composer pills that open a menu or popover ([#8673](https://github.com/getpaseo/paseo/pull/8673))
+- Changed daemon startup to launch configured plugins concurrently instead of one after another ([#8427](https://github.com/getpaseo/paseo/pull/8427) by [@DAnaeto](https://github.com/DAnaeto))
+- Fixed registry plugin installs failing with "npm artifact changed since review" when the host's npm uses a registry mirror ([#8756](https://github.com/getpaseo/paseo/pull/8756) by [@tlipoca9](https://github.com/tlipoca9))
+- Fixed the published `@getpaseo/*` npm packages declaring no license; they now declare Apache-2.0 ([#7816](https://github.com/getpaseo/paseo/pull/7816) by [@mdlawson](https://github.com/mdlawson), [@ragokan](https://github.com/ragokan))
+- Fixed forking from an earlier reply failing with "This checkpoint changed after it was created" after a plugin updated one of its timeline cards ([#8746](https://github.com/getpaseo/paseo/pull/8746) by [@monarchmaisuriya](https://github.com/monarchmaisuriya))
+- Fixed Collapse turns leaving a turn open, or folding to an earlier reply, when a plugin renders the final reply ([#8811](https://github.com/getpaseo/paseo/pull/8811) by [@geoqiao](https://github.com/geoqiao))
+- Fixed plugin screens showing "This plugin surface is unavailable" while the plugin catalog is still loading after an app reload ([#8123](https://github.com/getpaseo/paseo/pull/8123) by [@vs-tahir](https://github.com/vs-tahir))
+- Fixed the Workspaces list being pushed out of the mobile sidebar on short screens when plugins add many navigation items ([#8727](https://github.com/getpaseo/paseo/pull/8727) by [@jaredwang](https://github.com/jaredwang))
+- Fixed timeline plugins not receiving the sender, event and original text on agent-message tool calls ([#8492](https://github.com/getpaseo/paseo/pull/8492) by [@RRD-dev](https://github.com/RRD-dev), [@luoph](https://github.com/luoph))
+- Fixed plugin RPCs failing when their input or output schema uses a transform ([#8550](https://github.com/getpaseo/paseo/pull/8550))
+
+### Notes
+
+- Background tasks, the Change base picker, archive undo, background agents, plugin subscriptions and fx need both the host and the app on this version
+
+## 0.15.4 - 2026-11-10
+
+### Added
+
+- Added Claude Fable 5.2 and Mythos 5.2 with medium default effort ([#9233](https://github.com/getpaseo/paseo/pull/9233) by [@gengjiawen](https://github.com/gengjiawen), [@gudcks](https://github.com/gudcks))
+
+### Notes
+
+- Both models require Claude Code 2.1.321 or newer; Mythos 5.2 appears only when Claude Code advertises access
+
+## 0.15.3 - 2026-11-06
+
+### Fixed
+
+- Fixed conversation text becoming blurred when opening or dismissing the keyboard on iOS 26+ ([#8918](https://github.com/getpaseo/paseo/pull/8918) by [@dgreensp](https://github.com/dgreensp))
+
+## 0.15.2 - 2026-11-05
+
+### Added
+
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+### Improved
+
+- Changed the theme picker to a grid of tiles with a preview of each theme ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Replaced the "Loading…" text in Providers settings with skeleton rows ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed controls to two sizes: default controls are 32px tall on desktop and 44px on phones, and compact controls are 28px ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed first launch to go from the loading screen straight into setup instead of showing the empty home first ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- Changed dialogs on desktop and web to fade in over about 160ms ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- Changed modal and sheet backgrounds to match the screen background ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed documentation links in Settings sections to a `Label ↗` link beside the section title ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+## 0.15.1 - 2026-11-05
+
+### Fixed
+
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run `Get-CimInstance` ([#8810](https://github.com/getpaseo/paseo/pull/8810))
+
+## 0.15.0 - 2026-11-03
+
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+### Added
+
+- Insert known agent commands from replies into the Composer draft ([#8371](https://github.com/getpaseo/paseo/pull/8371))
+- Reuse running OpenCode v2 services ([#7435](https://github.com/getpaseo/paseo/pull/7435) by [@mcowger](https://github.com/mcowger))
+- Kept terminal programs running across daemon restarts, crashes and supported updates ([#7644](https://github.com/getpaseo/paseo/pull/7644), [#8155](https://github.com/getpaseo/paseo/pull/8155) by [@sebastianarena](https://github.com/sebastianarena))
+- Added an opt-in setting to resume interrupted agents in their existing conversations after a host restart ([#8127](https://github.com/getpaseo/paseo/pull/8127), [#8619](https://github.com/getpaseo/paseo/pull/8619) by [@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
+- Added draggable terminal text-selection handles on iOS and Android ([#8348](https://github.com/getpaseo/paseo/pull/8348))
+- Let phones and tablets rotate with the system orientation setting ([#8256](https://github.com/getpaseo/paseo/pull/8256) by [@magiclaw](https://github.com/magiclaw), [@yzim](https://github.com/yzim))
+- Copy ignored files selected by `.worktreeinclude` into new worktrees before setup and agents start ([#8100](https://github.com/getpaseo/paseo/pull/8100) by [@cprecioso](https://github.com/cprecioso))
+- Added daemon-wide support for `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` ([#8177](https://github.com/getpaseo/paseo/pull/8177))
+- Fetch usage only while displayed, with a host setting to disable usage checks entirely ([#8181](https://github.com/getpaseo/paseo/pull/8181))
+
+### Improved
+
+- Replaced mobile terminal text rendering to align CJK characters, emoji, styled text and the cursor with terminal columns ([#8336](https://github.com/getpaseo/paseo/pull/8336), [#8375](https://github.com/getpaseo/paseo/pull/8375))
+- Restore the configured terminal scrollback on reconnect, up to 10,000 retained lines ([#8282](https://github.com/getpaseo/paseo/pull/8282) by [@DrakenKor](https://github.com/DrakenKor), [@lennartschoch](https://github.com/lennartschoch))
+- Load paginated Codex histories when importing or reopening sessions ([#8171](https://github.com/getpaseo/paseo/pull/8171) by [@dundunHa](https://github.com/dundunHa), [@hr95savage](https://github.com/hr95savage))
+- Stopped rereading and retaining an unused copy of Codex history when reopening a cached chat ([#8132](https://github.com/getpaseo/paseo/pull/8132))
+- Split large daemon responses across relay frames instead of disconnecting at the frame limit ([#8302](https://github.com/getpaseo/paseo/pull/8302))
+- Truncate oversized chat entries before sending them to the app, including large tool results and embedded data ([#8274](https://github.com/getpaseo/paseo/pull/8274))
+- Show subagent activity in its own panel instead of duplicating it inside the parent’s tool card ([#8276](https://github.com/getpaseo/paseo/pull/8276))
+- Show exact usage reset times alongside more precise countdowns ([#8162](https://github.com/getpaseo/paseo/pull/8162))
+
+### Plugins
+
+- Fixed discarded messages returning after rewinding plugin conversations ([#8368](https://github.com/getpaseo/paseo/pull/8368) by [@mcowger](https://github.com/mcowger), [@omercnet](https://github.com/omercnet))
+- Reduced plugin downloads with smaller client bundles and a cache reused across reconnects and app launches ([#8040](https://github.com/getpaseo/paseo/pull/8040), [#8076](https://github.com/getpaseo/paseo/pull/8076) by [@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- Preserved plugin screens and local state during temporary host disconnections ([#8105](https://github.com/getpaseo/paseo/pull/8105) by [@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- Let plugins choose worktree locations and creation options through `worktree.create.before` ([#8117](https://github.com/getpaseo/paseo/pull/8117) by [@mcowger](https://github.com/mcowger))
+- Added `server.addHook` with an awaited `worktree.create.after` hook before workspace setup and agents start ([#8081](https://github.com/getpaseo/paseo/pull/8081))
+- Released redundant plugin streaming snapshots instead of retaining them for the session’s lifetime ([#7675](https://github.com/getpaseo/paseo/pull/7675) by [@suntianc](https://github.com/suntianc))
+
+### Fixed
+
+- Fixed rewinding Claude conversations to messages sent during an active turn ([#8372](https://github.com/getpaseo/paseo/pull/8372) by [@tieo](https://github.com/tieo))
+- Fixed duplicate rows and missing replies when resuming Claude subagents after reopening a session ([#8408](https://github.com/getpaseo/paseo/pull/8408) by [@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- Fixed Codex agents created without a prompt failing after their runtime reopens ([#8393](https://github.com/getpaseo/paseo/pull/8393) by [@babo-jeonguk](https://github.com/babo-jeonguk))
+- Fixed newly running agents appearing as finished immediately after creation ([#8396](https://github.com/getpaseo/paseo/pull/8396) by [@luoph](https://github.com/luoph))
+- Fixed ACP startup exits waiting for a timeout instead of reporting the process error ([#8384](https://github.com/getpaseo/paseo/pull/8384) by [@Peanut-HZM](https://github.com/Peanut-HZM))
+- Fixed skills missing from new ACP agents when commands arrive in multiple batches ([#8387](https://github.com/getpaseo/paseo/pull/8387) by [@Peanut-HZM](https://github.com/Peanut-HZM))
+- Fixed sidebar titles and statuses stopping updates after directory subscriptions are released ([#8403](https://github.com/getpaseo/paseo/pull/8403) by [@ragokan](https://github.com/ragokan))
+- Kept the open workspace visible in collapsed sidebar groups ([#8395](https://github.com/getpaseo/paseo/pull/8395) by [@0xroylee](https://github.com/0xroylee))
+- Fixed relative chat links opening missing files instead of files in nested repositories ([#8361](https://github.com/getpaseo/paseo/pull/8361) by [@apple-ouyang](https://github.com/apple-ouyang))
+- Accepted host:port and pasted URLs in the Direct connection Host field ([#8223](https://github.com/getpaseo/paseo/pull/8223) by [@DaydreamCoding](https://github.com/DaydreamCoding))
+- Fixed terminal Ctrl+V paste over plain HTTP on non-Mac keyboards ([#8230](https://github.com/getpaseo/paseo/pull/8230) by [@DaydreamCoding](https://github.com/DaydreamCoding))
+- Stopped failed history loads from repeatedly reopening the provider, with Retry available in the chat ([#8278](https://github.com/getpaseo/paseo/pull/8278))
+- Fixed Claude settings files being discarded when Paseo adds its own launch settings ([#8148](https://github.com/getpaseo/paseo/pull/8148) by [@yayugu](https://github.com/yayugu))
+- Fixed steering messages replacing a turn that was still starting and losing its original prompt ([#6192](https://github.com/getpaseo/paseo/pull/6192))
+- Fixed Pi tool-result images missing during streaming and after reopening the chat ([#8280](https://github.com/getpaseo/paseo/pull/8280) by [@duyiliu](https://github.com/duyiliu))
+- Fixed completed `edxeth/pi-subagents` children remaining marked as working ([#8176](https://github.com/getpaseo/paseo/pull/8176) by [@Zeno2019](https://github.com/Zeno2019))
+- Fixed Claude background subagent status after reopening a conversation ([#6259](https://github.com/getpaseo/paseo/pull/6259))
+- Fixed reused plugin subagents showing their previous completed status during new work ([#8080](https://github.com/getpaseo/paseo/pull/8080) by [@bccy](https://github.com/bccy))
+- Fixed custom Codex providers with reserved names such as `ollama` ([#6954](https://github.com/getpaseo/paseo/pull/6954) by [@mr860819](https://github.com/mr860819))
+- Fixed the MiniMax Code catalog command failing to select an executable ([#8201](https://github.com/getpaseo/paseo/pull/8201) by [@Peanut-HZM](https://github.com/Peanut-HZM))
+- Fixed Android keeping the wrong layout after folding or unfolding while backgrounded ([#8285](https://github.com/getpaseo/paseo/pull/8285))
+- Fixed Android workspace layouts and header fades retaining their old size after rotation ([#8349](https://github.com/getpaseo/paseo/pull/8349), [#8377](https://github.com/getpaseo/paseo/pull/8377))
+- Fixed chat reconnecting and updating status being hidden behind the header on iOS and Android phones ([#8568](https://github.com/getpaseo/paseo/pull/8568))
+- Fixed deleted agents leaving unclosable tabs in another window ([#8248](https://github.com/getpaseo/paseo/pull/8248) by [@loganmeyer](https://github.com/loganmeyer))
+- Fixed transcript text retaining old theme colors after the theme changes while the window is hidden ([#8199](https://github.com/getpaseo/paseo/pull/8199) by [@Nurshot](https://github.com/Nurshot), [@dansabin](https://github.com/dansabin))
+- Fixed web menus snapping back to their loading size after content arrives ([#8180](https://github.com/getpaseo/paseo/pull/8180) by [@babo-jeonguk](https://github.com/babo-jeonguk))
+- Fixed split dividers drifting ahead of or behind the pointer while dragging ([#6011](https://github.com/getpaseo/paseo/pull/6011))
+- Fixed delayed native filesystem watcher startup leaving Git updates unobserved ([#8107](https://github.com/getpaseo/paseo/pull/8107))
+- Fixed bundled skill arguments being passed incorrectly to Codex and Pi ([#8252](https://github.com/getpaseo/paseo/pull/8252) by [@AspireOne](https://github.com/AspireOne))
+
+### Notes
+
+- The first upgrade from 0.14.0 still closes terminals; terminal preservation starts once the new daemon is installed, and Windows desktop app upgrades still close them
+- Agent recovery is off by default; turn on **Resume agents after restart** in Host settings → Agents to send `Resume working.` or your own prompt
+- Before downgrading to 0.14.0, restore a backed-up `config.json` or remove the saved agent-resume and usage-check settings
 
 ## 0.14.0 - 2026-10-29
 
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index f87cb58805..6d69751d4e 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -1,15 +1,246 @@
-# 更新日志
+# Changelog
 
-尚未发布。以下变更已合入 `main`，但不包含在 0.14.0 中；下一个版本的条目会包含它们。
+## 0.16.0-beta.1 - 2026-11-10
 
-新增：
+- **后台任务**：Paseo 现在会在 Composer 上方显示 Agent 正在运行的后台任务，例如 shell 和监视器，每项都带“停止”按钮。支持 Claude Code、Codex 和 OpenCode v2。 ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162)，贡献者：[@fxlelouarn](https://github.com/fxlelouarn))
+- **更快的 diff 加载**：打开“更改”时会立即显示文件树，文件内容随后加载。大型 diff 分批到达，加载期间应用的其他部分照常响应，并且 diff 优先于 daemon 的后台 worktree 扫描。 ([#8907](https://github.com/getpaseo/paseo/pull/8907), [#9241](https://github.com/getpaseo/paseo/pull/9241), [#9243](https://github.com/getpaseo/paseo/pull/9243))
+- **返回时更少重连**：返回应用时会保留仍可用的连接，包括正在传输大型响应的连接，只在必要时重连一次。主机保存了多个连接时，Paseo 会留在可用的那个连接上。 ([#8651](https://github.com/getpaseo/paseo/pull/8651), [#9086](https://github.com/getpaseo/paseo/pull/9086), [#8855](https://github.com/getpaseo/paseo/pull/8855), [#9116](https://github.com/getpaseo/paseo/pull/9116))
+- **移动端键盘快捷键**：连接键盘后，iPad 和 Android 现在可使用与桌面端相同的快捷键，包括你自定义的绑定。检测到键盘时会显示快捷键提示和“设置 → 快捷键”。在较窄的桌面端和浏览器窗口中快捷键同样可用。 ([#8625](https://github.com/getpaseo/paseo/pull/8625)，贡献者：[@jeroenfrenken](https://github.com/jeroenfrenken)、[@lstroud](https://github.com/lstroud))
+- **适合触控的平板控件**：在 iPad 和其他触屏设备上，宽屏布局现在使用适合触控尺寸的按钮、行和栏。Composer 工具栏在空间不足时会把控件收进模型菜单；在工作区上向右滑动，可将已折叠的侧边栏以浮层方式显示。 ([#8748](https://github.com/getpaseo/paseo/pull/8748), [#8885](https://github.com/getpaseo/paseo/pull/8885), [#8891](https://github.com/getpaseo/paseo/pull/8891), [#8909](https://github.com/getpaseo/paseo/pull/8909), [#9151](https://github.com/getpaseo/paseo/pull/9151), [#9238](https://github.com/getpaseo/paseo/pull/9238), [#8739](https://github.com/getpaseo/paseo/pull/8739)，贡献者：[@zeyugao](https://github.com/zeyugao))
+- **插件侧边栏视图**：插件可以用自己的布局替换侧边栏内容，展示所有已连接主机上的工作区、Agent、项目和终端。在“设置 → 侧边栏”中为每台设备选择视图；Paseo 的侧边栏页眉和页脚保持不变。 ([#8906](https://github.com/getpaseo/paseo/pull/8906))
+- **插件 Composer 控件**：插件可以向 Composer 添加自己的控件，并读取和设置其中的提示词、附件、Provider、模型、模式和思考强度。插件还可以把光标放到任意 Agent 的 Composer 中、向“新建工作区”添加条目，并在 Agent 和工作区上保存自己的元数据。 ([#8744](https://github.com/getpaseo/paseo/pull/8744), [#9209](https://github.com/getpaseo/paseo/pull/9209), [#9207](https://github.com/getpaseo/paseo/pull/9207))
+- **细节打磨**：一轮对话结束时聊天保持不动，返回没有变化的聊天时直接显示原样，无需刷新。工具行从第一帧起就显示最终标题和图标，上下文窗口浮层打开时用量已加载完成，侧边栏悬停卡片一次只打开一个。 ([#8944](https://github.com/getpaseo/paseo/pull/8944), [#9175](https://github.com/getpaseo/paseo/pull/9175), [#9242](https://github.com/getpaseo/paseo/pull/9242), [#9248](https://github.com/getpaseo/paseo/pull/9248), [#9212](https://github.com/getpaseo/paseo/pull/9212), [#9071](https://github.com/getpaseo/paseo/pull/9071))
+- **重建移动端聊天时间线**：iOS 和 Android 上的聊天时间线已重建。展开或折叠轮次摘要、待办卡片或工具调用组时，你点按的那一行保持原位；在 Android 上，“显示更多”“收起”和计划卡片也是如此。 ([#8717](https://github.com/getpaseo/paseo/pull/8717), [#9085](https://github.com/getpaseo/paseo/pull/9085))
+- **撤销工作区归档**：在应用中归档工作区时，现在会显示“Workspace 已归档”提示，持续六秒。点击“撤销”或按 Cmd/Ctrl+Z 可恢复该工作区及其标签页和 Agent。在桌面端，侧边栏的工作区行在悬停时还会显示归档按钮。 ([#8904](https://github.com/getpaseo/paseo/pull/8904), [#9104](https://github.com/getpaseo/paseo/pull/9104))
 
-- 在 setup 和 Agent 启动前，使用内置的 `worktree-include` 插件将 `.worktreeinclude` 选中的被 gitignore 忽略的文件复制到新工作树 ([#8100](https://github.com/getpaseo/paseo/pull/8100))
-- 插件可通过 `worktree.create.before` 选择工作树路径和创建选项，自定义位置的工作树支持列出、归档、删除和恢复；附带同级目录放置示例 ([#8117](https://github.com/getpaseo/paseo/pull/8117))
+### 新增
 
-改进：
+- 在“更改”中为 worktree 工作区新增基准分支选择器（Change base），diff、提交列表和 Git 操作可改用其他分支 ([#8642](https://github.com/getpaseo/paseo/pull/8642), [#8934](https://github.com/getpaseo/paseo/pull/8934)，贡献者：[@Myasuka](https://github.com/Myasuka))
+- 新增 Issue 和 PR 引用链接：Agent 回复、计划、PR 面板和文件预览中的 `#123`、`owner/repo#123` 等引用会链接到 GitHub、GitLab、Gitea、Forgejo 或 Codeberg ([#8636](https://github.com/getpaseo/paseo/pull/8636))
+- 新增 iPhone Duo 布局支持：工作区操作位于系统竖向栏中，侧边栏和工作区分列折痕两侧 ([#8741](https://github.com/getpaseo/paseo/pull/8741), [#8901](https://github.com/getpaseo/paseo/pull/8901)，贡献者：[@zeyugao](https://github.com/zeyugao))
+- 新增 fx Provider，可在“设置 → Hosts → 提供方”的 Provider 目录中添加 ([#9160](https://github.com/getpaseo/paseo/pull/9160))
+- 新增后台 Agent：Agent 或插件可通过 `background: true` 创建辅助 Agent，它不打开标签页、不发送通知，也不出现在侧边栏和默认 Agent 列表中 ([#8683](https://github.com/getpaseo/paseo/pull/8683))
+- 新增 Terraform 和 HCL 文件（`.tf`、`.tfvars`、`.hcl`）的语法高亮 ([#9106](https://github.com/getpaseo/paseo/pull/9106))
+- 在每个 Agent 的环境中新增 `PASEO_WORKSPACE_ID`，Agent 可据此识别、重命名或归档自己的工作区 ([#8939](https://github.com/getpaseo/paseo/pull/8939)，贡献者：[@DTTerastar](https://github.com/DTTerastar))
 
-- 新增采用 `subject.operation.position` 命名的 `server.addHook` 和在 setup 及 Agent 之前等待的 `worktree.create.after` 钩子，弃用原有的插件钩子注册方法并保留原有行为 ([#8081](https://github.com/getpaseo/paseo/pull/8081))
+### 变更
+
+- 打开工作区时恢复你离开时的标签页，不再跳转到需要关注的 Agent ([#8935](https://github.com/getpaseo/paseo/pull/8935))
+- 问题卡片中选择选项后不再自动前进；请用“下一步”或“提交”继续 ([#8525](https://github.com/getpaseo/paseo/pull/8525))
+- 斜杠命令菜单现在显示加载和错误状态并提供“重试”，且不再默认选中 `/exit` ([#8905](https://github.com/getpaseo/paseo/pull/8905))
+- 文件浏览器（Explorer）或分屏使工作区变窄时，工作区页眉和标签页改用紧凑控件 ([#8740](https://github.com/getpaseo/paseo/pull/8740), [#9088](https://github.com/getpaseo/paseo/pull/9088)，贡献者：[@zeyugao](https://github.com/zeyugao))
+- 向进程已退出的 Pi Agent 发送消息时立即失败，并提示重新加载该 Agent ([#8718](https://github.com/getpaseo/paseo/pull/8718))
+
+### 修复
+
+- 修复 Agent 在你离开期间完成后，返回聊天时工作指示器消失的问题 ([#9170](https://github.com/getpaseo/paseo/pull/9170))
+- 修复包含较短折叠轮次的聊天打开时留有空白、需滚动后才填满的问题 ([#8358](https://github.com/getpaseo/paseo/pull/8358), [#9083](https://github.com/getpaseo/paseo/pull/9083))
+- 修复空闲的 Claude、Codex 或 OpenCode Agent 恢复后，“折叠轮次”把较早的回复藏进后一轮摘要行的问题 ([#9098](https://github.com/getpaseo/paseo/pull/9098))
+- 修复提示词与其下方的回复或折叠轮次摘要行之间缺少间距的问题 ([#9009](https://github.com/getpaseo/paseo/pull/9009))
+- 修复紧跟在段落之后、中间没有空行的 Markdown 表格显示为原始竖线的问题 ([#8485](https://github.com/getpaseo/paseo/pull/8485)，贡献者：[@ragokan](https://github.com/ragokan)、[@suk-6](https://github.com/suk-6)、[@thsrite](https://github.com/thsrite))
+- 修复网页版和桌面端中与文字同行的带链接徽章图片被渲染成整行宽度的问题 ([#8530](https://github.com/getpaseo/paseo/pull/8530))
+- 修复“查看源码”后点击“查看图表”会打开全屏、而不是回到内联 Mermaid 图表的问题 ([#8932](https://github.com/getpaseo/paseo/pull/8932)，贡献者：[@luoph](https://github.com/luoph))
+- 修复 Android 上聊天中鼠标滚轮滚动方向相反的问题 ([#8693](https://github.com/getpaseo/paseo/pull/8693)，贡献者：[@sjeon87](https://github.com/sjeon87))
+- 修复关闭 Agent 标签页时未发送的 Composer 文本和附件被删除的问题 ([#9079](https://github.com/getpaseo/paseo/pull/9079))
+- 修复向 Composer 粘贴带超链接的文本时丢失链接地址的问题；链接现在以 Markdown 形式粘贴 ([#8972](https://github.com/getpaseo/paseo/pull/8972))
+- 修复用鼠标点击“发送”后 Composer 失去焦点的问题 ([#9015](https://github.com/getpaseo/paseo/pull/9015))
+- 修复 iPhone 上 Composer 停在距底部边缘 50pt 处的问题 ([#8823](https://github.com/getpaseo/paseo/pull/8823)，贡献者：[@zeyugao](https://github.com/zeyugao))
+- 修复从侧边栏和“新建工作区”点击“添加主机”会跳转到“设置”的问题 ([#8512](https://github.com/getpaseo/paseo/pull/8512))
+- 修复打开失败的 Agent 或选择 Mark as read 后，其红点和“失败”分组仍留在侧边栏的问题 ([#8831](https://github.com/getpaseo/paseo/pull/8831))
+- 修复在 Agent 运行时已关闭的情况下清除未读后，工作区的未读指示仍然亮着的问题 ([#9087](https://github.com/getpaseo/paseo/pull/9087))
+- 修复流式回复期间聊天一滚动上下文窗口浮层就自行关闭的问题 ([#8742](https://github.com/getpaseo/paseo/pull/8742)，贡献者：[@3ae3ae](https://github.com/3ae3ae))
+- 修复侧边栏用量摘要只在打开“使用情况”时才更新的问题 ([#7806](https://github.com/getpaseo/paseo/pull/7806)，贡献者：[@ragokan](https://github.com/ragokan))
+- 修复 Android 上位于触发元素上方的提示和菜单在打开后内容变多时短暂盖住触发元素的问题 ([#9247](https://github.com/getpaseo/paseo/pull/9247))
+- 修复在“历史”页面刷新网页版后显示“无法加载历史”的问题 ([#9029](https://github.com/getpaseo/paseo/pull/9029))
+- 修复 HTML 文件预览中的章节链接把预览替换成 Paseo 应用、而不是在文件内滚动的问题 ([#8559](https://github.com/getpaseo/paseo/pull/8559)，贡献者：[@3ae3ae](https://github.com/3ae3ae))
+- 修复“文件”刷新期间文件夹处于折叠状态时，新建的文件一直不显示的问题 ([#8582](https://github.com/getpaseo/paseo/pull/8582)，贡献者：[@hadan8977](https://github.com/hadan8977))
+- 修复分支仍在加载或请求失败时，分支切换器显示“没有找到分支。”的问题 ([#8938](https://github.com/getpaseo/paseo/pull/8938))
+- 修复文件被移到上一级目录时，提交历史显示双斜杠、没有重命名状态也没有 diff 的问题 ([#8509](https://github.com/getpaseo/paseo/pull/8509)，贡献者：[@hadan8977](https://github.com/hadan8977))
+- 修复检出落后于 PR 头部时，已合并的 PR 从其工作区中消失的问题
+- 修复工作区 Git 监视器在设置超时后一直停留在回退轮询的问题
+- 修复网页版或桌面端重连后，被放弃的连接最多保持打开 45 秒的问题 ([#9067](https://github.com/getpaseo/paseo/pull/9067))
+- 修复通过另一台主机路由的连接在获取超大时间线时以“The receiving client cannot keep up with host output”关闭的问题 ([#9109](https://github.com/getpaseo/paseo/pull/9109))
+- 修复已连接的主机在更新到受支持的版本后仍停留在错误状态的问题 ([#8423](https://github.com/getpaseo/paseo/pull/8423)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复连接不可达主机的尝试超时后，握手重试和每秒一次的 `relay_e2ee_channel_error` 警告仍在继续的问题 ([#9025](https://github.com/getpaseo/paseo/pull/9025), [#9038](https://github.com/getpaseo/paseo/pull/9038))
+- 修复应用诊断对曾经连接后又断开的主机报告 `Last online: never` 的问题 ([#9054](https://github.com/getpaseo/paseo/pull/9054), [#9058](https://github.com/getpaseo/paseo/pull/9058))
+- 修复 Codex 轮次被停止或中断后，该轮次启动的 shell 命令仍继续运行的问题 ([#7525](https://github.com/getpaseo/paseo/pull/7525)，贡献者：[@thomasvan](https://github.com/thomasvan))
+- 修复因 API 错误（例如会话限额或 API key 无效）而停止的 Claude 轮次被报告为已完成而非失败的问题 ([#8480](https://github.com/getpaseo/paseo/pull/8480)，贡献者：[@RRD-dev](https://github.com/RRD-dev)、[@luoph](https://github.com/luoph))
+- 修复重新打开空闲聊天但未发送提示词时，Claude 进程一直留在内存中直到 daemon 重启的问题 ([#9019](https://github.com/getpaseo/paseo/pull/9019)，贡献者：[@Brandon168](https://github.com/Brandon168))
+- 修复开启 Agent 恢复后，daemon 正常停止或重启时 Claude Agent 不恢复的问题 ([#8686](https://github.com/getpaseo/paseo/pull/8686)，贡献者：[@babo-jeonguk](https://github.com/babo-jeonguk))
+- 修复来自 Claude `settings.json` 的 Claude 模型在 Composer 中缺少推理强度控件的问题 ([#8699](https://github.com/getpaseo/paseo/pull/8699)，贡献者：[@ragokan](https://github.com/ragokan)、[@yahao123](https://github.com/yahao123))
+- 修复对话记录非常大时导入 Claude 会话因 `Invalid string length` 失败的问题 ([#8457](https://github.com/getpaseo/paseo/pull/8457)，贡献者：[@qwist1233-cpu](https://github.com/qwist1233-cpu))
+- 修复在最大轮次限制处结束的 Claude 轮次丢失最终 token 数和费用的问题 ([#8519](https://github.com/getpaseo/paseo/pull/8519))
+- 修复 Codex 的“Apply file changes”审批在你接受之前不显示文件名和 diff 的问题 ([#8585](https://github.com/getpaseo/paseo/pull/8585)，贡献者：[@ragokan](https://github.com/ragokan))
+- 修复 Codex 在一个补丁中编辑多个文件时，时间线只显示第一个文件的 diff 的问题 ([#8613](https://github.com/getpaseo/paseo/pull/8613)，贡献者：[@ragokan](https://github.com/ragokan))
+- 修复多个 Codex 操作同时启动时，Codex 会话发现和启动偶发 SQLite 初始化错误的问题 ([#9008](https://github.com/getpaseo/paseo/pull/9008)，贡献者：[@colonelpanic8](https://github.com/colonelpanic8)、[@michaelmwu](https://github.com/michaelmwu))
+- 修复 daemon 重启时正处于轮次中的 OpenCode 对话显示为空闲并忽略“停止”的问题 ([#8698](https://github.com/getpaseo/paseo/pull/8698))
+- 修复审批待处理期间你发送消息时，OpenCode 被告知你拒绝了工具调用的问题 ([#8477](https://github.com/getpaseo/paseo/pull/8477))
+- 修复重新打开的 Pi 对话缺少上下文压缩之前的消息的问题 ([#8523](https://github.com/getpaseo/paseo/pull/8523))
+- 修复工作文件夹被移除后，已归档的 Pi 聊天因 `spawn pi ENOENT` 无法打开的问题 ([#8442](https://github.com/getpaseo/paseo/pull/8442)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复关闭空闲运行时清理的情况下，读取已归档的 Pi 聊天会遗留一个 Pi 进程的问题 ([#8554](https://github.com/getpaseo/paseo/pull/8554)，贡献者：[@rylwin](https://github.com/rylwin))
+- 修复向进程已退出的 ACP Agent 发送提示词后一直停留在运行中、而不是报错失败的问题 ([#8406](https://github.com/getpaseo/paseo/pull/8406)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复 ACP Agent 放弃审批请求并结束轮次后一直卡在“waiting for permission”的问题 ([#8548](https://github.com/getpaseo/paseo/pull/8548)，贡献者：[@3ae3ae](https://github.com/3ae3ae))
+- 修复 ACP Agent 发送配置更新后，更改其模式因 `invalid_params` 失败的问题 ([#8912](https://github.com/getpaseo/paseo/pull/8912)，贡献者：[@a-sh](https://github.com/a-sh))
+- 修复在运行中的 ACP Agent 上选择不可用的模型后，Paseo 仍显示并保存该模型的问题 ([#8957](https://github.com/getpaseo/paseo/pull/8957))
+- 修复导入会话时把它从自身的模型切换为 Provider 默认模型的问题 ([#8948](https://github.com/getpaseo/paseo/pull/8948))
+- 修复来自其他 Agent 的消息在你作答之前取消接收方待处理的提问或审批的问题 ([#8453](https://github.com/getpaseo/paseo/pull/8453)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复向已连接主机上已关闭或已归档的 Agent 发送提示词后，发送方 Agent 一直收不到完成通知的问题 ([#8575](https://github.com/getpaseo/paseo/pull/8575))
+- 修复 daemon 重启后，在打开父聊天之前创建子 Agent 因“Caller agent not found”失败的问题 ([#8714](https://github.com/getpaseo/paseo/pull/8714))
+- 修复 Agent 从 Provider 错误中恢复并完成下一轮次后仍显示为失败的问题 ([#8083](https://github.com/getpaseo/paseo/pull/8083)，贡献者：[@luoph](https://github.com/luoph))
+- 修复已分离的子 Agent 在刷新之前仍显示在其已归档的父 Agent 之下的问题 ([#8903](https://github.com/getpaseo/paseo/pull/8903)，贡献者：[@luoph](https://github.com/luoph))
+- 修复打开 Agent 时因“Working directory does not exist”失败、而不是显示其已保存对话的问题 ([#8737](https://github.com/getpaseo/paseo/pull/8737))
+- 修复 daemon 在每次工作区更新时重新读取全部已归档 Agent 和工作区历史的问题 ([#8735](https://github.com/getpaseo/paseo/pull/8735))
+- 修复工作区文件夹在其文件监视器处于回退轮询期间被删除后，daemon 仍反复在其中运行 Git 命令的问题 ([#8462](https://github.com/getpaseo/paseo/pull/8462)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复浏览器标签页关闭或刷新后，工作区服务连接仍保持打开的问题 ([#8421](https://github.com/getpaseo/paseo/pull/8421)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复 daemon 网页界面对不存在的 `/.well-known/*` 请求返回应用页面而非 404 的问题 ([#8622](https://github.com/getpaseo/paseo/pull/8622)，贡献者：[@HomicideZero](https://github.com/HomicideZero))
+- 修复定时任务接受单个数字后的 cron 步长（例如 `0/15 * * * *`）并按每小时运行的问题；现在会拒绝这类表达式 ([#8607](https://github.com/getpaseo/paseo/pull/8607)，贡献者：[@Mar-garet](https://github.com/Mar-garet))
+- 修复同时设置了日期和星期的 cron 定时任务只在两者都匹配时运行、而不是任一匹配即运行的问题 ([#8611](https://github.com/getpaseo/paseo/pull/8611)，贡献者：[@Mar-garet](https://github.com/Mar-garet))
+- 修复 `paseo logs --json` 输出纯文本对话记录而非 JSON 的问题 ([#8589](https://github.com/getpaseo/paseo/pull/8589)，贡献者：[@hadan8977](https://github.com/hadan8977))
+- 修复 `create_agent` 工具没有告知 Agent 在其他 Provider 上创建 Agent 需要指定模式的问题 ([#8483](https://github.com/getpaseo/paseo/pull/8483)，贡献者：[@guerinnoah](https://github.com/guerinnoah))
+- 修复在 Windows PowerShell 无法运行 `Get-CimInstance` 的 Windows 机器上终端无法打开的问题 ([#8818](https://github.com/getpaseo/paseo/pull/8818))
+- 修复程序查询终端版本时，终端把版本应答输入到 shell 中的问题 ([#8419](https://github.com/getpaseo/paseo/pull/8419)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复在网页版终端中用手指拖动时，历史滚动距离约为拖动距离两倍的问题 ([#8776](https://github.com/getpaseo/paseo/pull/8776)，贡献者：[@sinomoe](https://github.com/sinomoe))
+- 修复切换离开终端再返回后，Copilot CLI 等终端程序中的鼠标滚动失效的问题 ([#9004](https://github.com/getpaseo/paseo/pull/9004)，贡献者：[@imink](https://github.com/imink))
+- 修复向远程终端拖入多个文件时，粘贴的路径之间没有空格的问题 ([#8946](https://github.com/getpaseo/paseo/pull/8946)，贡献者：[@sebastianarena](https://github.com/sebastianarena))
+- 修复 `browser_fill` 工具在未更新 React 受控输入框和文本域的情况下报告成功的问题 ([#9022](https://github.com/getpaseo/paseo/pull/9022))
+- 修复 `browser_evaluate` 在内容安全策略未包含 `unsafe-eval` 的页面上失败的问题 ([#8973](https://github.com/getpaseo/paseo/pull/8973)，贡献者：[@amustapha](https://github.com/amustapha))
+- 修复 `browser_logs` 缺少每个网络请求的 HTTP 状态的问题 ([#8956](https://github.com/getpaseo/paseo/pull/8956)，贡献者：[@amustapha](https://github.com/amustapha))
+
+### 插件
+
+- 新增插件订阅，可将 daemon 的实时事件流式推送到插件面板；插件 RPC 和事件支持二进制（`Uint8Array`）负载 ([#8527](https://github.com/getpaseo/paseo/pull/8527))
+- “设置 → 插件”改为通过齿轮按钮打开插件设置，每个设置页面对应一个标签页 ([#8675](https://github.com/getpaseo/paseo/pull/8675))
+- 为会打开菜单或浮层的插件 Composer 胶囊按钮新增向上的箭头 ([#8673](https://github.com/getpaseo/paseo/pull/8673))
+- daemon 启动时改为并发启动已配置的插件，不再逐个启动 ([#8427](https://github.com/getpaseo/paseo/pull/8427)，贡献者：[@DAnaeto](https://github.com/DAnaeto))
+- 修复主机的 npm 使用镜像源时，从插件库安装插件因“npm artifact changed since review”失败的问题 ([#8756](https://github.com/getpaseo/paseo/pull/8756)，贡献者：[@tlipoca9](https://github.com/tlipoca9))
+- 修复已发布的 `@getpaseo/*` npm 包未声明许可证的问题；现在声明为 Apache-2.0 ([#7816](https://github.com/getpaseo/paseo/pull/7816)，贡献者：[@mdlawson](https://github.com/mdlawson)、[@ragokan](https://github.com/ragokan))
+- 修复插件更新了自己的某张时间线卡片后，从较早的回复分叉因“This checkpoint changed after it was created”失败的问题 ([#8746](https://github.com/getpaseo/paseo/pull/8746)，贡献者：[@monarchmaisuriya](https://github.com/monarchmaisuriya))
+- 修复由插件渲染最终回复时，“折叠轮次”让轮次保持展开或折叠到较早回复的问题 ([#8811](https://github.com/getpaseo/paseo/pull/8811)，贡献者：[@geoqiao](https://github.com/geoqiao))
+- 修复应用刷新后插件目录仍在加载时，插件页面显示“This plugin surface is unavailable”的问题 ([#8123](https://github.com/getpaseo/paseo/pull/8123)，贡献者：[@vs-tahir](https://github.com/vs-tahir))
+- 修复插件添加了许多导航项时，矮屏上的工作区列表被挤出移动端侧边栏的问题 ([#8727](https://github.com/getpaseo/paseo/pull/8727)，贡献者：[@jaredwang](https://github.com/jaredwang))
+- 修复时间线插件在 Agent 消息工具调用上收不到发送方、事件和原始文本的问题 ([#8492](https://github.com/getpaseo/paseo/pull/8492)，贡献者：[@RRD-dev](https://github.com/RRD-dev)、[@luoph](https://github.com/luoph))
+- 修复输入或输出 schema 使用 transform 时插件 RPC 失败的问题 ([#8550](https://github.com/getpaseo/paseo/pull/8550))
+
+### 说明
+
+- 后台任务、基准分支选择器、归档撤销、后台 Agent、插件订阅和 fx 需要主机和应用都更新到此版本
+
+## 0.15.4 - 2026-11-10
+
+### 新增
+
+- 新增 Claude Fable 5.2 和 Mythos 5.2，默认推理强度为 medium ([#9233](https://github.com/getpaseo/paseo/pull/9233)，贡献者：[@gengjiawen](https://github.com/gengjiawen)、[@gudcks](https://github.com/gudcks))
+
+### 说明
+
+- 两个模型均需 Claude Code 2.1.321 或更高版本；仅在 Claude Code 提供访问权限时显示 Mythos 5.2
+
+## 0.15.3 - 2026-11-06
+
+### 修复
+
+- 修复了 iOS 26 及更高版本中打开或收起键盘时聊天内容变模糊的问题 ([#8918](https://github.com/getpaseo/paseo/pull/8918)，贡献者：[@dgreensp](https://github.com/dgreensp))
+
+## 0.15.2 - 2026-11-05
+
+### 新增
+
+- 在 Paseo 桌面版和网页版新增首次运行引导，依次带新用户设置主题、提供商、项目、Agent 编排和移动端应用，并可通过“设置 → 通用 → Show setup again”重新打开 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 在引导的“项目”步骤中，根据你运行过 Claude Code、Codex、OpenCode 或 Pi 的文件夹推荐项目 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+### 改进
+
+- 将主题选择器改为带各主题预览的图块网格 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将“提供商”设置中的“Loading…”文字替换为骨架占位行 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将控件统一为两种尺寸：默认控件在桌面端高 32px、在手机上高 44px，紧凑控件高 28px ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将首次启动改为从加载界面直接进入引导，不再先显示空白的主页 ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- 将桌面端和网页版的对话框改为约 160 毫秒的淡入 ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- 将弹窗和面板的背景改为与屏幕背景一致 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将“设置”各分区的文档链接改为分区标题旁的 `Label ↗` 链接 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+## 0.15.1 - 2026-11-05
+
+### 修复
+
+- 修复终端工作进程无法读取自身进程标识时 daemon 无法启动的问题；此前在 Windows PowerShell 5.1 无法运行 `Get-CimInstance` 的 Windows 机器上，Paseo 桌面版因此没有可用的 daemon ([#8810](https://github.com/getpaseo/paseo/pull/8810))
+
+## 0.15.0 - 2026-11-03
+
+daemon 重启后，终端中的程序继续运行。开启 Agent 恢复后，被中断的 Agent 会在原有会话中恢复工作。
+
+移动端终端采用原生渲染，并提供可拖动的文本选择手柄。重新连接时最多恢复 10,000 行终端历史。
+
+worktree 初始化支持复制被忽略的文件，并在 Agent 启动前使用插件指定的位置。
+
+### 新增
+
+- 点击回复中的已知 Agent 命令，将其插入 Composer 草稿 ([#8371](https://github.com/getpaseo/paseo/pull/8371))
+- 复用已运行的 OpenCode v2 服务 ([#7435](https://github.com/getpaseo/paseo/pull/7435)，贡献者：[@mcowger](https://github.com/mcowger))
+- 让终端中的程序在 daemon 重启、崩溃和支持的更新过程中继续运行 ([#7644](https://github.com/getpaseo/paseo/pull/7644), [#8155](https://github.com/getpaseo/paseo/pull/8155)，贡献者：[@sebastianarena](https://github.com/sebastianarena))
+- 新增可选设置，在主机重启后于原有会话中恢复被中断的 Agent ([#8127](https://github.com/getpaseo/paseo/pull/8127), [#8619](https://github.com/getpaseo/paseo/pull/8619)，贡献者：[@coolwindX](https://github.com/coolwindX), [@suntianc](https://github.com/suntianc))
+- 在 iOS 和 Android 终端中新增可拖动的文本选择手柄 ([#8348](https://github.com/getpaseo/paseo/pull/8348))
+- 让手机和平板遵循系统屏幕旋转设置 ([#8256](https://github.com/getpaseo/paseo/pull/8256)，贡献者：[@magiclaw](https://github.com/magiclaw), [@yzim](https://github.com/yzim))
+- 通过 `.worktreeinclude` 选择要复制到新 worktree 的被忽略文件，在初始化和 Agent 启动前完成复制 ([#8100](https://github.com/getpaseo/paseo/pull/8100)，贡献者：[@cprecioso](https://github.com/cprecioso))
+- 让 daemon 的网络请求支持 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` ([#8177](https://github.com/getpaseo/paseo/pull/8177))
+- 仅在显示用量时查询用量，并提供主机设置以完全关闭用量查询 ([#8181](https://github.com/getpaseo/paseo/pull/8181))
+
+### 改进
+
+- 更换移动端终端文本渲染方式，让中日韩字符、表情符号、带样式文本和光标对齐终端列 ([#8336](https://github.com/getpaseo/paseo/pull/8336), [#8375](https://github.com/getpaseo/paseo/pull/8375))
+- 重新连接时恢复设置指定的终端回滚历史，最多保留 10,000 行 ([#8282](https://github.com/getpaseo/paseo/pull/8282)，贡献者：[@DrakenKor](https://github.com/DrakenKor), [@lennartschoch](https://github.com/lennartschoch))
+- 导入或重新打开 Codex 会话时加载分页历史 ([#8171](https://github.com/getpaseo/paseo/pull/8171)，贡献者：[@dundunHa](https://github.com/dundunHa), [@hr95savage](https://github.com/hr95savage))
+- 重新打开已有缓存的 Codex 聊天时，不再重复读取并保留未使用的历史副本 ([#8132](https://github.com/getpaseo/paseo/pull/8132))
+- 将 daemon 的大型响应拆分为多个 relay 帧，避免达到单帧限制时断开连接 ([#8302](https://github.com/getpaseo/paseo/pull/8302))
+- 向应用发送聊天条目前截断超大内容，包括大型工具结果和内嵌数据 ([#8274](https://github.com/getpaseo/paseo/pull/8274))
+- 在子 Agent 自己的面板中显示活动，不再在父 Agent 的工具卡片中重复显示 ([#8276](https://github.com/getpaseo/paseo/pull/8276))
+- 在更精确的倒计时旁显示用量限制的具体重置时间 ([#8162](https://github.com/getpaseo/paseo/pull/8162))
+
+### 插件
+
+- 修复了插件会话回退后已丢弃的消息重新出现的问题 ([#8368](https://github.com/getpaseo/paseo/pull/8368)，贡献者：[@mcowger](https://github.com/mcowger), [@omercnet](https://github.com/omercnet))
+- 通过缩小客户端代码包并在重连和应用启动时复用缓存，减少插件下载量 ([#8040](https://github.com/getpaseo/paseo/pull/8040), [#8076](https://github.com/getpaseo/paseo/pull/8076)，贡献者：[@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- 在主机暂时断开连接期间保留插件页面和本地状态 ([#8105](https://github.com/getpaseo/paseo/pull/8105)，贡献者：[@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- 让插件通过 `worktree.create.before` 指定 worktree 的位置和创建选项 ([#8117](https://github.com/getpaseo/paseo/pull/8117)，贡献者：[@mcowger](https://github.com/mcowger))
+- 新增 `server.addHook`，并在工作区初始化和 Agent 启动前等待 `worktree.create.after` hook 完成 ([#8081](https://github.com/getpaseo/paseo/pull/8081))
+- 释放多余的插件流式快照，不再将其保留到会话结束 ([#7675](https://github.com/getpaseo/paseo/pull/7675)，贡献者：[@suntianc](https://github.com/suntianc))
+
+### 修复
+
+- 修复了无法将 Claude 会话回退到运行过程中发送的消息的问题 ([#8372](https://github.com/getpaseo/paseo/pull/8372)，贡献者：[@tieo](https://github.com/tieo))
+- 修复了重新打开会话后恢复 Claude 子 Agent 时出现重复行和回复缺失的问题 ([#8408](https://github.com/getpaseo/paseo/pull/8408)，贡献者：[@luoph](https://github.com/luoph), [@RRD-dev](https://github.com/RRD-dev))
+- 修复了未发送提示词的 Codex Agent 在运行时重新打开后无法使用的问题 ([#8393](https://github.com/getpaseo/paseo/pull/8393)，贡献者：[@babo-jeonguk](https://github.com/babo-jeonguk))
+- 修复了刚开始运行的 Agent 在创建后立即显示为已完成的问题 ([#8396](https://github.com/getpaseo/paseo/pull/8396)，贡献者：[@luoph](https://github.com/luoph))
+- 修复了 ACP 启动进程退出后仍等待超时而未及时报告错误的问题 ([#8384](https://github.com/getpaseo/paseo/pull/8384)，贡献者：[@Peanut-HZM](https://github.com/Peanut-HZM))
+- 修复了命令分批到达时新 ACP Agent 的技能列表不完整的问题 ([#8387](https://github.com/getpaseo/paseo/pull/8387)，贡献者：[@Peanut-HZM](https://github.com/Peanut-HZM))
+- 修复了目录订阅释放后侧栏标题和状态停止更新的问题 ([#8403](https://github.com/getpaseo/paseo/pull/8403)，贡献者：[@ragokan](https://github.com/ragokan))
+- 在折叠的侧栏分组中保持当前工作区可见 ([#8395](https://github.com/getpaseo/paseo/pull/8395)，贡献者：[@0xroylee](https://github.com/0xroylee))
+- 修复了聊天中的相对链接未打开嵌套仓库中的文件而指向不存在文件的问题 ([#8361](https://github.com/getpaseo/paseo/pull/8361)，贡献者：[@apple-ouyang](https://github.com/apple-ouyang))
+- 在直接连接的主机字段中支持 host:port 和粘贴的 URL ([#8223](https://github.com/getpaseo/paseo/pull/8223)，贡献者：[@DaydreamCoding](https://github.com/DaydreamCoding))
+- 修复了非 Mac 键盘通过普通 HTTP 访问网页终端时 Ctrl+V 无法粘贴的问题 ([#8230](https://github.com/getpaseo/paseo/pull/8230)，贡献者：[@DaydreamCoding](https://github.com/DaydreamCoding))
+- 停止在历史加载失败后反复重新打开 Provider，可在聊天中手动重试 ([#8278](https://github.com/getpaseo/paseo/pull/8278))
+- 修复了 Paseo 添加自身启动设置时丢弃 Claude 设置文件的问题 ([#8148](https://github.com/getpaseo/paseo/pull/8148)，贡献者：[@yayugu](https://github.com/yayugu))
+- 修复了引导消息替换尚在启动的轮次并丢失原始提示词的问题 ([#6192](https://github.com/getpaseo/paseo/pull/6192))
+- 修复了 Pi 工具结果中的图片在流式输出和重新打开聊天后缺失的问题 ([#8280](https://github.com/getpaseo/paseo/pull/8280)，贡献者：[@duyiliu](https://github.com/duyiliu))
+- 修复了 `edxeth/pi-subagents` 子 Agent 完成后仍显示为工作中的问题 ([#8176](https://github.com/getpaseo/paseo/pull/8176)，贡献者：[@Zeno2019](https://github.com/Zeno2019))
+- 修复了重新打开会话后的 Claude 后台子 Agent 状态 ([#6259](https://github.com/getpaseo/paseo/pull/6259))
+- 修复了复用的插件子 Agent 开始新任务时仍显示上次已完成状态的问题 ([#8080](https://github.com/getpaseo/paseo/pull/8080)，贡献者：[@bccy](https://github.com/bccy))
+- 修复了使用 `ollama` 等保留名称的自定义 Codex Provider ([#6954](https://github.com/getpaseo/paseo/pull/6954)，贡献者：[@mr860819](https://github.com/mr860819))
+- 修复了 MiniMax Code 目录命令无法选定可执行文件的问题 ([#8201](https://github.com/getpaseo/paseo/pull/8201)，贡献者：[@Peanut-HZM](https://github.com/Peanut-HZM))
+- 修复了 Android 应用在后台折叠或展开后保留错误布局的问题 ([#8285](https://github.com/getpaseo/paseo/pull/8285))
+- 修复了 Android 屏幕旋转后工作区布局和顶栏渐变保留旧尺寸的问题 ([#8349](https://github.com/getpaseo/paseo/pull/8349), [#8377](https://github.com/getpaseo/paseo/pull/8377))
+- 修复了 iOS 和 Android 手机聊天中重新连接和更新状态被顶栏遮挡的问题 ([#8568](https://github.com/getpaseo/paseo/pull/8568))
+- 修复了删除 Agent 后，另一个窗口留下无法关闭的标签页的问题 ([#8248](https://github.com/getpaseo/paseo/pull/8248)，贡献者：[@loganmeyer](https://github.com/loganmeyer))
+- 修复了窗口隐藏期间切换主题后，聊天文本保留旧主题颜色的问题 ([#8199](https://github.com/getpaseo/paseo/pull/8199)，贡献者：[@Nurshot](https://github.com/Nurshot), [@dansabin](https://github.com/dansabin))
+- 修复了网页菜单加载内容后跳回加载时尺寸的问题 ([#8180](https://github.com/getpaseo/paseo/pull/8180)，贡献者：[@babo-jeonguk](https://github.com/babo-jeonguk))
+- 修复了拖动分隔线时，分隔线偏离指针的问题 ([#6011](https://github.com/getpaseo/paseo/pull/6011))
+- 修复了原生文件监听器启动延迟导致 Git 更新未被监听的问题 ([#8107](https://github.com/getpaseo/paseo/pull/8107))
+- 修复了内置 skill 参数未正确传递给 Codex 和 Pi 的问题 ([#8252](https://github.com/getpaseo/paseo/pull/8252)，贡献者：[@AspireOne](https://github.com/AspireOne))
+
+### 说明
+
+- 首次从 0.14.0 升级时仍会关闭终端；安装新 daemon 后才支持保留终端，Windows 桌面应用升级仍会关闭终端
+- Agent 恢复默认关闭；在主机设置 → Agent 中开启 **重启后恢复智能体**，即可发送 `Resume working.` 或自定义提示词
+- 降级到 0.14.0 前，请恢复备份的 `config.json`，或删除已保存的 Agent 恢复和用量查询设置
 
 ## 0.14.0 - 2026-10-29
 
diff --git a/CLAUDE.md b/CLAUDE.md
index ea2ca57a4f..f09b420056 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,6 +34,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/hover.md](docs/hover.md)                                       | Hover — the canonical pattern (plain View + onPointerEnter/Leave, separate inner Pressable) and the three ways agents break it |
 | [docs/unistyles.md](docs/unistyles.md)                               | Unistyles gotchas — `useUnistyles()` is forbidden, alternatives in order                                                       |
 | [docs/floating-panels.md](docs/floating-panels.md)                   | Anchored popovers — Portal/Modal escape for Android, lifecycle gates, keyboard-shared-value, status-bar offset, the flash      |
+| [docs/keyboard-shortcuts.md](docs/keyboard-shortcuts.md)             | The binding table, per-platform key sources, badges vs routing, iOS `UIKeyCommand` limits                                      |
 | [docs/menus.md](docs/menus.md)                                       | The menu engine — popover vs sheet, submenu pages, hover intent, when a decision earns a submenu                               |
 | [docs/expo-router.md](docs/expo-router.md)                           | Expo Router route ownership, startup restore, and native blank-screen gotchas                                                  |
 | [docs/notifications.md](docs/notifications.md)                       | Notification tap ownership, native replay and acknowledgement, startup handoff, and payload QA                                 |
@@ -55,6 +56,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/terminal-rendering.md](docs/terminal-rendering.md)             | Native terminal view: xterm owns the grid, cluster placement, emoji widths, mixed-direction limits, render regression          |
 | [docs/timeline-sync.md](docs/timeline-sync.md)                       | Owned agent history, rewind retirements, live stream vs authoritative fetch, paged catch-up, client replica                    |
 | [docs/agent-stream-performance.md](docs/agent-stream-performance.md) | Assistant text pipeline — coalescing window, paced reveal, why arrival lumps are smoothed at render                            |
+| [docs/agent-stream-disclosure.md](docs/agent-stream-disclosure.md)   | Expand/collapse in the chat timeline — hold contract, native anchor sequence, frame spacing, render-window cost                |
 | [docs/markdown-renderer.md](docs/markdown-renderer.md)               | Shared Markdown engine, native selection, links, images and library constraints                                                |
 | [docs/native-text-selection.md](docs/native-text-selection.md)       | Native diagram grouping, selection boundaries and leading inline image limitations                                             |
 | [docs/file-observation.md](docs/file-observation.md)                 | Recursive watcher ownership, Linux constraints, teardown invariants, and Parcel comparison                                     |
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 253b89de90..43b1f2f47c 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -14,9 +14,10 @@ Each live agent in `AgentManager` carries a `lastStatus` of `initializing`, `idl
 
 ## Daemon restart recovery
 
-Hosts resume interrupted agents by default after graceful shutdown or a crash. The daemon
-reopens the saved provider conversation and settings, then sends `Resume working.`. Change
-`agents.resumePrompt` or disable `agents.resumeOnStartup` in host config or Host settings → Agents.
+Restart recovery is off by default. Enable `agents.resumeOnStartup` in host config or
+Host settings → Agents to resume interrupted agents after graceful shutdown or a crash. The daemon
+reopens the saved provider conversation and settings, then sends `Resume working.`. Customize
+the prompt with `agents.resumePrompt` or the same settings page.
 Disabling recovery consumes pending intent; enabling it later does not revive old work.
 
 Only agents recorded as running qualify. Idle and initializing agents stay inactive. Archived
@@ -135,6 +136,12 @@ the marker. Closing a tab sets that client's label to `false`. Any `true` client
 open. Detach clears the parent and every open-tab label. The surviving child therefore becomes a
 normal root agent immediately, and closing its still-open tab archives it.
 
+Agent-scoped workspace creation records the caller's workspace as `parentWorkspaceId`.
+This is informational ancestry for future workspace grouping. It does not change placement,
+visibility, status, or archive behavior. Archiving a parent workspace preserves its children's
+records and parentage. Unscoped creation and existing workspaces have no parent; ancestry is
+never inferred from directories, projects, or Git branches.
+
 Runtime ownership is resolved from explicit workspace ID and caller context, never from `cwd`. Workspace creation is a separate operation with `local | worktree` isolation; agent creation reuses that workspace unless a new workspace is explicitly requested.
 
 Setup belongs to the workspace, including combined workspace-plus-agent creation and the supported agent `worktree` request. Run setup through the workspace workflow before launching configured terminals or scripts. Setup output is read in the Setup panel from per-command snapshots; never produce setup chat timeline rows or concatenate command logs. Legacy agent `git`/`worktreeName` inputs and hidden MCP worktree placement are rejected with workspace-creation guidance. Existing wire schemas retain an empty combined-log string for parsing compatibility.
@@ -182,23 +189,42 @@ Some providers can create their own child sessions inside one provider runtime.
 
 The provider still owns the underlying runtime. Paseo keeps an agent record so the child can be opened, tracked, archived, and cascaded with the parent, but prompts and history hydration route through the provider adapter for that native child handle.
 
-## Background workspaces
+## Background visibility
 
-`workspace.background` controls discovery only. Background workspaces contain ordinary durable
-agents and terminals: provider history, plugin hooks, parentage, archive, and restart recovery
-keep their normal behavior. Visibility is creation-only; selecting an existing workspace cannot
-change it. New workspaces default to false, inherit the caller workspace's value when an agent
-creates one without an override, and accept explicit true or false.
+An agent is effectively background when it or its workspace is background:
+`agent.background || workspace.background`. Background controls discovery only. Background agents
+and the agents in background workspaces are ordinary durable agents: provider history, plugin
+hooks, parentage, finish notifications to a caller, archive, and restart recovery keep their
+normal behavior. Both flags are fixed at creation.
 
-The daemon derives agent discovery from workspace ownership. Default workspace and agent lists,
-including History requests, exclude background work; `filter.includeBackground` includes it.
-Exact-ID operations bypass discovery filtering. The app replicates both kinds and filters only
-its sidebar with **Show background**, so direct navigation and restored tabs remain available.
+- **Agent.** `create_agent_request.background` marks the agent. Use it for helpers the user does
+  not watch, such as a plugin's classifier in the user's open workspace. A background agent never
+  raises attention, adds nothing to its workspace's status bucket or Last prompt time, and stays
+  out of tabs, the parent's subagent track and agent lists in the app. A tab opened by id still
+  works.
+- **Workspace.** `workspace.background` hides the workspace from the sidebar unless **Show
+  background** is on.
+- **Inheritance.** When `background` is omitted, an agent created by a caller agent takes the
+  caller's own `background`. A new workspace takes the caller's effective background. A request
+  that creates its workspace applies `background` to both the agent and the workspace. Explicit
+  true or false always wins.
+
+`AgentDirectory` (`packages/server/src/server/agent/directory.ts`) owns visibility for lists.
+Default workspace and agent lists, including History requests, exclude background work;
+`includeBackground` includes it. Exact-ID operations bypass discovery filtering. The app
+replicates inclusively and filters at each surface.
+
+Sources without the `background_agents` hello capability get workspace-only visibility on
+inclusive reads and subscriptions: agents in background workspaces, but no agent-level background
+agents. Older apps replicate inclusively and auto-open a tab for every root agent, so a classifier
+run would otherwise open a tab each turn. That visibility has its own directory sync generation.
 
 Sequenced directories keep complete canonical collections. A filtered read must never replace
 those collections with its subset. Inclusive and default observations have distinct cursor
 scopes, so changing scope requires a fresh snapshot rather than reusing an incomplete cache.
-Clients gate creation and inclusive discovery on `features.backgroundWorkspaces`.
+Clients gate background workspaces and inclusive discovery on `features.backgroundWorkspaces`.
+They gate a background agent placed in an existing workspace or under a caller on
+`features.backgroundAgents`.
 
 ### Private daemon helpers
 
@@ -234,6 +260,27 @@ archived workspace. History navigation must not infer workspace lifecycle from `
 or mutate either lifecycle. The workspace route asks the daemon for authoritative recovery state;
 only the route's explicit Unarchive or Restore action changes the archived workspace.
 
+Workspace archive is undoable from the archived toast, or with Cmd/Ctrl+Z, while the toast is up.
+The daemon runs one archive lane per workspace, shared by every connection
+(`packages/server/src/server/workspace-archive-operations.ts`):
+
+| A request arrives while  | Result                                                    |
+| ------------------------ | --------------------------------------------------------- |
+| an archive runs: archive | joins the running archive                                 |
+| an archive runs: undo    | aborts the archive, waits for it to settle, then restores |
+| an undo runs: archive    | waits for the undo, then archives                         |
+| an undo runs: undo       | joins the running undo                                    |
+
+A request takes its place in the lane before its first `await`. Arrival order decides, so an undo
+sent right behind its archive still cancels it.
+
+An aborted archive stops at its next checkpoint and reports `canceled`; the undo unarchives only
+the agents that archive itself archived. Deleting the worktree directory is the point of no
+return: an undo after it recreates the worktree through workspace recovery. The client shows or
+hides the row by the latest local intent, so a late remove or upsert from a superseded request
+does not flip it back. Tabs and layout are purged only once the undo window closes with the
+archive committed.
+
 History navigation opens the selected agent without changing either archive state. Workspace
 **Restore** recovers only the workspace; the selected archived agent stays open with its callout.
 The agent's **Unarchive** runs the provider's native unarchive hook before interactive resume and
@@ -288,17 +335,27 @@ Running provider-native subagents contribute `running` to the workspace owned by
 
 Only the parent's current runtime makes a provider child running. A child's stored status is the last report about it, and that report can come from provider history or from a runtime an earlier daemon ran, so a stored `running` child does not make the workspace running or keep the parent's runtime alive. It counts again once the live session reports it running. Closing a runtime cancels the children that runtime reported running; children it never reported keep their stored status.
 
-A finished workspace can be marked unread after it has been reviewed. The daemon restores
-`finished` attention on its newest eligible workspace-root agent without sending a new completion
-notification. Opening the workspace clears that attention through the normal focus flow.
+A finished or failed workspace can be marked unread after it has been reviewed. The daemon restores
+attention on its newest eligible workspace-root agent, `error` for an agent whose lifecycle is
+`error` and `finished` otherwise, without sending a new notification. Opening a workspace restores
+its selected tab; attention on another agent remains unread until that agent is focused or the
+workspace is explicitly marked read.
 
-Attention is set by the agent finishing or failing and cleared by the client's
-`workspace.clear_attention`, which fires when the user reads the chat. Loading an agent's runtime is
+Attention is set by the agent finishing or failing and acknowledged by deliberate focus or
+interaction with its chat, including repeat clicks in an already focused pane. A completion
+arriving while focused stays unread until the next interaction; leaving does not acknowledge it. Loading an agent's runtime is
 neither, so resuming carries the stored attention and the stored last-activity time through
 untouched. Forging either makes a background resume look like the user read a workspace and like the
 agent worked in it just now, which rewrites the sidebar timestamp permanently — persisted
 `updatedAt` is what workspace `statusEnteredAt` is re-derived from on the next daemon start.
 
+The `failed` bucket follows unread `error` attention, not lifecycle status. An agent stays `error`
+until its next turn starts, so reading the chat dismisses the red dot the same way it dismisses the
+green one. For the same reason every new failure raises `error` attention, including a failed reload
+that leaves the lifecycle at `error`, and replaces unread `finished` attention; otherwise the failed
+agent would show the green dot or none. Subagents track marks are the exception: they follow the
+child's lifecycle, because the track is where a failed child stays visible.
+
 ## The subagents track
 
 The track is a pill at the foot of an agent's pane (`packages/app/src/subagents/track.tsx`): a count you can read at a glance, and a panel behind it — a popover on wide screens, a sheet on compact ones — holding the rows. It floats over the transcript rather than sitting in a band above the composer, so the timeline scrolls underneath it; `packages/app/src/panels/agent-tracks.tsx` owns that placement, and the pill frame is shared with the task list in `packages/app/src/composer/tracks.tsx`.
diff --git a/docs/agent-stream-disclosure.md b/docs/agent-stream-disclosure.md
new file mode 100644
index 0000000000..1d5caefcf2
--- /dev/null
+++ b/docs/agent-stream-disclosure.md
@@ -0,0 +1,197 @@
+# Agent stream disclosures
+
+Expanding or collapsing something in the chat timeline (a turn's summary line, a tool-call group,
+a tool call's inline details, a todo card, a long user message's show more, a plan card) keeps the
+tapped trigger at the same screen y in the first painted frame. No animation.
+
+## The contract
+
+A disclosure component knows nothing about the list. It wraps its state change:
+
+```tsx
+const hold = useDisclosureHold();
+const handleToggle = () => hold(() => setExpanded((value) => !value));
+```
+
+`view.tsx` wraps every timeline row in `DisclosureRow`, which routes `hold` to the strategy's
+`holdRow(rowId, apply, triggerEdge)` (`packages/app/src/agent-stream/disclosure.tsx`). Outside a
+timeline row, `apply` runs as is. The strategy owns when `apply` runs and how the row keeps its place.
+A toggle that calls `setState` directly skips the hold: on Android the expanded content paints
+over the next row for a frame before the list learns the new size.
+
+`triggerEdge` names the edge of the row the trigger sits on, and the strategy keeps that edge in
+place. Header triggers sit on the top edge, the default. A long user message's show more sits under
+the text it opens, so `MessagePreview` passes `{ triggerEdge: "bottom" }`: the text grows and shrinks
+above the trigger, and the rows below stay put.
+
+Following output:
+
+- A hold detaches the bottom anchor controller (`holdForDisclosure`), except a bottom-edge hold on
+  native while following: there the end pin already keeps the row's bottom in place.
+- When the hold ends, the controller re-sticks only if the list sits at its end and no user scroll
+  owns the viewport (`releaseDisclosure({ isAtEnd })`). Expanding at the bottom therefore leaves
+  the list detached with the scroll-to-bottom pill showing; collapsing back to the end resumes
+  following.
+- Scroll events during the hold never re-stick: the correction is a programmatic scroll that
+  would otherwise read as "back at the bottom".
+
+The trigger can only stay put when the list has scroll room for the change. When the loaded
+content fits the viewport, or a collapse at the end would need an offset past the end, the list
+ends at its end and the trigger moves by the difference.
+
+## Web
+
+`holdRow` pins the row's trigger edge in the reading anchor and runs `apply`; the next reading
+reconcile restores that edge after layout, before paint (`strategy-web.tsx`). The pin records the
+scroll offset it was taken at, because the browser clamps `scrollTop` when a collapse shrinks the
+content past the offset, before the reconcile reads it. Restoring from the clamped offset would
+apply the shrink twice.
+
+## Native
+
+On compact layouts, tool calls and tool-call groups open a sheet instead of expanding, so they do
+not hold. Summary lines, todo cards, plan cards and show more expand inline.
+
+The timeline is a LegendList in forward order: one `data` array of history rows followed by the
+live head, oldest first (`strategy-native.tsx`). LegendList keeps a row in place across a size
+change in the commit that makes it, so a hold needs no anchor neighbour, native child index or
+render window stretch. The inverted FlatList it replaced needed all three, and three commits per
+toggle; its applied commit took up to 3.5 s of JS on a long turn.
+
+### Who owns the offset
+
+One owner keeps the scroll offset at any moment:
+
+| State                  | Owner                                                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Before rows are placed | LegendList's initial scroll to the end. It keeps the rows hidden until they are measured.                         |
+| Following the end      | The end pin (`native-end-pin.tsx`), also for a bottom-edge hold.                                                  |
+| Disclosure hold        | LegendList's `maintainVisibleContentPosition` on the hold's anchor row, or the end pin for the last row's bottom. |
+| User scroll            | The finger. The controller detaches at drag start.                                                                |
+| Detached               | LegendList's `maintainVisibleContentPosition` on the first visible row.                                           |
+| Keyboard motion        | Nobody. The keyboard translates the list with the composer and leaves the offset alone.                           |
+
+The end pin is a zero-height view at the bottom of the content and the content's first native
+child, with React Native's `maintainVisibleContentPosition` set to `{ minIndexForVisible: 0 }`. The
+native correction runs on the UI thread around each mount, so a row that grows or lands at the end
+scrolls in the frame it lays out. The controller scrolls only for a viewport resize (the composer
+growing or shrinking) and an explicit jump, both through the native `scrollToEnd`.
+
+Do not use LegendList's `maintainScrollAtEnd` instead. It scrolls from JS after the mount to the end
+its JS sizes predict: growth paints below the viewport for a frame, and the scroll lands short of
+the native end, which the controller reads as the user scrolling away.
+
+The keyboard never changes the list's size, padding or offset. `KeyboardTranslateView` moves the list
+and the composer together on the UI thread, and the composer viewport clips the top of the list
+while the keyboard is open. Do not add a keyboard-sized inset to keep that content reachable: it can
+only commit after the motion, and while detached or holding nothing corrects for it, so every row
+jumps by the keyboard height after the keyboard settles.
+
+### The hold
+
+`holdRow(rowId, apply, triggerEdge)` runs in the toggle's event:
+
+1. Pick the anchor and detach the controller (`holdForDisclosure`). LegendList restores row
+   tops only, so a top-edge hold anchors the toggled row and a bottom-edge hold anchors the row
+   below it, whose top is the toggled row's bottom (`disclosureAnchor`). The pin goes away
+   and LegendList's `maintainVisibleContentPosition` takes over, restoring only the anchor row
+   (`shouldRestorePosition`). A bottom-edge hold while following skips this step: the end pin
+   keeps the content end, and the row's bottom with it, in the frame the new height mounts.
+
+   A bottom-edge hold on the last row, such as a prompt the agent has not answered yet, has no
+   row below it: its bottom is the content end (the running indicator is the list footer, not a
+   row). The hold mounts the end pin while detached, and `apply` runs a frame later. The pin
+   anchors only once it is mounted, and a pin that mounts in the same commit as the new height
+   anchors nothing. The pin's commit mounts before that frame's JS callbacks run, so `apply`'s
+   commit mounts with the pin already in place. The pin keeps the distance from the end, and each
+   content size change clamps it to the scroll room left, so the hold re-sticks if the list was
+   at its end when tapped or a collapse used up the room. The release tracks that distance
+   instead of reading the offset: the new content size reaches JS before the pin's scroll does.
+   A reply landing below the row ends the pin in the commit that mounts the reply, so the reply
+   grows below the row and the trigger stays where it was. A reply that lands before `apply` runs
+   moves the hold to the reply's row.
+
+   Upstream LegendList anchors only rows from the first fully visible one down to the last fully
+   visible one, and a size change with no data change keeps the first row in view whatever
+   `shouldRestorePosition` says. A row cut off at the top would then let the row below it hold
+   instead, and a bottom-edge anchor just under the viewport would not hold at all. The LegendList
+   patch counts the rows cut off at the top, and the row just past the bottom, as in view and
+   applies `shouldRestorePosition` to size changes too. It also drops LegendList's Android clamp
+   prediction: the scroll view clamps after the adjustment
+   ([scroll view corrections](#scroll-view-corrections)), so the prediction moved a collapse near
+   the end to the end.
+
+2. Run `apply`.
+3. Call the row's `useSyncLayout` trigger. The toggle changes the row from its own state, so
+   LegendList's container does not re-render and would learn the new height from `onLayout` a task
+   later, after the change painted. The trigger puts the measurement and the corrected positions
+   in the toggle's own commit.
+
+The hold ends two frames after the last item size change, since the list measures the toggled row
+and any rows it inserted over several frames (`native-disclosure-hold.ts`). The controller then
+re-sticks only if the list is within 1 px of its end, the same distance web resumes from.
+
+### User scroll
+
+The controller detaches at `onScrollBeginDrag`, so lines that stream in during a drag grow below
+the rows under the finger. The detach reaches native a JS round trip after the drag begins, so for
+those frames the pin is still mounted. The scroll view subclasses skip the pin's correction while
+the user drags (see [scroll view corrections](#scroll-view-corrections)). They skip only the pin's:
+in the detached state LegendList uses the same native correction, and a history page that lands
+mid-drag needs it. They key on the drag, not the touch, so a tap or long press while following
+keeps following.
+
+Following resumes only for a gesture that ends within 1 px of the end, either when the finger lifts
+or when momentum stops. A release past the end counts: iOS bounces back to the end, and lines that
+land during the bounce must keep scrolling in. A release anywhere short of the end stays detached
+with the scroll-to-bottom pill, so the rows the user let go of never move.
+
+### Draw distance
+
+`drawDistance` is 2000 px on each side of the viewport. A fling over rows that were never measured
+blanks the viewport until LegendList renders and measures them. Twelve flings over a chat with a
+15,000 px turn expanded, Android emulator, dev build:
+
+| List                          | Blank viewport             | Janky frames | p50 / p90 / p99  |
+| ----------------------------- | -------------------------- | ------------ | ---------------- |
+| Inverted FlatList             | 1.3 to 1.7 s over 5 flings | 10.8%        | 27 / 48 / 109 ms |
+| LegendList, drawDistance 500  | 1.0 to 1.5 s per fling     |              |                  |
+| LegendList, drawDistance 2000 | none                       | 1.7%         | 24 / 32 / 48 ms  |
+
+With every turn collapsed, flinging from a cold open into history did not blank at any value from
+500 to 2000, and jank followed host load (19 to 40 on 16 cores) rather than draw distance. Measure
+1000 and 1500 on the expanded chat, on a host under load 10, before lowering it.
+
+### LegendList patch
+
+`patches/@legendapp+list+3.7.1.patch` carries twelve changes for the timeline. Its header lists
+them by purpose, and
+[legend-list #593](https://github.com/LegendApp/legend-list/issues/593) reports each upstream.
+Drop a hunk when the installed LegendList ships its fix.
+
+### Scroll view corrections
+
+`modules/paseo-scroll` replaces React Native's scroll view on both platforms with a subclass:
+Android's `PaseoScrollView` and iOS's `PaseoScrollViewComponentView`.
+`VisibleContentPositionClampTest` covers Android; iOS has no native test harness.
+
+**Content clamp.** A mount that shrinks the content while `maintainVisibleContentPosition` is set
+applies the shrink twice on both platforms: the scroll view clamps its offset to the new end during
+the mount, and React Native then adds the anchor's movement to the clamped offset
+([RN #58578](https://github.com/react/react-native/issues/58578), fix in
+[PR #58695](https://github.com/react/react-native/pull/58695)). A turn that folds while the list
+follows its end lands above the end. Android defers the clamp to the pre-draw pass, and iOS restores
+the pre-mount offset for the adjustment and clamps after it.
+
+**Removed anchor (iOS).** A hold removes the end pin in the same mount that opens the tapped
+disclosure, and React Native 0.86 on iOS moves the offset by the removed view's frame. The iOS
+subclass keeps the offset. Android keeps a removed view's last frame, so it keeps the offset already.
+React Native 0.88 skips the adjustment for a removed anchor
+([PR #57294](https://github.com/react/react-native/pull/57294)).
+
+**End pin during a drag.** Both subclasses recognize the pin by its native ID, `paseo-end-pin`,
+and skip its correction while the user drags ([user scroll](#user-scroll)). This one has no React
+Native counterpart; it stays while the timeline uses the pin.
+
+Remove the content clamp and removed-anchor overrides once the installed React Native includes
+their fixes.
diff --git a/docs/agent-stream-performance.md b/docs/agent-stream-performance.md
index ec506ee99b..4c43718215 100644
--- a/docs/agent-stream-performance.md
+++ b/docs/agent-stream-performance.md
@@ -34,10 +34,11 @@ So arrival sets a _target_ and the reveal rate is derived from the backlog inste
 - **First sight of a text is revealed whole.** Only growth is paced. This is what makes history hydration, timeline replay, a virtualized row remounting on scroll, and an already-finished message all render complete on first paint without a special case for each.
 - **Leaving `phase: "streaming"` snaps the reveal.** A completed turn must never be left holding characters. `layoutStream` sets the phase, so anything outside the live head with an active turn is already complete.
 - **The reducer queue commits on a frame, with a timer as the ceiling.** A frame callback never fires in a hidden tab, so a timer races it and wins when nothing is painting — the store has to keep advancing either way.
-- **A history row re-renders only when its item or layout item identity changes.** The inverted
-  FlatList hands every mounted cell a new `index` and `ref` whenever a row is prepended, so without a
-  memo boundary each coalesced tick re-rendered every mounted row (about 50 on a phone, 100–250 ms of
-  JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed,
+- **A turn boundary commits the queue before turn liveness changes.** The final reply arrives a few milliseconds before `turn_completed`, so it is still queued when the turn ends. `applyStreamEvent` in `viewed-timeline-sync.ts` flushes the agent's queue first; otherwise the chat paints a finished turn with no reply, drops the footer, and jumps twice.
+- **A history row re-renders only when its item or layout item identity changes.** Every
+  coalesced tick hands the list a new layout. Without a memo boundary each tick re-rendered every
+  mounted row (measured on the inverted FlatList native used before LegendList: about 50 rows on a
+  phone, 100–250 ms of JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed,
   `useRevisedHistoryRows` hands a fresh item identity to rows whose tool-call group, expanded state,
   or breakpoint changed, and `StreamRow` memoizes on both. Every viewport runs its history
   through that hook; the web viewport once skipped it and history hosts of a live tool group went
diff --git a/docs/android.md b/docs/android.md
index 6188589eb8..8b6201ae91 100644
--- a/docs/android.md
+++ b/docs/android.md
@@ -61,6 +61,18 @@ Gradle auto-fetches the platform/build-tools it needs once licenses are accepted
 
 ## Local build + install
 
+The `react-native-svg@15.15.4` patch prevents header fades retaining their old painted size after
+rotation. Rebuild native Android after changing it; Metro reloads cannot update this code. Keep the
+resize hunks until upstream invalidates descendant geometry on canvas resize. Its instrumentation
+regression renders real gradient pixels across growing and shrinking layouts, including a nested
+group. From `packages/app/android`, run it on your selected emulator:
+
+```bash
+ANDROID_SERIAL=emulator-5562 ./gradlew :react-native-svg:connectedDebugAndroidTest \
+  -Pandroid.testInstrumentationRunnerArguments.class=com.horcrux.svg.SvgResizeTest \
+  --no-daemon --max-workers=2 -Dorg.gradle.parallel=false
+```
+
 The locked `expo-modules-core@57.0.23` needs the patch installed by `npm install`.
 It backports
 [Expo's Activity-result launcher fix](https://github.com/expo/expo/pull/49634): changing
@@ -162,14 +174,18 @@ REACT_NATIVE_PACKAGER_HOSTNAME=localhost \
 
 This is the Android counterpart of the iOS local-simulator flow in [development.md](development.md): on iOS the simulator shares the Mac's loopback so `localhost:<port>` works directly; on Android you need `10.0.2.2` or `adb reverse`.
 
-## Inverted timeline selection
+## Scroll view corrections
 
-Android focus and selection visibility requests must not reposition inverted timelines. The
-`modules/paseo-scroll` package keeps React Native's scroll manager interface and returns zero for
-child-reveal scroll calculations when the view's transform matrix inverts the vertical axis. React
-Native's Android list uses `scale: -1`, which decomposes into a 180-degree rotation with positive
-`scaleY`; checking the scale property alone misses it. Dragging and explicit scroll
-commands still work; non-inverted scroll views keep Android's default behavior.
+`modules/paseo-scroll` replaces React Native's vertical scroll view with `PaseoScrollView`, which
+keeps React Native's scroll manager interface and corrects `maintainVisibleContentPosition` for the
+chat timeline. [agent-stream-disclosure.md](agent-stream-disclosure.md#scroll-view-corrections)
+lists the corrections and the React Native issues they work around. Its instrumentation test,
+`VisibleContentPositionClampTest`, mounts through React Native's own mounting manager:
+
+```bash
+cd packages/app/android
+./gradlew :paseo-scroll:connectedDebugAndroidTest --no-daemon --max-workers=2 -Dorg.gradle.parallel=false
+```
 
 Register this package before React Native's core package through its Expo config plugin. Normal
 Android builds use the prebuilt `react-android` library, so patching Java under `node_modules` does
diff --git a/docs/architecture.md b/docs/architecture.md
index 6409161670..b6215b8b59 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -277,7 +277,7 @@ its teardown; reconnect creates new server IDs for surviving client handles. See
 
 **Top-level WS envelopes** are `hello`, `recording_state`, `ping`/`pong`, and `session` (which wraps the rich union of session messages).
 
-Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC or RFC6455 control ping. Current clients ping every 10 seconds, beginning one interval after connecting. The first ping claims an application-ownership lease for that physical socket, all later inbound activity renews it, and the daemon forcibly terminates the socket if the lease expires. A legacy or raw socket that never sends an application ping never enters this lease and is not closed for omitting one. Session RPC timeouts are operation failures, not proof that the socket is dead. A subscription bootstrap timeout closes its source to clear any unknown server-owned registration; the failed handle is released before other surviving handles reconnect.
+Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC or RFC6455 control ping. Current clients ping every 10 seconds, beginning one interval after connecting; a window with no validated inbound frame is a miss, and two misses in a row tear the socket down. When the app returns to the foreground the client runs a fresh cycle of two 5-second windows back to back, then reconnects without backoff, because a socket that died while the OS had JS suspended stays `OPEN` and accepts sends: only inbound frames prove it. Misses and probes from before the suspension do not count toward that cycle, and a window whose timer fires long after its deadline spanned another suspension, so it is discarded and the cycle starts over. Any complete frame inside a window keeps the connection, so a slow multi-frame transfer survives; a single frame that takes longer than the two windows to arrive after foreground does not, and the fix for that is smaller daemon-to-client frames, not a longer window. The first ping claims an application-ownership lease for that physical socket, all later inbound activity renews it, and the daemon forcibly terminates the socket if the lease expires. A legacy or raw socket that never sends an application ping never enters this lease and is not closed for omitting one. Session RPC timeouts are operation failures, not proof that the socket is dead. A subscription bootstrap timeout closes its source to clear any unknown server-owned registration; the failed handle is released before other surviving handles reconnect.
 
 Every physical send path enforces an 8 MiB outbound high-water mark, including JSON broadcasts, binary terminal frames, and the encrypted relay adapter's asynchronous queue. This sits above the terminal stream's 4 MiB soft backpressure threshold, leaving room for snapshot catch-up before the hard cutoff. JSON is serialized once per broadcast after sockets already at the limit are removed, then its exact byte length is checked for every remaining socket. A frame that would cross the limit is not sent; that physical socket is forcibly terminated without disturbing other sockets attached to the same logical session. Multiple tabs and simultaneous direct and relay paths may legitimately share a client id.
 
diff --git a/docs/connected-hosts.md b/docs/connected-hosts.md
index 20c86c1295..7e8b67ee62 100644
--- a/docs/connected-hosts.md
+++ b/docs/connected-hosts.md
@@ -74,7 +74,10 @@ registrations remain inspectable; a changed destination requires explicit identi
 
 Both daemons advertise `connectedHosts`; the shared link additionally requires `hostMultiplexing`.
 A completes capability and pinned-identity checks on each physical recovery before admitting channels. There is no local fallback. An older daemon continues to serve existing local
-operations; requesting this feature gives update guidance.
+operations; requesting this feature gives update guidance. The registry retries an older destination
+with capped backoff, so it comes online once updated. Self, duplicate, changed-identity, and
+authentication failures stay in `error` until an update changes the connection, `enabled`, or
+`replaceIdentity`, or A restarts.
 
 Disposing a routed API releases its observations and session. It does not remove the saved host or
 affect sibling API scopes. Disposing the origin cascades to its derived scopes. Observations restore
diff --git a/docs/custom-providers.md b/docs/custom-providers.md
index 615389fe60..ef0281ec7f 100644
--- a/docs/custom-providers.md
+++ b/docs/custom-providers.md
@@ -65,6 +65,7 @@ per-agent examples and provider-specific keys.
 ## Table of Contents
 
 - [Extending a built-in provider](#extending-a-built-in-provider)
+- [OpenCode with an existing v2 server](#opencode-with-an-existing-v2-server)
 - [Z.AI (Zhipu) coding plan](#zai-zhipu-coding-plan)
 - [Alibaba Cloud (Qwen) coding plan](#alibaba-cloud-qwen-coding-plan)
 - [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai-compatible-endpoint)
@@ -107,6 +108,35 @@ See [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai
 
 ---
 
+## OpenCode with an existing v2 server
+
+Paseo first uses an explicitly configured server, then a healthy locally registered OpenCode v2 service, then starts its own helper. It never stops a reused service. To select a server explicitly, set its URL in the provider environment:
+
+```json
+{
+  "agents": {
+    "providers": {
+      "opencode": {
+        "env": {
+          "PASEO_OPENCODE_SERVER_URL": "http://127.0.0.1:4096",
+          "PASEO_OPENCODE_SERVER_PASSWORD": "<server password>"
+        }
+      }
+    }
+  }
+}
+```
+
+`PASEO_OPENCODE_SERVER_URL` must be an absolute `http` or `https` URL. Omit `PASEO_OPENCODE_SERVER_PASSWORD` when the server has no authentication; when set, Paseo authenticates with HTTP Basic auth as `opencode`.
+
+A configured URL takes precedence even when unreachable; Paseo reports the connection error. The local service registration supplies its own authentication. For a discovered local service, Paseo installs its bridge package in OpenCode's watched global plugin directory without changing the existing configuration. Refresh reads the existing service's catalogs without starting another server.
+
+An explicitly configured server needs the bridge installed separately. Connect once and start a session: the setup error gives the local package directory. Copy that directory to the server's OpenCode global `plugins` directory, then retry. For a server on another machine, set `PASEO_OPENCODE_BRIDGE_PORT` in the Paseo OpenCode provider environment before starting Paseo, and set `PASEO_OPENCODE_BRIDGE_URL` to the URL the OpenCode server can use to reach that port. For example, an SSH reverse tunnel can expose the Paseo loopback port on the OpenCode host. The bridge token is exchanged through the OpenCode connection and is not written into the plugin package.
+
+OpenCode's custom MCP registrations are shared by all sessions in a location. Paseo rejects custom MCP servers and per-agent process environment overrides on a reused server rather than applying them to other sessions or ignoring them. Session identity is applied to each session's shell environment. A Paseo-owned helper supports custom process and MCP settings; it is selected when there is no explicit URL or healthy registered service.
+
+---
+
 ## Z.AI (Zhipu) coding plan
 
 [Z.AI](https://z.ai) is a Chinese AI company (Zhipu AI) that offers an Anthropic-compatible API endpoint. Their GLM Coding Plan provides flat-rate access to GLM models through Claude Code's Anthropic API protocol. These are **not** Anthropic Claude models — they are Zhipu's own GLM models exposed through an Anthropic-compatible API.
@@ -747,6 +777,8 @@ The built-in `claude` provider appends concrete model IDs from `~/.claude/settin
 
 This lets users who already configured Claude Code for Bedrock, OpenRouter, ollama, Z.AI, or another Anthropic-compatible gateway select the exact model ID in Paseo. Explicit model IDs are passed unchanged to Claude Code, even when the same string is a compatibility alias for a built-in model. When `agents.providers.claude.models` is set it **replaces** both the hardcoded first-party Claude list and any settings.json-discovered entries; use `agents.providers.claude.additionalModels` to keep the first-party list and append curated entries on top.
 
+Paseo's effort selector does not inherit `effortLevel` from Claude's settings.json. Select an effort in Paseo to choose a specific value.
+
 ### Gotcha: `extends: "claude"` with third-party endpoints
 
 When a custom provider extends `"claude"` but points `ANTHROPIC_BASE_URL` at a non-Anthropic API (Z.AI, Alibaba/Qwen, proxies), the Claude Agent SDK may try to use Anthropic-only server-side tools like `WebSearch`. Third-party APIs don't support these tools, causing errors.
diff --git a/docs/data-model.md b/docs/data-model.md
index 39d39e0ce7..cb4f63a70e 100644
--- a/docs/data-model.md
+++ b/docs/data-model.md
@@ -26,6 +26,10 @@ checkout root. They intentionally differ for an exact subproject inside a worktr
 restore, branch auto-name, and descriptor flows consume those persisted facts rather than
 rediscovering ownership from a directory that may already be gone. Reconciliation may refresh
 mutable placement facts, but never changes `projectId`, `cwd`, `displayName`, or `baseBranch`.
+An explicit base selection is stored in the checkout's Git-directory Paseo metadata and
+mirrored to `baseBranch` in every workspace record sharing that checkout. The record keeps
+recovery possible after the checkout metadata is deleted. A newly opened workspace inherits
+the checkout's selected base; separate worktrees keep separate bases.
 Workspace archive runs lifecycle teardown from the exact `cwd` but removes only the backing
 `worktreeRoot` after its last active reference disappears. Worktree recovery recreates that backing
 checkout from `mainRepoRoot`, then restores the relative path from `worktreeRoot` to `cwd`.
@@ -92,6 +96,7 @@ Each agent is stored as a separate JSON file, grouped by project directory.
 | `lastUserMessageAt`  | `string?` (ISO 8601)                     | Last user message timestamp                                                                                                                                                                                                                                                                                                                                                         |
 | `title`              | `string?`                                | User-visible title                                                                                                                                                                                                                                                                                                                                                                  |
 | `labels`             | `Record<string, string>`                 | Key-value labels (default `{}`). Paseo uses `paseo.parent-agent-id` for parentage and client-scoped `paseo.open-agent-tab.*` labels while managed subagent tabs are open — see [agent-lifecycle.md](./agent-lifecycle.md)                                                                                                                                                           |
+| `metadata`           | `Record<string, JsonValue>`              | Plugin-owned data (default `{}`). Paseo stores and forwards it and never reads a key. Set at creation or through `agent.metadata.update.request`; `null` in a patch removes a key                                                                                                                                                                                                   |
 | `lastStatus`         | `AgentStatus`                            | One of: `"initializing"`, `"idle"`, `"running"`, `"error"`, `"closed"`. `closed` means the record is resumable but has no live provider runtime; archive remains represented separately by `archivedAt`.                                                                                                                                                                            |
 | `lastModeId`         | `string?`                                | Last active mode ID                                                                                                                                                                                                                                                                                                                                                                 |
 | `config`             | `SerializableConfig?`                    | Agent session configuration (see below)                                                                                                                                                                                                                                                                                                                                             |
@@ -343,6 +348,14 @@ the number of Git processes that have started but not exited. Every Git command
 including initial workspace reads, filesystem-triggered refreshes, background checks, and explicit
 requests.
 
+Commands wait in one of three lanes, drained in order: `high` (worktree creation and archive),
+`normal` (everything a caller waits for, including diffs and explicit refreshes), and `background`
+(workspace reconciliation, refreshes triggered by watchers, polls and fetches, and the fetches
+themselves). Daemon-initiated fan-out must run in the background lane: one rescan over ~90 worktrees
+queues over 1,000 commands, and in the normal lane every command a cold diff runs waited behind
+them. Set the lane on the runner with `createRunGitCommand(provenance, { priority })`, or around a
+whole operation with `runWithGitCommandPriority`.
+
 Environment variables override `config.json`:
 
 | Environment variable                 | Setting                  |
@@ -478,7 +491,7 @@ Array of workspace records. A workspace is a specific working directory within a
 | `title`                        | `string \| null`                                             | User-set name override layered over `displayName`. Null means "use `displayName`".                                                                                                            |
 | `branch`                       | `string \| null`                                             | The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name.                                                   |
 | `worktreeRoot`                 | `string \| null`                                             | Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement.                       |
-| `baseBranch`                   | `string \| null`                                             | Comparison base retained across archive and restore. Branch-off creation stores the resolved ref; legacy and PR-checkout records hold a bare name. Null means no recorded base.               |
+| `baseBranch`                   | `string \| null`                                             | Current base retained across archive and restore. Explicit selections and branch-off creation store exact refs; older records may store branch names. Null means no recorded base.            |
 | `isPaseoOwnedWorktree`         | `boolean`                                                    | Whether Paseo owns and may remove/recreate the backing `worktreeRoot`                                                                                                                         |
 | `mainRepoRoot`                 | `string \| null`                                             | Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot`                                                                                       |
 | `createdAt`                    | `string` (ISO 8601)                                          |                                                                                                                                                                                               |
@@ -486,6 +499,7 @@ Array of workspace records. A workspace is a specific working directory within a
 | `archivedAt`                   | `string \| null` (ISO 8601)                                  | Soft-delete; required nullable                                                                                                                                                                |
 | `autoArchivedChangeRequestUrl` | `string \| null`                                             | Change request whose merged state triggered auto-archive. Restore replaces it with the current merged change request, when present, so repeated snapshots cannot archive the workspace again. |
 | `labels`                       | `string[]?`                                                  | Normalized display names assigned from this host's shared label catalog. Missing means unlabelled.                                                                                            |
+| `metadata`                     | `Record<string, JsonValue>`                                  | Plugin-owned data (default `{}`). Paseo stores and forwards it and never reads a key. Set at creation or through `workspace.metadata.update.request`.                                         |
 | `pinnedAt`                     | `string \| null` (ISO 8601)                                  | Pinned-to-top-of-sidebar timestamp; null means "not pinned"                                                                                                                                   |
 | `untrustedSource`              | `{ kind: "change_request", forge, number, headRepository }?` | Provenance captured when a cross-repository change request creates the workspace. Missing means repository automation is allowed; explicit setup removes the field.                           |
 
diff --git a/docs/design.md b/docs/design.md
index a336b80a64..f86565e97e 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -20,7 +20,7 @@ A semantic element used in three or more places is a primitive. One of a kind is
 
 Primitives live in `packages/app/src/components/ui/` and `packages/app/src/components/headers/`. Card and row layout live in `packages/app/src/styles/settings.ts`. Section structure lives in `packages/app/src/screens/settings/settings-section.tsx`.
 
-A pressable styled to look like a button is wrong; the button is `<Button>` (`packages/app/src/components/ui/button.tsx`). A pressable wrapping an icon is wrong; the icon action is `<ToolbarButton>` (`packages/app/src/components/ui/pane-content-toolbar.tsx`), which owns the hitbox, the rounded `interactionHighlight` fill on hover and press, the compact size, and the tooltip. Rows on a menu surface are `<MenuItem>`, or `<ComposerTrackRow>` in a track panel; other rows are `<PressHighlight>` (`packages/app/src/components/ui/press-highlight.tsx`), which flashes on native the moment a finger lands. A bare `<Text>` styled to look like a section header is wrong; the section header is `<SettingsSection>` (`packages/app/src/screens/settings/settings-section.tsx`). A custom `Modal` for a confirmation is wrong; the confirmation is `confirmDialog` (`packages/app/src/utils/confirm-dialog.ts`). A hand-rolled overflow menu is wrong; the menu is `<DropdownMenu>` (`packages/app/src/components/ui/dropdown-menu.tsx`). A hand-rolled status pill is wrong; the pill is `<StatusBadge>` (`packages/app/src/components/ui/status-badge.tsx`). A circle pinned over a scrolling surface is wrong; the floating action is `<FloatingActionButton>` (`packages/app/src/components/ui/floating-action-button.tsx`), one per surface, and the surface reserves `FLOATING_ACTION_BUTTON_CLEARANCE` below its content so the button never traps the last row.
+A pressable styled to look like a button is wrong; the button is `<Button>` (`packages/app/src/components/ui/button.tsx`). A pressable wrapping an icon is wrong; the icon action is `<ToolbarButton>` (`packages/app/src/components/ui/pane-content-toolbar.tsx`), which owns the hitbox, the rounded `interactionHighlight` fill on hover and press, the compact size, and the tooltip. Rows on a menu surface are `<MenuItem>`, or `<ComposerTrackRow>` in a track panel; other rows are `<PressHighlight>` (`packages/app/src/components/ui/press-highlight.tsx`), which flashes on native the moment a finger lands. A bare `<Text>` styled to look like a section header is wrong; the section header is `<SettingsSection>` (`packages/app/src/components/settings/headings/settings-section.tsx`). A docs link in its header is its `link` prop, which renders `Label ↗` on the title's rail; a ghost button with an arrow is wrong. A custom `Modal` for a confirmation is wrong; the confirmation is `confirmDialog` (`packages/app/src/utils/confirm-dialog.ts`). A hand-rolled overflow menu is wrong; the menu is `<DropdownMenu>` (`packages/app/src/components/ui/dropdown-menu.tsx`). A hand-rolled status pill is wrong; the pill is `<StatusBadge>` (`packages/app/src/components/ui/status-badge.tsx`). A circle pinned over a scrolling surface is wrong; the floating action is `<FloatingActionButton>` (`packages/app/src/components/ui/floating-action-button.tsx`), one per surface, and the surface reserves `FLOATING_ACTION_BUTTON_CLEARANCE` below its content so the button never traps the last row.
 
 Before adding a new component, read `components/ui/`. The primitive usually exists.
 
@@ -35,8 +35,8 @@ The authored interface ramp uses a 14px base. New native installs default to 15p
 Weight has three tiers, applied by role:
 
 - **Screen titles** — the title in app chrome — use `<ScreenTitle>` (`packages/app/src/components/headers/screen-title.tsx`), which renders `fontSize.base` at weight `400` on compact and `300` on desktop. The New workspace hero is the only larger product title; it uses `fontSize["2xl"]` (`packages/app/src/screens/new-workspace-screen.tsx`).
-- **Structural labels** use `fontWeight.medium`. This applies to section labels above a stack of rows (`packages/app/src/components/agent-list.tsx:519-523`, `packages/app/src/components/keyboard-shortcuts-dialog.tsx:63-67`), form field labels above an input inside a modal (`packages/app/src/components/add-host-modal.tsx:19-23`, `packages/app/src/components/pair-link-modal.tsx:24-28`), the title at the top of a modal/sheet/dialog (`packages/app/src/components/adaptive-modal-sheet.tsx:90-94`, `packages/app/src/components/ui/combobox.tsx:1607-1611`, `packages/app/src/components/welcome-screen.tsx:48-53`), action button labels in tight components such as the sidebar callout actions (`packages/app/src/components/sidebar-callout.tsx:218-221`), and inline data emphasis on dense metadata rows (`packages/app/src/components/git-diff-pane.tsx:2322-2327`, `packages/app/src/components/file-explorer-pane.tsx:1115-1122`).
-- **Content** uses `fontWeight.normal`. This applies to settings rows (`packages/app/src/styles/settings.ts`), sidebar primary list-item titles (`packages/app/src/components/sidebar-workspace-list.tsx:2680-2686`, `packages/app/src/components/agent-list.tsx:572-578`), `<Button>` text (`packages/app/src/components/ui/button.tsx:80-84`), `<StatusBadge>` text (`packages/app/src/components/ui/status-badge.tsx:56-60`), and `<SidebarCallout>` titles (`packages/app/src/components/sidebar-callout.tsx:175-180`).
+- **Structural labels** use `fontWeight.medium`. This applies to section labels above a stack of rows (`packages/app/src/components/agent-list.tsx:519-523`, `packages/app/src/components/keyboard-shortcuts-dialog.tsx:63-67`), form field labels above an input inside a modal (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx:19-23`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx:24-28`), the title at the top of a modal/sheet/dialog (`packages/app/src/components/adaptive-modal-sheet.tsx:90-94`, `packages/app/src/components/ui/combobox.tsx:1607-1611`, `packages/app/src/components/welcome-screen.tsx:48-53`), action button labels in tight components such as the sidebar callout actions (`packages/app/src/components/sidebar-callout.tsx:218-221`), and inline data emphasis on dense metadata rows (`packages/app/src/components/git-diff-pane.tsx:2322-2327`, `packages/app/src/components/file-explorer-pane.tsx:1115-1122`).
+- **Content** uses `fontWeight.normal`. This applies to settings rows (`packages/app/src/styles/settings.ts`), sidebar primary list-item titles (`packages/app/src/components/sidebar-workspace-list.tsx:2680-2686`, `packages/app/src/components/agent-list.tsx:572-578`), `<StatusBadge>` text (`packages/app/src/components/ui/status-badge.tsx:56-60`), and `<SidebarCallout>` titles (`packages/app/src/components/sidebar-callout.tsx:175-180`).
 
 The rule, condensed: text that _names_ a surface or a group is `medium`. Text that lives _inside_ a surface or a group is `normal`. Top-of-screen titles are `<ScreenTitle>`, which is lighter still.
 
@@ -68,9 +68,15 @@ the sidebar. Apply it as `backgroundColor`; setting `opacity` on the control als
 
 `destructive` is filled with `destructive`. It only appears inside a confirm. The button on the page is `outline`; the destructive button is the confirm button inside the dialog.
 
-Sizes: `xs` for ultra-tight inline triggers. `sm` for any button sitting in a row. `md` is the page default. `lg` is reserved for large standalone CTAs.
+Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
 
-Sizes are a shared contract across control kinds, defined once in `control-geometry.ts`: `xs` = 28px tall with `fontSize.sm` labels, `sm` = 32px with `fontSize.base`, `md`/`lg` = 44px with `fontSize.base`. `<SegmentedControl>` (`packages/app/src/components/ui/segmented-control.tsx`) takes the same `xs`/`sm`/`md` sizes — a segmented control next to a `<Button>` of the same size always matches in height, label size, and corner radius. Its segments run one padding step tighter than a button, because the gap between segments already reads as padding. The selected segment is a `surface3` fill with `foreground` text, not an inverted one — inverting it inside thin chrome puts a white slab in the toolbar. Text fields take `xs`, `sm` and `md`. Thin chrome such as the file toolbar uses `xs`. A settings row sizes the controls in its trailing slot itself, `sm` in a card and `xs` when nested (`packages/app/src/components/ui/control-size.tsx`), so don't pass a size to a button, dropdown or field placed in a row. Never shrink a control's font or padding locally to fit a context — if the context needs a smaller control, the size tier is missing or the wrong one is in use.
+Dense toolbar rows, such as the composer's, are the exception to the 44pt control. Touch-sized the row is 44pt tall and each control is a 36pt circle (`TOOLBAR_DISC_SIZE`): send and stop fill it, and every other control's pressed highlight fills it, so every highlight is the same fully rounded shape. Labelled pickers are 36pt pills. A control lays out at its full highlight (`toolbarSlot`, `toolbarContentSlot`) with no gap between controls (`TOOLBAR_CONTROL_GAP`), so neighbouring highlights touch and never overlap. Toolbar glyphs match the header icons: 20pt, the app's 1.5px stroke, resting at `foreground` (`toolbarGlyphsFor`). The context ring is 18pt with a 2px stroke (`TOOLBAR_RINGS`): a circle fills its box where an outline glyph does not, and a thin circle reads lighter than a glyph at the same stroke. A disc's solid glyph, such as the stop square, stays at the `md` size (`TOOLBAR_DISC_GLYPH_SIZES`). Pointer-sized toolbars keep 28px controls, a 4px gap, and a 16pt muted glyph that brightens on hover.
+
+In the composer, the first glyph's ink starts on the text column's edge, and the trailing control is always a disc, so the row does not shift as it changes between voice mode, send and stop. The disc nests into the corner, as far from the right edge as from the bottom, and touch-sized the composer's corner radius is concentric with it (`packages/app/src/composer/input/toolbar-rails.ts`). Touch-sized the disc keeps a 6pt clearance from its neighbour, because it is always painted and a pressed neighbour would merge with it. The attach button sits 2pt closer to the picker than its highlight would put it: the plus is all thin arms, so the full gap reads wide. That offset is set by eye.
+
+One gate, `resolveControlSizing`, picks touch or pointer sizing: touch when the layout is compact or the device has a touch screen. An iPad with the sidebar docked is wide and touch-sized; a desktop is pointer-sized; a phone is both compact and touch. The touch-screen fact is read once at startup (`hasTouchScreen` in `hooks/use-fine-pointer.ts`), so attaching a mouse or keyboard to a tablet never shrinks its controls. Stylesheets take sizes from `bySizing({ touch, pointer })`, which resolves to a breakpoint value, so a caller never sees which sizing it got. Rows, icon buttons and icon slots take theirs from `styles/density.ts`, which uses the same gate. An `{ xs, md }` literal for a hit target or glyph is wrong: on an iPad it yields the pointer size.
+
+Buttons are pills (`borderRadius.full`) with medium-weight labels; an icon-only button is a circle. `<Switch>` follows the same two sizes: a 34×20 track by default and in `sm`, 44×26 where controls are touch-sized, and it reserves its size's control height so a row holding one lines up with a row holding a button. Buttons, text fields, dropdown triggers, and `<SegmentedControl>` (`packages/app/src/components/ui/segmented-control.tsx`) share the size contract — the same size name means the same height and label size on every control kind, so controls in one row line up. Segments run tighter than a button, because the gap between segments already reads as padding. The selected segment is a `surface3` fill with `foreground` text, not an inverted one — inverting it inside thin chrome puts a white slab in the toolbar. A settings row sizes the controls in its trailing slot itself, default in a card and `sm` when nested (`packages/app/src/components/ui/control-size.tsx`), so don't pass a size to a button, dropdown or field placed in a row. Code that computes with a control's height outside a stylesheet uses `controlHeightForLayout`. Never shrink a control's font or padding locally to fit a context — if the context needs a smaller control, the size tier is missing or the wrong one is in use.
 
 A `<Pressable>` wrapping a `<Text>` is a sixth variant. It is wrong. `<Button>` accepts `style`, `textStyle`, `leftIcon`, `disabled`, `size`, and `variant`.
 
@@ -102,7 +108,7 @@ Five primitives. The pick is determined by option count, the need to search, and
 
 `<ContextMenu>` is for right-click and long-press on a target. The row is the trigger; there is no visible affordance. Used for incidental actions on workspace rows in the sidebar (`packages/app/src/components/sidebar-workspace-list.tsx`).
 
-`<AdaptiveModalSheet>` is for a focused task. Multi-field forms (`packages/app/src/components/add-host-modal.tsx`, `packages/app/src/components/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`), confirmations with detail, anything that earns a backdrop. Bottom sheet on compact, centered card on desktop. Raw `Modal` is wrong for any of these.
+`<AdaptiveModalSheet>` is for a focused task. Multi-field forms (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`), confirmations with detail, anything that earns a backdrop. Bottom sheet on compact, centered card on desktop. Both sit on `surface0`, the same base as a screen, so settings cards and inputs inside a modal read the way they do on the Settings screen. Raw `Modal` is wrong for any of these.
 
 `<AdaptiveModalSheet>` owns the presentation. Its content inset — the gutter that puts sheet content on the same rails as the sheet header — and compact bottom safe-area padding are the sheet's, not the caller's. A caller declares layout intent through `contentStyle` and never branches on form factor to add its own margins. If a sheet's first snap point is shorter than its header, content, and safe-area clearance, raise that snap point rather than moving the sheet container.
 
@@ -114,7 +120,7 @@ Three themes is `DropdownMenu`. Thirty hosts is `Combobox`. A label and a value
 
 ## 7. Density and rhythm
 
-Settings detail pages, the projects detail page, and any list+detail content sit inside a centered, max-width 720 column (`packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`). Lines stay readable, the eye does not have to track wide horizontal distances. Form modals carry their own narrower content frame (`packages/app/src/components/add-host-modal.tsx`).
+Settings detail pages, the projects detail page, and any list+detail content sit inside a centered, max-width 720 column (`packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`). Lines stay readable, the eye does not have to track wide horizontal distances. Form modals carry their own narrower content frame (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx`).
 
 Workspace and chat surfaces use the full width — these are working surfaces, not reading surfaces. The composer carries `MAX_CONTENT_WIDTH` from `packages/app/src/constants/layout.ts` to keep lines readable while letting the workspace pane fill the rest.
 
@@ -126,7 +132,7 @@ Cards inside a section sit closer than sections. Rows inside a card touch — on
 
 Rows have generous vertical padding: roughly 16px of content plus 16px of vertical padding for settings rows, 8–12px for sidebar list items where many rows must fit. Compressing rows below the established density to fit more on the screen is wrong. Too many rows means more cards or more sections, not smaller rows.
 
-Rows revealed under a `<SettingsCollapsibleRow>` are nested rows, one step smaller than card rows: 8px of vertical padding, `fontSize.sm` text, `xs` controls, and one fixed height so rows with and without a trailing button line up. The collapsible row sets this for everything under it (`packages/app/src/components/settings/row-density.tsx`). Never pass a density to a row, and never pad or resize a nested row by hand.
+Rows revealed under a `<SettingsCollapsibleRow>` are nested rows, one step smaller than card rows: 8px of vertical padding, `fontSize.sm` text, `sm` controls, and one fixed height so rows with and without a trailing button line up. The collapsible row sets this for everything under it (`packages/app/src/components/settings/row-density.tsx`). Never pass a density to a row, and never pad or resize a nested row by hand.
 
 The whitespace is the design.
 
@@ -138,7 +144,7 @@ Things align to their glyphs, not to their boxes. A row's leading icon, its titl
 
 Pick the rails from the content, then hold them. A settings card establishes a leading rail at the icon's left edge and a trailing rail at the last glyph's right edge; every row in that card uses the same two. A row whose icon is absent still starts its title on the leading rail. Indentation is a new rail, not an arbitrary offset.
 
-The pressable is bigger than the glyph, and that is fine. Hit areas grow outward from the aligned content — they never move it. A button that looks two pixels off because its padding is asymmetric is misaligned even though its box is correct.
+The pressable is bigger than the glyph, and that is fine. Hit areas grow outward from the aligned content — they never move it. A button that looks two pixels off because its padding is asymmetric is misaligned even though its box is correct. The composer toolbar is the worked example: its outermost ink, the attach `+` on the left and the trailing glyph or send/stop disc on the right, sits on the text column's edges, and touch-sized the end highlights overhang into the composer padding by each end control's ink inset (`composerToolbarOverhang`).
 
 Optical alignment beats arithmetic when a glyph disagrees with its bounding box. Icons with visual weight on one side, chevrons, and single-character labels usually need a small nudge to look centered. Trust the eye, then leave a comment saying the offset is optical.
 
@@ -150,7 +156,7 @@ One row off the rail makes the whole card look unconsidered.
 
 Compact-first. The small case is designed; the large case adds chrome around it.
 
-Use `md: 600` for both the compact/wide layout boundary and responsive density, in logical points on native and CSS pixels on web. Do not add a separate density breakpoint. Measured content constraints remain independent: composer controls use `COMPACT_CONTENT_WIDTH` (500), so a narrow pane can keep compact controls inside a wide window.
+Use `md: 600` for the compact/wide layout boundary, in logical points on native and CSS pixels on web. Do not add a separate density breakpoint; touch sizing comes from the control sizing gate in [Buttons](#4-buttons). Measured content constraints remain independent: composer controls use `COMPACT_CONTENT_WIDTH` (500), so a narrow pane can keep compact controls inside a wide window.
 
 The settings shell (`packages/app/src/screens/settings-screen.tsx`) and the projects screen (`packages/app/src/screens/projects-screen.tsx`) share the canonical list+detail navigation pattern:
 
@@ -167,6 +173,8 @@ Electron window controls are top-corner obstructions, not a compact-layout condi
 
 Windows and Linux controls are fixed window chrome, outside scrolling header content. A tab rail that reaches them ends at their obstruction and shows the shared overflow fade. On macOS, the Explorer toggle occupies a fixed top-right window slot so opening and closing Explorer does not move the pointer target.
 
+Each window edge has one safe-area owner. `WindowLayoutProvider` publishes the bottom inset that every surface reads through `useSafeAreaInsets()`: on iOS 27.1 and later it is UIKit's bottom-bar clearance, which refines the rectangular home-indicator inset to the screen's corners, and elsewhere the system inset. Surfaces apply that value once and never stack their own spacing under it; `WindowLayoutSurface` owns the horizontal insets the same way.
+
 A new list+detail feature copies the settings shell. A new workspace-shaped feature copies the workspace shell. Inventing a third shape happens in design review, not in a PR.
 
 ---
@@ -197,11 +205,11 @@ Terminology:
 
 Loading is inline by default. `<LoadingSpinner size={14} color={foregroundMuted} />` sits next to the thing it relates to (`packages/app/src/screens/settings/providers-section.tsx:227-231`). Page-level loading is a centered `<LoadingSpinner size="large">` (`packages/app/src/screens/sessions-screen.tsx:69-72`). Card-level loading is a single short line, not a spinner. In-row dropdown items use `<DropdownMenuItem status="pending" pendingLabel="Removing...">`; the menu item handles its own pending state.
 
-Screen-level empty states use a centered, muted noun phrase and at most one ghost button (`packages/app/src/screens/sessions-screen.tsx`). Sidebar list empty states use a quiet bordered card with a left-aligned `sm` title, a muted `sm` description, and `xs` `<Button>` actions. Use `secondary` for the primary action and `outline` for a secondary action (`packages/app/src/components/sidebar/empty-states.tsx`). Keep both forms short and free of illustrations.
+Screen-level empty states use a centered, muted noun phrase and at most one ghost button (`packages/app/src/screens/sessions-screen.tsx`). Sidebar list empty states use a quiet bordered card with a left-aligned `sm` title, a muted `sm` description, and `sm` `<Button>` actions. Use `secondary` for the primary action and `outline` for a secondary action (`packages/app/src/components/sidebar/empty-states.tsx`). Keep both forms short and free of illustrations.
 
 Inline errors are a single sentence in `palette.red[300]` `xs`, sitting under the field or inside the card it relates to (`packages/app/src/screens/settings/providers-section.tsx:115-119`).
 
-Page-level alerts — informational notices, success confirmations, warnings, or recoverable errors that need a small visible block on the page — use `<Alert>` (`packages/app/src/components/ui/alert.tsx`). Variants: `default`, `info`, `success`, `warning`, `error`. The chrome is quiet by design: a 1px tinted border, transparent background, a small variant-tinted icon, the title in the variant accent, the description in `foregroundMuted`. Actions go in the `children` slot as `<Button variant="outline" size="sm">` — recovery actions are low-frequency and outline keeps them quiet alongside the alert's accent (`packages/app/src/screens/project-settings-screen.tsx`). One `<Alert>` at a time per region.
+Page-level alerts — informational notices, success confirmations, warnings, or recoverable errors that need a small visible block on the page — use `<Alert>` (`packages/app/src/components/ui/alert.tsx`). Variants: `default`, `info`, `success`, `warning`, `error`. The chrome is quiet by design: a 1px tinted border, transparent background, a small variant-tinted icon, the title in the variant accent, the description in `foregroundMuted`. Actions go in the `children` slot as `<Button variant="outline">` — recovery actions are low-frequency and outline keeps them quiet alongside the alert's accent (`packages/app/src/screens/project-settings-screen.tsx`). One `<Alert>` at a time per region.
 
 Sidebar callouts — cross-cutting alerts that apply across the whole app, like worktree setup, Rosetta install, and desktop update available — register through `useSidebarCallouts()` and render in the left sidebar via `<SidebarCallout>` (`packages/app/src/components/sidebar-callout.tsx`). The chrome (top-border-only, full-width action buttons) is tuned for that ~280px column. Canonical sources: `packages/app/src/components/worktree-setup-callout-source.tsx`, `packages/app/src/desktop/updates/rosetta-callout-source.tsx`, `packages/app/src/desktop/updates/update-callout-source.tsx`. Never import `<SidebarCallout>` into a page — that's what `<Alert>` is for.
 
@@ -251,7 +259,7 @@ New status pills use `<StatusBadge>`. Identity, shortcut, and interactive link b
 
 ## 14. Forbidden
 
-- `fontWeight.medium` on row titles, body text, button labels, badge text, or `<SidebarCallout>` titles. Medium is reserved for the structural-label tier described in §3 — section labels, modal/sheet titles, dense metadata emphasis, and tight action labels. Anything else is `normal`. `<ScreenTitle>` is responsive `400/300` and is never overridden.
+- `fontWeight.medium` on row titles, body text, badge text, or `<SidebarCallout>` titles. Medium is reserved for the structural-label tier described in §3 — section labels, modal/sheet titles, dense metadata emphasis, and tight action labels. Anything else is `normal`. `<ScreenTitle>` is responsive `400/300` and is never overridden.
 - `<Pressable>` wrapping `<Text>` to make a button. `<Button>` exists.
 - Importing `Pressable` or a `Touchable*` outside `components/ui/`. A raw pressable has no standard press or hover feedback, so every one drifts. `paseo/no-raw-pressable` reports it; the files on its burn-down list in `.oxlintrc.json` may only leave it.
 - Bare `<Text>` for a section header inside settings. `<SettingsSection>` exists.
@@ -278,7 +286,7 @@ New status pills use `<StatusBadge>`. Identity, shortcut, and interactive link b
 | List+detail (compact stack, desktop sidebar+pane)   | `packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`                                                                                                                                                                                                           |
 | Detail card+row                                     | `packages/app/src/screens/settings/host-page.tsx`, `packages/app/src/screens/settings/providers-section.tsx`                                                                                                                                                                                             |
 | Section grouping inside a card list                 | `packages/app/src/screens/settings/settings-section.tsx`                                                                                                                                                                                                                                                 |
-| Form modal (label + input fields, primary + cancel) | `packages/app/src/components/add-host-modal.tsx`, `packages/app/src/components/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`                                                                                                                                              |
+| Form modal (label + input fields, primary + cancel) | `packages/app/src/hosts/add-host/internal/add-host-modal.tsx`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`                                                                                                                    |
 | Destructive confirmation                            | `confirmDialog` invoked from `packages/app/src/screens/settings/host-page.tsx:541-547`                                                                                                                                                                                                                   |
 | Centered hero / first-run                           | `packages/app/src/components/welcome-screen.tsx`                                                                                                                                                                                                                                                         |
 | Sidebar list (workspaces, hosts)                    | `packages/app/src/components/sidebar-workspace-list.tsx`, `packages/app/src/components/left-sidebar.tsx`                                                                                                                                                                                                 |
diff --git a/docs/development.md b/docs/development.md
index 873f9cabb9..ddebf3ffff 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -593,7 +593,17 @@ rerun passes only by landing elsewhere.
 
 To confirm, fetch the URL from several runners and compare `content-length`, the `cf-ray` colo
 suffix, and the number of `attestations` entries (#7730 has the probe). To fix, remove or
-replace that version in the lockfile and report the URL to npm so they purge it.
+replace that version in the lockfile. If the dependent’s range cannot be changed, pin a clean
+version in root `overrides`. Report the URL to npm so they purge it.
+
+A lockfile regeneration is itself how new bad versions enter: the pkijs fix re-resolved the
+electron-builder tree and pulled in `semver` 5.7.3 and 6.3.2, published two days earlier, and
+5.7.3 then failed the same way. After editing `overrides`, run `npm install --package-lock-only`
+and check that the changed `resolved` lines in `package-lock.json` are only the ones you meant.
+
+A per-parent override such as `"tiny-async-pool": { "semver": "5.7.2" }` applies to that
+parent's whole subtree, so it can also downgrade a grandchild that needs a different major. Key
+the child by range (`{ "semver@^5": "5.7.2" }`) so only matching edges are replaced.
 
 ## ACP provider catalog versions
 
diff --git a/docs/expo-router.md b/docs/expo-router.md
index 3bd6a43435..f81c194ffb 100644
--- a/docs/expo-router.md
+++ b/docs/expo-router.md
@@ -58,11 +58,17 @@ restore the same workspace and could repeat the crash.
 
 ## App-Wide Route Hops
 
+Keep Add host in `hosts/add-host`, opened through `useAddHost()`. It is an in-place
+flow; callers choose what happens after success. Settings opts into the new host’s
+Overview. Do not send callers to Settings with an `addHost` query parameter: a
+retained route replays that request when appearance changes remount its content.
+The flow provider and sheet host stay outside appearance keys so open drafts survive.
+
 When app-wide routes such as `/new`, `/settings`, or `/sessions` navigate back
 into a host workspace, use `navigateToWorkspace()`. Do not make the caller
 branch on its current route.
 
-Pass only `serverId` and `workspaceId` for normal attention-aware navigation.
+Pass only `serverId` and `workspaceId` to restore the workspace’s selected tab.
 When the action names a specific tab, pass it as `target`; that explicit choice
 is authoritative. Callers should not choose between separate route and tab
 navigation APIs.
@@ -90,7 +96,8 @@ hidden workspace can overwrite the remembered workspace before Settings or
 History returns.
 
 Plugin settings use the distinct `settings/hosts/[serverId]/plugins/[pluginId]/[screenId]` leaf;
-Back returns to that host's Plugins page.
+Back returns to that host's Plugins page. Its screen tabs change `screenId` with `router.setParams`,
+so switching tabs adds no stack entries.
 
 Settings detail routes are separate siblings on purpose. Keep
 `settings/[section]`, the host routes, the projects index, and project detail as
diff --git a/docs/file-observation.md b/docs/file-observation.md
index d7d1d8f2f0..c2e68d83a9 100644
--- a/docs/file-observation.md
+++ b/docs/file-observation.md
@@ -8,7 +8,7 @@ Closing an observation must remain safe after its root is renamed or removed. Wo
 
 `unsubscribe()` is an awaited barrier. Once it resolves, no scan, reconciliation, queued event, native handle, or callback may remain. `updateIgnore()` is the equivalent barrier for excluded paths: events queued below a newly excluded root cannot be delivered after it resolves. Treat path disappearance while scanning, attaching, or receiving a watcher error as rename/archive churn. Surface permission and resource errors so WorkspaceGit can enter bounded polling.
 
-Linux topology repair is trailing-debounced and scoped to the renamed path. A file rename needs one classification stat; a new or moved directory scans only its subtree. Full-tree scans are reserved for startup and ignore-set replacement. The initial Linux scan conservatively emits existing files discovered before their directory watcher was installed; WorkspaceGit batches these into one refresh. Benchmark this startup cost with pre-populated trees.
+Linux topology repair is trailing-debounced and scoped to the renamed path. A file rename needs one classification stat; a new or moved directory scans only its subtree. Full-tree scans are reserved for startup and ignore-set replacement. A subscription reports changes after `subscribe()` resolves, not the files that already existed. macOS FSEvents can still replay writes made moments before the stream started. Consumers read their initial state after `subscribe()` resolves; WorkspaceGit re-reads its checkout once observation setup completes, because its first refresh runs in parallel with setup. The Linux startup scan therefore emits nothing; only a scoped reconciliation of new topology reports files found before their directory's watcher was installed. Startup creates made every cold diff compute and discard a first revision. Benchmark startup cost with pre-populated trees.
 
 Windows and macOS use one native recursive watcher plus an ignored-pruned, directory-indexed inventory. Native events deliver immediately. Named events trigger serialized shallow scans of their parent directories; known directory events also reconcile that subtree. This recovers concrete create and delete paths omitted by coalescing without walking the whole root for each edit. Classification is admission-controlled to 32 concurrent `fs.stat` calls, since `fs.stat` runs on the libuv threadpool the whole daemon shares. Startup and exclusion changes use an awaited full inventory barrier. Activity arms a full safety audit 30 seconds after it settles, with a 30-second minimum interval and a five-minute starvation bound; pathless native events also trigger an immediate shallow root scan. Observation fails into polling rather than retaining more than 250,000 file and directory entries per root. A repository that large is also expensive to poll, so degraded polling doubles its gap from 5 seconds to a 60-second ceiling while the workspace snapshot comes back unchanged, and resets to 5 seconds on the first change. Explicit reads still force a refresh; the ceiling only bounds how long an edit made outside Paseo stays undiscovered.
 
diff --git a/docs/floating-panels.md b/docs/floating-panels.md
index 4616a03815..ed49f3106d 100644
--- a/docs/floating-panels.md
+++ b/docs/floating-panels.md
@@ -157,8 +157,7 @@ and the stream keeps its existing flick-to-dismiss gesture.
 The dock's private viewport and capacity model are extracted from chat. The
 app-wide `@/keyboard/shift` module owns shared motion for the dock, portals, streams,
 terminal, explorer, and dialogs. Import only its public entry point: the provider,
-shift hooks, shift style, translate view, keyboard anchor, settled stream inset, and explorer padding
-policy. Its contexts and reconciliation stay private. Keep `KeyboardShiftProvider`
+shift hooks, shift style, translate view, and keyboard anchor. Its contexts and reconciliation stay private. Keep `KeyboardShiftProvider`
 at its root mount point outside the portal host when changing dock hosts.
 
 `KeyboardTranslateView` owns visual keyboard motion inside `@/keyboard/shift`. Android uses the
@@ -171,15 +170,19 @@ animation. Keep this platform choice inside the keyboard module's private platfo
 `KeyboardTranslateView`. The panel root clips it at the header edge, so rows
 slide under the header on open and out from under it on close. Do not swap the
 dock to keyboard padding at rest. Changing its height creates either a blank
-band or a paused transition when the inverted list updates its viewport.
+band or a paused transition when the stream list updates its viewport.
+
+The docked composer rests at the larger of the safe-area bottom and 16pt. With
+the keyboard open it keeps 16pt above the keyboard through the translate view's
+`keyboardGap`, which rises further than the keyboard's safe-area overlap. Do not
+grow the composer's bottom padding with the keyboard instead.
 
 Do not animate a layout prop through the keyboard transition. On Android
 Fabric, each animated layout update clones the shadow tree and runs Yoga over
 the dock subtree. This measured about 10 ms per frame on the emulator and the
 mounted layouts arrived in bursts every 2–4 frames. A transform does not dirty
-layout. Preserve the translated dock's history scroll range with a far-end
-content inset on the inverted stream list. Update that inset only when keyboard
-motion settles; never drive it per frame.
+layout. The stream list gets no keyboard inset either; see
+[who owns the offset](agent-stream-disclosure.md#who-owns-the-offset).
 
 The translated dock's height is not the composer's available height. Bound the
 composer against the stationary space below the header inside
@@ -443,6 +446,13 @@ Before you write a new one, ask:
    positioning (`bottom: windowHeight - anchor.y + gap`) and skip the
    `contentSize` round-trip entirely. **But only if the height is genuinely
    bounded**. Verify before you commit.
+6. **Can the content change size after the panel paints, and does the panel
+   sit above its anchor?** Hold it by its bottom edge with `holdSurfaceEdge`
+   and `surfaceFrameStyles` from `components/ui/anchor.ts`. Native delivers
+   `onLayout` after the frame that shows the new size, so a panel placed by
+   `top` paints over its anchor until the next placement lands, about 150 ms
+   on Android. Web hides this because React commits the resize and the
+   re-placement in one task.
 
 Then copy the closest canonical file and trim.
 
diff --git a/docs/forge-providers.md b/docs/forge-providers.md
index f69c7eb64a..2d31eaef2f 100644
--- a/docs/forge-providers.md
+++ b/docs/forge-providers.md
@@ -97,19 +97,15 @@ Register the adapter in `defaultForgeRegistry` with:
 - `matchesHost` from manifest `cloudHosts`
 - `probeHost` when self-hosted/Enterprise detection is supported
 
-Current change-request lookup uses two identities deliberately:
+Current change-request lookup matches the branch and repository for both open and
+terminal requests. Prefer an open request, then a terminal request at the local
+HEAD, then the most recently updated terminal request. A reused branch can show
+its previous request until a new one opens. Auto-archive separately requires an
+observed open-to-merged transition and a fresh exact match between checkout HEAD
+and the PR head, along with the existing workspace safety checks.
 
-- An open PR/MR belongs to the checkout when its head branch and head repository
-  match. Its remote head SHA may differ because the checkout can be ahead,
-  behind, or contain commits that have not been pushed yet.
-- A merged or closed PR/MR belongs to the checkout only when its recorded head
-  SHA exactly matches the checkout's current `HEAD`. Branch names are reusable;
-  selecting the newest terminal request by branch alone can silently attach an
-  old promotion or feature request to new work.
-
-Thread the checkout head SHA through adapter cache and poll identities as well
-as the lookup itself. Otherwise a commit made on the same branch can inherit the
-previous commit's cached terminal status until the cache expires.
+Keep checkout HEAD in adapter cache and poll identities so checkout changes
+refresh the facts used by archive eligibility.
 
 Cloud hosts in the manifest are a bounded public-host list, not a self-host
 allowlist. Self-hosted detection is a trust gate: Paseo only talks to a forge
@@ -125,7 +121,8 @@ rendering stack:
 `acme.ts` exports a `ClientForgeLogicModule`:
 
 - `id`
-- optional `urlGrammar` (including `referencePaths` for composer auto-attachment)
+- optional `urlGrammar` (including `referencePaths` for composer auto-attachment
+  and Markdown shorthand references)
 - optional `facts` registration (schema, merge-capability, native-check fallbacks)
 
 `acme.view.tsx` exports a `ClientForgeViewModule`:
@@ -212,6 +209,12 @@ are stale, run `npm run build:server`.
   neutral extractor matches the pasted host and full repository path against
   the current remote before it invokes cwd-routed forge search. Do not add a
   central forge switch or guess a self-hosted Gitea-family brand from URL shape.
+- Shorthand references in rendered Markdown (`#12`, GitLab and Gitea `!12`,
+  cross-repository `owner/repo#12`) come from the `sigil` on each
+  `referencePaths` entry. Leave `sigil` off a kind the forge does not link in
+  prose: GitHub has no `!`, and its `#` targets `/issues/`, which GitHub
+  redirects to the pull request. `packages/app/src/git/forge-shorthand` builds
+  the recognition pattern from the workspace descriptor's forge and remote.
 - GitLab pipeline status constants belong to the GitLab adapter/client module,
   not protocol.
 - GitLab `manual` jobs need `allow_failure` to distinguish optional gray jobs
diff --git a/docs/glossary.md b/docs/glossary.md
index c7fd1398c5..a6ff393c6a 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -28,6 +28,7 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **Workspace-owned state** — Per-workspace state that never leaks to a same-`cwd` sibling: tabs, agents, terminals, panes, title, plus review drafts, diff-mode overrides, composer attachments, and file-explorer open/expand state. Keyed by `workspaceId` (`cwd` only as a fallback for old payloads). See [architecture.md](architecture.md#right-sidebar-boundary-directory-backed-vs-workspace-owned).
 - **Last prompt** — Sidebar workspace sort by the most recent human prompt recorded by an agent in that workspace, including archived agents. Agent output, agent-to-agent messages, scheduled prompts, and opening a workspace do not count. A workspace without a human prompt uses its creation time.
 - **Workspace status bucket** — Aggregate activity signal for a workspace row. Same-`cwd` workspaces intentionally share agent and terminal status buckets, while tab, agent, and terminal visibility remains scoped by `workspaceId`.
+- **Background agent** — An agent hidden from default discovery and from app surfaces that announce agents: tabs, the subagent track, agent lists, workspace status and attention. It is otherwise an ordinary durable agent, addressable by id. An agent is effectively background when it or its workspace is background. Fixed at creation. Code: `background` on `AgentSnapshotPayload` and `create_agent_request`. See [agent-lifecycle.md](agent-lifecycle.md#background-visibility). Don't confuse with background work (provider shells and monitors) or the daemon's private internal helpers, which are never public ([agent-lifecycle.md](agent-lifecycle.md#private-daemon-helpers)).
 - **Agent session** — One running instance of an agent inside a workspace (one provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Moving toward this as the canonical term over "Agent". Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`).
 - **Session** — Two senses: (a) per-client connection to a daemon, internal; (b) user-facing agent session, see **Agent session**. Code: `Session` (`packages/server/src/server/session.ts`) for (a). Don't confuse with: provider-side agent session log.
 - **Profile** — Internal name for the persisted shape of a host. Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Never user-facing. Three other things are called "profile" in this codebase, so always qualify: **Agent profile**, **Terminal profile**, and the provider aliases in [custom-providers.md](custom-providers.md). Bare "profile" is forbidden in UI copy.
diff --git a/docs/hover.md b/docs/hover.md
index fe8b539edc..9d523be064 100644
--- a/docs/hover.md
+++ b/docs/hover.md
@@ -135,7 +135,7 @@ Heuristic: if your hover state is going to be `useState`'d and read by anything
 
 Sometimes the revealed content can't live inside the trigger — a hover card portals into a different layer, a tooltip floats above other content, a popover renders into a `Portal`. There's a real visual gap the user has to cross with the cursor.
 
-For a card whose content the user can point at or press, use `HoverCard` (`packages/app/src/components/ui/hover-card.tsx`). It is built on `useHoverSafeZone` (`packages/app/src/hooks/use-hover-safe-zone.ts`), which computes a rectangular "bridge" across the gap between the trigger and the content, whether the card sits beside, above, or below the trigger. While the pointer is inside trigger, content, or the bridge, the card stays open. A short grace timer absorbs jitter at the edges. `Tooltip` takes no pointer events and closes as soon as the pointer leaves the trigger. If the trigger has no focusable child, give `HoverCardTrigger` `focusable` and an accessible label so keyboard users can open the same content.
+For a card whose content the user can point at or press, use `HoverCard` (`packages/app/src/components/ui/hover-card.tsx`). It is built on `useHoverSafeZone` (`packages/app/src/hooks/use-hover-safe-zone.ts`), which computes a rectangular "bridge" across the gap between the trigger and the content, whether the card sits beside, above, or below the trigger. While the pointer is inside trigger, content, or the bridge, the card stays open. A short grace timer absorbs jitter at the edges. Only one card per overlay layer is open: pointing at another trigger replaces the open card at once, so a sweep down a list never shows two cards or leaves one behind. `Tooltip` takes no pointer events and closes as soon as the pointer leaves the trigger. If the trigger has no focusable child, give `HoverCardTrigger` `focusable` and an accessible label so keyboard users can open the same content.
 
 Don't roll your own. The math is annoying, the edge cases (pointer leaves window, drag in progress, content unmounts) are subtle, and we already paid for the hook.
 
diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md
new file mode 100644
index 0000000000..2c1045eb54
--- /dev/null
+++ b/docs/keyboard-shortcuts.md
@@ -0,0 +1,93 @@
+# Keyboard shortcuts
+
+Define shortcuts in [the shared binding table](../packages/app/src/keyboard/keyboard-shortcuts.ts). Platforms contribute key sources, not separate action maps, so matching and user rebinds stay consistent across runtimes. Add a shortcut through a binding; add platform support through a key source.
+
+## Badges and routing
+
+Routing runs whenever the app mounts its key sources, independently of layout.
+Use `useHardwareKeyboardPresent()` for hints and the Shortcuts settings section.
+iOS reads `GCKeyboard.coalesced` and connection notifications. Android watches input
+devices and hardware keyboard configuration. Web starts with a fine hover pointer and recognizes the first modified
+keydown, including on touch devices. Compact Electron keeps its bindings.
+
+Keyboard navigation needs the sidebar's filtered workspace model even when its visual
+panel is hidden. Retain that model while keyboard navigation is active; gating it on
+panel visibility leaves number shortcuts with no targets after a compact startup.
+
+Composer send-key customization remains a separate capability. Native retains its
+existing Return submission path; advertising its web-only customization would expose
+settings the native composer does not implement.
+
+## Native sources
+
+Use the iOS window press stream for hardware keys. `UIKeyCommand` only takes keys
+that must bypass the focused text control: composer Return and the top overlay's
+Enter and arrows. Keep the stream as the sole shortcut emitter: a command-owned
+press is still observed by the window.
+
+The source spike used an iPad Pro 11-inch (M4) simulator on iOS 18.6 with a
+`UITextView` first responder. Both `UIWindow.sendEvent` and the root controller's
+`pressesBegan` received Cmd+B, Cmd+P and Escape. With Escape registered as a
+`UIKeyCommand`, the window observed it and the command handler also ran.
+
+Simulator reserves Cmd+K for Toggle Software Keyboard. Injecting it produced
+HID 184 with empty characters rather than K; plain K, Cmd+B and Cmd+P arrived
+normally. Keep Simulator input capture off: Send Keyboard Input to Device
+prevented synthetic AppleScript input from arriving, including plain text.
+For simulator QA, use Cmd+B/P to check delivery and rebind the command center to
+Cmd+J to check toggle and rebind behavior. Cmd+K delivery needs a physical iPad.
+Simulator also reserves Cmd+1…4, Cmd+Shift+A and Cmd+comma. Exercise those actions
+through rebinds. For numeric injection, use AppleScript physical key codes (for example
+25 for 9); `keystroke "9"` did not deliver a digit in the QA session.
+Simulator exposes a virtual `GCKeyboard` even with Connect Hardware Keyboard off.
+Verify the iOS absence case on a physical iPhone.
+
+Never register Backspace: it would take deletion away from text fields. Changes
+to the native module require a native rebuild; an over-the-air JavaScript update
+cannot deliver them.
+
+## Overlay ownership
+
+Register keyboard handling with `useOverlayRegistration` from `@/keyboard`.
+Pass the surface's open state, layer, handled keys and `onKeyDown`. The highest
+layer gets first refusal; the latest registration wins a tie. Native registration
+does not need a DOM ref. Web adds focus trapping and restoration through its adapter.
+
+Capture a global overlay’s layer in state for its opening lifetime. Memo caches can
+be discarded or removed by React Compiler; recomputing against the registry lets an
+open modal rise above its own children and creates competing focus traps.
+
+Declare Enter and arrow keys only while the surface owns them. Native sources
+use the top overlay's declarations to take those keys before text controls edit.
+Backspace stays with the focused input. Composition confirmation must not select
+an overlay row or submit the composer.
+
+Android modals have their own windows. Observe them through React Native's
+`ExtraWindowEventListener` as well as the activity window. The dev client bypasses
+Expo's root-container handler, so an activity root-view wrapper misses presses.
+A modal can forward an unhandled event into the activity window. Observe the event
+once across that nested delivery without retaining recycled Android `KeyEvent`s.
+Keep an overlay-owned press consumed through key-up, even if its key-down closes
+the overlay; otherwise the modal's default Escape handler can close a second layer.
+
+iOS scene startup installs the observing window after Expo creates its root view.
+Keep that integration in the hardware keyboard module's config plugin. Its window
+owns both the press stream and the text-control key commands, including above modals.
+
+## Focus scopes
+
+The composer and terminal declare focus with `useKeyboardFocusSurface`. Native
+scope derives from those declarations and command-center state. Releasing an old
+surface must not clear a newer owner's declaration during a tab switch. Web keeps
+its DOM-derived scope.
+
+Escape interrupts an agent only in the message input or an unclaimed surface.
+A focused terminal excludes that binding. The source leaves terminal Escape alone;
+terminal Escape/Ctrl forwarding is a separate feature.
+
+## Keys shared with text editing
+
+A binding on a key the platform already uses for editing, such as Cmd/Ctrl+Z for
+workspace archive undo, declares `editable: false` and registers its handler with
+`isActive` true only while it has work. An inactive handler leaves the key
+unhandled, so the pipeline skips `preventDefault` and the platform's own undo runs.
diff --git a/docs/markdown-renderer.md b/docs/markdown-renderer.md
index d2508f0004..11b9f09405 100644
--- a/docs/markdown-renderer.md
+++ b/docs/markdown-renderer.md
@@ -10,9 +10,9 @@ Every block is separated by one gap, `density.blockGap`: 12 on compact layouts,
 
 ## Links and images
 
-Workspace file links use the shared file-link resolver. The workspace supplies its client, root and open-file action once; chat can supply the agent's more specific context. URLs use the same link press path. Recognized inline-code paths stay tappable. The library callback carries the tapped occurrence’s syntax context. Preserve it when opening files: explicit Markdown links decode URL escapes, while recognized inline-code paths preserve literal percent characters and use suffix lookup. Identical URL strings in different occurrences must stay distinct. Explicit absolute workspace links receive a relative hover title; existing authored titles remain intact.
+Workspace file links use the shared file-link resolver. The workspace supplies its client, root and open-file action once; chat can supply the agent's more specific context. URLs use the same link press path. Recognized inline-code paths stay tappable. The library callback carries the tapped occurrence’s syntax context. Preserve it when opening files: explicit Markdown links decode URL escapes, while recognized inline-code paths preserve literal percent characters and use suffix lookup. Identical URL strings in different occurrences must stay distinct. Explicit absolute workspace links receive a relative hover title; existing authored titles remain intact. Inside a workspace, forge references such as `#12` and `owner/repo#12` are recognized in prose (not code) and open the workspace forge; the reference pattern comes before path recognition so `group/project#12` is not read as a path. See [forge providers](forge-providers.md#gotchas).
 
-Resolve workspace image paths over the existing session RPC, then give the library a cached native file URL or web blob URL. HTTP(S) images pass through unchanged. This preserves relay, SSH and local socket connections, which do not expose a daemon HTTP endpoint. Each mounted renderer owns its image acquisition identity, so a later reply reads a rewritten path again while the earlier mounted reply retains its snapshot. Image taps open the attachment lightbox. File previews resolve relative images against the Markdown file's directory. An image alone on its line becomes its own paragraph before the library sees it, so it renders as a block on every platform; the library only treats sole-child paragraph images as blocks, and with hard soft breaks every newline is a break node, which left own-line images inline on iOS and web. Images that share a line with text stay inline.
+Resolve workspace image paths over the existing session RPC, then give the library a cached native file URL or web blob URL. HTTP(S) images pass through unchanged. This preserves relay, SSH and local socket connections, which do not expose a daemon HTTP endpoint. Each mounted renderer owns its image acquisition identity, so a later reply reads a rewritten path again while the earlier mounted reply retains its snapshot. Image taps open the attachment lightbox. File previews resolve relative images against the Markdown file's directory. An image alone on its line becomes its own paragraph before the library sees it, so it renders as a block on every platform; the library only treats sole-child paragraph images as blocks, and with hard soft breaks every newline is a break node, which left own-line images inline on iOS and web. Images that share a line with text stay inline at line height and keep their aspect ratio. A linked image counts as an image, so review-bot badges such as `[![Retrigger](badge.svg)](url) Confidence` stay inline on web; the library's web renderer only checked direct paragraph children, so it rendered them as full-width block images (local patch in `patches/react-native-enriched-markdown+*.patch`).
 
 ## Engine constraints
 
@@ -26,6 +26,8 @@ Native code blocks use the library's copy control and compiled grammars. Web cod
 
 The package patch also keeps overflowing native horizontal blocks in control of their drags: Android claims parent interception at touch-down and releases it for vertical drags so the chat list can scroll; iOS keeps its scroll recognizer active for outward drags at the leading edge. This prevents compact sidebar pans from taking block scrolling without changing sidebar swipes on prose or non-overflowing blocks. Native changes require a client rebuild.
 
+On iOS a newly mounted Markdown view paints empty for a frame or more after it is laid out at its measured height: the library parses even a view's first content on a background queue and applies it in a later main-queue turn. Expanding a turn in chat therefore shows its rows in place with the text arriving a frame later (165 ms when the mount keeps the main thread busy). Android paints the text in the first frame. Rendering a view's first content synchronously fixes the frame but costs frame time when a fling mounts history rows, so the app keeps the library's behavior until [enriched-markdown #1131](https://github.com/software-mansion/enriched-markdown/issues/1131) is resolved.
+
 Android measurements use a size-only, 512-entry LRU across view unmounts, matching the library’s existing iOS cache. Scrolling back through history can reuse layout sizes without parsing those rows again. Content, layout props and width identify each entry; font-scale changes and native layout invalidation discard affected sizes. The cache retains no views or spans.
 
 The library determines how incomplete Markdown appears during streaming. Completed text uses the same component and engine as history. Find and scroll-to-message address source message ids; selection-copy understands semantic HTML and the web code component's copy metadata.
diff --git a/docs/menus.md b/docs/menus.md
index 590def2b33..3e29e13ac3 100644
--- a/docs/menus.md
+++ b/docs/menus.md
@@ -226,7 +226,8 @@ its own.
   inactive. An async action can navigate before its menu closes; a hidden panel must not leave a
   portal backdrop blocking the destination. On web the chat suspends one commit after it goes
   inactive, and that inactive commit is where the surface unmounts.
-- Anchoring, flipping, and edge clamping live in `components/ui/anchor.ts`, shared with the hover
-  card, and are unit-tested. Fix positioning bugs there, not at a call site.
+- Anchoring, flipping, edge clamping, and capping a surface's width to the display live in
+  `components/ui/anchor.ts`, shared with the hover card, and are unit-tested. Clamping moves a
+  surface but cannot shrink it, so the width cap is what keeps a wide menu on a narrow screen. Fix positioning bugs there, not at a call site.
 - Everything else about floating surfaces on Android — Portal/Modal escape, lifecycle gates,
   status-bar offset, the open flash — is in [floating-panels.md](floating-panels.md).
diff --git a/docs/mobile-panels.md b/docs/mobile-panels.md
index 3301b4b60a..21849788d2 100644
--- a/docs/mobile-panels.md
+++ b/docs/mobile-panels.md
@@ -9,6 +9,10 @@ Compact layouts have three mutually exclusive destinations:
 They are one interaction, not two independent drawers. The implementation lives in
 `packages/app/src/mobile-panels/`.
 
+Wide layouts reuse `agent-list` for the navigation overlay. When the left dock is collapsed or
+yields its width, a touch swipe reveals the same sidebar over the workspace at the resolved sidebar
+width. The workspace does not move, and the saved dock preference does not change.
+
 ## Ownership
 
 React/Zustand owns the durable intent:
@@ -23,6 +27,12 @@ interface MobilePanelSelection {
 Every semantic target change increments `revision`. Repeating the current target is idempotent.
 Compact panel selection is not persisted; a cold start begins at `agent`.
 
+Only an overlay sidebar holds `agent-list`, and only a compact layout holds `file-explorer`. App
+chrome publishes the layout (compact or wide, and the left sidebar presentation `overlay`, `dock`, or
+`hidden`) to `panel-store`, which drops any target the layout does not present. A stale
+`agent-list` would reopen the overlay on the next collapse; a stale `file-explorer` after widening
+would block the navigation swipe, which begins only from `agent`.
+
 The UI worklet owns transient motion:
 
 - one normalized position (`-1` left, `0` center, `1` right)
@@ -32,8 +42,10 @@ The UI worklet owns transient motion:
 
 React publishes the active panel only when the canonical target and the UI-thread position agree at
 the final anchor. Retained content never observes gesture previews, progress, or an unsettled target.
-The gesture hosts stay mounted. The Gesture Handler web patch keeps initially disabled hosts
-from capturing paragraph pointers; that capture confines browser selection to its starting paragraph.
+The gesture hosts stay mounted. A pointer capture on a paragraph confines browser selection to that
+paragraph, so the Gesture Handler web patch keeps it off: initially disabled hosts register no
+pointer listeners, and an enabled host captures only a pointer its handler still tracks after
+pointer-down. The touch-only navigation pans fail a mouse at pointer-down and never capture it.
 Native worklets own overlay opacity and pointer events while
 React owns settled panel activity and accessibility. Keep hidden native overlays laid out: collapsing
 their scroll ranges makes Android spring retained offsets back to zero during touch cancellation or
@@ -43,8 +55,11 @@ appearance keys; see [Unistyles appearance boundaries](unistyles.md#runtime-them
 
 ## Why one position
 
-Both transforms and both backdrop opacities are derived from the same normalized position. Window
-width is only a projection input. Rotation changes the projection, not the panel state.
+Both transforms and both backdrop opacities are derived from the same normalized position. Panel
+width is only a projection input: the window width on the right, and on the left the width
+`MobilePanelsProvider` resolves (the full window on compact layouts, the saved sidebar width
+clamped to the viewport on wide ones). The dock, the overlay, and their gestures read that one
+value. Rotation changes the projection, not the panel state.
 
 This makes these invalid states unrepresentable:
 
@@ -62,7 +77,9 @@ A gesture captures the current revision when it becomes active. Per-frame update
 while that revision still owns the gesture.
 
 When a React command arrives during a drag, its newer revision clears gesture ownership and starts
-motion toward the new target. The older gesture's remaining updates and finish callback are ignored.
+motion toward its target, even an unchanged one: docking mid-swipe keeps `agent` and still returns
+the dragged position to its anchor. The older gesture's remaining updates and finish callback are
+ignored.
 Canceled gestures return to the latest canonical target. A successful gesture starts its finishing
 motion immediately; the matching React command adopts that motion instead of restarting it. Position
 settlement and command acceptance may arrive in either order. Activity changes after both agree on
@@ -80,6 +97,12 @@ definition, no longer eligible to begin.
 
 - Callers request semantic targets through `panel-store`; they never write shared values.
 - Gesture behavior comes from the four explicit hooks in `mobile-panels/gestures.ts`.
+- Navigation gestures accept touch pointers only. Mouse and pen fail at touch-down, so dragging a
+  mouse to select text on a hybrid laptop never moves a panel. Browsers without a touch screen
+  (`hooks/pointer-capabilities`) never enable them.
+- Phone web opens a drawer only from the 32px edge it slides in from, so interior swipes stay with
+  terminals, code blocks, and diff scrollers. Native drawers and the wide overlay open from anywhere.
+  Horizontal-scroll ownership and the open-gesture blocker still take precedence.
 - A focused interactive surface may block panel-opening gestures through
   `useBlockMobilePanelOpenGestures`. Register only while the conflicting interaction is active and
   unregister when the surface is hidden or unfocused. The blocker never disables gestures that close
@@ -87,11 +110,17 @@ definition, no longer eligible to begin.
 - Keep `SidebarModelProvider` outside `MobileGestureWrapper`. The provider shares sidebar derivation
   across consumers, while Gesture Handler requires the wrapper's direct child to be a native `View`
   so its injected `collapsable={false}` reaches Android/Fabric.
-- Mobile sidebars render through `MobilePanelOverlay`; do not duplicate overlay lifecycle or motion
-  styles in sidebar components.
-- The desktop left sidebar is retained too. App chrome owns separate mounted and visible decisions:
-  closing it or yielding its width marks it inactive and applies `display: none` without conditionally
-  removing the sidebar tree.
+- Sidebars render through `MobilePanelOverlay`; do not duplicate overlay lifecycle or motion styles
+  in sidebar components. The wide left sidebar keeps the same content and gesture hosts when switching
+  between dock and overlay. App chrome owns mounting and presentation; settled panel activity owns
+  overlay work. A hidden dock is inactive with `display: none`; the sidebar tree stays mounted. Keep
+  the native overlay laid out while hidden, as on compact layouts. Give the switching host no
+  Reanimated layout props: a width keyed on the presentation reaches Android after React commits the
+  switch, and a lost update left the workspace at the dock width. The dock sizes to its content and
+  the overlay host fills the window.
+- The overlay's backdrop covers the whole window; safe-area padding applies to the sidebar and
+  workspace content only. It closes by swiping back, tapping the backdrop, or picking a destination:
+  every sidebar destination closes the overlay before it navigates.
 - Animated panel nodes use React Native static styles plus inline theme values. Do not attach
   Unistyles-generated styles to those nodes; Unistyles and Reanimated patching the same Fabric node
   has caused native crashes.
diff --git a/docs/mobile-testing.md b/docs/mobile-testing.md
index 903244e3d9..3dbea66676 100644
--- a/docs/mobile-testing.md
+++ b/docs/mobile-testing.md
@@ -452,18 +452,9 @@ Regular `View` components can safely use Unistyles dynamic styles — the confli
 
 ## Native Chat Stream Layout
 
-The native agent stream uses an inverted `FlatList`, so chat layout has three coordinate systems:
-
-- chronological stream order
-- strategy-ordered array order
-- native inverted cell visual order
-
 Do not compute stream neighbors, history/live-head seams, turn footer ownership, assistant block spacing, or tool sequence endings inside React render loops. Those policies live in `packages/app/src/agent-stream/layout.ts` and are unit-tested without React Native rendering.
 
-Platform-specific stream edges belong on `StreamStrategy`:
-
-- forward web uses the last history item as the history/live-head boundary and renders content before a footer
-- native inverted uses the first history item as the history/live-head boundary and compensates for inverted cell child order
+Platform-specific stream edges belong on `StreamStrategy`. Web and native both render in chronological order, so both use the last history item as the history/live-head boundary and render content before a footer.
 
 If a chat footer looks duplicated or appears above the assistant message on mobile, start with `packages/app/src/agent-stream/layout.test.ts`. Do not add a React Native renderer test for this class of bug; make the pure layout invariant fail first.
 
diff --git a/docs/native-text-selection.md b/docs/native-text-selection.md
index dd7edcd79c..fb04571451 100644
--- a/docs/native-text-selection.md
+++ b/docs/native-text-selection.md
@@ -2,15 +2,6 @@
 
 Keep completed assistant prose in one native text view so selection crosses paragraphs, headings and lists. The shared [Markdown renderer](markdown-renderer.md) owns that view.
 
-## Android inverted chat
-
-Keep selection visibility handling in `modules/paseo-scroll`. Android's visibility
-rectangles ignore list inversion. React Native decomposes Android's `scale: -1`
-into rotation with positive `scaleY`, so test the composed matrix when deciding
-whether those requests should move the viewport. Native tests must apply the
-list's transform through React Native's view manager; assigning `scaleY` directly
-misses that decomposition.
-
 ## Diagrams in lists and quotes
 
 Selection stops at a Mermaid diagram. Native extracts Mermaid fences into separate views because the library exposes no native block renderer override. A diagram inside a list or quote therefore appears outside that container, and its following prose starts a separate Markdown fragment.
diff --git a/docs/plugins.md b/docs/plugins.md
index ffae136cc6..d64e7ed150 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -118,7 +118,7 @@ appear in the plugin catalog. Editing one in development requires a daemon resta
 Directory, Git, and npm installs cannot use a built-in ID.
 
 A provider registration with `requiresConfiguration: true` participates only while its ID exists
-under `agents.providers`. Hoplite uses this for catalog opt-in. Add writes `{ "enabled": true }`
+under `agents.providers`. Hoplite and fx use this for catalog opt-in. Add writes `{ "enabled": true }`
 without `extends`, so it selects the bundled adapter. Remove deletes the config entry; setting
 `enabled: false` keeps the entry. The bundled JavaScript still loads at startup, but an absent
 provider does not enter executable resolution or catalog discovery.
@@ -357,9 +357,27 @@ keys are stored under a `param.` prefix; plugins never see it and may use any ke
 `openScreen` validates its input once (`parsePluginOpenScreenInput`); code past it trusts the
 params.
 
-RPC contracts validate inputs and outputs in both the app and plugin subprocess. `useRpc` returns a
-typed async function. Use the host-provided `@tanstack/react-query` for request state and caching;
-Paseo gives each plugin installation its own query client.
+RPC and subscription contracts validate inputs, outputs, and events in both the app and plugin
+subprocess. `useRpc` returns a typed async function. Use the host-provided `@tanstack/react-query`
+for request state and caching; Paseo gives each plugin installation its own query client.
+
+A subscription is a session-owned observation (`plugin-rpc` delivery family): the session that
+subscribed owns its lifetime, so release, disconnect, plugin stop, and reload need no plugin code.
+Each subscriber gets its own handler call in the subprocess; there is no fan-out or replay. The
+runtime buffers pushes until the session has sent `plugin.rpc.subscribe.response`, so a client
+never sees an event for an unknown subscription. The app installation's lifetime aborts every
+subscription its surfaces left open, and a reload replaces the installation, which resubscribes
+mounted hooks.
+
+The byte rule (a top-level `Uint8Array` is binary, a nested one is a validation error) is checked
+once per hop by `assertPluginWireValue`. Bytes ride plugin binary frames, opcodes `0x20`-`0x2f`
+(`packages/protocol/src/binary-frames/plugin.ts`); nothing on the path copies or re-encodes them,
+and `plugin-subscriptions.perf.e2e.test.ts` locks that. Keep it that way: never stringify a plugin
+payload for a log, and the client's bootstrap buffer holds bytes only until the first observer
+attaches. Binary outputs reach only clients that send `pluginBinaryPayloads`. A binary input
+frame (`0x22`) becomes a synthetic `plugin.rpc.invoke.request` and runs through the normal message
+path, so it is authorized like any other invoke. The author contract, including the native upload
+limit, is in [stream events from the daemon](../public-docs/plugins/reference.md#subscriptions).
 
 `usePaseo()` and the handler's `{ paseo }` context expose the same `PaseoApi`: projects,
 workspaces, agents, terminals, providers, and daemon config. They do not expose connection lifecycle.
@@ -456,6 +474,10 @@ path shape: a plugin can place a worktree several directories below the default
 Emit from the operation owner, not a client subscription. Provider history replay must not trigger
 live hooks. Notifications must not be awaited inside agent mutations: a handler can send a prompt
 or answer a permission through its own daemon session. Awaiting it there deadlocks that command.
+The same holds for a hook that runs inside an agent's lifecycle lane: an `agent.open.before` or
+`agent.create.before` hook that awaits a write to the agent being opened (`setMetadata`, `setLabels`,
+an option, model, thinking or mode change) waits on the open, which waits on the hook. The hooks
+reference tells plugin authors to start such a write without awaiting it.
 
 ## Contribute a provider
 
@@ -511,13 +533,21 @@ need no change. See [catalogue ownership](providers.md#provider-snapshot-refresh
 `send()` resolves after acceptance. Publish operation completion, prompt disposition, turn state,
 configuration, permissions, persistence, and complete timeline snapshots through `onEvent()`.
 Route messages, structured commands, steering, and command side effects through `session.prompt`.
-Provider settings are toggle/select data that Paseo renders in the composer. Keep private options in
-the opaque `ProviderSessionConfig.providerOptions` object on `session.open`.
-It contains the provider defaults and per-agent overrides merged by the daemon.
+A provider's configuration is the opaque `ProviderSessionConfig.providerOptions` object on
+`session.open`. It contains the provider defaults and per-agent overrides merged by the daemon.
 Validate and apply it inside the provider; core does not know your option shape.
 See [provider options](custom-providers.md#provider-options) for configuration and
 merge semantics.
 
+The provider draws some of those keys in the composer by reporting `controls` and the values it runs
+(`providerOptions`) in `session.config`. A running-agent change arrives as
+`session.configure` with `changes.providerOptions` and follows the same apply-or-throw contract as
+built-in providers ([options flow](providers.md#options-flow)). `PluginAgentSession` in
+`packages/server/src/server/agent/plugin-provider.ts` is that adapter. A provider still reporting
+`settings` is read through `plugin-provider-options.ts`, which turns each setting into a control and
+its value into an option and is sent both shapes in `session.configure`; delete it with
+`COMPAT(plugin-provider-settings)`. The ACP shim still reports `settings`.
+
 Providers add an optional veto to daemon baseline cleanup through the per-session
 [runtime safety query](../public-docs/plugins/providers.md#permit-idle-runtime-cleanup).
 The daemon calls the same `AgentSession.canStopRuntime()` interface for built-ins and plugins;
@@ -552,6 +582,13 @@ Register a usage source from `index.server.ts` with `server.registerUsageSource(
 
 When the host’s **Check usage** switch is off, the daemon rejects usage requests before discovery, without reading logins or calling vendors. Otherwise, the daemon calls discovery for `usage.list_reports`; the client gates this RPC on `server_info.features.usageSources`. The old `provider.usage.list` RPC maps discovered reports for older clients.
 
+## Replace sidebar content
+
+The sidebar view slot is global across hosts, while header and footer contributions retain their
+host selection. The slot owns selection loading, fallback and the error boundary; the plugin owns
+its layout. This keeps plugin failures from removing navigation or recovery controls. The
+[sidebar view guide](../public-docs/plugins/sidebar-views.md) owns the author API.
+
 ## Contribute sidebar items
 
 Sidebar header and footer items are plugin components, not descriptors. The
@@ -636,6 +673,154 @@ Mounted surfaces and command invocations have shorter API lifetimes.
 Keep the client entry synchronous: return its cleanup function immediately and start asynchronous
 work inside it. See the maintained [composer pill example](../plugin-examples/local-plugin/client/main.tsx).
 
+## Contribute composer items
+
+`addComposerItem` mounts a plugin component in the agent, draft and New workspace composers. The
+public contract is the [composer items reference](../public-docs/plugins/reference.md#composer-items).
+
+A plugin reads one `ComposerModel` (`packages/app/src/composer/model.ts`): state, subscribe and
+commands. `toPluginComposer` (`packages/app/src/plugins/composer-items/`) turns its state into the
+`PluginComposer` an item reads, and the host never learns which kind of composer it got. Two
+implementations provide it:
+
+- A running agent's `agentComposer(serverId, agentId)` (`composer/agent-composer/`). It exists
+  without a mounted tab: the prompt and attachments are the agent's draft in the draft store, the
+  settings are the session store's agent, and `model` and `thinking` resolve through the provider
+  catalog with `resolveAgentModelSelection`, the picker's own function, so a read equals what the
+  picker shows. The model loads the catalog itself and resolves with no models until it lands, as the picker does,
+  so a read never differs from what the picker shows. While anything watches the model it holds a
+  `QueryObserver` on the agent's catalog: that is what lets reconnect repair, which refetches only
+  active queries, refresh a catalog nobody has a picker open for, and retry one that failed.
+  `PluginComposersSource.subscribe(selector, listener)` is what holds it for `useComposers`, so
+  the subscription must go through the model's own `subscribe`. Watching again after the catalog
+  was invalidated or failed refetches it, and a read with no watcher starts one deduplicated
+  refresh and shows the cached catalog until it lands. The model keeps one pair of store
+  subscriptions however many components watch it. It is shared for as long as its agent is in the
+  session and not archived, so a command a plugin saved keeps reaching the composer a later tab
+  mounts; it is dropped when the agent is gone or archived and nothing watches it or has one
+  mounted, checked on session changes and when the last holder lets go. The mounted
+  `AgentControls` plugs its input in with `attachInput` so `insertText` lands at the cursor.
+  Without a live input the model writes the stored prompt with `replaceDraftText`, which also asks
+  a mounted input to show it. A workspace the user left stays mounted, display none. Web
+  drops the input ref there; native keeps the input, with a stale cursor and selection.
+  `ComposerInput.isLive()` is how the model tells: it needs the ref and a retained panel that is
+  showing (`useRetainedPanelActive`). Closing a root agent's tab archives
+  it, so a running agent with no mounted composer at all only exists as a subagent whose tab was
+  closed. The daemon does not check `setModel` and `setThinking` against a catalog; the provider
+  decides and its refusal rejects the call.
+- A draft or New workspace screen's `composerModelFromHalves`, an adapter over the two contexts
+  in `composer/session.tsx`: `Composer` provides `ComposerInput` (prompt, attachments),
+  `DraftAgentControls` provides `ComposerAgent` (settings), and the adapter enforces the lock.
+
+`focus` differs per implementation on purpose. A running agent's model reveals the agent with
+`navigateToAgent` when `ComposerInput.isRevealed()` is false, and holds one pending request until an
+input that is revealed attaches. `isRevealed` is stricter than `isLive`: a compact overlay panel and
+an unfocused pane leave the input live but unable to take the keyboard, so the agent is revealed
+first, which also moves pane focus. `Composer` makes `revealed` part of `ComposerInput`, so a change
+re-runs `attachInput`, which is what tells the pending request the input is on screen. The draft
+half has nothing to navigate to and does not pull the user back to a draft they left, so it rejects
+when not revealed. Sheets, menus, pickers and modals the composer opens over itself do not count
+against `revealed`: `takeInputFocus` closes them through the `OverlayDismissalScope` in
+`components/ui/overlay-dismissal.tsx`, and places the cursor only after the commit that removes
+them. A web modal hands focus back to the button that opened it in that commit, so placing the
+cursor earlier loses it. The overlay primitives register while open: every controlled bottom
+sheet through `useIsolatedBottomSheetVisibility`, `AdaptiveModalSheet`'s desktop dialog, `MenuRoot`,
+`Combobox`, and `Modal` through its `onRequestClose`. Their close must close; a surface built on none
+of them must call `useDismissibleOverlay`. Overlapping requests share each overlay's close, and the
+latest request places the cursor while the earlier ones settle with it. A native input reports
+focus synchronously and refuses it while not editable, such as during dictation, so the native
+branch checks `isFocused()` instead of trusting the call. The agent panel opens the scope around its whole chat
+because the tracks above the composer render outside `Composer`, and the composer's own scope
+joins it. `toPluginComposer` clears the Command Center's focus restore, which would
+otherwise take the cursor back when the Command Center closes. Native `focus` opens the keyboard, so
+the app's web-only `focusInput` stays separate and plugins go through `takeInputFocus`.
+
+`ComposerAgent` stays for the built-in controls. Add a capability to the `ComposerModel`, both
+implementations and `toPluginComposer`; never branch on `context` in the host.
+
+`useComposers` and `composers()` reach an agent's model by reference (`plugins/composer-items/source.ts`):
+`PluginInstallationProvider` provides the plugin's source to every surface, and
+`createPluginCapabilities` puts `composers` on every command context. `{ focused: true }` is the
+agent Command Center registration hands to agent items, published through `plugins/focused-agent.ts`
+(null outside a workspace route). The source reads that module, not the navigation or layout
+stores, so the plugin runtime does not import them. The remembered workspace selection is
+navigation restore state and is not the focused agent. The query-cache subscriptions react to
+`updated` events only: a `useQuery` in another component's render announces `added`, and a
+subscriber that updates then triggers React's "update a component while rendering a different one"
+warning.
+
+Plugin `Toggle`, `Select` and `Action`, the thinking select and provider option controls all
+render through `ComposerControl` (`packages/app/src/composer/agent-controls/composer-control.tsx`),
+a toolbar icon or a row in the overflow sheet. Model and mode stay specialized but share its trigger,
+density and overflow. Plugin items count in the density presence in `layout.ts`, so a composer
+condenses to make room for them. A custom component renders wherever its item is placed, and an
+item that renders nothing still counts for density; there is no registration for either.
+
+A command runs against the owner's current state, not the render that built the callback. The
+draft's form (`openAgentForm`) and options (`openDraftOptions`) are plain stores for that reason,
+and `draftComposerAgent` rejects a provider the host does not offer. It passes a model id to the form
+as the picker does, with no catalog check; for a running agent the provider decides. `ComposerControl` owns the pending state and the error toast for callbacks that
+return a promise.
+
+The overflow sheet's content portals to the app root, away from the composer. Pass
+`useComposerSheetBridge()` as the sheet's `contextBridge`, or `useComposer()` returns nothing and
+the sheet draws no plugin rows.
+
+## Contribute New workspace items
+
+`addNewWorkspaceItem` mounts a plugin component on the New workspace screen. The public contract
+is the [New workspace items reference](../public-docs/plugins/reference.md#new-workspace-items).
+
+The screen's choices that a plugin may change live in one plain store,
+`createNewWorkspaceSetup` (`packages/app/src/screens/new-workspace/setup-model.ts`): the base
+picker selection, the manual isolation, the branch name and the workspace metadata. The pickers and
+the plugin commands write to it, so a command sees what an earlier command left. Project and host
+stay in the screen's hooks (`useNewWorkspaceHostSelector` reconciles them against each other), and
+they are read-only to plugins; a command that switched them would unmount the item that called it.
+
+The store is built in the render that creates the screen, with what the screen derives from its
+hooks (the lock, the project, whether the project can make worktrees, whether the host supports
+metadata), so a command is valid from a child's first effect, which runs before the screen's own
+effects. `syncInputs` refreshes those inputs in a layout effect on every commit, and commands read
+them when they run, never from the render that built them. The pickers and the commands pick
+through the same `chooseBase` and `chooseIsolation`, so a plugin command has the effects of a
+pick; the screen injects those effects when it builds the store (syncing the picker's PR attachment,
+remembering the isolation), so a command from a mount effect does the same as a click. Closing the
+picker stays in the picker's own handler. Add a capability by extending the store;
+do not read screen state from a plugin component.
+
+The item host (`PluginNewWorkspaceItems`) keys the items by `(serverId, project id)`, so a change of
+project or host remounts them. That is what keeps an item's own state and a `Combobox`'s cached
+results from outliving their project: the `Combobox` cannot tell that an author's inline `search`
+now means another project, because its identity changes every render. The store clears `branch`
+and `metadata` on the same change in `syncInputs`, and a remounted item's mount effect sets them
+again.
+
+An item's commands come from `setup.commandsFor({ serverId, projectId })`, bound to the target the
+item was mounted for. Once `syncInputs` reports another target they reject with a "moved" error, so
+a lookup that finishes after a project switch cannot write into the new project's choices. The
+reset only clears what was already written; this check covers what is written later. Rejecting, not
+ignoring, matches the lock: a command's promise resolves only when the change took effect.
+
+Known limit: an item that issues a command from `useLayoutEffect` on mount after a project or host
+switch runs before the screen's `syncInputs` layout effect, so its commands (bound to the new
+target) still see the previous target and reject as moved. This applies to a project switch as well as a host switch, since items
+remount per `(serverId, project id)`. Passive effects are not affected.
+
+`ensureWorkspace` sends the store's `branch` as `source.branchName` whenever the worktree cuts a
+new branch (`startsNewBranch`, which mirrors the daemon: anything but a checkout, including no base
+at all on a detached HEAD), and its `metadata` on `workspace.create` when it is not empty. The
+server uses `branchName ?? worktreeSlug` as the new branch. `baseRef.name` is the exact ref
+creation uses; `branchNameFromRef` is for labels only.
+
+Items render through `ComposerControl` with `surface="field"`: a `FieldTrigger` (a badge on
+desktop, a full-width field when compact) and the same pending state, error toast and list as the
+composer's controls. `ComposerControlLockProvider` carries the screen's lock to them. Plugin
+`Combobox` is a `select` item with `remoteSearch`: the app `Combobox` does not filter locally, and
+`PluginCombobox` (`plugins/react-native/composer-controls.tsx`) runs `search` through
+`useFetchQuery` with `dataShape: "list"`, which keeps the previous results while a newer query runs.
+`plugins/item-host.tsx` is the host shared by composer and New workspace items.
+
 ## Contribute timeline items
 
 Timeline transformers and renderers are client contributions. The daemon's canonical rows and
diff --git a/docs/providers.md b/docs/providers.md
index 1a43558ae3..fe3d58446a 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -30,6 +30,71 @@ at session startup. See [provider configuration](custom-providers.md#provider-op
 for defaults and merge rules, and the [SDK guide](../public-docs/sdk/provider-options.md)
 for native keys and examples.
 
+### Options flow
+
+`options` on the agent snapshot is the only option state. Controls describe how to draw an
+option and read `options`; they hold no value of their own. Any option can be read and set with
+or without a control.
+
+- **Create and resume.** The provider opens with the options it is given and emits nothing about
+  them while opening. `openOptionsPatch` carries every option the session ended up with that
+  differs from what it was given, including a setting nobody asked for (a native default such as
+  Cursor opening with Fast on). It is set before `createSession`/`resumeSession` resolves and the
+  daemon stores it before the agent is published. A reopened agent resumes that state, so a
+  native default the provider later changes does not follow. `options` on the snapshot is what
+  the session opened with, and afterwards it moves only through an apply or an `options_changed`.
+  Editing a provider default in `config.json` affects agents the next time they open.
+- **Live apply.** `applyOptions` receives the keys the patch touches, resolved against the
+  `config.json` defaults. A removal arrives as the default the key falls back to, or `null` when
+  there is none; the provider returns the setting to its own default if it can, or throws to
+  reject. A key the running session cannot apply (one the provider reads only when it opens) is
+  rejected too, so a stored option always describes what runs. Claude reads most options when it
+  starts its query, and replacing a started query would end its background work, so after the
+  first prompt only Fast can change. Codex fixes its approval policy and sandbox when the thread
+  starts, so it applies only `service_tier` and `plan_mode` live. A session with no
+  `applyOptions` rejects every patch; the daemon enforces this. The provider returns the options
+  it ended up with when they differ from the request. The daemon stores the patch and that
+  result in one step after the call resolves. Throwing rejects the whole patch and none of it is
+  stored. Emit nothing from inside the call. If the provider's own state moved before it refused,
+  it reports the moved values once as `options_changed` after the call has ended, because the
+  stored options must match what runs.
+- **One change at a time per agent.** `AgentManager` runs every option, model, thinking and mode
+  change inside the agent's lifecycle lane, the same queue that opens, reopens, closes and
+  archives it. `applyOptions`, `setModel`, `setThinkingOption` and `setMode` are never in flight
+  together on one session, and none of them overlaps an open or reopen. Providers do no
+  sequencing of their own: no queues, no "apply over the options as they are now" handling. A
+  change that arrives while another runs waits for it and then reads the agent's stored options
+  as that one left them.
+- **Old data converts in the agent manager.** Codex used to take `fast_mode`; it takes
+  `service_tier` now. `AgentManager` runs `convertLegacyOptions` (`option-controls.ts`) on an
+  agent's own options when it creates, resumes, imports, reloads or applies to it, and on draft
+  controls, before defaults merge and before anything is stored (`true` is `"fast"`, `false` is
+  `"default"`, and a `service_tier` in the same input wins). The manager converts for the adapter
+  behind the provider id, following `derivedFromProviderId`, so a custom provider with
+  `extends: "codex"` is converted too. Configured defaults convert in the provider registry. A
+  stored record keeps `fast_mode` until the agent is next opened or applied to, and is stored
+  converted from then on. Nothing past the manager sees `fast_mode` for Codex. Codex resolves
+  `"fast"` to the model's Fast tier and reports the id it runs through `openOptionsPatch` or the
+  `applyOptions` result like any other value. The `featureValues` to `options` fold is separate
+  and provider-agnostic; it stays at the protocol and legacy edges.
+- **Clients draw from the daemon's answer.** The app reads `controls` and `options` from the
+  agent snapshot for a running or closed agent. A draft and a profile form send everything they
+  would create with (seed, the provider's last-used control values once the provider has said it
+  still draws them, and the user's edits) in `provider.controls.list.request` and draw only what
+  comes back, so an alias such as a legacy Fast profile's `service_tier: "fast"` is resolved once,
+  by the daemon. A toggle shows over the last answer until its own answer arrives. The draft's
+  layers live in a plain model (`agent-controls/draft-options-model.ts`): applying a profile
+  replaces provider and options in one step, while choosing a provider by hand starts over. A
+  profile saves its stored options plus the form's edits, so options no control draws survive an
+  edit. A daemon without `server_info.features.providerOptionControls` sends `features` and
+  `featureValues`; `packages/client/src/compat/legacy-provider-options.ts` is the one place that
+  turns those into `controls` and `options` and back, so nothing in the app branches on it. A
+  create that carries options first lists the controls for its own provider, model, mode and
+  thinking level, since which options are controls differs by model, and sends those as
+  `featureValues`; callers do not prime anything.
+- **Provider-initiated changes.** A setting the provider changes on its own is an
+  `options_changed` event. The daemon stores and forwards it and does not push the old value back.
+
 Exact MCP preapproval is a separate daemon-owned contract. A new provider must fail
 closed for Hub unattended execution until it can approve one exact injected MCP
 server and tool identity without approving native tools.
@@ -89,7 +154,7 @@ OMP supports native Paseo host tools. The adapter registers the full caller-scop
 
 Pi RPC extension UI dialog requests (`select`, `input`, `editor`, `confirm`) are bridged into Paseo question permissions and answered with `extension_ui_response`. Pi extensions such as `ask_user` may chain dialogs: for example, a `select` can be followed by an optional-comment `input`. When an `ask_user` tool call declares `allowComment: true`, Paseo presents the selection and optional comment as one question permission, answers Pi's initial `select` immediately, then auto-answers the follow-up optional `input` with the comment the user already supplied (or an empty string). Preserve placeholders and optional/skip semantics for standalone optional inputs so the app can still distinguish "skip this optional input" from "cancel the whole dialog." Fire-and-forget extension UI requests such as notifications are intentionally ignored by the provider adapter unless Paseo grows first-class UI for them.
 
-OpenCode adapters target v1.14.46 and v2.0.10. V2 rejects binaries older than the tested 2.0.10 SDK at runtime selection. Runtime selection uses the configured command and environment. A recognized version is cached until provider configuration reload; a failed, timed-out, or unrecognized probe retains the v1 path and retries detection on the next operation. Load v2 code and materialize its plugin only after positive v2 selection; v1 sessions remain undecorated. Keep upstream SDK types inside the version-specific adapter. OpenCode owns storage migration; a missing native session must fail resume rather than create a replacement. V2 has no native archive/unarchive operation: archiving affects Paseo only. V1 retains native archiving.
+OpenCode adapters target v1.14.46 and v2.0.10. V2 rejects versions older than 2.0.10. Paseo selects an explicit server, then a healthy local registered service, then its own helper. It never stops a reused service. A local service loads the Paseo bridge from its watched plugin directory; sessions bind their own bridge credentials through OpenCode RPC. See [OpenCode with an existing v2 server](custom-providers.md#opencode-with-an-existing-v2-server) for setup and isolation limits. Load v2 code and materialize its plugin only after positive v2 selection; v1 sessions remain undecorated. Keep upstream SDK types inside the version-specific adapter. OpenCode owns storage migration; a missing native session must fail resume rather than create a replacement. V2 has no native archive/unarchive operation: archiving affects Paseo only. V1 retains native archiving.
 
 Use OpenCode v2 execution events to trigger turn completion, with active-state and durable-log reconciliation after admission, reconnect, and while a turn remains active. Do not use `session.wait`: a healthy turn exceeding Node's HTTP headers deadline produces a transport error while OpenCode keeps working. The live event feed has no replay, and shutdown interruption preserves the previous idle outcome, so the session snapshot alone cannot recover missed execution events. Quiet streams are healthy: v2 heartbeats are SSE comments, not application events.
 
@@ -115,7 +180,7 @@ Submitted user-message wire items carry the same Paseo ID in `messageId` and `cl
 
 Provider adapters must terminalize every transient timeline row before emitting the turn's terminal event. Codex may omit the completed `contextCompaction` item when a turn ends during compaction, so its adapter closes any pending root compaction before forwarding `turn_completed`, `turn_failed`, or `turn_canceled`. A terminal turn must never leave the client showing an operation as still loading.
 
-Draft metadata lookups should avoid creating provider sessions when the upstream provider has top-level APIs for that metadata. Prefer `AgentClient.fetchCatalog`, `listCommands`, or `listFeatures` over creating a scratch `AgentSession`; scratch sessions can show up as empty native sessions in provider import/history UIs. `fetchCatalog` is the single discovery API for models and modes — provider implementations may use one process, separate upstream calls, or static data internally, but callers outside the provider do not get separate runtime model/mode probes. Draft command listing and scratch-session feature listing require an explicit draft model. Do not resolve a default model through catalog discovery. A client-level `listFeatures` implementation may return features from an incomplete, model-less draft and owns which features are valid in that state.
+Draft metadata lookups should avoid creating provider sessions when the upstream provider has top-level APIs for that metadata. Prefer `AgentClient.fetchCatalog`, `listCommands`, or `listControls` over creating a scratch `AgentSession`; scratch sessions can show up as empty native sessions in provider import/history UIs. `fetchCatalog` is the single discovery API for models and modes — provider implementations may use one process, separate upstream calls, or static data internally, but callers outside the provider do not get separate runtime model/mode probes. Draft command listing and scratch-session control listing require an explicit draft model. Do not resolve a default model through catalog discovery. A client-level `listControls` implementation may return controls from an incomplete, model-less draft and owns which features are valid in that state. It returns `{ controls, options }`: the options a session opened from the draft would run with, so a value the provider resolves natively (an ACP select nobody set) shows in the draft the same way it would on the agent.
 
 Provider session import has its own contract. The picker calls `listImportableSessions` and receives rows only: provider handle, cwd, title, prompt previews, and last activity. Import calls `importSession({ providerHandleId, cwd })` for the selected row and must not call listing again. The provider returns the resumed session, storage config, persistence handle, and hydrated timeline for that one native session; `AgentManager.importProviderSession` seeds the daemon timeline and publishes the Paseo agent only after it is ready.
 
@@ -478,7 +543,7 @@ interface AgentSession {
   readonly provider: AgentProvider;
   readonly id: string | null;
   readonly capabilities: AgentCapabilityFlags;
-  readonly features?: AgentFeature[];
+  readonly controls?: AgentOptionControl[];
   run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
   startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{ turnId: string }>;
   steerActiveTurn?(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult>;
@@ -500,13 +565,15 @@ interface AgentSession {
   listCommands?(): Promise<AgentSlashCommand[]>;
   setModel?(modelId: string | null): Promise<void>;
   setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
-  setFeature?(featureId: string, value: unknown): Promise<void>;
+  applyOptions?(options: ProviderOptions): Promise<void>;
   tryHandleOutOfBand?(prompt: AgentPromptInput): {
     run(ctx: { emit: (event: AgentStreamEvent) => void }): Promise<void>;
   } | null;
 }
 ```
 
+`describePersistence()` returns a handle only once a new provider process could resume it. Reload, idle runtime collection and daemon restart resume whatever handle the agent stored; a stored agent without one starts a new session instead. When there is no handle, `AgentManager` stores `getRuntimeInfo().sessionId` as one, so that ID follows the same rule. Codex, for example, starts a thread when the agent is created but writes its rollout only at its first turn, and `thread/resume` fails for it until then, so its adapter reports neither ID before Codex announces that turn.
+
 `setMode` and `setThinkingOption` may return an `AgentProviderNotice` when the provider knows the change needs user-facing context. For example, providers that stage changes until the next turn should return an `info` notice while a turn is already running. The app renders the notice generically as a toast; provider-specific lifecycle behavior stays in the provider implementation.
 
 ### Steps
diff --git a/docs/release.md b/docs/release.md
index 328c189f7b..e76d2a833b 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -281,23 +281,26 @@ Drafts do not appear in GitHub's releases feed. Updater clients continue to see
 
 The `rollout_hours` input on `desktop-release.yml` is **only read on `workflow_dispatch`** — tag-push runs always default to 36. To get any other rollout duration on a fresh release, use the post-publish flip below.
 
-### Instant-admit release (rollout_hours=0 from publish)
+### Instant-admit release (rollout_hours=0)
 
-For a fresh release that should admit everyone immediately (low-risk change, doc-only, hotfix, or just a release you want out fast), cut the release normally and queue the rollout flip immediately after:
+`npm run release:patch` and `npm run release:minor` tag-push, and tag-push runs always stamp 36 hours. To admit everyone immediately (hotfix, doc-only change, a release you want out fast), cut the release normally, wait for it to publish, then flip the manifests:
 
 ```bash
-# 1. Cut and publish (default 36h ramp from tag push).
+# 1. Cut and publish (36h ramp from tag push).
 npm run release:patch
 
-# 2. Immediately queue the flip — runs as soon as finalize-rollout completes.
+# 2. Wait for Desktop Release to publish the GitHub Release.
+gh run watch <desktop-release-run-id> --exit-status
+
+# 3. Flip the published manifests to instant admit.
 gh workflow run desktop-rollout.yml \
   -f tag=v0.1.64 \
   -f rollout_hours=0
 ```
 
-**Why this is gap-free:** `desktop-release.yml`'s `finalize-rollout` job and `desktop-rollout.yml` share the concurrency group `desktop-rollout-<tag>`. Dispatching `desktop-rollout.yml` while the tag-push pipeline is still running queues it safely behind `finalize-rollout`. The first public manifests already carry `rolloutHours=36`, then `desktop-rollout.yml` flips them to `rolloutHours=0` shortly afterward. The renderer polls every 30 minutes, so active stable users pick up the new manifest on their next check.
+Dispatch only after `finalize-rollout` has published the release. Until then the release is a draft, and a draft has no tag: `desktop-rollout.yml` looks the release up by tag and fails with `release not found`. The concurrency group `desktop-rollout-<tag>` that the two workflows share orders them only once both are queued; it does not hold an early dispatch until the draft is published.
 
-Run the dispatch right after `release:patch` or `release:minor` returns. Don't wait for the tag-push CI to finish.
+The first public manifests carry `rolloutHours=36` for the minutes between publish and the flip. The renderer polls every 30 minutes, so active stable users pick up the new manifest on their next check.
 
 ### Adjusting an already-published release
 
@@ -591,7 +594,7 @@ Release notes depend on the changelog heading format. The heading **must** be st
 
 No prefix (`v`), no extra text. `Release Notes Sync` matches the `## X.Y.Z` (or `## X.Y.Z-beta.N`) line for the pushed tag to extract the version. A malformed heading breaks the release-notes sync for that tag.
 
-`CHANGELOG.md` on `main` is also what the app's **What's new** sheet fetches and renders, so the file is a shipped product surface, not just a release input. `##` starts a release and `###` starts a section; the app reads section titles from the document, so renaming or adding one needs no app change. Everything under a section is rendered as Markdown: prose, lists, links, inline code, fenced code, block quotes, tables, and images. Raw HTML does not render — the shared Markdown parser runs with `html: false`, so a `<video>`, `<iframe>` or `<embed>` tag reaches the reader as visible markup. Keep media out of the changelog, or link to it. A GitHub callout renders as a block quote with its `[!NOTE]` marker still in the text. A release entry is what a user reads on a phone the moment they are offered the update — write it for them.
+`CHANGELOG.md` on `main` is also what the app's **What's new** sheet fetches and renders, so the file is a shipped product surface, not just a release input. `##` starts a release and `###` starts a section; the app reads section titles from the document, so renaming or adding one needs no app change. Content between the release heading and the first `###` is the release's [highlights](#changelog-highlights). The What's new sheet, the website changelog and the GitHub release body show the highlights and keep the sections collapsed behind one control: Show all changes in the app and on the website, and an All changes `<details>` block that `Release Notes Sync` writes into the release body, so the file itself never needs HTML. A release with nothing before its first `###` shows its sections. Older entries that open with summary paragraphs are treated as highlights. The app, the website and the release scripts each parse the file with their own code, and installed apps keep the parser they shipped with, so those two heading rules are fixed: new kinds of content go inside the highlights or a section as Markdown, never behind a new heading level or marker. `scripts/test-support/changelog-structure.json` holds the cases all three parsers are tested against; change a structure rule there first. Everything under a section is rendered as Markdown: prose, lists, links, inline code, fenced code, block quotes, tables, and images. Raw HTML does not render — the shared Markdown parser runs with `html: false`, so a `<video>`, `<iframe>` or `<embed>` tag reaches the reader as visible markup. Keep media out of the changelog, or link to it. A GitHub callout renders as a block quote with its `[!NOTE]` marker still in the text. A release entry is what a user reads on a phone the moment they are offered the update — write it for them.
 
 ## Changelog policy
 
@@ -610,7 +613,7 @@ Older prerelease bodies on GitHub keep the notes they were synced with; `Release
 
 - The release agent writes the Chinese entry in the changelog commit, after the English entry is approved. Every beta that rewrites the English entry rewrites the Chinese one too, and promotion renames both. `packages/website/e2e/i18n.spec.ts` fails CI on the release commit when any entry has no current translation.
 - A translated entry uses the English heading unchanged: `## X.Y.Z - YYYY-MM-DD`. The website uses it only while the version and date both match the English entry. Otherwise it shows that release whole in English under a notice. Delete Chinese entries whose English entry was renamed.
-- Keep the English sections, bullets and links one to one. Section titles: Added 新增, Improved 改进, Changed 变更, Fixed 修复, Security 安全, Breaking 破坏性变更, Plugins 插件, Notes 说明. Wording follows [website-i18n.md](website-i18n.md#chinese-style).
+- Keep the English highlights, sections, bullets and links one to one. Section titles: Added 新增, Improved 改进, Changed 变更, Fixed 修复, Security 安全, Breaking 破坏性变更, Plugins 插件, Notes 说明. Wording follows [website-i18n.md](website-i18n.md#chinese-style).
 
 ## Changelog ownership
 
@@ -653,7 +656,7 @@ claims a general improvement, rewrite it with the concrete change.
 
 ## Changelog conciseness
 
-Every bullet must be scannable at a glance. The changelog is not release documentation — it's a list.
+Every section bullet must be scannable at a glance. The changelog is not release documentation — it's a list. [Highlights](#changelog-highlights) get more room; every other bullet follows these limits.
 
 - **One sentence per bullet, max.** If a bullet contains two sentences, the second one is doing work that belongs in product docs, not the changelog. Cut it.
 - **No trailing periods.** Bullets are list items, not prose. Drop the period at the end of every bullet, including the period inside any bolded lead-in. `**Configurable terminal scrollback**` not `**Configurable terminal scrollback.**`.
@@ -663,6 +666,57 @@ Every bullet must be scannable at a glance. The changelog is not release documen
 - **Stop after identifying the change.** Do not explain LAN/WAN topology, TLS handshakes, IPC, or other architecture in a changelog bullet. Put necessary background in product docs.
 - **Attribution follows the split.** When you split a dense bullet, move each PR/author to the bullet it belongs to. Never duplicate the same PR across multiple bullets.
 
+## Changelog highlights
+
+Every release entry leads with highlights: the changes a user would name first when asked what is
+new. They are a list above the first `###` section, biggest first. The sections below are the
+full record; a reader who stops after the highlights should have missed nothing they would ask
+about.
+
+```markdown
+## 0.16.0 - 2026-11-20
+
+- **Undo workspace archive:** Archiving a workspace in the app now shows a "Workspace archived" toast for six seconds. Undo, or Cmd/Ctrl+Z, restores the workspace with its tabs and agents. ([#8904](https://github.com/getpaseo/paseo/pull/8904))
+
+### Added
+```
+
+- **The lead-in names what is new in four words at most.** Bold it, colon inside the bold. A reader
+  who sees only the bold words should know what this release added or changed. A category lead-in
+  such as `**Polish:**` gathers several related changes.
+- **The lead-in is not a place or something Paseo already had.** A device, screen or area names
+  where the change landed. A feature name that was true of the last release hides the news: Paseo
+  already had keyboard shortcuts, so the lead-in says they now work on mobile.
+- **The first sentence says the plain thing.** Write what a user would tell a friend: Paseo now
+  shows the background tasks an agent is running. Leave out the conditions and mechanics that make
+  it true.
+- **Describe the new behavior, not the old one.** Say what is faster or better now, and do not
+  dwell on how slow or broken it was before. A number is welcome as a short aside after the new
+  behavior is stated: seconds, a percentage, a multiple.
+- **Do not list what a sentence already covers.** After "the same shortcuts as desktop", naming
+  five of them adds nothing. Keep a list only when it sets the scope, such as the providers a
+  feature works with.
+- **The description runs one to three sentences.** Sentences end with periods, and the attribution
+  follows the last one. [Changelog wording](#changelog-wording) applies in full.
+- **A highlight replaces the section bullets it covers.** A PR appears once in an entry, so its
+  attribution moves to the highlight.
+- **A highlight is something a user would name.** Everything else stays a section bullet. A patch
+  release still has one: the change it ships for.
+- **Fixes are routine and stay in `### Fixed`.** Do not add a summary of fixes. A fix, or a group
+  of related fixes, becomes a highlight only when it passes the same test as a feature, and then
+  it is written as what works now: `**Fewer reconnects on return:**`.
+
+| Avoid                                                                                      | Write                                                                                                            |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `**iPad and touch screens:**`                                                              | `**Touch-sized tablet controls:**`                                                                               |
+| `**Hardware keyboard shortcuts:**`                                                         | `**Keyboard shortcuts on mobile:**`                                                                              |
+| When an agent ends its turn while shells it started are still running, a pill lists them   | Paseo now shows the background tasks an agent is running                                                         |
+| A diff no longer waits 4 to 40 seconds behind worktree scans                               | Opening Changes shows the file tree right away, and diffs load about 6 times sooner on hosts with many worktrees |
+| The same shortcuts as desktop: command center, file picker, new workspace, workspace jumps | The same shortcuts as desktop, including your custom bindings                                                    |
+
+Before showing a draft, read only the bold lead-ins top to bottom. Each one must answer "what is
+new?" without its description.
+
 ## Changelog attribution
 
 Every changelog bullet must credit contributors and link to the PR(s) that delivered the change. This is not one-PR-per-line — a single bullet describes a user-facing change and may reference multiple PRs.
@@ -694,7 +748,7 @@ Rules:
 
 ## Changelog ordering
 
-Entries within each section (Added, Improved, Fixed) are ordered by user impact:
+Highlights come first, ordered by user impact. Entries within each section (Added, Improved, Fixed) follow the same order:
 
 1. **User-facing features and changes first** — things users will notice, want to try, or that change their workflow.
 2. **Quality-of-life improvements** — polish, performance, smoother interactions.
diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
index fd304aa144..4c418595fc 100644
--- a/docs/terminal-rendering.md
+++ b/docs/terminal-rendering.md
@@ -6,15 +6,25 @@ Web and Electron draw terminals with xterm.js. iOS and Android keep an `@xterm/h
 
 xterm decides which column every cell occupies. The native views never let text advance move a cell. Each row is shaped once, one run per font face, so Hangul jamo, ligatures, combining marks, conjuncts and fallback fonts see their neighbours. Each shaped cluster is then drawn at its first cell's column, centred in the columns it owns, and scaled down when its glyphs are wider. Cursor, selection, hit-testing and copy all use xterm's columns, so they stay correct whatever the font does.
 
-A cluster is the run of cells the shaper merged, and it is drawn once from the shaped row. Drawing part of a cluster on its own reshapes it: a half-form conjunct such as `स्ते` comes apart into `स्` with a visible virama. So colour and selection never split a cluster. A cluster whose cells differ in colour is drawn once per colour, clipped to that colour's columns.
+A cluster is the run of cells the shaper merged, and it is drawn once from the shaped row. xterm usually keeps a conjunct in one cell (see [Character widths](#character-widths)), but a colour change inside it leaves `क्` and `ष` in separate cells that still shape together. Drawing part of a cluster on its own reshapes it: the conjunct comes apart into `क्` with a visible virama. So colour and selection never split a cluster. A cluster whose cells differ in colour is drawn once per colour, clipped to that colour's columns.
 
-Android also groups cells with `android.icu.text.BreakIterator`, because Minikin's advances and cursor boundaries alone split some conjuncts. Grapheme rules follow the OS ICU version. Android 10 (API 29) splits `स्ते` after the virama and renders it incorrectly. The tested corpus passed on API 33, 34 and 35; API 30–32 have not been tested. We accept that version-dependent limitation to avoid bundling approximately 14 MB of ICU4J data. CoreText keeps this conjunct together on iOS. This renderer does not guarantee identical shaping across OS versions.
+Android also groups cells with `android.icu.text.BreakIterator`, because Minikin's advances and cursor boundaries alone split some clusters that span cells. Grouping only merges whole cells, so a conjunct xterm keeps in one cell cannot be split by the OS. Grapheme rules follow the OS ICU version, and we accept that to avoid bundling approximately 14 MB of ICU4J data. Before the buffers used grapheme widths, Android 10 (API 29) split `स्ते` across its two cells. This renderer does not guarantee identical shaping across OS versions.
 
 `TerminalRowLayoutTest.kt` is the Android regression test. It draws the rows of `grapheme-rows.json` and compares each with its grapheme clusters drawn one at a time, and with a wrong clustering that must not match. `terminal-frame.test.ts` checks that those rows are what xterm produces and that the clusters are UAX #29 grapheme clusters. Run it with `./gradlew :paseo-terminal:connectedDebugAndroidTest` from `packages/app/android`, with `ANDROID_SERIAL` set.
 
 The view reports ready only after it has measured its grid size. The pane attaches with that size, so the daemon replays the terminal at the client's size. Before this, the replay arrived at the PTY's old size, the resize came after it, and the shell's redraw landed on the wrong rows.
 
-Emoji widths come from the headless buffer, which uses xterm's default Unicode 6 table. `👍` gets one column, and `👋🏽` and `🇰🇷` get two cells drawn as one cluster. Web loads the Unicode 11 addon, so the same output can wrap differently on web and native.
+## Character widths
+
+The daemon, native and web buffers all load `@xterm/addon-unicode-graphemes`: the daemon through `packages/server/src/terminal/headless-terminal.ts`, native in `createNativeHeadlessTerminal`, web in `terminal-emulator-runtime.ts`. Each emoji cluster takes one two-column cell, including VS16 (`❤️`), skin tones (`👋🏽`), flags (`🇰🇷`) and ZWJ sequences (`👨‍👩‍👧`). That is the width colour-emoji fonts draw at. Under xterm's default Unicode 6 table `😀` got one column, and the native views scaled it to half size to fit.
+
+Every buffer must use the same table. The daemon answers cursor-position reports (`CSI 6n`) from its buffer, and a client re-parses the daemon's ANSI replay with its own table. A disagreement moves the cursor and the later cells of any row that holds a disputed cluster: after replay from a Unicode 6 daemon, the cursor that followed `A😀😀😀B` lands inside the third emoji.
+
+Daemons that use grapheme widths advertise `server_info.features["terminal-grapheme-widths"]`. `terminal-pane.tsx` reads it once and passes `characterWidths` to the emulator. Against an older daemon the app keeps each renderer's previous table: xterm's default on native, Unicode 11 on web. An older app against a newer daemon cannot match it, because every client shares the daemon's one buffer. A terminal kept by a worker from an unreleased pre-grapheme build keeps that worker's table until it exits.
+
+The table follows Unicode grapheme clusters, as Node's `string-width` does for Ink-based agent TUIs. Indic conjuncts follow the same rule: `क्ष` and `स्ते` take one column, and the native views scale them down to fit it. Shells measure with the C library's `wcwidth` instead. glibc counts `❤️` as one column, `👋🏽` as four and `क्ष` as two, so a line editor that measures those disagrees with the terminal.
+
+Use `@xterm/addon-unicode-graphemes` 0.5.0-beta.330 or later. Earlier versions read their width table from the wrong offset when Node decodes it into a pooled `Buffer`, which gives wrong widths or a load error depending on earlier allocations. `headless-terminal.test.ts` forces that case in a fresh process.
 
 ## Ink outside the row
 
diff --git a/docs/terminal-worker.md b/docs/terminal-worker.md
index be9321fb4f..d83dea9957 100644
--- a/docs/terminal-worker.md
+++ b/docs/terminal-worker.md
@@ -15,17 +15,20 @@ supervisor (paseo.pid) ──► daemon worker ──► launcher ──► term
 - The worker exits on its own when it has no controller and no terminals, on `shutdown`, on SIGTERM (killing its terminals), and when its record disappears (a deleted `$PASEO_HOME`: nobody can ever reach it again).
 - Its stderr goes to `$PASEO_HOME/terminal-worker.log`. No pipe to the daemon survives the daemon.
 
-The worker retains a fixed 10,000 history rows plus the screen in its existing xterm. Replay uses `@xterm/addon-serialize` 0.14 against headless xterm 6; no second cell grid or lifetime byte log is retained. The serializer boundary owns cursor position, visibility and explicit program-selected presentation; the addon alone does not preserve all three. An unset program style leaves each client’s configured cursor defaults intact. Standard modes come from the serializer; the existing input-mode tracker retains protocol modes such as Kitty and Win32 input. Commit that tracker with parsed output so replay bytes and metadata describe the same cut.
+The worker retains a fixed 10,000 history rows plus the screen in its existing xterm. Replay uses `@xterm/addon-serialize` 0.14 against headless xterm 6; no second cell grid or lifetime byte log is retained. The serializer boundary owns cursor position, visibility and explicit program-selected presentation; the addon alone does not preserve all three. An unset program style leaves each client’s configured cursor defaults intact. It also restores SGR mouse encoding: the addon preserves mouse tracking but omits its encoding, so switching away and back otherwise sends legacy wheel reports that Copilot CLI cannot use. These missing modes require xterm's internal services because its public modes API omits them. Standard modes come from the serializer; the existing input-mode tracker retains protocol modes such as Kitty and Win32 input. Commit that tracker with parsed output so replay bytes and metadata describe the same cut.
 
 Which triggers keep terminals and which close them is owned by the stop reason (`keepTerminals`) that flows from the request through the supervisor to `stop()`. The kill side always ends in the reaper (`terminal-worker-reaper.ts`), the only path that signals terminal processes outside a connected daemon.
 
 ## Record, socket and secret
 
-The worker writes `$PASEO_HOME/terminal-worker/<pid>.json` (owner-only) with its identity (birth time + command line carrying `--paseo-terminal-worker <recordId>`), protocol version, socket path, a random secret, the copy it runs from, and each terminal program's pid and birth time.
+The worker writes `$PASEO_HOME/terminal-worker/<pid>.json` (owner-only) with its pid, protocol version, socket path, random secret, runtime copy and terminal programs. One daemon holds the home's pid lock. Its records and sockets belong to that home.
 
-- The first frame on the socket must be `hello` with the secret; anything else closes the connection. Anyone who connects can type into every shell, so the record is `0600`, the unix socket `0600` in a `0700` directory.
-- Unix socket paths have a byte budget (103 on macOS, 107 on Linux). Dev homes under worktrees blow it, so `terminal-worker-socket-path.ts` tries `$PASEO_HOME/terminal-worker/sock/`, then `$TMPDIR/paseo-<uid>/`, then `/tmp/paseo-<uid>/`, and accepts an existing directory only if it is a real `0700` directory owned by you. It never chmods a shared root.
-- Cleanup signals a process only when its birth time matches the record. Birth times come from `ps -o lstart` with `LC_ALL=C` (it follows `LC_TIME` otherwise) and from `Win32_Process.CreationDate`. A missing birth time is "unknown", never matched by command text: a shell that ran `exec` keeps its pid and birth time but not its argv.
+- The first frame must be `hello` with the secret; anything else closes the connection. Anyone authenticated can type into every shell, so the record and Unix socket are `0600` inside a `0700` directory.
+- New socket names include the record id. A stale record whose pid belongs to a newer worker cannot reach that newer worker. Existing records keep their recorded paths. Legacy paths use only the home and pid, so force-killing through one also requires successful authentication. A legacy socket that cannot authenticate stays unconfirmed.
+- A missing pid or refused socket retires the record without signaling the worker. An accepting socket identifies the live worker. Cleanup asks it to shut down, then probes again before force-killing it after the grace period (`taskkill /T` on Windows). An inconclusive probe counts toward the worker limit and is retried on the next start or stop without signaling it.
+- Workers never query their own birth time or command line. Readers accept legacy identity fields but ignore them. Daemons through 0.15.1 report new records unreadable and cannot adopt them.
+- Windows terminal programs have no recorded birth time and terminal lifecycle operations never launch PowerShell. Linux and macOS retain program birth-time checks through `ps` with `LC_ALL=C`; Linux also walks sessions to find surviving jobs.
+- Unix socket paths have a byte budget (103 on macOS, 107 on Linux). Long dev homes use an owner-only fallback under `$TMPDIR/paseo-<uid>/` or `/tmp/paseo-<uid>/`. An existing directory must be a real `0700` directory owned by you; a shared root is never chmodded.
 - A kill cleanup that cannot confirm every process gone writes `closing-<recordId>.json` beside the worker record. The worker rewrites its own record whenever a terminal starts or exits, so the kill intent has to live in a file it never writes. A closing record is never adopted; the next stop or start retries it.
 - An unreadable record of either kind makes `daemon status` and a kill restart fail with its path: a kill cleanup that met it could not check what it names, and leaves nothing else behind. A read that fails with `EPERM`, `EBUSY` or `EACCES` is retried for 250ms first: on Windows, opening a record while the worker renames its new copy over it fails that way for a moment.
 
@@ -40,7 +43,7 @@ The worker writes `$PASEO_HOME/terminal-worker/<pid>.json` (owner-only) with its
 | two or more older                  | shuts it down; its terminals close (logged)                                                                                                                 |
 | newer, or a version it cannot read | leaves it running, undriven; `list_terminals` and `create_terminal` answer `rpc_error` `terminal_worker_incompatible`, and `paseo daemon status` prints why |
 
-Never more than two workers run. A new worker launches only when none is current, none is incompatible and fewer than two run. The count comes from the records, so an unreachable or unidentified worker counts, and so does one a cleanup could not confirm gone. When two run, the daemon starts with no current worker, and the first terminal created after one of them exits launches it.
+Never more than two workers run. A new worker launches only when none is current, none is incompatible and fewer than two run. The count comes from the records, so an unreachable worker counts, as does one whose socket probe is inconclusive, and one a cleanup could not confirm gone. When two run, the daemon starts with no current worker, and the first terminal created after one of them exits launches it.
 
 **The frozen envelope never changes across versions:** the frame format (4-byte length + `v8.serialize`), `hello`/`helloAck`, the `listTerminals` info fields and `shutdown`. That is what lets any daemon close any worker: a kill stop sends `shutdown` to a newer worker it cannot otherwise drive. Protocol 5 hard cuts unreleased protocols 1 through 4, including the acknowledgement-based replay contract: those workers are obsolete and close. For future versions, keep a previous-version adapter so the draining worker can still be driven, and drop the adapter for the version before that.
 
diff --git a/docs/timeline-sync.md b/docs/timeline-sync.md
index de62d99491..fdeeff6d52 100644
--- a/docs/timeline-sync.md
+++ b/docs/timeline-sync.md
@@ -101,8 +101,8 @@ Source coverage still includes interleaved tool updates.
 
 Canonical IDs define runs. With missing IDs, human prompts, heartbeats and typed received
 agent messages each start a fallback turn. This deterministic fallback is shared by paging
-and presentation; it cannot recover historical batching or steering. Older history remains
-user-driven by scrolling upward.
+and presentation; it cannot recover historical batching or steering. An underfilled viewport
+loads older history until it fills or history is exhausted. Further history is user-driven.
 
 A failed catch-up or subscription reconcile retries on its own, doubling from 1s to a 30s ceiling.
 A fixed 1s retry turned a persistent daemon-side refusal — a Codex thread that already has an active
@@ -127,21 +127,54 @@ Provider message IDs are not guaranteed for every displayed item. Paseo-generate
 Actions that address a point in chat history, such as Fork, use the daemon timeline `epoch` plus the projected item's `seqEnd`. The app carries that position on the rendered assistant item for both live and fetched history. When adjacent projected chunks merge, the merged item retains the newer chunk's position.
 
 The daemon validates the epoch and locates the projected item at the selected position. A fork
-includes projected items through that checkpoint. If an item spans the checkpoint and changed
-afterward, the daemon refuses that fork with an actionable error: discarded historical payloads
-cannot be reconstructed from sequence metadata. Forking the current context remains available.
+includes projected items through that checkpoint. If an item the fork copies spans the checkpoint
+and changed afterward, the daemon refuses that fork with an actionable error: discarded historical
+payloads cannot be reconstructed from sequence metadata. Plugin cards are not copied, so a card
+updated after the checkpoint does not block it. Forking the current context remains available.
 
 ## Resume behavior
 
-Opening, reconnecting, and returning from app background establish the current timeline through
-bounded catch-up. Switching between continuously subscribed open chats needs no fetch.
-Focus alone does not mutate timeline state; the response is compared with the local
-authoritative range first.
+Opening, reconnecting, and returning from app background establish whether the chat is current.
+Switching between continuously subscribed open chats needs no fetch. Focus alone does not mutate
+timeline state; the response is compared with the local authoritative range first.
 
-Cached history remains readable during recovery. The chat shows Reconnecting to host while the host is
-offline, then Updating messages until authoritative catch-up completes. Socket connectivity alone cannot
-certify that the displayed conversation is current. The timeline owner publishes freshness; the
-view renders it without a toast timer or a separate resume workflow.
+A chat with a cached cursor asks the daemon first. The `agent.timeline.set_subscription.request`
+that attaches the chat carries its `{ epoch, seq }`, and the response answers `current` or `behind`
+per chat. The daemon attaches before it compares, so an entry committed in between arrives live or
+counts as behind. `current` means the agent is loaded, the epoch matches, and the cursor is at the
+head; it completes catch-up with no fetch. The response carries the agent row for each `current`
+chat, because the timeline fetch is also what refreshes that row and the replica cache stores only
+part of it. `behind`, or no entry, runs the bounded catch-up. The subscribe handler never loads an
+agent, so an agent the daemon has not loaded answers `behind` and resumes in that fetch. Hosts without `features.timelineFreshnessCheck` get no cursors and always fetch.
+
+Cached history remains readable during recovery. The chat shows Reconnecting to host while the host
+is offline and until a reconnected chat's check answers, so an unchanged chat never shows a second
+toast. Returning from background on a socket that stayed connected shows nothing until the check
+answers: the chat stayed subscribed, so a slow answer is no reason to doubt it, and a socket that
+died without closing fails the foreground liveness probe and becomes a reconnect. Updating messages
+appears for a chat that is behind, until the fetch completes, and for an opened chat whose check is
+still unanswered `FRESHNESS_CHECK_QUIET_MS` after it was sent. That delay measures the daemon, so it
+starts at the request: on a cold start the cache read alone can take longer. Socket connectivity
+alone cannot certify that the displayed conversation is current. The timeline owner publishes freshness; the view renders it without a toast timer or a
+separate resume workflow.
+
+The turn footer in a chat follows its messages, not the agent status. Turn activity comes from the
+agent directory and messages from the chat's own catch-up, and either can land first. So the
+timeline owner keeps an unsettled turn per chat: the turn its messages were captured during. It is
+set when a check or catch-up becomes owed while the turn is open, or when cached messages are
+painted that were saved while one was, and it is saved with those messages in the replica. It
+carries the turn's start time. While it is set and the agent reads idle, the chat keeps showing that
+running turn, with its loader and elapsed timer unchanged, and there is no separate catching-up
+footer. The commit that brings the chat current clears it, in the same store write as the rows, so
+the final messages and the completed footer land together. A `current` answer is that commit with no
+rows. A check in flight keeps the hold, and `behind` keeps it until the fetched rows land. A failed
+catch-up clears it too, and the footer takes the true status. Losing the connection is not a failed
+catch-up: none can run or fail until the host returns, so the running footer stays beside
+"Reconnecting to host" and the check on reconnect resolves it. Releasing it offline would put a
+completed footer under messages known to be behind. Surfaces outside the timeline (the sidebar,
+tabs, the composer's stop and send controls) read the true status and never see this state. Live
+delivery needs no hold because `applyStreamEvent` commits queued rows before it applies turn
+liveness.
 
 The draft-create handoff has the same lifetime: the viewed-timeline owner releases it when the sync
 stops owing that chat a catch-up, not when the first authoritative page lands. Releasing it at the
diff --git a/fastlane/metadata/android/en-US/changelogs/150001.txt b/fastlane/metadata/android/en-US/changelogs/150001.txt
new file mode 100644
index 0000000000..0eb0c2ee0d
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150001.txt
@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150002.txt b/fastlane/metadata/android/en-US/changelogs/150002.txt
new file mode 100644
index 0000000000..0eb0c2ee0d
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150002.txt
@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150003.txt b/fastlane/metadata/android/en-US/changelogs/150003.txt
new file mode 100644
index 0000000000..0eb0c2ee0d
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150003.txt
@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150004.txt b/fastlane/metadata/android/en-US/changelogs/150004.txt
new file mode 100644
index 0000000000..0eb0c2ee0d
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150004.txt
@@ -0,0 +1,10 @@
+Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
+
+Mobile terminals have native rendering and draggable text-selection handles. Reconnecting restores up to 10,000 lines of terminal history.
+
+Worktree setup can copy ignored files and use plugin-defined locations before agents start.
+
+Added
+- Insert known agent commands from replies into the Composer draft
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150011.txt b/fastlane/metadata/android/en-US/changelogs/150011.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150011.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150012.txt b/fastlane/metadata/android/en-US/changelogs/150012.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150012.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150013.txt b/fastlane/metadata/android/en-US/changelogs/150013.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150013.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150014.txt b/fastlane/metadata/android/en-US/changelogs/150014.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150014.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150021.txt b/fastlane/metadata/android/en-US/changelogs/150021.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150021.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150022.txt b/fastlane/metadata/android/en-US/changelogs/150022.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150022.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150023.txt b/fastlane/metadata/android/en-US/changelogs/150023.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150023.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150024.txt b/fastlane/metadata/android/en-US/changelogs/150024.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150024.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150031.txt b/fastlane/metadata/android/en-US/changelogs/150031.txt
new file mode 100644
index 0000000000..ee51531c5e
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150031.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed conversation text becoming blurred when opening or dismissing the keyboard on iOS 26+
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150032.txt b/fastlane/metadata/android/en-US/changelogs/150032.txt
new file mode 100644
index 0000000000..ee51531c5e
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150032.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed conversation text becoming blurred when opening or dismissing the keyboard on iOS 26+
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150033.txt b/fastlane/metadata/android/en-US/changelogs/150033.txt
new file mode 100644
index 0000000000..ee51531c5e
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150033.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed conversation text becoming blurred when opening or dismissing the keyboard on iOS 26+
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150034.txt b/fastlane/metadata/android/en-US/changelogs/150034.txt
new file mode 100644
index 0000000000..ee51531c5e
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150034.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed conversation text becoming blurred when opening or dismissing the keyboard on iOS 26+
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150041.txt b/fastlane/metadata/android/en-US/changelogs/150041.txt
new file mode 100644
index 0000000000..f2f2509c35
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150041.txt
@@ -0,0 +1,7 @@
+Added
+- Added Claude Fable 5.2 and Mythos 5.2 with medium default effort
+
+Notes
+- Both models require Claude Code 2.1.321 or newer; Mythos 5.2 appears only when Claude Code advertises access
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150042.txt b/fastlane/metadata/android/en-US/changelogs/150042.txt
new file mode 100644
index 0000000000..f2f2509c35
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150042.txt
@@ -0,0 +1,7 @@
+Added
+- Added Claude Fable 5.2 and Mythos 5.2 with medium default effort
+
+Notes
+- Both models require Claude Code 2.1.321 or newer; Mythos 5.2 appears only when Claude Code advertises access
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150043.txt b/fastlane/metadata/android/en-US/changelogs/150043.txt
new file mode 100644
index 0000000000..f2f2509c35
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150043.txt
@@ -0,0 +1,7 @@
+Added
+- Added Claude Fable 5.2 and Mythos 5.2 with medium default effort
+
+Notes
+- Both models require Claude Code 2.1.321 or newer; Mythos 5.2 appears only when Claude Code advertises access
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150044.txt b/fastlane/metadata/android/en-US/changelogs/150044.txt
new file mode 100644
index 0000000000..f2f2509c35
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150044.txt
@@ -0,0 +1,7 @@
+Added
+- Added Claude Fable 5.2 and Mythos 5.2 with medium default effort
+
+Notes
+- Both models require Claude Code 2.1.321 or newer; Mythos 5.2 appears only when Claude Code advertises access
+
+Full notes: https://paseo.sh/changelog
diff --git a/nix/desktop-package.nix b/nix/desktop-package.nix
index 00ed6cd926..48cbd9bbb7 100644
--- a/nix/desktop-package.nix
+++ b/nix/desktop-package.nix
@@ -127,7 +127,7 @@ buildNpmPackage {
         # The Nix output is not a distributable DMG, so leave it unsigned and
         # disable the hardened runtime that requires a matching signature.
         CSC_IDENTITY_AUTO_DISCOVERY=false \
-          ../../node_modules/.bin/electron-builder \
+          npm exec --offline -- electron-builder \
             --config electron-builder.yml \
             --dir \
             --mac \
diff --git a/nix/npm-deps.hash b/nix/npm-deps.hash
index c7a63567f9..b1428a8c70 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-zFjdXeRpqrjEZk44ZCvEOTnVVGX0ASfDPktYNiWZpsw=
+sha256-21qteVXVoL7S/wF0aGxHNEkTX8in6UF6+wWEZi8N3HA=
diff --git a/package-lock.json b/package-lock.json
index 30ceb1cb4c..3ea347caf9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -30,6 +30,7 @@
         "concurrently": "^9.2.1",
         "cross-env": "^10.1.0",
         "electron": "44.2.0",
+        "electron-builder": "26.18.0",
         "expo-module-scripts": "^5.0.8",
         "get-port-cli": "^3.0.0",
         "js-yaml": "^4.1.1",
@@ -2788,58 +2789,6 @@
         "@jridgewell/sourcemap-codec": "^1.4.10"
       }
     },
-    "node_modules/@develar/schema-utils": {
-      "version": "2.6.5",
-      "resolved": "https://registry.npmjs.org/@develar/schema-utils/-/schema-utils-2.6.5.tgz",
-      "integrity": "sha512-0cp4PsWQ/9avqTVMCtZ+GirikIA36ikvjtHweU4/j8yLtgObI0+JUPhYFScgwlteveGB1rt3Cm8UhN04XayDig==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "ajv": "^6.12.0",
-        "ajv-keywords": "^3.4.1"
-      },
-      "engines": {
-        "node": ">= 8.9.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/webpack"
-      }
-    },
-    "node_modules/@develar/schema-utils/node_modules/ajv": {
-      "version": "6.14.0",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
-      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "fast-deep-equal": "^3.1.1",
-        "fast-json-stable-stringify": "^2.0.0",
-        "json-schema-traverse": "^0.4.1",
-        "uri-js": "^4.2.2"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/epoberezkin"
-      }
-    },
-    "node_modules/@develar/schema-utils/node_modules/ajv-keywords": {
-      "version": "3.5.2",
-      "resolved": "https://registry.npmjs.org/ajv-keywords/-/ajv-keywords-3.5.2.tgz",
-      "integrity": "sha512-5p6WTN0DdTGVQk6VjcEju19IgaHudalcfabD7yhDGeA6bcQnmL+CpveLJq/3hvfwd1aof6L386Ougkx6RfyMIQ==",
-      "dev": true,
-      "license": "MIT",
-      "peerDependencies": {
-        "ajv": "^6.9.1"
-      }
-    },
-    "node_modules/@develar/schema-utils/node_modules/json-schema-traverse": {
-      "version": "0.4.1",
-      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
-      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/@dnd-kit/accessibility": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/@dnd-kit/accessibility/-/accessibility-3.1.1.tgz",
@@ -3132,25 +3081,18 @@
       }
     },
     "node_modules/@electron/rebuild": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/@electron/rebuild/-/rebuild-4.0.3.tgz",
-      "integrity": "sha512-u9vpTHRMkOYCs/1FLiSVAFZ7FbjsXK+bQuzviJZa+lG7BHZl1nz52/IcGvwa3sk80/fc3llutBkbCq10Vh8WQA==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/@electron/rebuild/-/rebuild-4.2.1.tgz",
+      "integrity": "sha512-IS4pG3BysRrCLJ8xTAfvg+IQDbiUoAzdJy2SfjcYKnLDy5DpCdjnPdhS5Zf5UMfrkB24xu0KC+TqcOxg+eG+6w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@malept/cross-spawn-promise": "^2.0.0",
         "debug": "^4.1.1",
-        "detect-libc": "^2.0.1",
-        "got": "^11.7.0",
-        "graceful-fs": "^4.2.11",
         "node-abi": "^4.2.0",
         "node-api-version": "^0.2.1",
-        "node-gyp": "^11.2.0",
-        "ora": "^5.1.0",
-        "read-binary-file-arch": "^1.0.6",
-        "semver": "^7.3.5",
-        "tar": "^7.5.6",
-        "yargs": "^17.0.1"
+        "node-gyp": "^12.2.0",
+        "read-binary-file-arch": "^1.0.6"
       },
       "bin": {
         "electron-rebuild": "lib/cli.js"
@@ -3159,56 +3101,6 @@
         "node": ">=22.12.0"
       }
     },
-    "node_modules/@electron/rebuild/node_modules/chownr": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
-      "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@electron/rebuild/node_modules/minizlib": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
-      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "minipass": "^7.1.2"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/@electron/rebuild/node_modules/tar": {
-      "version": "7.5.12",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.12.tgz",
-      "integrity": "sha512-9TsuLcdhOn4XztcQqhNyq1KOwOOED/3k58JAvtULiYqbO8B/0IBAAIE1hj0Svmm58k27TmcigyDI0deMlgG3uw==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "@isaacs/fs-minipass": "^4.0.0",
-        "chownr": "^3.0.0",
-        "minipass": "^7.1.2",
-        "minizlib": "^3.1.0",
-        "yallist": "^5.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@electron/rebuild/node_modules/yallist": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
-      "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/@electron/universal": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/@electron/universal/-/universal-2.0.3.tgz",
@@ -3229,9 +3121,9 @@
       }
     },
     "node_modules/@electron/universal/node_modules/fs-extra": {
-      "version": "11.3.4",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.4.tgz",
-      "integrity": "sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==",
+      "version": "11.4.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.1.tgz",
+      "integrity": "sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3259,6 +3151,45 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/@electron/windows-sign": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/@electron/windows-sign/-/windows-sign-1.2.2.tgz",
+      "integrity": "sha512-dfZeox66AvdPtb2lD8OsIIQh12Tp0GNCRUDfBHIKGpbmopZto2/A8nSpYYLoedPIHpqkeblZ/k8OV0Gy7PYuyQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "cross-dirname": "^0.1.0",
+        "debug": "^4.3.4",
+        "fs-extra": "^11.1.1",
+        "minimist": "^1.2.8",
+        "postject": "^1.0.0-alpha.6"
+      },
+      "bin": {
+        "electron-windows-sign": "bin/electron-windows-sign.js"
+      },
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
+    "node_modules/@electron/windows-sign/node_modules/fs-extra": {
+      "version": "11.4.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.1.tgz",
+      "integrity": "sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
     "node_modules/@emnapi/core": {
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.8.1.tgz",
@@ -8211,6 +8142,26 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@legendapp/list": {
+      "version": "3.7.1",
+      "resolved": "https://registry.npmjs.org/@legendapp/list/-/list-3.7.1.tgz",
+      "integrity": "sha512-zgIy84yG2JP93+kib61rZBTcYGZ6fULrkCQz/MF7WrjVJeJQa/rR4z+rXfM5oveirO5mYkro4IDGytARIjJe9w==",
+      "license": "MIT",
+      "dependencies": {
+        "use-sync-external-store": "^1.5.0"
+      },
+      "peerDependencies": {
+        "react": "*"
+      },
+      "peerDependenciesMeta": {
+        "react-dom": {
+          "optional": true
+        },
+        "react-native": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@lezer/common": {
       "version": "1.5.1",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.1.tgz",
@@ -9135,81 +9086,6 @@
         "node": ">=12.4.0"
       }
     },
-    "node_modules/@npmcli/agent": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/@npmcli/agent/-/agent-3.0.0.tgz",
-      "integrity": "sha512-S79NdEgDQd/NGCay6TCoVzXSj74skRZIKJcpJjC5lOq34SZzyI6MqtiiWoiVWoVrTcGjNeC4ipbh1VIHlpfF5Q==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "agent-base": "^7.1.0",
-        "http-proxy-agent": "^7.0.0",
-        "https-proxy-agent": "^7.0.1",
-        "lru-cache": "^10.0.1",
-        "socks-proxy-agent": "^8.0.3"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
-    "node_modules/@npmcli/agent/node_modules/agent-base": {
-      "version": "7.1.4",
-      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
-      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "node_modules/@npmcli/agent/node_modules/http-proxy-agent": {
-      "version": "7.0.2",
-      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
-      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "agent-base": "^7.1.0",
-        "debug": "^4.3.4"
-      },
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "node_modules/@npmcli/agent/node_modules/https-proxy-agent": {
-      "version": "7.0.6",
-      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
-      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "agent-base": "^7.1.2",
-        "debug": "4"
-      },
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "node_modules/@npmcli/agent/node_modules/lru-cache": {
-      "version": "10.4.3",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
-      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
-      "dev": true,
-      "license": "ISC"
-    },
-    "node_modules/@npmcli/fs": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/@npmcli/fs/-/fs-4.0.0.tgz",
-      "integrity": "sha512-/xGlezI6xfGO9NwuJlnwz/K14qD1kCSAGtacBHnGzeAIuJGazcp45KP5NuyARXoKb7cwulAGWVsbeSxdG/cb0Q==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "semver": "^7.3.5"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
     "node_modules/@oclif/core": {
       "version": "1.26.2",
       "resolved": "https://registry.npmjs.org/@oclif/core/-/core-1.26.2.tgz",
@@ -10499,6 +10375,61 @@
         "node": "^20.19.0 || >=22.12.0"
       }
     },
+    "node_modules/@peculiar/asn1-schema": {
+      "version": "2.11.1",
+      "resolved": "https://registry.npmjs.org/@peculiar/asn1-schema/-/asn1-schema-2.11.1.tgz",
+      "integrity": "sha512-jaU9OaCcbZUdyXx9hMETZB9xoNmxTGjOGFqd3cOwKFkpKnyKd9WxF3uqj4PvX4cyOMP9bSdHg5YyML2qtx/d/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@peculiar/utils": "^2.0.2",
+        "asn1js": "^3.0.10",
+        "tslib": "^2.8.1"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/@peculiar/json-schema": {
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/@peculiar/json-schema/-/json-schema-1.1.12.tgz",
+      "integrity": "sha512-coUfuoMeIB7B8/NMekxaDzLhaYmp0HZNPEjYRm9goRou8UZIC3z21s0sL9AWoCw4EG876QyO3kYrc61WNF9B/w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
+    "node_modules/@peculiar/utils": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/@peculiar/utils/-/utils-2.0.3.tgz",
+      "integrity": "sha512-+oL3HPFRIZ1St2K50lWCXiioIgSoxzz7R1J3uF6neO2yl1sgmpgY6XXJH4BdpoDkMWznQTeYF6oWNDZLCdQ4eQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.8.1"
+      }
+    },
+    "node_modules/@peculiar/webcrypto": {
+      "version": "1.7.2",
+      "resolved": "https://registry.npmjs.org/@peculiar/webcrypto/-/webcrypto-1.7.2.tgz",
+      "integrity": "sha512-ktTSACRJ5WdpfjHjFT2EWJQQPacGv1cPCDfEbdmpAHOxdFiYqPe4lfnXGA3D8Dg9/0kHPYSvyRlgujIOVlTdvQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@peculiar/asn1-schema": "^2.7.0",
+        "@peculiar/json-schema": "^1.1.12",
+        "@peculiar/utils": "^2.0.2",
+        "tslib": "^2.8.1",
+        "webcrypto-core": "^1.9.2"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
     "node_modules/@pinojs/redact": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
@@ -13470,18 +13401,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@types/plist": {
-      "version": "3.0.5",
-      "resolved": "https://registry.npmjs.org/@types/plist/-/plist-3.0.5.tgz",
-      "integrity": "sha512-E6OCaRmAe4WDmWNsL/9RMqdkkzDCY1etutkflWk4c+AcjDU07Pcz1fQwTX0TQz+Pxqn9i4L1TU3UFpjnrcDgxA==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "@types/node": "*",
-        "xmlbuilder": ">=11.0.1"
-      }
-    },
     "node_modules/@types/prop-types": {
       "version": "15.7.15",
       "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
@@ -13632,14 +13551,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@types/verror": {
-      "version": "1.10.11",
-      "resolved": "https://registry.npmjs.org/@types/verror/-/verror-1.10.11.tgz",
-      "integrity": "sha512-RlDm9K7+o5stv0Co8i8ZRGxDbrTxhJtgjqjFyVh/tXQyl/rYtTKlnTvZ88oSTeYREWurwx20Js4kTuKCsFkUtg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/@types/ws": {
       "version": "8.18.1",
       "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -14740,16 +14651,52 @@
         "node": ">=10.0.0"
       }
     },
+    "node_modules/@xterm/addon-image": {
+      "version": "0.10.0-beta.331",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-image/-/addon-image-0.10.0-beta.331.tgz",
+      "integrity": "sha512-ShBTb3QF0ul/i55lfRdJpcu0hlA4aJdqRdzzHdOCws2WUzSsG0SCfMhLjzaoO1dVUGNj2Z7PNLqiXnlyqOinbg==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@xterm/xterm": "^6.1.0-beta.336"
+      }
+    },
     "node_modules/@xterm/addon-serialize": {
       "version": "0.14.0",
       "resolved": "https://registry.npmjs.org/@xterm/addon-serialize/-/addon-serialize-0.14.0.tgz",
       "integrity": "sha512-uteyTU1EkrQa2Ux6P/uFl2fzmXI46jy5uoQMKEOM0fKTyiW7cSn0WrFenHm5vO5uEXX/GpwW/FgILvv3r0WbkA==",
       "license": "MIT"
     },
+    "node_modules/@xterm/addon-unicode-graphemes": {
+      "version": "0.5.0-beta.330",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-unicode-graphemes/-/addon-unicode-graphemes-0.5.0-beta.330.tgz",
+      "integrity": "sha512-Zoiv/8tmku4LcU7bEL6zer+DNN6p6F8VCkyviSmbDxpA/W9zSnWDiD/ZpwFDQqegwjSptGzBNMhW2Os1sa+lUw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@xterm/xterm": "^6.1.0-beta.336"
+      }
+    },
+    "node_modules/@xterm/addon-webgl": {
+      "version": "0.20.0-beta.329",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-webgl/-/addon-webgl-0.20.0-beta.329.tgz",
+      "integrity": "sha512-bwqMma7X4cCBfwmWqKuhxNLkIXKW0lJTapaQ0g/9Kq7n6D6VCL4dYQCQ6DoeHv27ncJD4WzeoDTCEeSn0cspfg==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@xterm/xterm": "^6.1.0-beta.336"
+      }
+    },
     "node_modules/@xterm/headless": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-6.0.0.tgz",
-      "integrity": "sha512-5Yj1QINYCyzrZtf8OFIHi47iQtI+0qYFPHmouEfG8dHNxbZ9Tb9YGSuLcsEwj9Z+OL75GJqPyJbyoFer80a2Hw==",
+      "version": "6.1.0-beta.334",
+      "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-6.1.0-beta.334.tgz",
+      "integrity": "sha512-QkwuIeP9dXlk/eOsAbqX8AvtS/W8EhRo6dkl2YYZr+jWAWSfDDMi+zPlegWUflSdsRKMURMvzvvkVZr6GztK4g==",
+      "license": "MIT",
+      "workspaces": [
+        "addons/*"
+      ]
+    },
+    "node_modules/@xterm/xterm": {
+      "version": "6.1.0-beta.336",
+      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.1.0-beta.336.tgz",
+      "integrity": "sha512-QrvZZsffXsLW4Z3sba9GqimLvVwlb8b3W1NwZ+l6DdRnpH5pg5cFGWg2ceIburmfaGQ07YJHNekwxxlTcHZ3BA==",
       "license": "MIT",
       "workspaces": [
         "addons/*"
@@ -14762,13 +14709,6 @@
       "dev": true,
       "license": "BSD-2-Clause"
     },
-    "node_modules/7zip-bin": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/7zip-bin/-/7zip-bin-5.2.0.tgz",
-      "integrity": "sha512-ukTPVhqG4jNzMro2qA9HSCSSVJN3aN7tlb+hfqYCt3ER0yWroeA2VR38MNrOHLQ/cVj+DaIMad0kFCtWWowh/A==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/abab": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz",
@@ -15053,40 +14993,36 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
-    "node_modules/app-builder-bin": {
-      "version": "5.0.0-alpha.12",
-      "resolved": "https://registry.npmjs.org/app-builder-bin/-/app-builder-bin-5.0.0-alpha.12.tgz",
-      "integrity": "sha512-j87o0j6LqPL3QRr8yid6c+Tt5gC7xNfYo6uQIQkorAC6MpeayVMZrEDzKmJJ/Hlv7EnOQpaRm53k6ktDYZyB6w==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/app-builder-lib": {
-      "version": "26.8.1",
-      "resolved": "https://registry.npmjs.org/app-builder-lib/-/app-builder-lib-26.8.1.tgz",
-      "integrity": "sha512-p0Im/Dx5C4tmz8QEE1Yn4MkuPC8PrnlRneMhWJj7BBXQfNTJUshM/bp3lusdEsDbvvfJZpXWnYesgSLvwtM2Zw==",
+      "version": "26.18.0",
+      "resolved": "https://registry.npmjs.org/app-builder-lib/-/app-builder-lib-26.18.0.tgz",
+      "integrity": "sha512-lx+KkuCSZHcbECf4R3IAcC9VOFk0+cMUwljO63s5y8yqS1Lw0sRGmjPaWsPwP3zv3ohZYbMhUvjXeiQXXZhJXA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@develar/schema-utils": "~2.6.5",
         "@electron/asar": "3.4.1",
         "@electron/fuses": "^1.8.0",
         "@electron/get": "^3.0.0",
         "@electron/notarize": "2.5.0",
         "@electron/osx-sign": "1.3.3",
-        "@electron/rebuild": "^4.0.3",
+        "@electron/rebuild": "^4.2.1",
         "@electron/universal": "2.0.3",
         "@malept/flatpak-bundler": "^0.4.0",
+        "@noble/hashes": "^1.8.0",
+        "@peculiar/webcrypto": "^1.7.1",
         "@types/fs-extra": "9.0.13",
+        "ajv": "^8.18.0",
+        "asn1js": "^3.0.10",
         "async-exit-hook": "^2.0.1",
-        "builder-util": "26.8.1",
-        "builder-util-runtime": "9.5.1",
+        "builder-util": "26.16.0",
+        "builder-util-runtime": "9.7.0",
         "chromium-pickle-js": "^0.2.0",
         "ci-info": "4.3.1",
         "debug": "^4.3.4",
         "dotenv": "^16.4.5",
         "dotenv-expand": "^11.0.6",
         "ejs": "^3.1.8",
-        "electron-publish": "26.8.1",
+        "electron-publish": "26.18.0",
         "fs-extra": "^10.1.0",
         "hosted-git-info": "^4.1.0",
         "isbinaryfile": "^5.0.0",
@@ -15094,7 +15030,8 @@
         "js-yaml": "^4.1.0",
         "json5": "^2.2.3",
         "lazy-val": "^1.0.5",
-        "minimatch": "^10.0.3",
+        "minimatch": "^10.2.5",
+        "pkijs": "^3.4.0",
         "plist": "3.1.0",
         "proper-lockfile": "^4.1.2",
         "resedit": "^1.7.0",
@@ -15102,14 +15039,15 @@
         "tar": "^7.5.7",
         "temp-file": "^3.4.0",
         "tiny-async-pool": "1.3.0",
+        "unzipper": "^0.12.3",
         "which": "^5.0.0"
       },
       "engines": {
         "node": ">=14.0.0"
       },
       "peerDependencies": {
-        "dmg-builder": "26.8.1",
-        "electron-builder-squirrel-windows": "26.8.1"
+        "dmg-builder": "26.18.0",
+        "electron-builder-squirrel-windows": "26.18.0"
       }
     },
     "node_modules/app-builder-lib/node_modules/@electron/get": {
@@ -15159,6 +15097,36 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/app-builder-lib/node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/app-builder-lib/node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
     "node_modules/app-builder-lib/node_modules/balanced-match": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
@@ -15170,16 +15138,30 @@
       }
     },
     "node_modules/app-builder-lib/node_modules/brace-expansion": {
-      "version": "5.0.4",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz",
-      "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==",
+      "version": "5.0.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
+      "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
       },
       "engines": {
-        "node": "18 || 20 || >=22"
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/app-builder-lib/node_modules/builder-util-runtime": {
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
+      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.4",
+        "sax": "^1.2.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
       }
     },
     "node_modules/app-builder-lib/node_modules/chownr": {
@@ -15242,13 +15224,13 @@
       }
     },
     "node_modules/app-builder-lib/node_modules/minimatch": {
-      "version": "10.2.4",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
-      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
+      "version": "10.2.6",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
+      "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "dependencies": {
-        "brace-expansion": "^5.0.2"
+        "brace-expansion": "^5.0.8"
       },
       "engines": {
         "node": "18 || 20 || >=22"
@@ -15271,9 +15253,9 @@
       }
     },
     "node_modules/app-builder-lib/node_modules/tar": {
-      "version": "7.5.12",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.12.tgz",
-      "integrity": "sha512-9TsuLcdhOn4XztcQqhNyq1KOwOOED/3k58JAvtULiYqbO8B/0IBAAIE1hj0Svmm58k27TmcigyDI0deMlgG3uw==",
+      "version": "7.5.22",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
+      "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "dependencies": {
@@ -15562,15 +15544,19 @@
         "safer-buffer": "~2.1.0"
       }
     },
-    "node_modules/assert-plus": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/assert-plus/-/assert-plus-1.0.0.tgz",
-      "integrity": "sha512-NfJ4UzBCcQGLDlQq7nHxH+tv3kyZ0hHQqF5BO6J7tNJeP5do1llPr8dZ8zHonfhAu0PHAdMkSo+8o0wxg9lZWw==",
+    "node_modules/asn1js": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/asn1js/-/asn1js-3.1.0.tgz",
+      "integrity": "sha512-HWYi1THkOqguCiO+vwj09ZkQFD2kKEsejYHAYCtX0D80WVdoDnvRc9IukXX/jeb0T9NRWJnRtqwdbHltnFjwXA==",
       "dev": true,
-      "license": "MIT",
-      "optional": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "pvtsutils": "^1.3.6",
+        "pvutils": "^1.2.0",
+        "tslib": "^2.8.1"
+      },
       "engines": {
-        "node": ">=0.8"
+        "node": ">=12.0.0"
       }
     },
     "node_modules/assertion-error": {
@@ -15675,6 +15661,13 @@
       "integrity": "sha512-aDczADvlvTGajTDjcjpJMqRkOF6Qdz3YbPZm/PyW6tKPkx2hlYBzxMhEywM/tU72HrVZjgl5VCdRuMlA7pZ8Gw==",
       "license": "MIT"
     },
+    "node_modules/aws4": {
+      "version": "1.13.2",
+      "resolved": "https://registry.npmjs.org/aws4/-/aws4-1.13.2.tgz",
+      "integrity": "sha512-lHe62zvbTB5eEABUVi/AwVh0ZKY9rMMDhmm+eeyuuUQbQ3+J+fONVQOZyj+DdrvD4BY33uYniyRJ4UJIaSKAfw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/axios": {
       "version": "1.13.6",
       "resolved": "https://registry.npmjs.org/axios/-/axios-1.13.6.tgz",
@@ -16117,6 +16110,13 @@
       "integrity": "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==",
       "license": "MIT"
     },
+    "node_modules/bluebird": {
+      "version": "3.7.2",
+      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz",
+      "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/body-parser": {
       "version": "1.20.4",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.4.tgz",
@@ -16319,16 +16319,14 @@
       "license": "MIT"
     },
     "node_modules/builder-util": {
-      "version": "26.8.1",
-      "resolved": "https://registry.npmjs.org/builder-util/-/builder-util-26.8.1.tgz",
-      "integrity": "sha512-pm1lTYbGyc90DHgCDO7eo8Rl4EqKLciayNbZqGziqnH9jrlKe8ZANGdityLZU+pJh16dfzjAx2xQq9McuIPEtw==",
+      "version": "26.16.0",
+      "resolved": "https://registry.npmjs.org/builder-util/-/builder-util-26.16.0.tgz",
+      "integrity": "sha512-RLyJhB7Si3YkzKR9ubQslWuXW3Vhs3CGe1i+SeixBZ0qTd1mk3XBmssvY22TlB6CS5blyko8Gu1JzpYk8UkYAg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/debug": "^4.1.6",
-        "7zip-bin": "~5.2.0",
-        "app-builder-bin": "5.0.0-alpha.12",
-        "builder-util-runtime": "9.5.1",
+        "builder-util-runtime": "9.7.0",
         "chalk": "^4.1.2",
         "cross-spawn": "^7.0.6",
         "debug": "^4.3.4",
@@ -16341,6 +16339,9 @@
         "stat-mode": "^1.0.0",
         "temp-file": "^3.4.0",
         "tiny-async-pool": "1.3.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
       }
     },
     "node_modules/builder-util-runtime": {
@@ -16366,6 +16367,20 @@
         "node": ">= 14"
       }
     },
+    "node_modules/builder-util/node_modules/builder-util-runtime": {
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
+      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.4",
+        "sax": "^1.2.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/builder-util/node_modules/http-proxy-agent": {
       "version": "7.0.2",
       "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
@@ -16422,98 +16437,14 @@
         "node": ">= 0.8"
       }
     },
-    "node_modules/cacache": {
-      "version": "19.0.1",
-      "resolved": "https://registry.npmjs.org/cacache/-/cacache-19.0.1.tgz",
-      "integrity": "sha512-hdsUxulXCi5STId78vRVYEtDAjq99ICAUktLTeTYsLoTE6Z8dS0c8pWNCxwdrk9YfJeobDZc2Y186hD/5ZQgFQ==",
+    "node_modules/bytestreamjs": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/bytestreamjs/-/bytestreamjs-2.0.1.tgz",
+      "integrity": "sha512-U1Z/ob71V/bXfVABvNr/Kumf5VyeQRBEm6Txb0PQ6S7V5GpBM3w4Cbqz/xPDicR5tN0uvDifng8C+5qECeGwyQ==",
       "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "@npmcli/fs": "^4.0.0",
-        "fs-minipass": "^3.0.0",
-        "glob": "^10.2.2",
-        "lru-cache": "^10.0.1",
-        "minipass": "^7.0.3",
-        "minipass-collect": "^2.0.1",
-        "minipass-flush": "^1.0.5",
-        "minipass-pipeline": "^1.2.4",
-        "p-map": "^7.0.2",
-        "ssri": "^12.0.0",
-        "tar": "^7.4.3",
-        "unique-filename": "^4.0.0"
-      },
+      "license": "BSD-3-Clause",
       "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
-    "node_modules/cacache/node_modules/chownr": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
-      "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/cacache/node_modules/fs-minipass": {
-      "version": "3.0.3",
-      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-3.0.3.tgz",
-      "integrity": "sha512-XUBA9XClHbnJWSfBzjkm6RvPsyg3sryZt06BEQoXcF7EK/xpGaQYJgQKDJSUH5SGZ76Y7pFx1QBnXz09rU5Fbw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^7.0.3"
-      },
-      "engines": {
-        "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
-      }
-    },
-    "node_modules/cacache/node_modules/lru-cache": {
-      "version": "10.4.3",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
-      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
-      "dev": true,
-      "license": "ISC"
-    },
-    "node_modules/cacache/node_modules/minizlib": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
-      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "minipass": "^7.1.2"
-      },
-      "engines": {
-        "node": ">= 18"
-      }
-    },
-    "node_modules/cacache/node_modules/tar": {
-      "version": "7.5.12",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.12.tgz",
-      "integrity": "sha512-9TsuLcdhOn4XztcQqhNyq1KOwOOED/3k58JAvtULiYqbO8B/0IBAAIE1hj0Svmm58k27TmcigyDI0deMlgG3uw==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "@isaacs/fs-minipass": "^4.0.0",
-        "chownr": "^3.0.0",
-        "minipass": "^7.1.2",
-        "minizlib": "^3.1.0",
-        "yallist": "^5.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/cacache/node_modules/yallist": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
-      "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=18"
+        "node": ">=6.0.0"
       }
     },
     "node_modules/cacheable-lookup": {
@@ -16950,40 +16881,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/cli-truncate": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-2.1.0.tgz",
-      "integrity": "sha512-n8fOixwDD6b/ObinzTrp1ZKFzbgvKZvuz/TvejnLn1aQfC6r52XEx85FmuC+3HI+JM7coBRXUvNqEU2PHVrHpg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "slice-ansi": "^3.0.0",
-        "string-width": "^4.2.0"
-      },
-      "engines": {
-        "node": ">=8"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "node_modules/cli-truncate/node_modules/slice-ansi": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-3.0.0.tgz",
-      "integrity": "sha512-pSyv7bSTC7ig9Dcgbw9AuRNUb5k5V6oDudjZoMBSr13qpLBG7tB+zgCkARjq7xIUgdz5P1Qe8u+rSGdouOOIyQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "ansi-styles": "^4.0.0",
-        "astral-regex": "^2.0.0",
-        "is-fullwidth-code-point": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
     "node_modules/client-only": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/client-only/-/client-only-0.0.1.tgz",
@@ -17369,43 +17266,6 @@
         "layout-base": "^1.0.0"
       }
     },
-    "node_modules/crc": {
-      "version": "3.8.0",
-      "resolved": "https://registry.npmjs.org/crc/-/crc-3.8.0.tgz",
-      "integrity": "sha512-iX3mfgcTMIq3ZKLIsVFAbv7+Mc10kxabAGQb8HvjA1o3T1PIYprbakQ65d3I+2HGHt6nSKkM9PYjgoJO2KcFBQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "buffer": "^5.1.0"
-      }
-    },
-    "node_modules/crc/node_modules/buffer": {
-      "version": "5.7.1",
-      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
-      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
-      "dev": true,
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "base64-js": "^1.3.1",
-        "ieee754": "^1.1.13"
-      }
-    },
     "node_modules/create-jest": {
       "version": "29.7.0",
       "resolved": "https://registry.npmjs.org/create-jest/-/create-jest-29.7.0.tgz",
@@ -17442,6 +17302,15 @@
       "integrity": "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==",
       "license": "MIT"
     },
+    "node_modules/cross-dirname": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/cross-dirname/-/cross-dirname-0.1.0.tgz",
+      "integrity": "sha512-+R08/oI0nl3vfPcqftZRpytksBXDzOUveBq/NBVx0sUp1axwzPQrKinNx5yd5sxPu8j1wIy8AfnVQ+5eFdha6Q==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true
+    },
     "node_modules/cross-env": {
       "version": "10.1.0",
       "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-10.1.0.tgz",
@@ -18608,9 +18477,9 @@
       }
     },
     "node_modules/dir-compare/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -18645,75 +18514,18 @@
       }
     },
     "node_modules/dmg-builder": {
-      "version": "26.8.1",
-      "resolved": "https://registry.npmjs.org/dmg-builder/-/dmg-builder-26.8.1.tgz",
-      "integrity": "sha512-glMJgnTreo8CFINujtAhCgN96QAqApDMZ8Vl1r8f0QT8QprvC1UCltV4CcWj20YoIyLZx6IUskaJZ0NV8fokcg==",
+      "version": "26.18.0",
+      "resolved": "https://registry.npmjs.org/dmg-builder/-/dmg-builder-26.18.0.tgz",
+      "integrity": "sha512-ozCGC54wi2C1RkS2v69y9lQxvoQ1Coh+iT8CmWiyY8y1ZuOKVvuNson2Hd+HEOs9+EZNNsOBbzKgQZ4SNqWd0w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "app-builder-lib": "26.8.1",
-        "builder-util": "26.8.1",
+        "app-builder-lib": "26.18.0",
+        "builder-util": "26.16.0",
         "fs-extra": "^10.1.0",
-        "iconv-lite": "^0.6.2",
         "js-yaml": "^4.1.0"
-      },
-      "optionalDependencies": {
-        "dmg-license": "^1.0.11"
       }
     },
-    "node_modules/dmg-license": {
-      "version": "1.0.11",
-      "resolved": "https://registry.npmjs.org/dmg-license/-/dmg-license-1.0.11.tgz",
-      "integrity": "sha512-ZdzmqwKmECOWJpqefloC5OJy1+WZBBse5+MR88z9g9Zn4VY+WYUkAyojmhzJckH5YbbZGcYIuGAkY5/Ys5OM2Q==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "dependencies": {
-        "@types/plist": "^3.0.1",
-        "@types/verror": "^1.10.3",
-        "ajv": "^6.10.0",
-        "crc": "^3.8.0",
-        "iconv-corefoundation": "^1.1.7",
-        "plist": "^3.0.4",
-        "smart-buffer": "^4.0.2",
-        "verror": "^1.10.0"
-      },
-      "bin": {
-        "dmg-license": "bin/dmg-license.js"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/dmg-license/node_modules/ajv": {
-      "version": "6.14.0",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
-      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "fast-deep-equal": "^3.1.1",
-        "fast-json-stable-stringify": "^2.0.0",
-        "json-schema-traverse": "^0.4.1",
-        "uri-js": "^4.2.2"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/epoberezkin"
-      }
-    },
-    "node_modules/dmg-license/node_modules/json-schema-traverse": {
-      "version": "0.4.1",
-      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
-      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/dnssd-advertise": {
       "version": "1.1.6",
       "resolved": "https://registry.npmjs.org/dnssd-advertise/-/dnssd-advertise-1.1.6.tgz",
@@ -18905,6 +18717,16 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/duplexer2": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/duplexer2/-/duplexer2-0.1.4.tgz",
+      "integrity": "sha512-asLFVfWWtJ90ZyOUHMqk7/S2w2guQKxUI2itj3d92ADHhxUSbCMGi1f1cBcJ7xM1To+pE/Khbwo1yuNbMEPKeA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "readable-stream": "^2.0.2"
+      }
+    },
     "node_modules/eas-cli": {
       "version": "16.32.0",
       "resolved": "https://registry.npmjs.org/eas-cli/-/eas-cli-16.32.0.tgz",
@@ -19226,18 +19048,18 @@
       }
     },
     "node_modules/electron-builder": {
-      "version": "26.8.1",
-      "resolved": "https://registry.npmjs.org/electron-builder/-/electron-builder-26.8.1.tgz",
-      "integrity": "sha512-uWhx1r74NGpCagG0ULs/P9Nqv2nsoo+7eo4fLUOB8L8MdWltq9odW/uuLXMFCDGnPafknYLZgjNX0ZIFRzOQAw==",
+      "version": "26.18.0",
+      "resolved": "https://registry.npmjs.org/electron-builder/-/electron-builder-26.18.0.tgz",
+      "integrity": "sha512-ASgIuQnOq4RuD8jMhS9hI0LS3EMRT1I/M5R6utqifB/BHN80IcCjBdt+DED+NmNPvmBgEtrlExXZitNdA7kXOg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "app-builder-lib": "26.8.1",
-        "builder-util": "26.8.1",
-        "builder-util-runtime": "9.5.1",
+        "app-builder-lib": "26.18.0",
+        "builder-util": "26.16.0",
+        "builder-util-runtime": "9.7.0",
         "chalk": "^4.1.2",
         "ci-info": "^4.2.0",
-        "dmg-builder": "26.8.1",
+        "dmg-builder": "26.18.0",
         "fs-extra": "^10.1.0",
         "lazy-val": "^1.0.5",
         "simple-update-notifier": "2.0.0",
@@ -19251,6 +19073,33 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/electron-builder-squirrel-windows": {
+      "version": "26.18.0",
+      "resolved": "https://registry.npmjs.org/electron-builder-squirrel-windows/-/electron-builder-squirrel-windows-26.18.0.tgz",
+      "integrity": "sha512-a2elgTipboXNIsxqS1HOmHMGp4Pd3LJgIZOdIFTOskBSawvxKyZWYWQ1d7KKA4CtINSchYCYEKzhxRqiKZev9Q==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "app-builder-lib": "26.18.0",
+        "builder-util": "26.16.0",
+        "electron-winstaller": "5.4.0"
+      }
+    },
+    "node_modules/electron-builder/node_modules/builder-util-runtime": {
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
+      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.4",
+        "sax": "^1.2.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/electron-builder/node_modules/ci-info": {
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz",
@@ -19277,15 +19126,16 @@
       }
     },
     "node_modules/electron-publish": {
-      "version": "26.8.1",
-      "resolved": "https://registry.npmjs.org/electron-publish/-/electron-publish-26.8.1.tgz",
-      "integrity": "sha512-q+jrSTIh/Cv4eGZa7oVR+grEJo/FoLMYBAnSL5GCtqwUpr1T+VgKB/dn1pnzxIxqD8S/jP1yilT9VrwCqINR4w==",
+      "version": "26.18.0",
+      "resolved": "https://registry.npmjs.org/electron-publish/-/electron-publish-26.18.0.tgz",
+      "integrity": "sha512-MagnqaZSALSWjcdKu5HEVhYUZD/2BDL3q7XzrqWwub6gf/UfD3ItMgmthVDv9w5y9E0gH1C3JWqKaXwf6f4ROg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/fs-extra": "^9.0.11",
-        "builder-util": "26.8.1",
-        "builder-util-runtime": "9.5.1",
+        "aws4": "^1.13.2",
+        "builder-util": "26.16.0",
+        "builder-util-runtime": "9.7.0",
         "chalk": "^4.1.2",
         "form-data": "^4.0.5",
         "fs-extra": "^10.1.0",
@@ -19293,6 +19143,20 @@
         "mime": "^2.5.2"
       }
     },
+    "node_modules/electron-publish/node_modules/builder-util-runtime": {
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
+      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.3.4",
+        "sax": "^1.2.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/electron-publish/node_modules/mime": {
       "version": "2.6.0",
       "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
@@ -19328,6 +19192,66 @@
         "tiny-typed-emitter": "^2.1.0"
       }
     },
+    "node_modules/electron-winstaller": {
+      "version": "5.4.0",
+      "resolved": "https://registry.npmjs.org/electron-winstaller/-/electron-winstaller-5.4.0.tgz",
+      "integrity": "sha512-bO3y10YikuUwUuDUQRM4KfwNkKhnpVO7IPdbsrejwN9/AABJzzTQ4GeHwyzNSrVO+tEH3/Np255a3sVZpZDjvg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@electron/asar": "^3.2.1",
+        "debug": "^4.1.1",
+        "fs-extra": "^7.0.1",
+        "lodash": "^4.17.21",
+        "temp": "^0.9.0"
+      },
+      "engines": {
+        "node": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@electron/windows-sign": "^1.1.2"
+      }
+    },
+    "node_modules/electron-winstaller/node_modules/fs-extra": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz",
+      "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "graceful-fs": "^4.1.2",
+        "jsonfile": "^4.0.0",
+        "universalify": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=6 <7 || >=8"
+      }
+    },
+    "node_modules/electron-winstaller/node_modules/jsonfile": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz",
+      "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "optionalDependencies": {
+        "graceful-fs": "^4.1.6"
+      }
+    },
+    "node_modules/electron-winstaller/node_modules/universalify": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz",
+      "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">= 4.0.0"
+      }
+    },
     "node_modules/electron/node_modules/@types/node": {
       "version": "24.13.3",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.3.tgz",
@@ -21683,17 +21607,6 @@
       "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
       "license": "MIT"
     },
-    "node_modules/extsprintf": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/extsprintf/-/extsprintf-1.4.1.tgz",
-      "integrity": "sha512-Wrk35e8ydCKDj/ArClo1VrPVmN8zph5V4AtHwIuHhvMXsKf73UT3BOD+azBIW+3wOJ4FhEH7zyaJCFvChjYvMA==",
-      "dev": true,
-      "engines": [
-        "node >=0.6.0"
-      ],
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/fake-indexeddb": {
       "version": "6.2.5",
       "resolved": "https://registry.npmjs.org/fake-indexeddb/-/fake-indexeddb-6.2.5.tgz",
@@ -23247,9 +23160,9 @@
       }
     },
     "node_modules/http-cache-semantics": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
-      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.3.0.tgz",
+      "integrity": "sha512-M5t5LlJpS1UHMjvwRQVdFHvPISGeLAxNcrWuJkeGh0KxsqCHZ1O3NXZU/8x7cD0BDcGW8kapxMKTvwlqrNkHkA==",
       "dev": true,
       "license": "BSD-2-Clause"
     },
@@ -23403,32 +23316,6 @@
         }
       }
     },
-    "node_modules/iconv-corefoundation": {
-      "version": "1.1.7",
-      "resolved": "https://registry.npmjs.org/iconv-corefoundation/-/iconv-corefoundation-1.1.7.tgz",
-      "integrity": "sha512-T10qvkw0zz4wnm560lOEg0PovVqUXuOFhhHAkixw8/sycy7TJt7v/RrkEKEQnAw2viPSJu6iAkErxnzR0g8PpQ==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "dependencies": {
-        "cli-truncate": "^2.1.0",
-        "node-addon-api": "^1.6.3"
-      },
-      "engines": {
-        "node": "^8.11.2 || >=10"
-      }
-    },
-    "node_modules/iconv-corefoundation/node_modules/node-addon-api": {
-      "version": "1.7.2",
-      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-1.7.2.tgz",
-      "integrity": "sha512-ibPK3iA+vaY1eEjESkQkM0BbCqFOaZMiXRTtdB0u7b4djtY6JnsjvPdUHVMg6xQt3B8fpTTWHI9A+ADjM9frzg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/iconv-lite": {
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
@@ -27028,49 +26915,6 @@
       "dev": true,
       "license": "ISC"
     },
-    "node_modules/make-fetch-happen": {
-      "version": "14.0.3",
-      "resolved": "https://registry.npmjs.org/make-fetch-happen/-/make-fetch-happen-14.0.3.tgz",
-      "integrity": "sha512-QMjGbFTP0blj97EeidG5hk/QhKQ3T4ICckQGLgz38QF7Vgbk6e6FTARN8KhKxyBbWn8R0HU+bnw8aSoFPD4qtQ==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "@npmcli/agent": "^3.0.0",
-        "cacache": "^19.0.1",
-        "http-cache-semantics": "^4.1.1",
-        "minipass": "^7.0.2",
-        "minipass-fetch": "^4.0.0",
-        "minipass-flush": "^1.0.5",
-        "minipass-pipeline": "^1.2.4",
-        "negotiator": "^1.0.0",
-        "proc-log": "^5.0.0",
-        "promise-retry": "^2.0.1",
-        "ssri": "^12.0.0"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
-    "node_modules/make-fetch-happen/node_modules/negotiator": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
-      "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "node_modules/make-fetch-happen/node_modules/proc-log": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-5.0.0.tgz",
-      "integrity": "sha512-Azwzvl90HaF0aCz1JrDdXQykFakSSNPaPoiZ9fm5qJIMHioDZEi7OAdRwSm6rSoPtY3Qutnm3L7ogmg3dc+wbQ==",
-      "dev": true,
-      "license": "ISC",
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
     "node_modules/makeerror": {
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/makeerror/-/makeerror-1.0.12.tgz",
@@ -29271,115 +29115,6 @@
         "node": ">=16 || 14 >=14.17"
       }
     },
-    "node_modules/minipass-collect": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/minipass-collect/-/minipass-collect-2.0.1.tgz",
-      "integrity": "sha512-D7V8PO9oaz7PWGLbCACuI1qEOsq7UKfLotx/C0Aet43fCUB/wfQ7DYeq2oR/svFJGYDHPr38SHATeaj/ZoKHKw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^7.0.3"
-      },
-      "engines": {
-        "node": ">=16 || 14 >=14.17"
-      }
-    },
-    "node_modules/minipass-fetch": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/minipass-fetch/-/minipass-fetch-4.0.1.tgz",
-      "integrity": "sha512-j7U11C5HXigVuutxebFadoYBbd7VSdZWggSe64NVdvWNBqGAiXPL2QVCehjmw7lY1oF9gOllYbORh+hiNgfPgQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "minipass": "^7.0.3",
-        "minipass-sized": "^1.0.3",
-        "minizlib": "^3.0.1"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      },
-      "optionalDependencies": {
-        "encoding": "^0.1.13"
-      }
-    },
-    "node_modules/minipass-flush": {
-      "version": "1.0.5",
-      "resolved": "https://registry.npmjs.org/minipass-flush/-/minipass-flush-1.0.5.tgz",
-      "integrity": "sha512-JmQSYYpPUqX5Jyn1mXaRwOda1uQ8HP5KAT/oDSLCzt1BYRhQU0/hDtsB1ufZfEEzMZ9aAVmsBw8+FWsIXlClWw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^3.0.0"
-      },
-      "engines": {
-        "node": ">= 8"
-      }
-    },
-    "node_modules/minipass-flush/node_modules/minipass": {
-      "version": "3.3.6",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
-      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/minipass-pipeline": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/minipass-pipeline/-/minipass-pipeline-1.2.4.tgz",
-      "integrity": "sha512-xuIq7cIOt09RPRJ19gdi4b+RiNvDFYe5JH+ggNvBqGqpQXcru3PcRmOZuHBKWK1Txf9+cQ+HMVN4d6z46LZP7A==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/minipass-pipeline/node_modules/minipass": {
-      "version": "3.3.6",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
-      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/minipass-sized": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/minipass-sized/-/minipass-sized-1.0.3.tgz",
-      "integrity": "sha512-MbkQQ2CTiBMlA2Dm/5cY+9SWFEN8pzzOXi6rlM5Xxq0Yqbda5ZQy9sU75a673FE9ZK0Zsbr6Y5iP6u9nktfg2g==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/minipass-sized/node_modules/minipass": {
-      "version": "3.3.6",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
-      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
     "node_modules/minizlib": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.0.1.tgz",
@@ -29703,9 +29438,9 @@
       }
     },
     "node_modules/node-abi": {
-      "version": "4.28.0",
-      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-4.28.0.tgz",
-      "integrity": "sha512-Qfp5XZL1cJDOabOT8H5gnqMTmM4NjvYzHp4I/Kt/Sl76OVkOBBHRFlPspGV0hYvMoqQsypFjT/Yp7Km0beXW9g==",
+      "version": "4.40.0",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-4.40.0.tgz",
+      "integrity": "sha512-GuvqvtrOk+AC27RidBxBsMzVNkwNl7PjHgc4NXbmdvSVLgIUjpaqcG1FjNRYnt2Yn9Ytq+Ln37XsBaglUcte/w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -29791,28 +29526,28 @@
       }
     },
     "node_modules/node-gyp": {
-      "version": "11.5.0",
-      "resolved": "https://registry.npmjs.org/node-gyp/-/node-gyp-11.5.0.tgz",
-      "integrity": "sha512-ra7Kvlhxn5V9Slyus0ygMa2h+UqExPqUIkfk7Pc8QTLT956JLSy51uWFwHtIYy0vI8cB4BDhc/S03+880My/LQ==",
+      "version": "12.4.0",
+      "resolved": "https://registry.npmjs.org/node-gyp/-/node-gyp-12.4.0.tgz",
+      "integrity": "sha512-OMcPNvqTCFUnNaBlmdgq+lfNqY7gTiSmNRDjY3uAXRyudeKZEZxu3CLtjMQrx4zZxCX2b/mpNqTtwuCJgXhHkw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "env-paths": "^2.2.0",
         "exponential-backoff": "^3.1.1",
         "graceful-fs": "^4.2.6",
-        "make-fetch-happen": "^14.0.3",
-        "nopt": "^8.0.0",
-        "proc-log": "^5.0.0",
+        "nopt": "^9.0.0",
+        "proc-log": "^6.0.0",
         "semver": "^7.3.5",
-        "tar": "^7.4.3",
+        "tar": "^7.5.4",
         "tinyglobby": "^0.2.12",
-        "which": "^5.0.0"
+        "undici": "^6.25.0",
+        "which": "^6.0.0"
       },
       "bin": {
         "node-gyp": "bin/node-gyp.js"
       },
       "engines": {
-        "node": "^18.17.0 || >=20.5.0"
+        "node": "^20.17.0 || >=22.9.0"
       }
     },
     "node_modules/node-gyp-build": {
@@ -29842,6 +29577,16 @@
         "node-gyp-build-optional-packages-test": "build-test.js"
       }
     },
+    "node_modules/node-gyp/node_modules/abbrev": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-4.0.0.tgz",
+      "integrity": "sha512-a1wflyaL0tHtJSmLSOVybYhy22vRih4eduhhrkcjgrWGnRfrZtovJ2FRjxuTtkkj47O/baf0R86QU5OuYpz8fA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^20.17.0 || >=22.9.0"
+      }
+    },
     "node_modules/node-gyp/node_modules/chownr": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
@@ -29853,13 +29598,13 @@
       }
     },
     "node_modules/node-gyp/node_modules/isexe": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/isexe/-/isexe-3.1.5.tgz",
-      "integrity": "sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-4.0.0.tgz",
+      "integrity": "sha512-FFUtZMpoZ8RqHS3XeXEmHWLA4thH+ZxCv2lOiPIn1Xc7CxrqhWzNSDzD+/chS/zbYezmiwWLdQC09JdQKmthOw==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "node_modules/node-gyp/node_modules/minizlib": {
@@ -29875,20 +29620,36 @@
         "node": ">= 18"
       }
     },
+    "node_modules/node-gyp/node_modules/nopt": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-9.0.0.tgz",
+      "integrity": "sha512-Zhq3a+yFKrYwSBluL4H9XP3m3y5uvQkB/09CwDruCiRmR/UJYnn9W4R48ry0uGC70aeTPKLynBtscP9efFFcPw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "abbrev": "^4.0.0"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      },
+      "engines": {
+        "node": "^20.17.0 || >=22.9.0"
+      }
+    },
     "node_modules/node-gyp/node_modules/proc-log": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-5.0.0.tgz",
-      "integrity": "sha512-Azwzvl90HaF0aCz1JrDdXQykFakSSNPaPoiZ9fm5qJIMHioDZEi7OAdRwSm6rSoPtY3Qutnm3L7ogmg3dc+wbQ==",
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-6.1.0.tgz",
+      "integrity": "sha512-iG+GYldRf2BQ0UDUAd6JQ/RwzaQy6mXmsk/IzlYyal4A4SNFw54MeH4/tLkF4I5WoWG9SQwuqWzS99jaFQHBuQ==",
       "dev": true,
       "license": "ISC",
       "engines": {
-        "node": "^18.17.0 || >=20.5.0"
+        "node": "^20.17.0 || >=22.9.0"
       }
     },
     "node_modules/node-gyp/node_modules/tar": {
-      "version": "7.5.12",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.12.tgz",
-      "integrity": "sha512-9TsuLcdhOn4XztcQqhNyq1KOwOOED/3k58JAvtULiYqbO8B/0IBAAIE1hj0Svmm58k27TmcigyDI0deMlgG3uw==",
+      "version": "7.5.22",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
+      "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "dependencies": {
@@ -29902,20 +29663,30 @@
         "node": ">=18"
       }
     },
+    "node_modules/node-gyp/node_modules/undici": {
+      "version": "6.29.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.29.1.tgz",
+      "integrity": "sha512-EvRlUt/QqAEvXdQeRMYUfwOQsfzpDztykrG2owGEE/rBOBoYv9uF39ZzsNDh4lTFHhTr2XOZjKkYgueD12ZmGA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
     "node_modules/node-gyp/node_modules/which": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/which/-/which-5.0.0.tgz",
-      "integrity": "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ==",
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/which/-/which-6.0.1.tgz",
+      "integrity": "sha512-oGLe46MIrCRqX7ytPUf66EAYvdeMIZYn3WaocqqKZAxrBpkqHfL/qvTyJ/bTk5+AqHCjXmrv3CEWgy368zhRUg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "isexe": "^3.1.1"
+        "isexe": "^4.0.0"
       },
       "bin": {
         "node-which": "bin/which.js"
       },
       "engines": {
-        "node": "^18.17.0 || >=20.5.0"
+        "node": "^20.17.0 || >=22.9.0"
       }
     },
     "node_modules/node-gyp/node_modules/yallist": {
@@ -30591,19 +30362,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/p-map": {
-      "version": "7.0.4",
-      "resolved": "https://registry.npmjs.org/p-map/-/p-map-7.0.4.tgz",
-      "integrity": "sha512-tkAQEw8ysMzmkhgw8k+1U/iPhWNhykKnSk4Rd5zLoPJCuJaGRPo6YposrZgaxHKzDHdDWWZvE/Sk7hsL2X/CpQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/p-memoize": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/p-memoize/-/p-memoize-8.0.0.tgz",
@@ -31109,6 +30867,40 @@
         "node": ">=8"
       }
     },
+    "node_modules/pkijs": {
+      "version": "3.4.2",
+      "resolved": "https://registry.npmjs.org/pkijs/-/pkijs-3.4.2.tgz",
+      "integrity": "sha512-LIy5RqLEzlliax2ANQNWvDLvhJ2CtlpJahiSvKtXnpMdKHhXXoLdpdnWqae/uaTyF3U5l5ARweW0kZp9B0s2VA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "workspaces": [
+        "website"
+      ],
+      "dependencies": {
+        "@noble/hashes": "1.8.0",
+        "asn1js": "^3.0.6",
+        "bytestreamjs": "^2.0.1",
+        "pvtsutils": "^1.3.6",
+        "pvutils": "^1.1.3",
+        "tslib": "^2.8.1"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
+    "node_modules/pkijs/node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/playwright": {
       "version": "1.58.2",
       "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
@@ -31258,6 +31050,36 @@
       "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==",
       "license": "MIT"
     },
+    "node_modules/postject": {
+      "version": "1.0.0-alpha.6",
+      "resolved": "https://registry.npmjs.org/postject/-/postject-1.0.0-alpha.6.tgz",
+      "integrity": "sha512-b9Eb8h2eVqNE8edvKdwqkrY6O7kAwmI8kcnBv1NScolYJbo59XUF0noFq+lxbC1yN20bmC0WBEbDC5H/7ASb0A==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "commander": "^9.4.0"
+      },
+      "bin": {
+        "postject": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/postject/node_modules/commander": {
+      "version": "9.5.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz",
+      "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "engines": {
+        "node": "^12.20.0 || >=14"
+      }
+    },
     "node_modules/prelude-ls": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
@@ -31529,6 +31351,26 @@
       ],
       "license": "MIT"
     },
+    "node_modules/pvtsutils": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/pvtsutils/-/pvtsutils-1.3.6.tgz",
+      "integrity": "sha512-PLgQXQ6H2FWCaeRak8vvk1GW462lMxB5s3Jm673N82zI4vqtVUPuZdffdZbPDFRoU8kAhItWFtPCWiPpp4/EDg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.8.1"
+      }
+    },
+    "node_modules/pvutils": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/pvutils/-/pvutils-1.2.0.tgz",
+      "integrity": "sha512-BbubeCEyTuQjVMakvJQ/Sxbc93F2pwmbsxONT/ZRrwU7Ua38d8unYTwXpTVLAKJ4BDuH9IGztCjQcd/N/39Dvg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
     "node_modules/qrcode": {
       "version": "1.5.4",
       "resolved": "https://registry.npmjs.org/qrcode/-/qrcode-1.5.4.tgz",
@@ -33120,6 +32962,70 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/rimraf": {
+      "version": "2.6.3",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.6.3.tgz",
+      "integrity": "sha512-mwqeW5XsA2qAejG46gYdENaxXjx9onRNCfn7L0duuP4hCuTIi/QO7PDK07KJfp1d+izWPrzEJDcSqBa0OZQriA==",
+      "deprecated": "Rimraf versions prior to v4 are no longer supported",
+      "dev": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "glob": "^7.1.3"
+      },
+      "bin": {
+        "rimraf": "bin.js"
+      }
+    },
+    "node_modules/rimraf/node_modules/brace-expansion": {
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/rimraf/node_modules/glob": {
+      "version": "7.2.3",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
+      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "dev": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.1.1",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      },
+      "engines": {
+        "node": "*"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/rimraf/node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "dev": true,
+      "license": "ISC",
+      "peer": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/roarr": {
       "version": "2.15.4",
       "resolved": "https://registry.npmjs.org/roarr/-/roarr-2.15.4.tgz",
@@ -33410,9 +33316,9 @@
       }
     },
     "node_modules/sanitize-filename": {
-      "version": "1.6.3",
-      "resolved": "https://registry.npmjs.org/sanitize-filename/-/sanitize-filename-1.6.3.tgz",
-      "integrity": "sha512-y/52Mcy7aw3gRm7IrcGDFx/bCk4AhRh2eI9luHOQM86nZsqwiRkkq2GekHXBBD+SmPidc8i2PqtYZl+pWJ8Oeg==",
+      "version": "1.6.4",
+      "resolved": "https://registry.npmjs.org/sanitize-filename/-/sanitize-filename-1.6.4.tgz",
+      "integrity": "sha512-9ZyI08PsvdQl2r/bBIGubpVdR3RR9sY6RDiWFPreA21C/EFlQhmgo20UZlNjZMMZNubusLhAQozkA0Od5J21Eg==",
       "dev": true,
       "license": "WTFPL OR ISC",
       "dependencies": {
@@ -34084,17 +33990,6 @@
         "node": ">=8.0.0"
       }
     },
-    "node_modules/smart-buffer": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
-      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 6.0.0",
-        "npm": ">= 3.0.0"
-      }
-    },
     "node_modules/smol-toml": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.0.tgz",
@@ -34108,46 +34003,6 @@
         "url": "https://github.com/sponsors/cyyynthia"
       }
     },
-    "node_modules/socks": {
-      "version": "2.8.7",
-      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.7.tgz",
-      "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "ip-address": "^10.0.1",
-        "smart-buffer": "^4.2.0"
-      },
-      "engines": {
-        "node": ">= 10.0.0",
-        "npm": ">= 3.0.0"
-      }
-    },
-    "node_modules/socks-proxy-agent": {
-      "version": "8.0.5",
-      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-8.0.5.tgz",
-      "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "agent-base": "^7.1.2",
-        "debug": "^4.3.4",
-        "socks": "^2.8.3"
-      },
-      "engines": {
-        "node": ">= 14"
-      }
-    },
-    "node_modules/socks-proxy-agent/node_modules/agent-base": {
-      "version": "7.1.4",
-      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
-      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 14"
-      }
-    },
     "node_modules/sonic-boom": {
       "version": "4.2.1",
       "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
@@ -34276,19 +34131,6 @@
         "node": ">=20.16.0"
       }
     },
-    "node_modules/ssri": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/ssri/-/ssri-12.0.0.tgz",
-      "integrity": "sha512-S7iGNosepx9RadX82oimUkvr0Ct7IjJbEbs4mJcTxst8um95J3sDYU1RBEOvdu6oL1Wek2ODI5i4MAw+dZ6cAQ==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "minipass": "^7.0.3"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
     "node_modules/stable-hash": {
       "version": "0.0.5",
       "resolved": "https://registry.npmjs.org/stable-hash/-/stable-hash-0.0.5.tgz",
@@ -35035,6 +34877,21 @@
         "node": ">=8"
       }
     },
+    "node_modules/temp": {
+      "version": "0.9.4",
+      "resolved": "https://registry.npmjs.org/temp/-/temp-0.9.4.tgz",
+      "integrity": "sha512-yYrrsWnrXMcdsnu/7YMYAofM1ktpL5By7vZhf15CrXijWWrEYZks5AXBudalfSWJLlnen/QUJUB5aoB0kqZUGA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "mkdirp": "^0.5.1",
+        "rimraf": "~2.6.2"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/temp-dir": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/temp-dir/-/temp-dir-2.0.0.tgz",
@@ -35056,6 +34913,20 @@
         "fs-extra": "^10.0.0"
       }
     },
+    "node_modules/temp/node_modules/mkdirp": {
+      "version": "0.5.6",
+      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz",
+      "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "minimist": "^1.2.6"
+      },
+      "bin": {
+        "mkdirp": "bin/cmd.js"
+      }
+    },
     "node_modules/terminal-link": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/terminal-link/-/terminal-link-2.1.1.tgz",
@@ -36038,32 +35909,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/unique-filename": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/unique-filename/-/unique-filename-4.0.0.tgz",
-      "integrity": "sha512-XSnEewXmQ+veP7xX2dS5Q4yZAvO40cBN2MWkJ7D/6sW4Dg6wYBNwM1Vrnz1FhH5AdeLIlUXRI9e28z1YZi71NQ==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "unique-slug": "^5.0.0"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
-    "node_modules/unique-slug": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/unique-slug/-/unique-slug-5.0.0.tgz",
-      "integrity": "sha512-9OdaqO5kwqR+1kVgHAhsp5vPNU0hnxRa26rBFNfNgM7M6pNtgzeBn3s/xbyCQL3dcjzOatcef6UUHpB/6MaETg==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "imurmurhash": "^0.1.4"
-      },
-      "engines": {
-        "node": "^18.17.0 || >=20.5.0"
-      }
-    },
     "node_modules/unique-string": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/unique-string/-/unique-string-2.0.0.tgz",
@@ -36247,6 +36092,35 @@
         "mkdirp": "bin/cmd.js"
       }
     },
+    "node_modules/unzipper": {
+      "version": "0.12.5",
+      "resolved": "https://registry.npmjs.org/unzipper/-/unzipper-0.12.5.tgz",
+      "integrity": "sha512-tXYOi9R57Uj/2Z25SOs5RRSzq886MBQj2gY8dPL+xl/kv6s6SvByoKfAtvfVeEuhntWDgjd2o9p2lb4TVPAz0A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bluebird": "~3.7.2",
+        "duplexer2": "~0.1.4",
+        "fs-extra": "11.3.1",
+        "graceful-fs": "^4.2.2",
+        "node-int64": "^0.4.0"
+      }
+    },
+    "node_modules/unzipper/node_modules/fs-extra": {
+      "version": "11.3.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.1.tgz",
+      "integrity": "sha512-eXvGGwZ5CL17ZSwHWd3bbgk7UUpF6IFHtP57NYYakPvHOs8GDgDe5KJI36jIJzDkJ6eJjuzRA8eBQb6SkKue0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
     "node_modules/update-browserslist-db": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -36460,22 +36334,6 @@
         "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc"
       }
     },
-    "node_modules/verror": {
-      "version": "1.10.1",
-      "resolved": "https://registry.npmjs.org/verror/-/verror-1.10.1.tgz",
-      "integrity": "sha512-veufcmxri4e3XSrT0xwfUR7kguIkaxBeosDg00yDWhk49wdwkSUrvvsm7nc75e1PUyvIeZj6nS8VQRYz2/S4Xg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "assert-plus": "^1.0.0",
-        "core-util-is": "1.0.2",
-        "extsprintf": "^1.2.0"
-      },
-      "engines": {
-        "node": ">=0.6.0"
-      }
-    },
     "node_modules/vfile": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz",
@@ -36883,6 +36741,20 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/webcrypto-core": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmjs.org/webcrypto-core/-/webcrypto-core-1.9.2.tgz",
+      "integrity": "sha512-gsXecm82UQNlTBURJGuqOWy1Ww08S3kZUcr3aOJS02Pk0xLtkfeUAVC0u0xhgdonFme80edSJUIJyuvL/7250Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@peculiar/asn1-schema": "^2.7.0",
+        "@peculiar/json-schema": "^1.1.12",
+        "@peculiar/utils": "^2.0.2",
+        "asn1js": "^3.0.10",
+        "tslib": "^2.8.1"
+      }
+    },
     "node_modules/webidl-conversions": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
@@ -37596,7 +37468,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -37614,6 +37486,7 @@
         "@getpaseo/protocol": "*",
         "@gorhom/bottom-sheet": "^5.2.14",
         "@gorhom/portal": "^1.0.14",
+        "@legendapp/list": "^3.7.1",
         "@marijn/find-cluster-break": "^1.0.2",
         "@mattermost/react-native-paste-input": "2.0.1",
         "@react-native-async-storage/async-storage": "2.2.0",
@@ -37626,13 +37499,14 @@
         "@tanstack/react-virtual": "^3.13.21",
         "@xterm/addon-clipboard": "^0.3.0-beta.213",
         "@xterm/addon-fit": "^0.12.0-beta.213",
-        "@xterm/addon-image": "^0.10.0-beta.213",
+        "@xterm/addon-image": "0.10.0-beta.331",
         "@xterm/addon-ligatures": "^0.11.0-beta.213",
         "@xterm/addon-search": "^0.17.0-beta.213",
+        "@xterm/addon-unicode-graphemes": "0.5.0-beta.330",
         "@xterm/addon-unicode11": "^0.10.0-beta.213",
         "@xterm/addon-web-links": "^0.13.0-beta.213",
-        "@xterm/addon-webgl": "0.20.0-beta.291",
-        "@xterm/xterm": "6.1.0-beta.292",
+        "@xterm/addon-webgl": "0.20.0-beta.329",
+        "@xterm/xterm": "6.1.0-beta.336",
         "buffer": "^6.0.3",
         "expo": "~57.0.30",
         "expo-asset": "~57.0.20",
@@ -37710,7 +37584,7 @@
         "@vitest/browser": "^4.1.7",
         "@vitest/browser-playwright": "^4.1.7",
         "@xterm/addon-serialize": "0.14.0",
-        "@xterm/headless": "^6.1.0-beta.213",
+        "@xterm/headless": "6.1.0-beta.334",
         "babel-preset-expo": "~57.0.16",
         "dotenv": "^17.2.3",
         "eas-cli": "^16.24.1",
@@ -38489,15 +38363,6 @@
         "@xterm/xterm": "^6.1.0-beta.213"
       }
     },
-    "packages/app/node_modules/@xterm/addon-image": {
-      "version": "0.10.0-beta.213",
-      "resolved": "https://registry.npmjs.org/@xterm/addon-image/-/addon-image-0.10.0-beta.213.tgz",
-      "integrity": "sha512-L3QxLkj8g8TioVea9p1oVze52Jr75rRZPPLm1tgZl0X2EGJGFHnQzE3QRsgmYWI7R5j3kwwi3MRAkOAgvOK8uA==",
-      "license": "MIT",
-      "peerDependencies": {
-        "@xterm/xterm": "^6.1.0-beta.213"
-      }
-    },
     "packages/app/node_modules/@xterm/addon-ligatures": {
       "version": "0.11.0-beta.213",
       "resolved": "https://registry.npmjs.org/@xterm/addon-ligatures/-/addon-ligatures-0.11.0-beta.213.tgz",
@@ -38541,34 +38406,6 @@
         "@xterm/xterm": "^6.1.0-beta.213"
       }
     },
-    "packages/app/node_modules/@xterm/addon-webgl": {
-      "version": "0.20.0-beta.291",
-      "resolved": "https://registry.npmjs.org/@xterm/addon-webgl/-/addon-webgl-0.20.0-beta.291.tgz",
-      "integrity": "sha512-gH7r5g8f2NWMhBtaeApuwLQTJmX4uq7zT0okjeNWkFAD0nxzbUPB+kt6sogZZ5K90XYPt2OLu/bhuvF6DmKqOQ==",
-      "license": "MIT",
-      "peerDependencies": {
-        "@xterm/xterm": "^6.1.0-beta.292"
-      }
-    },
-    "packages/app/node_modules/@xterm/headless": {
-      "version": "6.1.0-beta.213",
-      "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-6.1.0-beta.213.tgz",
-      "integrity": "sha512-D08E4Bl0HRhYZRL2o5PxD4FNQN9qXpI8QSw3CkKrsym5dtTRAqsynVYE8V8echQrxfb+EpR0CB5reM7tEGZ/fA==",
-      "dev": true,
-      "license": "MIT",
-      "workspaces": [
-        "addons/*"
-      ]
-    },
-    "packages/app/node_modules/@xterm/xterm": {
-      "version": "6.1.0-beta.292",
-      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.1.0-beta.292.tgz",
-      "integrity": "sha512-17zqK5tM/l6qeD7McF42OrEJ6w3XqJ2vFVKdWqu0cYLzdFqMWAHp2oFNc8Fj5DmqDSl1E1FZEg6IFflDllTvLA==",
-      "license": "MIT",
-      "workspaces": [
-        "addons/*"
-      ]
-    },
     "packages/app/node_modules/babel-plugin-syntax-hermes-parser": {
       "version": "0.36.1",
       "resolved": "https://registry.npmjs.org/babel-plugin-syntax-hermes-parser/-/babel-plugin-syntax-hermes-parser-0.36.1.tgz",
@@ -39800,12 +39637,13 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.14.0",
-        "@getpaseo/protocol": "0.14.0",
-        "@getpaseo/server": "0.14.0",
+        "@getpaseo/client": "0.15.4",
+        "@getpaseo/protocol": "0.15.4",
+        "@getpaseo/server": "0.15.4",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -40052,10 +39890,11 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
-        "@getpaseo/protocol": "0.14.0",
-        "@getpaseo/relay": "0.14.0",
+        "@getpaseo/protocol": "0.15.4",
+        "@getpaseo/relay": "0.15.4",
         "ws": "^8.20.0",
         "zod": "^4.4.3"
       },
@@ -40067,7 +39906,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -40082,7 +39921,6 @@
         "@types/node": "24.6.0",
         "@types/ws": "^8.5.14",
         "electron": "44.2.0",
-        "electron-builder": "26.8.1",
         "typescript": "5.9.3",
         "unzip-crx-3": "^0.2.0",
         "vitest": "^4.1.6",
@@ -40311,7 +40149,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -40357,7 +40195,8 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "@codemirror/language": "6.12.4",
         "@codemirror/legacy-modes": "^6.5.3",
@@ -40386,15 +40225,16 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^1.4.0",
         "i18next": "^26.3.0",
         "use-sync-external-store": "^1.6.0"
       },
       "devDependencies": {
-        "@getpaseo/client": "0.14.0",
-        "@getpaseo/protocol": "0.14.0",
+        "@getpaseo/client": "0.15.4",
+        "@getpaseo/protocol": "0.15.4",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.2.3",
@@ -40404,8 +40244,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.14.0",
-        "@getpaseo/protocol": "0.14.0",
+        "@getpaseo/client": "0.15.4",
+        "@getpaseo/protocol": "0.15.4",
         "react": ">=19.1.0 <20",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -40427,7 +40267,8 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "semver": "^7.8.5",
         "zod": "^4.4.3"
@@ -40454,7 +40295,8 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "@noble/ciphers": "^2.4.0",
         "@noble/curves": "^2.4.0",
@@ -40675,22 +40517,24 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.14.0",
+      "version": "0.15.4",
+      "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
         "@anthropic-ai/claude-agent-sdk": "0.3.246",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.14.0",
-        "@getpaseo/highlight": "0.14.0",
-        "@getpaseo/plugin": "0.14.0",
-        "@getpaseo/protocol": "0.14.0",
-        "@getpaseo/relay": "0.14.0",
+        "@getpaseo/client": "0.15.4",
+        "@getpaseo/highlight": "0.15.4",
+        "@getpaseo/plugin": "0.15.4",
+        "@getpaseo/protocol": "0.15.4",
+        "@getpaseo/relay": "0.15.4",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
         "@opencode/client": "2.0.10",
         "@xterm/addon-serialize": "0.14.0",
-        "@xterm/headless": "^6.0.0",
+        "@xterm/addon-unicode-graphemes": "0.5.0-beta.330",
+        "@xterm/headless": "6.1.0-beta.334",
         "ai": "5.0.78",
         "ajv": "^8.20.0",
         "bcryptjs": "^3.0.3",
@@ -41630,7 +41474,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -43240,7 +43084,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.14.0",
+      "version": "0.15.4",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"
diff --git a/package.json b/package.json
index 938497a362..a5473a8491 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [
@@ -131,6 +131,7 @@
     "concurrently": "^9.2.1",
     "cross-env": "^10.1.0",
     "electron": "44.2.0",
+    "electron-builder": "26.18.0",
     "expo-module-scripts": "^5.0.8",
     "get-port-cli": "^3.0.0",
     "js-yaml": "^4.1.1",
@@ -148,14 +149,21 @@
   "overrides": {
     "@codemirror/language": "6.12.4",
     "@codemirror/view": "6.43.6",
+    "@electron/get@^3.0.0": {
+      "semver@^6": "6.3.1"
+    },
     "expo": "~57.0.30",
     "expo-router": "~57.0.28",
     "lightningcss": "1.30.1",
+    "pkijs": "3.4.2",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",
     "react-native-gesture-handler": "~2.32.0",
     "react-native-reanimated": "4.5.5",
-    "react-native-worklets": "0.10.4"
+    "react-native-worklets": "0.10.4",
+    "tiny-async-pool": {
+      "semver@^5": "5.7.2"
+    }
   }
 }
diff --git a/packages/app/app.config.js b/packages/app/app.config.js
index eb7907e5ce..fecdcce31a 100644
--- a/packages/app/app.config.js
+++ b/packages/app/app.config.js
@@ -142,6 +142,7 @@ export default {
       searchPaths: ["../../node_modules", "./node_modules"],
     },
     plugins: [
+      "./modules/paseo-hardware-keyboard/app.plugin",
       "expo-router",
       withPasteInput,
       withAndroidScroll,
diff --git a/packages/app/app.config.test.ts b/packages/app/app.config.test.ts
index d0de16bd03..dde61f4560 100644
--- a/packages/app/app.config.test.ts
+++ b/packages/app/app.config.test.ts
@@ -94,3 +94,21 @@ it("allows all orientations on iPhone and iPad", async () => {
     await rm(root, { recursive: true, force: true });
   }
 }, 30_000);
+
+// Scene startup is the integration boundary for the iOS keyboard window.
+describe("hardware keyboard scene integration", () => {
+  it("installs observation after Expo creates the scene window and is idempotent", () => {
+    const {
+      configureHardwareKeyboardAppDelegate,
+    } = require("./modules/paseo-hardware-keyboard/app.plugin.js");
+    const source =
+      "import Expo\nclass Scene {\n  super.scene(scene, willConnectTo: session, options: connectionOptions)\n}\n";
+    const configured = configureHardwareKeyboardAppDelegate(source);
+    expect(configured).toContain("import PaseoHardwareKeyboard");
+    expect(configured).toContain("PaseoHardwareKeyboardWindow.observing(window)");
+    expect(configured.indexOf("super.scene")).toBeLessThan(
+      configured.indexOf(".observing(window)"),
+    );
+    expect(configureHardwareKeyboardAppDelegate(configured)).toBe(configured);
+  });
+});
diff --git a/packages/app/e2e/browser/acp-provider-catalog.spec.ts b/packages/app/e2e/browser/acp-provider-catalog.spec.ts
index ceca7489e3..0f01e02ded 100644
--- a/packages/app/e2e/browser/acp-provider-catalog.spec.ts
+++ b/packages/app/e2e/browser/acp-provider-catalog.spec.ts
@@ -28,7 +28,7 @@ const ACP_PROVIDER = {
 
 interface ProviderCatalogDaemonClient {
   getLastServerInfoMessage(): {
-    features?: { hopliteProvider?: boolean; plugins?: boolean };
+    features?: { fxProvider?: boolean; hopliteProvider?: boolean; plugins?: boolean };
   } | null;
   connect(): Promise<void>;
   close(): Promise<void>;
@@ -58,6 +58,31 @@ test.describe("ACP provider catalog", () => {
   });
 });
 
+test("adds fx from the catalog with only a config entry", async ({ page }, testInfo) => {
+  const client = await connectDaemonClient<ProviderCatalogDaemonClient>({
+    clientIdPrefix: "fx-catalog-e2e",
+  });
+  try {
+    expect(client.getLastServerInfoMessage()?.features?.fxProvider).toBe(true);
+    await client.patchDaemonConfig({ removeProviders: ["fx"] });
+    await gotoAppShell(page);
+    await openSettings(page);
+    await openSettingsHost(page, getServerId());
+    await openSettingsHostSection(page, getServerId(), "providers");
+    await openAddProviderArea(page);
+
+    await findAcpCatalogProvider(page, "fx");
+    await page.screenshot({ path: testInfo.outputPath("fx-catalog.png") });
+    await installAcpCatalogProvider(page, "fx");
+    await expectProviderInstalledInSettings(page, "fx");
+    await page.screenshot({ path: testInfo.outputPath("fx-installed.png") });
+    expect((await client.getDaemonConfig()).config.providers?.fx).toEqual({ enabled: true });
+  } finally {
+    await client.patchDaemonConfig({ removeProviders: ["fx"] }).catch(() => undefined);
+    await client.close().catch(() => undefined);
+  }
+});
+
 for (const theme of ["light", "dark"] as const) {
   test(`adds Hoplite from the catalog in ${theme} theme`, async ({ page }, testInfo) => {
     const client = await connectDaemonClient<ProviderCatalogDaemonClient>({
diff --git a/packages/app/e2e/browser/add-project-flow.spec.ts b/packages/app/e2e/browser/add-project-flow.spec.ts
index 5770c3be9d..bce5adcaaf 100644
--- a/packages/app/e2e/browser/add-project-flow.spec.ts
+++ b/packages/app/e2e/browser/add-project-flow.spec.ts
@@ -5,6 +5,7 @@ import path from "node:path";
 import { test, expect } from "../support/fixtures";
 import {
   addProjectFlow,
+  chooseAddHostFromProjectFlow,
   addProjectFlowBack,
   addProjectFlowHost,
   addProjectFlowInput,
@@ -14,11 +15,14 @@ import {
   expectNewWorkspaceForAddedProject,
   expectAddProjectResultVisible,
   navigateAddProjectResults,
+  navigateAndDismissAddProject,
+  watchAddProjectRenderWarnings,
   openAddProjectFlow,
   openAddProjectHostSelection,
 } from "../support/helpers/add-project-flow";
 import { gotoAppShell } from "../support/helpers/app";
 import {
+  disconnectAllHostsAndReload,
   addConnectedHostAndReload,
   addConnectedHostsAndReload,
   addOfflineHostAndReload,
@@ -69,6 +73,19 @@ async function expectProjectHasNoWorkspaces(projectId: string): Promise<void> {
 test.describe("Add Project command-center flow", () => {
   test.describe.configure({ timeout: 180_000 });
 
+  test("Add host replaces the project dialog when no hosts are connected", async ({ page }) => {
+    await gotoAppShell(page);
+    await disconnectAllHostsAndReload(page);
+    await openAddProjectHostSelection(page);
+    const originalUrl = page.url();
+    await chooseAddHostFromProjectFlow(page);
+    await expect(addProjectFlow(page)).toBeHidden();
+    await expect(
+      page.getByRole("button", { name: "Direct connection", exact: true }),
+    ).toBeVisible();
+    await expect(page).toHaveURL(originalUrl);
+  });
+
   test("method selection shows the daemon's available project sources without search", async ({
     page,
   }) => {
@@ -131,6 +148,7 @@ test.describe("Add Project command-center flow", () => {
     test("Escape and Back restore searchable page input before closing at the root", async ({
       page,
     }) => {
+      const renderWarnings = watchAddProjectRenderWarnings(page);
       await gotoAppShell(page);
       await addConnectedHostAndReload(page, {
         serverId: secondaryHost.serverId,
@@ -168,8 +186,9 @@ test.describe("Add Project command-center flow", () => {
 
       await page.keyboard.press("Escape");
       await expectAddProjectPage(page, "host");
-      await page.keyboard.press("Escape");
+      await navigateAndDismissAddProject(page);
       await expect(addProjectFlow(page)).not.toBeVisible();
+      expect(renderWarnings).toEqual([]);
     });
 
     test("New directory creates a Project on the selected remote host", async ({ page }) => {
diff --git a/packages/app/e2e/browser/agent-message-submission.spec.ts b/packages/app/e2e/browser/agent-message-submission.spec.ts
index dcf872f8be..24f26f1c44 100644
--- a/packages/app/e2e/browser/agent-message-submission.spec.ts
+++ b/packages/app/e2e/browser/agent-message-submission.spec.ts
@@ -235,6 +235,7 @@ async function beginTimelineRowStabilityCheck(
       lastTop: initialRow.getBoundingClientRect().top,
       largestDownwardShift: 0,
       sawMissing: false,
+      sawHidden: false,
     };
     const windowState = window as unknown as Record<string, unknown>;
     windowState.__messageSubmissionTimelineRowStability = state;
@@ -245,6 +246,9 @@ async function beginTimelineRowStabilityCheck(
         requestAnimationFrame(checkFrame);
         return;
       }
+      if (!initialRow.checkVisibility({ opacityProperty: true, visibilityProperty: true })) {
+        state.sawHidden = true;
+      }
       const top = initialRow.getBoundingClientRect().top;
       state.largestDownwardShift = Math.max(state.largestDownwardShift, top - state.lastTop);
       state.lastTop = top;
@@ -257,14 +261,24 @@ async function beginTimelineRowStabilityCheck(
     const result = await page.evaluate(() => {
       const windowState = window as unknown as Record<string, unknown>;
       const state = windowState.__messageSubmissionTimelineRowStability as
-        | { active: boolean; largestDownwardShift: number; sawMissing: boolean }
+        | {
+            active: boolean;
+            largestDownwardShift: number;
+            sawMissing: boolean;
+            sawHidden: boolean;
+          }
         | undefined;
       if (!state) throw new Error("Timeline-row stability check was not started");
       state.active = false;
       delete windowState.__messageSubmissionTimelineRowStability;
-      return { largestDownwardShift: state.largestDownwardShift, sawMissing: state.sawMissing };
+      return {
+        largestDownwardShift: state.largestDownwardShift,
+        sawMissing: state.sawMissing,
+        sawHidden: state.sawHidden,
+      };
     });
     expect(result.sawMissing).toBe(false);
+    expect(result.sawHidden).toBe(false);
     expect(result.largestDownwardShift).toBeLessThanOrEqual(2);
   };
 }
@@ -1178,7 +1192,13 @@ test.describe("Agent message submission", () => {
     test.setTimeout(120_000);
     const toasts = await recordPanelToasts(page);
     const pending = await beginDraftCreateSubmission(page, draftCreateScenario);
+    // The created agent takes over the draft's timeline: the same row stays mounted and painted.
+    const finishTimelineRowStabilityCheck = await beginTimelineRowStabilityCheck(
+      page,
+      pending.userMessage,
+    );
     await completeDraftCreateSubmission(page, draftCreateScenario, pending);
+    await finishTimelineRowStabilityCheck();
     // A chat this client just created is current by construction; it is never out of date.
     await toasts.expectNeverShown("agent-updating-toast");
   });
diff --git a/packages/app/e2e/browser/agent-profile-modeless-preferences.spec.ts b/packages/app/e2e/browser/agent-profile-modeless-preferences.spec.ts
index a10afd2cca..97370bb7c8 100644
--- a/packages/app/e2e/browser/agent-profile-modeless-preferences.spec.ts
+++ b/packages/app/e2e/browser/agent-profile-modeless-preferences.spec.ts
@@ -62,7 +62,7 @@ async function readProviderFeaturePreferences(page: Page, provider: string): Pro
       const raw = localStorage.getItem(preferencesKey);
       if (!raw) return null;
       const preferences = JSON.parse(raw) as FormPreferences;
-      return preferences.providerPreferences?.[providerId]?.featureValues ?? null;
+      return preferences.providerPreferences?.[providerId]?.options ?? null;
     },
     { preferencesKey: CREATE_AGENT_PREFERENCES_KEY, providerId: provider },
   );
@@ -145,7 +145,7 @@ test.describe("Agent profiles repair modeless provider preferences", () => {
         provider: featureProviderId,
         model: featureModelId,
         modeId: "bypassPermissions",
-        featureValues: { fast_mode: true },
+        options: { fast_mode: true },
       },
     ]);
     const provider = await seedModelProvider({
@@ -181,7 +181,7 @@ test.describe("Agent profiles repair modeless provider preferences", () => {
       expect(createAgentRequest).toMatchObject({
         config: {
           provider: featureProviderId,
-          featureValues: { fast_mode: true },
+          providerOptions: { fast_mode: true },
         },
       });
     } finally {
diff --git a/packages/app/e2e/browser/agent-timeline-resume.spec.ts b/packages/app/e2e/browser/agent-timeline-resume.spec.ts
index 8a093feffc..c3054b2ebc 100644
--- a/packages/app/e2e/browser/agent-timeline-resume.spec.ts
+++ b/packages/app/e2e/browser/agent-timeline-resume.spec.ts
@@ -11,12 +11,21 @@ import {
   seedLongMockAgentTimeline,
 } from "../support/helpers/timeline-pagination";
 import {
+  answerFreshnessCheck,
   commitTimelineTurnsWhileDisconnected,
   disconnectViewedTimeline,
-  expectOneResumeCheckWithoutTail,
+  expectResumeAnsweredWithoutFetch,
   expectResumeOverflowFallsBackToOneTail,
+  hideTabAndReturn,
   rememberTimelineRequestCounts,
+  releaseHeldCatchUp,
+  restoreUnchangedViewedTimeline,
+  restoreViewedTimelineHoldingCatchUp,
   restoreViewedTimelineWithHeldResponse,
+  reopenWithFreshnessCheckUnanswered,
+  waitForResumeAnswer,
+  reopenAppWatchingForUpdatingToast,
+  watchForUpdatingToast,
 } from "../support/helpers/timeline-resume";
 
 test.describe("Agent timeline resume", () => {
@@ -42,7 +51,9 @@ test.describe("Agent timeline resume", () => {
     }
   });
 
-  test("an unchanged resume leaves a scrolled-up timeline untouched", async ({ page }) => {
+  test("returning to an unchanged chat shows no update and leaves it untouched", async ({
+    page,
+  }) => {
     test.setTimeout(120_000);
     const gate = await installDaemonWebSocketGate(page);
     const agent = await seedLongMockAgentTimeline({ turns: 30 });
@@ -51,13 +62,86 @@ test.describe("Agent timeline resume", () => {
       await expectTimelinePromptVisible(page, agent.newestPrompt);
       await scrollTimelinePromptIntoView(page, agent.initialTailAnchorPrompt);
       const presentation = await rememberTimelinePresentation(page, agent.initialTailAnchorPrompt);
+
+      await test.step("back from the background", async () => {
+        const requests = rememberTimelineRequestCounts(gate);
+        const expectNoUpdatingToast = await watchForUpdatingToast(page);
+
+        await hideTabAndReturn(page);
+        await waitForResumeAnswer(gate, requests);
+
+        await expectNoUpdatingToast();
+        await expectTimelinePresentationUnchanged(page, presentation);
+        expectResumeAnsweredWithoutFetch(gate, requests);
+      });
+
+      await test.step("back from a dropped connection", async () => {
+        const requests = rememberTimelineRequestCounts(gate);
+        const expectNoUpdatingToast = await watchForUpdatingToast(page);
+
+        await disconnectViewedTimeline(page, gate);
+        await restoreUnchangedViewedTimeline(page, gate);
+
+        await expectNoUpdatingToast();
+        await expectTimelinePresentationUnchanged(page, presentation);
+        expectResumeAnsweredWithoutFetch(gate, requests);
+      });
+
+      await test.step("back from reopening the app", async () => {
+        const requests = rememberTimelineRequestCounts(gate);
+
+        const expectNoUpdatingToast = await reopenAppWatchingForUpdatingToast(page);
+        await waitForResumeAnswer(gate, requests);
+        await expectTimelinePromptVisible(page, agent.newestPrompt);
+
+        await expectNoUpdatingToast();
+        expectResumeAnsweredWithoutFetch(gate, requests);
+      });
+    } finally {
+      gate.restore();
+      await agent.cleanup();
+    }
+  });
+
+  test("opening cached history reports an unanswered check until the daemon answers", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    const gate = await installDaemonWebSocketGate(page);
+    const agent = await seedLongMockAgentTimeline({ turns: 3 });
+    try {
+      await openAgentTimeline(page, agent);
+      await expectTimelinePromptVisible(page, agent.newestPrompt);
       const requests = rememberTimelineRequestCounts(gate);
 
+      await reopenWithFreshnessCheckUnanswered(page, gate, agent);
+      await answerFreshnessCheck(page, gate);
+
+      expectResumeAnsweredWithoutFetch(gate, requests);
+    } finally {
+      gate.restore();
+      await agent.cleanup();
+    }
+  });
+
+  test("returning to a changed chat reports the update and shows the new messages", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    const gate = await installDaemonWebSocketGate(page);
+    const agent = await seedLongMockAgentTimeline({ turns: 3 });
+    try {
+      await openAgentTimeline(page, agent);
+      await expectTimelinePromptVisible(page, agent.newestPrompt);
+      const presentation = await rememberTimelinePresentation(page, agent.newestPrompt);
+
       await disconnectViewedTimeline(page, gate);
-      await restoreViewedTimelineWithHeldResponse(page, gate);
+      const background = await commitTimelineTurnsWhileDisconnected(agent, 1);
+      await restoreViewedTimelineHoldingCatchUp(page, gate);
 
       await expectTimelinePresentationUnchanged(page, presentation);
-      expectOneResumeCheckWithoutTail(gate, requests);
+      await releaseHeldCatchUp(page, gate);
+      await expectTimelinePromptVisible(page, background.newestPrompt);
     } finally {
       gate.restore();
       await agent.cleanup();
diff --git a/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts b/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts
index 2f3fcab53a..b95e945056 100644
--- a/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts
+++ b/packages/app/e2e/browser/agent-timeline-sync-retry.spec.ts
@@ -6,6 +6,7 @@ import {
   seedLongMockAgentTimeline,
 } from "../support/helpers/timeline-pagination";
 import {
+  commitTimelineTurnsWhileDisconnected,
   disconnectViewedTimeline,
   restoreViewedTimelineWithHeldResponse,
 } from "../support/helpers/timeline-resume";
@@ -18,11 +19,14 @@ test.describe("Agent timeline sync retry", () => {
     const gate = await installDaemonWebSocketGate(page);
     const agent = await seedLongMockAgentTimeline({ turns: 2 });
     try {
+      gate.holdNextClientRequest("clear_agent_attention");
       await openAgentTimeline(page, agent);
       await expectTimelinePromptVisible(page, agent.newestPrompt);
+      await gate.waitForHeldClientRequest();
 
       gate.failTimelineResponses(agent.agentId);
       await disconnectViewedTimeline(page, gate);
+      await commitTimelineTurnsWhileDisconnected(agent, 1);
       await restoreViewedTimelineWithHeldResponse(page, gate);
 
       const callout = page.getByTestId("agent-timeline-sync-error");
diff --git a/packages/app/e2e/browser/agent-turn-end.spec.ts b/packages/app/e2e/browser/agent-turn-end.spec.ts
new file mode 100644
index 0000000000..d5f4ef26d4
--- /dev/null
+++ b/packages/app/e2e/browser/agent-turn-end.spec.ts
@@ -0,0 +1,525 @@
+import type { Page } from "@playwright/test";
+import { expect, test as baseTest } from "../support/fixtures";
+import { expectAgentIdle } from "../support/helpers/agent-stream";
+import { submitMessage } from "../support/helpers/composer";
+import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
+import {
+  openAgentRoute,
+  seedMockAgentWorkspace,
+  type MockAgentWorkspace,
+} from "../support/helpers/mock-agent";
+
+// A turn ends with its final reply, `turn_completed`, and the idle status snapshot arriving
+// within a few milliseconds of each other. These tests hold all three, let the running
+// turn paint, then release them together and sample every painted frame.
+
+interface Box {
+  top: number;
+  height: number;
+}
+
+interface TurnEndFrame {
+  at: number;
+  running: boolean;
+  replyLength: number;
+  footer: Box | null;
+  footerText: string;
+  elapsed: string | null;
+  userRow: Box | null;
+  replyVisible: boolean;
+}
+
+declare global {
+  interface Window {
+    __turnEndFrames?: { active: boolean; frames: TurnEndFrame[] };
+  }
+}
+
+const test = baseTest.extend<{ agent: MockAgentWorkspace }>({
+  agent: async ({ page: _page }, provide) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "turn-end-",
+      title: "Turn end",
+      initialPrompt: "emit 4 tool agent stream updates",
+    });
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await provide(agent);
+    await agent.cleanup();
+  },
+});
+
+async function recordTurnEndFrames(
+  page: Page,
+  input: { prompt: string; reply: string | null },
+): Promise<void> {
+  await page.evaluate(({ prompt, reply }) => {
+    const state = { active: true, frames: [] as TurnEndFrame[] };
+    const isVisible = (element: Element | null | undefined) => Boolean(element?.checkVisibility());
+    const boxOf = (element: Element | null | undefined): Box | null => {
+      if (!element || !isVisible(element)) return null;
+      const rect = element.getBoundingClientRect();
+      return rect.height > 0 ? { top: rect.top, height: rect.height } : null;
+    };
+    const sample = () => {
+      const viewport = Array.from(
+        document.querySelectorAll('[data-testid="agent-chat-scroll"]'),
+      ).find((candidate) => isVisible(candidate));
+      const footer = Array.from(viewport?.querySelectorAll('[data-testid="turn-footer"]') ?? [])
+        .map((element) => ({ element, box: boxOf(element) }))
+        .filter((row): row is { element: Element; box: Box } => row.box !== null)
+        .sort((left, right) => left.box.top - right.box.top)
+        .at(-1);
+      const elapsed =
+        viewport?.querySelector('[data-testid="turn-working-elapsed"]')?.textContent ?? null;
+      const userRow = Array.from(
+        viewport?.querySelectorAll('[data-testid="user-message"]') ?? [],
+      ).find((candidate) => candidate.textContent?.includes(prompt));
+      const replyRow =
+        reply === null
+          ? undefined
+          : Array.from(viewport?.querySelectorAll('[data-testid="assistant-message"]') ?? []).find(
+              (candidate) => candidate.textContent?.includes(reply),
+            );
+      const assistantRows = Array.from(
+        viewport?.querySelectorAll('[data-testid="assistant-message"]') ?? [],
+      );
+      state.frames.push({
+        at: performance.now(),
+        running: Boolean(viewport?.querySelector('[data-testid="turn-working-indicator"]')),
+        replyLength: assistantRows.reduce((sum, row) => sum + (row.textContent?.length ?? 0), 0),
+        footer: footer?.box ?? null,
+        footerText: (footer?.element.textContent ?? "").replace(elapsed ?? "", ""),
+        elapsed,
+        userRow: boxOf(userRow),
+        replyVisible: boxOf(replyRow) !== null,
+      });
+      if (state.active) requestAnimationFrame(() => setTimeout(sample, 0));
+    };
+    window.__turnEndFrames = state;
+    requestAnimationFrame(() => setTimeout(sample, 0));
+  }, input);
+}
+
+async function recordPaintsFor(page: Page, durationMs: number): Promise<void> {
+  const until = await page.evaluate((duration) => performance.now() + duration, durationMs);
+  await expect
+    .poll(() => page.evaluate(() => window.__turnEndFrames?.frames.at(-1)?.at ?? 0))
+    .toBeGreaterThanOrEqual(until);
+}
+
+async function stopRecording(page: Page): Promise<TurnEndFrame[]> {
+  return page.evaluate(() => {
+    const state = window.__turnEndFrames;
+    if (!state) throw new Error("Turn end frames were not recorded");
+    state.active = false;
+    return state.frames;
+  });
+}
+
+async function recordTurnEnd(
+  page: Page,
+  agent: MockAgentWorkspace,
+  input: { prompt: string; reply: string | null },
+): Promise<TurnEndFrame[]> {
+  const gate = await installDaemonWebSocketGate(page);
+  await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+  await expectAgentIdle(page);
+
+  if (input.reply === null) {
+    gate.setAgentStreamItemSuppressed("assistant_message", true);
+  } else {
+    gate.holdNextAgentStreamItem("assistant_message");
+  }
+  gate.holdNextAgentStreamEvent("turn_completed");
+  // The daemon sends more than one idle snapshot; hold the first and drop the rest until release.
+  gate.holdNextAgentUpdate(agent.agentId, "idle");
+  gate.setServerMessageSuppressed("agent_update", true);
+  await recordTurnEndFrames(page, input);
+  await submitMessage(page, input.prompt);
+  await Promise.all([
+    input.reply === null ? Promise.resolve() : gate.waitForHeldAgentStreamItem("assistant_message"),
+    gate.waitForHeldAgentStreamEvent("turn_completed"),
+    gate.waitForHeldAgentUpdate(agent.agentId, "idle"),
+  ]);
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await recordPaintsFor(page, 200);
+
+  if (input.reply !== null) gate.releaseHeldAgentStreamItem("assistant_message");
+  gate.releaseHeldAgentStreamEvent("turn_completed");
+  gate.releaseHeldAgentUpdate(agent.agentId, "idle");
+  gate.setServerMessageSuppressed("agent_update", false);
+  await expectAgentIdle(page);
+  await recordPaintsFor(page, 300);
+  return stopRecording(page);
+}
+
+function describeFrames(frames: TurnEndFrame[]): string {
+  return frames
+    .map(
+      (frame, index) =>
+        `${index}: ${frame.running ? "running " : "complete"} footer=${
+          frame.footer ? `${frame.footer.top.toFixed(1)}+${frame.footer.height.toFixed(1)}` : "none"
+        } timer=${frame.elapsed ?? "none"} prompt=${frame.userRow?.top.toFixed(1) ?? "none"} reply=${frame.replyVisible}`,
+    )
+    .join("\n");
+}
+
+function expectSteadyTurnEnd(frames: TurnEndFrame[], input: { reply: string | null }): void {
+  const firstRunning = frames.findIndex((frame) => frame.running && frame.footer !== null);
+  const firstComplete = frames.findIndex((frame, index) => index > firstRunning && !frame.running);
+  const record = `frames:\n${describeFrames(frames)}`;
+  expect(firstRunning, record).toBeGreaterThanOrEqual(0);
+  expect(firstComplete, record).toBeGreaterThan(firstRunning);
+
+  const transition = frames.slice(firstRunning);
+  const runningHeight = transition[0].footer?.height;
+  expect(
+    transition.map((frame) => frame.footer?.height ?? null),
+    `the footer must stay painted at one height\n${record}`,
+  ).toEqual(transition.map(() => runningHeight));
+  if (input.reply !== null) {
+    expect(
+      frames.slice(firstComplete).every((frame) => frame.replyVisible),
+      `a completed turn must show its reply in the same frame\n${record}`,
+    ).toBe(true);
+  }
+  // Tool rows land while the turn runs; only the turn end itself must be one step.
+  const ending = frames.slice(firstComplete - 1);
+  const promptMoves = ending
+    .slice(1)
+    .filter((frame, index) => frame.userRow?.top !== ending[index].userRow?.top);
+  expect(
+    promptMoves.length,
+    `the prompt must move at most once as the turn ends\n${record}`,
+  ).toBeLessThanOrEqual(1);
+}
+
+interface ReturnedTurn {
+  frames: TurnEndFrame[];
+  reconnectedAt: number;
+  finalReplyLength: number;
+}
+
+// The agent finishes while the socket is down, then the catch-up is held so the idle status
+// reaches the chat first. Painted frames are sampled from the running footer until everything
+// has settled.
+async function returnAfterTurnFinished(input: {
+  page: Page;
+  agent: MockAgentWorkspace;
+  prompt: string;
+  leaveWhile: (gate: DaemonWebSocketGate) => Promise<void>;
+}): Promise<ReturnedTurn> {
+  const { page, agent, prompt, leaveWhile } = input;
+  const gate = await installDaemonWebSocketGate(page);
+  await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+  await expect(page.getByRole("textbox", { name: "Message agent..." })).toBeVisible();
+
+  await recordTurnEndFrames(page, { prompt, reply: "" });
+  await leaveWhile(gate);
+  gate.holdTimelineResponses(agent.agentId);
+  const reconnectedAt = await page.evaluate(() => performance.now());
+  gate.restore();
+  await gate.waitForHeldTimelineResponse();
+  await expectAgentIdle(page);
+
+  await recordPaintsFor(page, 2_000);
+  gate.releaseHeldTimelineResponses();
+  await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+  await expect(page.getByTestId("turn-footer").last()).toBeVisible();
+  await recordPaintsFor(page, 500);
+  const frames = await stopRecording(page);
+  return { frames, reconnectedAt, finalReplyLength: frames.at(-1)?.replyLength ?? 0 };
+}
+
+type DaemonWebSocketGate = Awaited<ReturnType<typeof installDaemonWebSocketGate>>;
+
+async function leaveWithOnlyThePromptOnScreen(
+  page: Page,
+  agent: MockAgentWorkspace,
+  gate: DaemonWebSocketGate,
+  prompt: string,
+): Promise<void> {
+  gate.setAgentStreamItemSuppressed("assistant_message", true);
+  gate.holdNextAgentStreamEvent("turn_completed");
+  gate.holdNextAgentUpdate(agent.agentId, "idle");
+  gate.setServerMessageSuppressed("agent_update", true);
+  await submitMessage(page, prompt);
+  await Promise.all([
+    gate.waitForHeldAgentStreamEvent("turn_completed"),
+    gate.waitForHeldAgentUpdate(agent.agentId, "idle"),
+  ]);
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await gate.drop();
+  await agent.client.waitForFinish(agent.agentId, 15_000);
+  gate.setAgentStreamItemSuppressed("assistant_message", false);
+  gate.setServerMessageSuppressed("agent_update", false);
+}
+
+async function leaveWithAPartialReplyOnScreen(
+  page: Page,
+  agent: MockAgentWorkspace,
+  gate: DaemonWebSocketGate,
+  prompt: string,
+): Promise<void> {
+  await agent.client.sendAgentMessage(agent.agentId, prompt);
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expect(page.getByTestId("assistant-message").first()).toBeVisible();
+  await gate.drop();
+  await agent.client.waitForFinish(agent.agentId, 30_000);
+}
+
+function elapsedSeconds(frame: TurnEndFrame): number {
+  const units: Record<string, number> = { h: 3600, m: 60, s: 1 };
+  return [...(frame.elapsed ?? "").matchAll(/(\d+)([hms])/g)].reduce(
+    (total, [, value, unit]) => total + Number(value) * units[unit],
+    0,
+  );
+}
+
+function expectFooterUnchangedUntilMessagesLand(
+  { frames, reconnectedAt }: ReturnedTurn,
+  record: string,
+): void {
+  const held = frames.slice(
+    frames.findIndex((frame) => frame.at >= reconnectedAt),
+    frames.findIndex((frame) => frame.at >= reconnectedAt && !frame.running),
+  );
+  expect(
+    held.length,
+    `the running footer must hold until the messages land\n${record}`,
+  ).toBeGreaterThan(0);
+  expect(
+    new Set(held.map((frame) => `${frame.footer?.top}+${frame.footer?.height}`)).size,
+    `the held footer must not move or resize\n${record}`,
+  ).toBe(1);
+  expect(
+    new Set(held.map((frame) => frame.footerText)).size,
+    `the held footer's content must not change\n${record}`,
+  ).toBe(1);
+  expect(
+    held.filter((frame) => frame.elapsed === null).map((frame) => frame.at),
+    `the timer must stay on screen\n${record}`,
+  ).toEqual([]);
+  const seconds = held.map(elapsedSeconds);
+  expect(seconds, `the timer must keep counting up\n${record}`).toEqual(
+    seconds.toSorted((left, right) => left - right),
+  );
+}
+
+function expectReturnLandsWhole(returned: ReturnedTurn): void {
+  const { frames, finalReplyLength } = returned;
+  const record = `frames:\n${describeFrames(frames)}`;
+  const firstRunning = frames.findIndex((frame) => frame.running && frame.footer !== null);
+  expect(firstRunning, record).toBeGreaterThanOrEqual(0);
+  const fromRunning = frames.slice(firstRunning);
+
+  expect(
+    fromRunning.filter((frame) => frame.footer === null).map((frame) => frame.at),
+    `the footer must never disappear\n${record}`,
+  ).toEqual([]);
+
+  const completed = fromRunning.filter((frame) => !frame.running);
+  expect(completed.length, record).toBeGreaterThan(0);
+  // The first Markdown on a page paints an empty row until the web parser loads. Only text that
+  // is present and short of the final reply is stale.
+  expect(
+    completed
+      .filter((frame) => frame.replyLength > 0 && frame.replyLength !== finalReplyLength)
+      .map((frame) => frame.at),
+    `a completed footer must never sit under stale messages\n${record}`,
+  ).toEqual([]);
+
+  expectFooterUnchangedUntilMessagesLand(returned, record);
+}
+
+async function withFirstTurnAgent(
+  model: string,
+  run: (agent: MockAgentWorkspace) => Promise<void>,
+): Promise<void> {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "turn-return-",
+    title: "Turn return",
+    model,
+  });
+  try {
+    await run(agent);
+  } finally {
+    await agent.cleanup();
+  }
+}
+
+test.describe("Returning to a turn that finished while away", () => {
+  test("keeps the running footer until the messages land when only the prompt was on screen", async ({
+    page,
+  }) => {
+    await withFirstTurnAgent("e2e-fast-stream", async (agent) => {
+      const prompt = "emit 1 coalesced agent stream updates";
+      const returned = await returnAfterTurnFinished({
+        page,
+        agent,
+        prompt,
+        leaveWhile: (gate) => leaveWithOnlyThePromptOnScreen(page, agent, gate, prompt),
+      });
+      expectReturnLandsWhole(returned);
+    });
+  });
+
+  test("keeps the running footer until the messages land under a partial reply", async ({
+    page,
+  }) => {
+    await withFirstTurnAgent("ten-second-stream", async (agent) => {
+      const prompt = "Return partial prompt";
+      const returned = await returnAfterTurnFinished({
+        page,
+        agent,
+        prompt,
+        leaveWhile: (gate) => leaveWithAPartialReplyOnScreen(page, agent, gate, prompt),
+      });
+      expectReturnLandsWhole(returned);
+    });
+  });
+});
+
+test.describe("Turn end", () => {
+  test("ends a plain reply without moving or dropping its footer", async ({ page, agent }) => {
+    const input = { prompt: "emit 1 coalesced agent stream updates", reply: "stress-update-0" };
+    expectSteadyTurnEnd(await recordTurnEnd(page, agent, input), input);
+  });
+
+  test("ends a tool turn with its reply and completed footer together", async ({ page, agent }) => {
+    const input = { prompt: "emit 3 tool agent stream updates", reply: "Completed 3 commands" };
+    expectSteadyTurnEnd(await recordTurnEnd(page, agent, input), input);
+  });
+
+  test("keeps the footer height when a turn ends on a tool call", async ({ page, agent }) => {
+    const input = { prompt: "emit 2 tool agent stream updates", reply: null };
+    expectSteadyTurnEnd(await recordTurnEnd(page, agent, input), input);
+  });
+});
+
+async function expectTimingInsideFooter(page: Page): Promise<void> {
+  const label = page.getByRole("button", { name: /^Worked for/ }).last();
+  const paintedLines = await label.getByTestId("turn-footer-timing-label").evaluate((element) => {
+    const labelBounds = element.parentElement!.getBoundingClientRect();
+    const rowBounds = element.closest('[data-testid="turn-footer"]')!.getBoundingClientRect();
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+    const lines: boolean[] = [];
+    while (walker.nextNode()) {
+      const range = document.createRange();
+      range.selectNodeContents(walker.currentNode);
+      for (const rect of range.getClientRects()) {
+        lines.push(
+          rect.left >= Math.max(rowBounds.left, labelBounds.left) - 0.5 &&
+            rect.right <= Math.min(rowBounds.right, labelBounds.right) + 0.5 &&
+            rect.top >= Math.max(rowBounds.top, labelBounds.top) - 0.5 &&
+            rect.bottom <= Math.min(rowBounds.bottom, labelBounds.bottom) + 0.5,
+        );
+      }
+    }
+    return lines;
+  });
+  expect(paintedLines.length).toBeGreaterThan(0);
+  expect(paintedLines.every(Boolean)).toBe(true);
+}
+
+async function expectFooterWithinWidth(page: Page, width: number): Promise<void> {
+  const footer = page.getByTestId("turn-footer").last();
+  await footer.evaluate((element, availableWidth) => {
+    element.style.width = `${availableWidth}px`;
+  }, width);
+  const label = page.getByRole("button", { name: /^Worked for/ }).last();
+  await expect(label).toBeVisible();
+  await expectTimingInsideFooter(page);
+  const controls = footer.getByRole("button", { name: /Copy turn|Fork chat/ });
+  const before = await controls.evaluateAll((elements) =>
+    elements.map((element) => {
+      const rect = element.getBoundingClientRect();
+      return { x: rect.x, y: rect.y };
+    }),
+  );
+  const footerBefore = await footer.boundingBox();
+  const labelBefore = await label.boundingBox();
+  await label.hover({ position: { x: labelBefore!.width - 2, y: labelBefore!.height - 2 } });
+  await expect(label.getByTestId("turn-footer-timing-label")).toContainText(/\d:\d\d/);
+  expect(await label.boundingBox()).toMatchObject({
+    x: labelBefore!.x,
+    width: labelBefore!.width,
+    height: labelBefore!.height,
+  });
+  expect(
+    await controls.evaluateAll((elements) =>
+      elements.map((element) => {
+        const rect = element.getBoundingClientRect();
+        return { x: rect.x, y: rect.y };
+      }),
+    ),
+  ).toEqual(before);
+  expect(await footer.boundingBox()).toMatchObject({
+    x: footerBefore!.x,
+    y: footerBefore!.y,
+    width: footerBefore!.width,
+  });
+  await expectTimingInsideFooter(page);
+  await page.mouse.move(0, 0);
+  await expect(label.getByTestId("turn-footer-timing-label")).toContainText("Worked for");
+}
+
+test("footer timing fits the chat column and swapping labels keeps controls in place", async ({
+  page,
+  agent,
+}) => {
+  await openAgentRoute(page, agent);
+  await expectFooterWithinWidth(page, 140);
+  await expectFooterWithinWidth(page, 150);
+  await expectFooterWithinWidth(page, 300);
+  await expectFooterWithinWidth(page, 880);
+});
+
+async function visibleFooterLeftEdges(page: Page): Promise<number[]> {
+  return page.evaluate(() => {
+    const viewport = Array.from(
+      document.querySelectorAll('[data-testid="agent-chat-scroll"]'),
+    ).find((candidate) => candidate.checkVisibility());
+    return Array.from(viewport?.querySelectorAll('[data-testid="turn-footer"]') ?? [])
+      .filter((footer) => footer.checkVisibility())
+      .map((footer) => Math.round(footer.getBoundingClientRect().left));
+  });
+}
+
+async function expectFootersInOneColumn(page: Page): Promise<void> {
+  await expect
+    .poll(async () => {
+      const edges = await visibleFooterLeftEdges(page);
+      return edges.length >= 2 && new Set(edges).size === 1 ? "one column" : edges;
+    })
+    .toBe("one column");
+}
+
+test("keeps the latest turn's footer in the chat column while it runs and after it ends", async ({
+  page,
+  agent,
+}) => {
+  // Wider than the chat's max width, so the column is centered with space on both sides.
+  await page.setViewportSize({ width: 1600, height: 1000 });
+  const gate = await installDaemonWebSocketGate(page);
+  await openAgentRoute(page, agent);
+  await expectAgentIdle(page);
+
+  gate.holdNextAgentStreamEvent("turn_completed");
+  gate.holdNextAgentUpdate(agent.agentId, "idle");
+  gate.setServerMessageSuppressed("agent_update", true);
+  await submitMessage(page, "emit 1 coalesced agent stream updates");
+  await Promise.all([
+    gate.waitForHeldAgentStreamEvent("turn_completed"),
+    gate.waitForHeldAgentUpdate(agent.agentId, "idle"),
+  ]);
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible();
+  await expectFootersInOneColumn(page);
+
+  gate.releaseHeldAgentStreamEvent("turn_completed");
+  gate.releaseHeldAgentUpdate(agent.agentId, "idle");
+  gate.setServerMessageSuppressed("agent_update", false);
+  await expectAgentIdle(page);
+  await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+  await expectFootersInOneColumn(page);
+});
diff --git a/packages/app/e2e/browser/appearance-font-family.spec.ts b/packages/app/e2e/browser/appearance-font-family.spec.ts
index 6ec8600017..57b42ebde1 100644
--- a/packages/app/e2e/browser/appearance-font-family.spec.ts
+++ b/packages/app/e2e/browser/appearance-font-family.spec.ts
@@ -13,25 +13,30 @@ async function setFontFamily(page: Page, name: string, family: string) {
   await input.press("Tab");
 }
 
-for (const name of ["Code font family", "Interface font family"]) {
-  test(`keeps settings usable after an unfinished quote in ${name}`, async ({ page }, testInfo) => {
-    await openAppearance(page);
-    await setFontFamily(page, name, "'Fira Code', monospace");
-    await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
+test("keeps settings usable while editing code and interface font families", async ({
+  page,
+}, testInfo) => {
+  await openAppearance(page);
 
-    await setFontFamily(page, name, "'foo");
-    await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
-    await expect(page.getByRole("button", { name: "Appearance", exact: true })).toBeInViewport();
-    await expect(page.getByText("Theme", { exact: true }).first()).toHaveCSS("font-size", "12px");
+  for (const name of ["Code font family", "Interface font family"]) {
+    await test.step(`reject an unfinished quote in ${name} and restore the default`, async () => {
+      await setFontFamily(page, name, "'Fira Code', monospace");
+      await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
 
-    await page.screenshot({ path: testInfo.outputPath("rejected-font.png") });
-    await page.reload();
-    await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
-    await expect(page.getByRole("button", { name: "Appearance", exact: true })).toBeInViewport();
-    await setFontFamily(page, name, "");
-    await expect(page.getByRole("textbox", { name })).toHaveValue("");
-  });
-}
+      await setFontFamily(page, name, "'foo");
+      await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
+      await expect(page.getByRole("button", { name: "Appearance", exact: true })).toBeInViewport();
+      await expect(page.getByText("Theme", { exact: true }).first()).toHaveCSS("font-size", "12px");
+
+      await page.screenshot({ path: testInfo.outputPath(`rejected-${name}.png`) });
+      await page.reload();
+      await expect(page.getByRole("textbox", { name })).toHaveValue("'Fira Code', monospace");
+      await expect(page.getByRole("button", { name: "Appearance", exact: true })).toBeInViewport();
+      await setFontFamily(page, name, "");
+      await expect(page.getByRole("textbox", { name })).toHaveValue("");
+    });
+  }
+});
 
 test("opens settings with defaults when a malformed font was already saved", async ({ page }) => {
   await page.addInitScript(() => {
diff --git a/packages/app/e2e/browser/appearance-theme-picker.spec.ts b/packages/app/e2e/browser/appearance-theme-picker.spec.ts
index b0d86e164e..5e07f5bac0 100644
--- a/packages/app/e2e/browser/appearance-theme-picker.spec.ts
+++ b/packages/app/e2e/browser/appearance-theme-picker.spec.ts
@@ -9,9 +9,11 @@ test("shows Pure black in the appearance picker", async ({ page }, testInfo) =>
   await expect(page.getByTestId("settings-sidebar")).toBeVisible();
   await openSettingsSection(page, "appearance");
 
-  const themeTrigger = page.getByLabel("Theme: System", { exact: true });
-  await themeTrigger.click();
-  await expect(page.getByText("Pure black", { exact: true })).toBeVisible();
+  await expect(page.getByRole("radio", { name: "System", exact: true })).toBeChecked();
+  await expect(
+    page.getByRole("radiogroup", { name: "Theme" }).getByRole("radio").first(),
+  ).toHaveAccessibleName("System");
+  await expect(page.getByRole("radio", { name: "Pure black", exact: true })).toBeVisible();
   await page.screenshot({
     path: testInfo.outputPath("appearance-theme-picker.png"),
     fullPage: true,
diff --git a/packages/app/e2e/browser/archive-tab.spec.ts b/packages/app/e2e/browser/archive-tab.spec.ts
index 6ee80ddf1e..0dd5641184 100644
--- a/packages/app/e2e/browser/archive-tab.spec.ts
+++ b/packages/app/e2e/browser/archive-tab.spec.ts
@@ -6,6 +6,7 @@ import { connectSeedClient } from "../support/helpers/seed-client";
 import { createTempGitRepo } from "../support/helpers/workspace";
 import { buildHostWorkspaceRoute } from "@/utils/host-routes";
 import {
+  closeActiveAgentWithShortcut,
   archiveAgentFromDaemon,
   archiveAgentFromSessions,
   clickSessionRow,
@@ -20,8 +21,12 @@ import {
   openWorkspaceWithAgents,
   primeAdditionalPage,
   resetSeededPageState,
+  unarchiveAgentFromConversation,
   reloadWorkspace,
 } from "../support/helpers/archive-tab";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import { expectComposerDraft, fillComposerDraft, submitMessage } from "../support/helpers/composer";
+import { awaitAssistantMessage, expectAgentIdle } from "../support/helpers/agent-stream";
 import { expectAgentTabActive } from "../support/helpers/launcher";
 
 test.describe("Archive tab reconciliation", () => {
@@ -51,6 +56,34 @@ test.describe("Archive tab reconciliation", () => {
     await tempRepo?.cleanup();
   });
 
+  test("restoring a closed agent retains its unsent composer draft after reload", async ({
+    page,
+  }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "archived-composer-",
+      title: "Restore unsent draft",
+    });
+    try {
+      await openAgentRoute(page, agent);
+      await submitMessage(page, "A completed conversation before closing");
+      await awaitAssistantMessage(page);
+      await expectAgentIdle(page);
+      await fillComposerDraft(page, "Keep this unsent message after closing");
+      await expectComposerDraft(page, "Keep this unsent message after closing");
+      await closeActiveAgentWithShortcut(page, agent.agentId);
+      await expect.poll(() => fetchAgentArchivedAt(agent.client, agent.agentId)).not.toBeNull();
+      await page.reload();
+      await openSessions(page);
+      await expectSessionRowArchived(page, "Restore unsent draft");
+      await clickSessionRow(page, "Restore unsent draft");
+      await expectArchivedAgentFocused(page, agent.agentId);
+      await unarchiveAgentFromConversation(page);
+      await expectComposerDraft(page, "Keep this unsent message after closing");
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
   test("non-UI archive prunes the archived tab across open pages and reload", async ({ page }) => {
     const archived = await createIdleAgent(client, {
       cwd: tempRepo.path,
diff --git a/packages/app/e2e/browser/assistant-file-link-tooltip.spec.ts b/packages/app/e2e/browser/assistant-file-link-tooltip.spec.ts
index 69cccc52dd..09a9434995 100644
--- a/packages/app/e2e/browser/assistant-file-link-tooltip.spec.ts
+++ b/packages/app/e2e/browser/assistant-file-link-tooltip.spec.ts
@@ -1,4 +1,5 @@
-import { writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { test, expect, type Page } from "../support/fixtures";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
@@ -67,3 +68,54 @@ test("opening an assistant file link dismisses its tooltip over the file tab", a
     await agent.cleanup();
   }
 });
+
+async function readLinkedGuide(page: Page, linkName: string, content: string): Promise<void> {
+  await page.getByRole("link", { name: linkName, exact: true }).click();
+  await expect(page.getByTestId("markdown-preview-frame").filter({ visible: true })).toContainText(
+    content,
+  );
+}
+
+async function returnToNestedLinks(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Nested file links", exact: true }).click();
+  await expect(page.getByRole("link", { name: "nested guide", exact: true })).toBeVisible();
+}
+
+test("assistant directory paths find nested files and preserve exact workspace paths", async ({
+  page,
+}, testInfo) => {
+  testInfo.setTimeout(120_000);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "nested-file-link-",
+    title: "Nested file links",
+    featureValues: {
+      mockStreamingAssistantResponse:
+        "Read [nested guide](schema/x.md), [exact guide](schema/exact.md), and [missing guide](schema/missing.md).",
+      mockStreamingAssistantIntervalMs: 5,
+    },
+  });
+  try {
+    await mkdir(path.join(agent.cwd, "repo-a/schema"), { recursive: true });
+    execFileSync("git", ["init", "-b", "main"], { cwd: path.join(agent.cwd, "repo-a") });
+    await writeFile(
+      path.join(agent.cwd, "repo-a/schema/x.md"),
+      "# Nested file content\n\nDetails\n",
+    );
+    await mkdir(path.join(agent.cwd, "schema"), { recursive: true });
+    await writeFile(path.join(agent.cwd, "schema/exact.md"), "# Exact file content\n");
+    await writeFile(path.join(agent.cwd, "repo-a/schema/exact.md"), "# Wrong nested content\n");
+    await openAgentRoute(page, agent);
+    await agent.client.sendAgentMessage(agent.agentId, "Show the file links.");
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+
+    await expect(page.getByRole("textbox", { name: "Message agent..." }).first()).toBeEnabled();
+    await readLinkedGuide(page, "nested guide", "Nested file content");
+    await returnToNestedLinks(page);
+    await readLinkedGuide(page, "exact guide", "Exact file content");
+    await returnToNestedLinks(page);
+    await page.getByRole("link", { name: "missing guide", exact: true }).click();
+    await expect(page.getByText("File not found", { exact: true })).toBeVisible();
+  } finally {
+    await agent.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/assistant-selection-copy.spec.ts b/packages/app/e2e/browser/assistant-selection-copy.spec.ts
index 7daa11c7d6..81f89290c7 100644
--- a/packages/app/e2e/browser/assistant-selection-copy.spec.ts
+++ b/packages/app/e2e/browser/assistant-selection-copy.spec.ts
@@ -723,3 +723,46 @@ test("copying a selection across an assistant image keeps its Markdown source an
     await agent.cleanup();
   }
 });
+
+test.describe("on a touch-capable desktop browser", () => {
+  // A touch screen registers the navigation pan's pointer listeners over the whole workspace.
+  // The pan accepts touch only, and a mouse drag must still extend the browser's selection.
+  test.use({ hasTouch: true });
+
+  test("a mouse drag selects across assistant paragraphs", async ({ page }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "assistant-selection-drag-",
+      title: "Assistant selection drag",
+      initialPrompt: "Render three paragraphs.",
+      featureValues: {
+        mockAssistantResponse: "First paragraph.\n\nSecond paragraph.\n\nThird paragraph.",
+      },
+    });
+
+    try {
+      await agent.client.waitForAgentUpsert(
+        agent.agentId,
+        (snapshot) => snapshot.status === "idle",
+        30_000,
+      );
+      await openAgentRoute(page, agent);
+      const blocks = assistantMessageBlocks(page);
+      const first = await blocks.getByText("First paragraph.").boundingBox();
+      const third = await blocks.getByText("Third paragraph.").boundingBox();
+      if (!first || !third) {
+        throw new Error("Expected rendered paragraphs");
+      }
+
+      await page.mouse.move(first.x + 1, first.y + first.height / 2);
+      await page.mouse.down();
+      await page.mouse.move(third.x + third.width - 1, third.y + third.height / 2, { steps: 20 });
+      await page.mouse.up();
+
+      const selected = await page.evaluate(() => window.getSelection()?.toString() ?? "");
+      expect(selected).toContain("First paragraph.");
+      expect(selected).toContain("Third paragraph.");
+    } finally {
+      await agent.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/background-agents.spec.ts b/packages/app/e2e/browser/background-agents.spec.ts
new file mode 100644
index 0000000000..66c4787709
--- /dev/null
+++ b/packages/app/e2e/browser/background-agents.spec.ts
@@ -0,0 +1,65 @@
+import { test } from "../support/fixtures";
+import {
+  expectWorkspaceShownIdle,
+  finishAndArchiveAgent,
+  startBackgroundAgent,
+} from "../support/helpers/background-agents";
+import { openAgentRoute } from "../support/helpers/mock-agent";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import {
+  expectSubagentRowGone,
+  expectSubagentRowVisible,
+  openSubagentsTrack,
+  seedParentWithSubagent,
+  seedSubagent,
+} from "../support/helpers/subagents";
+import { expectOnlyWorkspaceAgentTabsVisible } from "../support/helpers/workspace-tabs";
+
+test.describe("Background agents", () => {
+  let workspace: SeededWorkspace;
+
+  test.beforeAll(async () => {
+    workspace = await seedWorkspace({
+      repoPrefix: "background-agents-",
+      title: "Classifier workspace",
+    });
+  });
+
+  test.afterAll(async () => {
+    await workspace?.cleanup();
+  });
+
+  test("a background agent runs in an open workspace without announcing itself", async ({
+    page,
+  }) => {
+    const agents = await seedParentWithSubagent(workspace, {
+      parentTitle: "Feature agent",
+      childTitle: "Visible helper",
+    });
+    await openAgentRoute(page, { workspaceId: agents.workspaceId, agentId: agents.parent.id });
+    await openSubagentsTrack(page);
+    await expectSubagentRowVisible(page, agents.child.id);
+
+    const classifier = await test.step("a plugin starts a background agent", () =>
+      startBackgroundAgent(workspace, { parentId: agents.parent.id, title: "Classifier" }));
+    // A visible child created after the classifier reaches the app on the same stream, so once
+    // its row shows, the app has processed the classifier too.
+    const marker = await seedSubagent(workspace, {
+      parentId: agents.parent.id,
+      title: "Ordering marker",
+    });
+
+    await test.step("it stays out of the track, the tabs and the sidebar status", async () => {
+      await expectSubagentRowVisible(page, marker.id);
+      await expectSubagentRowGone(page, classifier.id);
+      await expectOnlyWorkspaceAgentTabsVisible(page, [agents.parent.id]);
+      await expectWorkspaceShownIdle(page, "Classifier workspace");
+    });
+
+    await test.step("the plugin reads its finish and archives it", async () => {
+      await finishAndArchiveAgent(workspace, classifier.id);
+      await expectOnlyWorkspaceAgentTabsVisible(page, [agents.parent.id]);
+      await expectSubagentRowGone(page, classifier.id);
+    });
+  });
+});
diff --git a/packages/app/e2e/browser/background-reconnect.spec.ts b/packages/app/e2e/browser/background-reconnect.spec.ts
index e9831c257d..b879354a29 100644
--- a/packages/app/e2e/browser/background-reconnect.spec.ts
+++ b/packages/app/e2e/browser/background-reconnect.spec.ts
@@ -5,6 +5,7 @@ import {
   type IsolatedHostDaemon,
 } from "../support/helpers/isolated-host-daemon";
 import { seedSavedSettingsHosts } from "../support/helpers/settings";
+import { setTabVisibility } from "../support/helpers/workspace-ui";
 
 const test = base.extend<{ reconnectHost: IsolatedHostDaemon }>({
   reconnectHost: async ({ e2eWorker }, provide) => {
@@ -37,17 +38,6 @@ async function refocusConnectedTab(page: Page): Promise<void> {
   await expect(page.getByText("Online", { exact: true })).toBeVisible();
 }
 
-async function setTabVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
-  await page.evaluate((state) => {
-    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
-    Object.defineProperty(document, "hidden", {
-      configurable: true,
-      get: () => state === "hidden",
-    });
-    document.dispatchEvent(new Event("visibilitychange"));
-  }, visibility);
-}
-
 async function openHostOverview(page: Page, daemon: IsolatedHostDaemon): Promise<void> {
   await page.goto("/");
   await seedSavedSettingsHosts(page, [
diff --git a/packages/app/e2e/browser/branch-switcher.spec.ts b/packages/app/e2e/browser/branch-switcher.spec.ts
index c413b6413e..0f37f83b10 100644
--- a/packages/app/e2e/browser/branch-switcher.spec.ts
+++ b/packages/app/e2e/browser/branch-switcher.spec.ts
@@ -1,4 +1,7 @@
+import { writeFile, unlink } from "node:fs/promises";
+import path from "node:path";
 import { expect, test, type Page } from "../support/fixtures";
+import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 import { gotoAppShell } from "../support/helpers/app";
 import {
   expectNoBranchSwitcherInWorkspaceHeader,
@@ -14,6 +17,95 @@ import {
   waitForSidebarHydration,
 } from "../support/helpers/workspace-ui";
 
+// Hold the real daemon response until the test has observed the pending UI.
+async function holdBranchSuggestions(page: Page) {
+  let requestCount = 0;
+  let release!: () => void;
+  let gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  await page.routeWebSocket(daemonWsRoutePattern(), (browser) => {
+    const server = browser.connectToServer();
+    browser.onMessage((message) => {
+      if (typeof message === "string") {
+        const envelope = JSON.parse(message);
+        if (envelope.type === "session" && envelope.message?.type === "branch_suggestions_request")
+          requestCount++;
+      }
+      server.send(message);
+    });
+    server.onMessage(async (message) => {
+      if (typeof message === "string") {
+        const envelope = JSON.parse(message);
+        if (
+          envelope.type === "session" &&
+          envelope.message?.type === "branch_suggestions_response"
+        ) {
+          await gate;
+        }
+      }
+      browser.send(message);
+    });
+  });
+  return {
+    release: () => release(),
+    holdNextResponse: () => {
+      gate = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+    },
+    requestCount: () => requestCount,
+  };
+}
+
+async function expectInitialBranchLoading(page: Page, release: () => void): Promise<void> {
+  await page.getByRole("button", { name: "Current branch: main. Press to switch branch." }).click();
+  const picker = page.getByTestId("combobox-desktop-container");
+  await expect(picker.getByText("Loading...", { exact: true })).toBeVisible();
+  await expect(picker.getByText("No branches found.", { exact: true })).toHaveCount(0);
+  release();
+  await expect(picker.getByText("dev", { exact: true })).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(picker).not.toBeVisible();
+}
+
+async function expectFailedRefreshRecovery(
+  page: Page,
+  repoPath: string,
+  responses: Awaited<ReturnType<typeof holdBranchSuggestions>>,
+) {
+  // Expire the actual query freshness window before reopening the cached picker.
+  const started = Date.now();
+  await expect.poll(() => Date.now() - started, { timeout: 20_000 }).toBeGreaterThan(15_000);
+  const picker = page.getByTestId("combobox-desktop-container");
+  const packedRefs = path.join(repoPath, ".git", "packed-refs");
+  await writeFile(packedRefs, "invalid packed refs\n");
+  try {
+    await page
+      .getByRole("button", { name: "Current branch: dev. Press to switch branch." })
+      .click();
+    await expect(picker.getByRole("alert")).toHaveText(
+      "Could not load branches. Reopen the picker to try again.",
+    );
+  } finally {
+    await unlink(packedRefs);
+  }
+  await expect(picker.getByText("No branches found.", { exact: true })).toHaveCount(0);
+  responses.holdNextResponse();
+  const beforeRetry = responses.requestCount();
+  await page.keyboard.press("Escape");
+  await page.getByRole("button", { name: "Current branch: dev. Press to switch branch." }).click();
+  await expect(picker.getByRole("alert")).toHaveText("Loading...");
+  await expect.poll(responses.requestCount).toBe(beforeRetry + 1);
+  await expect(picker).toBeVisible();
+  responses.release();
+  await expect(picker.getByRole("alert")).toHaveCount(0);
+  await expect(picker.getByText("main", { exact: true })).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expectWorkspaceBranch(page, "dev");
+  expect(responses.requestCount()).toBe(beforeRetry + 1);
+}
+
 async function renameWorkspaceViaSidebar(
   page: Page,
   input: { workspaceId: string; title: string },
@@ -59,6 +151,7 @@ test.describe("Branch switcher", () => {
     try {
       expect(workspace.workspaceName).toBe("main");
 
+      const releaseBranches = await holdBranchSuggestions(page);
       await gotoAppShell(page);
       await waitForSidebarHydration(page);
       await switchWorkspaceViaSidebar({ page, serverId, workspaceId: workspace.workspaceId });
@@ -82,8 +175,10 @@ test.describe("Branch switcher", () => {
       // and switching it checks out the real branch on disk.
       await openChangesPanel(page);
       await expectWorkspaceBranch(page, "main");
+      await expectInitialBranchLoading(page, releaseBranches.release);
       await switchBranchFromChangesPanel(page, { from: "main", to: "dev" });
       await expectWorkspaceBranch(page, "dev");
+      await expectFailedRefreshRecovery(page, workspace.repoPath, releaseBranches);
 
       // The custom title is unaffected by the branch switch.
       await expect(headerTitle).toHaveText(customTitle, { timeout: 30_000 });
diff --git a/packages/app/e2e/browser/changes-pane.spec.ts b/packages/app/e2e/browser/changes-pane.spec.ts
index 1ff6059460..8bc76e2a37 100644
--- a/packages/app/e2e/browser/changes-pane.spec.ts
+++ b/packages/app/e2e/browser/changes-pane.spec.ts
@@ -8,7 +8,11 @@ import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 import { getServerId } from "../support/helpers/server-id";
 import { connectSeedClient } from "../support/helpers/seed-client";
 import { createTempGitRepo } from "../support/helpers/workspace";
-import { openChangesPanel, waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+import {
+  openChangesPanel,
+  openChangesTreePanel,
+  waitForWorkspaceTabsVisible,
+} from "../support/helpers/workspace-tabs";
 
 interface DirtyWorkspace {
   id: string;
@@ -262,6 +266,150 @@ test.afterEach(async () => {
   }
 });
 
+test("Changes without a comparison base explains how to view pending changes", async ({ page }) => {
+  const workspace = await createWorkspaceWithManyTinyDiffs(2, "dev");
+  await openWorkspaceChangesTree(page, workspace);
+  await expect(
+    page.getByText("Comparison base is unavailable. Select Uncommitted to view pending changes."),
+  ).toBeVisible();
+  await selectChangesComparison(page, "Uncommitted");
+  await expect(changesTree(page).getByText("file-0000.ts", { exact: true })).toBeVisible();
+});
+async function openWorkspaceChangesTree(page: Page, workspace: DirtyWorkspace): Promise<void> {
+  await page.setViewportSize({ width: 1400, height: 900 });
+  await page.goto(buildHostWorkspaceRoute(getServerId(), workspace.id));
+  await waitForWorkspaceTabsVisible(page);
+  await openChangesTreePanel(page);
+}
+
+test("streamed Changes shows the tree before completion and applies a one-file refresh", async ({
+  page,
+}, testInfo) => {
+  test.setTimeout(120_000);
+  const workspace = await createLargeStreamedWorkspace();
+  await addOversizedSibling(workspace);
+  const stream = await holdDiffCompletion(page);
+  await openWorkspaceChangesSurface(page, workspace, 90_000);
+  await expectAnnouncedTreeAndLoader(page);
+  await page.screenshot({ path: testInfo.outputPath("tree-loading.png") });
+  stream.finish();
+  await expect.poll(() => stream.completed, { timeout: 60_000 }).toBeGreaterThan(0);
+  await expect(page.getByRole("progressbar", { name: "Loading..." })).toHaveCount(0);
+  const connections = stream.connections;
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("src/file-0000.ts, +90, -1");
+  await addOneLineToFirstFile(workspace);
+  await expect.poll(() => stream.changedBodies.at(-1), { timeout: 30_000 }).toBe(1);
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("src/file-0000.ts, +91, -1");
+  await expect(page.getByRole("progressbar", { name: "Loading..." })).toHaveCount(0);
+  expect(stream.connections).toBe(connections);
+  await page.screenshot({ path: testInfo.outputPath("refreshed.png") });
+});
+
+test("reopening compact Changes keeps the painted diff while it resubscribes", async ({ page }) => {
+  const workspace = await createWorkspaceWithMountedTabDiff();
+  const stream = await holdDiffCompletion(page);
+  const explorer = await openCompactChanges(page, workspace);
+  stream.finish();
+  const firstFile = explorer.getByTestId("diff-file-0");
+  await expect(firstFile).toBeVisible({ timeout: 30_000 });
+  const painted = await firstFile.getAttribute("aria-label");
+
+  await explorer.getByTestId("workspace-tab-files").click();
+  stream.hold();
+  await explorer.getByTestId("workspace-tab-changes_tree").click();
+  await expect.poll(() => stream.held, { timeout: 30_000 }).toBeGreaterThan(0);
+  await expect(page.getByRole("progressbar", { name: "Loading..." })).toHaveCount(0);
+  await expect(firstFile).toHaveAccessibleName(painted ?? "");
+  stream.finish();
+});
+
+async function createLargeStreamedWorkspace(): Promise<DirtyWorkspace> {
+  const workspace = await createWorkspaceWithManyTinyDiffs(252);
+  await Promise.all(
+    Array.from({ length: 252 }, (_, file) =>
+      writeFile(
+        path.join(workspace.repoPath, `src/file-${String(file).padStart(4, "0")}.ts`),
+        Array.from(
+          { length: 90 },
+          (_unused, line) =>
+            `export const fn${line} = (param: string) => ({ key: param, value: ${file} });`,
+        ).join("\n") + "\n",
+      ),
+    ),
+  );
+  return workspace;
+}
+async function addOversizedSibling(workspace: DirtyWorkspace): Promise<void> {
+  await writeFile(path.join(workspace.repoPath, "zz-too-large.txt"), "x".repeat(1024 * 1024 + 1));
+}
+async function addOneLineToFirstFile(workspace: DirtyWorkspace): Promise<void> {
+  const file = path.join(workspace.repoPath, "src/file-0000.ts");
+  await writeFile(file, (await readFile(file, "utf8")) + "export const refreshed = true;\n");
+}
+async function holdDiffCompletion(page: Page) {
+  const { decodeDiffFrame, DiffOpcode } = await import("@getpaseo/protocol/binary-frames/index");
+  let holding = true;
+  let connections = 0;
+  let completed = 0;
+  const completions: Array<() => void> = [];
+  const changedBodies: number[] = [];
+  const bodyCounts = new Map<number, number>();
+  await page.routeWebSocket(daemonWsRoutePattern(), (browserSocket) => {
+    connections++;
+    const serverSocket = browserSocket.connectToServer();
+    browserSocket.onMessage((message) => serverSocket.send(message));
+    serverSocket.onMessage((message) => {
+      if (
+        typeof message !== "string" &&
+        message[0] >= DiffOpcode.Begin &&
+        message[0] <= DiffOpcode.End
+      ) {
+        const frame = decodeDiffFrame(message);
+        if (frame.opcode === DiffOpcode.Begin) bodyCounts.set(frame.slot, 0);
+        else if (frame.opcode === DiffOpcode.Bodies)
+          bodyCounts.set(frame.slot, (bodyCounts.get(frame.slot) ?? 0) + frame.files.length);
+        else {
+          completed++;
+          changedBodies.push(bodyCounts.get(frame.slot) ?? 0);
+        }
+      }
+      if (holding && typeof message !== "string" && message[0] === DiffOpcode.End) {
+        completions.push(() => browserSocket.send(message));
+        return;
+      }
+      browserSocket.send(message);
+    });
+  });
+  return {
+    changedBodies,
+    get connections() {
+      return connections;
+    },
+    get completed() {
+      return completed;
+    },
+    get held() {
+      return completions.length;
+    },
+    hold: () => {
+      holding = true;
+    },
+    finish: () => {
+      holding = false;
+      completions.splice(0).forEach((send) => send());
+    },
+  };
+}
+async function expectWorkingDiffLoaded(page: Page, timeout: number): Promise<void> {
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  await expect(panel.getByTestId("diff-file-0")).toBeAttached({ timeout });
+}
+async function expectAnnouncedTreeAndLoader(page: Page): Promise<void> {
+  await expect(changesTree(page).first()).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "Loading..." }).first()).toBeVisible();
+}
+
 test("Changes opens All changes for a clean checkout", async ({ page }) => {
   const workspace = await createWorkspaceWithCommittedDiff();
 
@@ -323,6 +471,119 @@ test("All changes combines committed and pending edits and preserves an unfinish
   });
 });
 
+test("Changes selects exact local and remote bases and retains the selection after reload", async ({
+  page,
+}, testInfo) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  execFileSync("git", ["update-ref", "refs/remotes/upstream/release", "main"], {
+    cwd: workspace.repoPath,
+  });
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: workspace.repoPath }).toString();
+  await openWorkspaceChangesSurface(page, workspace);
+  const tree = page.getByTestId("changes-tree-panel").filter({ visible: true });
+  const picker = tree.getByTestId("workspace-base-branch-trigger");
+  await expect(picker).toBeVisible();
+  await picker.click();
+  await expect(page.getByRole("button", { name: "release", exact: true })).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("base-picker.png") });
+  await page.getByRole("button", { name: "release", exact: true }).click();
+  await expect(picker).toContainText("release");
+  await expect(tree.getByText("No changes to display", { exact: true })).toBeVisible();
+  await picker.click();
+  await page.getByRole("button", { name: "upstream/release", exact: true }).click();
+  await expect(picker).toContainText("upstream/release");
+  await expect(tree.getByText("committed-only.ts", { exact: true })).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("base-selected.png") });
+  await page.reload();
+  await waitForWorkspaceTabsVisible(page);
+  await expect(picker).toContainText("upstream/release");
+  expect(execFileSync("git", ["rev-parse", "HEAD"], { cwd: workspace.repoPath }).toString()).toBe(
+    head,
+  );
+});
+
+test("Changes lets a compact workspace change its base in a sheet", async ({ page }, testInfo) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await openCompactChanges(page, workspace);
+  const picker = page.getByRole("button", { name: "Change base" }).filter({ visible: true });
+  await picker.click();
+  await expect(page.getByText("Change base", { exact: true })).toBeVisible();
+  const release = page.getByRole("button", { name: "release", exact: true });
+  await expect(release).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("compact-base-picker.png") });
+  await release.click();
+  await expect(picker).toContainText("release");
+  await page.screenshot({ path: testInfo.outputPath("compact-base-selected.png") });
+});
+
+test("Changes shows a failed base selection and lets the user retry", async ({ page }) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await openWorkspaceChangesSurface(page, workspace);
+  const picker = page
+    .getByTestId("workspace-base-branch-trigger")
+    .filter({ visible: true })
+    .first();
+  await picker.click();
+  const option = page.getByRole("button", { name: "release", exact: true });
+  await expect(option).toBeVisible();
+  execFileSync("git", ["branch", "-D", "release"], { cwd: workspace.repoPath });
+  await option.click();
+  await expect(page.getByTestId("workspace-base-branch-error")).toContainText(
+    "Base branch not found",
+  );
+  await expect(picker).toContainText("main");
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await option.click();
+  await expect(page.getByTestId("workspace-base-branch-error")).toHaveCount(0);
+  await expect(picker).toContainText("release");
+});
+
+test("Changes shows the base as text on a host without the base-branch capability", async ({
+  page,
+}) => {
+  let baseRequests = 0;
+  await page.routeWebSocket(daemonWsRoutePattern(), (browser) => {
+    const server = browser.connectToServer();
+    browser.onMessage((frame) => {
+      if (typeof frame === "string") {
+        const envelope = JSON.parse(frame) as { message?: { type?: string } };
+        if (envelope.message?.type === "workspace.base_branch.set.request") baseRequests += 1;
+      }
+      server.send(frame);
+    });
+    server.onMessage((frame) => {
+      if (typeof frame === "string") {
+        const envelope = JSON.parse(frame) as {
+          message?: { payload?: { status?: string; features?: Record<string, unknown> } };
+        };
+        const payload = envelope.message?.payload;
+        if (payload?.status === "server_info" && payload.features) {
+          delete payload.features.workspaceBaseBranch;
+          browser.send(JSON.stringify(envelope));
+          return;
+        }
+      }
+      browser.send(frame);
+    });
+  });
+  const workspace = await createWorktreeWithCommittedDiff();
+  await openWorkspaceChangesSurface(page, workspace);
+  await expect(page.getByTestId("workspace-base-branch-trigger")).toHaveCount(0);
+  expect(baseRequests).toBe(0);
+});
+
+test("Changes shows no base on a checkout that is not a Paseo worktree", async ({ page }) => {
+  const workspace = await createWorkspaceWithCommittedDiff();
+  await openWorkspaceChangesSurface(page, workspace);
+  const header = page.getByTestId("changes-repository-header").filter({ visible: true });
+  await expect(header).toContainText("feature");
+  await expect(header).not.toContainText("main");
+  await expect(page.getByTestId("workspace-base-branch-trigger")).toHaveCount(0);
+});
+
 test("Changes keeps a manual comparison when checkout dirtiness changes", async ({ page }) => {
   const workspace = await createWorkspaceWithMountedTabDiff();
   await openWorkspaceChanges(page, workspace);
@@ -386,6 +647,35 @@ test("an empty Changes comparison links to the populated comparison", async ({ p
   await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("committed-only.ts, +1, -0");
 });
 
+test("legacy diff hosts keep All, Committed and Uncommitted comparisons", async ({ page }) => {
+  await useLegacyDiffHost(page);
+  const workspace = await createWorkspaceWithScrollableComparisons();
+  await openWorkspaceChangesSurface(page, workspace);
+  await expect(changesTree(page).getByText("committed", { exact: true })).toBeVisible();
+  await expect(changesTree(page).getByText("uncommitted", { exact: true })).toBeVisible();
+  await selectChangesComparison(page, "Committed");
+  await expectWorkingComparisonFiles(page, "committed");
+  await selectChangesComparison(page, "Uncommitted");
+  await expectWorkingComparisonFiles(page, "uncommitted");
+});
+async function useLegacyDiffHost(page: Page): Promise<void> {
+  await page.routeWebSocket(daemonWsRoutePattern(), (browserSocket) => {
+    const serverSocket = browserSocket.connectToServer();
+    browserSocket.onMessage((message) => serverSocket.send(message));
+    serverSocket.onMessage((message) => {
+      if (typeof message === "string") {
+        const envelope = JSON.parse(message);
+        if (envelope.message?.payload?.status === "server_info") {
+          delete envelope.message.payload.features.diffSubscription;
+          browserSocket.send(JSON.stringify(envelope));
+          return;
+        }
+      }
+      browserSocket.send(message);
+    });
+  });
+}
+
 test("Changes comparison controls the working diff and tree selection focuses its file", async ({
   page,
 }) => {
@@ -928,11 +1218,11 @@ test("compact Changes keeps its actions compact and menu-only", async ({ page })
     throw new Error("Compact Changes toolbar geometry could not be measured");
   }
   expect(actionsBox.width).toBe(48);
-  expect(actionsBox.height).toBe(28);
-  expect(optionsBox.width).toBe(32);
-  expect(optionsBox.height).toBe(32);
-  expect(glyphBox.width).toBe(18);
-  expect(glyphBox.height).toBe(18);
+  expect(actionsBox.height).toBe(32);
+  expect(optionsBox.width).toBe(44);
+  expect(optionsBox.height).toBe(44);
+  expect(glyphBox.width).toBe(20);
+  expect(glyphBox.height).toBe(20);
 
   await expect(actions).not.toContainText("Commit");
   await expect(actions.locator("svg")).toHaveCount(2);
@@ -1198,11 +1488,13 @@ test("canvas diff uses the overlay scrollbar and its thumb controls vertical scr
 test("canvas headers keep a many-file diff bounded while scrolling end to end", async ({
   page,
 }) => {
-  test.setTimeout(180_000);
+  test.setTimeout(300_000);
   const workspace = await createWorkspaceWithManyTinyDiffs(2_000);
   await useUnwrappedDiffLines(page);
   await openWorkspaceChangesSurface(page, workspace, 90_000);
 
+  // Measure document bounds after delivery, independently of the cold Git read.
+  await expectWorkingDiffLoaded(page, 240_000);
   const root = page.getByTestId("git-diff-canvas-root");
   const scroller = page.getByTestId("git-diff-scroll");
   await expect(root.locator('[data-testid^="git-diff-sticky-header-"]')).toHaveCount(2);
@@ -1657,6 +1949,28 @@ async function expectRenderedAddedLine(page: Page, contents: string): Promise<vo
   }).toPass({ timeout: 15_000 });
 }
 
+async function createWorktreeWithCommittedDiff(): Promise<DirtyWorkspace> {
+  const repo = await createTempGitRepo("changes-base-worktree-", {
+    files: [{ path: "tracked.ts", content: "export const tracked = 1;\n" }],
+  });
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close();
+      await repo.cleanup();
+    },
+  });
+  const created = await client.createWorkspace({
+    source: { kind: "worktree", cwd: repo.path, worktreeSlug: "base-picker", baseBranch: "main" },
+  });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create worktree");
+  const cwd = created.workspace.workspaceDirectory;
+  await writeFile(path.join(cwd, "committed-only.ts"), "export const committed = true;\n");
+  execFileSync("git", ["add", "committed-only.ts"], { cwd });
+  execFileSync("git", ["commit", "-m", "Add committed-only file"], { cwd });
+  return { id: created.workspace.id, repoPath: cwd };
+}
+
 async function createWorkspaceWithCommittedDiff(): Promise<DirtyWorkspace> {
   const repo = await createTempGitRepo("changes-committed-", {
     files: [{ path: "tracked.ts", content: "export const tracked = 1;\n" }],
@@ -1759,12 +2073,16 @@ async function createWorkspaceWithTwoSelectionDiffs(): Promise<DirtyWorkspace> {
   return { id: created.workspace.id, repoPath: repo.path };
 }
 
-async function createWorkspaceWithManyTinyDiffs(fileCount: number): Promise<DirtyWorkspace> {
+async function createWorkspaceWithManyTinyDiffs(
+  fileCount: number,
+  branch = "main",
+): Promise<DirtyWorkspace> {
   const files = Array.from({ length: fileCount }, (_, index) => ({
     path: `src/file-${String(index).padStart(4, "0")}.ts`,
     content: "export const value = 0;\n",
   }));
   const repo = await createTempGitRepo("changes-canvas-many-files-", { files });
+  if (branch !== "main") execFileSync("git", ["branch", "-m", branch], { cwd: repo.path });
   await Promise.all(
     files.map((file, index) =>
       writeFile(path.join(repo.path, file.path), `export const value = ${index + 1};\n`),
diff --git a/packages/app/e2e/browser/command-center-file-search.spec.ts b/packages/app/e2e/browser/command-center-file-search.spec.ts
index 2f16db6f09..3dd51a3622 100644
--- a/packages/app/e2e/browser/command-center-file-search.spec.ts
+++ b/packages/app/e2e/browser/command-center-file-search.spec.ts
@@ -5,8 +5,10 @@ import {
   holdDirectorySuggestionResponses,
   expectOneLineTruncatedFileResult,
   expectStableCommandCenterLayout,
+  expectLayoutObservationToCatchPanelShift,
   failDirectorySuggestionRequests,
   startCommandCenterLayoutObservation,
+  shiftOutsideCommandCenter,
 } from "../support/helpers/command-center-file-search";
 import {
   scrollCommandCenterAwayFromSelection,
@@ -84,7 +86,9 @@ test("workspace file search stays geometrically stable through delayed loading a
     await expect(panel.getByTestId("command-center-file-search-loading")).toBeVisible();
     await expect(panel.getByText("Searching files...", { exact: true })).toHaveCount(0);
     await expect(panel.getByTestId("command-center-file-search-loading")).toBeHidden();
+    await shiftOutsideCommandCenter(page);
     await expectStableCommandCenterLayout(page);
+    await expectLayoutObservationToCatchPanelShift(page);
 
     await row.click();
     await expectFileTabOpen(page, FILE_PATH);
diff --git a/packages/app/e2e/browser/compact-git-actions-menu.spec.ts b/packages/app/e2e/browser/compact-git-actions-menu.spec.ts
index e2e2cdb34f..59fe207e51 100644
--- a/packages/app/e2e/browser/compact-git-actions-menu.spec.ts
+++ b/packages/app/e2e/browser/compact-git-actions-menu.spec.ts
@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { mkdtemp, writeFile } from "node:fs/promises";
 import path from "node:path";
+import type { Locator } from "@playwright/test";
 import { test, expect, type Page } from "../support/fixtures";
 import { getServerId } from "../support/helpers/server-id";
 import { connectSeedClient } from "../support/helpers/seed-client";
@@ -59,6 +60,14 @@ async function openCompactActionsMenu(page: Page, workspaceId: string) {
   return menu;
 }
 
+async function expectActionsInOrder(menu: Locator, labels: readonly string[]) {
+  const items = menu.getByRole("menuitem");
+  await expect(items).toHaveCount(labels.length);
+  for (const [index, label] of labels.entries()) {
+    await expect(items.nth(index).getByText(label, { exact: true })).toBeVisible();
+  }
+}
+
 test("compact git actions menu lists a promoted Pull once", async ({ page }) => {
   const repoPath = await createRemoteRepo("compact-menu-pull-");
   cleanupTasks.push(async () => {
@@ -83,12 +92,7 @@ test("compact git actions menu lists a promoted Pull once", async ({ page }) =>
   const menu = await openCompactActionsMenu(page, workspaceId);
 
   await expect(menu.getByTestId("changes-menu-pull")).toHaveCount(1);
-  await expect(menu.getByRole("menuitem")).toHaveText([
-    "Pull",
-    "Push",
-    "Pull and push",
-    "Archive workspace",
-  ]);
+  await expectActionsInOrder(menu, ["Pull", "Push", "Pull and push", "Archive workspace"]);
 });
 
 test("compact git actions menu lists a promoted Push once", async ({ page }) => {
@@ -106,10 +110,5 @@ test("compact git actions menu lists a promoted Push once", async ({ page }) =>
   const menu = await openCompactActionsMenu(page, workspaceId);
 
   await expect(menu.getByTestId("changes-menu-push")).toHaveCount(1);
-  await expect(menu.getByRole("menuitem")).toHaveText([
-    "Push",
-    "Pull",
-    "Pull and push",
-    "Archive workspace",
-  ]);
+  await expectActionsInOrder(menu, ["Push", "Pull", "Pull and push", "Archive workspace"]);
 });
diff --git a/packages/app/e2e/browser/compact-workspace-header.spec.ts b/packages/app/e2e/browser/compact-workspace-header.spec.ts
index be26dbb8d1..ca352e277e 100644
--- a/packages/app/e2e/browser/compact-workspace-header.spec.ts
+++ b/packages/app/e2e/browser/compact-workspace-header.spec.ts
@@ -1,5 +1,6 @@
 import type { Page, TestInfo } from "@playwright/test";
 import { test, expect } from "../support/fixtures";
+import { pauseWorkspaceTerminalWorker } from "../support/helpers/workspace-setup";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import { openAgentRoute } from "../support/helpers/mock-agent";
 import { getServerId } from "../support/helpers/server-id";
@@ -190,3 +191,49 @@ test("compact header menu runs, shows, and stops workspace scripts", async ({ pa
     await workspace.cleanup();
   }
 });
+
+async function restartScriptAcrossHeaderRemoval(page: Page, terminalId: string) {
+  await openRunningScriptPage(page, "lint");
+  const resumeWorker = await pauseWorkspaceTerminalWorker(terminalId);
+  try {
+    await menuRow(page, "Restart").click();
+    await page.setViewportSize({ width: 1280, height: 844 });
+    await expect(page.getByRole("button", { name: /Switch tabs/ })).toHaveCount(0);
+    await expect(page.getByTestId("workspace-scripts-button")).toBeVisible();
+  } finally {
+    resumeWorker();
+  }
+}
+
+async function expectScriptTerminalReplaced(
+  workspace: Awaited<ReturnType<typeof openWorkspaceWithScripts>>,
+  previousId: string,
+) {
+  await expect
+    .poll(
+      async () => {
+        const after = await workspace.client.listTerminals(undefined, undefined, {
+          workspaceId: workspace.workspaceId,
+        });
+        return after.terminals.filter((terminal) => terminal.id !== previousId).length;
+      },
+      { timeout: 15_000 },
+    )
+    .toBe(1);
+}
+
+test("pending script restart survives removal of the compact header", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  const workspace = await openWorkspaceWithScripts(page);
+  try {
+    await runScriptFromScriptsPage(page, "lint");
+    const before = await workspace.client.listTerminals(undefined, undefined, {
+      workspaceId: workspace.workspaceId,
+    });
+    expect(before.terminals).toHaveLength(1);
+    await restartScriptAcrossHeaderRemoval(page, before.terminals[0]!.id);
+    await expectScriptTerminalReplaced(workspace, before.terminals[0]!.id);
+  } finally {
+    await workspace.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/compact-workspace-sheet.spec.ts b/packages/app/e2e/browser/compact-workspace-sheet.spec.ts
index 5b68663862..cf64451c45 100644
--- a/packages/app/e2e/browser/compact-workspace-sheet.spec.ts
+++ b/packages/app/e2e/browser/compact-workspace-sheet.spec.ts
@@ -19,6 +19,7 @@ import {
   openSheetAsTab,
   expectDeclinedDiscardPrompt,
   expectSheetAtSnap,
+  promptMentioning,
   replaceSheetFileText,
   selectTabFromSwitcher,
   sheet,
@@ -28,17 +29,6 @@ import {
 
 const FILE_LINK = "linked.ts:3";
 
-function promptMentioning(target: string): string {
-  return [
-    "Generate a title and a git branch name for a coding agent from the user prompt and attachments.",
-    "Return JSON only with fields 'title' and 'branch'.",
-    "",
-    "<user-prompt>",
-    `Open \`${target}\` now`,
-    "</user-prompt>",
-  ].join("\n");
-}
-
 test("compact opens files and subagents in a sheet, leaving the tabs for agents", async ({
   page,
 }) => {
diff --git a/packages/app/e2e/browser/composer-autocomplete.spec.ts b/packages/app/e2e/browser/composer-autocomplete.spec.ts
index d83046d8b2..088159e7f0 100644
--- a/packages/app/e2e/browser/composer-autocomplete.spec.ts
+++ b/packages/app/e2e/browser/composer-autocomplete.spec.ts
@@ -1,5 +1,9 @@
 import { expect, test, type Page } from "../support/fixtures";
-import { composerLocator, expectComposerVisible } from "../support/helpers/composer";
+import {
+  attachFileFromMenu,
+  composerLocator,
+  expectComposerVisible,
+} from "../support/helpers/composer";
 import {
   openAgentRoute,
   seedMockAgentWorkspace,
@@ -101,7 +105,21 @@ interface PopoverFrameRecorderWindow extends Window {
   __stopComposerAutocompleteFrameRecorder?: () => void;
 }
 
-async function installListCommandsStub(page: Page): Promise<void> {
+interface ListCommandsReply {
+  commands: readonly { name: string; description: string; argumentHint: string }[];
+  error: string | null;
+}
+
+const TEST_COMMANDS_REPLY: ListCommandsReply = { commands: TEST_COMMANDS, error: null };
+
+/**
+ * Rewrites every `list_commands_response` with `reply()`. A reply that returns a promise holds
+ * the response until it settles, standing in for a slow host.
+ */
+async function installListCommandsStub(
+  page: Page,
+  reply: () => ListCommandsReply | Promise<ListCommandsReply> = () => TEST_COMMANDS_REPLY,
+): Promise<void> {
   await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
     const server = ws.connectToServer();
 
@@ -126,14 +144,20 @@ async function installListCommandsStub(page: Page): Promise<void> {
             };
           };
         };
+        const payload = parsed.message?.payload;
         if (
           parsed.type === "session" &&
           parsed.message?.type === "list_commands_response" &&
-          parsed.message.payload
+          payload
         ) {
-          parsed.message.payload.commands = TEST_COMMANDS;
-          parsed.message.payload.error = null;
-          ws.send(JSON.stringify(parsed));
+          const send = (result: ListCommandsReply) => {
+            payload.commands = result.commands;
+            payload.error = result.error;
+            ws.send(JSON.stringify(parsed));
+          };
+          const result = reply();
+          if (result instanceof Promise) void result.then(send);
+          else send(result);
           return;
         }
       } catch {
@@ -145,6 +169,17 @@ async function installListCommandsStub(page: Page): Promise<void> {
   });
 }
 
+function createHeldReply(): {
+  reply: () => Promise<ListCommandsReply>;
+  release: () => void;
+} {
+  let release = () => {};
+  const held = new Promise<ListCommandsReply>((resolve) => {
+    release = () => resolve(TEST_COMMANDS_REPLY);
+  });
+  return { reply: () => held, release };
+}
+
 async function openAppWideNewWorkspace(page: Page): Promise<void> {
   await page.getByTestId("sidebar-global-new-workspace").first().click();
   await page.waitForURL((url) => url.pathname === "/new", { timeout: 30_000 });
@@ -365,6 +400,56 @@ function expectPopoverDoesNotDisappearAfterFirstVisible(frames: PopoverFrame[]):
 }
 
 test.describe("Composer autocomplete", () => {
+  test("inserts suggested commands from assistant messages without sending", async ({ page }) => {
+    const requests = recordCommandRequestsByAgentId(page);
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "suggested-command-",
+      title: "Suggested commands",
+      initialPrompt: "Suggest `/mock` without running it",
+      featureValues: { mockAssistantResponse: "Try `/mock` or [Run mock](/mock)." },
+    });
+    try {
+      await openAgentRoute(page, session);
+      const message = page.getByTestId("assistant-message").filter({ hasText: "Run mock" });
+      await expect(message).toBeVisible();
+      await expect(page.getByTestId("user-message").getByRole("link")).toHaveCount(0);
+      await expect.poll(() => requests.length).toBe(1);
+      await attachFileFromMenu(page, {
+        name: "note.txt",
+        mimeType: "text/plain",
+        buffer: Buffer.from("attachment"),
+      });
+      await expect(page.getByTestId("composer-file-attachment-pill")).toContainText("note.txt");
+      await message.getByRole("link", { name: "/mock", exact: true }).click();
+      await expect(composerLocator(page)).toHaveValue("/mock ");
+      await expect(
+        page.getByTestId("composer-autocomplete-popover").filter({ visible: true }),
+      ).toHaveCount(0);
+      await expect(composerLocator(page)).toBeFocused();
+      await message.getByRole("link", { name: "Run mock" }).click();
+      await expect(composerLocator(page)).toHaveValue("/mock /mock ");
+      await expect(
+        page.getByTestId("composer-autocomplete-popover").filter({ visible: true }),
+      ).toHaveCount(0);
+      await expect(composerLocator(page)).toBeFocused();
+      await expect(page.getByTestId("composer-file-attachment-pill")).toContainText("note.txt");
+      await composerLocator(page).fill("draft");
+      await composerLocator(page).evaluate((element: HTMLTextAreaElement) =>
+        element.setSelectionRange(0, 0),
+      );
+      await message.getByRole("link", { name: "/mock", exact: true }).click();
+      await composerLocator(page).pressSequentially("argument");
+      await expect(composerLocator(page)).toHaveValue("draft /mock argument");
+      await composerLocator(page).fill("/");
+      await expect(
+        page.getByTestId("composer-autocomplete-popover").filter({ visible: true }),
+      ).toContainText("/mock");
+      expect(requests).toHaveLength(1);
+    } finally {
+      await session.cleanup();
+    }
+  });
+
   test("keeps New workspace off the running-agent command list before a project is chosen", async ({
     page,
   }) => {
@@ -491,16 +576,17 @@ test.describe("Composer autocomplete", () => {
       const input = composerLocator(page);
       await expect(input).toBeEditable({ timeout: 30_000 });
 
-      await input.fill("/he");
+      // `/hea` lists two commands and `/he` enough to reach the height cap, so the list grows.
+      await input.fill("/hea");
       const popover = page.getByTestId("composer-autocomplete-popover");
-      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+      await expect(popover.getByText("/heapdump", { exact: true }).first()).toBeVisible({
         timeout: 30_000,
       });
       const beforeDelete = await visiblePopoverBox(page);
 
       await input.press("Backspace");
-      await expect(input).toHaveValue("/h");
-      await expect(popover.getByText("/history", { exact: true }).first()).toBeVisible({
+      await expect(input).toHaveValue("/he");
+      await expect(popover.getByText("/hello", { exact: true }).first()).toBeVisible({
         timeout: 30_000,
       });
       const afterDelete = await visiblePopoverBox(page);
@@ -679,6 +765,116 @@ test.describe("Composer autocomplete", () => {
     }
   });
 
+  test("forgets an arrow-key choice once the search changes", async ({ page }) => {
+    await installListCommandsStub(page);
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "autocomplete-stale-choice-",
+      title: "Autocomplete stale choice",
+    });
+
+    try {
+      await openAgentRoute(page, session);
+      await expectWorkspaceTabVisible(page, session.agentId);
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+      await input.fill("/");
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByText("/tdd", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+
+      // Down wraps from the default bottom row to the top: /clear, then /exit.
+      await input.press("ArrowDown");
+      await input.press("ArrowDown");
+      await input.press("h");
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible();
+      await input.press("Backspace");
+      await expect(input).toHaveValue("/");
+      await input.press("Enter");
+
+      await expect(input).toHaveValue("/tdd ");
+      await expectWorkspaceTabVisible(page, session.agentId);
+    } finally {
+      await session.cleanup();
+    }
+  });
+
+  test("shows loading inside the popover until a slow host answers", async ({ page }) => {
+    const host = createHeldReply();
+    await installListCommandsStub(page, host.reply);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+      await input.fill("/");
+
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByTestId("composer-autocomplete-loading")).toBeVisible({
+        timeout: 30_000,
+      });
+      const loading = await visiblePopoverBox(page);
+
+      host.release();
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      await expect(popover.getByTestId("composer-autocomplete-loading")).toHaveCount(0);
+      const results = await visiblePopoverBox(page);
+
+      expect(Math.abs(results.bottom - loading.bottom)).toBeLessThanOrEqual(4);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("shows why commands failed, keeps Enter from choosing a hidden command, and retries", async ({
+    page,
+  }) => {
+    let reply: () => ListCommandsReply | Promise<ListCommandsReply> = () => ({
+      commands: [],
+      error: "Timed out waiting for the agent session",
+    });
+    await installListCommandsStub(page, () => reply());
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "autocomplete-failing-host-",
+      title: "Autocomplete failing host",
+    });
+
+    try {
+      await openAgentRoute(page, session);
+      await expectWorkspaceTabVisible(page, session.agentId);
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+      await input.fill("/");
+
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      const errorRow = popover.getByTestId("composer-autocomplete-error");
+      await expect(errorRow).toContainText("Timed out waiting for the agent session", {
+        timeout: 30_000,
+      });
+
+      await input.press("Enter");
+      await page.waitForTimeout(500);
+      await expectWorkspaceTabVisible(page, session.agentId);
+
+      await input.fill("/");
+      await expect(errorRow).toBeVisible({ timeout: 30_000 });
+
+      const host = createHeldReply();
+      reply = host.reply;
+      await errorRow.getByRole("button", { name: "Retry" }).click();
+      await expect(popover.getByTestId("composer-autocomplete-loading")).toBeVisible();
+
+      host.release();
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+    } finally {
+      await session.cleanup();
+    }
+  });
+
   test.describe("compact sidebar layering", () => {
     test.use({ viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true });
 
diff --git a/packages/app/e2e/browser/composer-bottom-spacing.spec.ts b/packages/app/e2e/browser/composer-bottom-spacing.spec.ts
new file mode 100644
index 0000000000..d4a00ee0a0
--- /dev/null
+++ b/packages/app/e2e/browser/composer-bottom-spacing.spec.ts
@@ -0,0 +1,53 @@
+import type { Locator } from "@playwright/test";
+import { expect, test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import { openNewWorkspaceComposer } from "../support/helpers/new-workspace";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+async function box(locator: Locator) {
+  await expect(locator).toBeVisible({ timeout: 30_000 });
+  const rect = await locator.boundingBox();
+  expect(rect).not.toBeNull();
+  return { top: rect!.y, bottom: rect!.y + rect!.height };
+}
+
+test.describe("Composer bottom spacing", () => {
+  test("the chat composer rests one content spacing above the window edge", async ({ page }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "composer-bottom-spacing-",
+      title: "Bottom spacing",
+    });
+    try {
+      await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+      const surface = await box(
+        page.getByTestId("message-input-root").filter({ visible: true }).first(),
+      );
+      const viewportHeight = await page.evaluate(() => window.innerHeight);
+      expect(viewportHeight - surface.bottom).toBe(16);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("the wide new workspace form keeps one content spacing above Import session", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "composer-bottom-spacing-form-" });
+    try {
+      await page.setViewportSize({ width: 1440, height: 900 });
+      await gotoAppShell(page);
+      await waitForSidebarHydration(page);
+      await openNewWorkspaceComposer(page, {
+        projectKey: workspace.projectKey,
+        projectDisplayName: workspace.projectDisplayName,
+      });
+      const composer = await box(page.locator('[data-testid="message-input-root"]:visible'));
+      const importButton = await box(page.getByTestId("new-workspace-import-session"));
+      expect(importButton.top - composer.bottom).toBe(16);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/composer-control-density.spec.ts b/packages/app/e2e/browser/composer-control-density.spec.ts
index 9c81037526..b904536ef4 100644
--- a/packages/app/e2e/browser/composer-control-density.spec.ts
+++ b/packages/app/e2e/browser/composer-control-density.spec.ts
@@ -1,13 +1,30 @@
 import { test, expect } from "../support/fixtures";
 import { openWorkspaceWithAgents } from "../support/helpers/archive-tab";
 import {
+  composerLocator,
+  expectComposerVisible,
+  fillComposerDraft,
+} from "../support/helpers/composer";
+import {
+  expectComposerToolbarOnTextRails,
+  expectTrailingActionSwap,
   expectNoCollapsedComposerToolbarFrame,
+  expectNoFrameTruncatesModelBesideThinking,
+  readSettledModelTriggerLabels,
+  readTrailingActionFrames,
   recordComposerToolbarFrames,
+  recordModelTriggerFramesFromLoad,
+  recordTrailingActionFrames,
+  sweepModelTriggerLabels,
 } from "../support/helpers/composer-control-density";
 import { clickNewChat, gotoWorkspace } from "../support/helpers/launcher";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
 
 const SETTLE_MS = 1_000;
+const TRAILING_ACTION_SETTLE_MS = 500;
+const VOICE_MODE = "Enable Voice mode";
+const SEND = "Send message";
 
 async function seedSettledMockAgent(workspace: SeededWorkspace, title: string) {
   const agent = await workspace.client.createAgent({
@@ -30,6 +47,52 @@ function visibleAgentTab(page: import("@playwright/test").Page, agentId: string)
   return page.getByTestId(`workspace-tab-agent_${agentId}`).filter({ visible: true }).first();
 }
 
+test.describe("Composer trailing action", () => {
+  test.describe.configure({ timeout: 120_000 });
+
+  for (const viewport of [
+    { name: "wide", width: 1280, height: 800 },
+    { name: "compact", width: 390, height: 844 },
+  ]) {
+    test(`swaps in place between voice mode and Send at ${viewport.name} width`, async ({
+      page,
+    }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height });
+      const agent = await seedMockAgentWorkspace({
+        repoPrefix: "composer-trailing-action-",
+        title: "Trailing action",
+      });
+      try {
+        await openAgentRoute(page, agent);
+        await expectComposerVisible(page);
+        await expect(page.getByRole("button", { name: VOICE_MODE, exact: true })).toBeVisible();
+        const composer = composerLocator(page);
+        await composer.focus();
+
+        await recordTrailingActionFrames(page);
+        await composer.press("x");
+        await expect(composer).toHaveValue("x");
+        await page.waitForTimeout(TRAILING_ACTION_SETTLE_MS);
+        expectTrailingActionSwap(await readTrailingActionFrames(page), {
+          from: VOICE_MODE,
+          to: SEND,
+        });
+
+        await recordTrailingActionFrames(page);
+        await composer.press("Backspace");
+        await expect(composer).toHaveValue("");
+        await page.waitForTimeout(TRAILING_ACTION_SETTLE_MS);
+        expectTrailingActionSwap(await readTrailingActionFrames(page), {
+          from: SEND,
+          to: VOICE_MODE,
+        });
+      } finally {
+        await agent.cleanup();
+      }
+    });
+  }
+});
+
 test.describe("Composer control density across tab switches", () => {
   test.describe.configure({ timeout: 180_000 });
 
@@ -92,3 +155,159 @@ test.describe("Composer control density across tab switches", () => {
     }
   });
 });
+
+test.describe("Composer controls folding on a touch device", () => {
+  test.use({ viewport: { width: 1194, height: 834 }, isMobile: true, hasTouch: true });
+  test.describe.configure({ timeout: 180_000 });
+
+  test("an open menu stays closed after the controls fold and unfold", async ({ page }) => {
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "composer-density-fold-",
+      title: "Folding chat",
+      model: "ten-second-stream",
+    });
+    try {
+      await openAgentRoute(page, session);
+      const thinking = page.getByTestId("agent-thinking-selector").filter({ visible: true });
+      const thinkingMenu = page.getByTestId("combobox-desktop-container");
+
+      await thinking.click();
+      await expect(thinkingMenu).toBeVisible();
+
+      // Still a wide layout, but too narrow for separate controls: they fold into the model control.
+      await page.setViewportSize({ width: 640, height: 834 });
+      await expect(thinking).toHaveCount(0);
+
+      await page.setViewportSize({ width: 1194, height: 834 });
+      await expect(thinking).toBeVisible();
+      await expect(thinkingMenu).toHaveCount(0);
+    } finally {
+      await session.cleanup();
+    }
+  });
+});
+
+test.describe("Folded model control on a phone", () => {
+  // Wide enough for "Ten second stream" and "Low" side by side; narrower, they no longer fit.
+  test.use({ viewport: { width: 480, height: 844 }, isMobile: true, hasTouch: true });
+  test.describe.configure({ timeout: 180_000 });
+
+  test("hides the thinking label before the model label truncates", async ({ page }) => {
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "composer-density-labels-",
+      title: "Label priority chat",
+      model: "ten-second-stream",
+    });
+    try {
+      await recordModelTriggerFramesFromLoad(page);
+      await openAgentRoute(page, session);
+      await expect(
+        page.getByTestId("combined-model-selector-thinking-label").filter({ visible: true }),
+      ).toHaveText("Low");
+      await readSettledModelTriggerLabels(page);
+      // From the first frame on, the control never guesses: it paints both labels only once it
+      // has measured that they fit.
+      await expectNoFrameTruncatesModelBesideThinking(page);
+
+      const sweep = await sweepModelTriggerLabels(page, {
+        from: 480,
+        to: 280,
+        step: 4,
+        height: 844,
+      });
+
+      expect(sweep.widest).toMatchObject({
+        modelText: "Ten second stream",
+        thinkingShown: true,
+        modelTruncated: false,
+      });
+      expect(sweep.thinkingHidden).toMatchObject({
+        modelText: "Ten second stream",
+        modelTruncated: false,
+      });
+      expect(sweep.modelTruncated.width).toBeLessThan(sweep.thinkingHidden.width);
+      // A clean tail: the label ends on a whole word and the ellipsis, never on a space.
+      expect(sweep.modelTruncated).toMatchObject({
+        modelText: "Ten second…",
+        thinkingShown: false,
+      });
+    } finally {
+      await session.cleanup();
+    }
+  });
+});
+
+test.describe("Composer toolbar rails on touch", () => {
+  test.use({ isMobile: true, hasTouch: true });
+  test.describe.configure({ timeout: 180_000 });
+
+  for (const viewport of [
+    { device: "phone", width: 390, height: 844 },
+    { device: "tablet", width: 1024, height: 1366 },
+  ]) {
+    test(`the toolbar starts on the text rail and ends in a disc nested in the corner on a ${viewport.device}`, async ({
+      page,
+    }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height });
+      const idle = await seedMockAgentWorkspace({
+        repoPrefix: "composer-rails-idle-",
+        title: "Rails idle chat",
+      });
+      let running: Awaited<ReturnType<typeof seedMockAgentWorkspace>> | null = null;
+      try {
+        await openAgentRoute(page, idle);
+        await expect(page.getByTestId("message-input-root").filter({ visible: true })).toBeVisible({
+          timeout: 30_000,
+        });
+        await test.step("empty composer: attach on the left, voice mode on the right", async () => {
+          await expectComposerToolbarOnTextRails(page);
+        });
+        await test.step("draft: the send disc on the right", async () => {
+          await fillComposerDraft(page, "Refactor the composer toolbar");
+          await expect(page.getByRole("button", { name: /send/i }).first()).toBeVisible();
+          await expectComposerToolbarOnTextRails(page);
+        });
+
+        running = await seedMockAgentWorkspace({
+          repoPrefix: "composer-rails-running-",
+          title: "Rails running chat",
+          model: "one-minute-stream",
+          initialPrompt: "stream for a while",
+        });
+        await openAgentRoute(page, running);
+        await test.step("running agent: the stop disc on the right", async () => {
+          await expect(page.getByRole("button", { name: /stop agent/i }).first()).toBeVisible({
+            timeout: 30_000,
+          });
+          await expectComposerToolbarOnTextRails(page);
+        });
+      } finally {
+        await idle.cleanup();
+        await running?.cleanup();
+      }
+    });
+  }
+});
+
+test.describe("Composer trailing disc on a new chat", () => {
+  test.use({ isMobile: true, hasTouch: true, viewport: { width: 1024, height: 1366 } });
+
+  test("an empty draft holds a disabled send disc until there is something to send", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "composer-placeholder-send-" });
+    try {
+      await gotoWorkspace(page, workspace.workspaceId);
+      await clickNewChat(page);
+      const send = page
+        .getByTestId("message-input-root")
+        .filter({ visible: true })
+        .getByRole("button", { name: "Send message", exact: true });
+      await expect(send).toBeDisabled({ timeout: 30_000 });
+      await fillComposerDraft(page, "Refactor the composer toolbar");
+      await expect(send).toBeEnabled();
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/composer-diff-stat.spec.ts b/packages/app/e2e/browser/composer-diff-stat.spec.ts
index 959567f58b..5dd2b8ae1d 100644
--- a/packages/app/e2e/browser/composer-diff-stat.spec.ts
+++ b/packages/app/e2e/browser/composer-diff-stat.spec.ts
@@ -1,7 +1,9 @@
-import type { Locator } from "@playwright/test";
+import type { CDPSession, Locator } from "@playwright/test";
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { expect, test, type Page } from "../support/fixtures";
+import { seedSubagent } from "../support/helpers/subagents";
+import { submitMessage } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import { gateNextAgentMessage } from "../support/helpers/agent-message-gate";
 import {
@@ -78,7 +80,8 @@ test("composer diff stat reveals Changes, then opens the diff in the configured
   const workspace = await seedChangedAgent("composer-diff-stat-side-");
 
   try {
-    await page.setViewportSize({ width: 1400, height: 900 });
+    // Keep both workspace rails visible alongside app navigation and Explorer.
+    await page.setViewportSize({ width: 1900, height: 900 });
     await openAgentRoute(page, {
       workspaceId: workspace.workspaceId,
       agentId: workspace.agentId,
@@ -859,3 +862,91 @@ async function expectReviewEditorBody(page: Page, body: string) {
     body,
   );
 }
+
+async function swipeComposerTracks(page: Page, client: CDPSession, direction: "left" | "right") {
+  const track = page.getByTestId("composer-track-scroll");
+  const box = await track.boundingBox();
+  if (!box) throw new Error("Composer tracks are not visible");
+  const start = direction === "left" ? box.x + box.width - 5 : box.x + 5;
+  const end = direction === "left" ? box.x + 5 : box.x + box.width - 5;
+  await swipeTouch(client, start, end, box.y + box.height / 2);
+}
+
+async function swipeTouch(client: CDPSession, start: number, end: number, y: number) {
+  await client.send("Input.dispatchTouchEvent", {
+    type: "touchStart",
+    touchPoints: [{ x: start, y }],
+  });
+  for (let step = 1; step <= 8; step++) {
+    await client.send("Input.dispatchTouchEvent", {
+      type: "touchMove",
+      touchPoints: [{ x: start + ((end - start) * step) / 8, y }],
+    });
+  }
+  await client.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+}
+
+async function trackScrollOffset(track: Locator): Promise<number> {
+  return track.evaluate((node) => node.scrollLeft);
+}
+
+test.describe("touch composer tracks", () => {
+  test.use({ hasTouch: true, isMobile: true });
+  test("compact composer scrolls its task, subagent and changes tracks without squeezing them", async ({
+    page,
+  }) => {
+    const workspace = await seedChangedAgent("composer-tracks-overflow-");
+    const touch = await page.context().newCDPSession(page);
+    try {
+      await seedSubagent(
+        { client: workspace.client, repoPath: workspace.cwd, workspaceId: workspace.workspaceId },
+        { parentId: workspace.agentId, title: "Track child" },
+      );
+      await page.setViewportSize({ width: 1000, height: 844 });
+      await openAgentRoute(page, {
+        workspaceId: workspace.workspaceId,
+        agentId: workspace.agentId,
+      });
+      await submitMessage(page, "emit 1 agent stream updates");
+      const tasks = page.getByTestId("agent-task-list-header");
+      const subagents = page.getByTestId("subagents-track-header");
+      const changes = page.getByTestId("composer-diff-stat-pill");
+      await expect(tasks).toBeVisible();
+      await expect(subagents).toBeVisible();
+      await expect(changes).toBeVisible();
+      const wideWidths = await Promise.all(
+        [tasks, subagents, changes].map(async (pill) => (await pill.boundingBox())!.width),
+      );
+      await page.setViewportSize({ width: 200, height: 844 });
+      const narrowWidths = await Promise.all(
+        [tasks, subagents, changes].map(async (pill) => (await pill.boundingBox())!.width),
+      );
+      for (const [index, width] of wideWidths.entries())
+        expect(narrowWidths[index]).toBeGreaterThanOrEqual(width - 1);
+      const track = page.getByTestId("composer-track-scroll");
+      expect(await track.evaluate((node) => node.scrollWidth)).toBeGreaterThan(
+        await track.evaluate((node) => node.clientWidth),
+      );
+      await swipeComposerTracks(page, touch, "left");
+      await expect.poll(() => trackScrollOffset(track)).toBeGreaterThan(0);
+      await swipeComposerTracks(page, touch, "right");
+      await expect.poll(() => trackScrollOffset(track)).toBeLessThanOrEqual(1);
+      await swipeComposerTracks(page, touch, "left");
+      await expect.poll(() => trackScrollOffset(track)).toBeGreaterThan(0);
+      await expect(page.getByTestId("sidebar-sessions")).not.toBeInViewport();
+      await expect(page.getByTestId("workspace-explorer-sidebar")).not.toBeInViewport();
+      await page.getByRole("button", { name: "Open menu" }).click();
+      await expect(page.getByTestId("sidebar-sessions")).toBeInViewport({ ratio: 1 });
+      await page.getByTestId("sidebar-close").click();
+      await expect(page.getByTestId("sidebar-sessions")).not.toBeInViewport();
+      await expect(changes).toBeInViewport();
+      await changes.click();
+      await expect(
+        page.getByTestId("changes-header").filter({ visible: true }).first(),
+      ).toBeVisible();
+    } finally {
+      await touch.detach();
+      await workspace.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/composer-focus.spec.ts b/packages/app/e2e/browser/composer-focus.spec.ts
index 5557e9e9ac..61d2a5a35e 100644
--- a/packages/app/e2e/browser/composer-focus.spec.ts
+++ b/packages/app/e2e/browser/composer-focus.spec.ts
@@ -1,5 +1,11 @@
 import { expect, test, type Page } from "../support/fixtures";
 import {
+  pasteRichTextIntoComposer,
+  fillComposerDraft,
+  copyLatestTurnIntoComposer,
+  selectComposerDraftRange,
+  undoComposerEdit,
+  redoComposerEdit,
   blurComposerInput,
   roundTripComposerTabBeforePaint,
   composerLocator,
@@ -13,6 +19,7 @@ import {
   expectWorkspaceHeaderVisible,
   resizeComposerViewport,
   submitMessage,
+  submitMessageWithButton,
   typeIntoFocusedComposer,
 } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
@@ -25,9 +32,10 @@ import {
   expectMobileAgentSidebarVisible,
   expectMobileExplorerHidden,
   expectMobileExplorerVisible,
-  swipeOpenMobileAgentSidebar,
+  openMobileAgentSidebarWithKeyboard,
   swipeOpenMobileExplorer,
 } from "../support/helpers/sidebar";
+import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
 import { readScrollMetrics } from "../support/helpers/agent-bottom-anchor";
 import {
   expectTimelinePromptPositionPreserved,
@@ -55,7 +63,9 @@ test("clicking chat text or background focuses the feed for keyboard paging", as
     await expect
       .poll(async () => (await readScrollMetrics(page)).offsetY)
       .toBeLessThan(beforePaging.offsetY - beforePaging.viewportHeight / 2);
-    await page.screenshot({ path: testInfo.outputPath("chat-keyboard-paging.png") });
+    await page.screenshot({
+      path: testInfo.outputPath("chat-keyboard-paging.png"),
+    });
     await page.keyboard.press("PageDown");
     await expect
       .poll(async () => (await readScrollMetrics(page)).distanceFromBottom)
@@ -124,20 +134,86 @@ test("focusing the feed preserves assistant text selection and code copy control
 });
 
 test("submitting a message leaves the composer ready for the next message", async ({ page }) => {
+  const copiedTable =
+    "| Resource | Status |\n| --- | --- |\n| [Unicode](https://example.com/日本語) | ~~closed~~ |\n| [Space](<https://example.com/a b>) | **open** |\n| [ASCII](https://example.com/1) | closed |";
   const agent = await seedMockAgentWorkspace({
     repoPrefix: "composer-focus-",
     title: "Composer focus",
+    featureValues: { mockAssistantResponse: copiedTable },
   });
 
+  const connection = await installDaemonWebSocketGate(page);
   try {
     await openAgentRoute(page, agent);
     await expectComposerVisible(page);
 
+    await submitMessageWithButton(page, "Pointer submission");
+    await expectComposerDraft(page, "");
+    await expectComposerFocused(page);
+    await typeIntoFocusedComposer(page, "Ready after Send");
+    await expectComposerDraft(page, "Ready after Send");
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await expectComposerFocused(page);
+
     await submitMessage(page, "First message");
     await expectComposerFocused(page);
 
-    await typeIntoFocusedComposer(page, "Second message");
-    await expectComposerDraft(page, "Second message");
+    await typeIntoFocusedComposer(page, "Investigate: replace this. Thanks");
+    await selectComposerDraftRange(page, 13, 25);
+    await pasteRichTextIntoComposer({
+      page,
+      html: '<a href="https://example.com/issues/39150">this FR</a>',
+      text: "this FR",
+    });
+    await expectComposerDraft(
+      page,
+      "Investigate: [this FR](https://example.com/issues/39150). Thanks",
+    );
+    await undoComposerEdit(page);
+    await expectComposerDraft(page, "Investigate: replace this. Thanks");
+    await redoComposerEdit(page);
+    await expectComposerDraft(
+      page,
+      "Investigate: [this FR](https://example.com/issues/39150). Thanks",
+    );
+    await typeIntoFocusedComposer(page, " next");
+    await expectComposerDraft(
+      page,
+      "Investigate: [this FR](https://example.com/issues/39150) next. Thanks",
+    );
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await expect(page.getByRole("button", { name: "Copy turn", exact: true }).last()).toBeVisible();
+    await connection.drop();
+    await connection.waitForBlockedConnection();
+    await pasteRichTextIntoComposer({
+      page,
+      html: '<a href="https://example.com/offline">offline link</a>',
+      text: "offline link",
+    });
+    await expectComposerDraft(
+      page,
+      "Investigate: [this FR](https://example.com/issues/39150) next[offline link](https://example.com/offline). Thanks",
+    );
+    await fillComposerDraft(page, "");
+    await pasteRichTextIntoComposer({
+      page,
+      html: '<table><thead><tr><th>Resource</th><th>Status</th></tr></thead><tbody><tr><td><a href="https://example.com/issue">Issue</a></td><td>closed</td></tr></tbody></table>',
+      text: "Resource\tStatus\nIssue\tclosed",
+    });
+    await expectComposerDraft(
+      page,
+      "| Resource | Status |\n| --- | --- |\n| [Issue](https://example.com/issue) | closed |",
+    );
+    await fillComposerDraft(page, "");
+    await pasteRichTextIntoComposer({
+      page,
+      html: '<a href="https://example.com/">Issue</a><table></table>',
+      text: "Issue",
+    });
+    await expectComposerDraft(page, "[Issue](https://example.com/)");
+    await copyLatestTurnIntoComposer(page);
+    await expectComposerDraft(page, copiedTable);
+    await expectComposerFocused(page);
   } finally {
     await agent.cleanup();
   }
@@ -168,7 +244,11 @@ async function waitForAnimationFrames(page: Page, count: number): Promise<void>
 test.describe("touch screen wide enough for the desktop layout", () => {
   // A tablet or an unfolded foldable gets the desktop layout, but focusing the
   // composer there raises the on-screen keyboard over the conversation.
-  test.use({ viewport: { width: 1024, height: 768 }, isMobile: true, hasTouch: true });
+  test.use({
+    viewport: { width: 1024, height: 768 },
+    isMobile: true,
+    hasTouch: true,
+  });
 
   test("remounting an inline composer does not restore focus on touch", async ({ page }) => {
     const agent = await seedMockAgentWorkspace({
@@ -192,7 +272,9 @@ test.describe("touch screen wide enough for the desktop layout", () => {
   test("returning to an inactive inline composer does not restore focus on touch", async ({
     page,
   }) => {
-    const workspace = await seedWorkspace({ repoPrefix: "composer-touch-retained-" });
+    const workspace = await seedWorkspace({
+      repoPrefix: "composer-touch-retained-",
+    });
     try {
       const first = await createMockIdleAgent(workspace.client, {
         cwd: workspace.repoPath,
@@ -240,6 +322,9 @@ test.describe("touch screen wide enough for the desktop layout", () => {
       // Autofocus makes its first attempt on the next animation frame.
       await waitForAnimationFrames(page, 4);
       await expectComposerNotFocused(page);
+      await submitMessageWithButton(page, "Touch submission");
+      await expectComposerDraft(page, "");
+      await expectComposerNotFocused(page);
     } finally {
       await agent.cleanup();
     }
@@ -249,7 +334,7 @@ test.describe("touch screen wide enough for the desktop layout", () => {
 const COMPACT_PANELS = [
   {
     name: "agent list",
-    open: swipeOpenMobileAgentSidebar,
+    open: openMobileAgentSidebarWithKeyboard,
     expectOpen: expectMobileAgentSidebarVisible,
     close: closeMobileAgentSidebar,
     expectClosed: expectMobileAgentSidebarHidden,
diff --git a/packages/app/e2e/browser/composer-recall.spec.ts b/packages/app/e2e/browser/composer-recall.spec.ts
index 368d23409c..a58a8ff59e 100644
--- a/packages/app/e2e/browser/composer-recall.spec.ts
+++ b/packages/app/e2e/browser/composer-recall.spec.ts
@@ -3,7 +3,7 @@ import {
   composerLocator,
   expectComposerDraft,
   expectComposerVisible,
-  submitMessage,
+  fillComposerDraft,
   typeIntoFocusedComposer,
 } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
@@ -12,8 +12,14 @@ function userMessages(page: Page) {
   return page.getByTestId("user-message");
 }
 
+async function sendDraftWhenReady(page: Page) {
+  await expect(page.getByRole("button", { name: "Send message", exact: true })).toBeEnabled();
+  await pressInComposer(page, "Enter");
+}
+
 async function sendAndWaitForMessage(page: Page, text: string, expectedCount: number) {
-  await submitMessage(page, text);
+  await fillComposerDraft(page, text);
+  await sendDraftWhenReady(page);
   await expect(userMessages(page)).toHaveCount(expectedCount, { timeout: 30_000 });
   await expectComposerDraft(page, "");
 }
@@ -49,7 +55,7 @@ test.describe("Composer recall", () => {
       await pressInComposer(page, "ArrowUp");
       await expectComposerDraft(page, "add tests for login");
 
-      await pressInComposer(page, "Enter");
+      await sendDraftWhenReady(page);
       await expect(userMessages(page)).toHaveCount(3, { timeout: 30_000 });
       await expect(userMessages(page).last()).toContainText("add tests for login");
     } finally {
diff --git a/packages/app/e2e/browser/composer-whitespace.spec.ts b/packages/app/e2e/browser/composer-whitespace.spec.ts
index 8e1a527f0f..9ad03112db 100644
--- a/packages/app/e2e/browser/composer-whitespace.spec.ts
+++ b/packages/app/e2e/browser/composer-whitespace.spec.ts
@@ -37,7 +37,7 @@ import {
   closeMobileAgentSidebar,
   expectMobileAgentSidebarHidden,
   expectMobileAgentSidebarVisible,
-  swipeOpenMobileAgentSidebar,
+  openMobileAgentSidebarWithKeyboard,
 } from "../support/helpers/sidebar";
 
 async function composerHeight(page: Page): Promise<number> {
@@ -541,8 +541,8 @@ test("the compact sidebar over a fullscreen editor leaves the exit action alone"
     await writeCompactDraft(page, draft);
     await enterComposerFullscreen(page);
     await expectWorkspaceHeaderHidden(page);
-    // Fullscreen hides the header's menu button; the edge swipe still opens the list over it.
-    await swipeOpenMobileAgentSidebar(page);
+    // Fullscreen hides the header's menu button; the keyboard shortcut opens the list over it.
+    await openMobileAgentSidebarWithKeyboard(page);
     await expectMobileAgentSidebarVisible(page);
     // The list covers the pane, so the editor's exit action is not armed.
     await page.keyboard.press("Escape");
diff --git a/packages/app/e2e/browser/context-window-meter.spec.ts b/packages/app/e2e/browser/context-window-meter.spec.ts
index be0835b116..82e75b151a 100644
--- a/packages/app/e2e/browser/context-window-meter.spec.ts
+++ b/packages/app/e2e/browser/context-window-meter.spec.ts
@@ -21,6 +21,7 @@ import {
   openAgent,
   pressContextWindowMeter,
   qaScreenshot,
+  recordContextWindowFrames,
   refreshUsageCard,
   reloadAgent,
   scriptAgentUsage,
@@ -299,9 +300,10 @@ for (const theme of ["light", "dark"] as const) {
       const slowSource = gate();
       usage.answerNext({ stream: [slowSource.promise, onWorkLogin(claude!)] });
       const closedEarly = await hoverContextWindowMeter(page);
-      await expect(closedEarly.getByText("Loading usage...", { exact: true })).toBeVisible();
+      await expect(usageCard(closedEarly, "claude:work").getByText(LOGIN_EXPIRED)).toBeVisible();
       await leaveContextWindowMeter(page);
 
+      await usage.resumeAgent(agent);
       const resumed = gate();
       const finished = gate();
       usage.answerNext({
@@ -385,6 +387,58 @@ for (const theme of ["light", "dark"] as const) {
   });
 }
 
+test("an open with loaded usage paints it in its first frame and never moves", async ({
+  page,
+  agent,
+}) => {
+  const [claude] = claudeAndCodexReports();
+  const usage = await scriptAgentUsage(page);
+  await page.setViewportSize(DESKTOP);
+  await openAgent(page, agent);
+  usage.answerNext([onWorkLogin(claude!)]);
+  const loaded = await hoverContextWindowMeter(page);
+  await expect(usageCard(loaded, "claude:work")).toBeVisible();
+  await leaveContextWindowMeter(page);
+
+  // The reopen's own request stays unanswered until the card has been on screen a while.
+  const refetch = gate();
+  usage.answerNext({ stream: [refetch.promise, onWorkLogin(claude!)] });
+  const recording = await recordContextWindowFrames(page);
+  const reopened = await hoverContextWindowMeter(page);
+  await page.waitForTimeout(300);
+  refetch.open();
+  await page.waitForTimeout(300);
+  await expect(usageCard(reopened, "claude:work")).toBeVisible();
+  const frames = (await recording.stop()).filter((frame) => frame.mounted);
+  await leaveContextWindowMeter(page);
+
+  expect(frames.filter((frame) => frame.loading)).toEqual([]);
+  expect(frames.filter((frame) => frame.usageCards !== 1)).toEqual([]);
+  expect(new Set(frames.map((frame) => frame.bottom)).size).toBe(1);
+});
+
+test("usage arriving after the card opens never moves its bottom edge", async ({ page, agent }) => {
+  const [claude] = claudeAndCodexReports();
+  const usage = await scriptAgentUsage(page);
+  await page.setViewportSize(DESKTOP);
+  await openAgent(page, agent);
+
+  const arrival = gate();
+  usage.answerNext({ stream: [arrival.promise, onWorkLogin(claude!)] });
+  const recording = await recordContextWindowFrames(page);
+  const card = await hoverContextWindowMeter(page);
+  await expect(card.getByText("Loading usage...", { exact: true })).toBeVisible();
+  arrival.open();
+  await expect(usageCard(card, "claude:work")).toBeVisible();
+  await page.waitForTimeout(300);
+  const frames = (await recording.stop()).filter((frame) => frame.mounted);
+  await leaveContextWindowMeter(page);
+
+  expect(frames.some((frame) => frame.loading)).toBe(true);
+  expect(frames.at(-1)?.usageCards).toBe(1);
+  expect(new Set(frames.map((frame) => frame.bottom)).size).toBe(1);
+});
+
 test("context details support keyboard entry and dismiss when the viewport moves", async ({
   page,
   agent,
@@ -429,6 +483,32 @@ test("context details support keyboard entry and dismiss when the viewport moves
   await expect(details).toHaveCount(0);
 });
 
+test("context details stay open while the chat streams", async ({ page }) => {
+  test.setTimeout(120_000);
+  await page.setViewportSize(DESKTOP);
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "context-window-streaming-",
+    title: "Context details while streaming",
+    model: "ten-second-stream",
+  });
+  try {
+    await openAgentRoute(page, session);
+    await expectComposerVisible(page);
+    await submitMessageWithButton(page, "Stream while the context details are open.");
+    const stop = page.getByRole("button", { name: /stop|cancel/i }).first();
+    await expect(stop).toBeVisible();
+    const details = await pressContextWindowMeter(page, /^Context window/);
+    await expect(stop).toBeVisible();
+    await qaScreenshot(page, "context-details-while-streaming");
+
+    await expect(stop).toHaveCount(0, { timeout: 30_000 });
+    await expect(details).toBeVisible();
+    await qaScreenshot(page, "context-details-after-streaming");
+  } finally {
+    await session.cleanup();
+  }
+});
+
 test("pointer hovering context details preserves composer focus", async ({ page, agent }) => {
   const usage = await scriptAgentUsage(page);
   await page.setViewportSize(DESKTOP);
diff --git a/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts b/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
index 0c3787f46d..b49e89cde7 100644
--- a/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
+++ b/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
@@ -1,3 +1,5 @@
+import { installLocalDesktopHost } from "../support/helpers/local-desktop-host";
+import type { Locator, Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
 import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
 import {
@@ -9,6 +11,7 @@ import { seedWorkspace } from "../support/helpers/seed-client";
 import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
 
 test.describe("Direct terminal shortcut pane placement", () => {
+  test.use({ viewport: { width: 1600, height: 900 } });
   test("opens a terminal in the focused pane", async ({ page }) => {
     const workspace = await seedWorkspace({ repoPrefix: "direct-terminal-shortcut-pane-" });
 
@@ -47,3 +50,91 @@ test.describe("Direct terminal shortcut pane placement", () => {
     }
   });
 });
+
+async function prepareNarrowSplit(page: Page, workspaceId: string) {
+  await page.setViewportSize({ width: 1600, height: 900 });
+  await gotoWorkspace(page, workspaceId);
+  await waitForWorkspaceTabsVisible(page);
+  await clickNewChat(page);
+  await runWorkspaceActionFromCommandCenter(page, "Split pane right");
+  const draftPane = page
+    .locator('[data-testid^="workspace-pane-"]')
+    .filter({ has: page.getByTestId("message-input-root") });
+  const emptyPane = page
+    .locator('[data-testid^="workspace-pane-"]')
+    .filter({ has: page.getByTestId("workspace-new-tab-panel") });
+  const draftPaneId = await draftPane.getAttribute("data-testid");
+  const emptyPaneId = await emptyPane.getAttribute("data-testid");
+  expect(draftPaneId).not.toBeNull();
+  expect(emptyPaneId).not.toBeNull();
+  await page.setViewportSize({ width: 760, height: 900 });
+  return {
+    originalPane: page.getByTestId(draftPaneId!),
+    otherPane: page.getByTestId(emptyPaneId!),
+  };
+}
+
+async function expectPanesKeepTabRails(page: Page, panes: Locator[]) {
+  for (const pane of panes) {
+    await expect(pane.getByTestId("workspace-tabs-row")).toBeVisible();
+  }
+  await expect(
+    page.getByTestId("workspace-tab-switcher-trigger").filter({ visible: true }),
+  ).toHaveCount(0);
+}
+
+async function launchTerminalFromPaneRail(page: Page, pane: Locator) {
+  await pane.getByTestId("workspace-new-tab-button").click();
+  await page.getByTestId("workspace-new-tab-menu-terminal").filter({ visible: true }).click();
+  await expect(pane.getByTestId("terminal-surface")).toBeVisible({ timeout: 30_000 });
+}
+
+async function maximizeAndRestorePane(pane: Locator) {
+  await pane.getByTestId("workspace-maximize-pane").click();
+  await pane.getByTestId("workspace-restore-pane").click();
+}
+
+test("narrow split panes keep their tab rails and launches stay in the owning pane", async ({
+  page,
+}) => {
+  const workspace = await seedWorkspace({ repoPrefix: "narrow-split-launch-" });
+  try {
+    const { originalPane, otherPane } = await prepareNarrowSplit(page, workspace.workspaceId);
+    await expectPanesKeepTabRails(page, [originalPane, otherPane]);
+    await launchTerminalFromPaneRail(page, originalPane);
+    await expect(otherPane.getByTestId("workspace-new-tab-panel")).toBeVisible();
+    await maximizeAndRestorePane(originalPane);
+    await expect(otherPane).toBeVisible();
+    await expectPanesKeepTabRails(page, [originalPane, otherPane]);
+  } finally {
+    await workspace.cleanup();
+  }
+});
+
+async function expectPaneHasWindowDragSurface(pane: Locator) {
+  await expect
+    .poll(() =>
+      pane.evaluate((element) =>
+        Array.from(element.querySelectorAll<HTMLElement>("div")).some(
+          (node) => node.style.getPropertyValue("-webkit-app-region") === "drag",
+        ),
+      ),
+    )
+    .toBe(true);
+}
+
+test("narrow desktop split panes retain window dragging with both sidebars closed", async ({
+  page,
+}) => {
+  const workspace = await seedWorkspace({ repoPrefix: "narrow-split-window-drag-" });
+  try {
+    await installLocalDesktopHost(page, workspace.repoPath);
+    const { originalPane, otherPane } = await prepareNarrowSplit(page, workspace.workspaceId);
+    await runWorkspaceActionFromCommandCenter(page, "Toggle left sidebar");
+    await expectPanesKeepTabRails(page, [originalPane, otherPane]);
+    await expectPaneHasWindowDragSurface(originalPane);
+    await expectPaneHasWindowDragSurface(otherPane);
+  } finally {
+    await workspace.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/empty-pane-keyboard.spec.ts b/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
index 46dc4cf47f..8430fe5974 100644
--- a/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
+++ b/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
@@ -56,9 +56,9 @@ test.describe("New tab keyboard launcher", () => {
       await expectLauncherSelection(launcher, "Diff");
       await page.keyboard.press("Enter");
 
-      await expect(
-        page.getByTestId("workspace-tab-working_diff").filter({ visible: true }),
-      ).toBeVisible({ timeout: 30_000 });
+      await expect(page.getByTestId("working-diff-panel").filter({ visible: true })).toBeVisible({
+        timeout: 30_000,
+      });
     } finally {
       await workspace.cleanup();
     }
diff --git a/packages/app/e2e/browser/explorer-pane-placement.spec.ts b/packages/app/e2e/browser/explorer-pane-placement.spec.ts
index 55f96cc0cf..9a4a7127fe 100644
--- a/packages/app/e2e/browser/explorer-pane-placement.spec.ts
+++ b/packages/app/e2e/browser/explorer-pane-placement.spec.ts
@@ -105,6 +105,9 @@ function collectConsoleErrors(page: Page): string[] {
   return errors;
 }
 
+// These drag and tab-menu journeys need full rails beside the docked Explorer.
+test.use({ viewport: { width: 1900, height: 900 } });
+
 test.describe("explorer pane tab placement", () => {
   test("agents open in the main pane and New-tab splits keep the app usable", async ({
     page,
diff --git a/packages/app/e2e/browser/explorer-resize-performance.spec.ts b/packages/app/e2e/browser/explorer-resize-performance.spec.ts
index 33cf48c94c..ca2ec5bf13 100644
--- a/packages/app/e2e/browser/explorer-resize-performance.spec.ts
+++ b/packages/app/e2e/browser/explorer-resize-performance.spec.ts
@@ -79,6 +79,12 @@ async function previewExplorerResize(page: Page, distance: number) {
   return { ...measurement, width: after };
 }
 
+async function expectCleanChangesLoaded(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("changes-tree-panel").getByText("No changes to display", { exact: true }),
+  ).toBeVisible();
+}
+
 async function expectExplorerWidthSurvivesReload(page: Page, width: number): Promise<void> {
   await page.reload();
   const explorer = page.getByTestId("workspace-explorer-sidebar");
@@ -100,6 +106,7 @@ test("Explorer drag previews without rerendering panes or rewriting the shared s
   await runWorkspaceActionFromCommandCenter(page, "Split pane right");
   await page.getByTestId("workspace-explorer-toggle").first().click();
   await expect(page.getByTestId("workspace-explorer-sidebar")).toBeVisible();
+  await expectCleanChangesLoaded(page);
   // Verify that direct pane renders are being counted before resetting them.
   expect(
     await page.evaluate(() =>
diff --git a/packages/app/e2e/browser/explorer-sidebar.spec.ts b/packages/app/e2e/browser/explorer-sidebar.spec.ts
index 06a6994332..b63775ab2b 100644
--- a/packages/app/e2e/browser/explorer-sidebar.spec.ts
+++ b/packages/app/e2e/browser/explorer-sidebar.spec.ts
@@ -13,6 +13,7 @@ import {
   ensureExplorerSidebar,
   openFilesPanel,
   waitForWorkspaceTabsVisible,
+  dragTabIntoExplorer,
 } from "../support/helpers/workspace-tabs";
 
 function explorerSidebar(page: Parameters<typeof ensureExplorerSidebar>[0]) {
@@ -194,26 +195,6 @@ test("Explorer keeps Files and Changes close actions in the context menu", async
   }
 });
 
-async function dragTabIntoExplorer(
-  page: Parameters<typeof ensureExplorerSidebar>[0],
-  tabId: string,
-) {
-  const source = page.getByTestId("workspace-pane-main").getByTestId(`workspace-tab-${tabId}`);
-  const destination = explorerSidebar(page).getByTestId("workspace-tab-files");
-  const sourceBox = await source.boundingBox();
-  const destinationBox = await destination.boundingBox();
-  if (!sourceBox || !destinationBox)
-    throw new Error("Tab drag requires visible source and destination");
-  const start = { x: sourceBox.x + 12, y: sourceBox.y + sourceBox.height / 2 };
-  await page.mouse.move(start.x, start.y);
-  await page.mouse.down();
-  await page.mouse.move(start.x + 12, start.y + 4);
-  await page.mouse.move(destinationBox.x + 12, destinationBox.y + destinationBox.height / 2, {
-    steps: 20,
-  });
-  await page.mouse.up();
-}
-
 test("moves agents into Explorer and keeps the shared Agent launcher available", async ({
   page,
 }, testInfo) => {
diff --git a/packages/app/e2e/browser/file-editing.spec.ts b/packages/app/e2e/browser/file-editing.spec.ts
index 0266d02691..a395a517c2 100644
--- a/packages/app/e2e/browser/file-editing.spec.ts
+++ b/packages/app/e2e/browser/file-editing.spec.ts
@@ -63,6 +63,24 @@ function htmlPreview(page: Page) {
   };
 }
 
+async function followHtmlPreviewLink(page: Page, name: string): Promise<void> {
+  await htmlPreview(page).document.getByRole("link", { name, exact: true }).click();
+}
+
+async function expectPageHandlesFragment(
+  page: Page,
+  handler: "Document" | "Window",
+): Promise<void> {
+  const preview = htmlPreview(page);
+  await followHtmlPreviewLink(page, `${handler} handled jump`);
+  await expect(preview.document.getByRole("status")).toHaveText(`${handler} handled click`);
+  await expect(
+    preview.document.getByRole("heading", { name: "Target section" }),
+  ).not.toBeInViewport();
+  expect(await preview.document.locator("body").evaluate(() => location.hash)).toBe("");
+  expect(await preview.document.locator("body").evaluate(() => window.scrollY)).toBe(0);
+}
+
 async function selectFileView(page: Page, view: "Preview" | "Source"): Promise<void> {
   const option = page.getByTestId("file-panel-bar").getByRole("button", {
     name: view,
@@ -417,7 +435,8 @@ test.describe("CodeMirror workspace file editing", () => {
     });
 
     try {
-      await page.setViewportSize({ width: 1280, height: 900 });
+      // Keep both tab rails available alongside the docked Explorer.
+      await page.setViewportSize({ width: 1900, height: 900 });
       await openAgentRoute(page, session);
 
       await openWorkspaceFile(page, "target.ts");
@@ -826,6 +845,192 @@ test.describe("CodeMirror workspace file editing", () => {
     await expect(preview.host).toBeVisible();
   });
 
+  test("keeps HTML fragment links in the preview and scrolls to the target", async ({
+    page,
+    withWorkspace,
+  }) => {
+    const workspace = await withWorkspace({ prefix: "html-fragments-" });
+    await writeFile(
+      path.join(workspace.repoPath, "fragments.html"),
+      `<!doctype html><html><body>
+<a href="#section">Jump to section</a>
+<div style="height: 1200px"></div>
+<h2 id="section">Target section</h2>
+</body></html>`,
+      "utf8",
+    );
+    await workspace.navigateTo();
+    await openWorkspaceFile(page, "fragments.html");
+
+    const preview = htmlPreview(page);
+    await expect(preview.document.getByRole("link", { name: "Jump to section" })).toBeVisible();
+    await page.screenshot({ path: test.info().outputPath("fragment-before-click.png") });
+    await preview.document.getByRole("link", { name: "Jump to section" }).click();
+
+    await expect(
+      preview.document.getByRole("heading", { name: "Target section" }),
+    ).toBeInViewport();
+    expect(await preview.document.locator("body").evaluate(() => location.hash)).toBe("#section");
+    expect(await preview.document.locator("body").evaluate(() => window.scrollY)).toBeGreaterThan(
+      0,
+    );
+    await page.screenshot({ path: test.info().outputPath("fragment-after-click.png") });
+  });
+
+  test("lets an HTML page prevent fragment navigation", async ({ page, withWorkspace }) => {
+    const workspace = await withWorkspace({ prefix: "html-fragment-handler-" });
+    await writeFile(
+      path.join(workspace.repoPath, "handled.html"),
+      `<!doctype html><html><body>
+<a href="#section" onclick="event.preventDefault(); document.querySelector('output').textContent = 'Page handled click'">Handled jump</a>
+<output>Waiting for click</output>
+<div style="height: 1200px"></div><h2 id="section">Target section</h2>
+</body></html>`,
+      "utf8",
+    );
+    await workspace.navigateTo();
+    await openWorkspaceFile(page, "handled.html");
+
+    const preview = htmlPreview(page);
+    await preview.document.getByRole("link", { name: "Handled jump" }).click();
+    await expect(preview.document.locator("output")).toHaveText("Page handled click");
+    await expect(
+      preview.document.getByRole("heading", { name: "Target section" }),
+    ).not.toBeInViewport();
+    expect(await preview.document.locator("body").evaluate(() => location.hash)).toBe("");
+    expect(await preview.document.locator("body").evaluate(() => window.scrollY)).toBe(0);
+  });
+
+  test("respects delegated HTML fragment handlers and normal URL parsing", async ({
+    page,
+    withWorkspace,
+  }) => {
+    const workspace = await withWorkspace({ prefix: "html-fragment-defaults-" });
+    await writeFile(
+      path.join(workspace.repoPath, "defaults.html"),
+      `<!doctype html><html><body>
+<nav style="position: fixed; top: 0; background: white">
+<a href="#section" id="document-handler">Document handled jump</a>
+<a href="#section" id="window-handler">Window handled jump</a>
+<a href=" \t#section\n">Whitespace jump</a>
+<a href="#100%">Percent jump</a>
+<output>Waiting for click</output>
+</nav>
+<div style="height: 1200px"></div><h2 id="section">Target section</h2>
+<div style="height: 1200px"></div><h2 id="100%">Percent target</h2>
+<div style="height: 1200px"></div>
+<script>
+document.addEventListener('click', function(event) {
+  if (event.target.id === 'document-handler') {
+    event.preventDefault(); document.querySelector('output').textContent = 'Document handled click';
+  }
+});
+window.addEventListener('click', function(event) {
+  if (event.target.id === 'window-handler') {
+    event.preventDefault(); document.querySelector('output').textContent = 'Window handled click';
+  }
+});
+</script></body></html>`,
+      "utf8",
+    );
+    await workspace.navigateTo();
+    await openWorkspaceFile(page, "defaults.html");
+
+    const preview = htmlPreview(page);
+    await expectPageHandlesFragment(page, "Document");
+    await expectPageHandlesFragment(page, "Window");
+
+    await followHtmlPreviewLink(page, "Whitespace jump");
+    await expect(
+      preview.document.getByRole("heading", { name: "Target section" }),
+    ).toBeInViewport();
+    await followHtmlPreviewLink(page, "Percent jump");
+    await expect(
+      preview.document.getByRole("heading", { name: "Percent target" }),
+    ).toBeInViewport();
+  });
+
+  test("handles HTML fragment targets, empty and missing fragments, and modified clicks", async ({
+    page,
+    withWorkspace,
+  }) => {
+    const workspace = await withWorkspace({ prefix: "html-fragment-targets-" });
+    await writeFile(
+      path.join(workspace.repoPath, "targets.html"),
+      `<!doctype html><html><head><style>:target { color: rgb(255, 0, 0); }</style></head><body>
+<nav style="position: fixed; top: 0; background: white">
+<a href="#section"><span>Nested jump</span></a>
+<a href="#legacy">Named jump</a>
+<a href="#encoded%20section">Encoded jump</a>
+<a href="#missing">Missing jump</a>
+<a href="#">Empty jump</a>
+<output>Waiting for hashchange</output><output id="modified">Waiting for modified click</output>
+</nav>
+<div style="height: 1200px"></div><h2 id="section">Target section</h2>
+<div style="height: 1200px"></div><a name="legacy">Named target</a>
+<div style="height: 1200px"></div><h2 id="encoded section">Encoded target</h2>
+<div style="height: 1200px"></div>
+<script>
+window.addEventListener('hashchange', function () { document.querySelector('output').textContent = location.hash || '(empty)'; });
+function modifiedClick(event) {
+  if (event.button === 1 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) {
+    document.getElementById('modified').textContent = String(event.defaultPrevented);
+    event.preventDefault();
+  }
+}
+window.addEventListener('click', modifiedClick);
+window.addEventListener('auxclick', modifiedClick);
+window.addEventListener('contextmenu', modifiedClick);
+</script></body></html>`,
+      "utf8",
+    );
+    await workspace.navigateTo();
+    await openWorkspaceFile(page, "targets.html");
+
+    const preview = htmlPreview(page);
+    const body = preview.document.locator("body");
+    const nested = preview.document.getByText("Nested jump", { exact: true });
+    await nested.click();
+    await expect(preview.document.locator("output").first()).toHaveText("#section");
+    await expect(
+      preview.document.getByRole("heading", { name: "Target section" }),
+    ).toBeInViewport();
+    await expect(preview.document.locator("#section")).toHaveCSS("color", "rgb(255, 0, 0)");
+
+    await body.evaluate(() => window.scrollTo(0, 0));
+    await nested.click();
+    await expect(
+      preview.document.getByRole("heading", { name: "Target section" }),
+    ).toBeInViewport();
+
+    await preview.document.getByRole("link", { name: "Named jump" }).click();
+    await expect(preview.document.getByText("Named target", { exact: true })).toBeInViewport();
+    await expect(preview.document.locator("output").first()).toHaveText("#legacy");
+
+    await preview.document.getByRole("link", { name: "Encoded jump" }).click();
+    await expect(
+      preview.document.getByRole("heading", { name: "Encoded target" }),
+    ).toBeInViewport();
+    await expect(preview.document.locator("output").first()).toHaveText("#encoded%20section");
+    const scrollY = await body.evaluate(() => window.scrollY);
+    await preview.document.getByRole("link", { name: "Missing jump" }).click();
+    expect(await body.evaluate(() => location.hash)).toBe("#missing");
+    expect(await body.evaluate(() => window.scrollY)).toBe(scrollY);
+
+    await preview.document.getByRole("link", { name: "Empty jump" }).click();
+    await expect(preview.document.locator("output").first()).toHaveText("(empty)");
+    expect(await body.evaluate(() => window.scrollY)).toBe(0);
+
+    for (const modifier of ["Control", "Meta", "Shift", "Alt"] as const) {
+      await nested.click({ modifiers: [modifier] });
+      await expect(preview.document.locator("#modified")).toHaveText("false");
+    }
+    await nested.click({ button: "middle" });
+    await expect(preview.document.locator("#modified")).toHaveText("false");
+    expect(await body.evaluate(() => location.hash)).toBe("");
+    expect(await body.evaluate(() => window.scrollY)).toBe(0);
+  });
+
   test("runs inline scripts without allowing fetch egress", async ({ page, withWorkspace }) => {
     test.setTimeout(90_000);
     const workspace = await withWorkspace({ prefix: "file-editing-html-csp-" });
diff --git a/packages/app/e2e/browser/file-explorer-collapse.spec.ts b/packages/app/e2e/browser/file-explorer-collapse.spec.ts
index 705f667260..b00101c2ff 100644
--- a/packages/app/e2e/browser/file-explorer-collapse.spec.ts
+++ b/packages/app/e2e/browser/file-explorer-collapse.spec.ts
@@ -1,4 +1,6 @@
-import { test } from "../support/fixtures";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test } from "../support/fixtures";
 import {
   collapseFolder,
   expandFolder,
@@ -8,6 +10,7 @@ import {
   openFileExplorer,
   openFileFromExplorer,
 } from "../support/helpers/file-explorer";
+import { delayDirectoryListingResponse } from "../support/helpers/directory-listing-gate";
 import { gotoWorkspace } from "../support/helpers/launcher";
 import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
 
@@ -49,3 +52,66 @@ test.describe("File explorer collapse", () => {
     await expectExplorerEntryVisible(page, "guide.md");
   });
 });
+
+test("Files Refresh reveals new files when a cached collapsed folder is reopened", async ({
+  page,
+}) => {
+  await gotoWorkspace(page, workspace.workspaceId);
+  await openFileExplorer(page);
+  await expandFolder(page, "docs");
+  await expectExplorerEntryVisible(page, "guide.md");
+  await collapseFolder(page, "docs");
+  await expectExplorerEntryHidden(page, "guide.md");
+  await createFileOutsidePaseo("docs/NEW.md");
+  await refreshFiles(page);
+  await expandFolder(page, "docs");
+  await expectExplorerEntryVisible(page, "guide.md");
+  await expectExplorerEntryVisible(page, "NEW.md");
+
+  await createFileOutsidePaseo("docs/NEXT.md");
+  await refreshFiles(page);
+  await expectExplorerEntryVisible(page, "NEXT.md");
+});
+
+async function refreshFiles(page: import("@playwright/test").Page): Promise<void> {
+  const refresh = page.getByRole("button", { name: "Refresh files", exact: true });
+  await refresh.click();
+  await expect(refresh).toBeEnabled();
+}
+
+async function createFileOutsidePaseo(filePath: string): Promise<void> {
+  await writeFile(path.join(workspace.repoPath, filePath), "# New output\n");
+}
+
+test("Files Refresh ignores an old reply for a folder collapsed while loading", async ({
+  page,
+}) => {
+  const reply = await delayDirectoryListingResponse(page, "docs");
+  await gotoWorkspace(page, workspace.workspaceId);
+  await openFileExplorer(page);
+  await expandFolder(page, "docs");
+  await reply.waitUntilHeld();
+  await collapseFolder(page, "docs");
+  await createFileOutsidePaseo("docs/DELAYED.md");
+  await refreshFiles(page);
+  await reply.release();
+  await expandFolder(page, "docs");
+  await expectExplorerEntryVisible(page, "DELAYED.md");
+});
+
+test("Files Refresh preserves expanded folders while their saved view is restoring", async ({
+  page,
+}) => {
+  await gotoWorkspace(page, workspace.workspaceId);
+  await openFileExplorer(page);
+  await expandFolder(page, "docs");
+  await expectExplorerEntryVisible(page, "guide.md");
+  const reply = await delayDirectoryListingResponse(page, "docs");
+  await page.reload();
+  await openFileExplorer(page);
+  await reply.waitUntilHeld();
+  await refreshFiles(page);
+  await expectExplorerEntryVisible(page, "guide.md");
+  await reply.release();
+  await expectExplorerEntryVisible(page, "guide.md");
+});
diff --git a/packages/app/e2e/browser/file-explorer-context-actions.spec.ts b/packages/app/e2e/browser/file-explorer-context-actions.spec.ts
index faf7285a62..b64da21bd8 100644
--- a/packages/app/e2e/browser/file-explorer-context-actions.spec.ts
+++ b/packages/app/e2e/browser/file-explorer-context-actions.spec.ts
@@ -294,10 +294,17 @@ test("creates, renames, copies, and deletes entries through the file explorer",
 
   await entry("renamed.txt").click({ button: "right" });
   const deleteAction = page.getByTestId(/file-explorer-row-\d+-delete$/);
-  const deleteLabelColor = await deleteAction
-    .getByText("Delete", { exact: true })
-    .evaluate((element) => getComputedStyle(element).color);
-  await expect(deleteAction.locator("svg")).toHaveCSS("stroke", deleteLabelColor);
+  await expect
+    .poll(async () => {
+      const labelColor = await deleteAction
+        .getByText("Delete", { exact: true })
+        .evaluate((element) => getComputedStyle(element).color);
+      const iconColor = await deleteAction
+        .locator("svg")
+        .evaluate((element) => getComputedStyle(element).stroke);
+      return labelColor !== "" && iconColor === labelColor;
+    })
+    .toBe(true);
   const cancelledConfirmation = new Promise<string>((resolve) => {
     page.once("dialog", async (dialog) => {
       const message = dialog.message();
diff --git a/packages/app/e2e/browser/folder-links.spec.ts b/packages/app/e2e/browser/folder-links.spec.ts
index a893fbcb68..358c579357 100644
--- a/packages/app/e2e/browser/folder-links.spec.ts
+++ b/packages/app/e2e/browser/folder-links.spec.ts
@@ -81,6 +81,8 @@ for (const folder of [
   "docs/guides",
   "docs/guides/",
   "docs/指南",
+  "examples/next.js/",
+  "examples/next.js",
 ]) {
   test(`chat folder link opens folder contents: ${folder}`, async ({ page }) => {
     const session = await seedMockAgentWorkspace({
@@ -92,6 +94,9 @@ for (const folder of [
     try {
       await mkdir(path.join(session.cwd, folder), { recursive: true });
       await writeFile(path.join(session.cwd, folder, "guide.md"), "# Folder link destination\n");
+      const competingFile = path.join(session.cwd, "repo-a", folder.replace(/\/$/, ""));
+      await mkdir(path.dirname(competingFile), { recursive: true });
+      await writeFile(competingFile, "This is a file, not the requested folder.\n");
       await session.client.waitForFinish(session.agentId, 30_000);
       await page.addInitScript(() => {
         localStorage.setItem(
diff --git a/packages/app/e2e/browser/host-confirmation.spec.ts b/packages/app/e2e/browser/host-confirmation.spec.ts
index 6de8da14ce..10ca88392f 100644
--- a/packages/app/e2e/browser/host-confirmation.spec.ts
+++ b/packages/app/e2e/browser/host-confirmation.spec.ts
@@ -9,7 +9,7 @@ import {
   expectHostInHostPicker,
   hostConfirmation,
   openPairingLink,
-  saveLinkedHostBeforeLoad,
+  reopenPairingLinkWithSavedHosts,
   type LinkedHost,
 } from "../support/helpers/host-confirmation";
 
@@ -20,7 +20,9 @@ const linkedHost: LinkedHost = {
   daemonPublicKeyB64: "bGlua0NvbmZpcm1hdGlvbktleQ",
 };
 
-test("a pairing link for a new host asks before saving it", async ({ page }) => {
+test("a pairing link asks before saving a host and reconnects without asking again", async ({
+  page,
+}) => {
   const link = buildPairingLink(linkedHost);
 
   await test.step("Cancel saves nothing and stays on the page", async () => {
@@ -39,13 +41,10 @@ test("a pairing link for a new host asks before saving it", async ({ page }) =>
     await openSettings(page);
     await expectHostInHostPicker(page, linkedHost.serverId, "listed");
   });
-});
 
-test("a pairing link for a saved host connects without asking", async ({ page }) => {
-  await saveLinkedHostBeforeLoad(page, linkedHost);
-
-  await openPairingLink(page, buildPairingLink(linkedHost));
-
-  await expectAppRoute(page, "/open-project", { timeout: 30_000 });
-  await expect(hostConfirmation(page)).toHaveCount(0);
+  await test.step("reopening the saved host link connects without asking", async () => {
+    await reopenPairingLinkWithSavedHosts(page, link);
+    await expectAppRoute(page, "/open-project", { timeout: 30_000 });
+    await expect(hostConfirmation(page)).toHaveCount(0);
+  });
 });
diff --git a/packages/app/e2e/browser/mermaid-fullscreen.spec.ts b/packages/app/e2e/browser/mermaid-fullscreen.spec.ts
index 72b05ed83e..4b458c4d03 100644
--- a/packages/app/e2e/browser/mermaid-fullscreen.spec.ts
+++ b/packages/app/e2e/browser/mermaid-fullscreen.spec.ts
@@ -1,6 +1,8 @@
 import { test } from "../support/fixtures";
 import {
   closeDiagramFullscreen,
+  expectInlineDiagramFitsViewport,
+  toggleDiagramSourceAndVerifyControls,
   closeDiagramFullscreenFromOutside,
   expectCompletedDiagram,
   expectFullscreenDiagram,
@@ -21,6 +23,36 @@ const MERMAID_DIAGRAM = [
   "```",
 ].join("\n");
 
+test("bounds a tall inline diagram", async ({ page }) => {
+  test.setTimeout(120_000);
+  const diagram = [
+    "```mermaid",
+    "flowchart TD",
+    ...Array.from({ length: 30 }, (_, i) => `N${i} --> N${i + 1}`),
+    "```",
+  ].join("\n");
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "mermaid-tall-",
+    title: "Tall Mermaid",
+    featureValues: {
+      mockStreamingAssistantResponse: diagram,
+      mockStreamingAssistantIntervalMs: 10,
+    },
+  });
+  try {
+    await openAgentRoute(page, agent);
+    await requestDiagram(agent);
+    await waitForDiagramTurnToComplete(agent);
+    await expectCompletedDiagram(page, ["N0", "N30"]);
+    await expectInlineDiagramFitsViewport(page);
+    await openDiagramFullscreen(page);
+    await expectFullscreenDiagram(page, ["N0", "N30"]);
+    await closeDiagramFullscreen(page);
+  } finally {
+    await agent.cleanup();
+  }
+});
+
 test("opens a Mermaid diagram fullscreen and closes it again", async ({ page }) => {
   test.setTimeout(120_000);
 
@@ -40,6 +72,10 @@ test("opens a Mermaid diagram fullscreen and closes it again", async ({ page })
       await expectCompletedDiagram(page, ["Start", "Ship"]);
     });
 
+    await test.step("Source toggles preserve the diagram and exclude hidden controls", async () => {
+      await toggleDiagramSourceAndVerifyControls(page);
+    });
+
     await test.step("The toolbar opens the diagram fullscreen", async () => {
       await openDiagramFullscreen(page);
       await expectFullscreenDiagram(page, ["Start", "Review", "Ship"]);
diff --git a/packages/app/e2e/browser/new-workspace-entry.spec.ts b/packages/app/e2e/browser/new-workspace-entry.spec.ts
index 3f1710b918..90c9e19964 100644
--- a/packages/app/e2e/browser/new-workspace-entry.spec.ts
+++ b/packages/app/e2e/browser/new-workspace-entry.spec.ts
@@ -122,10 +122,14 @@ test.describe("New workspace entry points", () => {
       });
       const hostTrigger = page.getByTestId("host-picker-trigger");
       await expect(hostTrigger).toContainText("localhost", { timeout: 30_000 });
+      const originalUrl = page.url();
       await hostTrigger.click();
       await expect(page.getByTestId("new-workspace-host-picker-add-host")).toBeVisible();
       await page.getByTestId("new-workspace-host-picker-add-host").click();
-      await expect(page).toHaveURL(/\/settings\/general\?addHost=/);
+      await expect(
+        page.getByRole("button", { name: "Direct connection", exact: true }),
+      ).toBeVisible();
+      await expect(page).toHaveURL(originalUrl);
     } finally {
       await seeded.cleanup();
     }
diff --git a/packages/app/e2e/browser/new-workspace-live-pin.spec.ts b/packages/app/e2e/browser/new-workspace-live-pin.spec.ts
index 3ed0755fc9..135e9439f8 100644
--- a/packages/app/e2e/browser/new-workspace-live-pin.spec.ts
+++ b/packages/app/e2e/browser/new-workspace-live-pin.spec.ts
@@ -1,6 +1,7 @@
 import type { Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
 import { gotoAppShell } from "../support/helpers/app";
+import { expectComposerModel } from "../support/helpers/agent-profiles";
 import {
   delayBrowserAgentCreatedStatus,
   openNewWorkspaceComposer,
@@ -69,6 +70,8 @@ test.describe("New workspace live pin", () => {
       await gotoAppShell(page);
       await waitForSidebarHydration(page);
       await openNewWorkspaceComposer(page, seeded);
+      // The composer appears before its provider catalog has hydrated.
+      await expectComposerModel(page, "Ten second stream");
       await submitNewWorkspacePrompt(page, "Pin me while I start");
 
       await creation.waitForCreateRequest();
diff --git a/packages/app/e2e/browser/onboarding.spec.ts b/packages/app/e2e/browser/onboarding.spec.ts
new file mode 100644
index 0000000000..cf9ab06442
--- /dev/null
+++ b/packages/app/e2e/browser/onboarding.spec.ts
@@ -0,0 +1,448 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { expect, metroTest as test } from "../support/fixtures";
+import {
+  addProjectFromSetup,
+  continueSetup,
+  expectSetupStep,
+  finishSetup,
+  goToSetupStep,
+  hostGivesAgentsPaseoTools,
+  openAppAsNewUser,
+  openRelayPairingFromSetup,
+  closeRelayPairing,
+  emptyHome,
+  loadingScreen,
+  openTailscaleDocsFromSetup,
+  paseoToolsSwitch,
+  pickTheme,
+  projectSuggestion,
+  projectSuggestionRow,
+  readFirstLaunch,
+  recordFirstLaunch,
+  setupModal,
+  setupPrimaryButton,
+  showSetupAgainFromSettings,
+  skipSetup,
+  startSetupHost,
+} from "../support/helpers/onboarding";
+import {
+  chooseCustomSkills,
+  openSkillSelection,
+  saveSkillSelection,
+} from "../support/helpers/agent-skills";
+import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
+import { enableRelayAndExpectOffer } from "../support/helpers/pair-device";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { openSettingsHostSection } from "../support/helpers/settings";
+import { createTempDirectory, createTempGitRepo } from "../support/helpers/workspace";
+
+// Midnight's muted foreground (#9a9db0), which the step description is drawn in.
+const MIDNIGHT_MUTED_FOREGROUND = "rgb(154, 157, 176)";
+
+test("a new user is walked through setup once", async ({ page }, testInfo) => {
+  const host = await startSetupHost("fresh");
+  const repo = await createTempGitRepo("onboarding-folder-");
+
+  try {
+    await openAppAsNewUser(page, host);
+
+    await test.step("setup opens on Appearance and a theme applies at once", async () => {
+      await expectSetupStep(page, "Welcome to Paseo");
+      await pickTheme(page, "Midnight");
+      await expect(
+        setupModal(page).getByText("Let's start by picking a look", { exact: true }),
+      ).toHaveCSS("color", MIDNIGHT_MUTED_FOREGROUND);
+      await page.screenshot({ path: testInfo.outputPath("1-appearance.png") });
+    });
+
+    await test.step("Providers shows the same provider list as Settings", async () => {
+      await continueSetup(page);
+      await expectSetupStep(page, "Your agents");
+      await expect(setupModal(page).getByTestId("host-page-providers-card")).toBeVisible();
+      await page.screenshot({ path: testInfo.outputPath("2-providers.png") });
+    });
+
+    await test.step("with no agent history, Add project opens the regular flow and the folder shows as added", async () => {
+      await continueSetup(page);
+      await expectSetupStep(page, "Add your projects");
+      await expect(
+        setupModal(page).getByText("No recent projects found", { exact: true }),
+      ).toBeVisible({ timeout: 60_000 });
+      await addProjectFromSetup(page, repo.path);
+      await expectSetupStep(page, "Add your projects");
+      await expect(setupModal(page).getByText(repo.path, { exact: true })).toBeVisible();
+      await expect(setupModal(page).getByText("Added", { exact: true })).toBeVisible();
+      await page.screenshot({ path: testInfo.outputPath("3-projects.png") });
+    });
+
+    await test.step("Orchestration starts with its switches on", async () => {
+      await continueSetup(page);
+      await expectSetupStep(page, "Let agents use Paseo");
+      await expect(paseoToolsSwitch(setupModal(page))).toBeChecked();
+      await expect(
+        setupModal(page).getByRole("switch", { name: "Orchestration skills", exact: true }),
+      ).toBeChecked();
+      await page.screenshot({ path: testInfo.outputPath("4-orchestration.png") });
+    });
+
+    await test.step("Skip setup closes it for good", async () => {
+      await skipSetup(page);
+      await page.reload();
+      await expect(
+        page.locator('[data-testid^="sidebar-project-row-"]').filter({
+          hasText: path.basename(repo.path),
+        }),
+      ).toBeVisible({ timeout: 60_000 });
+      await expect(setupModal(page)).toHaveCount(0);
+    });
+  } finally {
+    await host.close();
+    await repo.cleanup();
+  }
+});
+
+test("a new user goes from the loading screen straight into setup", async ({ page }) => {
+  const host = await startSetupHost("first-launch");
+
+  try {
+    await recordFirstLaunch(page);
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+
+    const launch = await readFirstLaunch(page);
+    expect(launch.appBeforeSetup).toBe(false);
+    expect(launch.setupOpacityOnArrival).toBeLessThan(1);
+    await expect(setupModal(page)).toHaveCSS("opacity", "1");
+  } finally {
+    await host.close();
+  }
+});
+
+test("with reduced motion, setup appears without fading in", async ({ page }) => {
+  const host = await startSetupHost("reduced-motion");
+
+  try {
+    await page.emulateMedia({ reducedMotion: "reduce" });
+    await recordFirstLaunch(page);
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+
+    expect((await readFirstLaunch(page)).setupOpacityOnArrival).toBe(1);
+  } finally {
+    await host.close();
+  }
+});
+
+test("changing the theme keeps the setup window in place on every step", async ({ page }) => {
+  const host = await startSetupHost("theme-change");
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+    const setupWindow = await setupModal(page).elementHandle();
+
+    for (const title of [
+      "Welcome to Paseo",
+      "Your agents",
+      "Add your projects",
+      "Let agents use Paseo",
+      "Take your agents with you",
+    ]) {
+      if (title !== "Welcome to Paseo") await continueSetup(page);
+      await expectSetupStep(page, title);
+      const heading = setupModal(page).getByRole("heading", { name: title });
+      const headingNode = await heading.elementHandle();
+      const lightColor = await heading.evaluate((node) => getComputedStyle(node).color);
+      await page.emulateMedia({ colorScheme: "dark" });
+      await expect(heading).not.toHaveCSS("color", lightColor);
+      await page.emulateMedia({ colorScheme: "light" });
+      await expect(heading).toHaveCSS("color", lightColor);
+      expect(await setupWindow?.evaluate((node) => node.isConnected), title).toBe(true);
+      expect(await headingNode?.evaluate((node) => node.isConnected), title).toBe(true);
+    }
+
+    await goToSetupStep(page, "Appearance");
+    await pickTheme(page, "Midnight");
+    await pickTheme(page, "Light");
+    expect(await setupWindow?.evaluate((node) => node.isConnected)).toBe(true);
+  } finally {
+    await host.close();
+  }
+});
+
+test("the loading screen stays up while the setup host loads its workspaces", async ({ page }) => {
+  const host = await startSetupHost("slow-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    await recordFirstLaunch(page);
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await expect(loadingScreen(page)).toBeVisible();
+    await expect(emptyHome(page)).toHaveCount(0);
+
+    gate.releaseHeldClientRequest();
+    await expectSetupStep(page, "Welcome to Paseo");
+    expect((await readFirstLaunch(page)).appBeforeSetup).toBe(false);
+  } finally {
+    await host.close();
+  }
+});
+
+test("a setup host that never loads its workspaces still lands on the home", async ({ page }) => {
+  const host = await startSetupHost("stuck-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+    await expect(setupModal(page)).toHaveCount(0);
+
+    // Setup still opens once the host answers.
+    gate.releaseHeldClientRequest();
+    await expectSetupStep(page, "Welcome to Paseo");
+  } finally {
+    await host.close();
+  }
+});
+
+test("a setup host that drops while loading still lands on the home", async ({ page }) => {
+  const host = await startSetupHost("dropped-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await gate.drop();
+    await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+    await expect(setupModal(page)).toHaveCount(0);
+  } finally {
+    await host.close();
+  }
+});
+
+test("an unreachable setup host lands on the home without setup", async ({ page }) => {
+  const host = await startSetupHost("unreachable");
+  await host.close();
+
+  await openAppAsNewUser(page, host);
+  await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+  await expect(setupModal(page)).toHaveCount(0);
+});
+
+test("setup suggests the repos the user already ran agents in", async ({ page }, testInfo) => {
+  const repo = await createTempGitRepo("onboarding-history-");
+  const repoName = path.basename(repo.path);
+  const subdirectory = path.join(repo.path, "packages", "web");
+  await mkdir(subdirectory, { recursive: true });
+  const worktree = `${repo.path}-fix`;
+  execFileSync("git", ["worktree", "add", "-b", "fix", worktree], { cwd: repo.path });
+  const scratch = await createTempDirectory("onboarding-scratch-");
+  const scratchName = path.basename(scratch.path);
+  const host = await startSetupHost("history", {
+    claudeSessionsIn: [repo.path, subdirectory, worktree, scratch.path, scratch.path, scratch.path],
+    withBrokenProvider: true,
+  });
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+    await goToSetupStep(page, "Projects");
+    await expectSetupStep(page, "Add your projects");
+
+    await test.step("the repo, its subfolder and its worktree become one checked row", async () => {
+      await expect(projectSuggestion(page, repoName)).toBeChecked({ timeout: 60_000 });
+      await expect(projectSuggestion(page, scratchName)).toBeChecked();
+      await expect(setupModal(page).getByTestId("project-suggestion")).toHaveCount(2);
+    });
+
+    await test.step("a provider that cannot read its history adds nothing and shows no error", async () => {
+      await expect(setupModal(page).getByTestId("project-suggestions-skeleton")).toHaveCount(0, {
+        timeout: 60_000,
+      });
+      await expect(setupModal(page).getByText(/Broken ACP/)).toHaveCount(0);
+      await expect(setupModal(page).getByTestId("project-suggestion")).toHaveCount(2);
+    });
+
+    await test.step("the footer adds what is checked; the Add project flow is separate", async () => {
+      await expect(setupPrimaryButton(page, "Add 2 projects")).toBeVisible();
+      await expect(setupModal(page).getByRole("button", { name: "Continue" })).toHaveCount(0);
+      await expect(
+        setupModal(page).getByRole("button", { name: "Add project", exact: true }),
+      ).toBeVisible();
+      await page.screenshot({ path: testInfo.outputPath("8-project-suggestions.png") });
+      await projectSuggestion(page, repoName).click();
+      await projectSuggestion(page, scratchName).click();
+      await expect(setupPrimaryButton(page, "Continue")).toBeVisible();
+      await projectSuggestion(page, repoName).click();
+      await projectSuggestion(page, scratchName).click();
+    });
+
+    await test.step("a folder that cannot be added keeps the user on the step", async () => {
+      await scratch.cleanup();
+      await setupPrimaryButton(page, "Add 2 projects").click();
+      await expect(setupPrimaryButton(page, "Add 1 project")).toBeVisible({ timeout: 30_000 });
+      await expectSetupStep(page, "Add your projects");
+      await expect(projectSuggestion(page, scratchName)).toBeChecked();
+      await expect(projectSuggestionRow(page, scratchName)).toContainText("Directory not found");
+      await expect(projectSuggestion(page, repoName)).toHaveCount(0);
+      await page.screenshot({ path: testInfo.outputPath("9-project-suggestion-failed.png") });
+    });
+
+    await test.step("with nothing checked, Continue moves on without adding", async () => {
+      await projectSuggestion(page, scratchName).click();
+      await setupPrimaryButton(page, "Continue").click();
+      await expectSetupStep(page, "Let agents use Paseo");
+      await expect(
+        page.locator('[data-testid^="sidebar-project-row-"]').filter({ hasText: repoName }),
+      ).toBeVisible({ timeout: 60_000 });
+      await expect(
+        page.locator('[data-testid^="sidebar-project-row-"]').filter({ hasText: scratchName }),
+      ).toHaveCount(0);
+    });
+  } finally {
+    await host.close();
+    await rm(worktree, { recursive: true, force: true });
+    await repo.cleanup();
+    await scratch.cleanup();
+  }
+});
+
+test("an existing user only sees setup when they ask for it", async ({ page }) => {
+  const host = await startSetupHost("existing");
+  const workspace = await seedWorkspace({ repoPrefix: "onboarding-existing-", port: host.port });
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expect(
+      page.getByTestId(`sidebar-workspace-row-${host.serverId}:${workspace.workspaceId}`),
+    ).toBeVisible({ timeout: 60_000 });
+    await expect(setupModal(page)).toHaveCount(0);
+
+    await showSetupAgainFromSettings(page);
+    await expectSetupStep(page, "Welcome to Paseo");
+    await expect(setupModal(page).getByRole("tab", { name: "Appearance" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  } finally {
+    await workspace.cleanup();
+    await host.close();
+  }
+});
+
+test("setup choices carry over to Settings and the phone step pairs over relay", async ({
+  page,
+}, testInfo) => {
+  const host = await startSetupHost("phone", { mutableRelay: { enabled: false } });
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+
+    await test.step("Paseo tools start on in setup and Continue turns them on", async () => {
+      await goToSetupStep(page, "Orchestration");
+      await expectSetupStep(page, "Let agents use Paseo");
+      await expect(paseoToolsSwitch(setupModal(page))).toBeChecked();
+      await continueSetup(page);
+    });
+
+    await test.step("Phone offers Tailscale docs and pairs over relay in its own modal", async () => {
+      await expectSetupStep(page, "Take your agents with you");
+      await page.screenshot({ path: testInfo.outputPath("5-phone.png") });
+      expect(await openTailscaleDocsFromSetup(page)).toBe(
+        "https://paseo.sh/docs/connectivity#tailscale",
+      );
+      const pairing = await openRelayPairingFromSetup(page);
+      await expect(pairing.getByText("Enable relay?", { exact: true })).toBeVisible();
+      await enableRelayAndExpectOffer(page);
+      await page.screenshot({ path: testInfo.outputPath("6-phone-qr.png") });
+      await closeRelayPairing(pairing);
+    });
+
+    await test.step("Finish closes setup and Settings shows the same Paseo tools value", async () => {
+      await finishSetup(page);
+      await page.locator('[data-testid="sidebar-settings"]:visible').first().click();
+      await openSettingsHostSection(page, host.serverId, "agents");
+      await expect(paseoToolsSwitch(page)).toBeChecked();
+      await page.screenshot({ path: testInfo.outputPath("7-settings-agents.png") });
+    });
+  } finally {
+    await host.close();
+  }
+});
+
+test("with no skills picked, skills read as off and Continue moves on", async ({ page }) => {
+  const host = await startSetupHost("no-skills");
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+    await goToSetupStep(page, "Orchestration");
+    await expectSetupStep(page, "Let agents use Paseo");
+
+    await openSkillSelection(page);
+    await chooseCustomSkills(page, []);
+    await saveSkillSelection(page);
+    const skillsSwitch = setupModal(page).getByRole("switch", {
+      name: "Orchestration skills",
+      exact: true,
+    });
+    await expect(skillsSwitch).not.toBeChecked();
+
+    await continueSetup(page);
+    await expectSetupStep(page, "Take your agents with you");
+  } finally {
+    await host.close();
+  }
+});
+
+test("in the compact layout, Finish on Orchestration applies its switches", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  const host = await startSetupHost("compact");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+  // The compact sheet is the only surface on screen, and Orchestration is its last step.
+  const step = (title: string) =>
+    expect(page.getByRole("heading", { name: title, exact: true })).toBeVisible({
+      timeout: 60_000,
+    });
+  const primary = (label: string) => page.getByRole("button", { name: label, exact: true });
+
+  try {
+    await openAppAsNewUser(page, host);
+    await step("Welcome to Paseo");
+    await primary("Continue").click();
+    await step("Your agents");
+    await primary("Continue").click();
+    await step("Add your projects");
+    await primary("Continue").click();
+
+    // The setup host starts with Paseo tools off; the switch starts on.
+    expect(await hostGivesAgentsPaseoTools(host)).toBe(false);
+    await step("Let agents use Paseo");
+    await expect(paseoToolsSwitch(page)).toBeChecked();
+    // Skills are not installed, so leaving them off has nothing to apply.
+    const skillsSwitch = page.getByRole("switch", { name: "Orchestration skills", exact: true });
+    await skillsSwitch.click();
+    await expect(skillsSwitch).not.toBeChecked();
+    gate.holdNextClientRequest("set_daemon_config_request");
+    await primary("Finish").click();
+
+    // While the choices apply, none of them can change.
+    await gate.waitForHeldClientRequest();
+    await expect(paseoToolsSwitch(page)).toBeDisabled();
+    await expect(skillsSwitch).toBeDisabled();
+    gate.releaseHeldClientRequest();
+
+    await expect.poll(() => hostGivesAgentsPaseoTools(host), { timeout: 30_000 }).toBe(true);
+    await expect(page.getByRole("heading", { name: "Let agents use Paseo" })).toHaveCount(0);
+  } finally {
+    await host.close();
+  }
+});
diff --git a/packages/app/e2e/browser/plugin-buttons.spec.ts b/packages/app/e2e/browser/plugin-buttons.spec.ts
index fe4227a8c3..0c60fd3990 100644
--- a/packages/app/e2e/browser/plugin-buttons.spec.ts
+++ b/packages/app/e2e/browser/plugin-buttons.spec.ts
@@ -10,6 +10,7 @@ test("plugin header and composer buttons share actions, menus, content, and upda
     await buttons.verifyObservationLifetime();
     await buttons.openWideMenusAndPopovers();
     await buttons.runAndUpdateActions();
+    await buttons.keepTrackSpaceWithoutPills();
     await buttons.openCompactSheets();
     await buttons.useCompactWorkspaceMenu();
     await buttons.hideAndUnloadOpenButtons();
diff --git a/packages/app/e2e/browser/plugin-composer-items.spec.ts b/packages/app/e2e/browser/plugin-composer-items.spec.ts
new file mode 100644
index 0000000000..2c669105ae
--- /dev/null
+++ b/packages/app/e2e/browser/plugin-composer-items.spec.ts
@@ -0,0 +1,81 @@
+import { test } from "../support/fixtures";
+import {
+  expectToolbarNeverCondensedOrClipped,
+  recordToolbarFramesFromLoad,
+  withComposerControlsExample,
+  withPickerComposerItem,
+  withToggleAndWatcherComposerItems,
+} from "../support/helpers/plugin-composer-items";
+
+test("a narrow composer's overflow sheet shows a plugin item's row", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withComposerControlsExample(page, async (composer) => {
+    await composer.narrowTheWindow();
+    await composer.openAgentFeatures();
+    await composer.expectFeatureRow("Needs review");
+    await composer.expectFeatureRow("Insert checklist");
+  });
+});
+
+test("a toolbar with room keeps a plugin toggle inline at full density", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withToggleAndWatcherComposerItems(page, async (composer) => {
+    // Wider than what renders, too narrow for two 125-wide "Plugin item" estimates.
+    await composer.setWindowWidth(1000);
+    await composer.expectToolbarWidthBetween(470, 620);
+    await composer.expectToggleInlineAtFullDensity();
+  });
+});
+
+test("a toolbar without room moves a plugin toggle to the overflow sheet and back", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withToggleAndWatcherComposerItems(page, async (composer) => {
+    await composer.setWindowWidth(1000);
+    await composer.expectToggleInlineAtFullDensity();
+    // Too narrow for full labels, wide enough that the controls have not folded away.
+    await composer.setWindowWidth(880);
+    await composer.expectToolbarWidthBetween(300, 395);
+    await composer.expectToggleInOverflow();
+    await composer.closeOverflowSheet();
+    await composer.setWindowWidth(1000);
+    await composer.expectToggleInlineAtFullDensity();
+  });
+});
+
+test("an open plugin picker closes when its trigger moves to the overflow", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPickerComposerItem(page, async (composer) => {
+    await composer.setWindowWidth(1000);
+    await composer.openInlinePicker();
+    await composer.setWindowWidth(880);
+    await composer.expectToolbarWidthBetween(300, 395);
+    await composer.expectPickerClosed();
+  });
+});
+
+test("the toolbar settles on one density without flipping as the window widens", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withToggleAndWatcherComposerItems(page, async (composer) => {
+    await composer.setWindowWidth(880);
+    await composer.expectToolbarWidthBetween(300, 395);
+    await composer.startRecordingDensity();
+    for (let width = 880; width <= 1000; width += 8) await composer.setWindowWidth(width);
+    await composer.expectAtMostOneDensityChange();
+  });
+});
+
+test("a toolbar with room never paints condensed or clipped while the plugin loads", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await page.setViewportSize({ width: 1000, height: 800 });
+  await recordToolbarFramesFromLoad(page);
+  await withToggleAndWatcherComposerItems(page, async (composer) => {
+    await composer.expectToggleInlineAtFullDensity();
+    await expectToolbarNeverCondensedOrClipped(page);
+  });
+});
diff --git a/packages/app/e2e/browser/plugin-composers-by-reference.spec.ts b/packages/app/e2e/browser/plugin-composers-by-reference.spec.ts
new file mode 100644
index 0000000000..1d8ddf5b7f
--- /dev/null
+++ b/packages/app/e2e/browser/plugin-composers-by-reference.spec.ts
@@ -0,0 +1,223 @@
+import { test } from "../support/fixtures";
+import {
+  CHECKLIST,
+  withComposerToolsExample,
+  withPluginFocusingAComposer,
+  withPluginFocusingASubagent,
+  withPluginFocusingAnAgentWithContextUsage,
+  withPluginHoldingNewWorkspaceComposer,
+  withPluginWritingToAnotherWorkspace,
+} from "../support/helpers/plugin-composers-by-reference";
+
+test("a panel in the Explorer inserts at the cursor of the focused agent's composer", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withComposerToolsExample(page, async (author) => {
+    await author.openComposerToolsInExplorer();
+    await author.typeInComposer("start end", 5);
+    await author.insertChecklistFromPanel();
+    await author.expectComposerText(`start${CHECKLIST} end`);
+  });
+});
+
+test("a Command Center item changes an agent's metadata through its composer", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withComposerToolsExample(page, async (author) => {
+    await author.openComposerToolsInExplorer();
+    await author.expectPanelShowsReview(false);
+    await author.markForReviewFromCommandCenter();
+    await author.expectPanelShowsReview(true);
+  });
+});
+
+test("the panel follows which agent is focused", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withComposerToolsExample(page, async (author) => {
+    await author.openComposerToolsInExplorer();
+    await author.expectPanelFocusedAgent(true);
+    await author.focusANewAgentTab();
+    await author.expectPanelFocusedAgent(false);
+    await author.focusTheAgentTab();
+    await author.expectPanelFocusedAgent(true);
+  });
+});
+
+test("an Action in the compact controls sheet closes the sheet and focuses the composer", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withComposerToolsExample(page, async (author) => {
+    await author.useCompactLayout();
+    await author.insertChecklistFromControlsSheet();
+    await author.expectComposerReadyToType(CHECKLIST);
+  });
+});
+
+test("a plugin writes to an agent's composer while its workspace is not on screen", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withPluginWritingToAnotherWorkspace(page, async (author) => {
+    await author.openTargetAgent();
+    await author.goToAnotherWorkspace();
+    await author.insertFromCommandCenter();
+    await author.returnToTargetWorkspace();
+    await author.expectComposerText("A note from a plugin");
+  });
+});
+
+test("a pill that inserts text and focuses leaves the cursor in the composer, ready to type", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingAComposer(page, async (author) => {
+    await author.openTargetAgent();
+    await author.moveFocusOutOfComposer();
+    await author.pressPill();
+    await author.expectComposerFocused();
+    await author.typeAtCursor(" world");
+    await author.expectComposerText("HELLO world");
+  });
+});
+
+test("focus reaches an agent in another tab of the workspace", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingAComposer(page, async (author) => {
+    await author.openTargetAgent();
+    await author.openOtherAgent();
+    await author.focusFromCommandCenter();
+    await author.expectOnTargetAgent();
+    await author.expectComposerFocused();
+  });
+});
+
+test("focus reaches an agent in another workspace, with the selection asked for", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingAComposer(page, async (author) => {
+    await author.openTargetAgent();
+    await author.fillComposer("typed before");
+    await author.goToAnotherWorkspace();
+    await author.selectPromptFromCommandCenter();
+    await author.expectOnTargetAgent();
+    await author.expectComposerFocused();
+    await author.typeAtCursor("replaced");
+    await author.expectComposerText("replaced");
+  });
+});
+
+test("focus closes the compact Explorer panel covering the composer", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingAComposer(page, async (author) => {
+    await author.useCompactLayout();
+    await author.openTargetAgent();
+    await author.coverComposerWithExplorerPanel();
+    await author.pressPanelFocusButton();
+    await author.expectExplorerPanelClosed();
+    await author.expectComposerFocused();
+  });
+});
+
+test("focus rejects on a New workspace composer the user has left", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginHoldingNewWorkspaceComposer(page, async (author) => {
+    await author.openNewWorkspace();
+    await author.expectHeldComposerFocusResult("focused");
+    await author.openSettings();
+    await author.expectHeldComposerFocusResult("The composer is not on screen.");
+  });
+});
+
+test("focus closes a picker the composer opened over itself", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginHoldingNewWorkspaceComposer(page, async (author) => {
+    await author.openNewWorkspace();
+    await author.openThinkingPicker();
+    await author.expectHeldComposerFocusResult("focused");
+    await author.expectHeldComposerReadyToType();
+  });
+});
+
+test("focus closes an image preview the composer opened over itself", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginHoldingNewWorkspaceComposer(page, async (author) => {
+    await author.openNewWorkspace();
+    await author.previewAttachedImage();
+    await author.expectHeldComposerFocusResult("focused");
+    await author.expectHeldComposerReadyToType();
+  });
+});
+
+test("overlapping focus calls end at the later selection while a preview closes", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await withPluginHoldingNewWorkspaceComposer(page, async (author) => {
+    await author.openNewWorkspace();
+    await author.typeInHeldComposer("HELLO");
+    await author.previewAttachedImage();
+    await author.expectOverlappingFocusesKeepTheLatestSelection();
+  });
+});
+
+test("focus closes the context usage sheet on a phone", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingAnAgentWithContextUsage(page, async (author) => {
+    await author.openContextUsageOnPhone();
+    await author.focusAgent();
+    await author.expectReadyToType();
+  });
+});
+
+test("focus closes a page the composer's Subagents track opened over it", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingASubagent(page, async (author) => {
+    await author.openParentAgent();
+    await author.openSubagentPageInParentComposer();
+    await author.focusParent();
+    await author.expectParentReadyToType();
+  });
+});
+
+test("focus reaches a New workspace composer opened from a compact Explorer", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginHoldingNewWorkspaceComposer(page, async (author) => {
+    await author.leaveCompactExplorerForNewWorkspace();
+    await author.expectHeldComposerFocusResult("focused");
+  });
+});
+
+test("focus opens a compact subagent as a tab with its composer", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingASubagent(page, async (author) => {
+    await author.openParentAgent();
+    await author.openExplorer();
+    await author.focusSubagent();
+    await author.expectSubagentTabReadyToType();
+  });
+});
+
+test("focus closes a file sheet still opening over an Explorer composer", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingASubagent(page, async (author) => {
+    await author.keepParentInExplorerOnCompactScreen();
+    await author.focusParent();
+    await author.expectParentReadyToType();
+    await author.focusParentAsAFileSheetOpens();
+    await author.expectParentReadyToType();
+  });
+});
+
+test("focus reaches an agent kept in the Explorer on a compact screen", async ({ page }) => {
+  test.setTimeout(120_000);
+  await withPluginFocusingASubagent(page, async (author) => {
+    await author.keepParentInExplorerOnCompactScreen();
+    await author.focusParent();
+    await author.expectParentReadyToType();
+    await author.coverExplorerComposerWithFileSheet();
+    await author.focusParent();
+    await author.expectParentReadyToType();
+  });
+});
diff --git a/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts b/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts
new file mode 100644
index 0000000000..485375b352
--- /dev/null
+++ b/packages/app/e2e/browser/plugin-new-workspace-items.spec.ts
@@ -0,0 +1,110 @@
+import { expect, test } from "../support/fixtures";
+import { withNewWorkspaceIssuesExample } from "../support/helpers/plugin-new-workspace-items";
+
+for (const layout of [
+  { name: "desktop", compact: false },
+  { name: "compact", compact: true },
+]) {
+  test(`a plugin's New workspace item sets the branch and metadata on ${layout.name}`, async ({
+    page,
+  }) => {
+    test.setTimeout(180_000);
+    await withNewWorkspaceIssuesExample(page, { compact: layout.compact }, async (screen) => {
+      await screen.chooseWorktree();
+      await screen.chooseIssue("PAS-102 Crash on resume");
+      const created = await screen.createWorkspace();
+      expect(created.branch).toBe("pas-102-crash-on-resume");
+      expect(created.metadata).toEqual({ "new-workspace-issues.issue": "PAS-102" });
+    });
+  });
+}
+
+test("a branch chosen while Local applies once the user switches to a new worktree", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(page, { compact: false }, async (screen) => {
+    await screen.chooseIssue("PAS-101 Slow sidebar");
+    await screen.chooseWorktree();
+    const created = await screen.createWorkspace({ prompt: "" });
+    expect(created.branch).toBe("pas-101-slow-sidebar");
+    expect(created.metadata).toEqual({ "new-workspace-issues.issue": "PAS-101" });
+  });
+});
+
+test("a plugin's branch applies when the project has no default base to branch off", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(
+    page,
+    { compact: false, detachedHead: true },
+    async (screen) => {
+      await screen.chooseWorktree();
+      await screen.chooseIssue("PAS-101 Slow sidebar");
+      const created = await screen.createWorkspace();
+      expect(created.branch).toBe("pas-101-slow-sidebar");
+    },
+  );
+});
+
+test("a branch and metadata chosen for one project are not sent for another", async ({ page }) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(
+    page,
+    { compact: false, otherProject: true },
+    async (screen) => {
+      await screen.chooseWorktree();
+      await screen.chooseIssue("PAS-101 Slow sidebar");
+      await screen.switchToOtherProject();
+      const created = await screen.createWorkspace();
+      expect(created.branch).not.toBe("pas-101-slow-sidebar");
+      expect(created.metadata ?? {}).toEqual({});
+    },
+  );
+});
+
+test("an item's Issue list does not keep the previous project's results after a project switch", async ({
+  page,
+}) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(
+    page,
+    { compact: false, otherProject: true, searchesByProject: true },
+    async (screen) => {
+      await screen.openIssueList();
+      await screen.expectIssueListText(`Issue of ${screen.firstProjectName}`, true);
+      await screen.closeIssueList();
+      await screen.switchToOtherProject();
+      await screen.openIssueList();
+      await screen.expectIssueListText(`Issue of ${screen.firstProjectName}`, false);
+    },
+  );
+});
+
+test("an isolation set from a mount effect is remembered like a pick", async ({ page }) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(
+    page,
+    { compact: false, setsOnMount: true },
+    async (screen) => {
+      await screen.expectIsolation("worktree");
+      await screen.reopenWithoutPlugin();
+      await screen.expectIsolation("worktree");
+    },
+  );
+});
+
+test("an item can set the branch and metadata from its mount effect", async ({ page }) => {
+  test.setTimeout(180_000);
+  await withNewWorkspaceIssuesExample(
+    page,
+    { compact: false, setsOnMount: true },
+    async (screen) => {
+      await screen.expectIsolation("worktree");
+      const created = await screen.createWorkspace();
+      expect(created.branch).toBe("set-on-mount");
+      expect(created.metadata).toEqual({ "new-workspace-issues.issue": "ON-MOUNT" });
+    },
+  );
+});
diff --git a/packages/app/e2e/browser/plugin-settings.spec.ts b/packages/app/e2e/browser/plugin-settings.spec.ts
index 6235cd647f..4a15063cd0 100644
--- a/packages/app/e2e/browser/plugin-settings.spec.ts
+++ b/packages/app/e2e/browser/plugin-settings.spec.ts
@@ -16,6 +16,14 @@ import {
   returnAndReopenSettings,
   returnToPluginsPage,
   expectSettingsUnavailable,
+  openPluginsPage,
+  expectActionsMenuWithoutSettings,
+  expectNoSettingsCogWithoutScreens,
+  openTabbedSettings,
+  selectSettingsTab,
+  openTabbedSettingsLink,
+  expectSettingsTooltip,
+  expectNamedPluginRow,
 } from "../support/helpers/plugin-settings";
 
 test("display preferences survive a reload", async ({ page }) => {
@@ -49,6 +57,32 @@ test("Back to plugins returns from a plugin settings screen", async ({ page }) =
   await returnToPluginsPage(page);
 });
 
+test("plugin settings open from the cog and show a tab per screen", async ({ page }) => {
+  await openPluginsPage(page);
+  await test.step("plugin rows show the display name", async () => {
+    await expectNamedPluginRow(page);
+  });
+  await test.step("the cog explains itself", async () => {
+    await expectSettingsTooltip(page);
+  });
+  await test.step("the actions menu keeps only plugin actions", async () => {
+    await expectActionsMenuWithoutSettings(page);
+  });
+  await test.step("tabs switch between the plugin's settings screens", async () => {
+    await openTabbedSettings(page);
+    await selectSettingsTab(page, "Advanced");
+    await selectSettingsTab(page, "General");
+    await returnToPluginsPage(page);
+  });
+  await test.step("a plugin without settings screens shows no cog", async () => {
+    await expectNoSettingsCogWithoutScreens(page);
+  });
+});
+
+test("a settings screen link opens its tab", async ({ page }) => {
+  await openTabbedSettingsLink(page, "Advanced");
+});
+
 test.describe("compact plugin settings", () => {
   test.use({ viewport: { width: 390, height: 844 } });
 
diff --git a/packages/app/e2e/browser/plugin-sidebar-items.spec.ts b/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
index 900fb42db9..e91b6a55da 100644
--- a/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
+++ b/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
@@ -2,6 +2,7 @@ import path from "node:path";
 import type { Locator, Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
 import { gotoWorkspace } from "../support/helpers/launcher";
+import { gotoAppShell } from "../support/helpers/app";
 import {
   BOTS_PLUGIN_ID,
   COMPACT,
@@ -27,6 +28,7 @@ import { seedWorkspace } from "../support/helpers/seed-client";
 import { getServerId } from "../support/helpers/server-id";
 import { installUsageReportsFixture } from "../support/helpers/usage-reports";
 import { claudeAndCodexReports } from "../support/helpers/usage-sidebar-item";
+import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 
 const APP_SETTINGS_KEY = "@paseo:app-settings";
 
@@ -133,6 +135,30 @@ function sidebarFooter(page: Page): Locator {
   return visibleTestId(page, "sidebar-add-project").locator("xpath=..");
 }
 
+function isPluginCatalogResponse(message: string | Buffer): boolean {
+  if (typeof message !== "string") return false;
+  const frame = JSON.parse(message);
+  return frame.type === "session" && frame.message?.type === "plugin.catalog.get.response";
+}
+
+async function holdNextPluginCatalogResponse(page: Page) {
+  const response = Promise.withResolvers<() => void>();
+  let holdCatalog = true;
+  await page.routeWebSocket(daemonWsRoutePattern(), (socket) => {
+    const server = socket.connectToServer();
+    socket.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      if (holdCatalog && isPluginCatalogResponse(message)) {
+        holdCatalog = false;
+        response.resolve(() => socket.send(message));
+        return;
+      }
+      socket.send(message);
+    });
+  });
+  return { response: response.promise };
+}
+
 test.describe("Plugin sidebar items", () => {
   let workspaceId: string;
   let cleanup: () => Promise<void>;
@@ -151,6 +177,69 @@ test.describe("Plugin sidebar items", () => {
     await cleanup();
   });
 
+  test("a short compact sidebar keeps workspaces usable while navigation scrolls", async ({
+    page,
+  }) => {
+    await page.setViewportSize({ width: 390, height: 600 });
+    await gotoAppShell(page);
+    await page.getByRole("button", { name: "Open menu", exact: true }).first().click();
+    await expect(botRow(page, "status")).toBeAttached();
+    const workspace = visibleTestId(page, `sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+    await expect(workspace).toBeInViewport({ ratio: 1 });
+
+    await test.step("scrolling navigation reaches its last row without moving workspaces", async () => {
+      const before = await boxOf(workspace);
+      await visibleTestId(page, "sidebar-global-new-workspace").hover();
+      await page.mouse.wheel(0, 800);
+      await expect(botRow(page, "status")).toBeInViewport({ ratio: 1 });
+      await expect(workspace).toBeInViewport({ ratio: 1 });
+      expect((await boxOf(workspace)).y).toBe(before.y);
+      await botRow(page, "status").click();
+      await expect(page.getByText("Bot status details", { exact: true })).toBeVisible();
+      await page.getByRole("button", { name: "Close bot status", exact: true }).click();
+    });
+
+    await test.step("the workspace still opens and closes the sidebar", async () => {
+      await workspace.click();
+      await expect(
+        page.getByRole("button", { name: "Open menu", exact: true }).first(),
+      ).toBeVisible();
+      await expect(workspace).not.toBeInViewport();
+    });
+  });
+
+  test("a restored plugin screen waits for its catalog before rendering", async ({ page }) => {
+    await page.setViewportSize(WIDE);
+    await gotoWorkspace(page, workspaceId);
+    const row = headerRow(page, SHOWCASE_PLUGIN_ID, "deploys");
+    await expect(row).toBeVisible({ timeout: 30_000 });
+    await row.click();
+    const body = page.getByText("Deploys screen body", { exact: true });
+    await expect(body).toBeVisible();
+    const screenUrl = page.url();
+    const catalog = await holdNextPluginCatalogResponse(page);
+
+    await page.reload();
+    const releaseCatalog = await catalog.response;
+    try {
+      await expect(
+        page.getByRole("progressbar", { name: "Loading plugin", exact: true }),
+      ).toBeVisible();
+      await expect(
+        page.getByText("This plugin surface is unavailable.", { exact: true }),
+      ).toHaveCount(0);
+      await expect(body).toHaveCount(0);
+    } finally {
+      releaseCatalog();
+    }
+
+    await expect(body).toBeVisible();
+    await expect(
+      page.getByRole("progressbar", { name: "Loading plugin", exact: true }),
+    ).toHaveCount(0);
+    await expect(page).toHaveURL(screenUrl);
+  });
+
   test("a plugin's screen, header row, footer popover and command work together", async ({
     page,
   }) => {
@@ -228,7 +317,10 @@ test.describe("Plugin sidebar items", () => {
       const compactSync = footerItem(page, SHOWCASE_PLUGIN_ID, "sync");
       await expect(compactSync).toBeInViewport();
       await expectFooterRow(page, compactSync);
-      await expect(headerRow(page, SHOWCASE_PLUGIN_ID, "deploys")).toBeInViewport();
+      // The compact nav block is capped at half the sidebar and scrolls past it.
+      const compactDeploys = headerRow(page, SHOWCASE_PLUGIN_ID, "deploys");
+      await compactDeploys.scrollIntoViewIfNeeded();
+      await expect(compactDeploys).toBeInViewport();
       await qaScreenshot(page, "phase2-compact-sidebar");
       await qaScreenshot(page, "phase5-compact-footer", sidebarFooter(page));
       await compactSync.click();
diff --git a/packages/app/e2e/browser/plugin-subscription-examples.spec.ts b/packages/app/e2e/browser/plugin-subscription-examples.spec.ts
new file mode 100644
index 0000000000..8cb25576bc
--- /dev/null
+++ b/packages/app/e2e/browser/plugin-subscription-examples.spec.ts
@@ -0,0 +1,79 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test, type Page } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { openCommandCenter } from "../support/helpers/command-center";
+import { connectNewWorkspaceDaemonClient } from "../support/helpers/new-workspace";
+import { copyPluginExample } from "../support/helpers/plugin-fixture";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { getServerId } from "../support/helpers/server-id";
+import {
+  switchWorkspaceViaSidebar,
+  waitForWorkspaceInSidebar,
+} from "../support/helpers/workspace-ui";
+
+async function runCommand(page: Page, title: string): Promise<void> {
+  const panel = await openCommandCenter(page);
+  await panel.getByTestId("command-center-input").fill(title);
+  await panel.getByRole("button", { name: title, exact: true }).click();
+  await expect(panel).not.toBeVisible();
+}
+
+/** Installs a plugin example, opens a seeded workspace, and runs `exercise` against them. */
+async function withExample(
+  page: Page,
+  example: { name: string; id: string },
+  exercise: (workspace: SeededWorkspace) => Promise<void>,
+): Promise<void> {
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const copy = await copyPluginExample(example.name);
+  const workspace = await seedWorkspace({ repoPrefix: `${example.name}-` });
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(copy.directory);
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await gotoAppShell(page);
+    const target = { serverId: getServerId(), workspaceId: workspace.workspaceId };
+    await waitForWorkspaceInSidebar(page, target);
+    await switchWorkspaceViaSidebar({ page, ...target });
+    await exercise(workspace);
+  } finally {
+    try {
+      await client.removePlugin(example.id);
+    } finally {
+      await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+      await workspace.cleanup();
+      await client.close();
+      await copy.cleanup();
+    }
+  }
+}
+
+test.describe("plugin subscriptions", () => {
+  test.describe.configure({ timeout: 180_000 });
+
+  test("a panel follows events the daemon pushes as files change", async ({ page }) => {
+    await withExample(page, { name: "diff-watch", id: "diff-watch" }, async (workspace) => {
+      await runCommand(page, "Open live changes");
+      await expect(page.getByText("No changes", { exact: true })).toBeVisible();
+
+      await writeFile(path.join(workspace.repoPath, "pushed.txt"), "from the test\n");
+      await expect(page.getByText("1 file changed", { exact: true })).toBeVisible();
+      await expect(page.getByText("pushed.txt", { exact: true })).toBeVisible();
+    });
+  });
+
+  test("a panel plays streamed bytes and sends bytes back", async ({ page }) => {
+    await withExample(page, { name: "media-stream", id: "media-stream" }, async () => {
+      await runCommand(page, "Open media stream");
+      await expect(page.getByText("live", { exact: true })).toBeVisible();
+      await expect(page.getByText(/^[1-9]\d* video frames/)).toBeVisible();
+
+      await page.getByRole("button", { name: "Send this frame back", exact: true }).click();
+      await expect(
+        page.getByText(/^The daemon received [1-9]\d* bytes, sha256 [0-9a-f]{12}$/),
+      ).toBeVisible();
+    });
+  });
+});
diff --git a/packages/app/e2e/browser/plugin-theme.spec.ts b/packages/app/e2e/browser/plugin-theme.spec.ts
index a5ef533326..5fbad282dd 100644
--- a/packages/app/e2e/browser/plugin-theme.spec.ts
+++ b/packages/app/e2e/browser/plugin-theme.spec.ts
@@ -2,7 +2,6 @@ import { pluginRequirements } from "../support/helpers/plugin-fixture";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import type { Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
 import { connectNewWorkspaceDaemonClient } from "../support/helpers/new-workspace";
 import { openSettingsSection } from "../support/helpers/settings";
@@ -69,8 +68,7 @@ test("applies a contributed theme and falls back when its plugin is gone", async
     await openSettingsSection(page, "appearance");
 
     const sectionTitle = page.getByText("Theme", { exact: true }).first();
-    await page.getByLabel("Theme: System", { exact: true }).click();
-    const mochaItem = page.getByText("Catppuccin Mocha", { exact: true });
+    const mochaItem = page.getByRole("radio", { name: "Catppuccin Mocha", exact: true });
     await expect(mochaItem).toBeVisible({ timeout: 30_000 });
     await page.screenshot({
       path: testInfo.outputPath("plugin-theme-picker.png"),
@@ -79,14 +77,14 @@ test("applies a contributed theme and falls back when its plugin is gone", async
     });
 
     await test.step("a contributed light theme uses the light palette", async () => {
-      await page.getByText("Catppuccin Latte", { exact: true }).click();
-      await expect(page.getByLabel("Theme: Catppuccin Latte", { exact: true })).toBeVisible();
+      const latteItem = page.getByRole("radio", { name: "Catppuccin Latte", exact: true });
+      await latteItem.click();
+      await expect(latteItem).toBeChecked();
       await expect(sectionTitle).toHaveCSS("color", LATTE_MUTED_FOREGROUND);
-      await page.getByLabel("Theme: Catppuccin Latte", { exact: true }).click();
     });
 
     await mochaItem.click();
-    await expect(page.getByLabel("Theme: Catppuccin Mocha", { exact: true })).toBeVisible();
+    await expect(mochaItem).toBeChecked();
     await expect(sectionTitle).toHaveCSS("color", MOCHA_MUTED_FOREGROUND);
     await page.screenshot({
       path: testInfo.outputPath("plugin-theme-applied.png"),
@@ -95,15 +93,13 @@ test("applies a contributed theme and falls back when its plugin is gone", async
 
     await test.step("the selection survives a reload", async () => {
       await page.reload();
-      await expect(page.getByLabel("Theme: Catppuccin Mocha", { exact: true })).toBeVisible({
-        timeout: 30_000,
-      });
+      await expect(mochaItem).toBeChecked({ timeout: 30_000 });
       await expect(sectionTitle).toHaveCSS("color", MOCHA_MUTED_FOREGROUND);
     });
 
     await test.step("removing the plugin falls back to the default theme", async () => {
       await client.removePlugin(PLUGIN_ID);
-      await expect(page.getByLabel("Theme: System", { exact: true })).toBeVisible({
+      await expect(page.getByRole("radio", { name: "System", exact: true })).toBeChecked({
         timeout: 30_000,
       });
       await expect(sectionTitle).not.toHaveCSS("color", MOCHA_MUTED_FOREGROUND);
@@ -147,15 +143,7 @@ const MANY_THEMES_SOURCE = `export default function contribute(plugin) {
   return () => {};
 }`;
 
-async function scrollThemeMenuToLastTheme(page: Page) {
-  const firstTheme = page.getByText("Pack theme 1", { exact: true });
-  await expect(firstTheme).toBeVisible({ timeout: 30_000 });
-  await firstTheme.hover();
-  await page.mouse.wheel(0, 4000);
-  await expect(page.getByText(LAST_THEME_NAME, { exact: true })).toBeInViewport({ ratio: 1 });
-}
-
-test("scrolls to the last theme when a plugin contributes more themes than fit", async ({
+test("reaches the last theme when a plugin contributes more themes than fit", async ({
   page,
 }, testInfo) => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-theme-many-e2e-"));
@@ -175,15 +163,16 @@ test("scrolls to the last theme when a plugin contributes more themes than fit",
     await expect(page.getByTestId("settings-sidebar")).toBeVisible();
     await openSettingsSection(page, "appearance");
 
-    await page.getByLabel("Theme: System", { exact: true }).click();
-    await scrollThemeMenuToLastTheme(page);
+    const lastTheme = page.getByRole("radio", { name: LAST_THEME_NAME, exact: true });
+    await expect(lastTheme).toBeAttached({ timeout: 30_000 });
+    await lastTheme.scrollIntoViewIfNeeded();
     await page.screenshot({
       path: testInfo.outputPath("plugin-theme-picker-scrolled.png"),
       animations: "disabled",
     });
 
-    await page.getByText(LAST_THEME_NAME, { exact: true }).click();
-    await expect(page.getByLabel(`Theme: ${LAST_THEME_NAME}`, { exact: true })).toBeVisible();
+    await lastTheme.click();
+    await expect(lastTheme).toBeChecked();
   } finally {
     await client.removePlugin(MANY_THEMES_PLUGIN_ID).catch(() => undefined);
     await client
diff --git a/packages/app/e2e/browser/plugin-timeline.spec.ts b/packages/app/e2e/browser/plugin-timeline.spec.ts
index d75653298e..aacd7c187b 100644
--- a/packages/app/e2e/browser/plugin-timeline.spec.ts
+++ b/packages/app/e2e/browser/plugin-timeline.spec.ts
@@ -24,11 +24,12 @@ for (const width of [1100, 390]) {
       await expectWholeCompletedCard(page);
       // Local state is checked during growth; the viewport remounts on the history handoff.
       const recovery = trackPluginChatRecovery(page);
-      gate.holdTimelineResponses(agent.agentId);
+      // A chat with a cached cursor answers current and never fetches, so hold the subscribe itself.
+      gate.holdNextClientRequest("agent.timeline.set_subscription.request");
       await page.reload({ waitUntil: "domcontentloaded" });
-      await gate.waitForHeldTimelineResponse();
+      await gate.waitForHeldClientRequest();
       await recovery.expectCatalogWithoutRetransmission();
-      gate.releaseHeldTimelineResponses();
+      gate.releaseHeldClientRequest();
       await expectWholeCompletedCard(page);
       await recovery.expectRecoveredWithoutRetransmission();
       recovery.reset();
diff --git a/packages/app/e2e/browser/provider-task-list.real.spec.ts b/packages/app/e2e/browser/provider-task-list.real.spec.ts
index b388b7d2c7..9636f7c799 100644
--- a/packages/app/e2e/browser/provider-task-list.real.spec.ts
+++ b/packages/app/e2e/browser/provider-task-list.real.spec.ts
@@ -1,7 +1,8 @@
-import { mkdtempSync, realpathSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { expect, test } from "../support/fixtures";
+import type { Locator } from "@playwright/test";
+import { expect, test, type Page } from "../support/fixtures";
 import {
   cleanupRewindFlow,
   launchAgent,
@@ -14,7 +15,11 @@ import {
   expectTaskListEntries,
   openCompletedTaskList,
 } from "../support/helpers/task-list";
-import { submitMessage } from "../support/helpers/composer";
+import { submitMessage, submitMessageWithButton } from "../support/helpers/composer";
+import { waitForSettledPosition } from "../support/helpers/sheet-layout";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { getServerId } from "../support/helpers/server-id";
+import { gotoAppShell } from "../support/helpers/app";
 
 interface TaskScenario {
   provider: RewindFlowProvider;
@@ -114,3 +119,425 @@ test.describe("real provider composer task lists", () => {
     }
   });
 });
+
+async function openBackgroundInventory(
+  page: Page,
+  options: { compact: boolean; count: number; timeout: number },
+): Promise<Locator> {
+  const pill = page.getByRole("button", {
+    name: options.count === 1 ? "1 background task" : `${options.count} background tasks`,
+  });
+  await expect(pill).toBeVisible({ timeout: options.timeout });
+  await pill.click();
+  const panel = page.getByTestId(
+    options.compact ? "background-work-panel-content" : "background-work-panel",
+  );
+  if (options.compact) await waitForSettledPosition(panel);
+  return panel;
+}
+
+async function openBackgroundWork(page: Page, compact: boolean): Promise<void> {
+  const panel = await openBackgroundInventory(page, { compact, count: 1, timeout: 30_000 });
+  await expect(panel).toContainText(/sleep 120/);
+}
+
+async function expectBackgroundItems(
+  panel: Locator,
+  selected: string,
+  sibling: string,
+): Promise<void> {
+  await expect(panel).toContainText(selected);
+  await expect(panel).toContainText(sibling);
+}
+
+async function stopBackgroundItem(panel: Locator, selected: string): Promise<void> {
+  const escaped = selected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  await panel.getByRole("button", { name: new RegExp(`Stop .*${escaped}`) }).click();
+}
+
+async function expectStoppedItemAndSibling(
+  panel: Locator,
+  selected: string,
+  sibling: string,
+): Promise<void> {
+  await expect(panel).not.toContainText(selected, { timeout: 40_000 });
+  await expect(panel).toContainText(sibling);
+}
+
+async function closeBackgroundWork(page: Page, compact: boolean): Promise<void> {
+  const panel = page.getByTestId(
+    compact ? "background-work-panel-content" : "background-work-panel",
+  );
+  if (compact) {
+    await page
+      .getByRole("button", { name: "Bottom sheet backdrop" })
+      .click({ position: { x: 12, y: 12 } });
+  } else {
+    await page.keyboard.press("Escape");
+  }
+  await expect(panel).toBeHidden();
+}
+
+async function expectBackgroundAgentRunning(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-status-indicator-running").first()).toBeVisible();
+  await expect(page.getByRole("button", { name: "Stop agent", exact: true })).toHaveCount(0);
+}
+
+async function expectAssistantReply(page: Page, text: string): Promise<void> {
+  await expect(page.getByTestId("assistant-message").filter({ hasText: text }).last()).toBeVisible({
+    timeout: 120_000,
+  });
+}
+
+async function expectBackgroundPill(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "1 background task" })).toBeVisible();
+}
+
+async function expectBackgroundWorkOnAnotherClient(page: Page): Promise<void> {
+  const another = await page.context().newPage();
+  try {
+    await another.goto(page.url());
+    await openBackgroundWork(another, false);
+  } finally {
+    await another.close();
+  }
+}
+
+async function startBackgroundWorkWithoutOpeningPane(workspace: SeededWorkspace): Promise<void> {
+  const agent = await workspace.client.createAgent({
+    provider: "claude",
+    model: "haiku",
+    modeId: "bypassPermissions",
+    cwd: workspace.workspaceDirectory,
+    workspaceId: workspace.workspaceId,
+    title: "Background work before opening",
+  });
+  await workspace.client.sendAgentMessage(
+    agent.id,
+    "Use Bash with run_in_background to run exactly sleep 120. Do not wait for it. Reply SPAWNED immediately.",
+  );
+  const result = await workspace.client.waitForFinish(agent.id, 120_000);
+  expect(result.status).toBe("idle");
+}
+
+async function expectWorkspaceRunning(page: Page, workspaceId: string): Promise<void> {
+  const row = page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+  await expect(row.getByTestId("workspace-status-indicator-running")).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+test("Claude keeps background work visible while accepting another turn", async ({ page }) => {
+  test.setTimeout(300_000);
+  const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-background-work-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({ page, provider: "claude", cwd, mode: "full-access" });
+    await sendMessage(
+      handle,
+      "Use Bash with run_in_background to run exactly sleep 120. Do not wait for it. Reply SPAWNED immediately.",
+    );
+    await expectBackgroundAgentRunning(page);
+    await openBackgroundWork(page, false);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/phase1-claude-background.png"),
+      animations: "disabled",
+    });
+    await closeBackgroundWork(page, false);
+    await sendMessage(handle, "Reply exactly HELLO without stopping the background command.");
+    await expectBackgroundPill(page);
+    await expectBackgroundWorkOnAnotherClient(page);
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+test("Claude background work remains readable in dark mode", async ({ page }) => {
+  test.setTimeout(300_000);
+  await page.addInitScript(() => {
+    localStorage.setItem("@paseo:app-settings", JSON.stringify({ theme: "pureBlack" }));
+  });
+  const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-background-dark-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({ page, provider: "claude", cwd, mode: "full-access" });
+    await sendMessage(
+      handle,
+      "Use Bash with run_in_background to run exactly sleep 120. Do not wait for it. Reply SPAWNED immediately.",
+    );
+    await openBackgroundWork(page, false);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/review-background-dark.png"),
+      animations: "disabled",
+    });
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+test("Claude background work opens in a compact sheet", async ({ page }) => {
+  test.setTimeout(300_000);
+  await page.setViewportSize({ width: 390, height: 844 });
+  const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-background-compact-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({ page, provider: "claude", cwd, mode: "full-access" });
+    await submitMessageWithButton(
+      page,
+      "Use Bash with run_in_background to run exactly sleep 120. Do not wait for it. Reply SPAWNED immediately.",
+    );
+    await expectAssistantReply(page, "SPAWNED");
+    await openBackgroundWork(page, true);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/phase1-claude-compact.png"),
+      animations: "disabled",
+    });
+    await closeBackgroundWork(page, true);
+    await submitMessageWithButton(
+      page,
+      "Reply exactly HELLO without stopping the background command.",
+    );
+    await expectAssistantReply(page, "HELLO");
+    await expectBackgroundPill(page);
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+test("background work updates the sidebar before the agent is opened", async ({ page }) => {
+  test.setTimeout(300_000);
+  const workspace = await seedWorkspace({ repoPrefix: "background-unopened-" });
+  try {
+    await gotoAppShell(page);
+    await expect(
+      page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspace.workspaceId}`),
+    ).toBeVisible();
+    await startBackgroundWorkWithoutOpeningPane(workspace);
+    await expectWorkspaceRunning(page, workspace.workspaceId);
+  } finally {
+    await workspace.cleanup();
+  }
+});
+
+test("Codex keeps a live command visible after its turn", async ({ page }) => {
+  test.setTimeout(300_000);
+  const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-codex-background-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({
+      page,
+      provider: "codex",
+      cwd,
+      mode: "full-access",
+      providerConfig: { model: "gpt-6-astra" },
+    });
+    await sendMessage(
+      handle,
+      "Use exec_command to run sleep 120 with yield_time_ms 1000. Do not wait for or stop it. Reply SPAWNED immediately.",
+    );
+    await expectBackgroundAgentRunning(page);
+    await openBackgroundWork(page, false);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/phase2-codex-background.png"),
+      animations: "disabled",
+    });
+    await closeBackgroundWork(page, false);
+    await sendMessage(handle, "Reply exactly HELLO without stopping the background command.");
+    await expectBackgroundPill(page);
+    await expectBackgroundWorkOnAnotherClient(page);
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+test("OpenCode keeps a live command visible after its turn", async ({ page }) => {
+  test.setTimeout(300_000);
+  const cwd = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-opencode-background-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({
+      page,
+      provider: "opencode",
+      cwd,
+      mode: "full-access",
+      providerConfig: { model: "openrouter/google/gemini-3.6-flash" },
+    });
+    await sendMessage(
+      handle,
+      "Use the shell tool with background true to run sleep 120. Do not wait or stop it. Reply SPAWNED immediately.",
+    );
+    await expectBackgroundAgentRunning(page);
+    await openBackgroundWork(page, false);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/phase2-opencode-background.png"),
+      animations: "disabled",
+    });
+    await closeBackgroundWork(page, false);
+    await sendMessage(handle, "Reply exactly HELLO without stopping the background command.");
+    await expectBackgroundPill(page);
+    await expectBackgroundWorkOnAnotherClient(page);
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+for (const scenario of [
+  {
+    provider: "claude" as const,
+    prompt:
+      "Use Bash with run_in_background to start sleep 180 and sleep 181 as two separate background commands. Do not wait for them. Reply SPAWNED immediately.",
+    providerConfig: { model: "haiku" },
+  },
+  {
+    provider: "codex" as const,
+    prompt:
+      "Use exec_command twice to start sleep 180 and sleep 181 separately with yield_time_ms 1000. Do not wait for or stop either process. Reply SPAWNED immediately.",
+    providerConfig: { model: "gpt-6-astra" },
+  },
+  {
+    provider: "opencode" as const,
+    prompt:
+      "Use the shell tool twice with background true: start sleep 180, then start sleep 181. Do not wait for or stop either. Reply SPAWNED immediately.",
+    providerConfig: { model: "openrouter/google/gemini-3.6-flash" },
+  },
+]) {
+  test(`${scenario.provider} stops selected background work after the turn`, async ({ page }) => {
+    test.setTimeout(300_000);
+    mkdirSync(path.resolve("../../.artifacts"), { recursive: true });
+    const cwd = realpathSync(mkdtempSync(path.resolve("../../.artifacts/phase3-qa-workspace-")));
+    let handle: AgentHandle | undefined;
+    try {
+      handle = await launchAgent({
+        page,
+        provider: scenario.provider,
+        cwd,
+        mode: "full-access",
+        providerConfig: scenario.providerConfig,
+      });
+      await sendMessage(handle, scenario.prompt);
+      const panel = await openBackgroundInventory(page, {
+        compact: false,
+        count: 2,
+        timeout: 60_000,
+      });
+      await expectBackgroundItems(panel, "sleep 180", "sleep 181");
+      await stopBackgroundItem(panel, "sleep 180");
+      await expectStoppedItemAndSibling(panel, "sleep 180", "sleep 181");
+      await page.screenshot({
+        path: path.resolve(`../../.artifacts/phase3-${scenario.provider}-stop.png`),
+        animations: "disabled",
+      });
+      await page.keyboard.press("Escape");
+      await sendMessage(handle, "Reply exactly HELLO without stopping the background command.");
+      await expectBackgroundPill(page);
+    } finally {
+      await cleanupRewindFlow({ handle, cwd });
+    }
+  });
+}
+
+test("Claude stops a selected monitor in the compact sheet", async ({ page }) => {
+  test.setTimeout(300_000);
+  await page.setViewportSize({ width: 390, height: 844 });
+  mkdirSync(path.resolve("../../.artifacts"), { recursive: true });
+  const cwd = realpathSync(mkdtempSync(path.resolve("../../.artifacts/phase3-monitor-workspace-")));
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({
+      page,
+      provider: "claude",
+      cwd,
+      mode: "full-access",
+      providerConfig: { model: "opus" },
+    });
+    await submitMessageWithButton(
+      page,
+      'Use exactly two separate Monitor tool calls, each with command `sleep 150`, timeout_ms 150000, persistent false, descriptions "probe monitor one" and "probe monitor two". Launch both independently, do not wait, then reply SPAWNED. Do not use any other tools.',
+    );
+    await expectAssistantReply(page, "SPAWNED");
+    const panel = await openBackgroundInventory(page, { compact: true, count: 2, timeout: 30_000 });
+    await expectBackgroundItems(panel, "probe monitor one", "probe monitor two");
+    await expect(panel.getByText("sleep 150", { exact: true })).toHaveCount(2);
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/refinement-monitor-compact.png"),
+      animations: "disabled",
+    });
+    await stopBackgroundItem(panel, "probe monitor one");
+    await expectStoppedItemAndSibling(panel, "probe monitor one", "probe monitor two");
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/phase3-claude-monitor-compact.png"),
+      animations: "disabled",
+    });
+    await closeBackgroundWork(page, true);
+    await submitMessageWithButton(
+      page,
+      "Reply exactly HELLO without stopping the background monitor.",
+    );
+    await expectAssistantReply(page, "HELLO");
+    await expectBackgroundPill(page);
+    await handle.client.sendAgentMessage(
+      handle.agentId,
+      "Use Bash to run sleep 20 in the foreground, then reply WAITED.",
+    );
+    await expect(page.getByRole("button", { name: "Stop agent", exact: true })).toBeVisible({
+      timeout: 30_000,
+    });
+    await handle.client.sendAgentMessage(
+      handle.agentId,
+      "Reply exactly INTERRUPTED without stopping the background monitor.",
+      { activeTurnBehavior: "interrupt" },
+    );
+    expect((await handle.client.waitForFinish(handle.agentId, 120_000)).status).toBe("idle");
+    await expectBackgroundPill(page);
+    await expect
+      .poll(async () => handle!.client.listAgentBackgroundWork(handle!.agentId))
+      .toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ description: "probe monitor two", kind: "monitor" }),
+        ]),
+      );
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
+
+test("Claude shows monitor description and command in the wide track", async ({ page }) => {
+  test.setTimeout(300_000);
+  const cwd = realpathSync(
+    mkdtempSync(path.resolve("../../.artifacts/refinement-wide-workspace-")),
+  );
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await launchAgent({
+      page,
+      provider: "claude",
+      cwd,
+      mode: "full-access",
+      providerConfig: { model: "opus" },
+    });
+    await sendMessage(
+      handle,
+      'Use Monitor with command `sleep 150`, timeout_ms 150000, persistent false, description "Watch the build". Do not wait; reply SPAWNED. Do not use other tools.',
+    );
+    await expectBackgroundAgentRunning(page);
+    const workspaceRow = page.getByTestId(
+      `sidebar-workspace-row-${getServerId()}:${handle.workspaceId}`,
+    );
+    await workspaceRow.scrollIntoViewIfNeeded();
+    await expect(workspaceRow.getByTestId("workspace-status-indicator-running")).toBeVisible();
+    const panel = await openBackgroundInventory(page, {
+      compact: false,
+      count: 1,
+      timeout: 30_000,
+    });
+    await expect(panel).toContainText("Watch the build");
+    await expect(panel).toContainText("sleep 150");
+    await expect(panel.getByRole("button", { name: "Stop Watch the build" })).toBeVisible();
+    await page.screenshot({
+      path: path.resolve("../../.artifacts/refinement-monitor-wide.png"),
+      animations: "disabled",
+    });
+  } finally {
+    await cleanupRewindFlow({ handle, cwd });
+  }
+});
diff --git a/packages/app/e2e/browser/question-prompt-pagination.spec.ts b/packages/app/e2e/browser/question-prompt-pagination.spec.ts
index 90a87433ed..35002ac2dd 100644
--- a/packages/app/e2e/browser/question-prompt-pagination.spec.ts
+++ b/packages/app/e2e/browser/question-prompt-pagination.spec.ts
@@ -108,10 +108,7 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("selecting description text never answers, and the label still does", async ({
-    page,
-    context,
-  }) => {
+  test("selecting description text keeps the question open", async ({ page, context }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
@@ -120,16 +117,13 @@ test.describe("Question option text", () => {
 
       await dragAcross(page, description);
       await expect.poll(() => selectedText(page)).toBe(DONE_DESCRIPTION);
-      await expectChecked(done, false);
-
       await description.getByText("Logs are at", { exact: false }).dblclick({
         position: { x: 4, y: 4 },
       });
       await expect.poll(() => selectedText(page)).toBe("Logs");
       await expectCurrentQuestion(page, { index: 1, total: 2, question: LINKED_QUESTION });
-      await expectChecked(done, false);
-
-      await done.getByText("Done", { exact: true }).click();
+      await expectChecked(done, true);
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
       await openQuestion(page, { index: 1, total: 2 });
       await expectChecked(done, true);
@@ -138,11 +132,17 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("double-clicking a single-select label answers once", async ({ page, context }) => {
+  test("double-clicking a single-select label selects once without advancing", async ({
+    page,
+    context,
+  }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
       await card.getByRole("radio", { name: "Done" }).getByText("Done", { exact: true }).dblclick();
+      await expectCurrentQuestion(page, { index: 1, total: 2, question: LINKED_QUESTION });
+      await expectChecked(card.getByRole("radio", { name: "Done" }), true);
+      await continueToNextQuestion(page);
 
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
       await expectChecked(card.getByRole("checkbox", { name: "Lint" }), false);
@@ -154,14 +154,12 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("multi-select description links and selection leave the option unchanged", async ({
-    page,
-    context,
-  }) => {
+  test("multi-select descriptions support links and text selection", async ({ page, context }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
       await card.getByRole("radio", { name: "Done" }).getByText("Done", { exact: true }).click();
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
 
       const lint = card.getByRole("checkbox", { name: "Lint" });
@@ -177,18 +175,16 @@ test.describe("Question option text", () => {
 
       await dragAcross(page, description);
       await expect.poll(() => selectedText(page)).toBe(LINT_DESCRIPTION);
-      await expectChecked(lint, false);
-
       await description.getByText("Rules:", { exact: false }).dblclick({
         position: { x: 4, y: 4 },
       });
       await expect.poll(() => selectedText(page)).toBe("Rules");
-      await expectChecked(lint, false);
+      await expectChecked(lint, true);
 
       await typecheck.getByText("Typecheck", { exact: true }).dblclick();
       await expectChecked(typecheck, true);
       await lint.getByText("Lint", { exact: true }).click();
-      await expectChecked(lint, true);
+      await expectChecked(lint, false);
     } finally {
       await session.cleanup();
     }
@@ -268,6 +264,7 @@ test.describe("Question prompt pagination", () => {
       await expectQuestionHidden(page, SUCCESS_QUESTION);
 
       await chooseQuestionOption(page, "App");
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, {
         index: 2,
         total: TOTAL_QUESTIONS,
@@ -288,6 +285,7 @@ test.describe("Question prompt pagination", () => {
         preview: 'flags.enabled("new-surface")',
       });
       await chooseQuestionOption(page, "Behind feature flag");
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, {
         index: 3,
         total: TOTAL_QUESTIONS,
@@ -466,7 +464,9 @@ retryTest(
     retryTest.setTimeout(180_000);
     const card = page.getByTestId("question-form-card");
     await chooseQuestionOption(page, "App");
+    await continueToNextQuestion(page);
     await chooseQuestionOption(page, "Behind feature flag");
+    await continueToNextQuestion(page);
     await fillQuestionAnswer(page, {
       question: SUCCESS_QUESTION,
       answer: "Preserve my answers after a failed submission.",
@@ -520,7 +520,9 @@ retryTest(
     const card = page.getByTestId("question-form-card");
     questionClient.releaseFirstResponse();
     await chooseQuestionOption(page, "App");
+    await continueToNextQuestion(page);
     await chooseQuestionOption(page, "Behind feature flag");
+    await continueToNextQuestion(page);
     await fillQuestionAnswer(page, {
       question: SUCCESS_QUESTION,
       answer: "Start with the internal team.",
diff --git a/packages/app/e2e/browser/schedules-edit-model-hydration.spec.ts b/packages/app/e2e/browser/schedules-edit-model-hydration.spec.ts
index de91c88569..4ca5f3378e 100644
--- a/packages/app/e2e/browser/schedules-edit-model-hydration.spec.ts
+++ b/packages/app/e2e/browser/schedules-edit-model-hydration.spec.ts
@@ -79,7 +79,9 @@ test.describe("Schedules", () => {
     cleanupTasks.length = 0;
   });
 
-  test("edit form hydrates the scheduled model selection", async ({ page }) => {
+  test("hydrates schedule editing and opens a pristine creation form afterward", async ({
+    page,
+  }) => {
     const workspace = await seedWorkspace({ repoPrefix: "schedule-model-hydration-" });
     cleanupTasks.push(() => workspace.cleanup());
     const scheduleName = `Hydrate model ${Date.now()}`;
@@ -93,29 +95,45 @@ test.describe("Schedules", () => {
 
     await row.click();
     const formSheet = page.getByTestId("schedule-form-sheet");
-    await expect(formSheet).toBeVisible({ timeout: 10_000 });
-    await expectStableHeight(formSheet);
     const hostTrigger = page.getByTestId("schedule-host-trigger");
     const projectTrigger = page.getByTestId("schedule-project-trigger");
     const modelTrigger = page.getByTestId("schedule-model-trigger");
     const thinkingTrigger = page.getByTestId("schedule-thinking-trigger");
     const modeTrigger = page.getByTestId("schedule-mode-trigger");
-    await expect(hostTrigger).toBeVisible({ timeout: 30_000 });
-    await expect(hostTrigger).toBeDisabled();
-    await expectSettled(hostTrigger);
-    await expect(projectTrigger).toContainText(workspace.projectDisplayName, { timeout: 30_000 });
-    await expectSettled(projectTrigger);
-    await expect(modelTrigger).toContainText("Ten second stream", { timeout: 30_000 });
-    await expectSettled(modelTrigger);
-    await expect(thinkingTrigger).toContainText("Low");
-    await expectSettled(thinkingTrigger);
-    await expect(modeTrigger).toBeVisible({ timeout: 30_000 });
-    await expectSettled(modeTrigger);
-    await expect(page.getByTestId("cadence-mode")).toHaveCount(0);
-    await expect(page.getByTestId("cadence-interval-value")).toHaveCount(0);
-    await expect(page.getByTestId("schedule-cadence-preset-trigger")).toContainText("Daily 9:00");
-    await expect(page.getByText(/Times are in/)).toHaveCount(0);
-    await expect(formSheet.getByText("Cron", { exact: true })).toHaveCount(0);
+    await test.step("edit form hydrates the saved model and controls", async () => {
+      await expect(formSheet).toBeVisible({ timeout: 10_000 });
+      await expectStableHeight(formSheet);
+      await expect(hostTrigger).toBeVisible({ timeout: 30_000 });
+      await expect(hostTrigger).toBeDisabled();
+      await expectSettled(hostTrigger);
+      await expect(projectTrigger).toContainText(workspace.projectDisplayName, { timeout: 30_000 });
+      await expectSettled(projectTrigger);
+      await expect(modelTrigger).toContainText("Ten second stream", { timeout: 30_000 });
+      await expectSettled(modelTrigger);
+      await expect(thinkingTrigger).toContainText("Low");
+      await expectSettled(thinkingTrigger);
+      await expect(modeTrigger).toBeVisible({ timeout: 30_000 });
+      await expectSettled(modeTrigger);
+      await expect(page.getByTestId("cadence-mode")).toHaveCount(0);
+      await expect(page.getByTestId("cadence-interval-value")).toHaveCount(0);
+      await expect(page.getByTestId("schedule-cadence-preset-trigger")).toContainText("Daily 9:00");
+      await expect(page.getByText(/Times are in/)).toHaveCount(0);
+      await expect(formSheet.getByText("Cron", { exact: true })).toHaveCount(0);
+    });
+
+    await test.step("closing edit leaves the new schedule form pristine", async () => {
+      await page.getByRole("button", { name: "Cancel" }).click();
+      await expect(formSheet).toHaveCount(0, { timeout: 30_000 });
+
+      await page.getByTestId("schedules-new").click();
+      await expect(formSheet).toBeVisible({ timeout: 10_000 });
+      await expect(projectTrigger).toContainText(/select project/i);
+      await expectSettled(projectTrigger);
+      await expect(page.getByTestId("schedule-model-trigger")).toHaveCount(0);
+      await expect(page.getByTestId("schedule-thinking-trigger")).toHaveCount(0);
+      await expect(page.getByTestId("schedule-mode-trigger")).toHaveCount(0);
+      await expect(page.getByTestId("cadence-interval-value")).toHaveCount(0);
+    });
   });
 
   test("edit form hydrates a non-default host schedule after reload", async ({ page }) => {
@@ -165,32 +183,4 @@ test.describe("Schedules", () => {
     await expect(page.getByTestId("cadence-mode")).toHaveCount(0);
     await expect(page.getByTestId("schedule-cadence-preset-trigger")).toContainText("Daily 9:00");
   });
-
-  test("create opens pristine after closing an edit form", async ({ page }) => {
-    const workspace = await seedWorkspace({ repoPrefix: "schedule-pristine-create-" });
-    cleanupTasks.push(() => workspace.cleanup());
-    const scheduleName = `Pristine create ${Date.now()}`;
-    const scheduleId = await seedMockSchedule(workspace, scheduleName);
-    cleanupTasks.push(() => deleteSeededSchedule(workspace, scheduleId));
-
-    await page.goto(buildSchedulesRoute());
-    const row = page.getByTestId(`schedule-row-${scheduleId}`);
-    await expect(row).toBeVisible({ timeout: 30_000 });
-    await row.click();
-    const formSheet = page.getByTestId("schedule-form-sheet");
-    await expect(formSheet).toBeVisible({ timeout: 10_000 });
-    await expectStableHeight(formSheet);
-    await page.getByRole("button", { name: "Cancel" }).click();
-    await expect(formSheet).toHaveCount(0, { timeout: 30_000 });
-
-    await page.getByTestId("schedules-new").click();
-    await expect(formSheet).toBeVisible({ timeout: 10_000 });
-    const projectTrigger = page.getByTestId("schedule-project-trigger");
-    await expect(projectTrigger).toContainText(/select project/i);
-    await expectSettled(projectTrigger);
-    await expect(page.getByTestId("schedule-model-trigger")).toHaveCount(0);
-    await expect(page.getByTestId("schedule-thinking-trigger")).toHaveCount(0);
-    await expect(page.getByTestId("schedule-mode-trigger")).toHaveCount(0);
-    await expect(page.getByTestId("cadence-interval-value")).toHaveCount(0);
-  });
 });
diff --git a/packages/app/e2e/browser/sessions-search.spec.ts b/packages/app/e2e/browser/sessions-search.spec.ts
index 7f54617304..6cf8024e35 100644
--- a/packages/app/e2e/browser/sessions-search.spec.ts
+++ b/packages/app/e2e/browser/sessions-search.spec.ts
@@ -60,6 +60,15 @@ async function verifyChronologicalFiltering(page: Page): Promise<void> {
   });
 }
 
+async function verifyHistorySurvivesReload(page: Page): Promise<void> {
+  await test.step("reloads History without visiting a workspace to reconnect", async () => {
+    await expectVisibleTitles(page, [TITLES.unbilled, TITLES.billing, TITLES.terminal]);
+    await page.reload();
+    await expectVisibleTitles(page, [TITLES.unbilled, TITLES.billing, TITLES.terminal]);
+    await expect(page.getByTestId("sessions-host-errors")).toBeHidden();
+  });
+}
+
 async function verifyRecencyBeforeMatchStrength(page: Page): Promise<void> {
   await test.step("keeps newer partial matches before older stronger matches", async () => {
     await search(page, `${NONCE} bill`);
@@ -151,6 +160,8 @@ test.describe("History search", () => {
 
       await verifyChronologicalFiltering(page);
 
+      await verifyHistorySurvivesReload(page);
+
       await verifyRecencyBeforeMatchStrength(page);
 
       await verifyExactAndTypoHighlights(page);
diff --git a/packages/app/e2e/browser/settings-host-page.spec.ts b/packages/app/e2e/browser/settings-host-page.spec.ts
index f9b358a307..4ada0c7fac 100644
--- a/packages/app/e2e/browser/settings-host-page.spec.ts
+++ b/packages/app/e2e/browser/settings-host-page.spec.ts
@@ -1,3 +1,8 @@
+import {
+  openGlobalNewWorkspaceComposer,
+  fillNewWorkspaceDraft,
+  expectNewWorkspaceDraft,
+} from "../support/helpers/new-workspace";
 import { readFile, mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -257,12 +262,15 @@ test.describe("Settings host page", () => {
   });
 });
 
-test("restart recovery host controls persist the opt-out and custom prompt", async ({ page }) => {
+test("restart recovery defaults off and persists opt-in and custom prompt", async ({ page }) => {
   const serverId = getServerId();
   await gotoAppShell(page);
   await openSettings(page);
   await openSettingsHost(page, serverId);
   await openHostSection(page, serverId, "agents");
+  await expectRestartRecoveryEnabled(page, false);
+  await setRestartRecoveryEnabled(page, true);
+  await page.reload();
   await expectRestartRecoveryEnabled(page, true);
   await expectRestartRecoveryPrompt(page, "Resume working.");
   await editRestartRecoveryPrompt(page, "Continue the interrupted work.");
@@ -273,3 +281,71 @@ test("restart recovery host controls persist the opt-out and custom prompt", asy
   await expectRestartRecoveryPrompt(page, "Continue the interrupted work.");
   await editRestartRecoveryPrompt(page, "Resume working.");
 });
+
+test("sidebar Add host preserves its caller and stays closed after theme changes", async ({
+  page,
+}) => {
+  await gotoAppShell(page);
+  await expect(page).toHaveURL(/\/open-project$/);
+  const originalUrl = page.url();
+  await openSidebarAddHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await closeAddHostAndChangeTheme(page);
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeHidden();
+  await expect(page).toHaveURL(originalUrl);
+});
+
+async function openSidebarAddHost(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Hosts", exact: true }).click();
+  await page.getByRole("button", { name: "Add host", exact: true }).click();
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeVisible();
+}
+
+async function closeAddHostAndChangeTheme(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Close", exact: true }).click();
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeHidden();
+  await page.keyboard.press("Control+Alt+t");
+}
+
+test("sidebar Add host completes without navigating", async ({ page }) => {
+  await gotoAppShell(page);
+  await expect(page).toHaveURL(/\/open-project$/);
+  const originalUrl = page.url();
+  await openSidebarAddHost(page);
+  await connectToTestHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await expect(page.getByRole("button", { name: "Hosts", exact: true })).toBeVisible();
+});
+
+test("Settings Add host opens the saved host Overview", async ({ page }) => {
+  await gotoAppShell(page);
+  await openSettings(page);
+  await addDirectHostFromSettings(page, { host: "127.0.0.1", port: Number(getE2EDaemonPort()) });
+  await expectSettingsHeader(page, "Overview");
+  await expect(page).toHaveURL(new RegExp(`/settings/hosts/${getServerId()}/host$`));
+});
+
+test("New workspace Add host preserves the prompt after connecting", async ({ page }) => {
+  await gotoAppShell(page);
+  await openGlobalNewWorkspaceComposer(page);
+  await fillNewWorkspaceDraft(page, "Keep this unfinished prompt while I add a host.");
+  const originalUrl = page.url();
+  await openNewWorkspaceAddHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await connectToTestHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await expectNewWorkspaceDraft(page, "Keep this unfinished prompt while I add a host.");
+});
+
+async function openNewWorkspaceAddHost(page: import("@playwright/test").Page) {
+  await page.getByTestId("host-picker-trigger").click();
+  await page.getByRole("button", { name: "Add host", exact: true }).click();
+}
+
+async function connectToTestHost(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Direct connection", exact: true }).click();
+  await page.getByRole("textbox", { name: "Host", exact: true }).fill("127.0.0.1");
+  await page.getByRole("textbox", { name: "Port", exact: true }).fill(String(getE2EDaemonPort()));
+  await page.getByRole("button", { name: "Connect", exact: true }).click();
+  await expect(page.getByTestId("add-host-modal")).toBeHidden({ timeout: 30_000 });
+}
diff --git a/packages/app/e2e/browser/settings-navigation.spec.ts b/packages/app/e2e/browser/settings-navigation.spec.ts
index 3ec921a663..5b019139f2 100644
--- a/packages/app/e2e/browser/settings-navigation.spec.ts
+++ b/packages/app/e2e/browser/settings-navigation.spec.ts
@@ -38,6 +38,9 @@ import {
   fillDirectHostUri,
   expectDirectHostFormValues,
   expectDirectHostSslEnabled,
+  expectDirectHostSslDisabled,
+  fillDirectHostAddress,
+  toggleDirectHostSsl,
   expectDirectHostUriValue,
   expectDirectHostUriHidden,
   expectDiagnosticsContent,
@@ -92,66 +95,63 @@ test.describe("Settings sidebar scroll position", () => {
     await expectSettingsSidebarScrollOffset(page, offset);
   });
 
-  test("scrolls the sidebar and detail pane independently", async ({ page }) => {
-    await gotoAppShell(page);
-    await openSettings(page);
-    const sidebarOffset = await scrollSettingsSidebarToEnd(page);
-    await openSettingsHostSection(page, getServerId(), "providers");
-    await expect(page.getByTestId("host-page-providers-card")).toBeVisible();
-    const detailOffset = await scrollSettingsDetailDown(page);
-    await expectSettingsSidebarScrollOffset(page, sidebarOffset);
-
-    await scrollSettingsSidebarUp(page, 60);
-    await expectSettingsSidebarScrollOffset(page, sidebarOffset - 60);
-    await expectSettingsDetailScrollOffset(page, detailOffset);
-  });
-
-  test("keeps the sidebar position after rapid consecutive selections", async ({ page }) => {
-    await gotoAppShell(page);
-    await openSettings(page);
-
-    const scrollTop = await scrollSettingsSidebarToEnd(page);
-
-    await selectSettingsHostSectionsRapidly(page);
-    await expectSettingsSidebarScrollOffset(page, scrollTop);
-
-    await expectSettingsSidebarScrollSettled(page, scrollTop);
-  });
-
-  test("keeps the sidebar position when switching between app and host sections", async ({
+  test("keeps sidebar and detail scrolling independent through section changes", async ({
     page,
   }) => {
     await gotoAppShell(page);
     await openSettings(page);
 
-    const hostScrollTop = await scrollSettingsSidebarToEnd(page);
-    await expect(page.getByTestId("settings-host-section-providers")).toBeInViewport();
+    await test.step("scrolls the sidebar and detail pane independently", async () => {
+      const sidebarOffset = await scrollSettingsSidebarToEnd(page);
+      await openSettingsHostSection(page, getServerId(), "providers");
+      await expect(page.getByTestId("host-page-providers-card")).toBeVisible();
+      const detailOffset = await scrollSettingsDetailDown(page);
+      await expectSettingsSidebarScrollOffset(page, sidebarOffset);
 
-    for (const section of [
-      "providers",
-      "terminals",
-      "providers",
-      "terminals",
-      "providers",
-    ] as const) {
-      await openSettingsHostSection(page, getServerId(), section);
-      await expect(page.getByTestId("page-title")).toHaveText(
-        section === "providers" ? "Providers" : "Terminals",
-      );
-      await expectSettingsSidebarScrollOffset(page, hostScrollTop);
-    }
+      await scrollSettingsSidebarUp(page, 60);
+      await expectSettingsSidebarScrollOffset(page, sidebarOffset - 60);
+      await expectSettingsDetailScrollOffset(page, detailOffset);
+    });
 
-    const sidebar = page.getByTestId("settings-sidebar");
-    const appScrollTop = await revealSettingsSidebarSection(page, "diagnostics");
-    await expect(sidebar.getByRole("button", { name: "About", exact: true })).toBeInViewport();
+    await test.step("keeps the sidebar position after rapid consecutive selections", async () => {
+      const scrollTop = await scrollSettingsSidebarToEnd(page);
 
-    await openSettingsSection(page, "about");
-    await expectAboutContent(page);
-    await expectSettingsSidebarScrollOffset(page, appScrollTop);
+      await selectSettingsHostSectionsRapidly(page);
+      await expectSettingsSidebarScrollOffset(page, scrollTop);
 
-    await openSettingsSection(page, "diagnostics");
-    await expectDiagnosticsContent(page);
-    await expectSettingsSidebarScrollOffset(page, appScrollTop);
+      await expectSettingsSidebarScrollSettled(page, scrollTop);
+    });
+
+    await test.step("keeps the sidebar position when switching between app and host sections", async () => {
+      const hostScrollTop = await scrollSettingsSidebarToEnd(page);
+      await expect(page.getByTestId("settings-host-section-providers")).toBeInViewport();
+
+      for (const section of [
+        "providers",
+        "terminals",
+        "providers",
+        "terminals",
+        "providers",
+      ] as const) {
+        await openSettingsHostSection(page, getServerId(), section);
+        await expect(page.getByTestId("page-title")).toHaveText(
+          section === "providers" ? "Providers" : "Terminals",
+        );
+        await expectSettingsSidebarScrollOffset(page, hostScrollTop);
+      }
+
+      const sidebar = page.getByTestId("settings-sidebar");
+      const appScrollTop = await revealSettingsSidebarSection(page, "diagnostics");
+      await expect(sidebar.getByRole("button", { name: "About", exact: true })).toBeInViewport();
+
+      await openSettingsSection(page, "about");
+      await expectAboutContent(page);
+      await expectSettingsSidebarScrollOffset(page, appScrollTop);
+
+      await openSettingsSection(page, "diagnostics");
+      await expectDiagnosticsContent(page);
+      await expectSettingsSidebarScrollOffset(page, appScrollTop);
+    });
   });
 });
 
@@ -284,6 +284,16 @@ test.describe("Settings sidebar navigation", () => {
     await expectAddHostMethodOptions(page);
     await selectHostConnectionType(page, "direct");
 
+    await fillDirectHostAddress(page, "example.paseo.test", "7443");
+    await expectDirectHostSslDisabled(page);
+    await toggleDirectHostSsl(page);
+    await expectDirectHostSslEnabled(page);
+    await toggleHostAdvanced(page);
+    await expectDirectHostUriValue(page, "tcp://example.paseo.test:7443?ssl=true");
+    await toggleHostAdvanced(page);
+    await toggleDirectHostSsl(page);
+    await expectDirectHostSslDisabled(page);
+
     await toggleHostAdvanced(page);
     await fillDirectHostUri(page, "tcp://example.paseo.test:7443?ssl=true&password=shared-secret");
     await toggleHostAdvanced(page);
@@ -313,12 +323,12 @@ test.describe("Settings sidebar navigation", () => {
 
     await test.step("a dropdown owns Escape", async () => {
       await openSettingsSection(page, "appearance");
-      await page.getByLabel(/Theme:/).click();
-      await expect(page.getByRole("menuitem", { name: "System", exact: true })).toBeVisible();
+      await page.getByLabel(/Highlight theme:/).click();
+      await expect(page.getByRole("menuitem", { name: "GitHub", exact: true })).toBeVisible();
 
       await page.keyboard.press("Escape");
 
-      await expect(page.getByRole("menuitem", { name: "System", exact: true })).toHaveCount(0);
+      await expect(page.getByRole("menuitem", { name: "GitHub", exact: true })).toHaveCount(0);
       await expect(page).toHaveURL(/\/settings(\/|$)/);
     });
 
diff --git a/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts b/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts
new file mode 100644
index 0000000000..da16dbb648
--- /dev/null
+++ b/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts
@@ -0,0 +1,127 @@
+import { expect, test } from "../support/fixtures";
+import { addProjectFlow } from "../support/helpers/add-project-flow";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  chooseFooterOverflowAction,
+  expectFooterLine,
+  expectFooterMenusInsideViewport,
+  expectFooterNeverClipped,
+  expectFooterOverflowActions,
+  footerOverflowMenu,
+  openFooterOverflow,
+  seedDockedSidebarWidth,
+  watchFooterClipping,
+} from "../support/helpers/sidebar-footer-overflow";
+import { addOfflineHostsAndReload } from "../support/helpers/hosts";
+import { openCompactSidebar } from "../support/helpers/usage-sidebar-item";
+
+const TOUCH_CONTROL = 44;
+const MIN_SIDEBAR_WIDTH = 200;
+const ALL_INLINE = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-settings",
+];
+// Five 44pt buttons and the row's padding need 236pt; 200pt holds three and the caret.
+const NARROW_TOUCH_LINE = [
+  "sidebar-add-project",
+  "sidebar-hosts-trigger",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+test.describe("Sidebar footer on a touch screen", () => {
+  test.use({ viewport: { width: 1280, height: 800 }, hasTouch: true });
+
+  test("a narrow docked sidebar moves the actions it can't fit behind a caret", async ({
+    page,
+  }) => {
+    await seedDockedSidebarWidth(page, MIN_SIDEBAR_WIDTH);
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+
+    await test.step("Help opens as a page of the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+      await chooseFooterOverflowAction(page, "Help and support");
+      await expect(page.getByRole("menuitem", { name: "What's new" })).toBeVisible();
+      await expect(page.getByTestId("sidebar-help-menu")).toHaveCount(0);
+      await page.keyboard.press("Escape");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+    });
+
+    await test.step("Usage opens from the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await chooseFooterOverflowAction(page, "Usage");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+      await expect(page.getByTestId("usage-modal")).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(page.getByTestId("usage-modal")).toBeHidden();
+    });
+
+    await test.step("Add project and Settings shortcuts still work", async () => {
+      await page.keyboard.press("Control+o");
+      await expect(addProjectFlow(page)).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(addProjectFlow(page)).toBeHidden();
+      await page.keyboard.press("Control+,");
+      await expect(page).toHaveURL(/\/settings\/general$/);
+    });
+  });
+
+  test("the default sidebar width keeps all five actions inline", async ({ page }) => {
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: ALL_INLINE, controlSize: TOUCH_CONTROL });
+  });
+});
+
+test.describe("Sidebar footer in a compact overlay narrower than the footer", () => {
+  test.use({ viewport: { width: 220, height: 800 }, hasTouch: true });
+
+  test("the overflow menu reaches the hidden actions", async ({ page }) => {
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await openCompactSidebar(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+  });
+});
+
+test.describe("Sidebar footer on a short, narrow phone", () => {
+  // 164pt for buttons holds Settings, Add project and the caret, so Hosts moves behind it.
+  test.use({ viewport: { width: 180, height: 360 }, hasTouch: true });
+
+  test("the overflow Hosts page scrolls to its last host and Add host", async ({ page }) => {
+    await gotoAppShell(page);
+    await addOfflineHostsAndReload(
+      page,
+      Array.from({ length: 10 }, (_, index) => ({
+        serverId: `overflow-host-${index}`,
+        label: `Overflow host ${index}`,
+      })),
+    );
+    await openCompactSidebar(page);
+    await expectFooterLine(page, {
+      testIDs: ["sidebar-add-project", "sidebar-footer-overflow", "sidebar-settings"],
+      controlSize: TOUCH_CONTROL,
+    });
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Hosts", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+    await chooseFooterOverflowAction(page, "Hosts");
+    await expectFooterMenusInsideViewport(page);
+    const addHost = page.getByRole("menuitem", { name: "Add host" });
+    await addHost.scrollIntoViewIfNeeded();
+    await expect(page.getByRole("menuitem", { name: "Overflow host 9" })).toBeVisible();
+    await expect(addHost).toBeInViewport();
+    await addHost.click();
+    await expect(page.getByText("Add connection", { exact: true })).toBeVisible();
+  });
+});
diff --git a/packages/app/e2e/browser/sidebar-help.spec.ts b/packages/app/e2e/browser/sidebar-help.spec.ts
index 4c0162e8d8..973b0ffc81 100644
--- a/packages/app/e2e/browser/sidebar-help.spec.ts
+++ b/packages/app/e2e/browser/sidebar-help.spec.ts
@@ -1,7 +1,14 @@
 import { expect, test, type Page } from "../support/fixtures";
 import { gotoAppShell, openSettings } from "../support/helpers/app";
 import { openSettingsSection } from "../support/helpers/settings";
-import { openWhatsNew, release, serveChangelog } from "../support/helpers/changelog";
+import {
+  allChangesToggle,
+  hideAllChanges,
+  openWhatsNew,
+  release,
+  serveChangelog,
+  showAllChanges,
+} from "../support/helpers/changelog";
 
 const DISCORD_DESTINATION =
   /^https:\/\/(?:discord\.gg\/jz8T2uahpH|discord\.com\/invite\/jz8T2uahpH)(?:[/?#]|$)/;
@@ -73,26 +80,30 @@ test("opens troubleshooting and support destinations", async ({ page }) => {
 });
 
 test("renders the changelog in the app and links the website", async ({ page }) => {
-  // A callout, a section name the app has never seen, and a fenced sample whose
-  // contents look like a release heading.
+  // Highlights, a section name the app has never seen, a callout, and a fenced
+  // sample whose contents look like a release heading.
   await serveChangelog(page, [
     "# Changelog",
     "",
     "## 9.1.0 - 2026-03-04",
     "",
-    "Headline release note.",
-    "",
-    "> [!WARNING]",
-    "> Read this before upgrading.",
+    "- **Background tasks:** Paseo now shows the tasks an agent is running.",
     "",
     "### Sparkles",
     "",
     "- Added a brand new thing",
     "",
+    "> [!WARNING]",
+    "> Read this before upgrading.",
+    "",
     "```md",
     "## 0.0.0 - 1999-01-01",
     "```",
     "",
+    "### Fixed",
+    "",
+    "- Fixed a crash",
+    "",
     "## 9.0.0 - 2026-02-01",
     "",
     "### Fixed",
@@ -104,14 +115,32 @@ test("renders the changelog in the app and links the website", async ({ page })
 
   const sheet = await openWhatsNew(page);
   const latest = release(sheet, "9.1.0");
+  const older = release(sheet, "9.0.0");
 
-  await expect(latest.getByText("March 4, 2026", { exact: true })).toBeVisible();
-  await expect(latest.getByText("Headline release note.")).toBeVisible();
-  await expect(latest.getByText("Read this before upgrading.")).toBeVisible();
-  await expect(latest.getByText("Sparkles", { exact: true })).toBeVisible();
-  await expect(latest.getByText("Added a brand new thing")).toBeVisible();
-  await expect(release(sheet, "9.0.0")).toBeVisible();
-  await expect(release(sheet, "0.0.0")).toHaveCount(0);
+  await test.step("leads a release with its highlights and tucks the rest away", async () => {
+    await expect(latest.getByText("March 4, 2026", { exact: true })).toBeVisible();
+    await expect(latest.getByText("Paseo now shows the tasks an agent is running.")).toBeVisible();
+    await expect(latest.getByText("Added a brand new thing")).toHaveCount(0);
+    await expect(latest.getByText("Fixed a crash")).toHaveCount(0);
+  });
+
+  await test.step("shows every section on request and tucks them away again", async () => {
+    await showAllChanges(latest);
+    await expect(latest.getByText("Sparkles", { exact: true })).toBeVisible();
+    await expect(latest.getByText("Added a brand new thing")).toBeVisible();
+    await expect(latest.getByText("Read this before upgrading.")).toBeVisible();
+    await expect(latest.getByText("Fixed a crash")).toBeVisible();
+    await expect(release(sheet, "0.0.0")).toHaveCount(0);
+
+    await hideAllChanges(latest);
+    await expect(latest.getByText("Added a brand new thing")).toHaveCount(0);
+    await expect(latest.getByText("Paseo now shows the tasks an agent is running.")).toBeVisible();
+  });
+
+  await test.step("shows a release without highlights whole", async () => {
+    await expect(older.getByText("Fixed an older thing")).toBeVisible();
+    await expect(allChangesToggle(older)).toHaveCount(0);
+  });
 
   await expectExternalPage(page, "changelog-open-website", CHANGELOG_DESTINATION);
   await closeSheet(page, "changelog-sheet");
diff --git a/packages/app/e2e/browser/sidebar-nav-settings.spec.ts b/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
index b557b73ccb..618d44729c 100644
--- a/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
+++ b/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
@@ -97,6 +97,7 @@ test("fixed footer line keeps its five icons, Help and Settings at the end", asy
   await setFooterItemVisible(page, "usage", true);
   await leaveSettings(page);
   await page.setViewportSize({ width: 390, height: 844 });
+  await openCompactSidebar(page);
   await expectCompactSidebarOpen(page);
   await expectFooterSeparator(page, true);
   await expectFooterIconRow(page);
diff --git a/packages/app/e2e/browser/sidebar-reorder.spec.ts b/packages/app/e2e/browser/sidebar-reorder.spec.ts
index 56cdd3dc5a..cf885a1d14 100644
--- a/packages/app/e2e/browser/sidebar-reorder.spec.ts
+++ b/packages/app/e2e/browser/sidebar-reorder.spec.ts
@@ -426,3 +426,81 @@ test("Manual restores pre-beta order and keeps drag order across sorting and rel
     await seed.cleanup();
   }
 });
+
+function workspaceRows(page: Page, ids: string[]) {
+  return page.locator(
+    ids.map((id) => `[data-testid="sidebar-workspace-row-${getServerId()}:${id}"]`).join(", "),
+  );
+}
+
+async function openWorkspaceRow(page: Page, workspaceId: string) {
+  await page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`).click();
+  await expect(page).toHaveURL(new RegExp(`/workspace/${workspaceId}`));
+}
+
+test("collapsed groups lead with the open workspace instead of hiding it behind Show more", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  const { seed, ids } = await seedCompactProject();
+  try {
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await selectWorkspaceSort(page, "Created");
+    const { rows, group } = compactProjectRows(page, seed);
+    await expectWorkspaceOrder(rows, ids.slice(0, 7));
+    await revealWorkspaces(group, "Show more");
+    await openWorkspaceRow(page, ids[9]!);
+    await expectWorkspaceOrder(rows, ids);
+    await revealWorkspaces(group, "Show less");
+    await expectWorkspaceOrder(rows, [ids[9]!, ...ids.slice(0, 7)]);
+    await expect(
+      page.getByTestId(`sidebar-workspace-row-${getServerId()}:${ids[9]!}`),
+    ).toHaveAttribute("aria-selected", "true");
+    await reconnectSidebar(page);
+    await expectWorkspaceOrder(rows, [ids[9]!, ...ids.slice(0, 7)]);
+    await expect(
+      page.getByTestId(`sidebar-workspace-row-${getServerId()}:${ids[9]!}`),
+    ).toHaveAttribute("aria-selected", "true");
+    await openWorkspaceRow(page, ids[2]!);
+    await expectWorkspaceOrder(rows, ids.slice(0, 7));
+    await expect(
+      page.getByTestId(`sidebar-workspace-row-${getServerId()}:${ids[2]!}`),
+    ).toHaveAttribute("aria-selected", "true");
+  } finally {
+    await seed.cleanup();
+  }
+});
+
+test("a Manual drag in a collapsed group keeps the open workspace's saved place", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  const { seed, ids } = await seedCompactProject();
+  try {
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    const projectKey = projectEquivalenceViewKey(seed.projectKey);
+    await restorePreBetaOrder(
+      page,
+      projectKey,
+      ids.map((id) => `${getServerId()}:${id}`),
+    );
+    await selectWorkspaceSort(page, "Manual");
+    const rows = workspaceRows(page, ids);
+    const toggle = page.getByTestId(`sidebar-project-show-more-${projectKey}`);
+    await expectWorkspaceOrder(rows, ids.slice(0, 7));
+    await toggle.click();
+    await openWorkspaceRow(page, ids[9]!);
+    await toggle.click();
+    await expectWorkspaceOrder(rows, [ids[9]!, ...ids.slice(0, 7)]);
+    await quickDragFirstRowAfterSecond(workspaceRows(page, [ids[0]!, ids[1]!]), pressWorkspaceRow);
+    await expectWorkspaceOrder(rows, [ids[9]!, ids[1]!, ids[0]!, ...ids.slice(2, 7)]);
+    await reconnectSidebar(page);
+    await expectWorkspaceOrder(rows, [ids[9]!, ids[1]!, ids[0]!, ...ids.slice(2, 7)]);
+    await toggle.click();
+    await expectWorkspaceOrder(rows, [ids[1]!, ids[0]!, ...ids.slice(2)]);
+  } finally {
+    await seed.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/sidebar-views.spec.ts b/packages/app/e2e/browser/sidebar-views.spec.ts
new file mode 100644
index 0000000000..665b682b53
--- /dev/null
+++ b/packages/app/e2e/browser/sidebar-views.spec.ts
@@ -0,0 +1,18 @@
+import { test } from "../support/fixtures";
+import { withSidebarViews } from "../support/helpers/sidebar-views";
+
+test("sidebar views replace the content, preserve chrome, and recover to the default", async ({
+  page,
+}) => {
+  test.setTimeout(150_000);
+  await withSidebarViews(page, async (views) => {
+    await views.expectDefault();
+    await views.chooseWorkspaces();
+    await views.exerciseExamples();
+    await views.exerciseTerminals();
+    await views.restoreDefault();
+    await views.recoverFromFailure();
+    await views.chooseWorkspaces();
+    await views.disableChosenView();
+  });
+});
diff --git a/packages/app/e2e/browser/sidebar-workspace-mark-unread.spec.ts b/packages/app/e2e/browser/sidebar-workspace-mark-unread.spec.ts
index ccf29179b8..670f5564b1 100644
--- a/packages/app/e2e/browser/sidebar-workspace-mark-unread.spec.ts
+++ b/packages/app/e2e/browser/sidebar-workspace-mark-unread.spec.ts
@@ -1,12 +1,13 @@
 import type { Page } from "@playwright/test";
 import { test as base, expect } from "../support/fixtures";
-import { gotoAppShell } from "../support/helpers/app";
 import {
   openAgentRoute,
   seedMockAgentWorkspace,
   type MockAgentWorkspace,
 } from "../support/helpers/mock-agent";
 import { expectOpenTabCount } from "../support/helpers/sheet";
+import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
+import { expectReconnectingToastGone } from "../support/helpers/workspace-ui";
 import { getServerId } from "../support/helpers/server-id";
 import { closeMobileAgentSidebar, openMobileAgentSidebar } from "../support/helpers/sidebar";
 
@@ -101,11 +102,13 @@ async function leaveMarkedWorkspaceAndReopen(page: Page, { subject, other }: Fin
 }
 
 async function completeTurnAndLeave(page: Page, { subject, other }: FinishedWorkspaces) {
-  await test.step("ordinary completion still clears on departure", async () => {
+  await test.step("ordinary completion stays unread on departure and clears on return", async () => {
     await subject.client.sendAgentMessage(subject.agentId, "Finish another turn.");
     await subject.client.waitForFinish(subject.agentId, 20_000);
     await expectStatus(page, subject.workspaceId, "attention");
     await openWorkspace(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspace(page, subject.workspaceId);
     await expectStatus(page, subject.workspaceId, "done");
   });
 }
@@ -141,13 +144,15 @@ async function leaveMarkedWorkspaceAndReopenOnCompact(
 }
 
 async function completeTurnAndLeaveOnCompact(page: Page, { subject, other }: FinishedWorkspaces) {
-  await test.step("ordinary completion still clears on departure", async () => {
+  await test.step("ordinary completion stays unread on departure and clears on return", async () => {
     await closeMobileAgentSidebar(page);
     await subject.client.sendAgentMessage(subject.agentId, "Finish another turn.");
     await subject.client.waitForFinish(subject.agentId, 20_000);
     await openMobileAgentSidebar(page);
     await expectStatus(page, subject.workspaceId, "attention");
     await openWorkspaceOnCompact(page, other.workspaceId);
+    await expectStatus(page, subject.workspaceId, "attention");
+    await openWorkspaceOnCompact(page, subject.workspaceId);
     await expectStatus(page, subject.workspaceId, "done");
   });
 }
@@ -194,11 +199,12 @@ async function markUnreadThenResumeChat(page: Page, workspaceId: string) {
   });
 }
 
-test("manual unread survives departure and clears on reopening without changing normal completions", async ({
+test("manual unread survives departure and clears on reopening and ordinary completion survives departure", async ({
   page,
   workspaces,
 }) => {
-  await gotoAppShell(page);
+  await openAgentRoute(page, workspaces.subject);
+  await expect(page.getByText("Finish this turn.", { exact: true })).toBeVisible();
   await openWorkspace(page, workspaces.other.workspaceId);
   await markBackgroundWorkspaceAndReopen(page, workspaces.subject.workspaceId);
   await leaveMarkedWorkspaceAndRead(page, workspaces);
@@ -207,16 +213,19 @@ test("manual unread survives departure and clears on reopening without changing
   await markBackgroundWorkspaceAndRead(page, workspaces.subject.workspaceId);
 });
 
-test("clicking a multi-agent workspace reveals and clears its marked agent", async ({
+test("clicking a multi-agent workspace preserves its selected agent and leaves the other unread", async ({
   page,
   workspaces,
 }) => {
   await openAgentRoute(page, workspaces.subject);
+  await expect(page.getByText("Finish this turn.", { exact: true })).toBeVisible();
   await expectSelectedAgent(page, workspaces.subject.agentId);
   await openWorkspace(page, workspaces.other.workspaceId);
-  const newest = await addFinishedAgent(workspaces.subject);
-  await markBackgroundWorkspaceAndReopen(page, workspaces.subject.workspaceId);
-  await expectSelectedAgent(page, newest.id);
+  await addFinishedAgent(workspaces.subject);
+  await markAsUnread(page, workspaces.subject.workspaceId);
+  await openWorkspace(page, workspaces.subject.workspaceId);
+  await expectSelectedAgent(page, workspaces.subject.agentId);
+  await expectStatus(page, workspaces.subject.workspaceId, "attention");
 });
 
 test("manual unread survives leaving the current workspace on compact layout", async ({
@@ -230,7 +239,7 @@ test("manual unread survives leaving the current workspace on compact layout", a
   await completeTurnAndLeaveOnCompact(page, workspaces);
 });
 
-async function reopenMarkedWorkspaceAfterBackgroundTurn(page: Page, workspace: MockAgentWorkspace) {
+async function reopenWorkspaceAfterBackgroundTurn(page: Page, workspace: MockAgentWorkspace) {
   const route = page.url();
   // End this app session before the turn, so its cached transcript cannot contain the new prompt.
   await page.goto("about:blank");
@@ -265,9 +274,68 @@ test("reopening a marked unread workspace restores only its agent tab and curren
   await test.step("mark the current workspace unread, then close and reopen the app", async () => {
     await openMobileAgentSidebar(page);
     await markAsUnread(page, workspaces.subject.workspaceId);
-    await reopenMarkedWorkspaceAfterBackgroundTurn(page, workspaces.subject);
+    await reopenWorkspaceAfterBackgroundTurn(page, workspaces.subject);
   });
   await test.step("restore the main tab without Explorer entries and load its latest history", async () => {
     await expectRestoredCompactChat(page);
   });
 });
+
+test("clicking the already focused timeline acknowledges a new completion", async ({
+  page,
+  workspaces,
+}) => {
+  await openAgentRoute(page, workspaces.subject);
+  await expect(page.getByText("Finish this turn.", { exact: true })).toBeVisible();
+  await workspaces.subject.client.sendAgentMessage(
+    workspaces.subject.agentId,
+    "Finish another turn.",
+  );
+  await workspaces.subject.client.waitForFinish(workspaces.subject.agentId, 20_000);
+  await expectStatus(page, workspaces.subject.workspaceId, "attention");
+  await page.getByText("Finish another turn.", { exact: true }).click();
+  await expectStatus(page, workspaces.subject.workspaceId, "done");
+});
+
+async function reconnectWithoutInteracting(
+  page: Page,
+  gate: Awaited<ReturnType<typeof installDaemonWebSocketGate>>,
+) {
+  await gate.drop();
+  await gate.waitForBlockedConnection();
+  gate.restore();
+  await expectReconnectingToastGone(page);
+  await expect(page.getByRole("alert").filter({ hasText: "Updating messages" })).toHaveCount(0);
+}
+
+test("reconnecting a focused chat preserves its unread completion until another click", async ({
+  page,
+  workspaces,
+}) => {
+  const gate = await installDaemonWebSocketGate(page);
+  await openAgentRoute(page, workspaces.subject);
+  await expect(page.getByText("Finish this turn.", { exact: true })).toBeVisible();
+  await workspaces.subject.client.sendAgentMessage(
+    workspaces.subject.agentId,
+    "Unread across reconnect.",
+  );
+  await workspaces.subject.client.waitForFinish(workspaces.subject.agentId, 20_000);
+  await expectStatus(page, workspaces.subject.workspaceId, "attention");
+  await reconnectWithoutInteracting(page, gate);
+  await expectStatus(page, workspaces.subject.workspaceId, "attention");
+  await page.getByText("Unread across reconnect.", { exact: true }).click();
+  await expectStatus(page, workspaces.subject.workspaceId, "done");
+});
+
+test("a cached read chat acknowledges a completion that arrived while the app was closed", async ({
+  page,
+  workspaces,
+}) => {
+  await openCompactWorkspace(page, workspaces.subject);
+  await expectStatus(page, workspaces.subject.workspaceId, "done");
+  await closeMobileAgentSidebar(page);
+  await reopenWorkspaceAfterBackgroundTurn(page, workspaces.subject);
+  await expectRestoredCompactChat(page);
+  await openMobileAgentSidebar(page);
+  await expectStatus(page, workspaces.subject.workspaceId, "done");
+});
diff --git a/packages/app/e2e/browser/sidebar-workspace.spec.ts b/packages/app/e2e/browser/sidebar-workspace.spec.ts
index d96f68580c..a307002c3b 100644
--- a/packages/app/e2e/browser/sidebar-workspace.spec.ts
+++ b/packages/app/e2e/browser/sidebar-workspace.spec.ts
@@ -6,6 +6,7 @@ import {
   closeMobileAgentSidebar,
   expectMobileAgentSidebarHidden,
   expectMobileAgentSidebarVisible,
+  expectOnlyWorkspaceHoverCardFor,
   expectWorkspaceHoverCardClosed,
   expectWorkspaceHoverCardOpen,
   expectWorkspaceHoverCardStaysOpen,
@@ -13,6 +14,8 @@ import {
   movePointerAwayFromWorkspaceHoverCard,
   openMobileAgentSidebar,
   pinWorkspaceFromSidebar,
+  scrollWorkspaceList,
+  sweepPointerAcrossWorkspaceRows,
 } from "../support/helpers/sidebar";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import { expectWorkspaceHeader } from "../support/helpers/workspace-ui";
@@ -79,6 +82,22 @@ async function openWorkspaceHoverCard(page: import("@playwright/test").Page, wor
   return hoverCard;
 }
 
+async function sortWorkspacesBySidebarOrder<T extends { workspaceId: string }>(
+  page: Page,
+  workspaces: T[],
+): Promise<T[]> {
+  const positioned = await Promise.all(
+    workspaces.map(async (workspace) => {
+      const bounds = await page
+        .getByTestId(getWorkspaceRowTestId(workspace.workspaceId))
+        .boundingBox();
+      if (!bounds) throw new Error(`Could not measure the row of ${workspace.workspaceId}`);
+      return { workspace, y: bounds.y };
+    }),
+  );
+  return positioned.sort((left, right) => left.y - right.y).map(({ workspace }) => workspace);
+}
+
 interface PaseoOwnedWorktree {
   projectName: string;
   workspaceId: string;
@@ -429,6 +448,38 @@ test.describe("Sidebar workspace list", () => {
     }
   });
 
+  test("scanning up the workspace rows leaves only the resting row's hover card open", async ({
+    page,
+  }) => {
+    const workspaces = await Promise.all(
+      [1, 2, 3, 4, 5].map((index) =>
+        seedWorkspace({
+          repoPrefix: `sidebar-hover-scan-${index}-`,
+          title: `Hover scan ${index}`,
+        }),
+      ),
+    );
+
+    try {
+      await gotoAppShell(page);
+      for (const workspace of workspaces) {
+        await waitForSidebarWorkspace(page, workspace.workspaceId);
+      }
+      const rowsTopToBottom = await sortWorkspacesBySidebarOrder(page, workspaces);
+      const top = rowsTopToBottom[0]!;
+
+      for (let scan = 0; scan < 3; scan += 1) {
+        await sweepPointerAcrossWorkspaceRows(
+          page,
+          rowsTopToBottom.map((workspace) => workspace.workspaceId).toReversed(),
+        );
+        await expectOnlyWorkspaceHoverCardFor(page, top.workspaceName);
+      }
+    } finally {
+      await Promise.all(workspaces.map((workspace) => workspace.cleanup()));
+    }
+  });
+
   test("workspace hover card follows keyboard focus on a row", async ({ page }) => {
     const workspace = await seedWorkspace({ repoPrefix: "sidebar-hover-keyboard-" });
 
@@ -582,6 +633,12 @@ test.describe("Half-screen desktop layout", () => {
       await page.getByTestId("menu-button").click();
       await expect(page.getByTestId("sidebar-global-new-workspace")).toBeVisible();
       await expect(sidebarScroll).toHaveJSProperty("scrollTop", scrollTop);
+
+      await movePointerAwayFromWorkspaceHoverCard(page);
+      await focusWorkspaceRowWithKeyboard(page, lastWorkspaceId);
+      await expectWorkspaceHoverCardOpen(page);
+      await scrollWorkspaceList(page);
+      await expectWorkspaceHoverCardClosed(page);
     } finally {
       await workspace.cleanup();
     }
@@ -645,6 +702,9 @@ test.describe("Half-screen desktop layout", () => {
           .locator('[data-testid^="workspace-pane-"]')
           .getByTestId("workspace-tabs-row")
           .filter({ visible: true }),
+      ).toHaveCount(0);
+      await expect(
+        page.getByTestId("workspace-tab-switcher-trigger").filter({ visible: true }),
       ).toHaveCount(1);
 
       await explorerToggle.click();
diff --git a/packages/app/e2e/browser/subagent-origin-pane.spec.ts b/packages/app/e2e/browser/subagent-origin-pane.spec.ts
index 545076ab06..8af88bd547 100644
--- a/packages/app/e2e/browser/subagent-origin-pane.spec.ts
+++ b/packages/app/e2e/browser/subagent-origin-pane.spec.ts
@@ -38,8 +38,12 @@ async function openParentInRightPane(page: Page, parentId: string, workspaceId:
   await expect(left).toBeVisible();
   await expect(right).toBeVisible();
   await expect(right).not.toHaveAttribute("data-testid", "workspace-pane-main");
+  // A later split can replace the parent pane's rail with compact chrome.
+  // Keep the pane identity instead of finding it again through that rail.
+  const rightPaneId = await right.getAttribute("data-testid");
+  expect(rightPaneId).not.toBeNull();
   await left.locator('[data-testid^="workspace-tab-draft_"]').click();
-  return { left, right };
+  return { left, right: page.getByTestId(rightPaneId!) };
 }
 
 test.beforeEach(async ({ page }) => {
diff --git a/packages/app/e2e/browser/terminal-find.spec.ts b/packages/app/e2e/browser/terminal-find.spec.ts
index 91e8e5826a..26a5b52063 100644
--- a/packages/app/e2e/browser/terminal-find.spec.ts
+++ b/packages/app/e2e/browser/terminal-find.spec.ts
@@ -1,3 +1,4 @@
+import { getServerId } from "../support/helpers/server-id";
 import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
 import { spawnSync } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
@@ -413,6 +414,8 @@ test("searches retained output without sending Find input to the shell", async (
 test("keeps terminal Find owned by retained tabs and the focused split pane", async ({
   page,
 }, testInfo) => {
+  // This journey selects tabs from the full rails in both split panes.
+  await page.setViewportSize({ width: 1600, height: 900 });
   const first = await harness.createTerminal({
     name: "First search",
     command: "bash",
@@ -487,3 +490,142 @@ test("keeps the shared Find controls usable in a compact dark browser", async ({
   await page.getByRole("button", { name: "Close Find" }).click();
   await expect(input(page)).toBeFocused();
 });
+
+// A phone browser installs xterm's document-level touch gesture listener too.
+// Keep this journey touch-enabled so it catches duplicate scroll handling.
+test.describe("terminal history with a finger", () => {
+  test.use({ isMobile: true, hasTouch: true, viewport: { width: 390, height: 844 } });
+
+  test("scrolls history once per finger drag", async ({ page }) => {
+    await openPhoneTerminalHistory(page);
+    await expectSingleFingerScroll(page, 24);
+    await expectSingleFingerScroll(page, 1);
+    await expectMouseWheelScrollsHistory(page);
+  });
+
+  for (const mode of ["alternate", "mouse"] as const) {
+    test(`preserves finger navigation in ${mode} input mode`, async ({ page }) => {
+      await openPhoneInputCapture(page, mode);
+      await expectFingerNavigationInput(page, mode);
+    });
+  }
+});
+
+async function expectFingerNavigationInput(page: Page, mode: "alternate" | "mouse") {
+  await dragTerminalWithFinger(page, 24, async () => {
+    const prefix = mode === "alternate" ? "TOUCH_BYTES:1b4f41" : "TOUCH_BYTES:1b5b3c3634";
+    await expect.poll(() => getTerminalBufferText(page)).toContain(prefix);
+  });
+}
+
+async function openPhoneTerminalHistory(page: Page) {
+  await harness.createTerminal({
+    name: "Finger scroll history",
+    command: "bash",
+    args: [
+      "--noprofile",
+      "--norc",
+      "-c",
+      "for i in $(seq 1 150); do echo HISTORY_$i; done; exec sleep 300",
+    ],
+  });
+  await openPhoneTerminal(page);
+  await expect.poll(() => getTerminalBufferText(page)).toContain("HISTORY_150");
+}
+
+async function openPhoneInputCapture(page: Page, mode: "alternate" | "mouse") {
+  const escapes = mode === "alternate" ? "\x1b[?1049h\x1b[?1h" : "\x1b[?1000h\x1b[?1006h";
+  await harness.createTerminal({
+    name: "Touch application input",
+    command: process.execPath,
+    args: [
+      "-e",
+      `
+      process.stdin.setRawMode(true);
+      process.stdin.once("data", () => {
+        process.stdin.on("data", chunk => {
+          process.stdout.write("\\r\\nTOUCH_BYTES:" + chunk.toString("hex") + ":END\\r\\n");
+        });
+        process.stdout.write(${JSON.stringify(escapes)} + "TOUCH_INPUT_READY\\r\\n");
+      });
+      process.stdout.write("TOUCH_START_READY\\r\\n");
+    `,
+    ],
+  });
+  await openPhoneTerminal(page);
+  await expect.poll(() => getTerminalBufferText(page)).toContain("TOUCH_START_READY");
+  await input(page).press("x");
+  await expect.poll(() => getTerminalBufferText(page)).toContain("TOUCH_INPUT_READY");
+  await expect
+    .poll(() => page.evaluate(() => window.__paseoTerminal!.buffer.active.type))
+    .toBe(mode === "alternate" ? "alternate" : "normal");
+  await expect
+    .poll(() => page.evaluate(() => window.__paseoTerminal!.modes.mouseTrackingMode))
+    .toBe(mode === "mouse" ? "vt200" : "none");
+}
+
+async function openPhoneTerminal(page: Page) {
+  await page.goto("/");
+  await page.getByRole("button", { name: "Open menu", exact: true }).click();
+  await page.getByTestId(`sidebar-workspace-row-${getServerId()}:${harness.workspaceId}`).click();
+  await expect(page.getByRole("textbox", { name: "Terminal input" })).toBeVisible();
+  await expect(page.getByTestId("terminal-surface").filter({ visible: true })).toBeVisible();
+}
+
+async function expectMouseWheelScrollsHistory(page: Page) {
+  const beforeWheel = (await viewport(page))!;
+  await page.mouse.move(200, 300);
+  await page.mouse.wheel(0, -120);
+  await expect.poll(() => viewport(page)).toBeLessThan(beforeWheel);
+}
+
+async function expectSingleFingerScroll(page: Page, moves: number) {
+  await dragTerminalWithFinger(page, moves, async ({ lineHeight, before }) => {
+    await expect.poll(async () => before - (await viewport(page))!).toBeGreaterThan(0);
+    const moved = before - (await viewport(page))!;
+    await test.info().attach("finger-scroll", {
+      body: JSON.stringify({ moves, distancePx: 120, lineHeight, rowsMoved: moved }),
+      contentType: "application/json",
+    });
+    expect(moved, "one gesture must not scroll twice its physical distance").toBeLessThanOrEqual(
+      Math.ceil(120 / lineHeight),
+    );
+  });
+}
+
+async function dragTerminalWithFinger(
+  page: Page,
+  moves: number,
+  inspect: (state: { lineHeight: number; before: number }) => Promise<void>,
+) {
+  await test.step(`Drag history with ${moves} touch moves`, async () => {
+    const screen = page
+      .getByTestId("terminal-surface")
+      .filter({ visible: true })
+      .locator(".xterm-screen");
+    const box = await screen.boundingBox();
+    if (!box) throw new Error("Terminal screen is not visible");
+    const rows = await page.evaluate(() => window.__paseoTerminal!.rows);
+    const lineHeight = box.height / rows;
+    const before = (await viewport(page))!;
+    const session = await page.context().newCDPSession(page);
+    try {
+      const start = { x: box.x + box.width / 2, y: box.y + box.height / 3 };
+      await session.send("Input.dispatchTouchEvent", {
+        type: "touchStart",
+        touchPoints: [{ ...start, id: 1 }],
+      });
+      for (let step = 1; step <= moves; step++) {
+        await session.send("Input.dispatchTouchEvent", {
+          type: "touchMove",
+          touchPoints: [{ x: start.x, y: start.y + (120 * step) / moves, id: 1 }],
+        });
+      }
+      // Check before lifting the finger to exclude inertial scrolling.
+      await inspect({ lineHeight, before });
+    } finally {
+      await session.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+      await session.detach();
+    }
+  });
+}
diff --git a/packages/app/e2e/browser/terminal-protocol-query.spec.ts b/packages/app/e2e/browser/terminal-protocol-query.spec.ts
index d5a0071189..4b2fc06d41 100644
--- a/packages/app/e2e/browser/terminal-protocol-query.spec.ts
+++ b/packages/app/e2e/browser/terminal-protocol-query.spec.ts
@@ -45,6 +45,11 @@ process.stdin.on("data", (chunk) => {
   for (;;) {
     const paste = /\x1b\[200~([^]*?)\x1b\[201~/.exec(buffer);
     if (!paste) break;
+    const pasted = JSON.stringify(paste[1]).replace(
+      /\s/g,
+      (space) => "\\u" + space.charCodeAt(0).toString(16).padStart(4, "0"),
+    );
+    process.stdout.write("PASTED:" + pasted + "\r\n");
     for (const [, path] of paste[1].matchAll(/'([^']*)'/g)) {
       const digest = crypto.createHash("sha256").update(fs.readFileSync(path)).digest("hex");
       const location = /[\\/]uploads[\\/]upload_/.test(path) ? "upload" : "local";
@@ -202,6 +207,21 @@ test.describe("Terminal protocol queries", () => {
     await expect.poll(() => terminalOutput(terminalId), { timeout: 10_000 }).toContain(text);
   }
 
+  // Every bracketed paste body the receiver consumed, in order and joined: what a
+  // shell would read as one command line.
+  async function pastedText(terminalId: string): Promise<string> {
+    const output = await terminalOutput(terminalId);
+    return [...output.matchAll(/PASTED:("(?:[^"\\]|\\.)*")/g)]
+      .map(([, json]) => JSON.parse(json) as string)
+      .join("");
+  }
+
+  // Exactly one ASCII space after each quoted path and nothing else between them,
+  // so the paths stay separate shell words.
+  async function expectSeparatePastedPaths(terminalId: string): Promise<void> {
+    await expect.poll(() => pastedText(terminalId)).toMatch(/^'[^']+' '[^']+' $/);
+  }
+
   test("pastes images from two panes into their own terminals as uploaded host files", async ({
     page,
   }) => {
@@ -238,6 +258,23 @@ test.describe("Terminal protocol queries", () => {
 
       await expectTerminalOutput(terminal.id, fileRead(pngBytes(3), "upload"));
       await expectTerminalOutput(terminal.id, fileRead(Buffer.from("remote notes"), "upload"));
+      await expectSeparatePastedPaths(terminal.id);
+    } finally {
+      await harness.killTerminal(terminal.id);
+    }
+  });
+
+  test("keeps the paths of two consecutive drops to another machine apart", async ({ page }) => {
+    const terminal = await openFileReceiver(page, "file-drop-remote-twice");
+    const first = { name: "first.png", type: "image/png", bytes: pngBytes(10) };
+    const second = { name: "second.txt", type: "text/plain", bytes: Buffer.from("second drop") };
+    try {
+      await dropFiles(page, [first]);
+      await expectTerminalOutput(terminal.id, fileRead(first.bytes, "upload"));
+      await dropFiles(page, [second]);
+      await expectTerminalOutput(terminal.id, fileRead(second.bytes, "upload"));
+
+      await expectSeparatePastedPaths(terminal.id);
     } finally {
       await harness.killTerminal(terminal.id);
     }
diff --git a/packages/app/e2e/browser/turn-collapse.spec.ts b/packages/app/e2e/browser/turn-collapse.spec.ts
index d990e33009..1ae180fb8e 100644
--- a/packages/app/e2e/browser/turn-collapse.spec.ts
+++ b/packages/app/e2e/browser/turn-collapse.spec.ts
@@ -2,12 +2,14 @@ import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import path from "node:path";
 import {
   holdOlderHistoryPages,
+  scrollTimelineRowIntoView,
   userScrollsTimelineToHistoryStart,
 } from "../support/helpers/timeline-pagination";
 import { getActiveTabTestId } from "../support/helpers/launcher";
 import type { Page, Locator } from "@playwright/test";
 import { test, expect } from "../support/fixtures";
 import { expectComposerVisible } from "../support/helpers/composer";
+import { withDirectoryPlugin } from "../support/helpers/plugin-timeline";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 
 test.use({
@@ -49,15 +51,36 @@ async function seedAnsweredAgent(title: string) {
 }
 
 /** Chat rows between the latest turn's summary line and its reply, in document order. */
-async function rowsBetweenLatestSummaryAndReply(page: Page): Promise<number> {
-  return page.evaluate(() => {
+async function rowsBetweenLatestSummaryAndReply(
+  page: Page,
+  replyTestId = "assistant-message",
+): Promise<number> {
+  return page.evaluate((testId) => {
     const rows = [...document.querySelectorAll("[data-message-id]")];
     const summaryRow = rows.findLastIndex((row) => row.querySelector("[data-testid=turn-summary]"));
-    const replyRow = rows.findLastIndex((row) =>
-      row.querySelector("[data-testid=assistant-message]"),
-    );
+    const replyRow = rows.findLastIndex((row) => row.querySelector(`[data-testid="${testId}"]`));
     return replyRow - summaryRow - 1;
-  });
+  }, replyTestId);
+}
+
+/** The latest turn's summary line is a chat row of its own, sitting apart from its prompt. */
+async function expectSummaryLineSitsApartFromPrompt(page: Page) {
+  const summaryRow = () =>
+    page.evaluate(() => {
+      const latest = (testId: string) =>
+        [...document.querySelectorAll(`[data-testid="${testId}"]`)].at(-1)!;
+      const summary = latest("turn-summary");
+      const row = summary.closest("[data-message-id]")!;
+      return {
+        sharesRowWithPrompt: row.querySelector("[data-testid=user-message]") !== null,
+        gapBelowPrompt: Math.round(
+          summary.getBoundingClientRect().top -
+            latest("user-message").getBoundingClientRect().bottom,
+        ),
+      };
+    });
+  await expect.poll(summaryRow).toMatchObject({ sharesRowWithPrompt: false });
+  expect((await summaryRow()).gapBelowPrompt).toBeGreaterThan(0);
 }
 
 async function groupedToolsInsideLatestTurn(page: Page): Promise<string[]> {
@@ -125,6 +148,67 @@ async function expandAndCollapseLongPrompt(page: Page) {
 }
 
 test.describe("Turn collapse", () => {
+  test("folds work before a plugin-rendered reply and reopens it", async ({ page }, info) => {
+    test.setTimeout(120_000);
+    await useChatDisplay(page, "collapseTurns");
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "plugin-reply-fold-",
+      title: "Plugin reply folding",
+      model: "ten-second-stream",
+      initialPrompt: "Make the fix and run the burst script.",
+    });
+    try {
+      await agent.client.waitForFinish(agent.agentId, 30_000);
+      await withDirectoryPlugin({
+        pluginId: "reply-fold-e2e",
+        source: `import React from "react";
+import { Text } from "react-native";
+import { z } from "zod";
+
+export default function contribute(client) {
+  client.addTimelineTransformer({
+    id: "reply", query: { itemType: "assistant_message" },
+    transform({ item, phase }) {
+      if (phase === "streaming") return undefined;
+      return { items: [{ type: "plugin", kind: "reply", version: 1, data: { text: item.text } }] };
+    },
+  });
+  client.addTimelineRenderer({
+    kind: "reply", version: 1, schema: z.object({ text: z.string() }),
+    Component: ({ item }) => <Text testID="plugin-reply">{item.data.text}</Text>,
+  });
+  return () => {};
+}`,
+        run: async () => {
+          await page.setViewportSize({ width: 1280, height: 1000 });
+          await openAgentRoute(page, agent);
+          await expectComposerVisible(page);
+          for (const width of [1280, 390]) {
+            await page.setViewportSize({ width, height: 1000 });
+            const summary = page.getByTestId("turn-summary").last().getByRole("button");
+            const reply = page.getByTestId("plugin-reply").last();
+            await expect(summary).toBeVisible();
+            await expect(reply).toContainText("(end of synthetic stream)");
+            await expect.poll(() => rowsBetweenLatestSummaryAndReply(page, "plugin-reply")).toBe(0);
+            await page.screenshot({ path: info.outputPath(`plugin-reply-folded-${width}.png`) });
+            await summary.click();
+            await expect
+              .poll(() => rowsBetweenLatestSummaryAndReply(page, "plugin-reply"))
+              .toBeGreaterThan(0);
+            await expect(reply).toContainText("(end of synthetic stream)");
+            await summary.click();
+            await expect.poll(() => rowsBetweenLatestSummaryAndReply(page, "plugin-reply")).toBe(0);
+          }
+          await page.reload();
+          await expect(page.getByTestId("turn-summary").last()).toBeVisible();
+          await expect.poll(() => rowsBetweenLatestSummaryAndReply(page, "plugin-reply")).toBe(0);
+        },
+      });
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
   test("folds each answered turn behind a summary line that opens it", async ({ page }) => {
     test.setTimeout(120_000);
     await page.setViewportSize({ width: 1280, height: 1000 });
@@ -144,6 +228,7 @@ test.describe("Turn collapse", () => {
         /\(end of synthetic stream\)$/,
       );
       await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
+      await expectSummaryLineSitsApartFromPrompt(page);
 
       await summary.click();
       await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBeGreaterThan(0);
@@ -343,7 +428,6 @@ test("opening a turn keeps the received message above it clipped on every frame"
       .getByTestId("user-message")
       .filter({ has: page.getByRole("button", { name: "Sent by Reviewer", exact: true }) });
     await expect(bubble.getByRole("button", { name: "Show more", exact: true })).toBeVisible();
-    await bubble.scrollIntoViewIfNeeded();
 
     await watchReceivedMessagePreview(page, "Sent by Reviewer");
     await page
@@ -407,34 +491,87 @@ async function seedWholeTurnHistory() {
   return agent;
 }
 
-test("loads complete long turns and preserves expansion while revealing older history", async ({
-  page,
-}) => {
+async function expectInitialFillIsConcealed(page: Page) {
+  await expect(page.getByTestId("agent-initial-fill")).toBeVisible();
+  await expect(page.getByTestId("agent-chat-scroll")).toHaveCSS("opacity", "0");
+}
+
+async function expectFilledChatAtBottom(page: Page) {
+  await expect(page.getByTestId("agent-initial-fill")).toBeHidden();
+  const chat = page.getByTestId("agent-chat-scroll");
+  await expect(chat).toHaveCSS("opacity", "1");
+  await expect
+    .poll(() =>
+      chat.evaluate((element) => ({
+        hasOverflow: element.scrollHeight > element.clientHeight,
+        atBottom: Math.abs(element.scrollHeight - element.clientHeight - element.scrollTop) <= 2,
+      })),
+    )
+    .toEqual({ hasOverflow: true, atBottom: true });
+}
+
+test("fills collapsed history before revealing a fresh chat", async ({ page }) => {
   test.setTimeout(120_000);
+  await page.setViewportSize({ width: 1280, height: 1000 });
   await useChatDisplay(page, "collapseTurns");
   const agent = await seedWholeTurnHistory();
   try {
     const history = await holdOlderHistoryPages(page, agent);
     await openAgentRoute(page, agent);
+    await history.expectRequestedPages(1);
+    await expectInitialFillIsConcealed(page);
+    history.releasePage(1);
+    await history.expectRequestedPages(2);
+    await expectInitialFillIsConcealed(page);
+    history.releasePage(2);
+    await expectFilledChatAtBottom(page);
+    await page.setViewportSize({ width: 1280, height: 8000 });
+    await history.expectRequestedPages(3);
+    await expect(page.getByTestId("agent-chat-scroll")).toHaveCSS("opacity", "1");
+    await expect(page.getByTestId("agent-initial-fill")).toBeHidden();
+    history.releasePage(3);
+    await history.expectSettledWithRequestedPages(3);
+    history.expectNoRepeatedEntries();
+  } finally {
+    await agent.cleanup();
+  }
+});
+
+test("loads complete long turns and preserves expansion while revealing older history", async ({
+  page,
+}) => {
+  test.setTimeout(120_000);
+  await page.setViewportSize({ width: 1280, height: 1000 });
+  await useChatDisplay(page, "collapseTurns");
+  const agent = await seedWholeTurnHistory();
+  try {
+    const history = await holdOlderHistoryPages(page, agent);
+    await openAgentRoute(page, agent);
+    await history.expectRequestedPages(1);
+    history.releasePage(1);
+    await history.expectRequestedPages(2);
+    history.releasePage(2);
+    await expectFilledChatAtBottom(page);
     await expectComposerVisible(page);
     const latest = page
       .getByTestId("turn-summary")
       .getByRole("button", { name: "Ran 120 commands", exact: true });
     await expect(latest).toBeVisible();
-    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
-    await latest.click();
-    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(120);
-    await userScrollsTimelineToHistoryStart(page);
-    await history.expectRequestedPages(1);
-    history.releasePage(1);
     await expect(
       page
         .getByTestId("turn-summary")
         .getByRole("button", { name: "Ran 60 commands", exact: true }),
     ).toBeVisible();
+    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
+    await latest.click();
+    await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(120);
+    await userScrollsTimelineToHistoryStart(page);
+    await history.expectRequestedPages(3);
+    history.releasePage(3);
+    await page.getByTestId("scroll-to-bottom-button").click();
     await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(120);
     history.expectNoRepeatedEntries();
-    await latest.scrollIntoViewIfNeeded();
+    await scrollTimelineRowIntoView(page, latest);
     await latest.click();
     await expect.poll(() => rowsBetweenLatestSummaryAndReply(page)).toBe(0);
   } finally {
@@ -529,6 +666,7 @@ async function expectThinkingPresentation(page: Page, autoExpandReasoning: boole
       .last();
     await expect(group).toContainText(/read 1 file/i);
     await expect(group.getByRole("button").first()).not.toContainText(/thought/i);
+    await scrollTimelineRowIntoView(page, group);
     await group.getByRole("button").first().click();
     // Expand thinking is off: the group opens its rows, but the thought row stays closed
     // until the reader opens it.
diff --git a/packages/app/e2e/browser/usage-sidebar-item.spec.ts b/packages/app/e2e/browser/usage-sidebar-item.spec.ts
index 9151403904..8d206f35e8 100644
--- a/packages/app/e2e/browser/usage-sidebar-item.spec.ts
+++ b/packages/app/e2e/browser/usage-sidebar-item.spec.ts
@@ -8,7 +8,7 @@ import {
   openProjectViaDaemon,
 } from "../support/helpers/new-workspace";
 import { getServerId } from "../support/helpers/server-id";
-import { openSettingsHostSection } from "../support/helpers/settings";
+import { openCompactSettings, openSettingsHostSection } from "../support/helpers/settings";
 import {
   expectFooterItemSetting,
   expectFooterSeparator,
@@ -42,6 +42,7 @@ import {
 import { seedSidebarFooterPreferences } from "../support/helpers/sidebar-nav-settings";
 import { waitForSettledPosition } from "../support/helpers/sheet-layout";
 import { createTempGitRepo } from "../support/helpers/workspace";
+import { buildOpenProjectRoute } from "@/utils/host-routes";
 
 const WIDE = { width: 1440, height: 900 };
 const COMPACT = { width: 390, height: 844 };
@@ -70,7 +71,112 @@ async function footerClip(page: Page) {
   return (await page.locator('[data-testid="sidebar-footer"]:visible').boundingBox())!;
 }
 
+async function setPageVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
+  await page.evaluate((state) => {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      get: () => state === "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+  }, visibility);
+}
+
 test.describe("Usage item", () => {
+  test("visible summary refreshes every five minutes without opening Usage", async ({ page }) => {
+    let usedPct = 31;
+    const usage = await installUsageReportsFixture(page, {
+      lists: [
+        () => [
+          {
+            ...claudeAndCodexReports()[0]!,
+            report: {
+              status: "available",
+              windows: [
+                { id: "five_hour", label: "Session", shortLabel: "5h", summary: true, usedPct },
+              ],
+            },
+          },
+        ],
+      ],
+    });
+    await page.clock.install();
+    await page.setViewportSize(WIDE);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await expectPinnedUsage(page, ["31% 5h"]);
+    const startingUrl = page.url();
+    await qaScreenshot(page, "usage-auto-refresh-initial", { kind: "footer" });
+    const requestsBeforeRefresh = usage.listRequests();
+
+    usedPct = 42;
+    await page.clock.fastForward(5 * 60_000);
+    await qaScreenshot(page, "usage-auto-refresh-after-interval", { kind: "footer" });
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+    await expect(page).toHaveURL(startingUrl);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeRefresh,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await setPageVisibility(page, "hidden");
+    const requestsBeforeBackgrounding = usage.listRequests();
+    usedPct = 47;
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeBackgrounding);
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await setPageVisibility(page, "visible");
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeBackgrounding,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await page.setViewportSize(COMPACT);
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeHiding = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeHiding);
+
+    await openCompactSidebar(page);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    await expect(page.getByTestId("agent-list-backdrop")).toBeVisible();
+    usedPct = 53;
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["53% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+
+    await page.setViewportSize(WIDE);
+    await openSidebarNavSettings(page);
+    await setFooterItemVisible(page, "usage", false);
+    await leaveSettings(page);
+    await expectNoUsageItem(page);
+    const requestsBeforeDisabling = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeDisabling);
+  });
+
+  test("Usage settings do not poll reports while the sidebar is inactive", async ({ page }) => {
+    const usage = await installUsageReportsFixture(page, {
+      lists: [() => claudeAndCodexReports()],
+    });
+    await page.clock.install();
+    await page.setViewportSize(COMPACT);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await openCompactSettings(page, buildOpenProjectRoute());
+    await openSettingsHostSection(page, getServerId(), "usage");
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeWaiting = usage.listRequests();
+
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeWaiting);
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+  });
+
   test("both compact footer entry points open Usage as a sheet", async ({ page }) => {
     await page.setViewportSize(COMPACT);
     await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });
diff --git a/packages/app/e2e/browser/viewed-agent-timelines.spec.ts b/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
index 5ef70cca61..934a48d264 100644
--- a/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
+++ b/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
@@ -357,6 +357,8 @@ test.describe("Viewed agent timelines", () => {
   });
 
   test("two visible split chats both stay current", async ({ page }) => {
+    // Keep both split panes wide enough for the tab-rail interactions below.
+    await page.setViewportSize({ width: 1600, height: 900 });
     const scenario = await seedViewedTimelineScenario();
     try {
       await enableMoveTabShortcut(page);
diff --git a/packages/app/e2e/browser/workspace-archive-undo.spec.ts b/packages/app/e2e/browser/workspace-archive-undo.spec.ts
new file mode 100644
index 0000000000..9f9567b75a
--- /dev/null
+++ b/packages/app/e2e/browser/workspace-archive-undo.spec.ts
@@ -0,0 +1,273 @@
+import type { Page } from "@playwright/test";
+import { expect, test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  archiveWorkspaceFromDaemon,
+  connectNewWorkspaceDaemonClient,
+  createWorktreeViaDaemon,
+  openProjectViaDaemon,
+} from "../support/helpers/new-workspace";
+import { getServerId } from "../support/helpers/server-id";
+import { expectWorkspaceAbsentFromSidebar } from "../support/helpers/sidebar";
+import { createMockIdleAgent, openWorkspaceWithAgents } from "../support/helpers/archive-tab";
+import { connectSeedClient } from "../support/helpers/seed-client";
+import { createTempGitRepo } from "../support/helpers/workspace";
+import { getWorkspaceTabTestIds } from "../support/helpers/workspace-tabs";
+import {
+  archiveFromRowButton,
+  createGatedTeardown,
+  expectDirectoryPresence,
+  expectHostWorkspaceSettledActive,
+  holdNextArchiveRequest,
+  outlastUndoWindow,
+  pressArchiveShortcut,
+  pressUndoShortcut,
+  resizeSidebarToMinimum,
+  rowArchiveButton,
+  rowKebab,
+  undoButton,
+  workspaceRow,
+  workspaceTitleWidth,
+} from "../support/helpers/workspace-archive-undo";
+import {
+  waitForSidebarHydration,
+  waitForWorkspaceInSidebar,
+} from "../support/helpers/workspace-ui";
+
+test.describe("Workspace archive undo", () => {
+  let client: Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
+  let tempRepo: { path: string; cleanup: () => Promise<void> };
+  const worktreeDirectories = new Set<string>();
+
+  test.describe.configure({ timeout: 120_000 });
+
+  test.beforeEach(async () => {
+    client = await connectNewWorkspaceDaemonClient();
+    tempRepo = await createTempGitRepo("archive-undo-");
+  });
+
+  test.afterEach(async () => {
+    for (const directory of worktreeDirectories) {
+      await archiveWorkspaceFromDaemon(client, directory).catch(() => undefined);
+    }
+    worktreeDirectories.clear();
+    await client?.close().catch(() => undefined);
+    await tempRepo?.cleanup().catch(() => undefined);
+  });
+
+  async function seedWorktree(page: Page, slug: string) {
+    await openProjectViaDaemon(client, tempRepo.path);
+    const worktree = await createWorktreeViaDaemon(client, {
+      cwd: tempRepo.path,
+      slug: `${slug}-${Date.now()}`,
+    });
+    worktreeDirectories.add(worktree.workspaceDirectory);
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await waitForWorkspaceInSidebar(page, {
+      serverId: getServerId(),
+      workspaceId: worktree.workspaceId,
+    });
+    return worktree;
+  }
+
+  test("the hover archive button overlays the title instead of narrowing it", async ({ page }) => {
+    const worktree = await seedWorktree(page, "archive-button-overlay");
+
+    await page.mouse.move(0, 0);
+    await expect(rowArchiveButton(page, worktree.workspaceId)).toHaveCount(0);
+    const restingWidth = await workspaceTitleWidth(page, worktree.workspaceId);
+
+    await workspaceRow(page, worktree.workspaceId).hover();
+    await expect(rowArchiveButton(page, worktree.workspaceId)).toBeVisible();
+    await expect(page.getByTestId("sidebar-workspace-trailing-scrim")).toBeVisible();
+    expect(await workspaceTitleWidth(page, worktree.workspaceId)).toBe(restingWidth);
+
+    const [buttonBox, kebabBox] = await Promise.all([
+      rowArchiveButton(page, worktree.workspaceId).boundingBox(),
+      rowKebab(page, worktree.workspaceId).boundingBox(),
+    ]);
+    if (!buttonBox || !kebabBox) throw new Error("Row actions are not laid out");
+    expect(kebabBox.x - (buttonBox.x + buttonBox.width)).toBeGreaterThanOrEqual(8);
+  });
+
+  test("the archived toast sits over the sidebar above its footer, and only Undo presses", async ({
+    page,
+  }) => {
+    const worktree = await seedWorktree(page, "archive-toast-sidebar");
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+
+    const [toastBox, footerBox] = await Promise.all([
+      page.getByTestId("workspace-archived-toast").boundingBox(),
+      page.getByTestId("sidebar-footer").boundingBox(),
+    ]);
+    if (!toastBox || !footerBox) throw new Error("Toast or footer is not laid out");
+    expect(toastBox.x).toBeGreaterThanOrEqual(footerBox.x);
+    expect(toastBox.x + toastBox.width).toBeLessThanOrEqual(footerBox.x + footerBox.width);
+    expect(toastBox.y + toastBox.height).toBeLessThanOrEqual(footerBox.y);
+    expect(footerBox.y - (toastBox.y + toastBox.height)).toBeLessThanOrEqual(16);
+
+    await expect(page.getByTestId("app-toast-message")).toHaveCSS("cursor", "auto");
+    await expect(undoButton(page)).toHaveCSS("cursor", "pointer");
+
+    const [labelBox, shortcutBox] = await Promise.all([
+      undoButton(page).getByText("Undo", { exact: true }).boundingBox(),
+      undoButton(page).getByText(/Z$/).boundingBox(),
+    ]);
+    if (!labelBox || !shortcutBox) throw new Error("Undo button is not laid out");
+    expect(shortcutBox.x - (labelBox.x + labelBox.width)).toBeLessThanOrEqual(8.5);
+  });
+
+  test("an archive that fails after the sidebar was replaced still shows its error", async ({
+    page,
+  }) => {
+    const archive = await holdNextArchiveRequest(page);
+    const worktree = await seedWorktree(page, "archive-late-failure");
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+    await archive.waitForHeld();
+    // Crossing the compact breakpoint swaps the sidebar, unmounting the toast's host.
+    await page.setViewportSize({ width: 400, height: 720 });
+    await expect(undoButton(page)).toHaveCount(0);
+
+    archive.releaseForUnknownWorkspace("workspace-the-daemon-never-had");
+
+    await expect(page.getByTestId("app-toast-message")).toHaveText(
+      "Workspace not found: workspace-the-daemon-never-had",
+    );
+  });
+
+  test("the archived toast keeps Undo inside the card at the narrowest sidebar", async ({
+    page,
+  }) => {
+    const worktree = await seedWorktree(page, "archive-toast-narrow");
+    await resizeSidebarToMinimum(page);
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+
+    const [toastBox, undoBox] = await Promise.all([
+      page.getByTestId("workspace-archived-toast").boundingBox(),
+      undoButton(page).boundingBox(),
+    ]);
+    if (!toastBox || !undoBox) throw new Error("Toast is not laid out");
+    expect(undoBox.x + undoBox.width).toBeLessThanOrEqual(toastBox.x + toastBox.width);
+    expect(undoBox.y + undoBox.height).toBeLessThanOrEqual(toastBox.y + toastBox.height);
+  });
+
+  test("archiving by shortcut with the sidebar collapsed shows the toast over the app", async ({
+    page,
+  }) => {
+    const worktree = await seedWorktree(page, "archive-toast-collapsed");
+    await workspaceRow(page, worktree.workspaceId).click();
+    await page.keyboard.press("ControlOrMeta+b");
+    await expect(workspaceRow(page, worktree.workspaceId)).not.toBeInViewport();
+
+    page.once("dialog", (dialog) => void dialog.accept());
+    await pressArchiveShortcut(page);
+
+    const toast = page.getByTestId("workspace-archived-toast");
+    await expect(toast).toBeInViewport();
+    const toastBox = await toast.boundingBox();
+    if (!toastBox) throw new Error("Toast is not laid out");
+    expect(toastBox.y).toBeLessThan(page.viewportSize()!.height / 2);
+  });
+
+  test("Cmd/Ctrl+Z right after archiving keeps the worktree", async ({ page }) => {
+    const worktree = await seedWorktree(page, "archive-undo-shortcut");
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+    await pressUndoShortcut(page);
+
+    await expect(workspaceRow(page, worktree.workspaceId)).toBeVisible();
+    await expect(undoButton(page)).toHaveCount(0);
+    await expectHostWorkspaceSettledActive(client, worktree.workspaceId);
+    // Once the host settled, any remove the canceled archive sent has already arrived.
+    await expect(workspaceRow(page, worktree.workspaceId)).toBeVisible();
+    await expectDirectoryPresence(worktree.workspaceDirectory, true);
+  });
+
+  test("Undo after the worktree was removed recreates it", async ({ page }) => {
+    const worktree = await seedWorktree(page, "archive-undo-recreate");
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+    // Hovering the toast holds it, and with it the undo, open while the archive finishes.
+    await undoButton(page).hover();
+    await expectDirectoryPresence(worktree.workspaceDirectory, false);
+    await undoButton(page).click();
+
+    await expect(workspaceRow(page, worktree.workspaceId)).toBeVisible({ timeout: 30_000 });
+    await expectDirectoryPresence(worktree.workspaceDirectory, true);
+    await expectHostWorkspaceSettledActive(client, worktree.workspaceId);
+  });
+
+  test("hovering Undo keeps the toast open past its deadline, and its close ends the undo", async ({
+    page,
+  }) => {
+    await page.clock.install({ time: Date.now() });
+    const worktree = await seedWorktree(page, "archive-undo-hold");
+
+    await archiveFromRowButton(page, worktree.workspaceId);
+    await page.getByTestId("workspace-archived-toast").hover({ position: { x: 8, y: 8 } });
+    await undoButton(page).hover();
+    await outlastUndoWindow(page);
+    await expect(undoButton(page)).toBeVisible();
+
+    await page.mouse.move(0, 0);
+    await outlastUndoWindow(page);
+    await expect(undoButton(page)).toHaveCount(0);
+
+    // The toast took the undo with it.
+    await pressUndoShortcut(page);
+    await expectWorkspaceAbsentFromSidebar(page, worktree.workspaceId);
+  });
+
+  test("opening the workspace while its undo is still running keeps its tabs", async ({ page }) => {
+    const teardown = createGatedTeardown();
+    const repo = await createTempGitRepo("archive-undo-tabs-", {
+      paseoConfig: teardown.paseoConfig,
+    });
+    const seedClient = await connectSeedClient();
+    try {
+      await openProjectViaDaemon(client, repo.path);
+      const worktree = await createWorktreeViaDaemon(client, {
+        cwd: repo.path,
+        slug: `archive-undo-tabs-${Date.now()}`,
+      });
+      worktreeDirectories.add(worktree.workspaceDirectory);
+      const target = { cwd: worktree.workspaceDirectory, workspaceId: worktree.workspaceId };
+      const agents = [
+        await createMockIdleAgent(seedClient, { ...target, title: "first" }),
+        await createMockIdleAgent(seedClient, { ...target, title: "second" }),
+      ] as const;
+      await openWorkspaceWithAgents(page, [agents[0], agents[1]]);
+      const tabsBefore = await getWorkspaceTabTestIds(page);
+
+      await archiveFromRowButton(page, worktree.workspaceId);
+      // The archive has taken its agents down and now parks in teardown.
+      await teardown.expectStarted();
+      await undoButton(page).click();
+      await workspaceRow(page, worktree.workspaceId).click();
+
+      for (const agent of agents) {
+        await expect(page.getByTestId(`workspace-tab-agent_${agent.id}`).first()).toBeVisible();
+      }
+      teardown.release();
+      await expectHostWorkspaceSettledActive(client, worktree.workspaceId);
+      await expect.poll(() => getWorkspaceTabTestIds(page)).toEqual(tabsBefore);
+    } finally {
+      teardown.release();
+      await seedClient.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    }
+  });
+
+  test("Cmd/Ctrl+Z without an archive to undo leaves the sidebar alone", async ({ page }) => {
+    const worktree = await seedWorktree(page, "archive-undo-none");
+
+    await pressUndoShortcut(page);
+
+    await expect(undoButton(page)).toHaveCount(0);
+    await expect(workspaceRow(page, worktree.workspaceId)).toBeVisible();
+  });
+});
diff --git a/packages/app/e2e/browser/workspace-focus-mode.spec.ts b/packages/app/e2e/browser/workspace-focus-mode.spec.ts
index e152b4defe..2929c2d093 100644
--- a/packages/app/e2e/browser/workspace-focus-mode.spec.ts
+++ b/packages/app/e2e/browser/workspace-focus-mode.spec.ts
@@ -101,3 +101,20 @@ test("focus mode only applies to the active workspace screen", async ({ page, wi
   await expect(exitFocusMode).toHaveCount(0);
   await expect(settingsButton).toBeVisible();
 });
+
+async function exitFocusModeFromCompactHeader(page: Page) {
+  await page.setViewportSize({ width: 400, height: 844 });
+  await page.getByTestId("workspace-header-menu-trigger").click();
+  await page.getByRole("menuitem", { name: "Exit focus mode", exact: true }).click();
+  await page.setViewportSize({ width: 1280, height: 900 });
+}
+
+test("compact workspace menu keeps focus mode exit reachable", async ({ page, withWorkspace }) => {
+  const workspace = await withWorkspace({ prefix: "compact-focus-exit-" });
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await workspace.navigateTo();
+  await enterFocusMode(page);
+  await exitFocusModeFromCompactHeader(page);
+  await expect(exitFocusModeButton(page)).toHaveCount(0);
+  await expect(page.getByTestId("sidebar-global-new-workspace")).toBeVisible();
+});
diff --git a/packages/app/e2e/browser/workspace-pane-remount.spec.ts b/packages/app/e2e/browser/workspace-pane-remount.spec.ts
index 201b6e3ccf..c259dc8af2 100644
--- a/packages/app/e2e/browser/workspace-pane-remount.spec.ts
+++ b/packages/app/e2e/browser/workspace-pane-remount.spec.ts
@@ -52,6 +52,8 @@ async function waitForWorkspaceRoute(page: Page, route: string) {
 test.describe("Workspace pane mounting", () => {
   test("workspace navigation keeps the existing agent composer mounted", async ({ page }) => {
     test.setTimeout(90_000);
+    // Keep both split panes wide enough for the tab-rail interactions below.
+    await page.setViewportSize({ width: 1600, height: 900 });
     const serverId = getServerId();
 
     const workspace = await seedWorkspace({ repoPrefix: "pane-remount-" });
diff --git a/packages/app/e2e/browser/workspace-relative-navigation.spec.ts b/packages/app/e2e/browser/workspace-relative-navigation.spec.ts
index 909672c489..5066411c78 100644
--- a/packages/app/e2e/browser/workspace-relative-navigation.spec.ts
+++ b/packages/app/e2e/browser/workspace-relative-navigation.spec.ts
@@ -70,25 +70,31 @@ test("previous and next traverse every visible workspace while digit shortcuts s
         workspaceId: order[8],
       });
     });
-    await test.step("hidden Done rows remain shortcut targets without expanding the project", async () => {
-      await expectHiddenWorkspaceShortcuts(page, order);
+    await test.step("collapsed groups keep shortcut targets selected without expanding", async () => {
+      await expectCollapsedWorkspaceShortcuts(page, order);
     });
   } finally {
     await project.cleanup();
   }
 });
 
-async function expectHiddenWorkspaceShortcuts(page: Page, order: string[]) {
+async function expectCollapsedWorkspaceShortcuts(page: Page, order: string[]) {
   await page.getByLabel("Show less", { exact: true }).click();
   const rows = page.getByRole("button", { name: /^Workspace \d{2}$/ });
-  await expect(rows).toHaveCount(7);
+  await expect(rows).toHaveCount(8);
+  await expectSidebarWorkspaceSelected({ page, serverId: getServerId(), workspaceId: order[8] });
   await switchWorkspaceViaSidebar({ page, serverId: getServerId(), workspaceId: order[0] });
+  await expect(rows).toHaveCount(7);
   await page.keyboard.press("Alt+9");
   await expect(page).toHaveURL(new RegExp(`/workspace/${order[8]}$`));
+  await expectSidebarWorkspaceSelected({ page, serverId: getServerId(), workspaceId: order[8] });
+  await expect(rows).toHaveCount(8);
+  await page.keyboard.press("Alt+]");
+  await expect(page).toHaveURL(new RegExp(`/workspace/${order[9]}$`));
+  await expectSidebarWorkspaceSelected({ page, serverId: getServerId(), workspaceId: order[9] });
+  await expect(rows).toHaveCount(8);
   await expect(page.getByTestId(`sidebar-workspace-row-${getServerId()}:${order[8]}`)).toHaveCount(
     0,
   );
-  await page.keyboard.press("Alt+]");
-  await expect(page).toHaveURL(new RegExp(`/workspace/${order[9]}$`));
-  await expect(rows).toHaveCount(7);
+  await expect(page.getByLabel("Show more", { exact: true })).toBeVisible();
 }
diff --git a/packages/app/e2e/browser/workspace-split-header.spec.ts b/packages/app/e2e/browser/workspace-split-header.spec.ts
new file mode 100644
index 0000000000..27bb92584d
--- /dev/null
+++ b/packages/app/e2e/browser/workspace-split-header.spec.ts
@@ -0,0 +1,131 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+import { test } from "../support/fixtures";
+import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
+import { clickNewChat, gotoWorkspace } from "../support/helpers/launcher";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+
+function visible(page: Page, testId: string): Locator {
+  return page.getByTestId(testId).filter({ visible: true });
+}
+
+function panes(page: Page): Locator {
+  return page.locator('[data-testid^="workspace-pane-"]').filter({ visible: true });
+}
+
+function splitDividers(page: Page): Locator {
+  return visible(page, "workspace-split-resize-handle");
+}
+
+async function openSplitWorkspace(
+  page: Page,
+  repoPrefix: string,
+  split: "Split pane right" | "Split pane down",
+): Promise<SeededWorkspace> {
+  await page.setViewportSize({ width: 1600, height: 900 });
+  const workspace = await seedWorkspace({ repoPrefix });
+  await gotoWorkspace(page, workspace.workspaceId);
+  await waitForWorkspaceTabsVisible(page);
+  await clickNewChat(page);
+  await expect(visible(page, "workspace-header-title")).toHaveCount(1);
+  await runWorkspaceActionFromCommandCenter(page, split);
+  await expect(splitDividers(page)).toHaveCount(1);
+  await expect(panes(page)).toHaveCount(2);
+  return workspace;
+}
+
+async function expectOneSharedWorkspaceHeader(page: Page): Promise<void> {
+  await expect(visible(page, "workspace-header-title")).toHaveCount(1);
+  await expect(visible(page, "workspace-header-menu-trigger")).toHaveCount(1);
+  await expect(panes(page).getByTestId("workspace-header-title")).toHaveCount(0);
+  await expect(panes(page).getByTestId("workspace-header-menu-trigger")).toHaveCount(0);
+}
+
+/** The tab counter belongs to the single-pane layout: split panes always show their rails. */
+async function expectPanesKeepTabRails(page: Page): Promise<void> {
+  for (const pane of await panes(page).all()) {
+    await expect(pane.getByTestId("workspace-tabs-row")).toBeVisible();
+  }
+  await expect(visible(page, "workspace-tab-switcher-trigger")).toHaveCount(0);
+}
+
+async function dragDivider(divider: Locator, deltaX: number): Promise<void> {
+  const page = divider.page();
+  const box = await divider.boundingBox();
+  if (!box) throw new Error("Divider has no bounding box");
+  const x = box.x + box.width / 2;
+  const y = box.y + box.height / 2;
+  await page.mouse.move(x, y);
+  await page.mouse.down();
+  await page.mouse.move(x + deltaX, y, { steps: 8 });
+  await page.mouse.up();
+}
+
+test.describe("Workspace header with split panes", () => {
+  test("wide side-by-side panes share one header and keep their tab rails", async ({ page }) => {
+    const workspace = await openSplitWorkspace(page, "split-header-wide-", "Split pane right");
+    try {
+      await expectOneSharedWorkspaceHeader(page);
+      await expectPanesKeepTabRails(page);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("stacked panes share one header", async ({ page }) => {
+    const workspace = await openSplitWorkspace(page, "split-header-stacked-", "Split pane down");
+    try {
+      await expectOneSharedWorkspaceHeader(page);
+      await expectPanesKeepTabRails(page);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("a narrow workspace shows one compact header and every pane keeps its tab rail", async ({
+    page,
+  }) => {
+    const workspace = await openSplitWorkspace(page, "split-header-narrow-", "Split pane right");
+    try {
+      await page.setViewportSize({ width: 760, height: 900 });
+      await expectPanesKeepTabRails(page);
+      await expectOneSharedWorkspaceHeader(page);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("a narrow pane beside a wide one keeps its tab rail", async ({ page }) => {
+    const workspace = await openSplitWorkspace(page, "split-header-mixed-", "Split pane right");
+    try {
+      await dragDivider(splitDividers(page), -300);
+      const [left, right] = await panes(page).all();
+      const leftBox = await left.boundingBox();
+      const rightBox = await right.boundingBox();
+      expect(leftBox!.width).toBeLessThan(500);
+      expect(rightBox!.width).toBeGreaterThan(500);
+      await expectPanesKeepTabRails(page);
+      await expectOneSharedWorkspaceHeader(page);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("closing back to one pane returns the merged compact header", async ({ page }) => {
+    const workspace = await openSplitWorkspace(page, "split-header-close-", "Split pane right");
+    try {
+      const [, emptyPane] = await panes(page).all();
+      const emptyPaneRail = emptyPane.getByTestId("workspace-tabs-row");
+      await emptyPaneRail.locator('[data-testid^="workspace-tab-"]').first().hover();
+      await emptyPaneRail.locator('[data-testid*="-close-"]').first().click();
+      await expect(splitDividers(page)).toHaveCount(0);
+      await expect(visible(page, "workspace-header-title")).toHaveCount(1);
+      await page.setViewportSize({ width: 760, height: 900 });
+      await expect(visible(page, "workspace-tabs-row")).toHaveCount(0);
+      await expect(visible(page, "workspace-tab-switcher-trigger")).toHaveCount(1);
+      await expect(visible(page, "workspace-header-title")).toHaveCount(1);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad b/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
index 359e89c5c9..d92c92771c 100644
--- a/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
+++ b/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
@@ -6,6 +6,11 @@ env APP_ID=sh.paseo.debug
 # Hold past drag arming (180ms), then release.
 open "${APP_ID}"
 press "label=\"Open menu\""
+wait "id=\"sidebar-close\"" 10000
+press "id=\"sidebar-close\""
+# The close target must clear system controls, including a trailing status column.
+wait "label=\"Open menu\"" 5000
+press "label=\"Open menu\""
 wait "id=\"${WORKSPACE_ROW}\"" 10000
 longpress "id=\"${WORKSPACE_ROW}\"" 250
 press "id=\"${WORKSPACE_ROW}\""
diff --git a/packages/app/e2e/mobile/composer-keyboard/android.sh b/packages/app/e2e/mobile/composer-keyboard/android.sh
index 809483ceff..b3b20ed2b7 100755
--- a/packages/app/e2e/mobile/composer-keyboard/android.sh
+++ b/packages/app/e2e/mobile/composer-keyboard/android.sh
@@ -509,6 +509,8 @@ check_autocomplete() {
     fi
   fi
   ad wait 'id="composer-autocomplete-popover"' 10000
+  # Rows replace the popover's loading row once the host lists them; a cold Claude list is slow.
+  ad wait "text=\"${expected}\"" 30000
   # The popover remeasures once keyboard motion settles.
   sleep 1
   capture_screen "${prefix}.png"
diff --git a/packages/app/e2e/mobile/composer-keyboard/ios.mjs b/packages/app/e2e/mobile/composer-keyboard/ios.mjs
index 513d68623e..9deb02ab68 100644
--- a/packages/app/e2e/mobile/composer-keyboard/ios.mjs
+++ b/packages/app/e2e/mobile/composer-keyboard/ios.mjs
@@ -69,17 +69,23 @@ async function waitFor(name, predicate, timeoutMs = 10_000) {
   }
 }
 
-// Keyboard motion has settled once two snapshots agree on the composer position.
+// Keyboard motion has settled once two snapshots agree on the composer position. The
+// popover shows a loading row until the host lists its commands; a cold Claude list is slow.
 async function settledPlacement(name, keyboard) {
   let previousTop;
-  return waitFor(name, (snap) => {
-    const composer = nodeById(snap, "message-input-root");
-    if (!nodeById(snap, "composer-autocomplete-popover") || !composer) return false;
-    if (keyboardShown(snap) !== keyboard) return false;
-    const stable = composer.rect.y === previousTop;
-    previousTop = composer.rect.y;
-    return stable;
-  });
+  return waitFor(
+    name,
+    (snap) => {
+      const composer = nodeById(snap, "message-input-root");
+      if (!nodeById(snap, "composer-autocomplete-popover") || !composer) return false;
+      if (nodeById(snap, "composer-autocomplete-loading")) return false;
+      if (keyboardShown(snap) !== keyboard) return false;
+      const stable = composer.rect.y === previousTop;
+      previousTop = composer.rect.y;
+      return stable;
+    },
+    30_000,
+  );
 }
 
 function assertPlacement(name, snap, expected) {
diff --git a/packages/app/e2e/mobile/system-bars/android.mjs b/packages/app/e2e/mobile/system-bars/android.mjs
index 8201f3dc12..acc7458c01 100644
--- a/packages/app/e2e/mobile/system-bars/android.mjs
+++ b/packages/app/e2e/mobile/system-bars/android.mjs
@@ -38,12 +38,9 @@ async function expectDarkIcons(expected, context) {
   assert.equal(windowState(), expected, context);
 }
 
+// Settings > Appearance shows every theme as a tile in one radio group.
 function selectTheme(theme) {
-  const current = ad("snapshot", "-i").match(/"Theme: ([^"]+)"/)?.[1];
-  assert(current, "Start on Settings > Appearance");
-  ad("press", `label="Theme: ${current}"`, "--settle");
   ad("press", `label="${theme}"`, "--settle");
-  ad("wait", "text", `Theme: ${theme}`, "5000");
 }
 
 ad("settings", "appearance", "light");
diff --git a/packages/app/e2e/mobile/terminal-rendering/check.mjs b/packages/app/e2e/mobile/terminal-rendering/check.mjs
index fbf4529bb3..92287e0586 100644
--- a/packages/app/e2e/mobile/terminal-rendering/check.mjs
+++ b/packages/app/e2e/mobile/terminal-rendering/check.mjs
@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { writeFileSync } from "node:fs";
+import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
 import xterm from "@xterm/headless";
 import { PNG } from "pngjs";
 import { ACCENT, fixtureLines, fixtureOutput, RULER_CELLS, SELECT_LINE } from "./fixture.mjs";
@@ -82,6 +83,8 @@ async function fixtureTerminal(size) {
     rows: size.rows,
     allowProposedApi: true,
   });
+  // The app's buffer uses grapheme widths; the expected cells must too.
+  terminal.loadAddon(new UnicodeGraphemesAddon());
   await new Promise((done) =>
     terminal.write(fixtureOutput(size.columns).replaceAll("\n", "\r\n"), done),
   );
diff --git a/packages/app/e2e/mobile/timeline-status/placement.mjs b/packages/app/e2e/mobile/timeline-status/placement.mjs
new file mode 100644
index 0000000000..8317c9e152
--- /dev/null
+++ b/packages/app/e2e/mobile/timeline-status/placement.mjs
@@ -0,0 +1,54 @@
+// Open an existing compact chat, with the keyboard closed, then interrupt its host connection.
+// Hold that interruption externally (for example, stop a disposable SSH TCP forward).
+// Leave the daemon running. This test observes the public reconnecting state.
+// node placement.mjs <session> <platform> <coordinate-scale> <composer-label> <artifacts>
+// coordinate-scale is screenshot pixels per layout point (Android density; iOS snapshots use 1).
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const [, , session, platform, coordinateScale, composerLabel, artifacts] = process.argv;
+assert(
+  session && ["android", "ios"].includes(platform) && composerLabel && artifacts,
+  "Pass all five arguments",
+);
+const scale = Number(coordinateScale);
+assert(scale > 0, "Pass a positive coordinate scale");
+mkdirSync(artifacts, { recursive: true });
+function ad(...args) {
+  return execFileSync("agent-device", ["--session", session, "--platform", platform, ...args], {
+    encoding: "utf8",
+    timeout: 90_000,
+  });
+}
+function capture(name) {
+  const snapshot = ad("snapshot", "--raw", "--json");
+  writeFileSync(path.join(artifacts, `${name}.json`), snapshot);
+  ad("screenshot", path.join(artifacts, `${name}.png`));
+  const nodes = JSON.parse(snapshot).data.nodes;
+  const header = nodes.find((node) => node.identifier === "floating-header");
+  const toast = nodes.find((node) => node.identifier === "agent-reconnecting-toast");
+  assert(header?.rect && toast?.rect, "Measured header and reconnecting toast must be present");
+  assert(toast.rect.height > 0 && toast.rect.width > 0, "Toast must have visible bounds");
+  const gap = (toast.rect.y - header.rect.y - header.rect.height) / scale;
+  assert(Math.abs(gap - 12) <= 1, `${name}: actual header-to-toast gap ${gap}, expected12 points`);
+  return toast.rect.y / scale;
+}
+
+ad("wait", 'id="agent-reconnecting-toast"', "20000");
+const closedTop = capture("keyboard-closed");
+ad("press", `label=${JSON.stringify(composerLabel)}`);
+const opened = ad("snapshot", "--raw", "--json");
+const nodes = JSON.parse(opened).data.nodes;
+assert(
+  nodes.some(
+    (node) => /keyboard/i.test(node.type ?? "") || /inputmethod/i.test(node.bundleId ?? ""),
+  ),
+  "Use a real visible software keyboard; open Android sessions with --no-test-ime",
+);
+const openTop = capture("keyboard-open");
+assert(Math.abs(openTop - closedTop) <= 1, "Keyboard must not translate the toast");
+console.log(
+  "PASS: rendered reconnecting toast stays12 points below measured header, keyboard closed/open",
+);
diff --git a/packages/app/e2e/support/fixtures.ts b/packages/app/e2e/support/fixtures.ts
index 89cfb6937d..26e6e4d2d2 100644
--- a/packages/app/e2e/support/fixtures.ts
+++ b/packages/app/e2e/support/fixtures.ts
@@ -107,6 +107,8 @@ const daemonTest = metroTest.extend<
 });
 
 const test = daemonTest.extend<{
+  /** Specs start past first-run setup; onboarding specs opt out to see a fresh install. */
+  e2eOnboardingCompleted: boolean;
   paseoE2ESetup: void;
   outdatedDaemon: OutdatedDaemon;
   desktopManagedOutdatedDaemon: OutdatedDaemon;
@@ -114,8 +116,9 @@ const test = daemonTest.extend<{
   projectPickerFixture: TrackedProjectPickerFixture;
   withWorkspace: WithWorkspace;
 }>({
+  e2eOnboardingCompleted: [true, { option: true }],
   paseoE2ESetup: [
-    async ({ page }, provide, testInfo) => {
+    async ({ page, e2eOnboardingCompleted }, provide, testInfo) => {
       const daemonPort = getE2EDaemonPort();
       const metroPort = process.env.E2E_METRO_PORT;
       if (!metroPort) {
@@ -157,7 +160,7 @@ const test = daemonTest.extend<{
       const createAgentPreferences = buildCreateAgentPreferences();
 
       await page.addInitScript(
-        ({ daemon, preferences, seedNonce: nonce, extraHostsKey }) => {
+        ({ daemon, preferences, seedNonce: nonce, extraHostsKey, onboardingCompleted }) => {
           // `addInitScript` runs on every navigation (including reloads). Some tests intentionally
           // override storage and reload; they can opt out of seeding for the *next* navigation by
           // setting this flag before the reload.
@@ -185,12 +188,20 @@ const test = daemonTest.extend<{
           if (!localStorage.getItem("@paseo:app-settings")) {
             localStorage.setItem("@paseo:app-settings", JSON.stringify({ chatDisplay: "full" }));
           }
+          // The shared daemon often has no projects, which would open first-run setup over the app.
+          if (onboardingCompleted && !localStorage.getItem("@paseo:onboarding")) {
+            localStorage.setItem(
+              "@paseo:onboarding",
+              JSON.stringify({ completedAt: new Date(0).toISOString() }),
+            );
+          }
         },
         {
           daemon: testDaemon,
           preferences: createAgentPreferences,
           seedNonce,
           extraHostsKey: EXTRA_HOSTS_KEY,
+          onboardingCompleted: e2eOnboardingCompleted,
         },
       );
 
diff --git a/packages/app/e2e/support/helpers/add-project-flow.ts b/packages/app/e2e/support/helpers/add-project-flow.ts
index 666469540e..1190bf0676 100644
--- a/packages/app/e2e/support/helpers/add-project-flow.ts
+++ b/packages/app/e2e/support/helpers/add-project-flow.ts
@@ -113,3 +113,29 @@ export async function expectAddProjectResultVisible(page: Page, text: string): P
     })
     .toBe(true);
 }
+
+export async function chooseAddHostFromProjectFlow(page: Page): Promise<void> {
+  await page.getByRole("button", { name: /Add host.*No connected hosts/ }).click();
+}
+
+export async function navigateAndDismissAddProject(page: Page): Promise<void> {
+  // Keep both keys in one task so Escape closes with a selection update still queued.
+  await page.evaluate(() => {
+    for (const key of ["ArrowDown", "Escape"]) {
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", { key, code: key, bubbles: true, cancelable: true }),
+      );
+    }
+  });
+}
+
+export function watchAddProjectRenderWarnings(page: Page): string[] {
+  const warnings: string[] = [];
+  page.on("console", (message) => {
+    const text = message.text();
+    if (text.includes("Cannot update a component") && text.includes("AddProjectFlow")) {
+      warnings.push(text);
+    }
+  });
+  return warnings;
+}
diff --git a/packages/app/e2e/support/helpers/agent-skills.ts b/packages/app/e2e/support/helpers/agent-skills.ts
index 5d8c15633c..2ac2903a7b 100644
--- a/packages/app/e2e/support/helpers/agent-skills.ts
+++ b/packages/app/e2e/support/helpers/agent-skills.ts
@@ -154,7 +154,7 @@ export async function chooseCustomSkills(page: Page, selected: string[]): Promis
   await all.click();
   const keep = new Set(selected);
   for (const name of await listSkillChoices(page)) {
-    if (!keep.has(name)) await page.getByRole("checkbox", { name, exact: true }).click();
+    if (!keep.has(name)) await skillSwitch(page, name).click();
   }
   await expectSkillChoices(page, selected);
 }
@@ -176,7 +176,7 @@ export async function cancelSkillSelection(page: Page): Promise<void> {
 }
 
 export async function toggleSkill(page: Page, name: string): Promise<void> {
-  await page.getByRole("checkbox", { name, exact: true }).click();
+  await skillSwitch(page, name).click();
 }
 
 export function answerNextRemovalWarning(
@@ -222,15 +222,21 @@ export async function expectSkillFile(
 export async function expectSkillChoices(page: Page, selected: string[]): Promise<void> {
   const expected = new Set(selected);
   for (const name of await listSkillChoices(page)) {
-    await expect(page.getByRole("checkbox", { name, exact: true })).toBeChecked({
+    await expect(skillSwitch(page, name)).toBeChecked({
       checked: expected.has(name),
     });
   }
 }
 
+/** One bundled skill's switch in the picker; "All skills" sits outside the list. */
+function skillSwitch(page: Page, name: string) {
+  return page.getByTestId("skill-selection-list-card").getByRole("switch", { name, exact: true });
+}
+
 async function listSkillChoices(page: Page): Promise<string[]> {
   return page
-    .getByRole("checkbox")
+    .getByTestId("skill-selection-list-card")
+    .getByRole("switch")
     .evaluateAll((elements) =>
       elements
         .map((element) => element.getAttribute("aria-label") ?? "")
diff --git a/packages/app/e2e/support/helpers/archive-tab.ts b/packages/app/e2e/support/helpers/archive-tab.ts
index cf9c43fcf3..97291d8951 100644
--- a/packages/app/e2e/support/helpers/archive-tab.ts
+++ b/packages/app/e2e/support/helpers/archive-tab.ts
@@ -219,6 +219,11 @@ export async function expectWorkspaceArchiveOutcome(
   await expectWorkspaceTabVisible(page, input.survivingAgentId);
 }
 
+export async function closeActiveAgentWithShortcut(page: Page, agentId: string): Promise<void> {
+  await page.keyboard.press("Alt+Shift+w");
+  await expectWorkspaceTabHidden(page, agentId);
+}
+
 export async function closeWorkspaceAgentTab(page: Page, agentId: string): Promise<void> {
   const closeButton = page.getByTestId(`workspace-agent-close-${agentId}`).filter({
     visible: true,
@@ -237,6 +242,10 @@ export async function expectArchivedAgentFocused(page: Page, agentId: string): P
   });
 }
 
+export async function unarchiveAgentFromConversation(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Unarchive", exact: true }).click();
+}
+
 export async function reloadWorkspace(page: Page, workspaceId: string): Promise<void> {
   const serverId = getServerId();
   await page.goto(buildHostWorkspaceRoute(serverId, workspaceId));
diff --git a/packages/app/e2e/support/helpers/background-agents.ts b/packages/app/e2e/support/helpers/background-agents.ts
new file mode 100644
index 0000000000..ffb2fc4ccf
--- /dev/null
+++ b/packages/app/e2e/support/helpers/background-agents.ts
@@ -0,0 +1,48 @@
+import { expect, type Page } from "@playwright/test";
+import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import type { SeededWorkspace } from "./seed-client";
+
+/**
+ * Starts a background agent the way a plugin helper does: in the workspace, under a parent,
+ * streaming for about ten seconds. Resolves once the daemon reports it running.
+ */
+export async function startBackgroundAgent(
+  workspace: Pick<SeededWorkspace, "client" | "repoPath" | "workspaceId">,
+  input: { parentId: string; title: string },
+): Promise<{ id: string }> {
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: input.title,
+    modeId: "load-test",
+    model: "ten-second-stream",
+    initialPrompt: "classify the last turn",
+    labels: { [PARENT_AGENT_ID_LABEL]: input.parentId },
+    background: true,
+  });
+  await workspace.client.waitForAgentUpsert(agent.id, (snapshot) => snapshot.status === "running");
+  return { id: agent.id };
+}
+
+/** Waits for the agent's turn to end and archives it, as the plugin does with a helper's reply. */
+export async function finishAndArchiveAgent(
+  workspace: Pick<SeededWorkspace, "client">,
+  agentId: string,
+): Promise<void> {
+  const finished = await workspace.client.waitForFinish(agentId, 60_000);
+  expect(finished.status).toBe("idle");
+  await workspace.client.archiveAgent(agentId);
+}
+
+export async function expectWorkspaceShownIdle(page: Page, workspaceName: string): Promise<void> {
+  const row = page.getByRole("button", {
+    name: new RegExp(`^${escapeRegExp(workspaceName)}(?:,|$)`),
+  });
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await expect(row.getByTestId("workspace-status-indicator-running")).toHaveCount(0);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
diff --git a/packages/app/e2e/support/helpers/changelog.ts b/packages/app/e2e/support/helpers/changelog.ts
index a2138920fb..959fba68bc 100644
--- a/packages/app/e2e/support/helpers/changelog.ts
+++ b/packages/app/e2e/support/helpers/changelog.ts
@@ -27,3 +27,18 @@ export async function openWhatsNew(page: Page): Promise<Locator> {
 export function release(sheet: Locator, version: string): Locator {
   return sheet.getByTestId(`changelog-release-${version}`);
 }
+
+/** The one control a release with highlights has for its sections, in either state. */
+export function allChangesToggle(entry: Locator): Locator {
+  return entry.getByRole("button", { name: /^(Show|Hide) all changes$/ });
+}
+
+export async function showAllChanges(entry: Locator): Promise<void> {
+  await entry.getByRole("button", { name: "Show all changes" }).click();
+  await expect(entry.getByRole("button", { name: "Hide all changes" })).toBeVisible();
+}
+
+export async function hideAllChanges(entry: Locator): Promise<void> {
+  await entry.getByRole("button", { name: "Hide all changes" }).click();
+  await expect(entry.getByRole("button", { name: "Show all changes" })).toBeVisible();
+}
diff --git a/packages/app/e2e/support/helpers/command-center-file-search.ts b/packages/app/e2e/support/helpers/command-center-file-search.ts
index eb0b888d24..175388a952 100644
--- a/packages/app/e2e/support/helpers/command-center-file-search.ts
+++ b/packages/app/e2e/support/helpers/command-center-file-search.ts
@@ -99,6 +99,7 @@ export async function startCommandCenterLayoutObservation(page: Page): Promise<v
     const observedElements = new WeakSet<Element>();
     const resizeObserver = new ResizeObserver(record);
     const mutationObserver = new MutationObserver(discover);
+    let performanceObserver: PerformanceObserver | undefined;
 
     function record(): void {
       if (!observation.active) return;
@@ -132,6 +133,7 @@ export async function startCommandCenterLayoutObservation(page: Page): Promise<v
       if (!observation.active) {
         mutationObserver.disconnect();
         resizeObserver.disconnect();
+        performanceObserver?.disconnect();
         return;
       }
       record();
@@ -141,9 +143,16 @@ export async function startCommandCenterLayoutObservation(page: Page): Promise<v
 
     if (typeof PerformanceObserver !== "undefined") {
       try {
-        const performanceObserver = new PerformanceObserver((list) => {
+        performanceObserver = new PerformanceObserver((list) => {
+          const panel = document.querySelector(selectors.panel);
           for (const entry of list.getEntries()) {
-            observation.layoutShift += (entry as PerformanceEntry & { value?: number }).value ?? 0;
+            const shift = entry as PerformanceEntry & {
+              value: number;
+              sources: Array<{ node: Node | null }>;
+            };
+            if (shift.sources.some((source) => source.node && panel?.contains(source.node))) {
+              observation.layoutShift += shift.value;
+            }
           }
         });
         performanceObserver.observe({ type: "layout-shift", buffered: false });
@@ -174,7 +183,54 @@ export async function expectStableCommandCenterLayout(page: Page): Promise<void>
       ).toBeLessThanOrEqual(1);
     }
   }
-  expect(observation.layoutShift, JSON.stringify(observation)).toBeLessThanOrEqual(0.001);
+  expect(
+    observation.layoutShift,
+    `command center layoutShift: ${JSON.stringify(observation)}`,
+  ).toBeLessThanOrEqual(0.001);
+}
+
+/** Exercise an unrelated page shift while the real search panel is being observed. */
+export async function shiftOutsideCommandCenter(page: Page): Promise<void> {
+  await shiftLayoutProbe(page.locator("body"));
+}
+
+export async function expectLayoutObservationToCatchPanelShift(page: Page): Promise<void> {
+  await startCommandCenterLayoutObservation(page);
+  await shiftLayoutProbe(page.getByTestId("command-center-panel"));
+  await expect(expectStableCommandCenterLayout(page)).rejects.toThrow("command center layoutShift");
+}
+
+async function shiftLayoutProbe(parent: Locator): Promise<void> {
+  const recordedShift = await parent.evaluate(async (container) => {
+    const sibling = document.createElement("div");
+    sibling.textContent = "Layout probe";
+    sibling.style.cssText =
+      "position:fixed;left:0;top:0;width:300px;height:100px;background:white;z-index:99999";
+    container.append(sibling);
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+    const value = await new Promise<number>((resolve) => {
+      const observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const shift = entry as PerformanceEntry & {
+            value: number;
+            sources: Array<{ node: Node | null }>;
+          };
+          if (shift.sources.some((source) => source.node === sibling)) {
+            observer.disconnect();
+            resolve(shift.value);
+          }
+        }
+      });
+      observer.observe({ type: "layout-shift", buffered: false });
+      sibling.style.left = "400px";
+    });
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+    sibling.remove();
+    return value;
+  });
+  expect(recordedShift, "the browser recorded a substantial probe shift").toBeGreaterThan(0.001);
 }
 
 export async function expectOneLineTruncatedFileResult(
diff --git a/packages/app/e2e/support/helpers/composer-control-density.ts b/packages/app/e2e/support/helpers/composer-control-density.ts
index ff5e53b25c..089b112b74 100644
--- a/packages/app/e2e/support/helpers/composer-control-density.ts
+++ b/packages/app/e2e/support/helpers/composer-control-density.ts
@@ -53,3 +53,302 @@ export async function expectNoCollapsedComposerToolbarFrame(page: Page): Promise
   const collapsed = frames.filter((frame) => frame.labels.some((label) => label === ""));
   expect(collapsed, `collapsed toolbar frames: ${JSON.stringify(collapsed)}`).toEqual([]);
 }
+
+/** One painted frame of the composer's trailing controls: the slot and what sits beside it. */
+export interface TrailingActionFrame {
+  atMs: number;
+  /** Every trailing action on screen, as `label` or `label (disabled)`. */
+  actions: string[];
+  slotX: number | null;
+  micX: number | null;
+  ringX: number | null;
+  ringWidth: number | null;
+}
+
+declare global {
+  interface Window {
+    __trailingActionFrames?: TrailingActionFrame[];
+    __trailingActionStop?: () => void;
+  }
+}
+
+const TRAILING_ACTION_LABELS = [
+  "Enable Voice mode",
+  "Send message",
+  "Queue message",
+  "Send and interrupt",
+  "Send and steer",
+  "Interrupt agent",
+  "Stop agent",
+];
+
+/**
+ * Records every painted frame of the visible composer's trailing controls. Takes one sample before
+ * the first paint, so input that lands right after this resolves still has a frame to compare to.
+ */
+export async function recordTrailingActionFrames(page: Page): Promise<void> {
+  await page.evaluate((labels) => {
+    const frames: TrailingActionFrame[] = [];
+    window.__trailingActionFrames = frames;
+    const start = performance.now();
+    const visibleRoot = () =>
+      Array.from(document.querySelectorAll('[data-testid="message-input-root"]')).find(
+        (root) => root.getClientRects().length > 0,
+      );
+    const sample = () => {
+      const root = visibleRoot();
+      const control = (selector: string) =>
+        Array.from(root?.querySelectorAll(selector) ?? []).find(
+          (node) => node.getClientRects().length > 0,
+        );
+      const actions = labels.flatMap((label) => {
+        const node = control(`[aria-label="${label}"]`);
+        if (!node) return [];
+        return [node.getAttribute("aria-disabled") === "true" ? `${label} (disabled)` : label];
+      });
+      const slot = labels.map((label) => control(`[aria-label="${label}"]`)).find(Boolean);
+      const mic = control('[aria-label="Start dictation"]');
+      const ring = control('[aria-label^="Context window"]');
+      frames.push({
+        atMs: Math.round(performance.now() - start),
+        actions,
+        slotX: slot ? slot.getBoundingClientRect().x : null,
+        micX: mic ? mic.getBoundingClientRect().x : null,
+        ringX: ring ? ring.getBoundingClientRect().x : null,
+        ringWidth: ring ? ring.getBoundingClientRect().width : null,
+      });
+    };
+    sample();
+    let running = true;
+    const tick = () => {
+      if (!running) return;
+      sample();
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+    window.__trailingActionStop = () => {
+      running = false;
+    };
+  }, TRAILING_ACTION_LABELS);
+}
+
+export async function readTrailingActionFrames(page: Page): Promise<TrailingActionFrame[]> {
+  return page.evaluate(() => {
+    window.__trailingActionStop?.();
+    return window.__trailingActionFrames ?? [];
+  });
+}
+
+/**
+ * Every frame of the span shows exactly one trailing action, in the one slot, moving straight from
+ * `from` to `to`, with the mic and context ring where they started.
+ */
+export function expectTrailingActionSwap(
+  frames: TrailingActionFrame[],
+  expected: { from: string; to: string },
+): void {
+  expect(frames.length).toBeGreaterThan(1);
+  const [first] = frames;
+  const wrongFrames = frames.filter(
+    (frame) =>
+      frame.actions.length !== 1 ||
+      frame.slotX !== first.slotX ||
+      frame.micX !== first.micX ||
+      frame.ringX !== first.ringX ||
+      frame.ringWidth !== first.ringWidth,
+  );
+  expect(wrongFrames, `frames that moved or showed the wrong action`).toEqual([]);
+  const sequence = frames
+    .map((frame) => frame.actions[0])
+    .filter((action, index, all) => action !== all[index - 1]);
+  expect(sequence).toEqual([expected.from, expected.to]);
+}
+
+/** What the folded model control's labels show, read from the DOM. */
+export interface ModelTriggerLabelState {
+  thinkingShown: boolean;
+  modelShown: boolean;
+  modelText: string;
+  modelTruncated: boolean;
+}
+
+declare global {
+  interface Window {
+    __modelTriggerFrames?: ModelTriggerLabelState[];
+  }
+}
+
+function readModelTriggerLabelStateInPage(): ModelTriggerLabelState {
+  const visible = (node: Element) => node.getClientRects().length > 0;
+  const model = Array.from(
+    document.querySelectorAll('[data-testid="combined-model-selector-model-label"]'),
+  ).find(visible);
+  const thinking = Array.from(
+    document.querySelectorAll('[data-testid="combined-model-selector-thinking-label"]'),
+  ).find(visible);
+  const shown = (node: Element | null): boolean => {
+    for (let current = node; current; current = current.parentElement) {
+      if (Number(getComputedStyle(current).opacity) === 0) return false;
+    }
+    return true;
+  };
+  const modelShown = model !== undefined && shown(model);
+  const modelText = model?.textContent ?? "";
+  return {
+    modelShown,
+    modelText,
+    thinkingShown: modelShown && thinking !== undefined,
+    modelTruncated:
+      model !== undefined && (modelText.endsWith("…") || model.scrollWidth > model.clientWidth),
+  };
+}
+
+/** Records the folded model control's labels on every painted frame from page load. */
+export async function recordModelTriggerFramesFromLoad(page: Page): Promise<void> {
+  await page.addInitScript(`(() => {
+    const read = ${readModelTriggerLabelStateInPage.toString()};
+    const frames = [];
+    window.__modelTriggerFrames = frames;
+    const tick = () => {
+      frames.push(read());
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  })()`);
+}
+
+/** The model control's labels once two reads 100ms apart agree. */
+export async function readSettledModelTriggerLabels(page: Page): Promise<ModelTriggerLabelState> {
+  let previous = await page.evaluate(readModelTriggerLabelStateInPage);
+  for (;;) {
+    await page.waitForTimeout(100);
+    const next = await page.evaluate(readModelTriggerLabelStateInPage);
+    if (JSON.stringify(next) === JSON.stringify(previous)) return next;
+    previous = next;
+  }
+}
+
+/** The labels at the widths where the folded model control changes what it shows. */
+export interface ModelTriggerLabelSweep {
+  /** The labels at the widest width. */
+  widest: ModelTriggerLabelState & { width: number };
+  /** The first width at which the thinking label is hidden. */
+  thinkingHidden: ModelTriggerLabelState & { width: number };
+  /** The first width at which the model label is truncated. */
+  modelTruncated: ModelTriggerLabelState & { width: number };
+}
+
+/**
+ * Narrows the viewport step by step and records where the thinking label disappears and where the
+ * model label first truncates.
+ */
+export async function sweepModelTriggerLabels(
+  page: Page,
+  widths: { from: number; to: number; step: number; height: number },
+): Promise<ModelTriggerLabelSweep> {
+  const steps: (ModelTriggerLabelState & { width: number })[] = [];
+  for (let width = widths.from; width >= widths.to; width -= widths.step) {
+    await page.setViewportSize({ width, height: widths.height });
+    const labels = await readSettledModelTriggerLabels(page);
+    steps.push({ ...labels, width });
+    if (labels.modelTruncated || !labels.modelShown) break;
+  }
+  const thinkingHidden = steps.find((step) => !step.thinkingShown);
+  const modelTruncated = steps.find((step) => step.modelTruncated);
+  if (!thinkingHidden || !modelTruncated) {
+    throw new Error(`the sweep never hid the thinking label and truncated the model label`);
+  }
+  return { widest: steps[0], thinkingHidden, modelTruncated };
+}
+
+/** No frame recorded so far painted a truncated model label beside the thinking label. */
+export async function expectNoFrameTruncatesModelBesideThinking(page: Page): Promise<void> {
+  const frames = await page.evaluate(() => window.__modelTriggerFrames ?? []);
+  expect(frames.some((frame) => frame.modelShown)).toBe(true);
+  const wrong = frames
+    .map((frame, index) => ({ ...frame, index }))
+    .filter((frame) => frame.thinkingShown && frame.modelTruncated);
+  expect(wrong, `of ${frames.length} frames`).toEqual([]);
+}
+
+/** Where the composer toolbar's ends sit against the composer, in CSS pixels. */
+export interface ComposerToolbarRails {
+  /** Where the text column starts. */
+  textLeft: number;
+  /** Where the toolbar's leftmost ink starts. */
+  inkLeft: number;
+  /** How far the trailing disc sits from the composer's right edge. */
+  discRightInset: number;
+  /** How far the trailing disc sits from the composer's bottom edge. */
+  discBottomInset: number;
+}
+
+/**
+ * Reads where the toolbar's ink starts against the text column and where the trailing disc sits
+ * in the composer's corner. A control's ink is its filled disc when it has one, otherwise its
+ * glyph's stroked geometry.
+ */
+export async function readComposerToolbarRails(page: Page): Promise<ComposerToolbarRails> {
+  const root = page.locator('[data-testid="message-input-root"]:visible').first();
+  return root.evaluate((element) => {
+    const textarea = element.querySelector("textarea");
+    if (!textarea) throw new Error("composer has no text input");
+    const composerRect = element.getBoundingClientRect();
+    const textLeft =
+      textarea.getBoundingClientRect().left +
+      Number.parseFloat(getComputedStyle(textarea).paddingLeft);
+
+    const isFilled = (node: Element) => {
+      const color = getComputedStyle(node).backgroundColor;
+      return color !== "" && color !== "transparent" && !/rgba\(.*,\s*0\)$/.test(color);
+    };
+    const glyphInkLeft = (svg: SVGSVGElement) => {
+      let left = Number.POSITIVE_INFINITY;
+      for (const shape of Array.from(
+        svg.querySelectorAll<SVGGraphicsElement>("path, circle, rect, line, polyline"),
+      )) {
+        const matrix = shape.getScreenCTM();
+        if (!matrix) continue;
+        const box = shape.getBBox();
+        const stroke = Number.parseFloat(getComputedStyle(shape).strokeWidth || "0");
+        left = Math.min(left, matrix.a * (box.x - stroke / 2) + matrix.e);
+      }
+      return left;
+    };
+
+    const band = composerRect.bottom - 64;
+    let inkLeft = Number.POSITIVE_INFINITY;
+    let trailingDisc: DOMRect | null = null;
+    for (const control of Array.from(element.querySelectorAll('[role="button"]'))) {
+      const rect = control.getBoundingClientRect();
+      if (rect.width === 0 || rect.top < band) continue;
+      const disc = [control, ...Array.from(control.querySelectorAll("div"))].find(isFilled);
+      const svg = control.querySelector("svg");
+      if (disc) {
+        const discRect = disc.getBoundingClientRect();
+        inkLeft = Math.min(inkLeft, discRect.left);
+        if (!trailingDisc || discRect.right > trailingDisc.right) trailingDisc = discRect;
+      } else if (svg) {
+        inkLeft = Math.min(inkLeft, glyphInkLeft(svg));
+      }
+    }
+    if (!trailingDisc) throw new Error("composer toolbar has no trailing disc");
+    return {
+      textLeft,
+      inkLeft,
+      discRightInset: composerRect.right - trailingDisc.right,
+      discBottomInset: composerRect.bottom - trailingDisc.bottom,
+    };
+  });
+}
+
+/**
+ * The toolbar's left ink sits on the text column's edge, and its trailing disc nests into the
+ * corner, as far from the right edge as from the bottom edge. Within half a pixel.
+ */
+export async function expectComposerToolbarOnTextRails(page: Page): Promise<void> {
+  const rails = await readComposerToolbarRails(page);
+  // A precision of 0 digits passes within half a pixel.
+  expect(rails.inkLeft).toBeCloseTo(rails.textLeft, 0);
+  expect(rails.discRightInset).toBeCloseTo(rails.discBottomInset, 0);
+}
diff --git a/packages/app/e2e/support/helpers/composer.ts b/packages/app/e2e/support/helpers/composer.ts
index bc0fef67f3..3c29bc24cc 100644
--- a/packages/app/e2e/support/helpers/composer.ts
+++ b/packages/app/e2e/support/helpers/composer.ts
@@ -31,7 +31,9 @@ export async function expectComposerVisible(
   page: Page,
   options?: { timeout?: number },
 ): Promise<void> {
-  await expect(composerInput(page)).toBeVisible({ timeout: options?.timeout ?? 15_000 });
+  await expect(composerInput(page)).toBeVisible({
+    timeout: options?.timeout ?? 15_000,
+  });
 }
 
 export async function expectComposerDisabled(page: Page): Promise<void> {
@@ -156,7 +158,9 @@ export async function attachImageFromMenu(
 }
 
 export async function expectAttachmentPill(page: Page, testID: string): Promise<void> {
-  await expect(page.getByTestId(testID).first()).toBeVisible({ timeout: 10_000 });
+  await expect(page.getByTestId(testID).first()).toBeVisible({
+    timeout: 10_000,
+  });
 }
 
 export async function attachFileFromMenu(
@@ -218,18 +222,24 @@ export async function expectGithubAttachmentPill(
 
 export async function openImageLightbox(page: Page): Promise<void> {
   await page.getByRole("button", { name: "Open image attachment" }).first().click();
-  await expect(page.getByTestId("attachment-lightbox-close")).toBeVisible({ timeout: 5_000 });
+  await expect(page.getByTestId("attachment-lightbox-close")).toBeVisible({
+    timeout: 5_000,
+  });
 }
 
 export async function closeImageLightbox(page: Page): Promise<void> {
   await page.keyboard.press("Escape");
-  await expect(page.getByTestId("attachment-lightbox-close")).not.toBeVisible({ timeout: 5_000 });
+  await expect(page.getByTestId("attachment-lightbox-close")).not.toBeVisible({
+    timeout: 5_000,
+  });
 }
 
 export async function openGithubPickerFromMenu(page: Page): Promise<void> {
   await openAttachmentMenu(page);
   await page.getByTestId("message-input-attachment-menu-item-github").click();
-  await expect(page.getByTestId("combobox-desktop-container")).toBeVisible({ timeout: 5_000 });
+  await expect(page.getByTestId("combobox-desktop-container")).toBeVisible({
+    timeout: 5_000,
+  });
 }
 
 /** Open picker, type a query, wait for the matching option by id (e.g. "issue:3", "change_request:1"), and click it. */
@@ -283,7 +293,10 @@ export async function startRunningMockAgent(
     model: opts.model,
     featureValues: opts.featureValues,
   });
-  const agentUrl = `${buildHostWorkspaceRoute(serverId, workspace.id)}?open=${encodeURIComponent(`agent:${agent.id}`)}`;
+  const agentUrl = `${buildHostWorkspaceRoute(
+    serverId,
+    workspace.id,
+  )}?open=${encodeURIComponent(`agent:${agent.id}`)}`;
   await page.goto(agentUrl);
   await expectComposerVisible(page);
   await client.sendAgentMessage(agent.id, opts.prompt);
@@ -347,7 +360,11 @@ export async function pasteComposerTestImage(page: Page): Promise<boolean> {
     const bytes = Uint8Array.from(atob(base64), (character) => character.charCodeAt(0));
     const clipboardData = new DataTransfer();
     clipboardData.items.add(new File([bytes], "pasted.png", { type: "image/png" }));
-    const event = new ClipboardEvent("paste", { clipboardData, bubbles: true, cancelable: true });
+    const event = new ClipboardEvent("paste", {
+      clipboardData,
+      bubbles: true,
+      cancelable: true,
+    });
     input.dispatchEvent(event);
     return event.defaultPrevented;
   }, COMPOSER_TEST_IMAGE_BASE64);
@@ -505,7 +522,10 @@ export async function recordVisibleComposerGeometry(page: Page): Promise<void> {
 export async function expectNoCollapsedVisibleComposer(page: Page): Promise<void> {
   const frames = await page.evaluate(() => {
     Reflect.get(window, "__stopComposerGeometry")?.();
-    return Reflect.get(window, "__composerGeometryFrames") as { input: number; root: number }[];
+    return Reflect.get(window, "__composerGeometryFrames") as {
+      input: number;
+      root: number;
+    }[];
   });
   expect(frames.length).toBeGreaterThan(0);
   expect(frames.filter((frame) => frame.root < 42 || frame.input < 42)).toEqual([]);
@@ -516,7 +536,10 @@ export async function roundTripComposerTabBeforePaint(
   page: Page,
   activeChatTitle: string,
 ): Promise<void> {
-  const activeTab = page.getByRole("button", { name: activeChatTitle, exact: true });
+  const activeTab = page.getByRole("button", {
+    name: activeChatTitle,
+    exact: true,
+  });
   await expect(activeTab).toHaveAttribute("aria-selected", "true");
   const result = await activeTab.evaluate((tab) => {
     const editor = document.activeElement;
@@ -556,7 +579,10 @@ export async function roundTripComposerTabBeforePaint(
           });
         }
       });
-      observer.observe(tab, { attributes: true, attributeFilter: ["aria-selected"] });
+      observer.observe(tab, {
+        attributes: true,
+        attributeFilter: ["aria-selected"],
+      });
       shortcut("BracketLeft");
     });
   });
@@ -566,3 +592,44 @@ export async function roundTripComposerTabBeforePaint(
   ).toBe(true);
   expect(result.focused, "returning on touch must leave the composer unfocused").toBe(false);
 }
+
+/** Paste both clipboard representations through the browser's normal paste command. */
+export async function pasteRichTextIntoComposer({
+  page,
+  html,
+  text,
+}: {
+  page: Page;
+  html: string;
+  text: string;
+}): Promise<void> {
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
+  await page.evaluate(
+    async ({ html: richHtml, text: plainText }) => {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob([richHtml], { type: "text/html" }),
+          "text/plain": new Blob([plainText], { type: "text/plain" }),
+        }),
+      ]);
+    },
+    { html, text },
+  );
+  await composerInput(page).press("ControlOrMeta+v");
+}
+
+export async function undoComposerEdit(page: Page): Promise<void> {
+  await composerInput(page).press("ControlOrMeta+z");
+}
+export async function redoComposerEdit(page: Page): Promise<void> {
+  await composerInput(page).press("ControlOrMeta+Shift+z");
+}
+
+/** Reuse the actual response Copy action and the browser's native paste. */
+export async function copyLatestTurnIntoComposer(page: Page): Promise<void> {
+  await page.context().grantPermissions(["clipboard-read", "clipboard-write"]);
+  await page.getByRole("button", { name: "Copy turn", exact: true }).last().click();
+  await expect(page.getByRole("button", { name: "Copied", exact: true })).toBeVisible();
+  await composerInput(page).fill("");
+  await composerInput(page).press("ControlOrMeta+v");
+}
diff --git a/packages/app/e2e/support/helpers/context-window.ts b/packages/app/e2e/support/helpers/context-window.ts
index afc91f859c..67e3ddb029 100644
--- a/packages/app/e2e/support/helpers/context-window.ts
+++ b/packages/app/e2e/support/helpers/context-window.ts
@@ -49,17 +49,97 @@ export async function moveOntoContextWindowDetails(page: Page, card: Locator): P
   await page.mouse.move(meter.x + meter.width / 2, box.y + box.height / 2, { steps: 20 });
 }
 
+/** The hover card as one painted frame showed it, or unmounted. */
+export interface ContextWindowFrame {
+  mounted: boolean;
+  bottom: number | null;
+  loading: boolean;
+  usageCards: number;
+}
+
+/**
+ * Reads the hover card as it was painted, every frame, until stopped, so a state that lasted one
+ * frame is seen. Stop it only after everything has settled.
+ */
+export async function recordContextWindowFrames(
+  page: Page,
+): Promise<{ stop: () => Promise<ContextWindowFrame[]> }> {
+  await page.evaluate(() => {
+    const recorder = window as unknown as {
+      __contextWindowFrames: ContextWindowFrame[];
+      __contextWindowRecording: boolean;
+    };
+    recorder.__contextWindowFrames = [];
+    recorder.__contextWindowRecording = true;
+    const findCard = () =>
+      document.querySelector<HTMLElement>('[data-testid="context-window-details"]');
+    const read = (card: HTMLElement | null): ContextWindowFrame => ({
+      mounted: card !== null,
+      bottom: card?.getBoundingClientRect().bottom ?? null,
+      loading: card?.innerText.includes("Loading usage...") ?? false,
+      usageCards: card?.querySelectorAll('[data-testid^="usage-report-"]').length ?? 0,
+    });
+    // A card that just resized has not been painted yet: its frame is read from an observer,
+    // which runs before that paint.
+    let watched: HTMLElement | null = null;
+    let paintedHeight: number | null = null;
+    let observer: ResizeObserver | null = null;
+    const watch = (card: HTMLElement) => {
+      observer = new ResizeObserver(() => {
+        paintedHeight = card.offsetHeight;
+        recorder.__contextWindowFrames.push(read(card));
+      });
+      observer.observe(card);
+    };
+    const channel = new MessageChannel();
+    // A message posted from an animation frame runs after that frame's paint.
+    channel.port1.addEventListener("message", () => {
+      const card = findCard();
+      if (card !== watched) {
+        observer?.disconnect();
+        watched = card;
+        paintedHeight = null;
+        if (card) watch(card);
+      }
+      if (!card || card.offsetHeight === paintedHeight) {
+        recorder.__contextWindowFrames.push(read(card));
+      }
+    });
+    channel.port1.start();
+    const sample = () => {
+      if (!recorder.__contextWindowRecording) return;
+      channel.port2.postMessage(null);
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+  });
+  return {
+    stop: () =>
+      page.evaluate(() => {
+        const recorder = window as unknown as {
+          __contextWindowFrames: ContextWindowFrame[];
+          __contextWindowRecording: boolean;
+        };
+        recorder.__contextWindowRecording = false;
+        return recorder.__contextWindowFrames;
+      }),
+  };
+}
+
 export async function leaveContextWindowMeter(page: Page): Promise<void> {
   await page.mouse.move(0, 0);
   await expect(contextWindowDetails(page)).toHaveCount(0);
 }
 
-/** Compact screens open the meter's details in a sheet. */
-export async function pressContextWindowMeter(page: Page, name = METER_NAME): Promise<Locator> {
+/** Clicking the meter opens its details in the active layout. */
+export async function pressContextWindowMeter(
+  page: Page,
+  name: string | RegExp = METER_NAME,
+): Promise<Locator> {
   await page.getByRole("button", { name, exact: true }).click({ timeout: 30_000 });
-  const sheet = contextWindowDetails(page);
-  await expect(sheet).toBeVisible();
-  return sheet;
+  const details = contextWindowDetails(page);
+  await expect(details).toBeVisible();
+  return details;
 }
 
 export async function closeContextWindowSheet(page: Page): Promise<void> {
@@ -136,6 +216,8 @@ export interface AgentUsageScript {
   agentRequests(): string[];
   /** Each scoped agent Refresh, by agent ID. */
   refreshedAgents(): string[];
+  /** Reloads the agent's session, which starts it under a new usage scope, as a resume does. */
+  resumeAgent(agent: MockAgentSession): Promise<void>;
 }
 
 /**
@@ -166,6 +248,8 @@ export async function scriptAgentUsage(page: Page): Promise<AgentUsageScript> {
       usage
         .listRequests()
         .flatMap((request) => (request.forceRefresh && request.agentId ? [request.agentId] : [])),
+    resumeAgent: (agent) =>
+      usage.untilUsageScopeChanges(agent.agentId, () => agent.client.refreshAgent(agent.agentId)),
   };
 }
 
diff --git a/packages/app/e2e/support/helpers/daemon-websocket-gate.ts b/packages/app/e2e/support/helpers/daemon-websocket-gate.ts
index bff52fc3f7..c33976879f 100644
--- a/packages/app/e2e/support/helpers/daemon-websocket-gate.ts
+++ b/packages/app/e2e/support/helpers/daemon-websocket-gate.ts
@@ -1,5 +1,5 @@
 import type { Page, WebSocketRoute } from "@playwright/test";
-import { daemonWsRoutePattern } from "./daemon-port";
+import { daemonWsRoutePattern, wsRoutePatternForPort } from "./daemon-port";
 
 export interface DirectoryBootstrapCounts {
   agents: number;
@@ -294,7 +294,8 @@ function recordClientRequest(
   directoryStarts.total[directory] += 1;
 }
 
-export async function installDaemonWebSocketGate(page: Page) {
+/** Gates the shared E2E daemon, or the daemon on `port` for a spec that runs its own. */
+export async function installDaemonWebSocketGate(page: Page, options: { port?: number } = {}) {
   let acceptingConnections = true;
   let reconnectWithFreshClient = false;
   let suppressAgentStream = false;
@@ -445,7 +446,11 @@ export async function installDaemonWebSocketGate(page: Page) {
     return true;
   };
 
-  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+  const routePattern =
+    options.port === undefined
+      ? daemonWsRoutePattern()
+      : wsRoutePatternForPort(String(options.port));
+  await page.routeWebSocket(routePattern, (ws) => {
     if (!acceptingConnections) {
       blockedConnectionCount += 1;
       for (const resolve of blockedConnectionWaiters) resolve();
diff --git a/packages/app/e2e/support/helpers/diagram.ts b/packages/app/e2e/support/helpers/diagram.ts
index 82fd745de1..48ecc60086 100644
--- a/packages/app/e2e/support/helpers/diagram.ts
+++ b/packages/app/e2e/support/helpers/diagram.ts
@@ -148,3 +148,59 @@ export async function expectFullscreenDiagram(
 export async function expectFullscreenDiagramClosed(page: Page): Promise<void> {
   await expect(page.getByTestId(FULLSCREEN_VIEWPORT)).toHaveCount(0);
 }
+
+/** Tall diagrams stay within the screen so their controls remain reachable. */
+export async function expectInlineDiagramFitsViewport(page: Page): Promise<void> {
+  const viewport = page.getByTestId("mermaid-viewport").last();
+  const box = await viewport.boundingBox();
+  expect(box, "the inline diagram has measurable layout").not.toBeNull();
+  const screenHeight = page.viewportSize()!.height;
+  expect(box!.height, "the inline diagram fits within the screen").toBeLessThan(screenHeight);
+  const contentHeight = await diagramSvg(page, "mermaid-viewport").evaluate(
+    (svg) => (svg as SVGSVGElement).viewBox.baseVal.height,
+  );
+  expect(box!.height, "a tall diagram is bounded rather than expanding the chat").toBeLessThan(
+    contentHeight,
+  );
+}
+
+/** Exercise pointer toggles and the controls encountered along that same journey. */
+export async function toggleDiagramSourceAndVerifyControls(page: Page): Promise<void> {
+  const viewport = page.getByTestId("mermaid-viewport").last();
+  const iframe = await viewport.locator("iframe").elementHandle();
+  for (let iteration = 0; iteration < 3; iteration++) {
+    await viewport.hover();
+    await page.getByRole("button", { name: "View source" }).last().click();
+    const viewDiagram = page.getByRole("button", { name: "View diagram" }).last();
+    await viewDiagram.click({ timeout: 10_000 });
+    await expect(viewDiagram).toHaveCount(0);
+    await expectFullscreenDiagramClosed(page);
+    expect(
+      await viewport.locator("iframe").evaluate((node, original) => node === original, iframe),
+      "switching views preserves the rendered diagram",
+    ).toBe(true);
+  }
+  await viewport.hover();
+  await page.getByRole("button", { name: "View source" }).last().click();
+  const hiddenFullscreen = viewport.getByRole("button", {
+    name: "Fullscreen",
+    includeHidden: true,
+  });
+  await hiddenFullscreen.focus();
+  await expect(hiddenFullscreen).not.toBeFocused();
+  await page.getByRole("button", { name: "View diagram" }).last().click();
+  await viewport.hover();
+  const fullscreen = viewport.getByRole("button", { name: "Fullscreen", exact: true });
+  const box = await viewport.boundingBox();
+  const control = await fullscreen.boundingBox();
+  expect(box).not.toBeNull();
+  expect(control).not.toBeNull();
+  expect(control!.y, "the toolbar starts inside the preview").toBeGreaterThanOrEqual(box!.y);
+  expect(control!.y + control!.height, "the toolbar fits inside the preview").toBeLessThanOrEqual(
+    box!.y + box!.height,
+  );
+  await viewport.getByRole("button", { name: "Zoom in" }).click();
+  await expect(viewport.getByRole("button", { name: "Reset view" })).toBeEnabled();
+  await viewport.getByRole("button", { name: "Reset view" }).click();
+  await expect(viewport.getByRole("button", { name: "Reset view" })).toBeDisabled();
+}
diff --git a/packages/app/e2e/support/helpers/directory-listing-gate.ts b/packages/app/e2e/support/helpers/directory-listing-gate.ts
new file mode 100644
index 0000000000..4e9dd8dc10
--- /dev/null
+++ b/packages/app/e2e/support/helpers/directory-listing-gate.ts
@@ -0,0 +1,44 @@
+import type { Page, WebSocketRoute } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+function listingResponse(message: string | Buffer) {
+  try {
+    const envelope = JSON.parse(message.toString());
+    return envelope.message?.type === "file_explorer_response" ? envelope.message.payload : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Delay one real directory response after the daemon has read its contents. */
+export async function delayDirectoryListingResponse(page: Page, directoryPath: string) {
+  let held: { socket: WebSocketRoute; message: string | Buffer; requestId: string } | null = null;
+  let resolveHeld!: () => void;
+  const heldResponse = new Promise<void>((resolve) => {
+    resolveHeld = resolve;
+  });
+  await page.routeWebSocket(daemonWsRoutePattern(), (socket) => {
+    const server = socket.connectToServer();
+    socket.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      const response = listingResponse(message);
+      if (!held && response?.mode === "list" && response.path === directoryPath) {
+        held = { socket, message, requestId: response.requestId };
+        resolveHeld();
+        return;
+      }
+      socket.send(message);
+    });
+  });
+  return {
+    waitUntilHeld: () => heldResponse,
+    release: async () => {
+      if (!held) throw new Error("Directory response must be held before release");
+      held.socket.send(held.message);
+      // Let the delivered reply update the UI before the user reopens the folder.
+      await page.evaluate(
+        () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve())),
+      );
+    },
+  };
+}
diff --git a/packages/app/e2e/support/helpers/host-confirmation.ts b/packages/app/e2e/support/helpers/host-confirmation.ts
index f6de576fc0..ea2e2f8a17 100644
--- a/packages/app/e2e/support/helpers/host-confirmation.ts
+++ b/packages/app/e2e/support/helpers/host-confirmation.ts
@@ -1,7 +1,5 @@
 import { expect, type Locator, type Page } from "@playwright/test";
 
-const EXTRA_HOSTS_KEY = "@paseo:e2e-extra-hosts";
-
 export interface LinkedHost {
   serverId: string;
   relayEndpoint: string;
@@ -31,31 +29,17 @@ export async function openPairingLink(page: Page, link: string): Promise<void> {
   await page.goto(link);
 }
 
-/** Saves a relay host before the app loads, as if it had been paired in an earlier session. */
-export async function saveLinkedHostBeforeLoad(page: Page, host: LinkedHost): Promise<void> {
-  await page.goto("/");
-  const nowIso = new Date().toISOString();
-  const connectionId = `relay:${host.relayEndpoint}`;
-  const savedHost = {
-    serverId: host.serverId,
-    label: host.serverId,
-    connections: [
-      {
-        id: connectionId,
-        type: "relay",
-        relayEndpoint: host.relayEndpoint,
-        useTls: false,
-        daemonPublicKeyB64: host.daemonPublicKeyB64,
-      },
-    ],
-    preferredConnectionId: connectionId,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-  await page.evaluate(({ key, hosts }) => localStorage.setItem(key, JSON.stringify(hosts)), {
-    key: EXTRA_HOSTS_KEY,
-    hosts: [savedHost],
-  });
+/** Reopens a link from a fresh document while retaining hosts saved through the UI. */
+export async function reopenPairingLinkWithSavedHosts(page: Page, link: string): Promise<void> {
+  for (const target of ["/", link]) {
+    // The fixture otherwise replaces the registry on every document load.
+    await page.evaluate(() => {
+      const nonce = localStorage.getItem("@paseo:e2e-seed-nonce");
+      if (!nonce) throw new Error("Expected the e2e seed nonce before reopening a pairing link.");
+      localStorage.setItem("@paseo:e2e-disable-default-seed-once", nonce);
+    });
+    await page.goto(target);
+  }
 }
 
 export function hostConfirmation(page: Page): Locator {
diff --git a/packages/app/e2e/support/helpers/hosts.ts b/packages/app/e2e/support/helpers/hosts.ts
index 95b1d17d5b..0e0a9f56fe 100644
--- a/packages/app/e2e/support/helpers/hosts.ts
+++ b/packages/app/e2e/support/helpers/hosts.ts
@@ -22,15 +22,27 @@ export async function addOfflineHostAndReload(
   page: Page,
   input: { serverId: string; label: string; primaryLabel?: string },
 ): Promise<void> {
-  const offlineHost = buildSeededHost({
-    serverId: input.serverId,
-    label: input.label,
-    endpoint: "127.0.0.1:59999",
-    nowIso: new Date().toISOString(),
-  });
+  await addOfflineHostsAndReload(page, [input], { primaryLabel: input.primaryLabel });
+}
+
+/** Adds several unreachable hosts with one reload. See `addOfflineHostAndReload`. */
+export async function addOfflineHostsAndReload(
+  page: Page,
+  hosts: Array<{ serverId: string; label: string }>,
+  options: { primaryLabel?: string } = {},
+): Promise<void> {
+  const nowIso = new Date().toISOString();
+  const offlineHosts = hosts.map((host) =>
+    buildSeededHost({
+      serverId: host.serverId,
+      label: host.label,
+      endpoint: "127.0.0.1:59999",
+      nowIso,
+    }),
+  );
 
   await page.evaluate(
-    ({ host, keys, primaryLabel }) => {
+    ({ hosts: added, keys, primaryLabel }) => {
       const nonce = localStorage.getItem(keys.nonce);
       if (!nonce) {
         throw new Error("Expected the e2e seed nonce before overriding the host registry.");
@@ -40,20 +52,22 @@ export async function addOfflineHostAndReload(
       if (primaryLabel && registry[0]) {
         registry[0].label = primaryLabel;
       }
-      if (!registry.some((entry) => entry.serverId === host.serverId)) {
-        registry.push(host);
+      for (const host of added) {
+        if (!registry.some((entry) => entry.serverId === host.serverId)) {
+          registry.push(host);
+        }
       }
       localStorage.setItem(keys.registry, JSON.stringify(registry));
       localStorage.setItem(keys.disableSeedOnce, nonce);
     },
     {
-      host: offlineHost,
+      hosts: offlineHosts,
       keys: {
         registry: REGISTRY_KEY,
         nonce: SEED_NONCE_KEY,
         disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
       },
-      primaryLabel: input.primaryLabel,
+      primaryLabel: options.primaryLabel,
     },
   );
 
@@ -273,3 +287,25 @@ export async function reloadPreservingHostRegistry(page: Page): Promise<void> {
   );
   await page.reload();
 }
+
+export async function disconnectAllHostsAndReload(page: Page): Promise<void> {
+  await page.evaluate(
+    ({ registryKey, nonceKey, disableSeedKey }) => {
+      const nonce = localStorage.getItem(nonceKey);
+      if (!nonce) throw new Error("Expected the e2e seed nonce");
+      const hosts = JSON.parse(localStorage.getItem(registryKey) ?? "[]");
+      for (const host of hosts) {
+        host.connections = [{ id: "offline", type: "directTcp", endpoint: "127.0.0.1:59999" }];
+        host.preferredConnectionId = "offline";
+      }
+      localStorage.setItem(registryKey, JSON.stringify(hosts));
+      localStorage.setItem(disableSeedKey, nonce);
+    },
+    {
+      registryKey: REGISTRY_KEY,
+      nonceKey: SEED_NONCE_KEY,
+      disableSeedKey: DISABLE_DEFAULT_SEED_ONCE_KEY,
+    },
+  );
+  await page.reload();
+}
diff --git a/packages/app/e2e/support/helpers/isolated-host-daemon.ts b/packages/app/e2e/support/helpers/isolated-host-daemon.ts
index c8dd3eaa44..dea61c3a37 100644
--- a/packages/app/e2e/support/helpers/isolated-host-daemon.ts
+++ b/packages/app/e2e/support/helpers/isolated-host-daemon.ts
@@ -25,6 +25,8 @@ export interface IsolatedHostDaemon {
 }
 
 export interface IsolatedHostDaemonOptions {
+  /** Written to the daemon's config.json; `mutableRelay` adds `daemon.relay` to it. */
+  config?: { daemon?: Record<string, unknown>; [key: string]: unknown };
   environment?: NodeJS.ProcessEnv;
   mutableRelay?: {
     enabled: boolean;
@@ -93,6 +95,28 @@ async function waitForServer(port: number, child: ChildProcess): Promise<void> {
   );
 }
 
+function withMutableRelay(
+  config: NonNullable<IsolatedHostDaemonOptions["config"]>,
+  relay: NonNullable<IsolatedHostDaemonOptions["mutableRelay"]>,
+): NonNullable<IsolatedHostDaemonOptions["config"]> {
+  const endpoint =
+    relay.endpoint ??
+    (process.env.E2E_RELAY_PORT ? `127.0.0.1:${process.env.E2E_RELAY_PORT}` : "127.0.0.1:9");
+  return {
+    ...config,
+    daemon: {
+      ...config.daemon,
+      relay: {
+        enabled: relay.enabled,
+        endpoint,
+        publicEndpoint: endpoint,
+        useTls: false,
+        publicUseTls: false,
+      },
+    },
+  };
+}
+
 export async function startIsolatedHostDaemon(
   serverId: string,
   options: IsolatedHostDaemonOptions = {},
@@ -138,24 +162,13 @@ export async function startIsolatedHostDaemon(
       throw error;
     }
   }
-  if (options.mutableRelay) {
-    const endpoint =
-      options.mutableRelay.endpoint ??
-      (process.env.E2E_RELAY_PORT ? `127.0.0.1:${process.env.E2E_RELAY_PORT}` : "127.0.0.1:9");
+  const config = options.mutableRelay
+    ? withMutableRelay(options.config ?? {}, options.mutableRelay)
+    : options.config;
+  if (config) {
     await writeFile(
       path.join(paseoHome, "config.json"),
-      `${JSON.stringify({
-        version: 1,
-        daemon: {
-          relay: {
-            enabled: options.mutableRelay.enabled,
-            endpoint,
-            publicEndpoint: endpoint,
-            useTls: false,
-            publicUseTls: false,
-          },
-        },
-      })}\n`,
+      `${JSON.stringify({ version: 1, ...config })}\n`,
     );
   }
   const serverDir = publishedPackageRoot
diff --git a/packages/app/e2e/support/helpers/new-workspace.ts b/packages/app/e2e/support/helpers/new-workspace.ts
index 63034d52a3..23696cf4ce 100644
--- a/packages/app/e2e/support/helpers/new-workspace.ts
+++ b/packages/app/e2e/support/helpers/new-workspace.ts
@@ -17,6 +17,8 @@ type NewWorkspaceDaemonClient = Pick<
   | "connect"
   | "createPaseoWorktree"
   | "createWorkspace"
+  | "createTerminal"
+  | "killTerminal"
   | "fetchAgents"
   | "fetchWorkspaces"
   | "getPaseoWorktreeList"
@@ -34,6 +36,7 @@ type NewWorkspaceDaemonClient = Pick<
   | "removePlugin"
   | "reloadPlugin"
   | "setWorkspaceTitle"
+  | "setWorkspaceLabel"
 >;
 
 type CreateWorkspacePayload = Awaited<ReturnType<NewWorkspaceDaemonClient["createWorkspace"]>>;
diff --git a/packages/app/e2e/support/helpers/onboarding.ts b/packages/app/e2e/support/helpers/onboarding.ts
new file mode 100644
index 0000000000..4226c1c27e
--- /dev/null
+++ b/packages/app/e2e/support/helpers/onboarding.ts
@@ -0,0 +1,278 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, type Locator, type Page } from "@playwright/test";
+import type { DaemonClient as InternalDaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { addProjectFlow, addProjectFlowInput, chooseAddProjectMethod } from "./add-project-flow";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { buildCreateAgentPreferences, buildSeededHost } from "./daemon-registry";
+import { startIsolatedHostDaemon, type IsolatedHostDaemonOptions } from "./isolated-host-daemon";
+
+/** Points a fresh browser profile at one host, with no first-run record and no app settings. */
+export async function openAppAsNewUser(
+  page: Page,
+  host: { serverId: string; port: number },
+): Promise<void> {
+  const seededHost = buildSeededHost({
+    serverId: host.serverId,
+    endpoint: `127.0.0.1:${host.port}`,
+    nowIso: new Date().toISOString(),
+  });
+  await page.route(/:6767\b/, (route) => route.abort());
+  await page.routeWebSocket(/:6767\b/, async (webSocket) => {
+    await webSocket.close({ code: 1008, reason: "Blocked developer daemon during e2e." });
+  });
+  await page.addInitScript(
+    ({ registryHost, preferences }) => {
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([registryHost]));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+    },
+    { registryHost: seededHost, preferences: buildCreateAgentPreferences() },
+  );
+  await page.goto("/");
+}
+
+interface FirstLaunchRecord {
+  appBeforeSetup: boolean;
+  setupOpacityOnArrival: number | null;
+}
+
+/**
+ * Watches the page from its first paint: whether the app's sidebar or home showed before setup,
+ * and how opaque setup was when it arrived. Call before `openAppAsNewUser`.
+ */
+export async function recordFirstLaunch(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const record: FirstLaunchRecord = { appBeforeSetup: false, setupOpacityOnArrival: null };
+    Object.assign(window, { __firstLaunch: record });
+    const observer = new MutationObserver(() => {
+      const setup = document.querySelector('[data-testid="onboarding-modal"] [role="dialog"]');
+      if (setup) {
+        record.setupOpacityOnArrival = Number(getComputedStyle(setup).opacity);
+        observer.disconnect();
+        return;
+      }
+      if (
+        document.querySelector(
+          '[data-testid="open-project-submit"], [data-testid="sidebar-settings"]',
+        )
+      ) {
+        record.appBeforeSetup = true;
+      }
+    });
+    observer.observe(document, { childList: true, subtree: true });
+  });
+}
+
+export async function readFirstLaunch(page: Page): Promise<FirstLaunchRecord> {
+  return page.evaluate(
+    () => (window as unknown as { __firstLaunch: FirstLaunchRecord }).__firstLaunch,
+  );
+}
+
+/** The loading screen the app shows while it starts. */
+export function loadingScreen(page: Page): Locator {
+  return page.getByTestId("startup-splash");
+}
+
+/** The empty home a host with no projects lands on. */
+export function emptyHome(page: Page): Locator {
+  return page.getByTestId("open-project-submit");
+}
+
+export function setupModal(page: Page): Locator {
+  return page.getByTestId("onboarding-modal").getByRole("dialog");
+}
+
+export async function expectSetupStep(page: Page, title: string): Promise<void> {
+  await expect(setupModal(page).getByRole("heading", { name: title, exact: true })).toBeVisible({
+    timeout: 60_000,
+  });
+}
+
+export async function pickTheme(page: Page, name: string): Promise<void> {
+  const tile = setupModal(page).getByRole("radio", { name, exact: true });
+  await tile.click();
+  await expect(tile).toBeChecked();
+}
+
+export async function continueSetup(page: Page): Promise<void> {
+  await setupModal(page).getByRole("button", { name: "Continue", exact: true }).click();
+}
+
+export async function skipSetup(page: Page): Promise<void> {
+  await setupModal(page).getByRole("button", { name: "Skip setup", exact: true }).click();
+  await expect(setupModal(page)).toHaveCount(0);
+}
+
+/** Adds a folder through the regular Add project flow, opened from the setup's Projects step. */
+export async function addProjectFromSetup(page: Page, projectPath: string): Promise<void> {
+  await setupModal(page).getByRole("button", { name: "Add project", exact: true }).click();
+  await expect(addProjectFlow(page)).toBeVisible({ timeout: 30_000 });
+  await chooseAddProjectMethod(page, "directory-search");
+  await addProjectFlowInput(page).fill(projectPath);
+  await page.keyboard.press("Enter");
+  await expect(addProjectFlow(page)).toHaveCount(0, { timeout: 30_000 });
+}
+
+export async function showSetupAgainFromSettings(page: Page): Promise<void> {
+  await page.locator('[data-testid="sidebar-settings"]:visible').first().click();
+  await page.getByRole("button", { name: "Show setup again", exact: true }).click();
+}
+
+export async function goToSetupStep(page: Page, label: string): Promise<void> {
+  await setupModal(page).getByRole("tab", { name: label, exact: true }).click();
+}
+
+export function paseoToolsSwitch(scope: Page | Locator): Locator {
+  return scope.getByRole("switch", { name: "Inject Paseo tools", exact: true });
+}
+
+/** Whether the host gives its agents Paseo tools, read from the host itself. */
+export async function hostGivesAgentsPaseoTools(host: { port: number }): Promise<boolean> {
+  const client = await connectDaemonClient<
+    Pick<InternalDaemonClient, "connect" | "close" | "getDaemonConfig">
+  >({ clientIdPrefix: "app-e2e-onboarding", port: host.port });
+  try {
+    return (await client.getDaemonConfig()).config.mcp.injectIntoAgents !== false;
+  } finally {
+    await client.close();
+  }
+}
+
+export async function finishSetup(page: Page): Promise<void> {
+  await setupModal(page).getByRole("button", { name: "Finish", exact: true }).click();
+  await expect(setupModal(page)).toHaveCount(0);
+}
+
+/** Opens the Phone step's Relay row: the pair device modal, over setup. */
+export async function openRelayPairingFromSetup(page: Page): Promise<Locator> {
+  await setupModal(page).getByRole("button", { name: "Relay", exact: true }).click();
+  const pairing = page.getByTestId("onboarding-pair-device-card");
+  await expect(pairing).toBeVisible();
+  return pairing;
+}
+
+export async function closeRelayPairing(pairing: Locator): Promise<void> {
+  await pairing.getByRole("button", { name: "Close", exact: true }).click();
+  await expect(pairing).toHaveCount(0);
+}
+
+/** Clicks the Phone step's Tailscale row and returns the docs page it opened. */
+export async function openTailscaleDocsFromSetup(page: Page): Promise<string> {
+  await page
+    .context()
+    .route("https://paseo.sh/**", (route) =>
+      route.fulfill({ contentType: "text/html", body: "<title>Paseo docs</title>" }),
+    );
+  const popup = page.waitForEvent("popup");
+  await setupModal(page).getByRole("link", { name: "Tailscale, Docs", exact: true }).click();
+  const docs = await popup;
+  await docs.waitForLoadState("domcontentloaded");
+  const url = docs.url();
+  await docs.close();
+  return url;
+}
+
+export interface SetupHost {
+  serverId: string;
+  port: number;
+  close(): Promise<void>;
+}
+
+/**
+ * An isolated host whose only agent history is the Claude sessions given here, so suggestions
+ * never depend on the machine running the test. Its HOME is a scratch folder, so the skills setup
+ * installs never land in the real ~/.agents, ~/.claude or ~/.codex. `withBrokenProvider` adds a
+ * provider that cannot start.
+ */
+export async function startSetupHost(
+  label: string,
+  options: {
+    claudeSessionsIn?: readonly string[];
+    withBrokenProvider?: boolean;
+    mutableRelay?: IsolatedHostDaemonOptions["mutableRelay"];
+  } = {},
+): Promise<SetupHost> {
+  const serverId = `srv_onboarding_${label}_${randomUUID().replaceAll("-", "").slice(0, 8)}`;
+  const claudeConfigDir = await seedClaudeHistory(options.claudeSessionsIn ?? []);
+  const home = await mkdtemp(path.join(tmpdir(), "paseo-onboarding-home-"));
+  const daemon = await startIsolatedHostDaemon(serverId, {
+    config: claudeOnlyConfig({ withBrokenProvider: options.withBrokenProvider ?? false }),
+    environment: { ...process.env, HOME: home, CLAUDE_CONFIG_DIR: claudeConfigDir },
+    mutableRelay: options.mutableRelay,
+  });
+  return {
+    serverId,
+    port: daemon.port,
+    close: async () => {
+      await daemon.close();
+      await rm(claudeConfigDir, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    },
+  };
+}
+
+/** Writes one recent Claude session per folder into a fresh CLAUDE_CONFIG_DIR. */
+async function seedClaudeHistory(cwds: readonly string[]): Promise<string> {
+  const configDir = await mkdtemp(path.join(tmpdir(), "paseo-onboarding-claude-"));
+  const newest = Date.now() - 60_000;
+  for (const [index, cwd] of cwds.entries()) {
+    const sessionId = `onboarding-session-${index + 1}`;
+    const projectDir = path.join(configDir, "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"));
+    await mkdir(projectDir, { recursive: true });
+    const sessionPath = path.join(projectDir, `${sessionId}.jsonl`);
+    const record = {
+      type: "user",
+      uuid: `${sessionId}-user`,
+      message: { role: "user", content: `Work on session ${index + 1}` },
+      cwd,
+      sessionId,
+    };
+    await writeFile(sessionPath, `${JSON.stringify(record)}\n`);
+    const timestamp = new Date(newest - index * 60_000);
+    await utimes(sessionPath, timestamp, timestamp);
+  }
+  return configDir;
+}
+
+function claudeOnlyConfig(options: { withBrokenProvider: boolean }) {
+  const brokenProvider = {
+    "broken-acp": {
+      extends: "acp",
+      label: "Broken ACP",
+      command: ["missing-agent-command", "acp"],
+    },
+  };
+  return {
+    agents: {
+      providers: {
+        codex: { enabled: false },
+        copilot: { enabled: false },
+        omp: { enabled: false },
+        opencode: { enabled: false },
+        pi: { enabled: false },
+        ...(options.withBrokenProvider ? brokenProvider : {}),
+      },
+    },
+  };
+}
+
+/** The switch that picks a suggested project for adding. */
+export function projectSuggestion(page: Page, name: string): Locator {
+  return setupModal(page).getByRole("switch", { name, exact: true });
+}
+
+/** The whole suggestion row, with its path, last use and any add error beside the switch. */
+export function projectSuggestionRow(page: Page, name: string): Locator {
+  return setupModal(page)
+    .getByTestId("project-suggestion")
+    .filter({ has: page.getByRole("switch", { name, exact: true }) });
+}
+
+/** The footer's main button, which adds the checked suggestions when there are any. */
+export function setupPrimaryButton(page: Page, label: string): Locator {
+  return setupModal(page).getByRole("button", { name: label, exact: true });
+}
diff --git a/packages/app/e2e/support/helpers/plugin-buttons.ts b/packages/app/e2e/support/helpers/plugin-buttons.ts
index 2418f284d2..b28050fd00 100644
--- a/packages/app/e2e/support/helpers/plugin-buttons.ts
+++ b/packages/app/e2e/support/helpers/plugin-buttons.ts
@@ -4,6 +4,9 @@ import path from "node:path";
 import type { Locator, TestInfo } from "@playwright/test";
 import { test, expect, type Page } from "@playwright/test";
 import { gotoAppShell } from "./app";
+import { scrollAgentChatToBottom, waitForScrollableChat } from "./agent-bottom-anchor";
+import { expectTurnCopyButton } from "./agent-stream";
+import { submitMessage } from "./composer";
 import { buildAgentRoute } from "./mock-agent";
 import { openCommandCenter } from "./command-center";
 import {
@@ -88,7 +91,7 @@ export default function contribute(client) {
   header("locked", { title: "Production locked", icon: "Lock", disabled: true, behavior: { kind: "action", onPress() {} } });
   const review = pill("review", { title: "Run review", icon: "Scan", label: "Review", behavior: { kind: "action", async onPress() { await new Promise((resolve) => { finishReview = resolve; }); review.update({ label: "Reviewed" }); } } });
   const pillMenu = pill("checks", { title: "Composer checks", icon: "ListChecks", label: "Checks", behavior: menu });
-  pill("usage", { title: "Composer status", icon: StatusIcon, label: "Status", behavior: { kind: "popover", Content: Details } });
+  const usage = pill("usage", { title: "Composer status", icon: StatusIcon, label: "Status", behavior: { kind: "popover", Content: Details } });
   const command = (id, title, onSelect) => client.addCommandCenterItem({ id, title, icon: "Settings", context: "workspace", onSelect });
   command("finish", "Finish deployment", () => finish());
   command("finish-review", "Finish review", () => finishReview());
@@ -102,10 +105,16 @@ export default function contribute(client) {
   command("hide-menu", "Hide composer menu", () => pillMenu.update({ visible: false }));
   command("show-menu", "Show composer menu", () => pillMenu.update({ visible: true }));
   const lifetime = new AbortController();
+  let pillsHidden = false;
   const applyWorkspace = (workspace) => {
     if (workspace.id !== workspaceId) return;
+    const hidePills = workspace.name === "No composer pills";
     deploy.update({ visible: workspace.name !== "Compact checks" });
-    pillMenu.update({ visible: workspace.name !== "Hide composer menu" });
+    pillMenu.update({ visible: workspace.name !== "Hide composer menu" && !hidePills });
+    if (hidePills === pillsHidden) return;
+    pillsHidden = hidePills;
+    review.update({ visible: !hidePills });
+    usage.update({ visible: !hidePills });
   };
   void client.paseo.workspaces.list({ subscribe: {}, signal: lifetime.signal }).then(({ subscription }) => {
     subscription.subscribe({
@@ -244,6 +253,38 @@ async function captureSchemes(page: Page, info: TestInfo, name: string, subject:
   await page.emulateMedia({ colorScheme: "light" });
 }
 
+const COMPOSER_PILLS = ["Run review", "Composer checks", "Composer status"] as const;
+
+function chevronOf(page: Page, title: string): Locator {
+  return page
+    .getByRole("button", { name: title, exact: true })
+    .getByTestId("plugin-button-chevron");
+}
+
+/** Composer pills that open a menu or popover carry a chevron; a one-tap action does not. */
+async function expectComposerPillChevrons(page: Page) {
+  await expect(chevronOf(page, "Composer checks")).toHaveCount(1);
+  await expect(chevronOf(page, "Composer status")).toHaveCount(1);
+  await expect(chevronOf(page, "Run review")).toHaveCount(0);
+}
+
+async function setComposerPillsShown(
+  page: Page,
+  showcase: { setTitle(title: string): Promise<unknown> },
+  shown: boolean,
+) {
+  await showcase.setTitle(shown ? "Button showcase" : "No composer pills");
+  for (const title of COMPOSER_PILLS) {
+    await expect(page.getByRole("button", { name: title, exact: true })).toHaveCount(shown ? 1 : 0);
+  }
+}
+
+async function lastTurnTop(page: Page): Promise<number> {
+  const box = await page.getByRole("button", { name: "Copy turn" }).last().boundingBox();
+  expect(box).not.toBeNull();
+  return box!.y;
+}
+
 async function expectHeaderTextTruncated(page: Page) {
   const title = page.getByTestId("workspace-header-title");
   const subtitle = page.getByTestId("workspace-header-subtitle");
@@ -276,6 +317,7 @@ export async function withButtonShowcase(
   run: (buttons: {
     openWideMenusAndPopovers(): Promise<void>;
     runAndUpdateActions(): Promise<void>;
+    keepTrackSpaceWithoutPills(): Promise<void>;
     openCompactSheets(): Promise<void>;
     useCompactWorkspaceMenu(): Promise<void>;
     hideAndUnloadOpenButtons(): Promise<void>;
@@ -348,11 +390,7 @@ export async function withButtonShowcase(
               .getByRole("button", { name: "Header checks", exact: true })
               .getByTestId("plugin-button-chevron"),
           ).toHaveCount(1);
-          await expect(
-            page
-              .getByRole("button", { name: "Composer checks", exact: true })
-              .getByTestId("plugin-button-chevron"),
-          ).toHaveCount(0);
+          await expectComposerPillChevrons(page);
           await expectSurfaceVisible(page);
           await captureSchemes(
             page,
@@ -476,10 +514,31 @@ export async function withButtonShowcase(
             "Review ready",
           );
         }),
+      keepTrackSpaceWithoutPills: () =>
+        test.step("the composer track keeps its space when every pill leaves and returns", async () => {
+          await page.setViewportSize(WIDE);
+          await submitMessage(page, "Stream a turn under the composer pills");
+          await expectTurnCopyButton(page);
+          await waitForScrollableChat(page, { minScrollableDistance: 200, timeout: 30_000 });
+          for (const viewport of [WIDE, COMPACT]) {
+            await page.setViewportSize(viewport);
+            await scrollAgentChatToBottom(page);
+            const top = await lastTurnTop(page);
+            await setComposerPillsShown(page, showcase, false);
+            expect(await lastTurnTop(page)).toBe(top);
+            await setComposerPillsShown(page, showcase, true);
+            expect(await lastTurnTop(page)).toBe(top);
+          }
+          await page.setViewportSize(WIDE);
+        }),
       openCompactSheets: () =>
         test.step("compact header leaves plugin actions to the workspace menu while composer triggers open sheets", async () => {
           await page.setViewportSize(COMPACT);
-          await expect(page.getByTestId("plugin-button-chevron")).toHaveCount(0);
+          await expect(
+            page.getByRole("toolbar", { name: "Workspace actions", exact: true }),
+          ).toHaveCount(0);
+          await expectComposerPillChevrons(page);
+          await expect(page.getByTestId("plugin-button-chevron")).toHaveCount(2);
           await expect(
             page.getByRole("button", { name: "Composer checks", exact: true }),
           ).toContainText("Checks");
diff --git a/packages/app/e2e/support/helpers/plugin-composer-items.ts b/packages/app/e2e/support/helpers/plugin-composer-items.ts
new file mode 100644
index 0000000000..678c9544da
--- /dev/null
+++ b/packages/app/e2e/support/helpers/plugin-composer-items.ts
@@ -0,0 +1,295 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test, type Page } from "@playwright/test";
+import { gotoAppShell } from "./app";
+import { openAgentRoute } from "./mock-agent";
+import { connectNewWorkspaceDaemonClient } from "./new-workspace";
+import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
+import { seedWorkspace } from "./seed-client";
+
+const PLUGIN_ID = "composer-controls-example";
+const NARROW = { width: 500, height: 800 };
+
+/** Runs `run` in an agent's composer with the composer-controls example installed. */
+export async function withComposerControlsExample(
+  page: Page,
+  run: (composer: {
+    narrowTheWindow(): Promise<void>;
+    openAgentFeatures(): Promise<void>;
+    expectFeatureRow(name: string): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({
+    repoPrefix: "composer-items-",
+    title: "Composer items",
+  });
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: "Composer items agent",
+    model: "ten-second-stream",
+    modeId: "load-test",
+  });
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const example = await copyPluginExample("composer-controls");
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(example.directory);
+    await gotoAppShell(page);
+    await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: agent.id });
+    await run({
+      narrowTheWindow: () =>
+        test.step("narrow the window until the composer folds its controls away", () =>
+          page.setViewportSize(NARROW)),
+      openAgentFeatures: () =>
+        test.step("open the agent features sheet", async () => {
+          await page.getByRole("button", { name: "Open agent features", exact: true }).click();
+        }),
+      expectFeatureRow: (name) =>
+        test.step(`the sheet has a row for "${name}"`, () =>
+          expect(page.getByRole("button", { name, exact: true })).toBeVisible()),
+    });
+  } finally {
+    await client.removePlugin(PLUGIN_ID);
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await example.cleanup();
+    await workspace.cleanup();
+  }
+}
+
+const ONE_TOGGLE_PLUGIN_ID = "composer-toggle-and-watcher-e2e";
+const ONE_TOGGLE_NAME = "Sandbox flag";
+const ONE_TOGGLE_PLUGIN_SOURCE = `import { useComposer } from "@getpaseo/plugin/client";
+import { Toggle } from "@getpaseo/plugin/client/ui";
+import { useState } from "react";
+
+function PromptWatcher() {
+  useComposer();
+  return null;
+}
+
+function SandboxFlag() {
+  const [value, setValue] = useState(false);
+  return (
+    <Toggle
+      title="${ONE_TOGGLE_NAME}"
+      icon="Lock"
+      value={value}
+      onValueChange={({ value: next }) => setValue(next)}
+    />
+  );
+}
+
+export default function contribute(client) {
+  client.addComposerItem({ id: "prompt-watcher", Component: PromptWatcher });
+  client.addComposerItem({ id: "sandbox-flag", Component: SandboxFlag });
+  return () => {};
+}`;
+
+const PICKER_NAME = "Review state";
+const PICKER_PLUGIN_SOURCE = `import { Select } from "@getpaseo/plugin/client/ui";
+import { useState } from "react";
+
+const OPTIONS = [
+  { value: "draft", label: "Draft" },
+  { value: "ready", label: "Ready" },
+];
+
+function ReviewState() {
+  const [value, setValue] = useState("draft");
+  return (
+    <Select
+      title="${PICKER_NAME}"
+      icon="CircleDot"
+      value={value}
+      options={OPTIONS}
+      onValueChange={({ value: next }) => setValue(next)}
+    />
+  );
+}
+
+export default function contribute(client) {
+  client.addComposerItem({ id: "review-state", Component: ReviewState });
+  return () => {};
+}`;
+
+function toolbar(page: Page) {
+  return page.getByTestId("agent-controls-toolbar").filter({ visible: true }).first();
+}
+
+interface ToolbarFrame {
+  overflowButton: boolean;
+  clipped: boolean;
+}
+
+declare global {
+  interface Window {
+    __pluginToolbarFrames?: ToolbarFrame[];
+  }
+}
+
+/** From the first frame on, records whether the toolbar condensed or clipped. Call before loading. */
+export async function recordToolbarFramesFromLoad(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const frames: ToolbarFrame[] = [];
+    window.__pluginToolbarFrames = frames;
+    const tick = () => {
+      const row = Array.from(
+        document.querySelectorAll('[data-testid="agent-controls-toolbar"]'),
+      ).find((node) => node.getClientRects().length > 0);
+      if (row) {
+        frames.push({
+          overflowButton: row.querySelector('[data-testid="agent-controls-features"]') !== null,
+          clipped: row.scrollWidth > row.clientWidth,
+        });
+      }
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+}
+
+export async function expectToolbarNeverCondensedOrClipped(page: Page): Promise<void> {
+  const frames = await page.evaluate(() => window.__pluginToolbarFrames ?? []);
+  expect(frames.length).toBeGreaterThan(0);
+  expect(frames.filter((frame) => frame.overflowButton || frame.clipped)).toEqual([]);
+}
+
+function agentFeaturesButton(page: Page) {
+  return page.getByRole("button", { name: "Open agent features", exact: true });
+}
+
+interface ToolbarPluginComposer {
+  setWindowWidth(width: number): Promise<void>;
+  expectToolbarWidthBetween(min: number, max: number): Promise<void>;
+  expectToggleInlineAtFullDensity(): Promise<void>;
+  expectToggleInOverflow(): Promise<void>;
+  closeOverflowSheet(): Promise<void>;
+  startRecordingDensity(): Promise<void>;
+  expectAtMostOneDensityChange(): Promise<void>;
+  openInlinePicker(): Promise<void>;
+  expectPickerClosed(): Promise<void>;
+}
+
+/** Runs `run` in an agent's composer with one icon toggle and one item that renders nothing. */
+export function withToggleAndWatcherComposerItems(
+  page: Page,
+  run: (composer: ToolbarPluginComposer) => Promise<void>,
+) {
+  return withToolbarPlugin(page, ONE_TOGGLE_PLUGIN_SOURCE, run);
+}
+
+/** Runs `run` in an agent's composer with one plugin `Select` in the toolbar. */
+export function withPickerComposerItem(
+  page: Page,
+  run: (composer: ToolbarPluginComposer) => Promise<void>,
+) {
+  return withToolbarPlugin(page, PICKER_PLUGIN_SOURCE, run);
+}
+
+async function withToolbarPlugin(
+  page: Page,
+  pluginSource: string,
+  run: (composer: ToolbarPluginComposer) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({ repoPrefix: "composer-measured-items-" });
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: "Measured items agent",
+    model: "ten-second-stream",
+    modeId: "load-test",
+  });
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-composer-measured-items-"));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: ONE_TOGGLE_PLUGIN_ID, requirements: pluginRequirements }),
+  );
+  await writeFile(path.join(directory, "index.client.tsx"), pluginSource);
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    await gotoAppShell(page);
+    await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: agent.id });
+    await expect(toolbar(page)).toBeVisible({ timeout: 30_000 });
+    await run({
+      setWindowWidth: (width) =>
+        test.step(`set the window to ${width} wide`, () =>
+          page.setViewportSize({ width, height: 800 })),
+      expectToolbarWidthBetween: (min, max) =>
+        test.step(`the toolbar is between ${min} and ${max} wide`, async () => {
+          await expect
+            .poll(async () => (await toolbar(page).boundingBox())?.width ?? 0)
+            .toBeGreaterThanOrEqual(min);
+          expect((await toolbar(page).boundingBox())?.width ?? 0).toBeLessThanOrEqual(max);
+        }),
+      expectToggleInlineAtFullDensity: () =>
+        test.step("the toggle is inline and the toolbar keeps its labels", async () => {
+          const toggle = toolbar(page).getByRole("button", { name: ONE_TOGGLE_NAME, exact: true });
+          await expect(toggle).toBeVisible();
+          await expect(agentFeaturesButton(page)).toHaveCount(0);
+          await expect(toolbar(page).getByTestId("agent-thinking-selector")).toHaveText("Low");
+          const row = await toolbar(page).boundingBox();
+          const box = await toggle.boundingBox();
+          expect(box && row && box.x + box.width <= row.x + row.width).toBe(true);
+        }),
+      expectToggleInOverflow: () =>
+        test.step("the toggle has moved to the overflow sheet", async () => {
+          await expect(
+            toolbar(page).getByRole("button", { name: ONE_TOGGLE_NAME, exact: true }),
+          ).toHaveCount(0);
+          await agentFeaturesButton(page).click();
+          await expect(
+            page.getByRole("button", { name: ONE_TOGGLE_NAME, exact: true }),
+          ).toBeVisible();
+        }),
+      closeOverflowSheet: () =>
+        test.step("close the overflow sheet", async () => {
+          await page.keyboard.press("Escape");
+          await expect(page.getByTestId("agent-features-sheet")).toHaveCount(0);
+        }),
+      startRecordingDensity: () =>
+        test.step("record which density each frame paints", () =>
+          page.evaluate(() => {
+            const frames: boolean[] = [];
+            const paint = () => {
+              frames.push(
+                document.querySelector('[data-testid="agent-controls-features"]') !== null,
+              );
+              window.requestAnimationFrame(paint);
+            };
+            window.requestAnimationFrame(paint);
+            Object.assign(window, { __densityFrames: frames });
+          })),
+      expectAtMostOneDensityChange: () =>
+        test.step("the density changed once at most", async () => {
+          const changes = await page.evaluate(() => {
+            const frames = (window as unknown as { __densityFrames: boolean[] }).__densityFrames;
+            return frames.filter((frame, index) => index > 0 && frame !== frames[index - 1]).length;
+          });
+          expect(changes).toBeLessThanOrEqual(1);
+        }),
+      openInlinePicker: () =>
+        test.step("open the plugin picker from the toolbar", async () => {
+          await toolbar(page).getByRole("button", { name: PICKER_NAME, exact: true }).click();
+          await expect(page.getByTestId("combobox-desktop-container")).toBeVisible();
+        }),
+      expectPickerClosed: () =>
+        test.step("the plugin picker has closed", () =>
+          expect(page.getByTestId("combobox-desktop-container")).toHaveCount(0)),
+    });
+  } finally {
+    await client.removePlugin(ONE_TOGGLE_PLUGIN_ID);
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await rm(directory, { recursive: true, force: true });
+    await workspace.cleanup();
+  }
+}
diff --git a/packages/app/e2e/support/helpers/plugin-composers-by-reference.ts b/packages/app/e2e/support/helpers/plugin-composers-by-reference.ts
new file mode 100644
index 0000000000..bfba91d2e5
--- /dev/null
+++ b/packages/app/e2e/support/helpers/plugin-composers-by-reference.ts
@@ -0,0 +1,761 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test, type Page } from "@playwright/test";
+import { gotoAppShell } from "./app";
+import { attachComposerTestImage, openImageLightbox } from "./composer";
+import {
+  contextWindowDetails,
+  pressContextWindowMeter,
+  seedAgentWithContextWindow,
+} from "./context-window";
+import { gotoWorkspace } from "./launcher";
+import { openCommandCenter } from "./command-center";
+import { openAgentRoute, seedMockAgentWorkspace } from "./mock-agent";
+import { connectNewWorkspaceDaemonClient, openGlobalNewWorkspaceComposer } from "./new-workspace";
+import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
+import { seedWorkspace } from "./seed-client";
+import {
+  expectNoSheetOpen,
+  expectOpenTabCount,
+  promptMentioning,
+  sheet,
+  tapSheetBackdrop,
+} from "./sheet";
+import { openSubagentFromCompactTrack, seedSubagent } from "./subagents";
+import { getServerId } from "./server-id";
+import {
+  createAgentTabFromMenu,
+  dragTabIntoExplorer,
+  ensureExplorerSidebar,
+} from "./workspace-tabs";
+
+const WIDE = { width: 1440, height: 900 };
+const COMPACT = { width: 390, height: 844 };
+const CHECKLIST = "- [ ] Tests\n- [ ] Docs\n";
+const FILE_LINK = "linked.ts:3";
+
+type Workspace = Awaited<ReturnType<typeof seedWorkspace>>;
+
+function prompt(page: Page) {
+  return page.getByRole("textbox", { name: "Message agent..." });
+}
+
+async function createMockAgent(workspace: Workspace, title: string) {
+  return workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title,
+    model: "ten-second-stream",
+    modeId: "load-test",
+  });
+}
+
+async function runCommand(page: Page, title: string) {
+  const panel = await openCommandCenter(page);
+  await panel.getByTestId("command-center-input").fill(title);
+  await panel.getByRole("button", { name: title, exact: true }).click();
+  await expect(panel).not.toBeVisible();
+}
+
+export async function withComposerToolsExample(
+  page: Page,
+  run: (author: {
+    openComposerToolsInExplorer(): Promise<void>;
+    typeInComposer(text: string, cursorAfter: number): Promise<void>;
+    insertChecklistFromPanel(): Promise<void>;
+    expectComposerText(text: string): Promise<void>;
+    markForReviewFromCommandCenter(): Promise<void>;
+    focusANewAgentTab(): Promise<void>;
+    focusTheAgentTab(): Promise<void>;
+    expectPanelFocusedAgent(focused: boolean): Promise<void>;
+    expectPanelShowsReview(needsReview: boolean): Promise<void>;
+    useCompactLayout(): Promise<void>;
+    insertChecklistFromControlsSheet(): Promise<void>;
+    expectComposerReadyToType(text: string): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({ repoPrefix: "composer-tools-", title: "Composer tools" });
+  const agent = await createMockAgent(workspace, "Composer tools agent");
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const example = await copyPluginExample("composer-controls");
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(example.directory);
+    await page.setViewportSize(WIDE);
+    await gotoAppShell(page);
+    await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: agent.id });
+    await run({
+      openComposerToolsInExplorer: () =>
+        test.step("open the Composer tools panel in the Explorer", async () => {
+          const explorer = await ensureExplorerSidebar(page);
+          await explorer.getByRole("button", { name: "New tab", exact: true }).click();
+          await page
+            .getByTestId("workspace-new-tab-menu")
+            .filter({ visible: true })
+            .getByRole("menuitem", { name: "Composer tools", exact: true })
+            .click();
+          await expect(page.getByText("Focused agent: mock", { exact: true })).toBeVisible();
+        }),
+      typeInComposer: (text, cursorAfter) =>
+        test.step(`type "${text}" and put the cursor after ${cursorAfter} characters`, async () => {
+          const input = prompt(page);
+          await input.fill(text);
+          await input.press("Home");
+          for (let index = 0; index < cursorAfter; index += 1) await input.press("ArrowRight");
+        }),
+      insertChecklistFromPanel: () =>
+        test.step("press the panel's button", () =>
+          page
+            .getByRole("button", { name: "Insert checklist into the focused agent", exact: true })
+            .click()),
+      expectComposerText: (text) =>
+        test.step("the composer holds the text", () => expect(prompt(page)).toHaveValue(text)),
+      markForReviewFromCommandCenter: () =>
+        test.step("run the Command Center item", () =>
+          runCommand(page, "Composer controls: mark for review")),
+      focusANewAgentTab: () =>
+        test.step("focus a new agent tab, which is a draft", () => createAgentTabFromMenu(page)),
+      focusTheAgentTab: () =>
+        test.step("focus the running agent's tab again", () =>
+          page
+            .getByTestId(`workspace-tab-agent_${agent.id}`)
+            .filter({ visible: true })
+            .first()
+            .click({ position: { x: 12, y: 13 } })),
+      expectPanelFocusedAgent: (focused) =>
+        test.step(`the panel ${focused ? "names" : "has no"} focused agent`, async () => {
+          await expect(page.getByText("Focused agent: mock", { exact: true })).toHaveCount(
+            focused ? 1 : 0,
+          );
+          await expect(page.getByText("No agent is focused", { exact: true })).toHaveCount(
+            focused ? 0 : 1,
+          );
+        }),
+      expectPanelShowsReview: (needsReview) =>
+        test.step(`the panel's snapshot says needs review: ${needsReview}`, () =>
+          expect(
+            page.getByText(`Needs review: ${needsReview ? "yes" : "no"}`, { exact: true }),
+          ).toBeVisible()),
+      useCompactLayout: () =>
+        test.step("narrow the window to a phone", async () => {
+          await page.setViewportSize(COMPACT);
+          await expect(prompt(page).filter({ visible: true })).toBeVisible();
+        }),
+      insertChecklistFromControlsSheet: () =>
+        test.step("press the Action in the composer's controls sheet", async () => {
+          await page.getByRole("button", { name: /^Select model/ }).click();
+          await page.getByText("Insert checklist", { exact: true }).click();
+        }),
+      expectComposerReadyToType: (text) =>
+        test.step("the sheet is closed and the cursor is in the composer", async () => {
+          await expectNoSheetOpen(page);
+          const input = prompt(page).filter({ visible: true });
+          await expect(input).toHaveValue(text);
+          await expect(input).toBeFocused();
+        }),
+    });
+  } finally {
+    await client.removePlugin("composer-controls-example");
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await example.cleanup();
+    await workspace.cleanup();
+  }
+}
+
+/**
+ * A plugin that names an agent by id from a Command Center item while the user is in another
+ * workspace: the target's workspace is not on screen, so its composer is not mounted.
+ */
+export async function withPluginWritingToAnotherWorkspace(
+  page: Page,
+  run: (author: {
+    openTargetAgent(): Promise<void>;
+    goToAnotherWorkspace(): Promise<void>;
+    insertFromCommandCenter(): Promise<void>;
+    returnToTargetWorkspace(): Promise<void>;
+    expectComposerText(text: string): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({ repoPrefix: "composer-ref-", title: "Composer ref" });
+  const elsewhere = await seedWorkspace({ repoPrefix: "composer-away-", title: "Composer away" });
+  const target = await createMockAgent(workspace, "Target agent");
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-composer-ref-"));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "composer-ref", requirements: pluginRequirements }),
+  );
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `export default function contribute(client) {
+  client.addCommandCenterItem({
+    id: "note",
+    title: "Composer ref: add a note",
+    icon: "Flag",
+    context: "global",
+    onSelect({ composers }) {
+      for (const composer of composers({ agentId: ${JSON.stringify(target.id)} })) composer.insertText("A note from a plugin");
+    },
+  });
+  return () => {};
+}`,
+  );
+  const targetTab = () => page.getByTestId(`workspace-tab-agent_${target.id}`);
+  const workspaceRow = (id: string) =>
+    page.getByTestId(`sidebar-workspace-row-${getServerId()}:${id}`);
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    await page.setViewportSize(WIDE);
+    await gotoAppShell(page);
+    await run({
+      openTargetAgent: () =>
+        test.step("open the agent the plugin will write to", async () => {
+          await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: target.id });
+          await expect(prompt(page)).toBeVisible({ timeout: 30_000 });
+        }),
+      goToAnotherWorkspace: () =>
+        test.step("go to another workspace, so the agent's composer is not on screen", async () => {
+          await workspaceRow(elsewhere.workspaceId).click();
+          // The app keeps the workspace it left mounted, out of sight.
+          await expect(targetTab().first()).toBeHidden();
+        }),
+      insertFromCommandCenter: () =>
+        test.step("run the plugin's Command Center item", () =>
+          runCommand(page, "Composer ref: add a note")),
+      returnToTargetWorkspace: () =>
+        test.step("return to the agent's workspace without reloading the app", async () => {
+          await workspaceRow(workspace.workspaceId).click();
+          await expect(targetTab().first()).toBeVisible({ timeout: 30_000 });
+        }),
+      expectComposerText: (text) =>
+        test.step("its composer holds the text", () => expect(prompt(page)).toHaveValue(text)),
+    });
+  } finally {
+    await client.removePlugin("composer-ref");
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await rm(directory, { recursive: true, force: true });
+    await elsewhere.cleanup();
+    await workspace.cleanup();
+  }
+}
+
+/**
+ * A plugin that reaches one agent's composer from a pill and from Command Center items, and asks
+ * for focus, wherever the user is.
+ */
+export async function withPluginFocusingAComposer(
+  page: Page,
+  run: (author: {
+    openOtherAgent(): Promise<void>;
+    openTargetAgent(): Promise<void>;
+    goToAnotherWorkspace(): Promise<void>;
+    moveFocusOutOfComposer(): Promise<void>;
+    pressPill(): Promise<void>;
+    focusFromCommandCenter(): Promise<void>;
+    selectPromptFromCommandCenter(): Promise<void>;
+    useCompactLayout(): Promise<void>;
+    coverComposerWithExplorerPanel(): Promise<void>;
+    pressPanelFocusButton(): Promise<void>;
+    expectExplorerPanelClosed(): Promise<void>;
+    fillComposer(text: string): Promise<void>;
+    expectOnTargetAgent(): Promise<void>;
+    expectComposerFocused(): Promise<void>;
+    typeAtCursor(text: string): Promise<void>;
+    expectComposerText(text: string): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({ repoPrefix: "composer-focus-", title: "Composer focus" });
+  const elsewhere = await seedWorkspace({ repoPrefix: "focus-away-", title: "Focus away" });
+  const target = await createMockAgent(workspace, "Target agent");
+  const other = await createMockAgent(workspace, "Other agent");
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-composer-focus-"));
+  const targetId = JSON.stringify(target.id);
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "composer-focus", requirements: pluginRequirements }),
+  );
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `import { Pressable, Text } from "react-native";
+
+export default function contribute(client) {
+  client.addComposerPill({
+    id: "hello",
+    workspaceId: ${JSON.stringify(workspace.workspaceId)},
+    agentId: ${targetId},
+    button: {
+      title: "Add HELLO to the composer",
+      icon: "Hand",
+      label: "Hello",
+      behavior: {
+        kind: "action",
+        async onPress() {
+          for (const composer of client.composers({ agentId: ${targetId} })) {
+            composer.insertText("HELLO");
+            await composer.focus();
+          }
+        },
+      },
+    },
+  });
+  client.addWorkspacePanel({
+    id: "tools",
+    title: "Focus tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component() {
+      return (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Focus the target agent"
+          onPress={() => client.composers({ agentId: ${targetId} })[0]?.focus()}
+        >
+          <Text>Focus the target agent</Text>
+        </Pressable>
+      );
+    },
+  });
+  client.addCommandCenterItem({
+    id: "focus",
+    title: "Composer focus: focus the target",
+    icon: "Flag",
+    context: "global",
+    onSelect({ composers }) {
+      return composers({ agentId: ${targetId} })[0].focus();
+    },
+  });
+  client.addCommandCenterItem({
+    id: "select",
+    title: "Composer focus: select the prompt",
+    icon: "Flag",
+    context: "global",
+    onSelect({ composers }) {
+      const composer = composers({ agentId: ${targetId} })[0];
+      return composer.focus({ selection: { start: 0, end: composer.prompt.length } });
+    },
+  });
+  return () => {};
+}`,
+  );
+  const targetTab = () => page.getByTestId(`workspace-tab-agent_${target.id}`);
+  const workspaceRow = (id: string) =>
+    page.getByTestId(`sidebar-workspace-row-${getServerId()}:${id}`);
+  const panelFocusButton = () =>
+    page.getByRole("button", { name: "Focus the target agent", exact: true });
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    await page.setViewportSize(WIDE);
+    await gotoAppShell(page);
+    await run({
+      openOtherAgent: () =>
+        test.step("open another agent, so the target's tab is not showing", async () => {
+          await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: other.id });
+          await expect(prompt(page)).toBeVisible({ timeout: 30_000 });
+        }),
+      openTargetAgent: () =>
+        test.step("open the target agent", async () => {
+          await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: target.id });
+          await expect(prompt(page)).toBeVisible({ timeout: 30_000 });
+        }),
+      goToAnotherWorkspace: () =>
+        test.step("go to another workspace", async () => {
+          await workspaceRow(elsewhere.workspaceId).click();
+          await expect(targetTab().first()).toBeHidden();
+        }),
+      moveFocusOutOfComposer: () =>
+        test.step("the composer does not have focus", async () => {
+          await prompt(page).blur();
+          await expect(prompt(page)).not.toBeFocused();
+        }),
+      pressPill: () =>
+        test.step("press the pill", () => page.getByRole("button", { name: "Hello" }).click()),
+      focusFromCommandCenter: () =>
+        test.step("run the plugin's focus command", () =>
+          runCommand(page, "Composer focus: focus the target")),
+      selectPromptFromCommandCenter: () =>
+        test.step("run the plugin's select command", () =>
+          runCommand(page, "Composer focus: select the prompt")),
+      useCompactLayout: () =>
+        test.step("use a phone-sized window", () => page.setViewportSize(COMPACT)),
+      coverComposerWithExplorerPanel: () =>
+        test.step("open the plugin's panel in the Explorer, covering the composer", async () => {
+          const explorer = await ensureExplorerSidebar(page);
+          await explorer.getByRole("button", { name: "New tab", exact: true }).click();
+          await page
+            .getByTestId("workspace-new-tab-menu")
+            .filter({ visible: true })
+            .getByRole("menuitem", { name: "Focus tools", exact: true })
+            .click();
+          await expect(panelFocusButton()).toBeVisible();
+        }),
+      pressPanelFocusButton: () =>
+        test.step("press the panel's button", () => panelFocusButton().click()),
+      expectExplorerPanelClosed: () =>
+        test.step("the Explorer no longer covers the composer", () =>
+          expect(panelFocusButton()).toBeHidden({ timeout: 30_000 })),
+      fillComposer: (text) =>
+        test.step(`write "${text}" in the composer`, () => prompt(page).fill(text)),
+      expectOnTargetAgent: () =>
+        test.step("the target agent's tab is showing", async () => {
+          await expect(targetTab().filter({ visible: true }).first()).toHaveAttribute(
+            "aria-selected",
+            "true",
+            { timeout: 30_000 },
+          );
+        }),
+      expectComposerFocused: () =>
+        test.step("the composer input has focus", () =>
+          expect(prompt(page)).toBeFocused({ timeout: 30_000 })),
+      typeAtCursor: (text) => test.step(`type "${text}"`, () => page.keyboard.type(text)),
+      expectComposerText: (text) =>
+        test.step("the composer holds the text", () => expect(prompt(page)).toHaveValue(text)),
+    });
+  } finally {
+    await client.removePlugin("composer-focus");
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await rm(directory, { recursive: true, force: true });
+    await elsewhere.cleanup();
+    await workspace.cleanup();
+  }
+}
+
+export { CHECKLIST };
+
+type HeldComposerGlobal = typeof globalThis & {
+  heldComposer?: {
+    focus(options?: { selection?: { start: number; end: number } }): Promise<void>;
+  };
+};
+
+export async function withPluginHoldingNewWorkspaceComposer(
+  page: Page,
+  run: (author: {
+    openNewWorkspace(): Promise<void>;
+    leaveCompactExplorerForNewWorkspace(): Promise<void>;
+    openSettings(): Promise<void>;
+    openThinkingPicker(): Promise<void>;
+    previewAttachedImage(): Promise<void>;
+    typeInHeldComposer(text: string): Promise<void>;
+    expectOverlappingFocusesKeepTheLatestSelection(): Promise<void>;
+    expectHeldComposerFocusResult(result: string): Promise<void>;
+    expectHeldComposerReadyToType(): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedWorkspace({ repoPrefix: "held-composer-", title: "Held composer" });
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-held-composer-"));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "held-composer", requirements: pluginRequirements }),
+  );
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `import { useComposer } from "@getpaseo/plugin/client";
+
+function Holder() {
+  globalThis.heldComposer = useComposer();
+  return null;
+}
+
+export default function contribute(client) {
+  client.addComposerItem({ id: "holder", Component: Holder });
+  return () => {};
+}`,
+  );
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    await page.setViewportSize(WIDE);
+    await gotoAppShell(page);
+    await run({
+      openNewWorkspace: () =>
+        test.step("open the New workspace composer", async () => {
+          await openGlobalNewWorkspaceComposer(page);
+          await page.waitForFunction(() => (globalThis as HeldComposerGlobal).heldComposer);
+        }),
+      leaveCompactExplorerForNewWorkspace: () =>
+        test.step("leave a compact Explorer for New workspace with the shortcut", async () => {
+          await gotoWorkspace(page, workspace.workspaceId);
+          await page.setViewportSize(COMPACT);
+          await expect(await ensureExplorerSidebar(page)).toBeVisible();
+          await page.evaluate(() => {
+            (globalThis as HeldComposerGlobal).heldComposer = undefined;
+          });
+          await page.keyboard.press("ControlOrMeta+n");
+          await expect(page).toHaveURL(/\/new(?:\?.*)?$/);
+          // A compact composer mounts plugin items inside its controls sheet.
+          await page.getByRole("button", { name: /^Select model/ }).click();
+          await page.waitForFunction(() => (globalThis as HeldComposerGlobal).heldComposer);
+          await tapSheetBackdrop(page);
+          await expectNoSheetOpen(page);
+        }),
+      openSettings: () =>
+        test.step("push Settings over the New workspace screen", async () => {
+          await page.getByTestId("sidebar-settings").filter({ visible: true }).click();
+          await expect(page.getByTestId("settings-sidebar")).toBeVisible();
+        }),
+      openThinkingPicker: () =>
+        test.step("open the thinking picker in the New workspace composer", async () => {
+          await page
+            .getByRole("button", { name: /^Select thinking option/ })
+            .filter({ visible: true })
+            .click();
+          await expect(page.getByText("High", { exact: true })).toBeVisible();
+        }),
+      previewAttachedImage: () =>
+        test.step("attach an image to the New workspace composer and preview it", async () => {
+          await attachComposerTestImage(page);
+          await openImageLightbox(page);
+        }),
+      typeInHeldComposer: (text) =>
+        test.step(`type ${text} in the New workspace composer`, async () => {
+          await prompt(page).filter({ visible: true }).fill(text);
+        }),
+      expectOverlappingFocusesKeepTheLatestSelection: () =>
+        test.step("two overlapping focus() calls leave the later selection", async () => {
+          const selection = await page.evaluate(async () => {
+            const composer = (globalThis as HeldComposerGlobal).heldComposer!;
+            await Promise.all([
+              composer.focus({ selection: { start: 0, end: 1 } }),
+              composer.focus({ selection: { start: 2, end: 4 } }),
+            ]);
+            const input = document.activeElement as HTMLTextAreaElement;
+            return [input.selectionStart, input.selectionEnd];
+          });
+          expect(selection).toEqual([2, 4]);
+        }),
+      expectHeldComposerReadyToType: () =>
+        test.step("nothing covers the composer and the cursor is in it", async () => {
+          await expect(page.getByText("High", { exact: true })).toHaveCount(0);
+          await expect(page.getByTestId("attachment-lightbox-close")).toHaveCount(0);
+          await expect(prompt(page).filter({ visible: true })).toBeFocused();
+        }),
+      expectHeldComposerFocusResult: (result) =>
+        test.step(`the held composer's focus() reports ${result}`, async () => {
+          const actual = await page.evaluate(() =>
+            (globalThis as HeldComposerGlobal).heldComposer?.focus().then(
+              () => "focused",
+              (error: Error) => error.message,
+            ),
+          );
+          expect(actual).toBe(result);
+        }),
+    });
+  } finally {
+    await client.removePlugin("held-composer");
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await rm(directory, { recursive: true, force: true });
+    await workspace.cleanup();
+  }
+}
+
+type FocusAgentGlobal = typeof globalThis & {
+  focusAgent?: (agentId: string) => Promise<void>;
+};
+
+export async function withPluginFocusingASubagent(
+  page: Page,
+  run: (author: {
+    openParentAgent(): Promise<void>;
+    openExplorer(): Promise<void>;
+    focusSubagent(): Promise<void>;
+    expectSubagentTabReadyToType(): Promise<void>;
+    keepParentInExplorerOnCompactScreen(): Promise<void>;
+    focusParent(): Promise<void>;
+    expectParentReadyToType(): Promise<void>;
+    coverExplorerComposerWithFileSheet(): Promise<void>;
+    focusParentAsAFileSheetOpens(): Promise<void>;
+    openSubagentPageInParentComposer(): Promise<void>;
+  }) => Promise<void>,
+) {
+  const workspace = await seedMockAgentWorkspace({
+    repoPrefix: "focus-subagent-",
+    title: "Focus parent",
+    initialPrompt: promptMentioning(FILE_LINK),
+  });
+  await writeFile(path.join(workspace.cwd, "linked.ts"), "one\ntwo\nthree\n", "utf8");
+  const child = await seedSubagent(
+    { client: workspace.client, repoPath: workspace.cwd, workspaceId: workspace.workspaceId },
+    { parentId: workspace.agentId, title: "Focus child" },
+  );
+  const plugin = await installFocusingPlugin(page);
+  const { focusAgent } = plugin;
+  try {
+    await page.setViewportSize(COMPACT);
+    await gotoAppShell(page);
+    await run({
+      keepParentInExplorerOnCompactScreen: () =>
+        test.step("move the parent into the Explorer, then narrow the window", async () => {
+          await page.setViewportSize(WIDE);
+          await openAgentRoute(page, {
+            workspaceId: workspace.workspaceId,
+            agentId: workspace.agentId,
+          });
+          await page.waitForFunction(() => (globalThis as FocusAgentGlobal).focusAgent);
+          // The seeded turn must finish first, so the drag isn't racing its updates to the tab.
+          await expect(page.getByText(FILE_LINK, { exact: true })).toBeVisible({ timeout: 15_000 });
+          const explorer = await ensureExplorerSidebar(page);
+          await dragTabIntoExplorer(page, `agent_${workspace.agentId}`);
+          await expect(
+            explorer.getByTestId(`workspace-tab-agent_${workspace.agentId}`),
+          ).toBeVisible();
+          await page.setViewportSize(COMPACT);
+          // The phone layout hides the Explorer; focus must find it there, not in the wide layout.
+          await expect(explorer).toBeHidden();
+        }),
+      focusParent: () =>
+        test.step("focus the agent kept in the Explorer", () => focusAgent(workspace.agentId)),
+      expectParentReadyToType: () =>
+        test.step("no sheet is open and the cursor is in the composer", async () => {
+          await expectNoSheetOpen(page);
+          await expect(prompt(page).filter({ visible: true })).toBeFocused();
+        }),
+      openSubagentPageInParentComposer: () =>
+        test.step("open the subagent's page from the parent's Subagents track", async () => {
+          await openSubagentFromCompactTrack(page, child.id);
+          await expect(sheet(page, child.title)).toBeVisible();
+        }),
+      coverExplorerComposerWithFileSheet: () =>
+        test.step("open a file's sheet over the Explorer's composer", async () => {
+          await page.getByText(FILE_LINK, { exact: true }).filter({ visible: true }).click();
+          await expect(sheet(page, "linked.ts")).toBeVisible();
+        }),
+      focusParentAsAFileSheetOpens: () =>
+        test.step("focus the agent while a file's sheet is opening over it", async () => {
+          // The click looks the file up first. Focus in the commit that mounts the sheet, before
+          // its opening animation has started.
+          await page.evaluate((id) => {
+            const global = globalThis as FocusAgentGlobal & {
+              focusedAsSheetOpens?: Promise<string>;
+            };
+            global.focusedAsSheetOpens = new Promise((resolve) => {
+              const observer = new MutationObserver(() => {
+                if (!document.querySelector('[aria-label="Bottom sheet backdrop"]')) return;
+                observer.disconnect();
+                void global.focusAgent?.(id).then(
+                  () => resolve("focused"),
+                  (error: Error) => resolve(error.message),
+                );
+              });
+              observer.observe(document.body, { childList: true, subtree: true });
+            });
+          }, workspace.agentId);
+          await page.getByText(FILE_LINK, { exact: true }).filter({ visible: true }).click();
+          const outcome = await page.evaluate(
+            () => (globalThis as { focusedAsSheetOpens?: Promise<string> }).focusedAsSheetOpens,
+          );
+          expect(outcome).toBe("focused");
+        }),
+      openParentAgent: () =>
+        test.step("open the parent agent on a phone", async () => {
+          await openAgentRoute(page, {
+            workspaceId: workspace.workspaceId,
+            agentId: workspace.agentId,
+          });
+          await expect(prompt(page)).toBeVisible({ timeout: 30_000 });
+          await expectOpenTabCount(page, 1);
+          await page.waitForFunction(() => (globalThis as FocusAgentGlobal).focusAgent);
+        }),
+      openExplorer: () =>
+        test.step("open the Explorer over the parent's composer", async () => {
+          await expect(await ensureExplorerSidebar(page)).toBeVisible();
+        }),
+      focusSubagent: () =>
+        test.step("focus the subagent, which has no tab", () => focusAgent(child.id)),
+      expectSubagentTabReadyToType: () =>
+        test.step("the subagent is a tab with the cursor in its composer", async () => {
+          await expectNoSheetOpen(page);
+          await expectOpenTabCount(page, 2);
+          await expect(prompt(page)).toBeFocused();
+        }),
+    });
+  } finally {
+    await plugin.remove();
+    await workspace.cleanup();
+  }
+}
+
+/** A plugin that focuses any agent's composer, as a callback holding the agent's id would. */
+async function installFocusingPlugin(page: Page) {
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-focus-agent-"));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({ id: "focus-agent", requirements: pluginRequirements }),
+  );
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `export default function contribute(client) {
+  globalThis.focusAgent = (agentId) => client.composers({ agentId })[0].focus();
+  return () => {};
+}`,
+  );
+  await client.patchDaemonConfig({ pluginsEnabled: true });
+  await client.installDirectoryPlugin(directory);
+  return {
+    focusAgent: async (agentId: string) => {
+      const result = await page.evaluate(
+        (id) =>
+          (globalThis as FocusAgentGlobal).focusAgent?.(id).then(
+            () => "focused",
+            (error: Error) => error.message,
+          ),
+        agentId,
+      );
+      expect(result).toBe("focused");
+    },
+    remove: async () => {
+      await client.removePlugin("focus-agent");
+      await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+      await client.close();
+      await rm(directory, { recursive: true, force: true });
+    },
+  };
+}
+
+export async function withPluginFocusingAnAgentWithContextUsage(
+  page: Page,
+  run: (author: {
+    openContextUsageOnPhone(): Promise<void>;
+    focusAgent(): Promise<void>;
+    expectReadyToType(): Promise<void>;
+  }) => Promise<void>,
+) {
+  const agent = await seedAgentWithContextWindow();
+  const plugin = await installFocusingPlugin(page);
+  try {
+    await page.setViewportSize(COMPACT);
+    await gotoAppShell(page);
+    await run({
+      openContextUsageOnPhone: () =>
+        test.step("open the agent's context usage on a phone", async () => {
+          await openAgentRoute(page, agent);
+          await page.waitForFunction(() => (globalThis as FocusAgentGlobal).focusAgent);
+          await pressContextWindowMeter(page);
+        }),
+      focusAgent: () => test.step("focus the agent", () => plugin.focusAgent(agent.agentId)),
+      expectReadyToType: () =>
+        test.step("the context usage is closed and the cursor is in the composer", async () => {
+          await expect(contextWindowDetails(page)).toHaveCount(0);
+          await expect(prompt(page).filter({ visible: true })).toBeFocused();
+        }),
+    });
+  } finally {
+    await plugin.remove();
+    await agent.cleanup();
+  }
+}
diff --git a/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts b/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts
new file mode 100644
index 0000000000..ddcdd6d08b
--- /dev/null
+++ b/packages/app/e2e/support/helpers/plugin-new-workspace-items.ts
@@ -0,0 +1,228 @@
+import { execFileSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test, type Page } from "@playwright/test";
+import { gotoAppShell } from "./app";
+import {
+  archiveWorkspaceFromDaemon,
+  assertNewWorkspaceSidebarAndHeader,
+  connectNewWorkspaceDaemonClient,
+  expectWorkspaceIsolationSelected,
+  openNewWorkspaceComposer,
+  openProjectViaDaemon,
+  submitNewWorkspacePrompt,
+} from "./new-workspace";
+import { copyPluginExample } from "./plugin-fixture";
+import { getServerId } from "./server-id";
+import { createTempGitRepo } from "./workspace";
+import { waitForSidebarHydration } from "./workspace-ui";
+
+/** Presses Create, typing the prompt first unless the test wants an empty one. */
+async function submitCreate(page: Page, prompt: string | undefined) {
+  if (prompt !== "") return submitNewWorkspacePrompt(page, prompt);
+  await page.getByTestId("message-input-root").getByRole("button", { name: "Create" }).click();
+}
+
+/** An item that sets the branch and metadata from its mount effect, before the user touches anything. */
+async function replaceWithMountEffectItem(directory: string) {
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `import { useEffect } from "react";
+import { useNewWorkspace } from "@getpaseo/plugin/client";
+import { Action } from "@getpaseo/plugin/client/ui";
+function OnMount() {
+  const newWorkspace = useNewWorkspace();
+  useEffect(() => {
+    void newWorkspace.setIsolation("worktree");
+    void newWorkspace.setBranch("set-on-mount");
+    void newWorkspace.setMetadata({ "new-workspace-issues.issue": "ON-MOUNT" });
+  }, []);
+  return <Action title="Mount" icon="Flag" onPress={() => {}} />;
+}
+export default function contribute(client) {
+  client.addNewWorkspaceItem({ id: "on-mount", Component: OnMount });
+  return () => {};
+}
+`,
+  );
+}
+
+/**
+ * An item whose search depends on the project: it answers with the project's name, and never
+ * answers for the project named "other", so a list that still shows the first project's answer
+ * there is stale.
+ */
+async function replaceWithProjectSearchItem(directory: string) {
+  await writeFile(
+    path.join(directory, "index.client.tsx"),
+    `import { useNewWorkspace } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+function ProjectIssues() {
+  const { project } = useNewWorkspace();
+  const name = project?.name ?? "";
+  return (
+    <Combobox
+      title="Issue"
+      icon="CircleDot"
+      value={null}
+      search={() =>
+        name.includes("other")
+          ? new Promise(() => {})
+          : Promise.resolve([{ id: name, label: "Issue of " + name }])
+      }
+      onSelect={() => {}}
+    />
+  );
+}
+export default function contribute(client) {
+  client.addNewWorkspaceItem({ id: "project-issues", Component: ProjectIssues });
+  return () => {};
+}
+`,
+  );
+}
+
+type Client = Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
+
+/** The daemon fills in the git runtime after it creates the workspace, so wait for the branch. */
+async function readCreatedWorkspace(client: Client, workspaceId: string) {
+  const deadline = Date.now() + 30_000;
+  for (;;) {
+    const { entries } = await client.fetchWorkspaces();
+    const workspace = entries.find((entry) => entry.id === workspaceId);
+    const branch = workspace?.gitRuntime?.currentBranch ?? null;
+    if (workspace && branch) return { branch, metadata: workspace.metadata };
+    if (Date.now() > deadline) throw new Error(`Workspace ${workspaceId} never reported a branch`);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+const PLUGIN_ID = "new-workspace-issues-example";
+const COMPACT = { width: 500, height: 800 };
+
+/** Runs `run` on the New workspace screen with the new-workspace-issues example installed. */
+export async function withNewWorkspaceIssuesExample(
+  page: Page,
+  options: {
+    compact: boolean;
+    detachedHead?: boolean;
+    setsOnMount?: boolean;
+    /** Installs an item whose Issue list depends on the project instead of the example's. */
+    searchesByProject?: boolean;
+    /** A second project the screen can switch to. */
+    otherProject?: boolean;
+  },
+  run: (screen: {
+    chooseWorktree(): Promise<void>;
+    chooseIssue(label: string): Promise<void>;
+    createWorkspace(options?: { prompt?: string }): Promise<{ branch: string; metadata: unknown }>;
+    switchToOtherProject(): Promise<void>;
+    openIssueList(): Promise<void>;
+    closeIssueList(): Promise<void>;
+    /** The Issue list shows `text`, or does not show it when `shown` is false. */
+    expectIssueListText(text: string, shown: boolean): Promise<void>;
+    /** The name the first project's items read as `project.name`. */
+    firstProjectName: string;
+    expectIsolation(isolation: "local" | "worktree"): Promise<void>;
+    /** Removes the plugin, leaves the screen, and opens New workspace for the project again. */
+    reopenWithoutPlugin(): Promise<void>;
+  }) => Promise<void>,
+) {
+  const client = await connectNewWorkspaceDaemonClient();
+  const previous = await client.getDaemonConfig();
+  const example = await copyPluginExample("new-workspace-issues");
+  if (options.searchesByProject) await replaceWithProjectSearchItem(example.directory);
+  if (options.setsOnMount) await replaceWithMountEffectItem(example.directory);
+  const repo = await createTempGitRepo("new-workspace-issues-", { branches: ["main"] });
+  const otherRepo = options.otherProject
+    ? await createTempGitRepo("new-workspace-other-", { branches: ["main"] })
+    : null;
+  let createdDirectory: string | null = null;
+  try {
+    // A detached HEAD leaves the screen with no default base to branch off.
+    if (options.detachedHead) execFileSync("git", ["checkout", "--detach"], { cwd: repo.path });
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(example.directory);
+    const project = await openProjectViaDaemon(client, repo.path);
+    const other = otherRepo ? await openProjectViaDaemon(client, otherRepo.path) : null;
+    let target = project;
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await openNewWorkspaceComposer(page, project);
+    // The sidebar rows used to reach the screen exist only at desktop width.
+    if (options.compact) await page.setViewportSize(COMPACT);
+    await run({
+      chooseWorktree: () =>
+        test.step("choose a new worktree", async () => {
+          await page.getByTestId("workspace-create-isolation-trigger").click();
+          await page.getByTestId("workspace-create-isolation-worktree").click();
+        }),
+      chooseIssue: (label) =>
+        test.step(`choose the issue "${label}"`, async () => {
+          await page.getByRole("button", { name: "Issue", exact: true }).click();
+          await page.getByText(label, { exact: true }).click();
+        }),
+      firstProjectName: project.projectDisplayName,
+      openIssueList: () =>
+        test.step("open the Issue list", async () => {
+          await page.getByRole("button", { name: "Issue", exact: true }).click();
+        }),
+      closeIssueList: () => test.step("close the Issue list", () => page.keyboard.press("Escape")),
+      expectIssueListText: (text, shown) =>
+        test.step(`the Issue list ${shown ? "shows" : "does not show"} "${text}"`, async () => {
+          const list = page.getByTestId("combobox-desktop-container").last();
+          await expect(list.getByText(text, { exact: true })).toHaveCount(shown ? 1 : 0);
+        }),
+      switchToOtherProject: () =>
+        test.step("switch to the other project", async () => {
+          if (!other) throw new Error("Open the example with otherProject to switch projects");
+          await page.getByRole("button", { name: "Workspace project" }).click();
+          await page
+            .getByTestId("combobox-desktop-container")
+            .last()
+            .getByText(other.projectDisplayName, { exact: true })
+            .click();
+          await expect(page.getByRole("button", { name: "Workspace project" })).toContainText(
+            other.projectDisplayName,
+          );
+          target = other;
+        }),
+      expectIsolation: (isolation) =>
+        test.step(`the screen is on ${isolation}`, () =>
+          expectWorkspaceIsolationSelected(page, isolation)),
+      reopenWithoutPlugin: () =>
+        test.step("reopen the screen without the plugin", async () => {
+          await client.removePlugin(PLUGIN_ID);
+          // Leaving the screen drops its in-memory choice, so only the saved preference is left.
+          await page.goBack();
+          await expect(page.getByTestId("workspace-create-isolation-trigger")).toHaveCount(0);
+          await openNewWorkspaceComposer(page, project);
+          await expect(page.getByRole("button", { name: "Mount", exact: true })).toHaveCount(0);
+        }),
+      createWorkspace: (createOptions) =>
+        test.step("create the workspace and read what it carries", async () => {
+          await submitCreate(page, createOptions?.prompt);
+          const created = await assertNewWorkspaceSidebarAndHeader(page, {
+            serverId: getServerId(),
+            client,
+            previousWorkspaceId: target.workspaceId,
+            projectDisplayName: target.projectDisplayName,
+            // The sidebar is closed at compact width.
+            assertSidebarRow: !options.compact,
+          });
+          createdDirectory = created.workspaceDirectory;
+          return readCreatedWorkspace(client, created.workspaceId);
+        }),
+    });
+  } finally {
+    if (createdDirectory) {
+      await archiveWorkspaceFromDaemon(client, createdDirectory).catch(() => undefined);
+    }
+    await client.removePlugin(PLUGIN_ID).catch(() => undefined);
+    await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+    await client.close();
+    await example.cleanup();
+    await repo.cleanup();
+    await otherRepo?.cleanup();
+  }
+}
diff --git a/packages/app/e2e/support/helpers/plugin-settings.ts b/packages/app/e2e/support/helpers/plugin-settings.ts
index 32f07fcdfd..53048359f1 100644
--- a/packages/app/e2e/support/helpers/plugin-settings.ts
+++ b/packages/app/e2e/support/helpers/plugin-settings.ts
@@ -1,4 +1,7 @@
-import { copyPluginExample } from "./plugin-fixture";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { copyPluginExample, pluginRequirements } from "./plugin-fixture";
 import { expect, test as base, type Page } from "../fixtures";
 import { gotoAppShell, openSettings } from "./app";
 import { goBackInSettings, openCompactSettings, openHostSection } from "./settings";
@@ -9,6 +12,54 @@ import { connectNewWorkspaceDaemonClient } from "./new-workspace";
 
 type SettingsClient = Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
 
+const TABBED_PLUGIN_ID = "settings-tabs";
+const TABBED_PLUGIN_NAME = "Tabbed settings";
+/** Two settings screens, so the settings page shows a tab per screen. */
+const TABBED_SOURCE = `import React from "react";
+import { Text, View } from "react-native";
+import { defineTranslations, useTranslation } from "@getpaseo/plugin/client";
+
+const messages = defineTranslations({ resources: { en: { icon: "advanced-tab-icon" } } });
+
+function General({ theme }) {
+  return <Text style={{ color: theme.colors.foreground }}>General settings body</Text>;
+}
+
+function Advanced({ theme }) {
+  return <Text style={{ color: theme.colors.foreground }}>Advanced settings body</Text>;
+}
+
+// Component icons run with the plugin's runtime; one that throws costs its tab only the icon.
+function TranslatedIcon({ color, size }) {
+  const { t } = useTranslation(messages);
+  return <View testID={t("icon")} aria-hidden style={{ width: size, height: size, borderRadius: size / 2, backgroundColor: color }} />;
+}
+
+function BrokenIcon() {
+  throw new Error("Settings tab icon exploded");
+}
+
+export default function contribute(client) {
+  client.addSettingsScreen({ id: "general", title: "General", icon: BrokenIcon, Component: General });
+  client.addSettingsScreen({ id: "advanced", title: "Advanced", icon: TranslatedIcon, Component: Advanced });
+  return () => {};
+}
+`;
+
+async function writeTabbedPlugin() {
+  const directory = await mkdtemp(path.join(tmpdir(), `paseo-${TABBED_PLUGIN_ID}-`));
+  await writeFile(
+    path.join(directory, "paseo-plugin.json"),
+    JSON.stringify({
+      id: TABBED_PLUGIN_ID,
+      name: TABBED_PLUGIN_NAME,
+      requirements: pluginRequirements,
+    }),
+  );
+  await writeFile(path.join(directory, "index.client.tsx"), TABBED_SOURCE);
+  return { directory, cleanup: () => rm(directory, { recursive: true, force: true }) };
+}
+
 export const test = base.extend<{ settingsPlugin: SettingsClient }>({
   settingsPlugin: [
     async ({ e2eWorker, page }, provide, testInfo) => {
@@ -16,16 +67,20 @@ export const test = base.extend<{ settingsPlugin: SettingsClient }>({
       const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
       const previous = await client.getDaemonConfig();
       const example = await copyPluginExample("settings");
+      const tabbed = await writeTabbedPlugin();
       try {
         await client.patchDaemonConfig({ pluginsEnabled: true });
         await client.installDirectoryPlugin(example.directory);
+        await client.installDirectoryPlugin(tabbed.directory);
         await provide(client);
         await page.screenshot({ path: testInfo.outputPath("settings.png") });
       } finally {
         await client.removePlugin("settings-example");
+        await client.removePlugin(TABBED_PLUGIN_ID);
         await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
         await client.close();
         await example.cleanup();
+        await tabbed.cleanup();
       }
     },
     { auto: true },
@@ -44,9 +99,88 @@ export async function openCompactDisplaySettings(page: Page) {
 }
 async function openPluginScreen(page: Page) {
   await openHostSection(page, getServerId(), "plugins");
-  await page.getByRole("button", { name: "Actions for settings-example", exact: true }).click();
-  await page.getByRole("menuitem", { name: "Display", exact: true }).click();
+  await openSettingsFromCog(page);
+}
+/** The cog on a plugin's row. Its label is "Settings"; the row tells plugins apart. */
+function settingsButton(page: Page, pluginId: string) {
+  return page
+    .getByTestId(`plugin-row-${pluginId}`)
+    .filter({ visible: true })
+    .getByRole("button", { name: "Settings", exact: true });
+}
+async function openSettingsFromCog(page: Page) {
+  await settingsButton(page, "settings-example").click();
   await expect(page.getByRole("switch", { name: "Show metadata" })).toBeVisible();
+  // A plugin with one settings screen shows no tabs, and the header names only the plugin.
+  await expect(page.getByTestId("plugin-settings-tabs")).toHaveCount(0);
+  await expectSettingsHeader(page, "settings-example");
+}
+export async function openPluginsPage(page: Page) {
+  await gotoAppShell(page);
+  await openSettings(page);
+  await openHostSection(page, getServerId(), "plugins");
+}
+export async function expectActionsMenuWithoutSettings(page: Page) {
+  await page.getByRole("button", { name: "Actions for settings-example", exact: true }).click();
+  await expect(page.getByRole("menuitem", { name: "Reload", exact: true })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Display", exact: true })).toHaveCount(0);
+  await page.keyboard.press("Escape");
+}
+export async function expectNoSettingsCogWithoutScreens(page: Page) {
+  await page.getByRole("switch", { name: "settings-example: Disable" }).click();
+  await expect(page.getByRole("switch", { name: "settings-example: Enable" })).toBeVisible();
+  await expect(settingsButton(page, "settings-example")).toHaveCount(0);
+  await page.getByRole("switch", { name: "settings-example: Enable" }).click();
+  await expect(settingsButton(page, "settings-example")).toBeVisible();
+}
+export async function expectSettingsTooltip(page: Page) {
+  await settingsButton(page, "settings-example").hover();
+  await expect(page.getByRole("tooltip")).toHaveText("Settings");
+  await page.mouse.move(0, 0);
+}
+/** A manifest `name` titles the row and its controls; the id stays visible beneath it. */
+export async function expectNamedPluginRow(page: Page) {
+  const row = page.getByTestId(`plugin-row-${TABBED_PLUGIN_ID}`).filter({ visible: true });
+  await expect(row.getByText(TABBED_PLUGIN_NAME, { exact: true })).toBeVisible();
+  await expect(row.getByText(TABBED_PLUGIN_ID, { exact: true })).toBeVisible();
+  await expect(
+    page.getByRole("switch", { name: `${TABBED_PLUGIN_NAME}: Disable`, exact: true }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: `Actions for ${TABBED_PLUGIN_NAME}`, exact: true }),
+  ).toBeVisible();
+}
+export async function openTabbedSettings(page: Page) {
+  await settingsButton(page, TABBED_PLUGIN_ID).click();
+  await expectSettingsTab(page, "General");
+  // The Advanced icon reads the plugin's translations; the General icon throws and is dropped.
+  await expect(page.getByTestId("advanced-tab-icon")).toBeVisible();
+}
+function settingsTab(page: Page, title: string) {
+  return page.getByTestId("plugin-settings-tabs").getByRole("button", { name: title, exact: true });
+}
+export async function selectSettingsTab(page: Page, title: "General" | "Advanced") {
+  await settingsTab(page, title).click();
+  await expectSettingsTab(page, title);
+}
+export async function expectSettingsTab(page: Page, title: "General" | "Advanced") {
+  const other = title === "General" ? "Advanced" : "General";
+  await expect(settingsTab(page, title)).toHaveAttribute("aria-selected", "true");
+  await expect(page.getByText(`${title} settings body`, { exact: true })).toBeVisible();
+  await expect(page.getByText(`${other} settings body`, { exact: true })).toHaveCount(0);
+  // The header names the plugin by its manifest name; the tab names the screen.
+  await expectSettingsHeader(page, TABBED_PLUGIN_NAME);
+  await expectAppRoute(
+    page,
+    `${buildSettingsHostSectionRoute(getServerId(), "plugins")}/${TABBED_PLUGIN_ID}/${title.toLowerCase()}`,
+  );
+}
+export async function openTabbedSettingsLink(page: Page, title: "General" | "Advanced") {
+  await gotoAppShell(page);
+  await page.goto(
+    `${buildSettingsHostSectionRoute(getServerId(), "plugins")}/${TABBED_PLUGIN_ID}/${title.toLowerCase()}`,
+  );
+  await expectSettingsTab(page, title);
 }
 export async function groupByWorkspace(page: Page) {
   await page.getByRole("button", { name: /^Group agents by:/ }).click();
@@ -101,11 +235,7 @@ export async function discardTitle(page: Page) {
 }
 export async function returnAndReopenSettings(page: Page) {
   await goBackInSettings(page);
-  const actions = page.getByRole("button", { name: "Actions for settings-example", exact: true });
-  await expect(actions).toBeVisible();
-  await actions.click();
-  await page.getByRole("menuitem", { name: "Display", exact: true }).click();
-  await expect(page.getByRole("switch", { name: "Show metadata" })).toBeVisible();
+  await openSettingsFromCog(page);
 }
 export async function returnToPluginsPage(page: Page) {
   await page.getByRole("button", { name: "Back to plugins", exact: true }).click();
@@ -114,6 +244,10 @@ export async function returnToPluginsPage(page: Page) {
     page.getByRole("button", { name: "Actions for settings-example", exact: true }),
   ).toBeVisible();
 }
+async function expectSettingsHeader(page: Page, title: string) {
+  // Settings keeps the Plugins page mounted beneath, so read the visible title only.
+  await expect(page.getByText(title, { exact: true }).filter({ visible: true })).toHaveCount(1);
+}
 export async function expectSettingsUnavailable(page: Page) {
   await expect(
     page.getByText("This plugin settings screen is unavailable.", { exact: true }),
diff --git a/packages/app/e2e/support/helpers/plugin-timeline.ts b/packages/app/e2e/support/helpers/plugin-timeline.ts
index 98ab7d303b..923e4fabd7 100644
--- a/packages/app/e2e/support/helpers/plugin-timeline.ts
+++ b/packages/app/e2e/support/helpers/plugin-timeline.ts
@@ -48,7 +48,13 @@ export function trackPluginChatRecovery(page: Page) {
     async expectRecoveredWithoutRetransmission() {
       await this.expectCatalogWithoutRetransmission();
       await expect
-        .poll(() => messages.some((message) => message.type === "fetch_agent_timeline_response"))
+        .poll(() =>
+          messages.some(
+            (message) =>
+              message.type === "fetch_agent_timeline_response" ||
+              message.type === "agent.timeline.set_subscription.response",
+          ),
+        )
         .toBe(true);
     },
   };
@@ -134,7 +140,7 @@ export default function contribute(client) {
 }`;
 }
 
-async function withDirectoryPlugin(options: {
+export async function withDirectoryPlugin(options: {
   pluginId: string;
   source: string;
   run: () => Promise<void>;
diff --git a/packages/app/e2e/support/helpers/seed-client.ts b/packages/app/e2e/support/helpers/seed-client.ts
index fe6af133f9..41e676473f 100644
--- a/packages/app/e2e/support/helpers/seed-client.ts
+++ b/packages/app/e2e/support/helpers/seed-client.ts
@@ -118,6 +118,7 @@ export interface SeedDaemonClient {
     featureValues?: Record<string, unknown>;
     initialPrompt?: string;
     labels?: Record<string, string>;
+    background?: boolean;
   }): Promise<{ id: string; status: string }>;
   fetchAgents(options?: { scope?: "active" }): Promise<{
     entries: Array<{
@@ -156,8 +157,11 @@ export interface SeedDaemonClient {
   sendAgentMessage(
     agentId: string,
     text: string,
-    options?: { sourceAgentId?: string },
+    options?: { sourceAgentId?: string; activeTurnBehavior?: "interrupt" | "steer" | "queue" },
   ): Promise<void>;
+  listAgentBackgroundWork(
+    agentId: string,
+  ): Promise<import("@getpaseo/client").PaseoAgentBackgroundWorkItem[]>;
   waitForFinish(
     agentId: string,
     timeout?: number,
diff --git a/packages/app/e2e/support/helpers/settings.ts b/packages/app/e2e/support/helpers/settings.ts
index a2befccfbf..796d0b45f5 100644
--- a/packages/app/e2e/support/helpers/settings.ts
+++ b/packages/app/e2e/support/helpers/settings.ts
@@ -351,9 +351,24 @@ export async function expectDirectHostFormValues(
 }
 
 export async function expectDirectHostSslEnabled(page: Page): Promise<void> {
+  await expect(page.getByRole("checkbox", { name: "Use SSL", exact: true })).toBeChecked();
   await expect(page.getByTestId("direct-ssl-toggle-checked")).toBeVisible();
 }
 
+export async function fillDirectHostAddress(page: Page, host: string, port: string): Promise<void> {
+  await page.getByRole("textbox", { name: "Host", exact: true }).fill(host);
+  await page.getByRole("textbox", { name: "Port", exact: true }).fill(port);
+}
+
+export async function toggleDirectHostSsl(page: Page): Promise<void> {
+  await page.getByRole("checkbox", { name: "Use SSL", exact: true }).click();
+}
+
+export async function expectDirectHostSslDisabled(page: Page): Promise<void> {
+  await expect(page.getByRole("checkbox", { name: "Use SSL", exact: true })).not.toBeChecked();
+  await expect(page.getByTestId("direct-ssl-toggle-checked")).toHaveCount(0);
+}
+
 export async function expectDirectHostUriValue(page: Page, uri: string): Promise<void> {
   await expect(page.getByTestId("direct-host-uri-input")).toHaveValue(uri);
 }
diff --git a/packages/app/e2e/support/helpers/sheet.ts b/packages/app/e2e/support/helpers/sheet.ts
index 94c33747d0..36dcb61a85 100644
--- a/packages/app/e2e/support/helpers/sheet.ts
+++ b/packages/app/e2e/support/helpers/sheet.ts
@@ -112,3 +112,15 @@ export async function expectDeclinedDiscardPrompt(
   await close();
   expect(await prompt).toContain("discard the draft");
 }
+
+/** A seeded prompt the mock agent echoes, so the chat shows `target` as a tappable file link. */
+export function promptMentioning(target: string): string {
+  return [
+    "Generate a title and a git branch name for a coding agent from the user prompt and attachments.",
+    "Return JSON only with fields 'title' and 'branch'.",
+    "",
+    "<user-prompt>",
+    `Open \`${target}\` now`,
+    "</user-prompt>",
+  ].join("\n");
+}
diff --git a/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts b/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts
new file mode 100644
index 0000000000..85983578df
--- /dev/null
+++ b/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts
@@ -0,0 +1,127 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+/** Every footer control that can sit in the icon line, caret included. */
+const FOOTER_LINE_TEST_IDS = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+// Browser layout boxes include floating-point rounding, even for whole-pixel styles.
+const GEOMETRY_TOLERANCE = 0.01;
+
+/** Open the app with the docked sidebar at `width`, as if the user had dragged it there. */
+export async function seedDockedSidebarWidth(page: Page, width: number): Promise<void> {
+  await page.addInitScript((sidebarWidth) => {
+    localStorage.setItem("panel-state", JSON.stringify({ version: 17, state: { sidebarWidth } }));
+  }, width);
+}
+
+/**
+ * From the first frame, record any frame in which a footer button reaches past its row, so a row
+ * laid out before it measured shows up even if it lasted one frame.
+ */
+export async function watchFooterClipping(page: Page): Promise<void> {
+  await page.addInitScript((testIDs) => {
+    const clippedFrames: string[] = [];
+    Object.assign(window, { __footerClippedFrames: clippedFrames });
+    const sample = () => {
+      for (const row of document.querySelectorAll('[data-testid="sidebar-footer-bottom-line"]')) {
+        const rowRect = row.getBoundingClientRect();
+        if (rowRect.width === 0) continue;
+        for (const testID of testIDs) {
+          const button = row.querySelector(`[data-testid="${testID}"]`);
+          if (button && button.getBoundingClientRect().right > rowRect.right + 0.5) {
+            clippedFrames.push(testID);
+          }
+        }
+      }
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+  }, FOOTER_LINE_TEST_IDS);
+}
+
+export async function expectFooterNeverClipped(page: Page): Promise<void> {
+  const clipped = await page.evaluate(
+    () => (window as unknown as { __footerClippedFrames: string[] }).__footerClippedFrames,
+  );
+  expect(clipped).toEqual([]);
+}
+
+function footerLine(page: Page): Locator {
+  return page.locator('[data-testid="sidebar-footer-bottom-line"]:visible');
+}
+
+export function footerOverflowMenu(page: Page): Locator {
+  return page.getByTestId("sidebar-footer-overflow-menu");
+}
+
+/**
+ * The icon line shows exactly `testIDs`, in order, each `controlSize` square and wholly inside the
+ * line's box, so no button is cut off by the sidebar's edge.
+ */
+export async function expectFooterLine(
+  page: Page,
+  input: { testIDs: string[]; controlSize: number },
+): Promise<void> {
+  const line = footerLine(page);
+  await expect(line).toHaveCount(1);
+  await expect
+    .poll(async () =>
+      line
+        .locator(FOOTER_LINE_TEST_IDS.map((testID) => `[data-testid="${testID}"]`).join(","))
+        .evaluateAll((elements) => elements.map((element) => element.getAttribute("data-testid"))),
+    )
+    .toEqual(input.testIDs);
+  const { row, buttons } = await line.evaluate((element, testIDs) => {
+    const rect = (node: Element) => {
+      const { x, width, height } = node.getBoundingClientRect();
+      return { x, width, height };
+    };
+    return {
+      row: rect(element),
+      buttons: testIDs.map((testID) => rect(element.querySelector(`[data-testid="${testID}"]`)!)),
+    };
+  }, input.testIDs);
+  for (const button of buttons) {
+    expect(Math.abs(button.width - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(Math.abs(button.height - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(button.x).toBeGreaterThanOrEqual(row.x - GEOMETRY_TOLERANCE);
+    expect(button.x + button.width).toBeLessThanOrEqual(row.x + row.width + GEOMETRY_TOLERANCE);
+  }
+}
+
+export async function openFooterOverflow(page: Page): Promise<void> {
+  await footerLine(page).getByTestId("sidebar-footer-overflow").click();
+  await expect(footerOverflowMenu(page)).toBeVisible();
+}
+
+/** The overflow menu lists exactly these actions, in row order. */
+export async function expectFooterOverflowActions(page: Page, names: string[]): Promise<void> {
+  await expect(footerOverflowMenu(page).getByRole("menuitem")).toHaveText(names);
+}
+
+export async function chooseFooterOverflowAction(page: Page, name: string): Promise<void> {
+  await footerOverflowMenu(page).getByRole("menuitem", { name }).click();
+}
+
+/** Every row of the open overflow menu, and of the page it opened, is inside the viewport's width. */
+export async function expectFooterMenusInsideViewport(page: Page): Promise<void> {
+  const viewport = page.viewportSize()!;
+  const rows = page.getByRole("menuitem");
+  await expect(rows.first()).toBeVisible();
+  const boxes = await rows.evaluateAll((elements) =>
+    elements.map((element) => {
+      const { x, width } = element.getBoundingClientRect();
+      return { x, width };
+    }),
+  );
+  for (const box of boxes) {
+    expect(box.x).toBeGreaterThanOrEqual(0);
+    expect(box.x + box.width).toBeLessThanOrEqual(viewport.width);
+  }
+}
diff --git a/packages/app/e2e/support/helpers/sidebar-views.ts b/packages/app/e2e/support/helpers/sidebar-views.ts
new file mode 100644
index 0000000000..0c869235ae
--- /dev/null
+++ b/packages/app/e2e/support/helpers/sidebar-views.ts
@@ -0,0 +1,203 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, type Page } from "@playwright/test";
+import { copyPluginExample } from "./plugin-fixture";
+import { connectNewWorkspaceDaemonClient } from "./new-workspace";
+import { seedWorkspace } from "./seed-client";
+import { gotoWorkspace } from "./launcher";
+import { openSidebarNavSettings, leaveSettings } from "./sidebar-nav-settings";
+import { visibleTestId } from "./plugin-sidebar-items";
+import { getServerId } from "./server-id";
+
+export async function withSidebarViews(
+  page: Page,
+  run: (views: ReturnType<typeof sidebarViews>) => Promise<void>,
+) {
+  const example = await copyPluginExample("sidebar-views");
+  const entry = path.join(example.directory, "index.client.tsx");
+  const original = await readFile(entry, "utf8");
+  await writeFile(
+    entry,
+    original.replace(
+      "const cleanups = [",
+      'client.addSidebarView({ id: "broken", title: "Broken example", Component() { throw new Error("View failed"); } });\n  const cleanups = [',
+    ),
+  );
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const workspace = await seedWorkspace({
+    repoPrefix: "sidebar-views-",
+    title: "Sidebar view workspace",
+  });
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(example.directory);
+    await page.setViewportSize({ width: 1280, height: 900 });
+    await gotoWorkspace(page, workspace.workspaceId);
+    await run(sidebarViews(page, workspace.workspaceId, client));
+  } finally {
+    await client.removePlugin("sidebar-views");
+    await client.close();
+    await workspace.cleanup();
+    await example.cleanup();
+  }
+}
+function sidebarViews(
+  page: Page,
+  workspaceId: string,
+  client: Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>,
+) {
+  const builtinRow = () =>
+    visibleTestId(page, `sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+  async function choose(title: string) {
+    await openSidebarNavSettings(page);
+    await page.getByRole("button", { name: /^View:/ }).click();
+    await page.getByRole("menuitem", { name: title, exact: true }).click();
+    await expect(page.getByRole("button", { name: `View: ${title}`, exact: true })).toBeVisible();
+    await leaveSettings(page);
+  }
+  async function expectDefault() {
+    await expect(builtinRow()).toBeVisible();
+  }
+  async function expectPlugin() {
+    await expect(
+      visibleTestId(page, "plugin-sidebar-view").getByText("Sidebar view workspace", {
+        exact: true,
+      }),
+    ).toBeVisible();
+    await expect(builtinRow()).toHaveCount(0);
+    await expect(visibleTestId(page, "sidebar-global-new-workspace")).toBeVisible();
+    await expect(visibleTestId(page, "sidebar-settings")).toBeVisible();
+  }
+  return {
+    expectDefault,
+    async chooseWorkspaces() {
+      await choose("Example workspaces");
+      await expectPlugin();
+    },
+    async exerciseExamples() {
+      await choose("Example agents");
+      await expect(
+        visibleTestId(page, "plugin-sidebar-view").getByText("Respond", { exact: true }),
+      ).toBeVisible();
+      await choose("Example nested agents");
+      await expectPlugin();
+      await choose("Example label folders");
+      const slot = visibleTestId(page, "plugin-sidebar-view");
+      await slot
+        .getByRole("button", { name: `Move workspace ${workspaceId}`, exact: true })
+        .click();
+      await slot.getByRole("button", { name: "Move to Inbox", exact: true }).click();
+      await expect
+        .poll(
+          async () =>
+            (await client.fetchWorkspaces()).entries.find((item) => item.id === workspaceId)
+              ?.labels,
+        )
+        .toContain("Inbox");
+      await slot
+        .getByRole("button", { name: `Move workspace ${workspaceId}`, exact: true })
+        .click();
+      await slot.getByRole("button", { name: "Move to Later", exact: true }).click();
+      await expect
+        .poll(
+          async () =>
+            (await client.fetchWorkspaces()).entries.find((item) => item.id === workspaceId)
+              ?.labels,
+        )
+        .toEqual(["Later"]);
+      await client.setWorkspaceLabel({
+        workspaceId,
+        label: { name: "Unlabelled", color: "red" },
+        assigned: true,
+      });
+      // Wait for the named label folder alongside the built-in unlabelled bucket.
+      // Counts alone can match stale Inbox/Later rows from the preceding move.
+      await expect(
+        slot.getByRole("button", { name: "Toggle Unlabelled", exact: true }),
+      ).toHaveCount(2);
+      // Observe both label rows before removing Later so a stale single row
+      // cannot satisfy the final readiness check.
+      const moveWorkspace = slot.getByRole("button", {
+        name: `Move workspace ${workspaceId}`,
+        exact: true,
+      });
+      await expect(moveWorkspace).toHaveCount(2);
+      await client.setWorkspaceLabel({
+        workspaceId,
+        label: { name: "Later", color: "red" },
+        assigned: false,
+      });
+      await expect
+        .poll(
+          async () =>
+            (await client.fetchWorkspaces()).entries.find((item) => item.id === workspaceId)
+              ?.labels,
+        )
+        .toEqual(["Unlabelled"]);
+      // The daemon reply does not guarantee the browser has applied the removal.
+      await expect(moveWorkspace).toHaveCount(1);
+      await moveWorkspace.click();
+      await slot.getByRole("button", { name: "Move to Inbox", exact: true }).click();
+      await expect
+        .poll(
+          async () =>
+            (await client.fetchWorkspaces()).entries.find((item) => item.id === workspaceId)
+              ?.labels,
+        )
+        .toEqual(["Inbox"]);
+    },
+    async exerciseTerminals() {
+      await choose("Example terminals");
+      const slot = visibleTestId(page, "plugin-sidebar-view");
+      await slot
+        .getByRole("button", { name: `Terminals on ${getServerId()}`, exact: true })
+        .click();
+      await expect(slot.getByText("No terminals", { exact: true })).toBeVisible();
+      const workspace = (await client.fetchWorkspaces()).entries.find(
+        (item) => item.id === workspaceId,
+      )!;
+      const created = await client.createTerminal(
+        workspace.workspaceDirectory,
+        "Sidebar terminal",
+        undefined,
+        { workspaceId },
+      );
+      if (!created.terminal) throw new Error(created.error ?? "Terminal creation failed");
+      try {
+        await expect(
+          slot.getByTestId(`sidebar-terminal-open-${created.terminal.id}`),
+        ).toBeVisible();
+        await slot.getByTestId(`sidebar-terminal-open-${created.terminal.id}`).click();
+        await expect(page.getByTestId("terminal-surface").first()).toBeVisible();
+        await slot.getByTestId(`sidebar-terminal-kill-${created.terminal.id}`).click();
+        await expect
+          .poll(async () => (await client.listTerminals()).terminals.map((item) => item.id))
+          .not.toContain(created.terminal!.id);
+        await expect(slot.getByText("No terminals", { exact: true })).toBeVisible();
+      } finally {
+        await client.killTerminal(created.terminal.id);
+      }
+    },
+    async restoreDefault() {
+      await choose("Default view");
+      await expectDefault();
+    },
+    async recoverFromFailure() {
+      await choose("Broken example");
+      await expect(page.getByText("Sidebar view failed to load.", { exact: true })).toBeVisible();
+      await page.getByRole("button", { name: "Use default view", exact: true }).click();
+      await expectDefault();
+    },
+    async disableChosenView() {
+      await client.disablePlugin("sidebar-views");
+      await expectDefault();
+      await openSidebarNavSettings(page);
+      await expect(
+        page.getByText("The selected view is unavailable or disabled. Showing Default view.", {
+          exact: true,
+        }),
+      ).toBeVisible();
+      await leaveSettings(page);
+    },
+  };
+}
diff --git a/packages/app/e2e/support/helpers/sidebar.ts b/packages/app/e2e/support/helpers/sidebar.ts
index 66a913e7b3..96d1441070 100644
--- a/packages/app/e2e/support/helpers/sidebar.ts
+++ b/packages/app/e2e/support/helpers/sidebar.ts
@@ -71,8 +71,23 @@ export async function focusWorkspaceRowWithKeyboard(
   await expect(row).toBeFocused();
 }
 
+export async function scrollWorkspaceList(page: Page): Promise<void> {
+  const list = page.getByTestId("sidebar-project-workspace-list-scroll");
+  const before = await list.evaluate((element) => element.scrollTop);
+  await list.evaluate((element) =>
+    element.scrollBy({ top: element.scrollTop > 0 ? -40 : 40, behavior: "instant" }),
+  );
+  await expect.poll(() => list.evaluate((element) => element.scrollTop)).not.toBe(before);
+}
+
 export async function expectWorkspaceHoverCardOpen(page: Page): Promise<void> {
-  await expect(page.getByTestId("workspace-hover-card")).toBeVisible();
+  const cards = page.getByTestId("workspace-hover-card");
+  // Keyboard navigation can leave the previous card closing while the next opens.
+  // Retry both checks together: another card may mount between count and visibility.
+  await expect(async () => {
+    expect(await cards.count()).toBe(1);
+    expect(await cards.isVisible()).toBe(true);
+  }).toPass({ timeout: 10_000 });
 }
 
 export async function expectWorkspaceHoverCardStaysOpen(page: Page): Promise<void> {
@@ -81,6 +96,35 @@ export async function expectWorkspaceHoverCardStaysOpen(page: Page): Promise<voi
   await expectWorkspaceHoverCardOpen(page);
 }
 
+/** Scans the rows in the given order at about a user's pace, then rests on the last one. */
+export async function sweepPointerAcrossWorkspaceRows(
+  page: Page,
+  workspaceIds: string[],
+): Promise<void> {
+  const centers: Array<{ x: number; y: number }> = [];
+  for (const workspaceId of workspaceIds) {
+    const row = page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+    await expect(row).toBeVisible({ timeout: 30_000 });
+    const bounds = await row.boundingBox();
+    if (!bounds) throw new Error(`Could not measure the row of ${workspaceId}`);
+    centers.push({ x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 });
+  }
+  const [first, ...rest] = centers;
+  await page.mouse.move(first!.x, first!.y);
+  for (const center of rest) {
+    await page.mouse.move(center.x, center.y, { steps: 3 });
+  }
+}
+
+export async function expectOnlyWorkspaceHoverCardFor(
+  page: Page,
+  workspaceName: string,
+): Promise<void> {
+  const cards = page.getByTestId("workspace-hover-card");
+  await expect(cards).toHaveCount(1);
+  await expect(cards.getByTestId("hover-card-workspace-name")).toHaveText(workspaceName);
+}
+
 export async function expectWorkspaceHoverCardClosed(page: Page): Promise<void> {
   await expect(page.getByTestId("workspace-hover-card")).toHaveCount(0);
 }
@@ -252,16 +296,9 @@ export async function expectMobileAgentSidebarHidden(page: Page): Promise<void>
   await expect(page.getByTestId("sidebar-sessions")).not.toBeInViewport({ timeout: 5_000 });
 }
 
-/** Drag from the left edge: the only way to open the list while fullscreen hides the header. */
-export async function swipeOpenMobileAgentSidebar(page: Page): Promise<void> {
-  const viewport = page.viewportSize();
-  if (!viewport) throw new Error("viewport size is required");
-  const y = Math.round(viewport.height / 2);
-  await page.mouse.move(8, y);
-  await page.mouse.down();
-  await page.mouse.move(40, y, { steps: 4 });
-  await page.mouse.move(Math.round(viewport.width * 0.7), y, { steps: 12 });
-  await page.mouse.up();
+/** Opens navigation without moving focus to the header, including over a fullscreen editor. */
+export async function openMobileAgentSidebarWithKeyboard(page: Page): Promise<void> {
+  await page.keyboard.press("ControlOrMeta+b");
 }
 
 /** Drag from the right edge to open the compact Explorer over the agent. */
diff --git a/packages/app/e2e/support/helpers/timeline-pagination.ts b/packages/app/e2e/support/helpers/timeline-pagination.ts
index e575f4f0d9..ed69897e4e 100644
--- a/packages/app/e2e/support/helpers/timeline-pagination.ts
+++ b/packages/app/e2e/support/helpers/timeline-pagination.ts
@@ -477,18 +477,29 @@ export async function expectStableHistoryStartGutter(page: Page): Promise<void>
     .toBe(32);
 }
 
-export async function scrollTimelinePromptIntoView(page: Page, prompt: string): Promise<void> {
+/**
+ * Wheels the timeline until `row` is centered, as a reader does. Playwright's own
+ * scroll-into-view is programmatic, which the timeline does not treat as the reader leaving
+ * the bottom: it snaps back to the bottom and can move the row away mid-click.
+ */
+export async function scrollTimelineRowIntoView(page: Page, row: Locator): Promise<void> {
   const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
-  const row = timeline.getByTestId("user-message").filter({ hasText: prompt });
   const [viewport, target] = await Promise.all([timeline.boundingBox(), row.boundingBox()]);
   if (!viewport || !target) {
-    throw new Error(`Expected a rendered timeline prompt for ${prompt}`);
+    throw new Error("Expected a rendered timeline row");
   }
-  // Programmatic scrolling does not express the user's intent to stop following output.
   await timeline.hover();
   await page.mouse.wheel(0, target.y - viewport.y - (viewport.height - target.height) / 2);
   await expect(row).toBeInViewport({ ratio: 1 });
   await waitForTimelineGeometryToSettle(page);
+}
+
+export async function scrollTimelinePromptIntoView(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scrollTimelineRowIntoView(
+    page,
+    timeline.getByTestId("user-message").filter({ hasText: prompt }),
+  );
   await expect
     .poll(async () => (await readTimelineViewport(page)).scrollTop)
     .toBeGreaterThan(HISTORY_START_THRESHOLD_PX);
@@ -564,8 +575,10 @@ export async function expectFoldedTurnAtReadingPosition(page: Page, prompt: stri
   const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
   const promptRow = timeline.locator("[data-history-row-id]").filter({ hasText: prompt });
   await expect(promptRow).toBeVisible({ timeout: 15_000 });
-  // The host row carries the folded turn's summary line.
-  await expect(promptRow.getByTestId("turn-summary")).toBeVisible();
+  // The folded turn's summary line is the row under its prompt.
+  const hostId = await promptRow.getAttribute("data-history-row-id");
+  const summaryRow = timeline.locator(`[data-history-row-id="turn-summary:${hostId}"]`);
+  await expect(summaryRow.getByTestId("turn-summary")).toBeVisible();
   await expect
     .poll(
       async () => {
diff --git a/packages/app/e2e/support/helpers/timeline-resume.ts b/packages/app/e2e/support/helpers/timeline-resume.ts
index d8926013b2..028ab90f03 100644
--- a/packages/app/e2e/support/helpers/timeline-resume.ts
+++ b/packages/app/e2e/support/helpers/timeline-resume.ts
@@ -1,14 +1,32 @@
 import { expect, type Page } from "@playwright/test";
 import type { installDaemonWebSocketGate } from "./daemon-websocket-gate";
+import { readReplicaCache } from "./replica-cache-storage";
 import type { LongTimelineAgent } from "./timeline-pagination";
-import { expectReconnectingToastGone, expectReconnectingToastVisible } from "./workspace-ui";
+import {
+  expectReconnectingToastGone,
+  expectReconnectingToastVisible,
+  setTabVisibility,
+} from "./workspace-ui";
 
 type DaemonWebSocketGate = Awaited<ReturnType<typeof installDaemonWebSocketGate>>;
 
+const SUBSCRIPTION_REQUEST = "agent.timeline.set_subscription.request";
+const SUBSCRIPTION_RESPONSE = "agent.timeline.set_subscription.response";
+const TIMELINE_REQUEST = "fetch_agent_timeline_request";
+const TIMELINE_RESPONSE = "fetch_agent_timeline_response";
+/**
+ * `FRESHNESS_CHECK_QUIET_MS` is 500: an opening check unanswered that long reports Updating messages by
+ * design, however long the daemon takes. The app starts that wait just before it sends the question
+ * this helper times, so the bound stops short of 500.
+ */
+const QUIET_WINDOW_FLOOR_MS = 300;
+
 export interface TimelineRequestCounts {
   agentId?: string;
   after: number;
   tail: number;
+  subscriptions: number;
+  fetches: number;
 }
 
 export interface BackgroundTimelineTurns {
@@ -42,17 +60,140 @@ export function rememberTimelineRequestCounts(
     agentId,
     after: gate.getTimelineRequestCount("after", agentId),
     tail: gate.getTimelineRequestCount("tail", agentId),
+    subscriptions: gate.getClientRequestCount(SUBSCRIPTION_REQUEST),
+    fetches: gate.getClientRequestCount(TIMELINE_REQUEST),
   };
 }
 
-export function expectOneResumeCheckWithoutTail(
+export function expectResumeAnsweredWithoutFetch(
   gate: DaemonWebSocketGate,
   before: TimelineRequestCounts,
 ): void {
-  expect(gate.getTimelineRequestCount("after", before.agentId) - before.after).toBe(1);
+  expect(gate.getTimelineRequestCount("after", before.agentId) - before.after).toBe(0);
   expect(gate.getTimelineRequestCount("tail", before.agentId) - before.tail).toBe(0);
 }
 
+/** Resolves once the daemon has told the app where this chat stands, whichever way it asked. */
+export async function waitForResumeAnswer(
+  gate: DaemonWebSocketGate,
+  before: TimelineRequestCounts,
+): Promise<void> {
+  await Promise.race([
+    gate.waitForServerMessage(SUBSCRIPTION_RESPONSE, before.subscriptions + 1),
+    gate.waitForServerMessage(TIMELINE_RESPONSE, before.fetches + 1),
+  ]);
+}
+
+interface UpdatingToastTiming {
+  askedAt: number | null;
+  shownAt: number | null;
+}
+
+declare global {
+  interface Window {
+    __updatingToastTiming?: UpdatingToastTiming;
+  }
+}
+
+/** Runs in the page: times the freshness question and the toast's first commit on its own clock. */
+function recordUpdatingToastTiming(): void {
+  const noteToast = (timing: UpdatingToastTiming) => {
+    if (document.querySelector('[data-testid="agent-updating-toast"]') === null) return;
+    timing.shownAt ??= performance.now();
+  };
+  const existing = window.__updatingToastTiming;
+  if (existing) {
+    existing.askedAt = null;
+    existing.shownAt = null;
+    noteToast(existing);
+    return;
+  }
+  const timing: UpdatingToastTiming = { askedAt: null, shownAt: null };
+  window.__updatingToastTiming = timing;
+  const send = WebSocket.prototype.send;
+  WebSocket.prototype.send = function sendRecordingQuestion(data) {
+    if (
+      typeof data === "string" &&
+      data.includes("agent.timeline.set_subscription.request") &&
+      data.includes('"agentIds":["')
+    ) {
+      timing.askedAt ??= performance.now();
+    }
+    return send.call(this, data);
+  };
+  new MutationObserver(() => noteToast(timing)).observe(document, {
+    childList: true,
+    subtree: true,
+  });
+  noteToast(timing);
+}
+
+/** A toast may only follow an unanswered question; nothing about the daemon's speed changes that. */
+async function expectToastWaitedForTheDaemon(page: Page): Promise<void> {
+  await waitForNextPaint(page);
+  const showedTooSoon = await page.evaluate((floorMs) => {
+    const { askedAt, shownAt } = window.__updatingToastTiming as UpdatingToastTiming;
+    if (shownAt === null) return false;
+    return askedAt === null || shownAt - askedAt < floorMs;
+  }, QUIET_WINDOW_FLOOR_MS);
+  expect(showedTooSoon, "the Updating messages toast did not wait for the daemon").toBe(false);
+}
+
+/** Records every appearance of the toast, including one that lasts a single commit. */
+export async function watchForUpdatingToast(page: Page): Promise<() => Promise<void>> {
+  await page.evaluate(recordUpdatingToastTiming);
+  return () => expectToastWaitedForTheDaemon(page);
+}
+
+/** Reopens the app on this chat, recording the toast from the first paint of the new page. */
+export async function reopenAppWatchingForUpdatingToast(page: Page): Promise<() => Promise<void>> {
+  await page.addInitScript(recordUpdatingToastTiming);
+  await page.reload();
+  return () => expectToastWaitedForTheDaemon(page);
+}
+
+/** Opens persisted history with the daemon's freshness answer held. */
+export async function reopenWithFreshnessCheckUnanswered(
+  page: Page,
+  gate: DaemonWebSocketGate,
+  agent: LongTimelineAgent,
+): Promise<void> {
+  // A cold open needs a persisted authoritative cursor to ask a freshness question.
+  await expect
+    .poll(async () => {
+      const cache = await readReplicaCache(page);
+      return cache?.hosts
+        ?.flatMap((host) => host.timelines)
+        .find((timeline) => timeline.agentId === agent.agentId)?.range?.endSeq;
+    })
+    .toBeGreaterThan(0);
+  gate.holdNextClientRequest(SUBSCRIPTION_REQUEST);
+  await page.reload();
+  await expect(page.getByText(agent.newestPrompt, { exact: true })).toBeVisible();
+  await gate.waitForHeldClientRequest();
+  await expect(page.getByRole("alert").filter({ hasText: "Updating messages" })).toBeVisible();
+}
+
+export async function answerFreshnessCheck(page: Page, gate: DaemonWebSocketGate): Promise<void> {
+  gate.releaseHeldClientRequest();
+  await expect(page.getByRole("alert").filter({ hasText: "Updating messages" })).toHaveCount(0);
+}
+
+async function waitForNextPaint(page: Page): Promise<void> {
+  await page.evaluate(
+    () =>
+      new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      }),
+  );
+}
+
+export async function hideTabAndReturn(page: Page): Promise<void> {
+  await setTabVisibility(page, "hidden");
+  await waitForNextPaint(page);
+  await setTabVisibility(page, "visible");
+}
+
 export function expectResumeOverflowFallsBackToOneTail(
   gate: DaemonWebSocketGate,
   before: TimelineRequestCounts,
@@ -69,15 +210,34 @@ export async function disconnectViewedTimeline(
   await expectReconnectingToastVisible(page);
 }
 
-export async function restoreViewedTimelineWithHeldResponse(
+export async function restoreViewedTimelineHoldingCatchUp(
   page: Page,
   gate: DaemonWebSocketGate,
 ): Promise<void> {
-  gate.holdNextServerMessage("fetch_agent_timeline_response");
+  gate.holdNextServerMessage(TIMELINE_RESPONSE);
   gate.restore();
   await gate.waitForHeldServerMessage();
   await expectReconnectingToastGone(page);
   await expect(page.getByRole("alert").filter({ hasText: "Updating messages" })).toBeVisible();
+}
+
+export async function releaseHeldCatchUp(page: Page, gate: DaemonWebSocketGate): Promise<void> {
   gate.releaseHeldServerMessage();
   await expect(page.getByRole("alert").filter({ hasText: "Updating messages" })).toHaveCount(0);
 }
+
+export async function restoreViewedTimelineWithHeldResponse(
+  page: Page,
+  gate: DaemonWebSocketGate,
+): Promise<void> {
+  await restoreViewedTimelineHoldingCatchUp(page, gate);
+  await releaseHeldCatchUp(page, gate);
+}
+
+export async function restoreUnchangedViewedTimeline(
+  page: Page,
+  gate: DaemonWebSocketGate,
+): Promise<void> {
+  gate.restore();
+  await expectReconnectingToastGone(page);
+}
diff --git a/packages/app/e2e/support/helpers/usage-reports.ts b/packages/app/e2e/support/helpers/usage-reports.ts
index bb46e52f95..6f617f70b2 100644
--- a/packages/app/e2e/support/helpers/usage-reports.ts
+++ b/packages/app/e2e/support/helpers/usage-reports.ts
@@ -11,6 +11,8 @@ export interface UsageListRequest {
 export interface UsageReportsFixture {
   listRequests(): UsageListRequest[];
   waitForListRequests(count: number): Promise<void>;
+  /** Runs `action`, then waits until the app has received the agent's next usage scope. */
+  untilUsageScopeChanges(agentId: string, action: () => Promise<unknown>): Promise<void>;
 }
 
 interface UsageReportsFixtureOptions {
@@ -97,6 +99,26 @@ function withUsageSupportFeature(
   });
 }
 
+function agentUsageScope(message: WebSocketMessage): { agentId: string; key: string } | null {
+  const envelope = parseJson(message) as {
+    type?: unknown;
+    message?: {
+      type?: unknown;
+      payload?: { kind?: unknown; agent?: { id?: unknown; usageScopeKey?: unknown } };
+    };
+  } | null;
+  const agent = envelope?.message?.payload?.agent;
+  if (
+    envelope?.message?.type !== "agent_update" ||
+    envelope.message.payload?.kind !== "upsert" ||
+    typeof agent?.id !== "string" ||
+    typeof agent.usageScopeKey !== "string"
+  ) {
+    return null;
+  }
+  return { agentId: agent.id, key: agent.usageScopeKey };
+}
+
 function pick<T>(values: T[], index: number): T {
   const value = values[Math.min(index, values.length - 1)];
   if (value === undefined) throw new Error("Usage fixture requires at least one response.");
@@ -127,6 +149,16 @@ export async function installUsageReportsFixture(
 ): Promise<UsageReportsFixture> {
   const listRequests: UsageListRequest[] = [];
   const listCounter = createCounter();
+  const usageScopes = new Map<string, string>();
+  const usageScopeChanges = new Map<string, ReturnType<typeof createCounter>>();
+  const usageScopeCounts = new Map<string, number>();
+  const usageScopeCounter = (agentId: string) => {
+    const existing = usageScopeChanges.get(agentId);
+    if (existing) return existing;
+    const created = createCounter();
+    usageScopeChanges.set(agentId, created);
+    return created;
+  };
   const usageSupported = options.usageSupported ?? true;
   const isUsageSupported = () =>
     typeof usageSupported === "function" ? usageSupported() : usageSupported;
@@ -239,6 +271,15 @@ export async function installUsageReportsFixture(
               options.usageSettingSupported ?? true,
             )
           : null;
+      const scope = agentUsageScope(message);
+      if (scope && usageScopes.get(scope.agentId) !== scope.key) {
+        usageScopes.set(scope.agentId, scope.key);
+        usageScopeCounts.set(scope.agentId, (usageScopeCounts.get(scope.agentId) ?? 0) + 1);
+        // The app must hold the new scope before a test acts on it.
+        ws.send(serverInfo ?? message);
+        usageScopeCounter(scope.agentId).increment();
+        return;
+      }
       ws.send(serverInfo ?? message);
     });
   });
@@ -246,5 +287,10 @@ export async function installUsageReportsFixture(
   return {
     listRequests: () => [...listRequests],
     waitForListRequests: (count) => listCounter.waitFor(count),
+    untilUsageScopeChanges: async (agentId, action) => {
+      const next = (usageScopeCounts.get(agentId) ?? 0) + 1;
+      await action();
+      await usageScopeCounter(agentId).waitFor(next);
+    },
   };
 }
diff --git a/packages/app/e2e/support/helpers/workspace-archive-undo.ts b/packages/app/e2e/support/helpers/workspace-archive-undo.ts
new file mode 100644
index 0000000000..7f6846b252
--- /dev/null
+++ b/packages/app/e2e/support/helpers/workspace-archive-undo.ts
@@ -0,0 +1,164 @@
+import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { Page } from "@playwright/test";
+import { expect } from "../fixtures";
+import type { connectNewWorkspaceDaemonClient } from "./new-workspace";
+import { daemonWsRoutePattern } from "./daemon-port";
+import { getServerId } from "./server-id";
+import { expectWorkspaceAbsentFromSidebar } from "./sidebar";
+
+type DaemonClient = Awaited<ReturnType<typeof connectNewWorkspaceDaemonClient>>;
+
+const UNDO_SHORTCUT = process.platform === "darwin" ? "Meta+Z" : "Control+Z";
+const ARCHIVE_SHORTCUT =
+  process.platform === "darwin" ? "Meta+Shift+Backspace" : "Control+Shift+Backspace";
+/** The archived toast's lifetime, from `WORKSPACE_ARCHIVE_UNDO_WINDOW_MS`. */
+const UNDO_WINDOW_MS = 6000;
+
+export function workspaceRow(page: Page, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+}
+
+export function rowArchiveButton(page: Page, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-archive-button-${getServerId()}:${workspaceId}`);
+}
+
+export function rowKebab(page: Page, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-kebab-${getServerId()}:${workspaceId}`);
+}
+
+export function undoButton(page: Page) {
+  return page.getByRole("button", { name: /^Undo/ });
+}
+
+export async function workspaceTitleWidth(page: Page, workspaceId: string): Promise<number> {
+  const box = await page
+    .getByTestId(`sidebar-workspace-title-${getServerId()}:${workspaceId}`)
+    .boundingBox();
+  if (!box) throw new Error(`Title of ${workspaceId} is not laid out`);
+  return box.width;
+}
+
+/** Archives a workspace with its row's hover button and waits for the undo toast. */
+export async function archiveFromRowButton(page: Page, workspaceId: string): Promise<void> {
+  page.once("dialog", (dialog) => void dialog.accept());
+  await workspaceRow(page, workspaceId).hover();
+  await rowArchiveButton(page, workspaceId).click();
+  await expectWorkspaceAbsentFromSidebar(page, workspaceId);
+  await expect(undoButton(page)).toBeVisible();
+}
+
+/** Drags the sidebar's edge past its minimum, leaving it as narrow as it goes. */
+export async function resizeSidebarToMinimum(page: Page): Promise<void> {
+  const handle = await page.getByTestId("left-sidebar-resize-handle").boundingBox();
+  if (!handle) throw new Error("Sidebar resize handle is not laid out");
+  const y = handle.y + handle.height / 2;
+  await page.mouse.move(handle.x + handle.width / 2, y);
+  await page.mouse.down();
+  await page.mouse.move(handle.x - 30, y, { steps: 8 });
+  await page.mouse.move(10, y, { steps: 16 });
+  await page.mouse.up();
+  await expect
+    .poll(async () => (await page.getByTestId("sidebar-footer").boundingBox())?.width)
+    .toBeLessThanOrEqual(200);
+}
+
+export async function pressArchiveShortcut(page: Page): Promise<void> {
+  await page.keyboard.press(ARCHIVE_SHORTCUT);
+}
+
+export async function pressUndoShortcut(page: Page): Promise<void> {
+  await page.keyboard.press(UNDO_SHORTCUT);
+}
+
+/** Moves the page clock past the moment an unheld archived toast would have closed. */
+export async function outlastUndoWindow(page: Page): Promise<void> {
+  await page.clock.fastForward(UNDO_WINDOW_MS + 1000);
+}
+
+/** Waits until the host lists the workspace as active with no archive running on it. */
+export async function expectHostWorkspaceSettledActive(
+  client: DaemonClient,
+  workspaceId: string,
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const { entries } = await client.fetchWorkspaces();
+        const entry = entries.find((candidate) => candidate.id === workspaceId);
+        return entry ? { active: true, archiving: Boolean(entry.archivingAt) } : null;
+      },
+      { timeout: 30_000 },
+    )
+    .toEqual({ active: true, archiving: false });
+}
+
+export async function expectDirectoryPresence(directory: string, present: boolean): Promise<void> {
+  await expect.poll(() => existsSync(directory), { timeout: 30_000 }).toBe(present);
+}
+
+export interface HeldArchiveRequest {
+  waitForHeld(): Promise<void>;
+  /** Sends the held request to the daemon naming a workspace it has no record of, so it refuses. */
+  releaseForUnknownWorkspace(workspaceId: string): void;
+}
+
+/** Keeps the next archive request from reaching the daemon until the test releases it. */
+export async function holdNextArchiveRequest(page: Page): Promise<HeldArchiveRequest> {
+  let held: { request: SessionRequest; forward: (raw: string) => void } | null = null;
+  await page.routeWebSocket(daemonWsRoutePattern(), (browser) => {
+    const server = browser.connectToServer();
+    browser.onMessage((message) => {
+      const request = parseSessionRequest(message);
+      if (!held && request?.type === "archive_workspace_request") {
+        held = { request, forward: (raw) => server.send(raw) };
+        return;
+      }
+      server.send(message);
+    });
+    server.onMessage((message) => browser.send(message));
+  });
+  return {
+    waitForHeld: () => expect.poll(() => held !== null).toBe(true),
+    releaseForUnknownWorkspace: (workspaceId) => {
+      if (!held) throw new Error("No archive request is held");
+      held.forward(JSON.stringify({ type: "session", message: { ...held.request, workspaceId } }));
+    },
+  };
+}
+
+interface SessionRequest {
+  type: string;
+  requestId: string;
+  workspaceId: string;
+}
+
+function parseSessionRequest(message: string | Buffer): SessionRequest | null {
+  try {
+    const envelope = JSON.parse(typeof message === "string" ? message : message.toString("utf8"));
+    return envelope?.type === "session" ? envelope.message : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface GatedTeardown {
+  /** The `paseo.json` config whose worktree teardown parks until released. */
+  paseoConfig: Record<string, unknown>;
+  expectStarted(): Promise<void>;
+  release(): void;
+}
+
+/** A worktree teardown that parks an archive mid-flight, so an undo lands while it runs. */
+export function createGatedTeardown(): GatedTeardown {
+  const gateDir = mkdtempSync(path.join(tmpdir(), "archive-undo-gate-"));
+  const startedPath = path.join(gateDir, "started");
+  const releasePath = path.join(gateDir, "release");
+  const teardown = `node -e "const fs=require('fs');fs.writeFileSync('${startedPath}','started');const timer=setInterval(()=>{if(fs.existsSync('${releasePath}'))clearInterval(timer)},20)"`;
+  return {
+    paseoConfig: { worktree: { teardown: [teardown] } },
+    expectStarted: () => expectDirectoryPresence(startedPath, true),
+    release: () => writeFileSync(releasePath, "release\n"),
+  };
+}
diff --git a/packages/app/e2e/support/helpers/workspace-setup.ts b/packages/app/e2e/support/helpers/workspace-setup.ts
index eda1d8d023..a89f52c70a 100644
--- a/packages/app/e2e/support/helpers/workspace-setup.ts
+++ b/packages/app/e2e/support/helpers/workspace-setup.ts
@@ -1,3 +1,5 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
 import { realpathSync } from "node:fs";
 import { expect, type Page } from "@playwright/test";
 import type { DaemonClient as InternalDaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -380,3 +382,21 @@ export function observeSetupPanelTraffic(page: Page) {
 export function setupCommandOutput(detail: { commands: Array<{ log: string }> }): string {
   return detail.commands.map((command) => command.log).join("\n");
 }
+
+/** Hold this isolated daemon's terminal worker so script exit cannot race a layout change. */
+export async function pauseWorkspaceTerminalWorker(terminalId: string): Promise<() => void> {
+  const home = process.env.E2E_PASEO_HOME;
+  if (!home) throw new Error("Missing isolated E2E home");
+  const directory = path.join(home, "terminal-worker");
+  for (const name of await readdir(directory)) {
+    if (!name.endsWith(".json")) continue;
+    const record = JSON.parse(await readFile(path.join(directory, name), "utf8")) as {
+      pid: number;
+      terminals: Array<{ id: string }>;
+    };
+    if (!record.terminals.some((terminal) => terminal.id === terminalId)) continue;
+    process.kill(record.pid, "SIGSTOP");
+    return () => process.kill(record.pid, "SIGCONT");
+  }
+  throw new Error(`No isolated terminal worker owns ${terminalId}`);
+}
diff --git a/packages/app/e2e/support/helpers/workspace-tabs.ts b/packages/app/e2e/support/helpers/workspace-tabs.ts
index 8ddd507563..c124e12df2 100644
--- a/packages/app/e2e/support/helpers/workspace-tabs.ts
+++ b/packages/app/e2e/support/helpers/workspace-tabs.ts
@@ -61,6 +61,23 @@ function explorerSidebar(page: Page) {
   return visibleTestId(page, "workspace-explorer-sidebar").first();
 }
 
+export async function dragTabIntoExplorer(page: Page, tabId: string): Promise<void> {
+  const source = page.getByTestId("workspace-pane-main").getByTestId(`workspace-tab-${tabId}`);
+  const destination = explorerSidebar(page).getByTestId("workspace-tab-files");
+  const sourceBox = await source.boundingBox();
+  const destinationBox = await destination.boundingBox();
+  if (!sourceBox || !destinationBox)
+    throw new Error("Tab drag requires visible source and destination");
+  const start = { x: sourceBox.x + 12, y: sourceBox.y + sourceBox.height / 2 };
+  await page.mouse.move(start.x, start.y);
+  await page.mouse.down();
+  await page.mouse.move(start.x + 12, start.y + 4);
+  await page.mouse.move(destinationBox.x + 12, destinationBox.y + destinationBox.height / 2, {
+    steps: 20,
+  });
+  await page.mouse.up();
+}
+
 async function selectWorkspaceTab(tab: Locator): Promise<void> {
   if ((await tab.getAttribute("aria-selected")) !== "true") {
     // The close action overlays the chip's trailing edge on hover. Click the
diff --git a/packages/app/e2e/support/helpers/workspace-ui.ts b/packages/app/e2e/support/helpers/workspace-ui.ts
index fe03ec053c..3e8aa0401c 100644
--- a/packages/app/e2e/support/helpers/workspace-ui.ts
+++ b/packages/app/e2e/support/helpers/workspace-ui.ts
@@ -91,6 +91,20 @@ export async function expectWorkspaceHeader(
   });
 }
 
+export async function setTabVisibility(
+  page: Page,
+  visibility: DocumentVisibilityState,
+): Promise<void> {
+  await page.evaluate((state) => {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      get: () => state === "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+  }, visibility);
+}
+
 export async function expectReconnectingToastVisible(
   page: Page,
   options?: { timeout?: number },
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/build.gradle b/packages/app/modules/paseo-hardware-keyboard/android/build.gradle
new file mode 100644
index 0000000000..62031857e0
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/build.gradle
@@ -0,0 +1,16 @@
+apply plugin: 'com.android.library'
+apply plugin: 'expo-module-gradle-plugin'
+
+group = 'sh.paseo.keyboard'
+version = '0.1.0'
+android {
+  namespace 'sh.paseo.keyboard'
+  defaultConfig {
+    versionCode 1
+    versionName '0.1.0'
+  }
+}
+dependencies {
+  implementation 'com.facebook.react:react-android'
+  testImplementation 'junit:junit:4.13.2'
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/HardwareCharacterKey.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/HardwareCharacterKey.kt
new file mode 100644
index 0000000000..bccf25fe6b
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/HardwareCharacterKey.kt
@@ -0,0 +1,7 @@
+package sh.paseo.keyboard
+
+import android.view.KeyCharacterMap
+
+internal fun hardwareCharacterKey(character: Int): String =
+  if (character and KeyCharacterMap.COMBINING_ACCENT != 0) "Dead"
+  else String(Character.toChars(character))
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardModule.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardModule.kt
new file mode 100644
index 0000000000..f8b5fd7d31
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardModule.kt
@@ -0,0 +1,164 @@
+package sh.paseo.keyboard
+
+import android.content.ComponentCallbacks
+import android.content.res.Configuration
+import android.hardware.input.InputManager
+import android.os.Handler
+import android.os.Looper
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.Window
+import android.widget.EditText
+import android.view.inputmethod.BaseInputConnection
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.interfaces.ExtraWindowEventListener
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+internal object HardwareKeyboard {
+  var module: PaseoHardwareKeyboardModule? = null
+  @Volatile var overlayKeys: Set<String> = emptySet()
+  private val windows = mutableMapOf<Window, KeyboardWindowCallback>()
+  val dispatcher = WindowKeyDispatcher<KeyEvent>()
+  private val consumedPresses = mutableSetOf<Int>()
+
+  fun observe(window: Window) {
+    if (windows.containsKey(window)) return
+    val callback = KeyboardWindowCallback(window, window.callback)
+    windows[window] = callback
+    window.callback = callback
+  }
+  fun release(window: Window) {
+    val callback = windows.remove(window) ?: return
+    if (window.callback === callback) window.callback = callback.previous
+  }
+  fun releaseAll() {
+    windows.keys.toList().forEach { release(it) }
+    consumedPresses.clear()
+  }
+
+  fun dispatch(event: KeyEvent, composing: Boolean): Boolean {
+    if (event.flags and KeyEvent.FLAG_SOFT_KEYBOARD != 0) return false
+    if (event.action != KeyEvent.ACTION_DOWN && event.action != KeyEvent.ACTION_UP) return false
+    val code = code(event.keyCode)
+    if (code.isEmpty()) return false
+    val textModifiers = event.metaState and KeyEvent.META_CTRL_MASK.inv() and KeyEvent.META_META_MASK.inv()
+    val character = event.getUnicodeChar(textModifiers)
+    val named = !code.startsWith("Key") && !code.startsWith("Digit")
+    val key = when {
+      code.startsWith("Control") -> "Control"
+      code.startsWith("Meta") -> "Meta"
+      code.startsWith("Shift") -> "Shift"
+      code.startsWith("Alt") -> "Alt"
+      named && (character == 0 || code == "Enter" || code == "Tab" || code == "Backspace") -> code
+      character != 0 -> hardwareCharacterKey(character)
+      else -> code
+    }
+    module?.emit(mapOf(
+      "key" to key, "code" to code,
+      "altKey" to event.isAltPressed, "ctrlKey" to event.isCtrlPressed,
+      "metaKey" to event.isMetaPressed, "shiftKey" to event.isShiftPressed,
+      "repeat" to (event.repeatCount > 0), "isComposing" to composing,
+      "phase" to if (event.action == KeyEvent.ACTION_UP) "up" else "down"
+    ))
+    if (event.action == KeyEvent.ACTION_UP) return consumedPresses.remove(event.keyCode)
+    val overlayOwnsKey = key != "Dead" && key in overlayKeys && !event.isCtrlPressed && !event.isMetaPressed && !event.isAltPressed && !composing
+    if (overlayOwnsKey) consumedPresses.add(event.keyCode)
+    return overlayOwnsKey
+  }
+
+  private fun code(keyCode: Int): String = when (keyCode) {
+    in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z -> "Key" + ('A'.code + keyCode - KeyEvent.KEYCODE_A).toChar()
+    in KeyEvent.KEYCODE_0..KeyEvent.KEYCODE_9 -> "Digit" + (keyCode - KeyEvent.KEYCODE_0)
+    in KeyEvent.KEYCODE_F1..KeyEvent.KEYCODE_F12 -> "F" + (keyCode - KeyEvent.KEYCODE_F1 + 1)
+    KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> "Enter"
+    KeyEvent.KEYCODE_ESCAPE -> "Escape"
+    KeyEvent.KEYCODE_DEL -> "Backspace"
+    KeyEvent.KEYCODE_FORWARD_DEL -> "Delete"
+    KeyEvent.KEYCODE_TAB -> "Tab"
+    KeyEvent.KEYCODE_SPACE -> "Space"
+    KeyEvent.KEYCODE_DPAD_UP -> "ArrowUp"
+    KeyEvent.KEYCODE_DPAD_DOWN -> "ArrowDown"
+    KeyEvent.KEYCODE_DPAD_LEFT -> "ArrowLeft"
+    KeyEvent.KEYCODE_DPAD_RIGHT -> "ArrowRight"
+    KeyEvent.KEYCODE_CTRL_LEFT -> "ControlLeft"
+    KeyEvent.KEYCODE_CTRL_RIGHT -> "ControlRight"
+    KeyEvent.KEYCODE_META_LEFT -> "MetaLeft"
+    KeyEvent.KEYCODE_META_RIGHT -> "MetaRight"
+    KeyEvent.KEYCODE_SHIFT_LEFT -> "ShiftLeft"
+    KeyEvent.KEYCODE_SHIFT_RIGHT -> "ShiftRight"
+    KeyEvent.KEYCODE_ALT_LEFT -> "AltLeft"
+    KeyEvent.KEYCODE_ALT_RIGHT -> "AltRight"
+    KeyEvent.KEYCODE_COMMA -> "Comma"
+    KeyEvent.KEYCODE_PERIOD -> "Period"
+    KeyEvent.KEYCODE_MINUS -> "Minus"
+    KeyEvent.KEYCODE_EQUALS -> "Equal"
+    KeyEvent.KEYCODE_LEFT_BRACKET -> "BracketLeft"
+    KeyEvent.KEYCODE_RIGHT_BRACKET -> "BracketRight"
+    KeyEvent.KEYCODE_BACKSLASH -> "Backslash"
+    KeyEvent.KEYCODE_SEMICOLON -> "Semicolon"
+    KeyEvent.KEYCODE_APOSTROPHE -> "Quote"
+    KeyEvent.KEYCODE_GRAVE -> "Backquote"
+    KeyEvent.KEYCODE_SLASH -> "Slash"
+    else -> ""
+  }
+}
+
+private class KeyboardWindowCallback(private val window: Window, val previous: Window.Callback) : Window.Callback by previous {
+  override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+    val editable = (window.currentFocus as? EditText)?.text
+    val composing = editable != null && BaseInputConnection.getComposingSpanStart(editable) >= 0
+    return HardwareKeyboard.dispatcher.dispatch(event, { HardwareKeyboard.dispatch(event, composing) }, { previous.dispatchKeyEvent(event) })
+  }
+}
+
+class PaseoHardwareKeyboardModule : Module(), ExtraWindowEventListener, InputManager.InputDeviceListener, ComponentCallbacks {
+  private var inputManager: InputManager? = null
+  private var registeredReactContext: ReactContext? = null
+  private fun keyboardPresent(): Boolean {
+    val config = registeredReactContext?.resources?.configuration
+    return (config?.keyboard == Configuration.KEYBOARD_QWERTY && config.hardKeyboardHidden != Configuration.HARDKEYBOARDHIDDEN_YES) ||
+      InputDevice.getDeviceIds().any { id -> InputDevice.getDevice(id)?.let { !it.isVirtual && it.keyboardType == InputDevice.KEYBOARD_TYPE_ALPHABETIC } == true }
+  }
+  private fun presenceChanged() { sendEvent("onHardwareKeyboardPresenceChanged", emptyMap<String, Any>()) }
+  override fun onInputDeviceAdded(id: Int) { presenceChanged() }
+  override fun onInputDeviceRemoved(id: Int) { presenceChanged() }
+  override fun onInputDeviceChanged(id: Int) { presenceChanged() }
+  override fun onConfigurationChanged(config: Configuration) { presenceChanged() }
+  override fun onLowMemory() {}
+  override fun onExtraWindowCreate(window: Window) { HardwareKeyboard.observe(window) }
+  override fun onExtraWindowDestroy(window: Window) { HardwareKeyboard.release(window) }
+  override fun definition() = ModuleDefinition {
+    Name("PaseoHardwareKeyboard")
+    Events("onHardwareKeyboardShortcut", "onHardwareKeyboardPresenceChanged")
+    OnCreate {
+      HardwareKeyboard.module = this@PaseoHardwareKeyboardModule
+      val context = appContext.reactContext
+      require(context is ReactContext) { "Hardware keyboard observation requires a React context" }
+      registeredReactContext = context
+      context.registerComponentCallbacks(this@PaseoHardwareKeyboardModule)
+      inputManager = context.getSystemService(InputManager::class.java)
+      inputManager?.registerInputDeviceListener(this@PaseoHardwareKeyboardModule, Handler(Looper.getMainLooper()))
+      context.addExtraWindowEventListener(this@PaseoHardwareKeyboardModule)
+      UiThreadUtil.runOnUiThread { appContext.currentActivity?.window?.let { HardwareKeyboard.observe(it) } }
+    }
+    OnDestroy {
+      inputManager?.unregisterInputDeviceListener(this@PaseoHardwareKeyboardModule)
+      inputManager = null
+      registeredReactContext?.unregisterComponentCallbacks(this@PaseoHardwareKeyboardModule)
+      registeredReactContext?.removeExtraWindowEventListener(this@PaseoHardwareKeyboardModule)
+      registeredReactContext = null
+      if (HardwareKeyboard.module === this@PaseoHardwareKeyboardModule) {
+        HardwareKeyboard.module = null
+        HardwareKeyboard.overlayKeys = emptySet()
+        UiThreadUtil.runOnUiThread { if (HardwareKeyboard.module == null) HardwareKeyboard.releaseAll() }
+      }
+    }
+    Function("getHardwareKeyboardPresent") { keyboardPresent() }
+    Function("setOverlayKeys") { keys: List<String> ->
+      HardwareKeyboard.overlayKeys = keys.filter { it in setOf("Escape", "Enter", "ArrowUp", "ArrowDown") }.toSet()
+    }
+  }
+  internal fun emit(event: Map<String, Any>) { sendEvent("onHardwareKeyboardShortcut", event) }
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardPackage.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardPackage.kt
new file mode 100644
index 0000000000..8084863010
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/PaseoHardwareKeyboardPackage.kt
@@ -0,0 +1,17 @@
+package sh.paseo.keyboard
+
+import android.app.Activity
+import android.content.Context
+import android.os.Bundle
+import expo.modules.core.interfaces.Package
+import expo.modules.core.interfaces.ReactActivityLifecycleListener
+
+class PaseoHardwareKeyboardPackage : Package {
+  override fun createReactActivityLifecycleListeners(activityContext: Context): List<ReactActivityLifecycleListener> = listOf(
+    object : ReactActivityLifecycleListener {
+      override fun onCreate(activity: Activity, savedInstanceState: Bundle?) { HardwareKeyboard.observe(activity.window) }
+      override fun onResume(activity: Activity) { HardwareKeyboard.observe(activity.window) }
+      override fun onDestroy(activity: Activity) { HardwareKeyboard.release(activity.window) }
+    }
+  )
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/WindowKeyDispatcher.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/WindowKeyDispatcher.kt
new file mode 100644
index 0000000000..a94928b5e2
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/main/java/sh/paseo/keyboard/WindowKeyDispatcher.kt
@@ -0,0 +1,11 @@
+package sh.paseo.keyboard
+
+// A modal can forward the same physical event into the activity window. Keep
+// observation outside that nested delivery, without retaining recycled KeyEvents.
+internal class WindowKeyDispatcher<Event : Any> {
+  private val delivering = java.util.Collections.newSetFromMap(java.util.IdentityHashMap<Event, Boolean>())
+  fun dispatch(event: Event, observe: () -> Boolean, deliver: () -> Boolean): Boolean {
+    if (!delivering.add(event)) return deliver()
+    return try { observe() || deliver() } finally { delivering.remove(event) }
+  }
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/HardwareCharacterKeyTest.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/HardwareCharacterKeyTest.kt
new file mode 100644
index 0000000000..d1a2b05ee7
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/HardwareCharacterKeyTest.kt
@@ -0,0 +1,11 @@
+package sh.paseo.keyboard
+import org.junit.Assert.assertEquals
+import org.junit.Test
+class HardwareCharacterKeyTest {
+  @Test fun deadAccentUsesDomKeyWithoutThrowing() {
+    assertEquals("Dead", hardwareCharacterKey(Int.MIN_VALUE or 0xB4))
+  }
+  @Test fun ordinaryUnicodeRemainsText() {
+    assertEquals("é", hardwareCharacterKey(0xE9))
+  }
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/WindowKeyDispatcherTest.kt b/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/WindowKeyDispatcherTest.kt
new file mode 100644
index 0000000000..e6fd88607f
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/android/src/test/java/sh/paseo/keyboard/WindowKeyDispatcherTest.kt
@@ -0,0 +1,27 @@
+package sh.paseo.keyboard
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class WindowKeyDispatcherTest {
+  @Test fun observesOnePressAcrossNestedWindows() {
+    val dispatcher = WindowKeyDispatcher<Any>()
+    val event = Any()
+    var observations = 0
+    var deliveries = 0
+    dispatcher.dispatch(event, { observations++; false }, {
+      dispatcher.dispatch(event, { observations++; false }, { deliveries++; false })
+    })
+    assertEquals(1, observations)
+    assertEquals(1, deliveries)
+    dispatcher.dispatch(event, { observations++; false }, { false })
+    assertEquals(2, observations)
+  }
+  @Test fun consumedOverlayKeyDoesNotReachTheView() {
+    val dispatcher = WindowKeyDispatcher<Any>()
+    var deliveries = 0
+    assertTrue(dispatcher.dispatch(Any(), { true }, { deliveries++; false }))
+    assertEquals(0, deliveries)
+  }
+}
diff --git a/packages/app/modules/paseo-hardware-keyboard/app.plugin.js b/packages/app/modules/paseo-hardware-keyboard/app.plugin.js
new file mode 100644
index 0000000000..0c32c0506d
--- /dev/null
+++ b/packages/app/modules/paseo-hardware-keyboard/app.plugin.js
@@ -0,0 +1,29 @@
+const { withAppDelegate } = require("expo/config-plugins");
+const SCENE_START = "super.scene(scene, willConnectTo: session, options: connectionOptions)";
+
+function configureHardwareKeyboardAppDelegate(source) {
+  source = source.replace(
+    /^import PaseoHardwareKeyboard$/m,
+    "internal import PaseoHardwareKeyboard",
+  );
+  if (source.includes("PaseoHardwareKeyboardWindow.observing(window)")) return source;
+  if (!source.includes(SCENE_START)) {
+    throw new Error("Hardware keyboard observation requires the app's Expo scene delegate");
+  }
+  const installation = `${SCENE_START}
+    if let window {
+      let observedWindow = PaseoHardwareKeyboardWindow.observing(window)
+      self.window = observedWindow
+      (UIApplication.shared.delegate as? ExpoReactNativeFactoryProvider)?.window = observedWindow
+    }`;
+  return "internal import PaseoHardwareKeyboard\n" + source.replace(SCENE_START, installation);
+}
+module.exports = function withHardwareKeyboardWindow(config) {
+  return withAppDelegate(config, (modConfig) => {
+    modConfig.modResults.contents = configureHardwareKeyboardAppDelegate(
+      modConfig.modResults.contents,
+    );
+    return modConfig;
+  });
+};
+module.exports.configureHardwareKeyboardAppDelegate = configureHardwareKeyboardAppDelegate;
diff --git a/packages/app/modules/paseo-hardware-keyboard/expo-module.config.json b/packages/app/modules/paseo-hardware-keyboard/expo-module.config.json
index 57759b1d87..12d1b54eb8 100644
--- a/packages/app/modules/paseo-hardware-keyboard/expo-module.config.json
+++ b/packages/app/modules/paseo-hardware-keyboard/expo-module.config.json
@@ -1,7 +1,9 @@
 {
-  "platforms": ["ios"],
+  "platforms": ["ios", "android"],
   "ios": {
-    "modules": ["PaseoHardwareKeyboardModule"],
-    "reactDelegateHandlers": ["PaseoHardwareKeyboardReactDelegateHandler"]
+    "modules": ["PaseoHardwareKeyboardModule"]
+  },
+  "android": {
+    "modules": ["sh.paseo.keyboard.PaseoHardwareKeyboardModule"]
   }
 }
diff --git a/packages/app/modules/paseo-hardware-keyboard/ios/PaseoHardwareKeyboardModule.swift b/packages/app/modules/paseo-hardware-keyboard/ios/PaseoHardwareKeyboardModule.swift
index cd325748e3..446e1d98c4 100644
--- a/packages/app/modules/paseo-hardware-keyboard/ios/PaseoHardwareKeyboardModule.swift
+++ b/packages/app/modules/paseo-hardware-keyboard/ios/PaseoHardwareKeyboardModule.swift
@@ -1,53 +1,159 @@
 import ExpoModulesCore
 import UIKit
+import GameController
 
 private let hardwareSubmitEventName = "onHardwareKeyboardSubmit"
+private let hardwareShortcutEventName = "onHardwareKeyboardShortcut"
 
 private weak var activeModule: PaseoHardwareKeyboardModule?
 private var isHardwareSubmitEnabled = false
+private var overlayKeys: Set<String> = []
 
-@objc
-public class PaseoHardwareKeyboardReactDelegateHandler: ExpoReactDelegateHandler {
-  public override func createRootViewController() -> UIViewController? {
-    return PaseoHardwareKeyboardRootViewController()
+/// UIKit spells non-character keys as sentinel input strings rather than as the
+/// character they would type. JS sends the DOM `code` and the mapping lives
+/// here, so the constants stay in the one place that owns UIKit vocabulary.
+private let namedKeyInputs: [String: String] = [
+  "Escape": UIKeyCommand.inputEscape,
+  "ArrowUp": UIKeyCommand.inputUpArrow,
+  "ArrowDown": UIKeyCommand.inputDownArrow,
+  "Enter": "\r",
+]
+
+/// Whether the first responder is mid-IME-composition.
+///
+/// A committing key has to stay out of the way while a CJK candidate is being
+/// chosen: Enter confirms the candidate, and consuming it as a key command
+/// would submit the half-composed text instead.
+private func isComposingText() -> Bool {
+  guard let responder = UIResponder.paseoCurrentFirstResponder as? UITextInput else {
+    return false
   }
+  return responder.markedTextRange != nil
 }
 
 public class PaseoHardwareKeyboardModule: Module {
+  private var keyboardObservers: [NSObjectProtocol] = []
   public func definition() -> ModuleDefinition {
     Name("PaseoHardwareKeyboard")
 
-    Events(hardwareSubmitEventName)
+    Events(hardwareSubmitEventName, hardwareShortcutEventName, "onHardwareKeyboardPresenceChanged")
 
     OnCreate {
       activeModule = self
+      for name in [Notification.Name.GCKeyboardDidConnect, Notification.Name.GCKeyboardDidDisconnect] {
+        self.keyboardObservers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
+          self?.sendEvent("onHardwareKeyboardPresenceChanged", [:])
+        })
+      }
     }
 
+    Function("getHardwareKeyboardPresent") { GCKeyboard.coalesced != nil }
+
     Function("setHardwareKeyboardSubmitEnabled") { (enabled: Bool) in
       DispatchQueue.main.async {
         isHardwareSubmitEnabled = enabled
       }
     }
 
+    Function("setOverlayKeys") { (keys: [String]) in
+      DispatchQueue.main.async {
+        overlayKeys = Set(keys).intersection(["Enter", "ArrowUp", "ArrowDown"])
+        UIMenuSystem.main.setNeedsRebuild()
+      }
+    }
+
     OnDestroy {
+      self.keyboardObservers.forEach(NotificationCenter.default.removeObserver)
+      self.keyboardObservers = []
       if activeModule === self {
         activeModule = nil
+        isHardwareSubmitEnabled = false
+        overlayKeys = []
       }
-      isHardwareSubmitEnabled = false
     }
   }
 
   fileprivate func emitHardwareKeyboardSubmit() {
     sendEvent(hardwareSubmitEventName, [:])
   }
+
+  fileprivate func emitHardwareKeyboardPress(_ press: UIPress, isRepeat: Bool) {
+    guard let key = press.key else { return }
+    let code = hardwareKeyCode(key)
+    let characters = key.characters
+    let named = namedKeyInputs.first { $0.value == characters }?.key
+    let keyName: String
+    if code.hasPrefix("Meta") { keyName = "Meta" }
+    else if code.hasPrefix("Control") { keyName = "Control" }
+    else if code.hasPrefix("Shift") { keyName = "Shift" }
+    else if code.hasPrefix("Alt") { keyName = "Alt" }
+    else { keyName = named ?? (characters.isEmpty ? code : characters) }
+    guard !code.isEmpty else { return }
+    sendEvent(hardwareShortcutEventName, [
+      "key": keyName,
+      "code": code,
+      "altKey": key.modifierFlags.contains(.alternate),
+      "ctrlKey": key.modifierFlags.contains(.control),
+      "metaKey": key.modifierFlags.contains(.command),
+      "shiftKey": key.modifierFlags.contains(.shift),
+      "repeat": isRepeat,
+      "isComposing": isComposingText(),
+      "phase": press.phase == .ended || press.phase == .cancelled ? "up" : "down",
+    ])
+  }
 }
 
-private final class PaseoHardwareKeyboardRootViewController: UIViewController {
-  override var keyCommands: [UIKeyCommand]? {
-    guard isHardwareSubmitEnabled && UIDevice.current.userInterfaceIdiom == .pad else {
-      return super.keyCommands
-    }
+public final class PaseoHardwareKeyboardWindow: UIWindow {
+  private var pressedCodes: Set<Int> = []
+  public static func observing(_ original: UIWindow) -> UIWindow {
+    if original is PaseoHardwareKeyboardWindow { return original }
+    guard let scene = original.windowScene else { return original }
+    let observed = PaseoHardwareKeyboardWindow(windowScene: scene)
+    observed.windowLevel = original.windowLevel
+    observed.backgroundColor = original.backgroundColor
+    let controller = original.rootViewController
+    original.rootViewController = nil
+    original.isHidden = true
+    observed.rootViewController = controller
+    observed.makeKeyAndVisible()
+    return observed
+  }
 
+  public override func sendEvent(_ event: UIEvent) {
+    if let event = event as? UIPressesEvent {
+      for press in event.allPresses where press.phase == .began || press.phase == .ended || press.phase == .cancelled {
+        guard let key = press.key else { continue }
+        let raw = Int(key.keyCode.rawValue)
+        let isRepeat = press.phase == .began && pressedCodes.contains(raw)
+        if press.phase == .began { pressedCodes.insert(raw) }
+        else { pressedCodes.remove(raw) }
+        activeModule?.emitHardwareKeyboardPress(press, isRepeat: isRepeat)
+      }
+    }
+    super.sendEvent(event)
+  }
+  public override var keyCommands: [UIKeyCommand]? {
+    var commands = super.keyCommands ?? []
+    if isHardwareSubmitEnabled && !isPlainReturnClaimed && !isComposingText()
+      && UIDevice.current.userInterfaceIdiom == .pad
+    {
+      commands.append(makeSubmitCommand())
+    }
+    if !isComposingText() { commands.append(contentsOf: overlayKeys.compactMap(makeShortcutCommand)) }
+    return commands
+  }
+
+  /// Whether something registered has already asked for an unmodified Return.
+  ///
+  /// The submit command is registered for as long as the composer holds focus,
+  /// which includes while a picker is open over it. Registering both would put
+  /// two commands on one press, and the composer would win a press the picker
+  /// asked for — Enter would create the workspace instead of choosing a project.
+  private var isPlainReturnClaimed: Bool {
+    overlayKeys.contains("Enter")
+  }
+
+  private func makeSubmitCommand() -> UIKeyCommand {
     let command = UIKeyCommand(
       input: "\r",
       modifierFlags: [],
@@ -56,7 +162,14 @@ private final class PaseoHardwareKeyboardRootViewController: UIViewController {
     if #available(iOS 15.0, *) {
       command.wantsPriorityOverSystemBehavior = true
     }
-    return (super.keyCommands ?? []) + [command]
+    return command
+  }
+
+  private func makeShortcutCommand(_ key: String) -> UIKeyCommand? {
+    guard let input = namedKeyInputs[key] else { return nil }
+    let command = UIKeyCommand(input: input, modifierFlags: [], action: #selector(handleHardwareKeyboardShortcut(_:)))
+    if #available(iOS 15.0, *) { command.wantsPriorityOverSystemBehavior = true }
+    return command
   }
 
   @objc
@@ -67,6 +180,9 @@ private final class PaseoHardwareKeyboardRootViewController: UIViewController {
     activeModule?.emitHardwareKeyboardSubmit()
   }
 
+  @objc
+  private func handleHardwareKeyboardShortcut(_ sender: UIKeyCommand) {}
+
   private func canSubmitCurrentTextInput() -> Bool {
     guard let responder = UIResponder.paseoCurrentFirstResponder else {
       return false
@@ -97,3 +213,25 @@ private extension UIResponder {
     UIResponder.currentFirstResponder = self
   }
 }
+
+
+private func hardwareKeyCode(_ key: UIKey) -> String {
+  let raw = key.keyCode.rawValue
+  if raw >= 4 && raw <= 29 {
+    let letter = UnicodeScalar(Int(raw) + 61)!
+    return "Key" + String(letter)
+  }
+  if raw >= 30 && raw <= 38 { return "Digit" + String(raw - 29) }
+  if raw == 39 { return "Digit0" }
+  let codes: [Int: String] = [
+    40: "Enter", 41: "Escape", 42: "Backspace", 43: "Tab", 44: "Space",
+    45: "Minus", 46: "Equal", 47: "BracketLeft", 48: "BracketRight",
+    49: "Backslash", 51: "Semicolon", 52: "Quote", 53: "Backquote",
+    54: "Comma", 55: "Period", 56: "Slash", 76: "Delete", 79: "ArrowRight",
+    80: "ArrowLeft", 81: "ArrowDown", 82: "ArrowUp", 224: "ControlLeft",
+    225: "ShiftLeft", 226: "AltLeft", 227: "MetaLeft", 228: "ControlRight",
+    229: "ShiftRight", 230: "AltRight", 231: "MetaRight",
+  ]
+  if raw >= 58 && raw <= 69 { return "F" + String(raw - 57) }
+  return codes[Int(raw)] ?? ""
+}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml b/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml
new file mode 100644
index 0000000000..2b3dae4d2a
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <!-- Hosts a scroll view in a real window, so layout clamps and draws run as they do on device. -->
+    <activity android:name="android.app.Activity" android:exported="false" />
+  </application>
+</manifest>
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java
new file mode 100644
index 0000000000..fb9f65ced1
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java
@@ -0,0 +1,77 @@
+package sh.paseo.scroll;
+
+import android.content.Context;
+import com.facebook.react.bridge.BridgeReactContext;
+import com.facebook.react.bridge.UIManager;
+import com.facebook.react.bridge.UIManagerListener;
+import com.facebook.react.uimanager.events.EventDispatcher;
+import com.facebook.react.uimanager.events.EventDispatcherProvider;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A React context with a running Fabric UIManager, so scroll views find the mount listener
+ * registry and event dispatcher the way they do in the app. The UIManager only records mount
+ * listeners and the dispatcher drops events; every other call returns a default. Java, because
+ * {@link EventDispatcherProvider} is internal to React Native's Kotlin module.
+ */
+final class MountingReactContext extends BridgeReactContext implements EventDispatcherProvider {
+  final List<UIManagerListener> mountListeners = new ArrayList<>();
+  final UIManager uiManager;
+  private final EventDispatcher eventDispatcher = inert(EventDispatcher.class, null);
+
+  MountingReactContext(Context base) {
+    super(base);
+    uiManager = inert(UIManager.class, this);
+  }
+
+  /** Runs one Fabric mount: listeners see willMountItems, then the change, then didMountItems. */
+  void mount(Runnable change) {
+    for (UIManagerListener listener : new ArrayList<>(mountListeners)) listener.willMountItems(uiManager);
+    change.run();
+    for (UIManagerListener listener : new ArrayList<>(mountListeners)) listener.didMountItems(uiManager);
+  }
+
+  @Override
+  public boolean hasActiveReactInstance() {
+    return true;
+  }
+
+  @Override
+  public UIManager getFabricUIManager() {
+    return uiManager;
+  }
+
+  @Override
+  public EventDispatcher getEventDispatcher() {
+    return eventDispatcher;
+  }
+
+  private static <T> T inert(Class<T> type, MountingReactContext owner) {
+    return type.cast(
+        Proxy.newProxyInstance(
+            type.getClassLoader(),
+            new Class<?>[] {type},
+            (proxy, method, args) -> {
+              switch (method.getName()) {
+                case "addUIManagerEventListener":
+                  owner.mountListeners.add((UIManagerListener) args[0]);
+                  return null;
+                case "removeUIManagerEventListener":
+                  owner.mountListeners.remove((UIManagerListener) args[0]);
+                  return null;
+                case "getEventDispatcher":
+                  return owner.eventDispatcher;
+                default:
+                  Class<?> result = method.getReturnType();
+                  if (result == boolean.class) return false;
+                  if (result == int.class) return 0;
+                  if (result == long.class) return 0L;
+                  if (result == float.class) return 0f;
+                  if (result == double.class) return 0.0;
+                  return null;
+              }
+            }));
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt
deleted file mode 100644
index c7007776ba..0000000000
--- a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt
+++ /dev/null
@@ -1,101 +0,0 @@
-package sh.paseo.scroll
-
-import android.graphics.Rect
-import android.text.Selection
-import android.text.Spannable
-import android.view.View
-import android.widget.FrameLayout
-import android.widget.TextView
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import androidx.test.platform.app.InstrumentationRegistry
-import com.facebook.react.bridge.BridgeReactContext
-import com.facebook.react.bridge.JavaOnlyArray
-import com.facebook.react.bridge.JavaOnlyMap
-import com.facebook.react.soloader.OpenSourceMergedSoMapping
-import com.facebook.react.uimanager.DisplayMetricsHolder
-import com.facebook.react.uimanager.ReactStylesDiffMap
-import com.facebook.react.uimanager.ThemedReactContext
-import com.facebook.react.views.scroll.ReactScrollView
-import com.facebook.react.views.scroll.ReactScrollViewManager
-import com.facebook.soloader.SoLoader
-import org.junit.Assert.*
-import org.junit.Test
-import org.junit.runner.RunWith
-
-@RunWith(AndroidJUnit4::class)
-class ScrollSelectionTest {
-  @Test fun focusingSelectableTextKeepsInvertedViewportStill() = withScroll(inverted = true) { scroll, text ->
-    val before = scroll.scrollY
-    assertTrue(text.requestFocus())
-    assertSame(text, scroll.findFocus())
-    assertEquals("Text focus must not move the inverted viewport", before, scroll.scrollY)
-    assertTrue(text.isTextSelectable)
-  }
-
-  @Test fun selectingTextKeepsInvertedViewportStill() = withScroll(inverted = true) { scroll, text ->
-    val before = scroll.scrollY
-    Selection.setSelection(text.text as Spannable, 0, 8)
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertEquals("Selection visibility requests must not move the inverted viewport", before, scroll.scrollY)
-    assertEquals("Selectab", text.text.subSequence(text.selectionStart, text.selectionEnd).toString())
-  }
-
-  @Test fun explicitScrollCommandsStillMoveInvertedViewport() = withScroll(inverted = true) { scroll, _ ->
-    scroll.scrollTo(0, 600)
-    assertEquals(600, scroll.scrollY)
-  }
-
-  @Test fun ordinaryScrollViewsStillRevealSelectedText() = withScroll(inverted = false) { scroll, text ->
-    val before = scroll.scrollY
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertNotEquals(before, scroll.scrollY)
-  }
-
-  @Test fun verticalScaleStillKeepsFocusAndSelectionInPlace() = withScroll(inverted = true, transform = "scaleY") { scroll, text ->
-    val before = scroll.scrollY
-    assertTrue(text.requestFocus())
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertEquals(before, scroll.scrollY)
-  }
-
-  @Test fun horizontalScaleStillRevealsSelectedText() = withScroll(inverted = true, transform = "scaleX") { scroll, text ->
-    val before = scroll.scrollY
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertNotEquals(before, scroll.scrollY)
-  }
-
-  private fun withScroll(inverted: Boolean, transform: String = "scale", check: (ReactScrollView, TextView) -> Unit) {
-    val instrumentation = InstrumentationRegistry.getInstrumentation()
-    instrumentation.runOnMainSync {
-      val appContext = instrumentation.targetContext
-      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(appContext)
-      SoLoader.init(appContext, OpenSourceMergedSoMapping)
-      val reactContext = BridgeReactContext(appContext)
-      val context = ThemedReactContext(reactContext, appContext)
-      val manager = PaseoScrollPackage().createViewManager(reactContext, ReactScrollViewManager.REACT_CLASS) as ReactScrollViewManager
-      val scroll = manager.createViewInstance(context)
-      val content = FrameLayout(context)
-      val text = TextView(context).apply {
-        setText("Selectable timeline text", TextView.BufferType.SPANNABLE)
-        setTextIsSelectable(true)
-      }
-      content.addView(text, FrameLayout.LayoutParams(300, 100).apply { topMargin = 1400 })
-      scroll.addView(content)
-      content.measure(exact(300), exact(2000))
-      content.layout(0, 0, 300, 2000)
-      scroll.measure(exact(300), exact(300))
-      scroll.layout(0, 0, 300, 300)
-      // Apply RN's actual Android inversion through the manager's transform decomposition.
-      val transforms = JavaOnlyArray.of(JavaOnlyMap.of(transform, if (inverted) -1.0 else 1.0))
-      manager.updateProperties(scroll, ReactStylesDiffMap(JavaOnlyMap.of("transform", transforms)))
-      if (inverted && transform == "scale") {
-        assertEquals(1f, scroll.scaleY, 0f)
-        assertEquals(180f, kotlin.math.abs(scroll.rotation), 0f)
-      }
-      scroll.scrollTo(0, 400)
-      check(scroll, text)
-    }
-  }
-
-  private fun exact(size: Int) = View.MeasureSpec.makeMeasureSpec(size, View.MeasureSpec.EXACTLY)
-}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt
new file mode 100644
index 0000000000..c99241db47
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt
@@ -0,0 +1,271 @@
+package sh.paseo.scroll
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.graphics.Canvas
+import android.os.SystemClock
+import android.view.MotionEvent
+import android.view.View
+import android.widget.FrameLayout
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import com.facebook.react.bridge.JavaOnlyMap
+import com.facebook.react.soloader.OpenSourceMergedSoMapping
+import com.facebook.react.uimanager.DisplayMetricsHolder
+import com.facebook.react.uimanager.ReactStylesDiffMap
+import com.facebook.react.uimanager.RootView
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.views.scroll.ReactScrollView
+import com.facebook.react.views.scroll.ReactScrollViewManager
+import com.facebook.react.views.view.ReactViewGroup
+import com.facebook.soloader.SoLoader
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * A Fabric mount that shrinks the content of a scroll view with `maintainVisibleContentPosition`
+ * set. The mount runs through React Native's real position keeper, driven by the same
+ * willMountItems/didMountItems calls Fabric makes, inside a real window so layout clamps and draws
+ * happen as they do on a device.
+ */
+@RunWith(AndroidJUnit4::class)
+class VisibleContentPositionClampTest {
+  private val instrumentation = InstrumentationRegistry.getInstrumentation()
+  private var activity: Activity? = null
+
+  @After fun finish() {
+    activity?.finish()
+  }
+
+  @Test fun shrinkAtTheEndLandsAtTheNewEnd() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.shrinkInOneMount()
+
+    assertEquals("Offset after the mount", NEW_END, timeline.scrollY())
+    assertEquals("Offset in the first frame drawn after the mount", NEW_END, timeline.firstDrawnScrollY())
+  }
+
+  @Test fun shrinkBelowAnUnmovedAnchorIsClampedBeforeTheFrameDraws() {
+    val timeline = openTimeline(anchor = Anchor.TOP_ROW)
+
+    timeline.shrinkInOneMount()
+
+    assertEquals("Offset in the first frame drawn after the mount", NEW_END, timeline.firstDrawnScrollY())
+    assertEquals("Offset after the mount", NEW_END, timeline.scrollY())
+  }
+
+  @Test fun shrinkDuringATouchDragLeavesNoOffsetPastTheEnd() {
+    val timeline = openTimeline(anchor = Anchor.TOP_ROW)
+
+    timeline.beginDrag()
+    assertTrue("The drag owns the viewport", timeline.scrollY() < CONTENT_HEIGHT - VIEWPORT)
+    timeline.shrinkInOneMount()
+    val drawn = timeline.firstDrawnScrollY()
+    timeline.endDrag()
+    val settled = timeline.settledScrollY()
+
+    assertTrue("Offset $drawn drawn past the end $NEW_END", drawn <= NEW_END)
+    assertTrue("Offset $settled settled past the end $NEW_END", settled <= NEW_END)
+    timeline.awaitFrames(10)
+    assertEquals("Offset kept moving after the drag ended", settled, timeline.scrollY())
+  }
+
+  @Test fun growthAtTheEndFollowsWithoutATouch() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.growInOneMount()
+
+    assertEquals("Offset after the mount", CONTENT_HEIGHT + GROWTH - VIEWPORT, timeline.scrollY())
+  }
+
+  // The drag begins before JS stops following and removes the pin, so a line mounting in the drag's
+  // first frames must not scroll the rows the finger is on.
+  @Test fun growthAtTheEndDuringATouchDragKeepsTheRowsUnderTheFinger() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.beginDrag()
+    val dragged = timeline.scrollY()
+    assertTrue("The drag owns the viewport", dragged < CONTENT_HEIGHT - VIEWPORT)
+    timeline.growInOneMount()
+
+    assertEquals("Offset after the mount", dragged, timeline.scrollY())
+    assertEquals("Offset in the first frame drawn after the mount", dragged, timeline.firstDrawnScrollY())
+    timeline.endDrag()
+  }
+
+  private enum class Anchor {
+    /** A zero-height view at the bottom of the content, first child: the end pin. */
+    END,
+    /** A row at the top of the content that reaches into the viewport and does not move. */
+    TOP_ROW,
+  }
+
+  private inner class Timeline(
+    val scroll: ReactScrollView,
+    private val content: ReactViewGroup,
+    private val endPin: View,
+    private val probe: DrawProbe,
+    private val reactContext: MountingReactContext,
+  ) {
+    private var dragY = 0f
+    private var downTime = 0L
+
+    fun scrollY(): Int {
+      var y = 0
+      instrumentation.runOnMainSync { y = scroll.scrollY }
+      return y
+    }
+
+    fun shrinkInOneMount() = resizeInOneMount(CONTENT_HEIGHT - SHRINK)
+
+    fun growInOneMount() = resizeInOneMount(CONTENT_HEIGHT + GROWTH)
+
+    private fun resizeInOneMount(height: Int) {
+      instrumentation.runOnMainSync {
+        probe.drawnScrollY.clear()
+        reactContext.mount { layoutContent(height) }
+        probe.invalidate()
+      }
+    }
+
+    fun firstDrawnScrollY(): Int {
+      val deadline = SystemClock.uptimeMillis() + 2000
+      while (SystemClock.uptimeMillis() < deadline) {
+        instrumentation.waitForIdleSync()
+        var drawn: Int? = null
+        instrumentation.runOnMainSync { drawn = probe.drawnScrollY.firstOrNull() }
+        drawn?.let { return it }
+        SystemClock.sleep(16)
+      }
+      throw AssertionError("No frame was drawn after the mount")
+    }
+
+    fun beginDrag() {
+      downTime = SystemClock.uptimeMillis()
+      dragY = 300f
+      touch(MotionEvent.ACTION_DOWN)
+      // Finger moves down, so the content scrolls up from the end and the drag owns the viewport.
+      repeat(6) {
+        dragY += 12f
+        touch(MotionEvent.ACTION_MOVE)
+      }
+    }
+
+    fun endDrag() {
+      dragY += 4f
+      touch(MotionEvent.ACTION_MOVE)
+      touch(MotionEvent.ACTION_UP)
+    }
+
+    fun settledScrollY(): Int {
+      var previous = scrollY()
+      repeat(60) {
+        awaitFrames(2)
+        val current = scrollY()
+        if (current == previous) return current
+        previous = current
+      }
+      throw AssertionError("Offset never settled")
+    }
+
+    fun awaitFrames(count: Int) {
+      repeat(count) {
+        instrumentation.waitForIdleSync()
+        SystemClock.sleep(16)
+      }
+    }
+
+    fun layoutContent(height: Int) {
+      content.layout(0, 0, WIDTH, height)
+      endPin.layout(0, height, 0, height)
+    }
+
+    private fun touch(action: Int) {
+      instrumentation.runOnMainSync {
+        val event = MotionEvent.obtain(downTime, SystemClock.uptimeMillis(), action, WIDTH / 2f, dragY, 0)
+        scroll.dispatchTouchEvent(event)
+        event.recycle()
+      }
+    }
+  }
+
+  /** The React surface root a scroll view reports its native gestures to. */
+  private class SurfaceRoot(context: Context) : FrameLayout(context), RootView {
+    override fun onChildStartedNativeGesture(childView: View?, ev: MotionEvent) {}
+
+    override fun onChildEndedNativeGesture(childView: View, ev: MotionEvent) {}
+
+    override fun handleException(t: Throwable) {
+      throw t
+    }
+  }
+
+  private class DrawProbe(context: Context) : View(context) {
+    val drawnScrollY = mutableListOf<Int>()
+
+    override fun onDraw(canvas: Canvas) {
+      drawnScrollY += (parent.parent as View).scrollY
+    }
+  }
+
+  private fun openTimeline(anchor: Anchor): Timeline {
+    val started =
+      instrumentation.startActivitySync(
+        Intent(instrumentation.targetContext, Activity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      )
+    activity = started
+    lateinit var timeline: Timeline
+    instrumentation.runOnMainSync {
+      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(started)
+      SoLoader.init(started, OpenSourceMergedSoMapping)
+      val reactContext = MountingReactContext(started.applicationContext)
+      val context = ThemedReactContext(reactContext, started)
+      val manager =
+        PaseoScrollPackage().createViewManager(reactContext, ReactScrollViewManager.REACT_CLASS)
+          as ReactScrollViewManager
+      val scroll = manager.createViewInstance(context)
+      val content = ReactViewGroup(context)
+      val endPin = View(context).apply { setTag(com.facebook.react.R.id.view_tag_native_id, END_PIN_NATIVE_ID) }
+      val probe = DrawProbe(context)
+      if (anchor == Anchor.END) {
+        content.addView(endPin)
+        content.addView(probe)
+      } else {
+        content.addView(probe)
+        content.addView(endPin)
+      }
+      scroll.addView(content)
+      manager.updateProperties(
+        scroll,
+        ReactStylesDiffMap(
+          JavaOnlyMap.of("maintainVisibleContentPosition", JavaOnlyMap.of("minIndexForVisible", 0))
+        ),
+      )
+      started.setContentView(SurfaceRoot(started).apply { addView(scroll, FrameLayout.LayoutParams(WIDTH, VIEWPORT)) })
+      timeline = Timeline(scroll, content, endPin, probe, reactContext)
+      timeline.layoutContent(CONTENT_HEIGHT)
+      probe.layout(0, 0, WIDTH, PROBE_HEIGHT)
+    }
+    timeline.awaitFrames(2)
+    instrumentation.runOnMainSync { timeline.scroll.scrollTo(0, CONTENT_HEIGHT - VIEWPORT) }
+    timeline.awaitFrames(2)
+    assertEquals("Starts at the end", CONTENT_HEIGHT - VIEWPORT, timeline.scrollY())
+    return timeline
+  }
+
+  private companion object {
+    const val WIDTH = 300
+    const val VIEWPORT = 600
+    const val CONTENT_HEIGHT = 1000
+    const val SHRINK = 240
+    const val GROWTH = 120
+    const val END_PIN_NATIVE_ID = "paseo-end-pin"
+    const val NEW_END = CONTENT_HEIGHT - SHRINK - VIEWPORT
+    const val PROBE_HEIGHT = 700
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
index 71ff179cb1..617a017336 100644
--- a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
+++ b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
@@ -1,7 +1,5 @@
 package sh.paseo.scroll
 
-import android.graphics.Matrix
-import android.graphics.Rect
 import com.facebook.react.ReactPackage
 import com.facebook.react.ViewManagerOnDemandReactPackage
 import com.facebook.react.bridge.NativeModule
@@ -26,17 +24,3 @@ private class PaseoScrollViewManager : ReactScrollViewManager() {
   override fun createViewInstance(context: ThemedReactContext): ReactScrollView =
     PaseoScrollView(context)
 }
-
-private class PaseoScrollView(context: ThemedReactContext) : ReactScrollView(context) {
-  private val transformValues = FloatArray(9)
-
-  // Both RN focus handling and Android selection visibility requests use this calculation.
-  // Its coordinates ignore inversion. Keep focus/selection bookkeeping, but leave timeline
-  // movement to user gestures and explicit scroll commands.
-  override fun computeScrollDeltaToGetChildRectOnScreen(rect: Rect): Int {
-    // RN's Android scale: -1 becomes a 180-degree rotation with positive scaleY.
-    matrix.getValues(transformValues)
-    if (transformValues[Matrix.MSCALE_Y] < 0) return 0
-    return super.computeScrollDeltaToGetChildRectOnScreen(rect)
-  }
-}
diff --git a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java
new file mode 100644
index 0000000000..5e2345830c
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java
@@ -0,0 +1,142 @@
+package sh.paseo.scroll;
+
+import android.content.Context;
+import android.view.MotionEvent;
+import android.view.View;
+import android.view.ViewGroup;
+import android.view.ViewTreeObserver;
+import androidx.annotation.Nullable;
+import com.facebook.react.R;
+import com.facebook.react.views.scroll.MaintainVisibleScrollPositionHelper;
+import com.facebook.react.views.scroll.ReactScrollView;
+import com.facebook.react.views.scroll.ReactScrollViewHelper;
+
+/**
+ * React Native's vertical scroll view with two corrections. Java, because the content-position
+ * config type is internal to React Native's Kotlin module.
+ */
+final class PaseoScrollView extends ReactScrollView {
+  // The chat timeline's end pin, packages/app/src/agent-stream/native-end-pin.tsx.
+  private static final String END_PIN_NATIVE_ID = "paseo-end-pin";
+
+  private final ViewTreeObserver.OnPreDrawListener clampBeforeDraw =
+      () -> {
+        clampToContentEnd();
+        return true;
+      };
+  private @Nullable MaintainVisibleScrollPositionHelper.Config visibleContentPosition = null;
+  private boolean isClampPending = false;
+  private boolean isUserDragging = false;
+
+  PaseoScrollView(Context context) {
+    super(context);
+  }
+
+  @Override
+  public void setMaintainVisibleContentPosition(
+      @Nullable MaintainVisibleScrollPositionHelper.Config config) {
+    super.setMaintainVisibleContentPosition(config);
+    visibleContentPosition = config;
+  }
+
+  // While the timeline follows its end, its end pin anchors the content position, so every line that
+  // mounts scrolls the content by its height. A drag owns the offset from the frame it begins, and
+  // JS removes the pin only a round trip later. While the user drags, the correction for the pin is
+  // skipped, so the line grows below the rows under the finger. iOS's PaseoScrollViewComponentView
+  // does the same.
+  // MaintainVisibleScrollPositionHelper is the only caller: it moves the offset by its anchor's move.
+  @Override
+  public void scrollToPreservingMomentum(int x, int y) {
+    if (isUserDragging && isEndPinTheAnchor()) return;
+    super.scrollToPreservingMomentum(x, y);
+  }
+
+  // The drag begins where React Native emits onScrollBeginDrag.
+  @Override
+  protected void handleInterceptedTouchEvent(MotionEvent ev) {
+    super.handleInterceptedTouchEvent(ev);
+    isUserDragging = true;
+  }
+
+  @Override
+  public boolean onTouchEvent(MotionEvent ev) {
+    boolean handled = super.onTouchEvent(ev);
+    int action = ev.getActionMasked();
+    if (action == MotionEvent.ACTION_UP || action == MotionEvent.ACTION_CANCEL) {
+      isUserDragging = false;
+    }
+    return handled;
+  }
+
+  // The helper anchors on the first content child from minIndexForVisible that reaches into the
+  // viewport. The pin is the first child and sits at the bottom of the content, so it always does.
+  private boolean isEndPinTheAnchor() {
+    if (visibleContentPosition == null || visibleContentPosition.getMinIndexForVisible() != 0) {
+      return false;
+    }
+    View content = getChildAt(0);
+    if (!(content instanceof ViewGroup) || ((ViewGroup) content).getChildCount() == 0) return false;
+    Object nativeId = ((ViewGroup) content).getChildAt(0).getTag(R.id.view_tag_native_id);
+    return END_PIN_NATIVE_ID.equals(nativeId);
+  }
+
+  // With maintainVisibleContentPosition set, a mount that shrinks the content past the offset would
+  // apply the shrink twice:
+  // 1. MaintainVisibleScrollPositionHelper.willMountItems records the anchor's frame.
+  // 2. The mount lays out the shorter content, and ReactScrollView.onLayoutChange clamps the offset
+  //    to the new end.
+  // 3. MaintainVisibleScrollPositionHelper.didMountItems adds the anchor's move to the clamped
+  //    offset, so the shrink moves the offset a second time (to the top, for a shrink at the end).
+  // The clamp waits for the pre-draw pass instead, which runs after didMountItems and before the
+  // frame draws: the anchor's move applies to the offset the content had before the mount, and the
+  // clamp only catches what the anchor did not account for.
+  // https://github.com/react/react-native/issues/58578 tracks it; remove this override once
+  // https://github.com/react/react-native/pull/58695 ships in the React Native version we use.
+  @Override
+  public void onLayoutChange(
+      View v,
+      int left,
+      int top,
+      int right,
+      int bottom,
+      int oldLeft,
+      int oldTop,
+      int oldRight,
+      int oldBottom) {
+    if (visibleContentPosition == null) {
+      super.onLayoutChange(v, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom);
+      return;
+    }
+    if (!isClampPending) {
+      isClampPending = true;
+      getViewTreeObserver().addOnPreDrawListener(clampBeforeDraw);
+    }
+    ReactScrollViewHelper.emitLayoutChangeEvent(this);
+  }
+
+  @Override
+  protected void onDetachedFromWindow() {
+    cancelPendingClamp();
+    isUserDragging = false;
+    super.onDetachedFromWindow();
+  }
+
+  private void clampToContentEnd() {
+    cancelPendingClamp();
+    View content = getChildAt(0);
+    if (content == null || content.getWidth() == 0 || content.getHeight() == 0 || !isShown()) {
+      return;
+    }
+    int viewportHeight = getHeight() - getPaddingTop() - getPaddingBottom();
+    int maxScrollY = Math.max(0, content.getHeight() - viewportHeight);
+    if (getScrollY() > maxScrollY) {
+      scrollTo(getScrollX(), maxScrollY);
+    }
+  }
+
+  private void cancelPendingClamp() {
+    if (!isClampPending) return;
+    isClampPending = false;
+    getViewTreeObserver().removeOnPreDrawListener(clampBeforeDraw);
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/expo-module.config.json b/packages/app/modules/paseo-scroll/expo-module.config.json
index ba00434407..47b7ac97b7 100644
--- a/packages/app/modules/paseo-scroll/expo-module.config.json
+++ b/packages/app/modules/paseo-scroll/expo-module.config.json
@@ -1 +1 @@
-{ "platforms": ["android"], "android": { "modules": [] } }
+{ "platforms": ["android", "ios"], "android": { "modules": [] }, "ios": { "modules": [] } }
diff --git a/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec b/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec
new file mode 100644
index 0000000000..8ddbfd47b2
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec
@@ -0,0 +1,16 @@
+Pod::Spec.new do |s|
+  s.name           = 'PaseoScroll'
+  s.version        = '0.1.0'
+  s.summary        = 'Scroll view corrections for Paseo'
+  s.description    = 'Scroll view corrections for Paseo'
+  s.license        = 'Apache-2.0'
+  s.author         = 'Paseo'
+  s.homepage       = 'https://paseo.sh'
+  s.platforms      = { :ios => '15.1' }
+  s.source         = { :path => '.' }
+  s.static_framework = true
+
+  s.source_files = "**/*.{h,mm}"
+
+  install_modules_dependencies(s)
+end
diff --git a/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm b/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm
new file mode 100644
index 0000000000..4bd5cfe2f3
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm
@@ -0,0 +1,170 @@
+#import <React/RCTComponentViewFactory.h>
+#import <React/RCTCustomPullToRefreshViewProtocol.h>
+#import <React/RCTScrollViewComponentView.h>
+#import <React/RCTViewComponentView.h>
+#import <react/renderer/components/scrollview/ScrollViewProps.h>
+#import <react/renderer/components/scrollview/ScrollViewShadowNode.h>
+
+using namespace facebook::react;
+
+/**
+ * React Native's scroll view with three maintainVisibleContentPosition corrections.
+ *
+ * An anchor removed by the mount it anchors. React Native picks the anchor before the mount and
+ * moves the offset by the anchor's movement after it. When the mount removes that view, its frame
+ * after the mount no longer describes the content, and the offset jumps by an unrelated amount.
+ * Android keeps a removed view's last frame, so it keeps the offset. This class keeps the offset on
+ * iOS too.
+ * The chat timeline hits this when it stops following its end: the same mount removes the end pin
+ * and opens the disclosure the reader tapped.
+ * React Native 0.88 skips the adjustment for a removed anchor
+ * (https://github.com/react/react-native/pull/57294). Its view-registry tag check matches the check
+ * here; its superview check also skips anchors that removeClippedSubviews detached
+ * (https://github.com/react/react-native/issues/58910). Remove this part once the installed React
+ * Native includes the tag check.
+ *
+ * The chat timeline's end pin during a drag. While the timeline follows its end, a zero-height view
+ * at the bottom of the content (native ID "paseo-end-pin", packages/app/src/agent-stream/
+ * native-end-pin.tsx) is the anchor, so every line that mounts scrolls the content by its height.
+ * A drag owns the offset from the frame it begins, and JS removes the pin only a round trip later.
+ * While the user drags, a mount anchored on the pin keeps the offset, so the line grows below the
+ * rows under the finger. Android's PaseoScrollView does the same.
+ *
+ * A shrink at the end. A mount that shrinks the content sets the smaller contentSize, and UIKit
+ * clamps contentOffset to the new end. React Native then adds the anchor's movement to the clamped
+ * offset, so the shrink is applied twice and the viewport lands above the content it kept.
+ * The chat timeline hits this when a finished turn folds while the end pin follows the latest row.
+ * https://github.com/react/react-native/issues/58578
+ * Remove once https://github.com/react/react-native/pull/58695 ships; it keeps the pre-mount
+ * offset and clamps after the adjustment, as this class does.
+ */
+@interface PaseoScrollViewComponentView : RCTScrollViewComponentView
+@end
+
+@implementation PaseoScrollViewComponentView {
+  CGPoint _offsetBeforeMount;
+  __weak UIView *_anchorBeforeMount;
+  NSInteger _anchorTagBeforeMount;
+}
+
+// Replaces React Native's class for the ScrollView component. The factory looks a component up the
+// first time it mounts, so the registration has to come before the first surface.
++ (void)load
+{
+  [[RCTComponentViewFactory currentComponentViewFactory] registerComponentViewClass:self];
+}
+
+// iOS 26 blurs a scroll view's edges and places the blur in the scroll view's own coordinates,
+// ignoring transforms. The keyboard lifts the chat with a translateY, so on iPhones the blur lands
+// over the readable chat and stays until the next scroll (#7883). React Native hides it for
+// inverted lists for the same reason (https://github.com/react/react-native/pull/58684). The app
+// draws its own header fade, so every edge is hidden; hiding only top and bottom leaves the side
+// effects, which also cover a transformed list on device.
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+#if defined(__IPHONE_26_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_26_0
+    if (@available(iOS 26.0, *)) {
+      UIScrollView *scrollView = self.scrollView;
+      scrollView.topEdgeEffect.hidden = YES;
+      scrollView.bottomEdgeEffect.hidden = YES;
+      scrollView.leftEdgeEffect.hidden = YES;
+      scrollView.rightEdgeEffect.hidden = YES;
+    }
+#endif
+  }
+  return self;
+}
+
+- (void)mountingTransactionWillMount:(const MountingTransaction &)transaction
+                withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
+{
+  _offsetBeforeMount = self.scrollView.contentOffset;
+  _anchorBeforeMount = [self visibleContentAnchor];
+  _anchorTagBeforeMount = _anchorBeforeMount.tag;
+  [super mountingTransactionWillMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+}
+
+- (void)mountingTransactionDidMount:(const MountingTransaction &)transaction
+               withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
+{
+  // The view registry sets a removed view's tag to 0; a released view reads nil here.
+  BOOL isAnchorRemoved = _anchorTagBeforeMount != 0 && _anchorBeforeMount.tag != _anchorTagBeforeMount;
+  if (isAnchorRemoved || (self.scrollView.isDragging && [self isEndPin:_anchorBeforeMount])) {
+    // Without the content-position props, React Native's mount completes without moving the offset.
+    SharedViewProps props = _props;
+    _props = ScrollViewShadowNode::defaultSharedProps();
+    [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+    _props = props;
+    return;
+  }
+  if (![self didClampOffsetDuringMount]) {
+    [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+    return;
+  }
+  UIScrollView *scrollView = self.scrollView;
+  scrollView.contentOffset = _offsetBeforeMount;
+  [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+  CGFloat y = MAX(MIN(scrollView.contentOffset.y, [self maxOffsetY]), -scrollView.adjustedContentInset.top);
+  if (y != scrollView.contentOffset.y) {
+    scrollView.contentOffset = CGPointMake(scrollView.contentOffset.x, y);
+  }
+}
+
+// UIKit moved the offset to the new end while the mount set a smaller contentSize. A user scroll
+// never gets here: React Native keeps the offset through contentSize changes while the user scrolls.
+- (BOOL)didClampOffsetDuringMount
+{
+  const auto &props = static_cast<const ScrollViewProps &>(*_props);
+  if (!props.maintainVisibleContentPosition) {
+    return NO;
+  }
+  CGFloat y = self.scrollView.contentOffset.y;
+  return y < _offsetBeforeMount.y - 0.5 && ABS(y - [self maxOffsetY]) <= 0.5;
+}
+
+// The view React Native anchors on for vertical content: the first content child from
+// minIndexForVisible that reaches into the viewport, or the last one.
+- (UIView *)visibleContentAnchor
+{
+  const auto &props = static_cast<const ScrollViewProps &>(*_props);
+  UIScrollView *scrollView = self.scrollView;
+  if (!props.maintainVisibleContentPosition || scrollView.contentSize.width > self.frame.size.width) {
+    return nil;
+  }
+  NSArray<UIView *> *children = [self contentView].subviews;
+  NSUInteger first = props.maintainVisibleContentPosition.value().minIndexForVisible;
+  for (NSUInteger index = first; index < children.count; ++index) {
+    UIView *child = children[index];
+    if (CGRectGetMaxY(child.frame) > scrollView.contentOffset.y || index == children.count - 1) {
+      return child;
+    }
+  }
+  return nil;
+}
+
+- (BOOL)isEndPin:(UIView *)view
+{
+  return [view isKindOfClass:[RCTViewComponentView class]] &&
+      [((RCTViewComponentView *)view).nativeId isEqualToString:@"paseo-end-pin"];
+}
+
+- (UIView *)contentView
+{
+  for (UIView *child in self.containerView.subviews) {
+    if (![child conformsToProtocol:@protocol(RCTCustomPullToRefreshViewProtocol)]) {
+      return child;
+    }
+  }
+  return nil;
+}
+
+- (CGFloat)maxOffsetY
+{
+  UIScrollView *scrollView = self.scrollView;
+  return MAX(
+      scrollView.contentSize.height - scrollView.bounds.size.height + scrollView.adjustedContentInset.bottom,
+      -scrollView.adjustedContentInset.top);
+}
+
+@end
diff --git a/packages/app/modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json b/packages/app/modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json
index 31c2b0c8d7..351ed32e73 100644
--- a/packages/app/modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json
+++ b/packages/app/modules/paseo-terminal/android/src/androidTest/assets/grapheme-rows.json
@@ -1,21 +1,21 @@
 [
   {
     "output": "स्ते",
-    "row": "2,1,2,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;स्ते      ",
-    "clusterStarts": [0, 2, 3, 4, 5, 6, 7],
-    "contrastStarts": [0, 1, 2, 3, 4, 5, 6, 7]
+    "row": "4,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;स्ते       ",
+    "clusterStarts": [0, 1, 2, 3, 4, 5, 6, 7],
+    "contrastStarts": [0, 2, 3, 4, 5, 6, 7]
   },
   {
     "output": "क्ष",
-    "row": "2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;क्ष      ",
-    "clusterStarts": [0, 2, 3, 4, 5, 6, 7],
-    "contrastStarts": [0, 1, 2, 3, 4, 5, 6, 7]
+    "row": "3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;क्ष       ",
+    "clusterStarts": [0, 1, 2, 3, 4, 5, 6, 7],
+    "contrastStarts": [0, 2, 3, 4, 5, 6, 7]
   },
   {
     "output": "নক্ষত্র",
-    "row": "1,1,2,1,1,1,2,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;নক্ষত্র   ",
-    "clusterStarts": [0, 1, 3, 5, 6, 7],
-    "contrastStarts": [0, 1, 2, 3, 4, 5, 6, 7]
+    "row": "1,1,3,1,3,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;নক্ষত্র     ",
+    "clusterStarts": [0, 1, 2, 3, 4, 5, 6, 7],
+    "contrastStarts": [0, 2, 3, 4, 5, 6, 7]
   },
   {
     "output": "क्अ",
@@ -31,7 +31,7 @@
   },
   {
     "output": "अ्क",
-    "row": "2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;अ्क      ",
+    "row": "3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1;8,4294638330,0,0;अ्क       ",
     "clusterStarts": [0, 1, 2, 3, 4, 5, 6, 7],
     "contrastStarts": [0, 2, 3, 4, 5, 6, 7]
   }
diff --git a/packages/app/modules/paseo-terminal/android/src/androidTest/java/sh/paseo/terminal/TerminalRowLayoutTest.kt b/packages/app/modules/paseo-terminal/android/src/androidTest/java/sh/paseo/terminal/TerminalRowLayoutTest.kt
index 8e889bccf2..632065eab0 100644
--- a/packages/app/modules/paseo-terminal/android/src/androidTest/java/sh/paseo/terminal/TerminalRowLayoutTest.kt
+++ b/packages/app/modules/paseo-terminal/android/src/androidTest/java/sh/paseo/terminal/TerminalRowLayoutTest.kt
@@ -1,6 +1,5 @@
 package sh.paseo.terminal
 
-import android.os.Build
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.graphics.Paint
@@ -44,13 +43,6 @@ class TerminalRowLayoutTest {
       val output = row.getString("output")
       val (toExpected, toContrast) = difference(drawn, expected) to difference(drawn, contrast)
       Log.i("TerminalRowLayoutTest", "$output expected=$toExpected contrast=$toContrast")
-      // Android 10's platform ICU splits this conjunct. Keep its observed raster baseline
-      // explicit rather than claiming this supported OS passes the modern grapheme corpus.
-      if (Build.VERSION.SDK_INT == 29 && output == "स्ते") {
-        assertTrue("Android 10 unexpectedly matches modern conjunct clustering", toExpected > MATCH_TOLERANCE)
-        assertTrue("Android 10 split-conjunct baseline changed", toContrast <= MATCH_TOLERANCE)
-        continue
-      }
       assertTrue("$output differs from its grapheme clusters by $toExpected", toExpected <= MATCH_TOLERANCE)
       assertTrue("$output also matches the wrong clusters", toContrast > MATCH_TOLERANCE)
     }
diff --git a/packages/app/modules/paseo-window-layout/expo-module.config.json b/packages/app/modules/paseo-window-layout/expo-module.config.json
new file mode 100644
index 0000000000..369360a041
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/expo-module.config.json
@@ -0,0 +1,4 @@
+{
+  "platforms": ["ios"],
+  "ios": { "modules": ["PaseoWindowLayoutModule"] }
+}
diff --git a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec
new file mode 100644
index 0000000000..6f2e20f24a
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec
@@ -0,0 +1,15 @@
+Pod::Spec.new do |s|
+  s.name = 'PaseoWindowLayout'
+  s.version = '0.1.0'
+  s.summary = 'System window layout geometry for Paseo'
+  s.description = 'Publishes system bar and division geometry'
+  s.license = 'Apache-2.0'
+  s.author = 'Paseo'
+  s.homepage = 'https://paseo.sh'
+  s.platforms = { :ios => '16.4' }
+  s.swift_version = '5.4'
+  s.source = { :path => '.' }
+  s.static_framework = true
+  s.dependency 'ExpoModulesCore'
+  s.source_files = '**/*.swift'
+end
diff --git a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
new file mode 100644
index 0000000000..2168daf5b6
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
@@ -0,0 +1,140 @@
+import ExpoModulesCore
+import UIKit
+
+public final class PaseoWindowLayoutModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("PaseoWindowLayout")
+    View(WindowLayoutView.self) {
+      Events("onGeometryChange")
+    }
+  }
+}
+
+final class WindowLayoutView: ExpoView {
+  let onGeometryChange = EventDispatcher()
+  private var updateScheduled = false
+  private var previousPayload: [String: Any]?
+  private var divisions: [CGRect] = []
+  private var barGuide: UILayoutGuide?
+  private var barEdge = "none"
+  private var bottomBarGuide: UILayoutGuide?
+  private var topBarGuide: UILayoutGuide?
+  private var occlusions: [CGRect] = []
+  private var measuredBounds = CGRect.zero
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    isUserInteractionEnabled = false
+    #if compiler(>=6.4)
+    if #available(iOS 27.1, *) {
+      registerForTraitChanges(UITraitCollection.systemTraitsAffectingVerticalBarEdge) {
+        (view: WindowLayoutView, _) in
+        view.setNeedsUpdateConstraints()
+        view.scheduleUpdate()
+      }
+    }
+    #endif
+  }
+
+  override func didMoveToWindow() {
+    super.didMoveToWindow()
+    previousPayload = nil
+    bottomBarGuide = nil
+    topBarGuide = nil
+    setNeedsUpdateConstraints()
+    scheduleUpdate()
+  }
+
+  override func safeAreaInsetsDidChange() {
+    super.safeAreaInsetsDidChange()
+    setNeedsUpdateConstraints()
+    scheduleUpdate()
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    if bounds != measuredBounds {
+      measuredBounds = bounds
+      setNeedsUpdateConstraints()
+    }
+    scheduleUpdate()
+  }
+
+  override func updateConstraints() {
+    #if compiler(>=6.4)
+    if #available(iOS 27.1, *) {
+      // UIKit tracks these reads and invalidates constraints when regions change.
+      divisions = reservedRegions(kind: .division).compactMap { $0.isActive ? $0.frame : nil }
+      // Frames already include the system's interactive margins.
+      occlusions = reservedRegions(kind: .occlusion).compactMap { $0.isActive ? $0.frame : nil }
+      let edge: String
+      switch traitCollection.verticalBarEdge {
+      case .leading: edge = "leading"
+      case .trailing: edge = "trailing"
+      default: edge = "none"
+      }
+      if bottomBarGuide == nil {
+        // Where a bottom bar rests: above the home indicator, refined to the
+        // screen's corners rather than the rectangular safe area.
+        bottomBarGuide = layoutGuide(for: .bar(onEdge: UIRectEdge.bottom, extent: 44))
+      }
+      if topBarGuide == nil {
+        // Where a top bar rests. Beside a partial status region it can start above the
+        // rectangular safe area; content still keeps out of the occlusions.
+        topBarGuide = layoutGuide(for: .bar(onEdge: UIRectEdge.top, extent: 44))
+      }
+      if edge != barEdge {
+        barEdge = edge
+        barGuide = edge == "none" ? nil : layoutGuide(
+          for: .bar(onEdge: edge == "trailing" ? .right : .left, extent: 44)
+        )
+      }
+    }
+    #endif
+    super.updateConstraints()
+    scheduleUpdate()
+  }
+
+  private func scheduleUpdate() {
+    guard !updateScheduled else { return }
+    updateScheduled = true
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      self.updateScheduled = false
+      self.publish()
+    }
+  }
+
+  private func publish() {
+    guard window != nil, bounds.width > 0, bounds.height > 0 else { return }
+    let bar = barGuide?.layoutFrame
+    var barPayload: Any = NSNull()
+    if let bar, bar.width > 0, bar.height > 0 { barPayload = rect(bar) }
+    // Before UIKit resolves the guide its frame has no height: publish null (the
+    // system inset applies) rather than a false zero clearance.
+    var bottomClearance: Any = NSNull()
+    if let bottomBar = bottomBarGuide?.layoutFrame, bottomBar.height > 0 {
+      bottomClearance = max(0, bounds.maxY - bottomBar.maxY)
+    }
+    var topBar: Any = NSNull()
+    if let frame = topBarGuide?.layoutFrame, frame.width > 0, frame.height > 0 {
+      topBar = rect(frame)
+    }
+    let payload: [String: Any] = [
+      "bounds": rect(bounds),
+      "verticalBarEdge": barEdge,
+      "verticalBar": barPayload,
+      "bottomClearance": bottomClearance,
+      "topBar": topBar,
+      "occlusions": occlusions.map(rect),
+      "divisions": divisions.map(rect)
+    ]
+    guard !NSDictionary(dictionary: payload).isEqual(to: previousPayload ?? [:]) else { return }
+    previousPayload = payload
+    onGeometryChange(payload)
+  }
+
+  private func rect(_ frame: CGRect) -> [String: CGFloat] {
+    ["x": frame.minX, "y": frame.minY, "width": frame.width, "height": frame.height]
+  }
+}
diff --git a/packages/app/package.json b/packages/app/package.json
index 4fcd5d4737..456765a4f4 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "private": true,
   "main": "index.ts",
   "scripts": {
@@ -40,7 +40,7 @@
     "dev:ios": "npm --prefix ../.. run build:client && cross-env APP_VARIANT=development expo run:ios",
     "build:apk": "npm --prefix ../.. run build:apk",
     "build:apk:arm64": "npm --prefix ../.. run build:apk:arm64",
-    "test:android": "expo prebuild --platform android --no-install && cd android && ./gradlew :paseo-native-trace:testReleaseUnitTest :react-native-enriched-markdown:testReleaseUnitTest --tests '*InlineCodeFormattingTest' --no-daemon --max-workers=2 -Dorg.gradle.parallel=false"
+    "test:android": "expo prebuild --platform android --no-install && cd android && ./gradlew :paseo-native-trace:testReleaseUnitTest :paseo-hardware-keyboard:testReleaseUnitTest :react-native-enriched-markdown:testReleaseUnitTest --tests '*InlineCodeFormattingTest' --no-daemon --max-workers=2 -Dorg.gradle.parallel=false"
   },
   "dependencies": {
     "@codemirror/commands": "6.10.4",
@@ -59,6 +59,7 @@
     "@getpaseo/protocol": "*",
     "@gorhom/bottom-sheet": "^5.2.14",
     "@gorhom/portal": "^1.0.14",
+    "@legendapp/list": "^3.7.1",
     "@marijn/find-cluster-break": "^1.0.2",
     "@mattermost/react-native-paste-input": "2.0.1",
     "@react-native-async-storage/async-storage": "2.2.0",
@@ -71,13 +72,14 @@
     "@tanstack/react-virtual": "^3.13.21",
     "@xterm/addon-clipboard": "^0.3.0-beta.213",
     "@xterm/addon-fit": "^0.12.0-beta.213",
-    "@xterm/addon-image": "^0.10.0-beta.213",
+    "@xterm/addon-image": "0.10.0-beta.331",
     "@xterm/addon-ligatures": "^0.11.0-beta.213",
     "@xterm/addon-search": "^0.17.0-beta.213",
+    "@xterm/addon-unicode-graphemes": "0.5.0-beta.330",
     "@xterm/addon-unicode11": "^0.10.0-beta.213",
     "@xterm/addon-web-links": "^0.13.0-beta.213",
-    "@xterm/addon-webgl": "0.20.0-beta.291",
-    "@xterm/xterm": "6.1.0-beta.292",
+    "@xterm/addon-webgl": "0.20.0-beta.329",
+    "@xterm/xterm": "6.1.0-beta.336",
     "buffer": "^6.0.3",
     "expo": "~57.0.30",
     "expo-asset": "~57.0.20",
@@ -155,7 +157,7 @@
     "@vitest/browser": "^4.1.7",
     "@vitest/browser-playwright": "^4.1.7",
     "@xterm/addon-serialize": "0.14.0",
-    "@xterm/headless": "^6.1.0-beta.213",
+    "@xterm/headless": "6.1.0-beta.334",
     "babel-preset-expo": "~57.0.16",
     "dotenv": "^17.2.3",
     "eas-cli": "^16.24.1",
diff --git a/packages/app/src/hooks/agent-commands-query.ts b/packages/app/src/agent-commands/cache/index.ts
similarity index 52%
rename from packages/app/src/hooks/agent-commands-query.ts
rename to packages/app/src/agent-commands/cache/index.ts
index 276c0fd9ba..baee276a47 100644
--- a/packages/app/src/hooks/agent-commands-query.ts
+++ b/packages/app/src/agent-commands/cache/index.ts
@@ -1,8 +1,16 @@
 import type { QueryClient } from "@tanstack/react-query";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
+import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
+import equal from "fast-deep-equal";
 import { normalizeWorkspacePath } from "@/utils/workspace-identity";
 
 export const AGENT_COMMANDS_QUERY_ROOT = "agentCommands";
+export const sessionCommandQueryPolicy = {
+  staleTime: 600_000,
+  gcTime: 1_800_000,
+  refetchOnMount: true,
+  refetchOnWindowFocus: false,
+} as const;
 
 export interface AgentCommandsDraftConfig {
   provider: AgentProvider;
@@ -10,7 +18,7 @@ export interface AgentCommandsDraftConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }
 
 export function normalizeAgentCommandsCwd(cwd: string): string {
@@ -21,6 +29,46 @@ export function agentCommandsQueryRoot(serverId: string) {
   return [AGENT_COMMANDS_QUERY_ROOT, serverId] as const;
 }
 
+/** Snapshot announcements contain provider metadata, not command catalogs. Ignore initial
+ * discovery and unrelated providers; explicit refresh still invalidates every catalog. */
+export function invalidateCommandsForProviderChange(input: {
+  queryClient: QueryClient;
+  serverId: string;
+  cwd: string | null;
+  previous: readonly ProviderSnapshotEntry[] | undefined;
+  current: readonly ProviderSnapshotEntry[];
+}): Promise<void> {
+  const previous = new Map((input.previous ?? []).map((entry) => [entry.provider, entry]));
+  const current = new Map(input.current.map((entry) => [entry.provider, entry]));
+  const relevant = (entry: ProviderSnapshotEntry | undefined) =>
+    entry && {
+      status: entry.status,
+      enabled: entry.enabled,
+      source: entry.source,
+      models: entry.models,
+      modes: entry.modes,
+      defaultModeId: entry.defaultModeId,
+    };
+  return input.queryClient.invalidateQueries({
+    queryKey: agentCommandsQueryRoot(input.serverId),
+    predicate: (query) => {
+      const isDraft = query.queryKey[2] === "draft";
+      const provider =
+        query.meta?.agentCommandProvider ?? (isDraft ? query.queryKey[6] : undefined);
+      const cwd = query.meta?.agentCommandCwd ?? (isDraft ? query.queryKey[4] : undefined);
+      if (input.cwd && typeof cwd === "string" && normalizeAgentCommandsCwd(cwd) !== input.cwd)
+        return false;
+      if (typeof provider !== "string") return false;
+      const before = previous.get(provider);
+      const after = current.get(provider);
+      if (!before) return after?.status === "ready" && query.state.status === "error";
+      if (before.status !== "ready")
+        return after?.status === "ready" && query.state.status === "error";
+      return !equal(relevant(before), relevant(after));
+    },
+  });
+}
+
 export function sessionAgentCommandsQueryKey(input: { serverId: string; agentId: string }) {
   return [...agentCommandsQueryRoot(input.serverId), "session", input.agentId] as const;
 }
@@ -50,7 +98,7 @@ export function draftAgentCommandsQueryKey(input: {
     "thinking",
     draftConfig.thinkingOptionId ?? null,
     "features",
-    draftConfig.featureValues ?? null,
+    draftConfig.providerOptions ?? null,
   ] as const;
 }
 
diff --git a/packages/app/src/agent-commands/index.tsx b/packages/app/src/agent-commands/index.tsx
new file mode 100644
index 0000000000..23d5a61e5f
--- /dev/null
+++ b/packages/app/src/agent-commands/index.tsx
@@ -0,0 +1,99 @@
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import type { ComposerEditingSession } from "@/composer/editing-session";
+import { agentCommandsQueryKey } from "./cache";
+import {
+  useAgentCommandsQuery,
+  type AgentSlashCommand,
+  type DraftCommandConfig,
+} from "./use-query";
+
+export type {
+  AgentSlashCommand,
+  DraftCommandConfig,
+  DraftCommandTarget,
+  AgentCommandsClient,
+} from "./use-query";
+export { fetchAgentCommands } from "./use-query";
+
+type CommandQuery = ReturnType<typeof useAgentCommandsQuery>;
+const QueryContext = createContext<CommandQuery | null>(null);
+export interface CommandHints {
+  names: ReadonlySet<string>;
+  insert(command: string): void;
+}
+const HintsContext = createContext<CommandHints | null>(null);
+
+function useLiveAgentCommands() {
+  return useContext(QueryContext);
+}
+export function useAutocompleteCommands(input: {
+  serverId: string;
+  agentId: string;
+  enabled: boolean;
+  draftConfig?: DraftCommandConfig;
+}) {
+  const live = useLiveAgentCommands();
+  const fallback = useAgentCommandsQuery({
+    serverId: input.serverId,
+    agentId: input.agentId,
+    enabled: !live && input.enabled,
+    draftConfig: input.draftConfig,
+  });
+  return live ?? fallback;
+}
+export function useAgentCommandHints() {
+  return useContext(HintsContext);
+}
+export function matchCommandLink(
+  url: string,
+  sourceType: "markdown" | "text" | "inline-code" | undefined,
+  names: ReadonlySet<string>,
+): string | null {
+  return (sourceType === "markdown" || sourceType === "inline-code") &&
+    url.startsWith("/") &&
+    names.has(url.slice(1))
+    ? url
+    : null;
+}
+
+export function AgentCommandsProvider({
+  serverId,
+  agentId,
+  editingSession,
+  enabled,
+  children,
+}: {
+  serverId: string;
+  agentId: string;
+  editingSession: ComposerEditingSession;
+  enabled: boolean;
+  children: ReactNode;
+}) {
+  const query = useAgentCommandsQuery({ serverId, agentId, enabled });
+  const queryClient = useQueryClient();
+  const namesKey = JSON.stringify(
+    [...new Set(query.commands.map((command) => command.name))].sort(),
+  );
+  const names = useMemo<ReadonlySet<string>>(
+    () => new Set(JSON.parse(namesKey) as string[]),
+    [namesKey],
+  );
+  const insert = useCallback(
+    (token: string) => {
+      const commands = queryClient.getQueryData<AgentSlashCommand[]>(
+        agentCommandsQueryKey({ serverId, agentId }),
+      );
+      if (token.startsWith("/") && commands?.some((command) => `/${command.name}` === token)) {
+        editingSession.insertCommand(token);
+      }
+    },
+    [agentId, editingSession, queryClient, serverId],
+  );
+  const hints = useMemo(() => ({ names, insert }), [names, insert]);
+  return (
+    <QueryContext.Provider value={enabled ? query : null}>
+      <HintsContext.Provider value={enabled ? hints : null}>{children}</HintsContext.Provider>
+    </QueryContext.Provider>
+  );
+}
diff --git a/packages/app/src/hooks/agent-commands-query.test.ts b/packages/app/src/agent-commands/query.test.ts
similarity index 51%
rename from packages/app/src/hooks/agent-commands-query.test.ts
rename to packages/app/src/agent-commands/query.test.ts
index e8d8ee0b94..33b55b4464 100644
--- a/packages/app/src/hooks/agent-commands-query.test.ts
+++ b/packages/app/src/agent-commands/query.test.ts
@@ -1,11 +1,61 @@
 import { describe, expect, it } from "vitest";
+import { QueryClient, QueryObserver } from "@tanstack/react-query";
+import { fetchQueryOptions } from "@/data/query";
 import {
   agentCommandsQueryKey,
   agentCommandsQueryRoot,
   draftAgentCommandsQueryKey,
   normalizeAgentCommandsCwd,
   sessionAgentCommandsQueryKey,
-} from "./agent-commands-query";
+  sessionCommandQueryPolicy,
+} from "./cache";
+
+it("reuses fresh commands and keeps stale commands during a shared refresh and failure", async () => {
+  const client = new QueryClient({ defaultOptions: { queries: { gcTime: 300_000 } } });
+  const key = sessionAgentCommandsQueryKey({ serverId: "s", agentId: "a" });
+  let calls = 0;
+  let fail = false;
+  let resolveRefresh: (value: string[]) => void = () => {};
+  const refresh = new Promise<string[]>((resolve) => {
+    resolveRefresh = resolve;
+  });
+  const options = fetchQueryOptions({
+    ...sessionCommandQueryPolicy,
+    staleTimeMs: sessionCommandQueryPolicy.staleTime,
+    dataShape: "value",
+    queryKey: key,
+    retry: false,
+    queryFn: async () => {
+      calls++;
+      if (fail) throw new Error("offline");
+      return refresh;
+    },
+  });
+  client.setQueryData(key, ["old"]);
+  const fresh = new QueryObserver(client, options);
+  const unsubscribeFresh = fresh.subscribe(() => {});
+  expect(calls).toBe(0);
+  unsubscribeFresh();
+  client.setQueryData(key, ["old"], { updatedAt: 1 });
+  const first = new QueryObserver(client, options);
+  const second = new QueryObserver(client, options);
+  const unsubscribeFirst = first.subscribe(() => {});
+  const unsubscribeSecond = second.subscribe(() => {});
+  expect(calls).toBe(1);
+  expect(first.getCurrentResult().data).toEqual(["old"]);
+  expect(client.getQueryCache().find({ queryKey: key })?.gcTime).toBe(1_800_000);
+  resolveRefresh(["new"]);
+  await refresh;
+  await first.refetch({ cancelRefetch: false });
+  expect(second.getCurrentResult().data).toEqual(["new"]);
+  fail = true;
+  await client.invalidateQueries({ queryKey: key });
+  expect(first.getCurrentResult().data).toEqual(["new"]);
+  expect(first.getCurrentResult().isError).toBe(true);
+  unsubscribeFirst();
+  unsubscribeSecond();
+  client.clear();
+});
 
 describe("agent command query keys", () => {
   it("shares draft commands across draft tabs with the same provider setup", () => {
diff --git a/packages/app/src/hooks/use-agent-commands-query.test.ts b/packages/app/src/agent-commands/use-query.test.ts
similarity index 82%
rename from packages/app/src/hooks/use-agent-commands-query.test.ts
rename to packages/app/src/agent-commands/use-query.test.ts
index 87f5919da8..db14491923 100644
--- a/packages/app/src/hooks/use-agent-commands-query.test.ts
+++ b/packages/app/src/agent-commands/use-query.test.ts
@@ -1,9 +1,5 @@
 import { describe, expect, it } from "vitest";
-import {
-  type AgentCommandsClient,
-  type DraftCommandConfig,
-  fetchAgentCommands,
-} from "./use-agent-commands-query";
+import { type AgentCommandsClient, type DraftCommandConfig, fetchAgentCommands } from "./use-query";
 
 type ListCommands = AgentCommandsClient["listCommands"];
 type ListCommandsResult = Awaited<ReturnType<ListCommands>>;
@@ -38,6 +34,12 @@ function commandsPayload(commands: ListCommandsResult["commands"]): ListCommands
 }
 
 describe("fetchAgentCommands", () => {
+  it("rejects a discovery error so a previous catalog is retained", async () => {
+    const client = createClient({ ...commandsPayload([]), error: "provider unavailable" });
+    await expect(fetchAgentCommands({ client, agentId: "agent-1" })).rejects.toThrow(
+      "provider unavailable",
+    );
+  });
   it("loads commands for a draft composer without an agent id", async () => {
     const client = createClient(
       commandsPayload([{ name: "compact", description: "Compact context", argumentHint: "" }]),
diff --git a/packages/app/src/hooks/use-agent-commands-query.ts b/packages/app/src/agent-commands/use-query.ts
similarity index 62%
rename from packages/app/src/hooks/use-agent-commands-query.ts
rename to packages/app/src/agent-commands/use-query.ts
index eddc0ab02b..61a869d092 100644
--- a/packages/app/src/hooks/use-agent-commands-query.ts
+++ b/packages/app/src/agent-commands/use-query.ts
@@ -1,12 +1,17 @@
-import { useQuery } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useFetchQuery } from "@/data/query";
 import { useTranslation } from "react-i18next";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { useRetainedPanelActive } from "@/components/retained-panel";
+import { useSessionStore } from "@/stores/session-store";
+import { useShallow } from "zustand/shallow";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import { agentCommandsQueryKey, type AgentCommandsDraftConfig } from "@/hooks/agent-commands-query";
-
-const DRAFT_COMMANDS_STALE_TIME = Number.POSITIVE_INFINITY;
-const SESSION_COMMANDS_STALE_TIME = 60_000;
+import {
+  agentCommandsQueryKey,
+  sessionCommandQueryPolicy,
+  type AgentCommandsDraftConfig,
+} from "./cache";
 
 export interface AgentSlashCommand {
   name: string;
@@ -41,6 +46,7 @@ export async function fetchAgentCommands(input: {
     agentId: input.agentId,
     draftConfig: input.draftConfig,
   });
+  if (response.error) throw new Error(response.error);
   return response.commands as AgentSlashCommand[];
 }
 
@@ -62,8 +68,17 @@ export function useAgentCommandsQuery({
   const queryEnabled = enabled && retainedPanelActive;
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
+  const { provider, cwd } = useSessionStore(
+    useShallow((state) => {
+      const agent =
+        state.sessions[serverId]?.agents?.get(agentId) ??
+        state.sessions[serverId]?.agentDetails?.get(agentId);
+      return { provider: agent?.provider, cwd: agent?.cwd };
+    }),
+  );
 
-  const query = useQuery({
+  const queryClient = useQueryClient();
+  const query = useFetchQuery({
     queryKey: agentCommandsQueryKey({ serverId, agentId, draftConfig }),
     queryFn: async () => {
       if (!client) {
@@ -72,7 +87,15 @@ export function useAgentCommandsQuery({
       return fetchAgentCommands({ client, agentId, draftConfig });
     },
     enabled: queryEnabled && !!client && isConnected && (!!agentId || !!draftConfig),
-    staleTime: draftConfig ? DRAFT_COMMANDS_STALE_TIME : SESSION_COMMANDS_STALE_TIME,
+    dataShape: "value",
+    meta: {
+      agentCommandProvider: draftConfig?.provider ?? provider,
+      agentCommandCwd: draftConfig?.cwd ?? cwd,
+    },
+    ...(draftConfig
+      ? { immutableWhen: () => true as const }
+      : { ...sessionCommandQueryPolicy, staleTimeMs: sessionCommandQueryPolicy.staleTime }),
+    subscribed: queryEnabled,
     retry: 3,
     retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 5000),
   });
@@ -81,10 +104,20 @@ export function useAgentCommandsQuery({
   // isLoading is true when fetching and no data yet
   const isLoading = query.isPending || query.isLoading;
 
+  // Reset rather than refetch: a refetch keeps the error status while it runs, and the menu
+  // shows loading for the retry.
+  const retry = useCallback(() => {
+    void queryClient.resetQueries({
+      queryKey: agentCommandsQueryKey({ serverId, agentId, draftConfig }),
+      exact: true,
+    });
+  }, [agentId, draftConfig, queryClient, serverId]);
+
   return {
     commands: query.data ?? [],
     isLoading,
-    isError: query.isError,
+    isError: query.isError && query.data === undefined,
     error: query.error,
+    retry,
   };
 }
diff --git a/packages/app/src/agent-controls/draft-options-model.test.ts b/packages/app/src/agent-controls/draft-options-model.test.ts
new file mode 100644
index 0000000000..1efee32348
--- /dev/null
+++ b/packages/app/src/agent-controls/draft-options-model.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it } from "vitest";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import { isControlActive } from "./option-controls";
+import {
+  draftControlsRequest,
+  openDraftOptions,
+  ownDraftOptions,
+  viewDraftOptions,
+} from "./draft-options-model";
+
+const SPEED: AgentOptionControl = {
+  type: "select",
+  key: "service_tier",
+  label: "Speed",
+  defaultValue: "default",
+  choices: [
+    { value: "default", label: "Standard" },
+    { value: "priority", label: "Fast" },
+  ],
+};
+const WEB_SEARCH: AgentOptionControl = { type: "toggle", key: "web_search", label: "Web search" };
+
+function answer(
+  provider: string,
+  requestKey: string,
+  options: Record<string, unknown>,
+  controls = [SPEED, WEB_SEARCH],
+) {
+  return { provider, requestKey, controls, options };
+}
+
+describe("draft options model", () => {
+  it("draws a legacy Fast profile as the Fast tier the daemon resolved", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { service_tier: "fast" } });
+    model.applyResolved(answer("codex", "k1", { service_tier: "priority" }));
+
+    const view = viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k1" });
+
+    expect(view?.options).toEqual({ service_tier: "priority" });
+    expect(view && isControlActive(SPEED, view.options)).toBe(true);
+    // The daemon still gets the stored value to resolve, and so does create.
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "fast" });
+  });
+
+  it("applying a profile from another provider keeps its options through the provider change", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", {}));
+
+    model.applyProfile({
+      provider: "codex",
+      options: { sandbox_mode: "read-only", service_tier: "fast" },
+    });
+    // The form follows the profile to its provider.
+    model.observeProvider("codex");
+
+    expect(ownDraftOptions(model.getState())).toEqual({
+      sandbox_mode: "read-only",
+      service_tier: "fast",
+    });
+    expect(model.getState().resolved).toBeNull();
+  });
+
+  it("choosing another provider by hand starts the options over", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { sandbox_mode: "read-only" } });
+    model.setOption("web_search", true);
+
+    model.observeProvider("claude");
+
+    expect(ownDraftOptions(model.getState())).toBeUndefined();
+    expect(model.getState().resolved).toBeNull();
+  });
+
+  it("never pairs a manually chosen provider with the previous provider's options", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(
+      answer("claude", "k1", { fast_mode: true }, [
+        { type: "toggle", key: "fast_mode", label: "Fast" },
+      ]),
+    );
+    model.setOption("fast_mode", true);
+    const form = { provider: "claude", cwd: "/repo" };
+    expect(draftControlsRequest(model.getState(), form)).toMatchObject({
+      provider: "claude",
+      providerOptions: { fast_mode: true },
+    });
+
+    // The form shows OpenCode on its next render; the model has not observed it yet.
+    expect(draftControlsRequest(model.getState(), { ...form, provider: "opencode" })).toBeNull();
+
+    model.observeProvider("opencode");
+    const request = draftControlsRequest(model.getState(), { ...form, provider: "opencode" });
+    expect(request).toEqual({ provider: "opencode", cwd: "/repo" });
+  });
+
+  it("stops sending a toggle once the model in use draws no control for it", () => {
+    const FAST_MODE: AgentOptionControl = { type: "toggle", key: "fast_mode", label: "Fast" };
+    const model = openDraftOptions({ provider: "claude", seed: { sandbox_mode: "read-only" } });
+    model.applyResolved(answer("claude", "opus", { fast_mode: false }, [FAST_MODE]));
+    model.setOption("fast_mode", true);
+    expect(ownDraftOptions(model.getState())).toEqual({
+      sandbox_mode: "read-only",
+      fast_mode: true,
+    });
+
+    // The form moves to a model without Fast; its answer lists no such control.
+    model.applyResolved(answer("claude", "haiku", {}, []));
+
+    expect(ownDraftOptions(model.getState())).toEqual({ sandbox_mode: "read-only" });
+
+    // Back on a model that draws the control, the toggle applies again. The daemon's answer
+    // for the request without it said Fast was off; the request that carries it follows.
+    model.applyResolved(answer("claude", "opus-again", { fast_mode: false }, [FAST_MODE]));
+    expect(ownDraftOptions(model.getState())).toEqual({
+      sandbox_mode: "read-only",
+      fast_mode: true,
+    });
+  });
+
+  it("always sends an option no control has drawn", () => {
+    const FAST_MODE: AgentOptionControl = { type: "toggle", key: "fast_mode", label: "Fast" };
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", {}, [FAST_MODE]));
+
+    model.setOption("token_budget", 5);
+
+    expect(ownDraftOptions(model.getState())).toEqual({ token_budget: 5 });
+    model.applyResolved(answer("claude", "k2", {}, []));
+    expect(ownDraftOptions(model.getState())).toEqual({ token_budget: 5 });
+  });
+
+  it("keeps a draft's seed when the first provider is chosen", () => {
+    const model = openDraftOptions({ provider: null, seed: { web_search: true } });
+
+    model.observeProvider("claude");
+
+    expect(ownDraftOptions(model.getState())).toEqual({ web_search: true });
+  });
+
+  it("sends a remembered value to the daemon, and draws only what comes back", () => {
+    const model = openDraftOptions({ provider: "codex" });
+    model.setRemembered({ service_tier: "fast", retired: true });
+    // Nothing is known about the provider's controls yet.
+    expect(ownDraftOptions(model.getState())).toBeUndefined();
+
+    model.applyResolved(answer("codex", "k1", { service_tier: "default" }));
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "fast" });
+    // The answer to the first request does not show the remembered value as if it applied.
+    expect(
+      viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k2" })?.options,
+    ).toEqual({ service_tier: "default" });
+
+    model.applyResolved(answer("codex", "k2", { service_tier: "priority" }));
+    expect(
+      viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k2" })?.options,
+    ).toEqual({ service_tier: "priority" });
+  });
+
+  it("does not let a remembered value override the seed", () => {
+    const model = openDraftOptions({ provider: "codex", seed: { service_tier: "default" } });
+    model.applyResolved(answer("codex", "k1", { service_tier: "default" }));
+    model.setRemembered({ service_tier: "fast" });
+
+    expect(ownDraftOptions(model.getState())).toEqual({ service_tier: "default" });
+  });
+
+  it("lays a toggle over the previous answer until the new one arrives", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", { web_search: false }));
+
+    model.setOption("web_search", true);
+
+    expect(
+      viewDraftOptions(model.getState(), { provider: "claude", requestKey: "k2" })?.options,
+    ).toEqual({ web_search: true });
+    model.applyResolved(answer("claude", "k2", { web_search: true }));
+    expect(
+      viewDraftOptions(model.getState(), { provider: "claude", requestKey: "k2" })?.options,
+    ).toEqual({ web_search: true });
+  });
+
+  it("draws nothing for a provider the answer is not for", () => {
+    const model = openDraftOptions({ provider: "claude" });
+    model.applyResolved(answer("claude", "k1", {}));
+
+    expect(viewDraftOptions(model.getState(), { provider: "codex", requestKey: "k1" })).toBe(
+      undefined,
+    );
+  });
+});
diff --git a/packages/app/src/agent-controls/draft-options-model.ts b/packages/app/src/agent-controls/draft-options-model.ts
new file mode 100644
index 0000000000..27c73194f5
--- /dev/null
+++ b/packages/app/src/agent-controls/draft-options-model.ts
@@ -0,0 +1,217 @@
+import type {
+  AgentOptionControl,
+  AgentSessionConfig,
+  ProviderOptions,
+} from "@getpaseo/protocol/agent-types";
+import { withoutLostControls } from "./lost-controls";
+
+/**
+ * The options of one draft agent, as a plain model (see docs/forms.md). It owns which layers
+ * make up the draft's options; the daemon owns what they mean. Every layer is sent to the daemon
+ * (`ownDraftOptions`) and the UI draws what comes back (`viewDraftOptions`), so no alias,
+ * default or legacy key is resolved here.
+ *
+ * - `seed`: options the draft started from (a profile, a forked agent).
+ * - `remembered`: the provider's last-used control values.
+ * - `edits`: toggles made in this draft.
+ *
+ * An edit of `null` removes the key from every layer, the way a patch does on a running agent, so
+ * the provider's default applies again.
+ *
+ * Choosing a provider by hand starts the options over; applying a profile replaces the provider
+ * and the options in one step, so the provider change that follows does not clear them.
+ */
+export interface ResolvedDraftOptions {
+  provider: string;
+  /** Names the request that produced this answer; see `viewDraftOptions`. */
+  requestKey: string;
+  controls: AgentOptionControl[];
+  options: ProviderOptions;
+}
+
+export interface DraftOptionsState {
+  provider: string | null;
+  seed: ProviderOptions;
+  remembered: ProviderOptions;
+  edits: ProviderOptions;
+  resolved: ResolvedDraftOptions | null;
+  /** Every key an answer for this provider has drawn as a control. */
+  drawn: ReadonlySet<string>;
+}
+
+export interface DraftOptionsModel {
+  getState: () => DraftOptionsState;
+  subscribe: (listener: () => void) => () => void;
+  /** The provider the draft's form now has. A different one than the model's is a manual choice. */
+  observeProvider: (provider: string | null) => void;
+  applyProfile: (profile: { provider: string; options: ProviderOptions }) => void;
+  setRemembered: (remembered: ProviderOptions) => void;
+  setOption: (key: string, value: unknown) => void;
+  applyResolved: (resolved: ResolvedDraftOptions) => void;
+}
+
+export function openDraftOptions(input: {
+  provider: string | null;
+  seed?: ProviderOptions;
+  /**
+   * The provider the draft's form has now. An edit belongs to it even before the screen has
+   * rendered the change, so `setOption` observes it first.
+   */
+  currentProvider?: () => string | null;
+}): DraftOptionsModel {
+  let state: DraftOptionsState = {
+    provider: input.provider,
+    seed: input.seed ?? {},
+    remembered: {},
+    edits: {},
+    resolved: null,
+    drawn: new Set(),
+  };
+  const listeners = new Set<() => void>();
+
+  function publish(update: (current: DraftOptionsState) => DraftOptionsState): void {
+    const next = update(state);
+    if (next === state) return;
+    state = next;
+    for (const listener of listeners) listener();
+  }
+
+  function observeProvider(provider: string | null): void {
+    publish((current) => {
+      if (provider === current.provider) return current;
+      // The first provider a draft picks does not discard what it was opened with.
+      if (current.provider === null) return { ...current, provider };
+      return { ...current, provider, seed: {}, edits: {}, resolved: null, drawn: new Set() };
+    });
+  }
+
+  return {
+    getState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    observeProvider,
+    applyProfile: (profile) =>
+      publish((current) => ({
+        ...current,
+        provider: profile.provider,
+        seed: profile.options,
+        edits: {},
+        resolved: current.provider === profile.provider ? current.resolved : null,
+        drawn: current.provider === profile.provider ? current.drawn : new Set(),
+      })),
+    setRemembered: (remembered) => publish((current) => ({ ...current, remembered })),
+    setOption: (key, value) => {
+      if (input.currentProvider) observeProvider(input.currentProvider());
+      publish((current) =>
+        Object.is(current.edits[key], value)
+          ? current
+          : { ...current, edits: { ...current.edits, [key]: value } },
+      );
+    },
+    applyResolved: (resolved) =>
+      publish((current) => ({
+        ...current,
+        resolved,
+        drawn: new Set([...current.drawn, ...resolved.controls.map((control) => control.key)]),
+      })),
+  };
+}
+
+/**
+ * Everything the draft would create with, for the daemon to resolve. A last-used value applies
+ * once the provider has told us it still draws a control for that key, and never over the seed.
+ * An edit of a key an earlier answer drew as a control stops applying when the latest answer
+ * draws none for it (the model changed to one without that control) and applies again when a
+ * control for it returns. An edit of a key no answer has drawn is an option without a control
+ * and always applies.
+ */
+export function ownDraftOptions(state: DraftOptionsState): ProviderOptions | undefined {
+  const controlKeys = new Set((state.resolved?.controls ?? []).map((control) => control.key));
+  const remembered = Object.fromEntries(
+    Object.entries(state.remembered).filter(
+      ([key]) => controlKeys.has(key) && !(key in state.seed),
+    ),
+  );
+  const edits = withoutLostControls(state.edits, state.drawn, controlKeys);
+  const own = withoutRemovals({ ...state.seed, ...remembered, ...edits });
+  return Object.keys(own).length > 0 ? own : undefined;
+}
+
+function withoutRemovals(options: ProviderOptions): ProviderOptions {
+  return Object.fromEntries(Object.entries(options).filter(([, value]) => value !== null));
+}
+
+export type DraftControlsRequest = Pick<
+  AgentSessionConfig,
+  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "providerOptions"
+>;
+
+/** What the draft's form has chosen; the options come from the model. */
+export interface DraftControlsForm {
+  provider: string | null;
+  cwd: string;
+  modeId?: string | null;
+  modelId?: string | null;
+  thinkingOptionId?: string | null;
+}
+
+/**
+ * The listing request for the draft's form, built from one snapshot of the model. The form
+ * reaches a new provider before the model has observed it, and the model still holds the
+ * previous provider's options until it does; that render has no request, so a request never
+ * pairs one provider with another's options.
+ */
+export function draftControlsRequest(
+  state: DraftOptionsState,
+  form: DraftControlsForm,
+): DraftControlsRequest | null {
+  if (!form.provider || !form.cwd || form.provider !== state.provider) return null;
+  const providerOptions = ownDraftOptions(state);
+  return {
+    provider: form.provider,
+    cwd: form.cwd,
+    ...(form.modeId ? { modeId: form.modeId } : {}),
+    ...(form.modelId ? { model: form.modelId } : {}),
+    ...(form.thinkingOptionId ? { thinkingOptionId: form.thinkingOptionId } : {}),
+    ...(providerOptions ? { providerOptions } : {}),
+  };
+}
+
+/**
+ * What the controls draw: the daemon's answer for this provider. The last answer stays up while
+ * a newer request is in flight, with the toggles made since laid over it, so a switch does not
+ * wait for the round trip. It never carries a seed or remembered value the daemon has not
+ * resolved.
+ */
+export function viewDraftOptions(
+  state: DraftOptionsState,
+  current: { provider: string | null; requestKey: string },
+): { controls: AgentOptionControl[]; options: ProviderOptions } | undefined {
+  const { resolved } = state;
+  if (!resolved || resolved.provider !== current.provider) return undefined;
+  return {
+    controls: resolved.controls,
+    options:
+      resolved.requestKey === current.requestKey
+        ? resolved.options
+        : withoutRemovals({ ...resolved.options, ...state.edits }),
+  };
+}
+
+const NO_OPTIONS: ProviderOptions = {};
+
+/**
+ * The options the draft will create with, for a plugin or a control to read: the daemon's answer
+ * for this provider when there is one, otherwise the draft's own layers, so an edit shows before
+ * the daemon has answered.
+ */
+export function shownDraftOptions(
+  state: DraftOptionsState,
+  current: { provider: string | null; requestKey: string },
+): ProviderOptions {
+  return viewDraftOptions(state, current)?.options ?? ownDraftOptions(state) ?? NO_OPTIONS;
+}
diff --git a/packages/app/src/agent-controls/icons.test.ts b/packages/app/src/agent-controls/icons.test.ts
new file mode 100644
index 0000000000..b43e7f88e7
--- /dev/null
+++ b/packages/app/src/agent-controls/icons.test.ts
@@ -0,0 +1,16 @@
+import { Settings2 } from "lucide-react-native";
+import { describe, expect, it } from "vitest";
+import { getAgentFeatureIcon } from "./icons";
+
+describe("getAgentFeatureIcon", () => {
+  it("draws the Lucide icon a plugin provider names", () => {
+    const icon = getAgentFeatureIcon("Mic");
+    expect(icon).not.toBe(Settings2);
+    expect(getAgentFeatureIcon("Mic")).toBe(icon);
+  });
+
+  it("falls back to the generic icon for a missing or unknown name", () => {
+    expect(getAgentFeatureIcon()).toBe(Settings2);
+    expect(getAgentFeatureIcon("not-an-icon")).toBe(Settings2);
+  });
+});
diff --git a/packages/app/src/agent-controls/icons.ts b/packages/app/src/agent-controls/icons.ts
index 06b2759071..485eb3e915 100644
--- a/packages/app/src/agent-controls/icons.ts
+++ b/packages/app/src/agent-controls/icons.ts
@@ -13,11 +13,13 @@ import {
   ShieldQuestionMark,
   Zap,
 } from "lucide-react-native";
+import { isLucideIconName, pluginIconComponent } from "@/plugins/icons";
 import { getModeVisuals, type AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 
 export interface AgentControlIconProps {
   size: number;
   color: string;
+  strokeWidth?: number;
 }
 
 export type AgentControlIcon = ComponentType<AgentControlIconProps>;
@@ -60,6 +62,9 @@ export function getAgentModeOptionIcon(
   return icon ? MODE_ICONS[icon] : undefined;
 }
 
+/** A built-in control names its icon in kebab case; a plugin provider names a Lucide icon. */
 export function getAgentFeatureIcon(icon?: string): AgentControlIcon {
-  return (icon ? FEATURE_ICONS[icon] : undefined) ?? Settings2;
+  if (!icon) return Settings2;
+  if (FEATURE_ICONS[icon]) return FEATURE_ICONS[icon];
+  return isLucideIconName(icon) ? pluginIconComponent(icon) : Settings2;
 }
diff --git a/packages/app/src/agent-controls/lost-controls.ts b/packages/app/src/agent-controls/lost-controls.ts
new file mode 100644
index 0000000000..0ea7d76940
--- /dev/null
+++ b/packages/app/src/agent-controls/lost-controls.ts
@@ -0,0 +1,17 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+
+/**
+ * The options that still apply after an answer from the daemon. A key an earlier answer drew as a
+ * control and the latest answer does not (the model changed to one without that control) is
+ * dropped, and applies again if a control for it returns. A key no answer has drawn is an option
+ * without a control and always applies.
+ */
+export function withoutLostControls(
+  options: ProviderOptions,
+  drawn: ReadonlySet<string>,
+  current: ReadonlySet<string>,
+): ProviderOptions {
+  return Object.fromEntries(
+    Object.entries(options).filter(([key]) => !drawn.has(key) || current.has(key)),
+  );
+}
diff --git a/packages/app/src/agent-controls/option-controls.test.ts b/packages/app/src/agent-controls/option-controls.test.ts
new file mode 100644
index 0000000000..b14f20d6ed
--- /dev/null
+++ b/packages/app/src/agent-controls/option-controls.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import {
+  getControlTooltip,
+  isControlActive,
+  readSelectOption,
+  readToggleOption,
+} from "./option-controls";
+
+const speed: AgentOptionControl = {
+  type: "select",
+  key: "service_tier",
+  label: "Speed",
+  defaultValue: "default",
+  choices: [
+    { value: "default", label: "Normal" },
+    { value: "priority", label: "Fast" },
+  ],
+};
+const fast: AgentOptionControl = { type: "toggle", key: "fast_mode", label: "Fast" };
+
+describe("option controls", () => {
+  it("reads a select from options and falls back to the control's default", () => {
+    if (speed.type !== "select") throw new Error("select expected");
+    expect(readSelectOption(speed, { service_tier: "priority" })).toBe("priority");
+    expect(readSelectOption(speed, {})).toBe("default");
+    expect(readSelectOption(speed, { service_tier: "unknown-tier" })).toBe("default");
+  });
+
+  it("reads a toggle from options and is off when unset", () => {
+    if (fast.type !== "toggle") throw new Error("toggle expected");
+    expect(readToggleOption(fast, { fast_mode: true })).toBe(true);
+    expect(readToggleOption(fast, {})).toBe(false);
+  });
+
+  it("is active when the option differs from the control's default", () => {
+    expect(isControlActive(speed, { service_tier: "priority" })).toBe(true);
+    expect(isControlActive(speed, { service_tier: "default" })).toBe(false);
+    expect(isControlActive(speed, {})).toBe(false);
+    expect(isControlActive(fast, { fast_mode: true })).toBe(true);
+    expect(isControlActive(fast, {})).toBe(false);
+  });
+
+  it("prefers a control's tooltip over its label", () => {
+    expect(getControlTooltip({ label: "Plan", tooltip: "Toggle plan mode" })).toBe(
+      "Toggle plan mode",
+    );
+    expect(getControlTooltip({ label: "Custom" })).toBe("Custom");
+  });
+});
diff --git a/packages/app/src/agent-controls/option-controls.ts b/packages/app/src/agent-controls/option-controls.ts
new file mode 100644
index 0000000000..ae513de23d
--- /dev/null
+++ b/packages/app/src/agent-controls/option-controls.ts
@@ -0,0 +1,47 @@
+import type {
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  AgentOptionToggleControl,
+  ProviderOptions,
+} from "@getpaseo/protocol/agent-types";
+
+/**
+ * The composer's option controls. A control only describes how to draw one option key; the
+ * value is read from `options`, which the daemon resolved (defaults, aliases, what runs).
+ */
+export interface ComposerOptionControls {
+  controls: AgentOptionControl[];
+  options: ProviderOptions;
+  onSetOption: (key: string, value: unknown) => void;
+}
+
+export function readToggleOption(
+  control: AgentOptionToggleControl,
+  options: ProviderOptions,
+): boolean {
+  const value = options[control.key];
+  return typeof value === "boolean" ? value : (control.defaultValue ?? false);
+}
+
+/** The selected choice's value, or the control's default when the option names no choice. */
+export function readSelectOption(
+  control: AgentOptionSelectControl,
+  options: ProviderOptions,
+): string | null {
+  const value = options[control.key];
+  if (typeof value === "string" && control.choices.some((choice) => choice.value === value)) {
+    return value;
+  }
+  return control.defaultValue ?? null;
+}
+
+/** Whether the option is set to something other than the control's default. */
+export function isControlActive(control: AgentOptionControl, options: ProviderOptions): boolean {
+  if (control.type === "toggle") return readToggleOption(control, options);
+  const value = readSelectOption(control, options);
+  return value !== null && value !== control.defaultValue;
+}
+
+export function getControlTooltip(control: Pick<AgentOptionControl, "label" | "tooltip">): string {
+  return control.tooltip ?? control.label;
+}
diff --git a/packages/app/src/agent-presentation/index.ts b/packages/app/src/agent-presentation/index.ts
index f3c3f139f7..0afb1426d4 100644
--- a/packages/app/src/agent-presentation/index.ts
+++ b/packages/app/src/agent-presentation/index.ts
@@ -1,4 +1,6 @@
 import { useShallow } from "zustand/shallow";
+import { useTranslation } from "react-i18next";
+import { i18n } from "@/i18n/i18next";
 import { useProviderIcon } from "@/components/provider-icons";
 import type { PanelDescriptor } from "@/panels/panel-registry";
 import { useSessionStore, selectAgentTurnPresentation, type Agent } from "@/stores/session-store";
@@ -33,6 +35,7 @@ export function useAgentDescriptor(
   target: { kind: "agent"; agentId: string },
   context: { serverId: string },
 ): PanelDescriptor {
+  useTranslation();
   const descriptorState = useSessionStore(
     useShallow((state) => {
       const session = state.sessions[context.serverId];
@@ -42,6 +45,7 @@ export function useAgentDescriptor(
         provider: agent?.provider ?? "codex",
         title: agent?.title ?? null,
         status: agent?.status ?? null,
+        backgroundWork: agent?.backgroundWork,
         pendingPermissionCount: agent?.pendingPermissions.length ?? 0,
         requiresAttention: agent?.requiresAttention ?? false,
         attentionReason: agent?.attentionReason ?? null,
@@ -57,6 +61,7 @@ export function buildAgentDescriptor(input: {
   provider: Agent["provider"];
   title: string | null;
   status: Agent["status"] | null;
+  backgroundWork?: Agent["backgroundWork"];
   pendingPermissionCount: number;
   requiresAttention: boolean;
   attentionReason: Agent["attentionReason"];
@@ -65,20 +70,25 @@ export function buildAgentDescriptor(input: {
 }): PanelDescriptor {
   const provider = input.provider;
   const label = resolveAgentLabel(input.title);
+  const statusBucket = input.status
+    ? deriveSidebarStateBucket({
+        status: input.isTurnActive ? "running" : input.status,
+        backgroundWork: input.backgroundWork,
+        pendingPermissionCount: input.pendingPermissionCount,
+        requiresAttention: input.requiresAttention,
+        attentionReason: input.attentionReason,
+      })
+    : null;
 
   return {
     label: label ?? "",
-    subtitle: `${formatProviderLabel(provider)} agent`,
+    subtitle:
+      statusBucket === "running" && !input.isTurnActive && input.status !== "running"
+        ? i18n.t("message.backgroundWork.running")
+        : `${formatProviderLabel(provider)} agent`,
     tooltip: label ?? `${formatProviderLabel(provider)} agent`,
     titleState: label ? "ready" : "loading",
     icon: input.icon,
-    statusBucket: input.status
-      ? deriveSidebarStateBucket({
-          status: input.isTurnActive ? "running" : input.status,
-          pendingPermissionCount: input.pendingPermissionCount,
-          requiresAttention: input.requiresAttention,
-          attentionReason: input.attentionReason,
-        })
-      : null,
+    statusBucket,
   };
 }
diff --git a/packages/app/src/agent-profiles/internal/materialize-profile.test.ts b/packages/app/src/agent-profiles/internal/materialize-profile.test.ts
index dd60b6680f..507ea84e12 100644
--- a/packages/app/src/agent-profiles/internal/materialize-profile.test.ts
+++ b/packages/app/src/agent-profiles/internal/materialize-profile.test.ts
@@ -23,7 +23,7 @@ describe("materializeAgentProfile", () => {
           model: "claude-opus-5",
           modeId: "plan",
           thinkingOptionId: "think-hard",
-          featureValues: { web_search: true },
+          options: { web_search: true },
         }),
       ),
     ).toEqual({
@@ -31,7 +31,7 @@ describe("materializeAgentProfile", () => {
       modelId: "claude-opus-5",
       modeId: "plan",
       thinkingOptionId: "think-hard",
-      featureValues: { web_search: true },
+      options: { web_search: true },
     });
   });
 
@@ -41,7 +41,7 @@ describe("materializeAgentProfile", () => {
       modelId: "",
       modeId: "",
       thinkingOptionId: "",
-      featureValues: {},
+      options: {},
     });
   });
 
@@ -61,7 +61,7 @@ describe("toAgentConfigApply", () => {
             model: "claude-opus-5",
             modeId: "plan",
             thinkingOptionId: "think-hard",
-            featureValues: { web_search: true },
+            options: { web_search: true },
           }),
         ),
       ),
@@ -69,7 +69,7 @@ describe("toAgentConfigApply", () => {
       modelId: "claude-opus-5",
       modeId: "plan",
       thinkingOptionId: "think-hard",
-      featureValues: { web_search: true },
+      options: { web_search: true },
     });
   });
 
@@ -81,8 +81,8 @@ describe("toAgentConfigApply", () => {
 
   it("omits an empty feature map so the agent keeps its own feature values", () => {
     expect(
-      toAgentConfigApply(materializeAgentProfile(profile({ featureValues: {} }))),
-    ).not.toHaveProperty("featureValues");
+      toAgentConfigApply(materializeAgentProfile(profile({ options: {} }))),
+    ).not.toHaveProperty("options");
   });
 
   it("never carries a provider, which a running agent cannot change", () => {
diff --git a/packages/app/src/agent-profiles/internal/materialize-profile.ts b/packages/app/src/agent-profiles/internal/materialize-profile.ts
index fc393f5ec2..e0e3df628c 100644
--- a/packages/app/src/agent-profiles/internal/materialize-profile.ts
+++ b/packages/app/src/agent-profiles/internal/materialize-profile.ts
@@ -12,7 +12,7 @@ export interface MaterializedAgentProfile {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  options: Record<string, unknown>;
 }
 
 function trimmed(value: string | undefined): string {
@@ -25,7 +25,7 @@ export function materializeAgentProfile(profile: AgentProfile): MaterializedAgen
     modelId: trimmed(profile.model),
     modeId: trimmed(profile.modeId),
     thinkingOptionId: trimmed(profile.thinkingOptionId),
-    featureValues: profile.featureValues ?? {},
+    options: profile.options ?? {},
   };
 }
 
@@ -52,8 +52,6 @@ export function toAgentConfigApply(profile: MaterializedAgentProfile): AgentConf
     ...(profile.modelId ? { modelId: profile.modelId } : {}),
     ...(profile.modeId ? { modeId: profile.modeId } : {}),
     ...(profile.thinkingOptionId ? { thinkingOptionId: profile.thinkingOptionId } : {}),
-    ...(Object.keys(profile.featureValues).length > 0
-      ? { featureValues: profile.featureValues }
-      : {}),
+    ...(Object.keys(profile.options).length > 0 ? { options: profile.options } : {}),
   };
 }
diff --git a/packages/app/src/agent-profiles/internal/profile-form-model.test.ts b/packages/app/src/agent-profiles/internal/profile-form-model.test.ts
index 7689621830..4756bc127a 100644
--- a/packages/app/src/agent-profiles/internal/profile-form-model.test.ts
+++ b/packages/app/src/agent-profiles/internal/profile-form-model.test.ts
@@ -1,7 +1,7 @@
 import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
 import { describe, expect, it } from "vitest";
 import {
-  buildFeatureRequestKey,
+  buildControlsRequestKey,
   openAgentProfileForm,
   type AgentProfileFormModel,
 } from "./profile-form-model";
@@ -70,6 +70,21 @@ function optionValues(options: readonly { value: string }[]): string[] {
   return options.map((option) => option.value);
 }
 
+const FAST = {
+  controls: [{ type: "toggle" as const, key: "fast_mode", label: "Fast" }],
+  options: { fast_mode: false },
+};
+const NO_CONTROLS = { controls: [], options: {} };
+
+function toggledOnOpus(): AgentProfileFormModel {
+  const model = openWithCatalog({ mode: "create" });
+  model.setName("Fast");
+  selectClaude(model);
+  model.applyControls(model.getState().controlsRequestKey ?? "", FAST);
+  model.setOption("fast_mode", true);
+  return model;
+}
+
 describe("openAgentProfileForm", () => {
   it("starts a create form empty and cannot submit", () => {
     const model = openWithCatalog({ mode: "create" });
@@ -159,6 +174,7 @@ describe("openAgentProfileForm", () => {
       provider: "codex",
       model: "gpt-5.2-codex",
       modeId: "read-only",
+      options: {},
     });
   });
 
@@ -173,7 +189,7 @@ describe("openAgentProfileForm", () => {
         model: "claude-opus-5",
         modeId: "plan",
         thinkingOptionId: "think-hard",
-        featureValues: { webSearch: true },
+        options: { webSearch: true },
         notes: "Visual work only.",
       },
     });
@@ -229,10 +245,11 @@ describe("openAgentProfileForm", () => {
       selectClaude(model);
       model.setModel("claude-opus-5", { label: "Opus 5" });
       model.setThinking("think-hard", { label: "Think hard" });
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
-      model.setFeatureValue("webSearch", true);
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
+        options: { webSearch: false },
+      });
+      model.setOption("webSearch", true);
 
       model.setProvider("codex", { label: "Codex" });
       const state = model.getState();
@@ -242,8 +259,9 @@ describe("openAgentProfileForm", () => {
       expect(state.modelDisplay).toEqual({ label: "GPT-5.2 Codex" });
       expect(state.thinkingOptionId).toBe("");
       expect(state.thinkingDisplay).toBeNull();
-      expect(state.featureValues).toEqual({});
-      expect(state.features).toEqual([]);
+      expect(state.options).toEqual({});
+      expect(state.optionEdits).toEqual({});
+      expect(state.controls).toEqual([]);
       expect(state.name).toBe("Test writer");
     });
 
@@ -334,23 +352,28 @@ describe("openAgentProfileForm", () => {
     });
   });
 
-  describe("features", () => {
-    it("asks for features per provider/model/mode/thinking combination", () => {
+  const WEB_SEARCH_CONTROLS = {
+    controls: [{ type: "toggle" as const, key: "webSearch", label: "Web search" }],
+    options: { webSearch: false },
+  };
+
+  describe("controls", () => {
+    it("asks for controls per provider/model/mode/thinking combination", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
 
-      expect(model.getState().featureRequest).toEqual({
+      expect(model.getState().controlsRequest).toEqual({
         provider: "claude",
         model: "claude-opus-5",
         modeId: "plan",
         thinkingOptionId: "think",
       });
-      const firstKey = model.getState().featureRequestKey;
+      const firstKey = model.getState().controlsRequestKey;
 
       model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
 
-      expect(model.getState().featureRequestKey).not.toBe(firstKey);
-      expect(model.getState().featureRequest).toEqual({
+      expect(model.getState().controlsRequestKey).not.toBe(firstKey);
+      expect(model.getState().controlsRequest).toEqual({
         provider: "claude",
         model: "claude-haiku-4-5",
         modeId: "plan",
@@ -361,77 +384,235 @@ describe("openAgentProfileForm", () => {
     it("moves from pending to complete only for the current request", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
-      const key = model.getState().featureRequestKey ?? "";
-      expect(model.getState().featureResolution).toBe("pending");
+      const key = model.getState().controlsRequestKey ?? "";
+      expect(model.getState().controlsResolution).toBe("pending");
 
-      model.applyFeatures("stale-key", [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
-      expect(model.getState().featureResolution).toBe("pending");
-      expect(model.getState().features).toEqual([]);
+      model.applyControls("stale-key", {
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
+        options: { webSearch: false },
+      });
+      expect(model.getState().controlsResolution).toBe("pending");
+      expect(model.getState().controls).toEqual([]);
 
-      model.applyFeatures(key, [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
-      expect(model.getState().featureResolution).toBe("complete");
-      expect(model.getState().disclosure.showFeaturesField).toBe(true);
+      model.applyControls(key, {
+        controls: [{ type: "toggle", key: "webSearch", label: "Web search" }],
+        options: { webSearch: false },
+      });
+      expect(model.getState().controlsResolution).toBe("complete");
+      expect(model.getState().disclosure.showControlsField).toBe(true);
     });
 
-    it("reflects a set feature value back into the rendered feature", () => {
+    it("reflects a set option back into the rendered controls", () => {
+      const model = openWithCatalog({ mode: "create" });
+      model.setName("Searcher");
+      selectClaude(model);
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
+
+      model.setOption("webSearch", true);
+
+      expect(model.getState().controls[0]).toMatchObject({ key: "webSearch" });
+      expect(model.getState().controlOptions).toEqual({ webSearch: true });
+      expect(model.getState().submitValue?.options).toEqual({ webSearch: true });
+    });
+
+    it("keeps stored options while the controls are still pending", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: { id: "p1", name: "UI work", provider: "claude", options: { webSearch: true } },
+      });
+      model.applyProviderCatalog(ENTRIES);
+
+      expect(model.getState().controlsResolution).toBe("pending");
+      expect(model.getState().submitValue?.options).toEqual({ webSearch: true });
+    });
+
+    it("keeps options no control draws, so editing a profile does not drop them", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: {
+          id: "p1",
+          name: "UI work",
+          provider: "claude",
+          options: { webSearch: true, sandbox_mode: "read-only" },
+        },
+      });
+      model.applyProviderCatalog(ENTRIES);
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
+      model.setOption("webSearch", false);
+
+      expect(model.getState().submitValue?.options).toEqual({
+        webSearch: false,
+        sandbox_mode: "read-only",
+      });
+    });
+
+    it("draws the options the daemon resolved from the stored ones, then the edits", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: { id: "p1", name: "Fast", provider: "codex", options: { service_tier: "fast" } },
+      });
+      model.applyProviderCatalog(ENTRIES);
+
+      // The request carries the stored options so the daemon can resolve the legacy tier.
+      expect(model.getState().controlsRequest?.providerOptions).toEqual({ service_tier: "fast" });
+
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
+        controls: [
+          {
+            type: "select",
+            key: "service_tier",
+            label: "Speed",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Standard" },
+              { value: "priority", label: "Fast" },
+            ],
+          },
+        ],
+        options: { service_tier: "priority" },
+      });
+
+      expect(model.getState().controlOptions).toEqual({ service_tier: "priority" });
+      // Nothing was edited, so the stored value is saved as it was.
+      expect(model.getState().submitValue?.options).toEqual({ service_tier: "fast" });
+    });
+
+    it("sends an edit to the daemon with the stored options, and draws the answer", () => {
+      const model = openAgentProfileForm({
+        mode: "edit",
+        profile: {
+          id: "p1",
+          name: "Fast",
+          provider: "codex",
+          options: { service_tier: "fast", sandbox_mode: "read-only" },
+        },
+      });
+      model.applyProviderCatalog(ENTRIES);
+      const speed = {
+        controls: [
+          {
+            type: "select" as const,
+            key: "service_tier",
+            label: "Speed",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Standard" },
+              { value: "priority", label: "Fast" },
+            ],
+          },
+        ],
+        options: { service_tier: "priority", sandbox_mode: "read-only" },
+      };
+      model.applyControls(model.getState().controlsRequestKey ?? "", speed);
+
+      model.setOption("service_tier", "default");
+
+      // The controls stay up while the daemon answers, with the toggle laid over the last answer.
+      expect(model.getState().controls).toHaveLength(1);
+      expect(model.getState().controlOptions).toMatchObject({ service_tier: "default" });
+      // The request carries everything the profile would save, so the daemon resolves it.
+      expect(model.getState().controlsRequest?.providerOptions).toEqual({
+        service_tier: "default",
+        sandbox_mode: "read-only",
+      });
+      expect(model.getState().controlsResolution).toBe("pending");
+
+      model.applyControls(model.getState().controlsRequestKey ?? "", {
+        ...speed,
+        options: { service_tier: "default", sandbox_mode: "read-only" },
+      });
+      expect(model.getState().controlsResolution).toBe("complete");
+      expect(model.getState().controlOptions).toEqual({
+        service_tier: "default",
+        sandbox_mode: "read-only",
+      });
+    });
+
+    it("draws no controls for the previous model while another model's answer is pending", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
+      model.applyControls(model.getState().controlsRequestKey ?? "", WEB_SEARCH_CONTROLS);
 
-      model.setFeatureValue("webSearch", true);
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
 
-      expect(model.getState().features[0]).toMatchObject({ id: "webSearch", value: true });
-      expect(model.getState().featureValues).toEqual({ webSearch: true });
+      expect(model.getState().controls).toEqual([]);
     });
 
-    it("keeps stored feature values while the feature list is still pending", () => {
+    it("does not save a toggle once the model that drew it is replaced by one without it", () => {
+      const model = toggledOnOpus();
+      expect(model.getState().submitValue?.options).toEqual({ fast_mode: true });
+
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
+      model.applyControls(model.getState().controlsRequestKey ?? "", NO_CONTROLS);
+
+      // Empty, not absent: the daemon reads a profile write without `options` as one from an
+      // app that predates them and keeps the stored options.
+      expect(model.getState().submitValue?.options).toEqual({});
+      expect(model.getState().controlsRequest?.providerOptions).toBeUndefined();
+    });
+
+    it("saves a toggle again when the model that draws it returns", () => {
+      const model = toggledOnOpus();
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
+      model.applyControls(model.getState().controlsRequestKey ?? "", NO_CONTROLS);
+
+      model.setModel("claude-opus-5", { label: "Opus 5" });
+      model.applyControls(model.getState().controlsRequestKey ?? "", FAST);
+
+      expect(model.getState().submitValue?.options).toEqual({ fast_mode: true });
+    });
+
+    it("does not save a stored toggle profile either", () => {
       const model = openAgentProfileForm({
         mode: "edit",
         profile: {
           id: "p1",
-          name: "UI work",
+          name: "Fast",
           provider: "claude",
-          featureValues: { webSearch: true },
+          model: "claude-opus-5",
+          options: { fast_mode: true },
         },
       });
       model.applyProviderCatalog(ENTRIES);
+      model.applyControls(model.getState().controlsRequestKey ?? "", FAST);
 
-      expect(model.getState().featureResolution).toBe("pending");
-      expect(model.getState().submitValue?.featureValues).toEqual({ webSearch: true });
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
+      model.applyControls(model.getState().controlsRequestKey ?? "", NO_CONTROLS);
+
+      expect(model.getState().submitValue?.options).toEqual({});
     });
 
-    it("prunes stored values the provider no longer reports", () => {
-      const model = openAgentProfileForm({
-        mode: "edit",
-        profile: {
-          id: "p1",
-          name: "UI work",
-          provider: "claude",
-          featureValues: { webSearch: true, retiredFlag: true },
-        },
-      });
-      model.applyProviderCatalog(ENTRIES);
-      model.applyFeatures(model.getState().featureRequestKey ?? "", [
-        { type: "toggle", id: "webSearch", label: "Web search", value: false },
-      ]);
+    it("never drops an option no control has drawn", () => {
+      const model = openWithCatalog({ mode: "create" });
+      model.setName("Fast");
+      selectClaude(model);
+      model.applyControls(model.getState().controlsRequestKey ?? "", FAST);
+      model.setOption("token_budget", 8000);
+      model.setOption("fast_mode", true);
 
-      expect(model.getState().featureValues).toEqual({ webSearch: true });
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
+      model.applyControls(model.getState().controlsRequestKey ?? "", NO_CONTROLS);
+
+      expect(model.getState().submitValue?.options).toEqual({ token_budget: 8000 });
+    });
+
+    it("keeps a toggle when the daemon cannot list controls", () => {
+      const model = toggledOnOpus();
+
+      model.setModel("claude-haiku-4-5", { label: "Haiku 4.5" });
+      model.applyControlsUnavailable(model.getState().controlsRequestKey ?? "");
+
+      expect(model.getState().submitValue?.options).toEqual({ fast_mode: true });
     });
 
     it("resolves an unavailable feature listing without showing the field", () => {
       const model = openWithCatalog({ mode: "create" });
       selectClaude(model);
 
-      model.applyFeaturesUnavailable(model.getState().featureRequestKey ?? "");
+      model.applyControlsUnavailable(model.getState().controlsRequestKey ?? "");
 
-      expect(model.getState().featureResolution).toBe("complete");
-      expect(model.getState().disclosure.showFeaturesField).toBe(false);
+      expect(model.getState().controlsResolution).toBe("complete");
+      expect(model.getState().disclosure.showControlsField).toBe(false);
     });
   });
 
@@ -464,15 +645,15 @@ describe("openAgentProfileForm", () => {
   });
 });
 
-describe("buildFeatureRequestKey", () => {
+describe("buildControlsRequestKey", () => {
   it("is null without a provider", () => {
-    expect(buildFeatureRequestKey(null)).toBeNull();
+    expect(buildControlsRequestKey(null)).toBeNull();
   });
 
   it("separates the fields so a value cannot bleed across positions", () => {
-    expect(buildFeatureRequestKey({ provider: "claude", model: "a|b" })).toBe("claude|a|b||");
-    expect(buildFeatureRequestKey({ provider: "claude", modeId: "a" })).not.toBe(
-      buildFeatureRequestKey({ provider: "claude", model: "a" }),
+    expect(buildControlsRequestKey({ provider: "claude", model: "a|b" })).toBe("claude|a|b||");
+    expect(buildControlsRequestKey({ provider: "claude", modeId: "a" })).not.toBe(
+      buildControlsRequestKey({ provider: "claude", model: "a" }),
     );
   });
 });
diff --git a/packages/app/src/agent-profiles/internal/profile-form-model.ts b/packages/app/src/agent-profiles/internal/profile-form-model.ts
index 2ab6185054..37756376bd 100644
--- a/packages/app/src/agent-profiles/internal/profile-form-model.ts
+++ b/packages/app/src/agent-profiles/internal/profile-form-model.ts
@@ -1,13 +1,14 @@
 import type {
-  AgentFeature,
+  AgentOptionControl,
+  ProviderOptions,
   AgentMode,
   AgentModelDefinition,
   AgentSelectOption,
   ProviderSnapshotEntry,
 } from "@getpaseo/protocol/agent-types";
 import type { AgentProfile } from "@getpaseo/protocol/messages";
+import { withoutLostControls } from "@/agent-controls/lost-controls";
 import { formatAgentModeLabel, formatThinkingOptionLabel } from "@/agent-controls/labels";
-import { applyFeatureValues, pruneFeatureValues } from "@/hooks/feature-preferences";
 import { filterSelectableModels } from "@/provider-selection/model-catalog";
 
 /**
@@ -57,11 +58,15 @@ export interface AgentProfileFormSnapshot {
 }
 
 /**
- * The inputs a feature listing needs. Features are provider-scoped and change
- * with model/mode/thinking, so every one of those is part of the request.
+ * The inputs a controls listing needs. Controls are provider-scoped and change
+ * with model/mode/thinking, so every one of those is part of the request. The
+ * profile's own options ride along so the daemon can resolve them (a legacy
+ * `service_tier: "fast"` is drawn as the model's Fast tier); they are the same
+ * for the life of one provider, so they are not part of the key.
  */
-export interface AgentProfileFeatureRequest {
+export interface AgentProfileControlsRequest {
   provider: string;
+  providerOptions?: ProviderOptions;
   model?: string;
   modeId?: string;
   thinkingOptionId?: string;
@@ -73,7 +78,7 @@ export interface AgentProfileFormDisclosure {
   showModelField: boolean;
   showModeField: boolean;
   showThinkingField: boolean;
-  showFeaturesField: boolean;
+  showControlsField: boolean;
 }
 
 export interface AgentProfileFormState {
@@ -86,13 +91,22 @@ export interface AgentProfileFormState {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  /** The options the profile was opened with, including ones no control draws. */
+  options: ProviderOptions;
+  /** Changes made in this form, over `options`. */
+  optionEdits: ProviderOptions;
 
   providerOptions: AgentProfileFormOption[];
   modelOptions: AgentProfileFormOption[];
   modeOptions: AgentProfileFormOption[];
   thinkingOptions: AgentProfileFormOption[];
-  features: AgentFeature[];
+  controls: AgentOptionControl[];
+  /** What the controls show: the options the daemon resolved from `options`, then the edits. */
+  controlOptions: ProviderOptions;
+  /** Every key an answer for this provider has drawn as a control. */
+  drawnControlKeys: ReadonlySet<string>;
+  /** The keys the latest answer draws as controls. */
+  answeredControlKeys: ReadonlySet<string>;
 
   providerDisplay: AgentProfileFormDisplay | null;
   modelDisplay: AgentProfileFormDisplay | null;
@@ -100,9 +114,9 @@ export interface AgentProfileFormState {
   thinkingDisplay: AgentProfileFormDisplay | null;
 
   catalogResolution: AgentProfileResolutionStatus;
-  featureResolution: AgentProfileResolutionStatus;
-  featureRequest: AgentProfileFeatureRequest | null;
-  featureRequestKey: string | null;
+  controlsResolution: AgentProfileResolutionStatus;
+  controlsRequest: AgentProfileControlsRequest | null;
+  controlsRequestKey: string | null;
 
   disclosure: AgentProfileFormDisclosure;
   isSubmitting: boolean;
@@ -118,9 +132,12 @@ export interface AgentProfileFormModel {
   /** Late input: the host-scoped provider catalog. Never touches selections. */
   applyProviderCatalog: (entries: readonly ProviderSnapshotEntry[]) => void;
   /** Late input: the feature list for one request. Stale keys are ignored. */
-  applyFeatures: (requestKey: string, features: readonly AgentFeature[]) => void;
+  applyControls: (
+    requestKey: string,
+    resolved: { controls: readonly AgentOptionControl[]; options: ProviderOptions },
+  ) => void;
   /** Resolve a request that produced no usable features (provider error). */
-  applyFeaturesUnavailable: (requestKey: string) => void;
+  applyControlsUnavailable: (requestKey: string) => void;
   setName: (value: string) => void;
   setAppearance: (value: { icon: string; color: string }) => void;
   setNotes: (value: string) => void;
@@ -128,7 +145,7 @@ export interface AgentProfileFormModel {
   setModel: (modelId: string, display: AgentProfileFormDisplay | null) => void;
   setMode: (modeId: string, display: AgentProfileFormDisplay | null) => void;
   setThinking: (thinkingOptionId: string, display: AgentProfileFormDisplay | null) => void;
-  setFeatureValue: (featureId: string, value: unknown) => void;
+  setOption: (key: string, value: unknown) => void;
   setSubmitting: (value: boolean) => void;
   setSubmitError: (value: string | null) => void;
 }
@@ -312,19 +329,39 @@ function refineDisplay(
   return current ?? { label: selectedId };
 }
 
-function buildFeatureRequest(state: AgentProfileFormState): AgentProfileFeatureRequest | null {
+function buildControlsRequest(state: AgentProfileFormState): AgentProfileControlsRequest | null {
   if (!state.provider) {
     return null;
   }
+  const ownOptions = ownOptionsOf(state);
   return {
     provider: state.provider,
     ...(state.modelId ? { model: state.modelId } : {}),
     ...(state.modeId ? { modeId: state.modeId } : {}),
     ...(state.thinkingOptionId ? { thinkingOptionId: state.thinkingOptionId } : {}),
+    ...(Object.keys(ownOptions).length > 0 ? { providerOptions: ownOptions } : {}),
   };
 }
 
-export function buildFeatureRequestKey(request: AgentProfileFeatureRequest | null): string | null {
+/**
+ * Everything the profile would save as its options; the daemon resolves them for the form. A
+ * toggle the model in use does not draw is not saved (see `withoutLostControls`).
+ */
+function ownOptionsOf(
+  state: Pick<
+    AgentProfileFormState,
+    "options" | "optionEdits" | "drawnControlKeys" | "answeredControlKeys"
+  >,
+): ProviderOptions {
+  return withoutLostControls(
+    { ...state.options, ...state.optionEdits },
+    state.drawnControlKeys,
+    state.answeredControlKeys,
+  );
+}
+
+/** The part of a request that decides which controls exist; options only change their values. */
+function buildControlsScopeKey(request: AgentProfileControlsRequest | null): string | null {
   if (!request) {
     return null;
   }
@@ -336,6 +373,18 @@ export function buildFeatureRequestKey(request: AgentProfileFeatureRequest | nul
   ].join("|");
 }
 
+export function buildControlsRequestKey(
+  request: AgentProfileControlsRequest | null,
+): string | null {
+  if (!request) {
+    return null;
+  }
+  const scope = buildControlsScopeKey(request);
+  return request.providerOptions
+    ? `${scope}|${JSON.stringify(Object.entries(request.providerOptions).sort(([a], [b]) => a.localeCompare(b)))}`
+    : scope;
+}
+
 function buildSubmitValue(state: AgentProfileFormState): AgentProfileValue | null {
   const name = state.name.trim();
   const notes = state.notes.trim();
@@ -350,16 +399,18 @@ function buildSubmitValue(state: AgentProfileFormState): AgentProfileValue | nul
     ...(state.modelId ? { model: state.modelId } : {}),
     ...(state.modeId ? { modeId: state.modeId } : {}),
     ...(state.thinkingOptionId ? { thinkingOptionId: state.thinkingOptionId } : {}),
-    ...(Object.keys(state.featureValues).length > 0 ? { featureValues: state.featureValues } : {}),
+    // Always sent, empty included: the daemon reads a write without `options` as one from an
+    // app that predates them and keeps the profile's stored options.
+    options: ownOptionsOf(state),
     ...(notes ? { notes } : {}),
   };
 }
 
-function resolveFeatureStatus(
-  featureRequestKey: string | null,
+function resolveControlsStatus(
+  controlsRequestKey: string | null,
   featuresAreCurrent: boolean,
 ): AgentProfileResolutionStatus {
-  if (featureRequestKey === null) {
+  if (controlsRequestKey === null) {
     return "idle";
   }
   return featuresAreCurrent ? "complete" : "pending";
@@ -392,25 +443,29 @@ function buildInitialState(snapshot: AgentProfileFormSnapshot): AgentProfileForm
     modelId,
     modeId: profile.modeId ?? "",
     thinkingOptionId: profile.thinkingOptionId ?? "",
-    featureValues: { ...profile.featureValues },
+    options: { ...profile.options },
+    optionEdits: {},
     providerOptions: [],
     modelOptions: [],
     modeOptions: [],
     thinkingOptions: [],
-    features: [],
+    controls: [],
+    controlOptions: {},
+    drawnControlKeys: new Set(),
+    answeredControlKeys: new Set(),
     providerDisplay: seedDisplay(provider),
     modelDisplay: seedDisplay(modelId),
     modeDisplay: seedDisplay(profile.modeId),
     thinkingDisplay: seedDisplay(profile.thinkingOptionId),
     catalogResolution: "idle",
-    featureResolution: "idle",
-    featureRequest: null,
-    featureRequestKey: null,
+    controlsResolution: "idle",
+    controlsRequest: null,
+    controlsRequestKey: null,
     disclosure: {
       showModelField: false,
       showModeField: false,
       showThinkingField: false,
-      showFeaturesField: false,
+      showControlsField: false,
     },
     isSubmitting: false,
     submitError: null,
@@ -422,28 +477,45 @@ function buildInitialState(snapshot: AgentProfileFormSnapshot): AgentProfileForm
 export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentProfileFormModel {
   let entries: readonly ProviderSnapshotEntry[] = [];
   let catalogResolution: AgentProfileResolutionStatus = "idle";
-  let resolvedFeatureKey: string | null = null;
-  let resolvedFeatures: AgentFeature[] = [];
+  let resolvedControlsKey: string | null = null;
+  let resolvedScopeKey: string | null = null;
+  let resolvedControls: AgentOptionControl[] = [];
+  let resolvedOptions: ProviderOptions = {};
+  let drawnKeys: ReadonlySet<string> = new Set();
+  let answeredKeys: ReadonlySet<string> = new Set();
   let listeners = new Set<() => void>();
   let closed = false;
 
   function derive(incoming: AgentProfileFormState): AgentProfileFormState {
     const models = resolveModels(entries, incoming.provider);
     const modes = resolveModes(entries, incoming.provider);
-    const next = seedSelections(incoming, {
-      entry: findEntry(entries, incoming.provider),
-      models,
-      modes,
-    });
+    const next: AgentProfileFormState = {
+      ...seedSelections(incoming, {
+        entry: findEntry(entries, incoming.provider),
+        models,
+        modes,
+      }),
+      drawnControlKeys: drawnKeys,
+      answeredControlKeys: answeredKeys,
+    };
     const thinking = resolveThinkingOptions(entries, next.provider, next.modelId);
-    const featureRequest = buildFeatureRequest(next);
-    const featureRequestKey = buildFeatureRequestKey(featureRequest);
+    const controlsRequest = buildControlsRequest(next);
+    const controlsRequestKey = buildControlsRequestKey(controlsRequest);
+    const controlsScopeKey = buildControlsScopeKey(controlsRequest);
     const featuresAreCurrent =
-      featureRequestKey !== null && featureRequestKey === resolvedFeatureKey;
-    const features = featuresAreCurrent
-      ? applyFeatureValues(resolvedFeatures, next.featureValues)
-      : [];
-    const featureResolution = resolveFeatureStatus(featureRequestKey, featuresAreCurrent);
+      controlsRequestKey !== null && controlsRequestKey === resolvedControlsKey;
+    // A toggle changes only the options, so the controls stay up while the daemon answers and the
+    // toggle shows over the last answer. A change of provider, model, mode or thinking draws none
+    // until its own answer arrives.
+    const controlsApply = controlsScopeKey !== null && controlsScopeKey === resolvedScopeKey;
+    const controls = controlsApply ? resolvedControls : [];
+    let controlOptions: ProviderOptions = next.options;
+    if (controlsApply) {
+      controlOptions = featuresAreCurrent
+        ? resolvedOptions
+        : { ...resolvedOptions, ...next.optionEdits };
+    }
+    const controlsResolution = resolveControlsStatus(controlsRequestKey, featuresAreCurrent);
 
     const withOptions: AgentProfileFormState = {
       ...next,
@@ -451,7 +523,8 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       modelOptions: buildModelOptions(models),
       modeOptions: buildModeOptions(modes),
       thinkingOptions: buildThinkingOptions(thinking),
-      features,
+      controls,
+      controlOptions,
       providerDisplay: refineDisplay(
         next.providerDisplay,
         next.provider,
@@ -479,9 +552,9 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
         })(),
       ),
       catalogResolution,
-      featureResolution,
-      featureRequest,
-      featureRequestKey,
+      controlsResolution,
+      controlsRequest,
+      controlsRequestKey,
     };
 
     // A field appears once the catalog can populate it, and stays visible while
@@ -492,7 +565,7 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       showModeField: hasProvider && (modes.length > 0 || Boolean(withOptions.modeId)),
       showThinkingField:
         hasProvider && (thinking.length > 0 || Boolean(withOptions.thinkingOptionId)),
-      showFeaturesField: hasProvider && features.length > 0,
+      showControlsField: hasProvider && controls.length > 0,
     };
     const canSubmit =
       withOptions.name.trim().length > 0 &&
@@ -531,23 +604,26 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       catalogResolution = "complete";
       publish((current) => current);
     },
-    applyFeatures: (requestKey, features) => {
-      if (requestKey !== state.featureRequestKey) {
+    applyControls: (requestKey, resolved) => {
+      if (requestKey !== state.controlsRequestKey) {
         return;
       }
-      resolvedFeatureKey = requestKey;
-      resolvedFeatures = [...features];
-      publish((current) => ({
-        ...current,
-        featureValues: pruneFeatureValues(current.featureValues, resolvedFeatures),
-      }));
+      resolvedControlsKey = requestKey;
+      resolvedScopeKey = buildControlsScopeKey(state.controlsRequest);
+      resolvedControls = [...resolved.controls];
+      resolvedOptions = resolved.options;
+      answeredKeys = new Set(resolved.controls.map((control) => control.key));
+      drawnKeys = new Set([...drawnKeys, ...answeredKeys]);
+      publish((current) => current);
     },
-    applyFeaturesUnavailable: (requestKey) => {
-      if (requestKey !== state.featureRequestKey) {
+    applyControlsUnavailable: (requestKey) => {
+      if (requestKey !== state.controlsRequestKey) {
         return;
       }
-      resolvedFeatureKey = requestKey;
-      resolvedFeatures = [];
+      resolvedControlsKey = requestKey;
+      resolvedScopeKey = buildControlsScopeKey(state.controlsRequest);
+      resolvedControls = [];
+      resolvedOptions = {};
       publish((current) => current);
     },
     setName: (value) => publish((current) => ({ ...current, name: value })),
@@ -562,6 +638,8 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
         // Everything below the provider is provider-scoped: a model id, mode id,
         // thinking id or feature id from the old provider means nothing here.
         // Clearing them is enough — `derive` seeds the new provider's defaults.
+        drawnKeys = new Set();
+        answeredKeys = new Set();
         return {
           ...current,
           provider: providerId,
@@ -572,7 +650,8 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
           modeDisplay: null,
           thinkingOptionId: "",
           thinkingDisplay: null,
-          featureValues: {},
+          options: {},
+          optionEdits: {},
         };
       }),
     setModel: (modelId, display) =>
@@ -598,10 +677,10 @@ export function openAgentProfileForm(snapshot: AgentProfileFormSnapshot): AgentP
       publish((current) => ({ ...current, modeId, modeDisplay: display })),
     setThinking: (thinkingOptionId, display) =>
       publish((current) => ({ ...current, thinkingOptionId, thinkingDisplay: display })),
-    setFeatureValue: (featureId, value) =>
+    setOption: (key, value) =>
       publish((current) => ({
         ...current,
-        featureValues: { ...current.featureValues, [featureId]: value },
+        optionEdits: { ...current.optionEdits, [key]: value },
       })),
     setSubmitting: (value) => publish((current) => ({ ...current, isSubmitting: value })),
     setSubmitError: (value) => publish((current) => ({ ...current, submitError: value })),
diff --git a/packages/app/src/agent-profiles/internal/profile-summary.ts b/packages/app/src/agent-profiles/internal/profile-summary.ts
index a0507e6b94..28431b093c 100644
--- a/packages/app/src/agent-profiles/internal/profile-summary.ts
+++ b/packages/app/src/agent-profiles/internal/profile-summary.ts
@@ -47,7 +47,7 @@ export function buildAgentProfileTags(input: {
     tags.push({ id: "thinking", label: formatThinkingOptionLabel({ id: thinkingOptionId }) });
   }
 
-  const featureCount = Object.keys(input.profile.featureValues ?? {}).length;
+  const featureCount = Object.keys(input.profile.options ?? {}).length;
   if (featureCount > 0) {
     tags.push({ id: "features", label: input.formatFeatureCount(featureCount) });
   }
diff --git a/packages/app/src/agent-profiles/internal/use-agent-profile-picker.ts b/packages/app/src/agent-profiles/internal/use-agent-profile-picker.ts
index c4b97ec229..589d4d0b29 100644
--- a/packages/app/src/agent-profiles/internal/use-agent-profile-picker.ts
+++ b/packages/app/src/agent-profiles/internal/use-agent-profile-picker.ts
@@ -117,9 +117,7 @@ export function useAgentProfilePicker(
           modelId: resolved.modelId,
           modeId: resolved.modeId,
           thinkingOptionId: resolved.thinkingOptionId,
-          ...(Object.keys(resolved.featureValues).length > 0
-            ? { featureValues: resolved.featureValues }
-            : {}),
+          ...(Object.keys(resolved.options).length > 0 ? { options: resolved.options } : {}),
         }),
       ).catch((error) => {
         console.warn("[useAgentProfilePicker] persist profile selection failed", error);
diff --git a/packages/app/src/agent-profiles/internal/use-profile-form-inputs.ts b/packages/app/src/agent-profiles/internal/use-profile-form-inputs.ts
index fb78320ca1..d7cfb2b6e6 100644
--- a/packages/app/src/agent-profiles/internal/use-profile-form-inputs.ts
+++ b/packages/app/src/agent-profiles/internal/use-profile-form-inputs.ts
@@ -27,7 +27,7 @@ export function useAgentProfileFormCatalog(input: {
   }, [entries, input.model]);
 }
 
-export function useAgentProfileFormFeatures(input: {
+export function useAgentProfileFormControls(input: {
   serverId: string;
   model: AgentProfileFormModel;
   state: AgentProfileFormState;
@@ -35,14 +35,14 @@ export function useAgentProfileFormFeatures(input: {
   const { t } = useTranslation();
   const client = useHostRuntimeClient(input.serverId);
   const isConnected = useHostRuntimeIsConnected(input.serverId);
-  const request = input.state.featureRequest;
-  const requestKey = input.state.featureRequestKey;
+  const request = input.state.controlsRequest;
+  const requestKey = input.state.controlsRequestKey;
 
   // `dataShape: "value"` and not `"list"`: a list shape keeps the previous
   // page's data while the next request is in flight, which would hand the
   // features of one provider/model combination to the key of another.
-  const featuresQuery = useFetchQuery({
-    queryKey: ["agentProfileFeatures", input.serverId, requestKey],
+  const controlsQuery = useFetchQuery({
+    queryKey: ["agentProfileControls", input.serverId, requestKey],
     dataShape: "value",
     staleTimeMs: 5 * 60 * 1000,
     enabled: Boolean(client && isConnected && request),
@@ -51,28 +51,28 @@ export function useAgentProfileFormFeatures(input: {
       if (!client || !request) {
         throw new Error(t("workspace.terminal.hostDisconnected"));
       }
-      const payload = await client.listProviderFeatures({ ...request, cwd: HOME_SCOPE_CWD });
+      const payload = await client.listProviderControls({ ...request, cwd: HOME_SCOPE_CWD });
       if (payload.error) {
         throw new Error(payload.error);
       }
-      return payload.features ?? [];
+      return { controls: payload.controls ?? [], options: payload.options ?? {} };
     },
   });
 
-  const { data, isError } = featuresQuery;
+  const { data, isError } = controlsQuery;
   const { model } = input;
 
   useEffect(() => {
     if (!requestKey || !data) {
       return;
     }
-    model.applyFeatures(requestKey, data);
+    model.applyControls(requestKey, data);
   }, [data, model, requestKey]);
 
   useEffect(() => {
     if (!requestKey || !isError) {
       return;
     }
-    model.applyFeaturesUnavailable(requestKey);
+    model.applyControlsUnavailable(requestKey);
   }, [isError, model, requestKey]);
 }
diff --git a/packages/app/src/agent-profiles/settings/agent-profile-appearance-field.tsx b/packages/app/src/agent-profiles/settings/agent-profile-appearance-field.tsx
index 9d958daffe..f9200b1565 100644
--- a/packages/app/src/agent-profiles/settings/agent-profile-appearance-field.tsx
+++ b/packages/app/src/agent-profiles/settings/agent-profile-appearance-field.tsx
@@ -8,7 +8,7 @@ import { Combobox, type ComboboxOption } from "@/components/ui/combobox";
 import {
   createControlGeometry,
   resolveControlInteractionStyles,
-  type FieldControlSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import { Field } from "@/components/ui/form-field";
 import { identityForeground } from "@/styles/identity-colors";
@@ -153,7 +153,7 @@ export function AgentProfileAppearanceField({
   icon: string;
   color: string;
   onChange: (next: { icon: string; color: string }) => void;
-  size?: FieldControlSize;
+  size?: ControlSize;
   disabled?: boolean;
   testID?: string;
   triggerTestID?: string;
diff --git a/packages/app/src/agent-profiles/settings/agent-profile-edit-modal.tsx b/packages/app/src/agent-profiles/settings/agent-profile-edit-modal.tsx
index cc06432d62..1fb3c0620a 100644
--- a/packages/app/src/agent-profiles/settings/agent-profile-edit-modal.tsx
+++ b/packages/app/src/agent-profiles/settings/agent-profile-edit-modal.tsx
@@ -2,11 +2,12 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement }
 import { Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
-import type { AgentFeature } from "@getpaseo/protocol/agent-types";
+import type { AgentOptionControl, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { readSelectOption, readToggleOption } from "@/agent-controls/option-controls";
 import type { AgentProfile } from "@getpaseo/protocol/messages";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
-import { type FieldControlSize } from "@/components/ui/control-geometry";
+import { type ControlSize } from "@/components/ui/control-geometry";
 import { Field, FormTextInput } from "@/components/ui/form-field";
 import {
   SelectField,
@@ -14,7 +15,6 @@ import {
   type SelectFieldOption,
 } from "@/components/ui/select-field";
 import { Switch } from "@/components/ui/switch";
-import { useIsCompactFormFactor } from "@/constants/layout";
 import { toErrorMessage } from "@/utils/error-messages";
 import { AgentProfileAppearanceField } from "./agent-profile-appearance-field";
 import type {
@@ -25,7 +25,7 @@ import type {
 } from "../internal/profile-form-model";
 import {
   useAgentProfileFormCatalog,
-  useAgentProfileFormFeatures,
+  useAgentProfileFormControls,
 } from "../internal/use-profile-form-inputs";
 import {
   useAgentProfileFormModel,
@@ -133,7 +133,7 @@ function OpenAgentProfileEditModal({
   onSave,
 }: AgentProfileEditModalProps & { onDismiss: () => void }): ReactElement {
   const { t } = useTranslation();
-  const controlSize: FieldControlSize = useIsCompactFormFactor() ? "md" : "sm";
+  const controlSize: ControlSize = "md";
   const snapshot = useMemo(
     () => ({ mode, ...(profile ? { profile } : {}), ...(seed ? { seed } : {}) }),
     [mode, profile, seed],
@@ -141,7 +141,7 @@ function OpenAgentProfileEditModal({
   const model = useAgentProfileFormModel(snapshot);
   const state = useAgentProfileFormState(model);
   useAgentProfileFormCatalog({ serverId, model });
-  useAgentProfileFormFeatures({ serverId, model, state });
+  useAgentProfileFormControls({ serverId, model, state });
 
   const sheetHeader = useMemo<SheetHeader>(
     () => ({
@@ -328,16 +328,17 @@ function OpenAgentProfileEditModal({
           />
         ) : null}
 
-        {state.disclosure.showFeaturesField ? (
+        {state.disclosure.showControlsField ? (
           <Field
             label={t("settings.host.agentProfiles.featuresLabel")}
             testID="agent-profile-features-field"
           >
             <View style={styles.featureCard} testID="agent-profile-features-card">
-              {state.features.map((feature, index) => (
-                <AgentProfileFeatureRow
-                  key={feature.id}
-                  feature={feature}
+              {state.controls.map((control, index) => (
+                <AgentProfileControlRow
+                  key={control.key}
+                  control={control}
+                  options={state.controlOptions}
                   isFirst={index === 0}
                   disabled={state.isSubmitting}
                   size={controlSize}
@@ -400,17 +401,19 @@ function OpenAgentProfileEditModal({
   );
 }
 
-function AgentProfileFeatureRow({
-  feature,
+function AgentProfileControlRow({
+  control,
+  options,
   isFirst,
   disabled,
   size,
   model,
 }: {
-  feature: AgentFeature;
+  control: AgentOptionControl;
+  options: ProviderOptions;
   isFirst: boolean;
   disabled: boolean;
-  size: FieldControlSize;
+  size: ControlSize;
   model: AgentProfileFormModel;
 }): ReactElement {
   const rowStyle = useMemo(
@@ -418,74 +421,75 @@ function AgentProfileFeatureRow({
     [isFirst],
   );
   const handleToggle = useCallback(
-    (value: boolean) => model.setFeatureValue(feature.id, value),
-    [feature.id, model],
+    (value: boolean) => model.setOption(control.key, value),
+    [control.key, model],
   );
   const handleSelect = useCallback(
-    (value: string) => model.setFeatureValue(feature.id, value),
-    [feature.id, model],
+    (value: string) => model.setOption(control.key, value),
+    [control.key, model],
   );
   const selectOptions = useMemo<SelectFieldOption<string>[]>(
     () =>
-      feature.type === "select"
-        ? feature.options.map((option) => ({
-            id: option.id,
-            value: option.id,
-            label: option.label,
-            ...(option.description ? { description: option.description } : {}),
-            testID: `agent-profile-feature-option-${feature.id}-${option.id}`,
+      control.type === "select"
+        ? control.choices.map((choice) => ({
+            id: choice.value,
+            value: choice.value,
+            label: choice.label,
+            ...(choice.description ? { description: choice.description } : {}),
+            testID: `agent-profile-feature-option-${control.key}-${choice.value}`,
           }))
         : [],
-    [feature],
+    [control],
   );
+  const selectedValue = control.type === "select" ? readSelectOption(control, options) : null;
   const selectedDisplay = useMemo<SelectFieldDisplay | null>(() => {
-    if (feature.type !== "select" || !feature.value) {
+    if (control.type !== "select" || !selectedValue) {
       return null;
     }
-    const option = feature.options.find((candidate) => candidate.id === feature.value);
-    return { label: option?.label ?? feature.value };
-  }, [feature]);
+    const choice = control.choices.find((candidate) => candidate.value === selectedValue);
+    return { label: choice?.label ?? selectedValue };
+  }, [control, selectedValue]);
 
-  if (feature.type === "select") {
+  if (control.type === "select") {
     return (
-      <View style={rowStyle} testID={`agent-profile-feature-row-${feature.id}`}>
+      <View style={rowStyle} testID={`agent-profile-feature-row-${control.key}`}>
         <SelectField
-          label={feature.label}
-          value={feature.value}
+          label={control.label}
+          value={selectedValue}
           selectedDisplay={selectedDisplay}
           options={selectOptions}
           onChange={handleSelect}
-          placeholder={feature.label}
-          emptyText={feature.label}
+          placeholder={control.label}
+          emptyText={control.label}
           disabled={disabled}
-          {...(feature.description ? { hint: feature.description } : {})}
-          title={feature.label}
+          {...(control.description ? { hint: control.description } : {})}
+          title={control.label}
           size={size}
-          testID={`agent-profile-feature-field-${feature.id}`}
-          triggerTestID={`agent-profile-feature-trigger-${feature.id}`}
+          testID={`agent-profile-feature-field-${control.key}`}
+          triggerTestID={`agent-profile-feature-trigger-${control.key}`}
         />
       </View>
     );
   }
 
   return (
-    <View style={rowStyle} testID={`agent-profile-feature-row-${feature.id}`}>
+    <View style={rowStyle} testID={`agent-profile-feature-row-${control.key}`}>
       <View style={styles.featureMeta}>
         <Text style={styles.featureLabel} numberOfLines={1}>
-          {feature.label}
+          {control.label}
         </Text>
-        {feature.description ? (
+        {control.description ? (
           <Text style={styles.featureDescription} numberOfLines={2}>
-            {feature.description}
+            {control.description}
           </Text>
         ) : null}
       </View>
       <Switch
-        value={feature.value === true}
+        value={readToggleOption(control, options)}
         onValueChange={handleToggle}
         disabled={disabled}
-        accessibilityLabel={feature.label}
-        testID={`agent-profile-feature-switch-${feature.id}`}
+        accessibilityLabel={control.label}
+        testID={`agent-profile-feature-switch-${control.key}`}
       />
     </View>
   );
diff --git a/packages/app/src/agent-profiles/settings/agent-profile-row.tsx b/packages/app/src/agent-profiles/settings/agent-profile-row.tsx
index c2686d1a1f..260bec4668 100644
--- a/packages/app/src/agent-profiles/settings/agent-profile-row.tsx
+++ b/packages/app/src/agent-profiles/settings/agent-profile-row.tsx
@@ -103,7 +103,6 @@ export function AgentProfileRow({
       <View style={styles.rowActions}>
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveUpIcon}
           onPress={handleMoveUp}
           disabled={isFirst}
@@ -112,7 +111,6 @@ export function AgentProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveDownIcon}
           onPress={handleMoveDown}
           disabled={isLast}
@@ -121,7 +119,6 @@ export function AgentProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={editIcon}
           onPress={handleEdit}
           accessibilityLabel={t("settings.host.agentProfiles.editProfile")}
@@ -129,7 +126,6 @@ export function AgentProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={removeIcon}
           onPress={handleRemove}
           accessibilityLabel={t("settings.host.agentProfiles.remove")}
diff --git a/packages/app/src/agent-profiles/settings/agent-profiles-section.tsx b/packages/app/src/agent-profiles/settings/agent-profiles-section.tsx
index 0cbee5d4d6..2a0d491b0a 100644
--- a/packages/app/src/agent-profiles/settings/agent-profiles-section.tsx
+++ b/packages/app/src/agent-profiles/settings/agent-profiles-section.tsx
@@ -124,7 +124,6 @@ export function AgentProfilesSection({ serverId }: { serverId: string }): ReactE
     () => (
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={addIcon}
         onPress={handleAddOpen}
         disabled={!profiles}
@@ -181,7 +180,7 @@ export function AgentProfilesSection({ serverId }: { serverId: string }): ReactE
               <Text style={styles.emptyText} testID="agent-profiles-empty">
                 {t("settings.host.agentProfiles.emptyState")}
               </Text>
-              <Button size="sm" leftIcon={addIcon} onPress={handleAddOpen} disabled={!profiles}>
+              <Button leftIcon={addIcon} onPress={handleAddOpen} disabled={!profiles}>
                 {t("settings.host.agentProfiles.newProfile")}
               </Button>
             </View>
diff --git a/packages/app/src/agent-skills/index.tsx b/packages/app/src/agent-skills/index.tsx
index 1241192b50..9be1813dfe 100644
--- a/packages/app/src/agent-skills/index.tsx
+++ b/packages/app/src/agent-skills/index.tsx
@@ -3,29 +3,27 @@ import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
 import { useFocusEffect } from "expo-router/react-navigation";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { ArrowUpRight, Blocks, Check, Settings2 } from "lucide-react-native";
+import { Settings2 } from "lucide-react-native";
 import type { AgentSkillOperation, AgentSkillsStatus } from "@getpaseo/protocol/messages";
 import type { TFunction } from "i18next";
+import { SettingsCard, SettingsRow, SettingsSection } from "@/components/settings";
 import { Button } from "@/components/ui/button";
-import { SettingsSection } from "@/components/settings/headings/settings-section";
+import { Switch } from "@/components/ui/switch";
 import { settingsStyles } from "@/styles/settings";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import { confirmDialog } from "@/utils/confirm-dialog";
-import { openExternalUrl } from "@/utils/open-external-url";
 import { SkillSelectionSheet } from "./selection-sheet";
-import { useAgentSkills } from "./use-agent-skills";
+import { useAgentSkills, type AgentSkillsController } from "./use-agent-skills";
+
+export { useAgentSkills, type AgentSkillsController } from "./use-agent-skills";
 
 const OP_KIND_ORDER: Record<AgentSkillOperation["kind"], number> = {
   add: 0,
   update: 1,
   delete: 2,
 };
-const ThemedBlocks = withUnistyles(Blocks);
-const ThemedCheck = withUnistyles(Check);
 const ThemedSettings = withUnistyles(Settings2);
-const ThemedArrowUpRight = withUnistyles(ArrowUpRight);
 const SKILLS_DOCS_URL = "https://paseo.sh/docs/skills";
-const foregroundMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 const mutedMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
 
 function formatUpdateMessage(ops: readonly AgentSkillOperation[], t: TFunction): string {
@@ -35,91 +33,50 @@ function formatUpdateMessage(ops: readonly AgentSkillOperation[], t: TFunction):
     .join("\n");
 }
 
+/** Whether the host has Paseo's skills installed in any form, current or not. */
+export function areSkillsInstalled(status: AgentSkillsStatus | null): boolean {
+  return status !== null && status.state !== "not-installed";
+}
+
+/** Whether the saved selection names any skill there is to install. */
+export function hasSelectedSkills(status: AgentSkillsStatus | null): boolean {
+  if (!status) return false;
+  if (status.selection.mode === "all") return status.available.length > 0;
+  return status.selection.skills.some((name) => status.available.includes(name));
+}
+
 export function AgentSkillsSection({ serverId }: { serverId: string }) {
   const { t } = useTranslation();
   const skills = useAgentSkills(serverId);
-  const refreshSkills = skills.refresh;
-  const skillsConnected = skills.connected;
-  const skillsSupported = skills.supported;
-  const [isChoosing, setIsChoosing] = useState(false);
+  const { refresh, connected, supported, reconcile, uninstall } = skills;
   useFocusEffect(
     useCallback(() => {
-      if (skillsConnected && skillsSupported) void refreshSkills();
+      if (connected && supported) void refresh();
       return undefined;
-    }, [refreshSkills, skillsConnected, skillsSupported]),
+    }, [refresh, connected, supported]),
   );
-  const maintenanceOps = useMemo(
-    () => skills.status?.ops.filter((op) => op.kind !== "delete") ?? [],
-    [skills.status?.ops],
+  const handleValueChange = useCallback(
+    (next: boolean) => {
+      void (next ? reconcile() : uninstall());
+    },
+    [reconcile, uninstall],
   );
-  const state =
-    skills.status?.state === "drift" && maintenanceOps.length === 0
-      ? "up-to-date"
-      : (skills.status?.state ?? null);
-  const hasSelected =
-    (skills.status?.selection.mode === "all" && skills.status.available.length > 0) ||
-    (skills.status?.selection.mode === "custom" &&
-      skills.status.selection.skills.some((name) => skills.status?.available.includes(name)));
-
-  const handleReconcile = useCallback(async () => {
-    if (skills.isWorking) return;
-    const confirmed = await confirmDialog({
-      title: t("settings.host.skills.updateTitle"),
-      message:
-        maintenanceOps.length > 0
-          ? formatUpdateMessage(maintenanceOps, t)
-          : t("settings.host.skills.updateFallback"),
-      confirmLabel: t("settings.host.skills.actions.update"),
-    });
-    if (confirmed) await skills.reconcile();
-  }, [maintenanceOps, skills, t]);
-  const handleUninstall = useCallback(async () => {
-    if (skills.isWorking) return;
-    const confirmed = await confirmDialog({
-      title: t("settings.host.skills.uninstallTitle"),
-      message: t("settings.host.skills.uninstallMessage"),
-      confirmLabel: t("settings.host.skills.actions.uninstall"),
-      destructive: true,
-    });
-    if (confirmed) await skills.uninstall();
-  }, [skills, t]);
-  const chooseIcon = useMemo(
-    () => <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedMapping} />,
-    [],
-  );
-  const handleOpen = useCallback(() => setIsChoosing(true), []);
-  const handleClose = useCallback(() => setIsChoosing(false), []);
-  const handleOpenDocs = useCallback(() => {
-    void openExternalUrl(SKILLS_DOCS_URL);
-  }, []);
-  const docsIcon = useMemo(
-    () => <ThemedArrowUpRight size={ICON_SIZE.sm} uniProps={mutedMapping} />,
-    [],
-  );
-  const trailing = useMemo(
-    () => (
-      <Button
-        variant="ghost"
-        size="sm"
-        leftIcon={docsIcon}
-        textStyle={settingsStyles.sectionHeaderLinkText}
-        style={settingsStyles.sectionHeaderLink}
-        onPress={handleOpenDocs}
-        accessibilityLabel={t("settings.host.skills.openDocs")}
-      >
-        {t("settings.host.skills.docs")}
-      </Button>
-    ),
-    [docsIcon, handleOpenDocs, t],
+  const docsLink = useMemo(
+    () => ({
+      href: SKILLS_DOCS_URL,
+      label: t("settings.host.skills.docs"),
+      accessibilityLabel: t("settings.host.skills.openDocs"),
+    }),
+    [t],
   );
 
-  if (!skills.connected || !skills.supported) {
+  if (!connected || !supported) {
     return (
-      <SettingsSection title={t("settings.host.skills.sectionTitle")} trailing={trailing}>
+      <SettingsSection title={t("settings.host.skills.sectionTitle")} link={docsLink}>
         <View style={settingsStyles.card} testID="host-agent-skills-unavailable">
           <View style={styles.emptyCard}>
             <Text style={styles.mutedText}>
-              {skills.connected
+              {connected
                 ? t("settings.host.skills.unsupported")
                 : t("settings.host.skills.unavailable")}
             </Text>
@@ -130,109 +87,112 @@ export function AgentSkillsSection({ serverId }: { serverId: string }) {
   }
 
   return (
-    <SettingsSection title={t("settings.host.skills.sectionTitle")} trailing={trailing}>
-      <View style={settingsStyles.card} testID="host-agent-skills-card">
-        <View style={settingsStyles.row}>
-          <View style={settingsStyles.rowContent}>
-            <View style={styles.rowTitleRow}>
-              <ThemedBlocks size={ICON_SIZE.md} uniProps={foregroundMapping} />
-              <Text style={settingsStyles.rowTitle}>{t("settings.host.skills.title")}</Text>
-            </View>
-            <Text style={settingsStyles.rowHint}>
-              {state === "drift"
-                ? t("settings.host.skills.updateAvailable")
-                : t("settings.host.skills.description")}
-            </Text>
-          </View>
-          <View style={styles.actionsRow}>
-            <Button
-              variant="ghost"
-              size="sm"
-              leftIcon={chooseIcon}
-              onPress={handleOpen}
-              disabled={skills.status === null || skills.isWorking}
-              accessibilityLabel={t("settings.host.skills.choose")}
-            />
-            {hasSelected ? (
-              <SkillsActions
-                state={state}
-                isWorking={skills.isWorking}
-                onInstall={skills.reconcile}
-                onReconcile={handleReconcile}
-                onUninstall={handleUninstall}
-              />
-            ) : null}
-          </View>
-        </View>
-      </View>
-      {skills.status ? (
-        <SkillSelectionSheet
-          visible={isChoosing}
-          available={skills.status.available}
-          selection={skills.status.selection}
-          isSaving={skills.isWorking}
-          onSave={skills.saveSelection}
-          onClose={handleClose}
+    <SettingsSection title={t("settings.host.skills.sectionTitle")} link={docsLink}>
+      <SettingsCard testID="host-agent-skills-card">
+        <AgentSkillsRow
+          skills={skills}
+          value={areSkillsInstalled(skills.status)}
+          onValueChange={handleValueChange}
         />
-      ) : null}
+      </SettingsCard>
     </SettingsSection>
   );
 }
 
-function SkillsActions({
-  state,
-  isWorking,
-  onReconcile,
-  onInstall,
-  onUninstall,
+/**
+ * The orchestration skills row: a switch for whether they are installed, a gear that opens the
+ * skill picker, and Update when the installed skills fall behind the bundled ones. The caller
+ * decides what the switch is bound to; the picker and Update always act on the host.
+ */
+export function AgentSkillsRow({
+  skills,
+  value,
+  onValueChange,
+  disabled = false,
 }: {
-  state: AgentSkillsStatus["state"] | null;
-  isWorking: boolean;
-  onReconcile: () => void;
-  onInstall: () => void;
-  onUninstall: () => void;
+  skills: AgentSkillsController;
+  value: boolean;
+  onValueChange: (next: boolean) => void;
+  disabled?: boolean;
 }) {
   const { t } = useTranslation();
-  if (state === "up-to-date") {
-    return (
-      <View style={styles.actionsRow}>
-        <View style={styles.installedLabel}>
-          <ThemedCheck size={14} uniProps={mutedMapping} />
-          <Text style={styles.mutedText}>{t("settings.host.skills.actions.installed")}</Text>
-        </View>
-        <Button variant="outline" size="sm" onPress={onUninstall} disabled={isWorking}>
-          {t("settings.host.skills.actions.uninstall")}
-        </Button>
-      </View>
-    );
-  }
-  if (state === "drift") {
-    return (
-      <View style={styles.actionsRow}>
-        <Button variant="outline" size="sm" onPress={onReconcile} disabled={isWorking}>
-          {isWorking
-            ? t("settings.host.skills.actions.working")
-            : t("settings.host.skills.actions.update")}
-        </Button>
-        <Button variant="outline" size="sm" onPress={onUninstall} disabled={isWorking}>
-          {t("settings.host.skills.actions.uninstall")}
-        </Button>
-      </View>
-    );
-  }
+  const { status, isWorking, reconcile, saveSelection } = skills;
+  const [isChoosing, setIsChoosing] = useState(false);
+  // Deleting a deselected skill is a choice made in the picker, not an update to offer here.
+  const maintenanceOps = useMemo(
+    () => status?.ops.filter((op) => op.kind !== "delete") ?? [],
+    [status?.ops],
+  );
+  const needsUpdate = status?.state === "drift" && maintenanceOps.length > 0;
+
+  const handleUpdate = useCallback(async () => {
+    if (isWorking) return;
+    const confirmed = await confirmDialog({
+      title: t("settings.host.skills.updateTitle"),
+      message: formatUpdateMessage(maintenanceOps, t),
+      confirmLabel: t("settings.host.skills.actions.update"),
+    });
+    if (confirmed) await reconcile();
+  }, [isWorking, maintenanceOps, reconcile, t]);
+  const handleOpen = useCallback(() => setIsChoosing(true), []);
+  const handleClose = useCallback(() => setIsChoosing(false), []);
+  const chooseIcon = useMemo(
+    () => <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedMapping} />,
+    [],
+  );
+
   return (
-    <Button variant="outline" size="sm" onPress={onInstall} disabled={isWorking}>
-      {isWorking
-        ? t("settings.host.skills.actions.installing")
-        : t("settings.host.skills.actions.install")}
-    </Button>
+    <>
+      <SettingsRow
+        label={t("settings.host.skills.title")}
+        hint={
+          needsUpdate
+            ? t("settings.host.skills.updateAvailable")
+            : t("settings.host.skills.description")
+        }
+      >
+        <View style={styles.controls}>
+          {needsUpdate ? (
+            <Button variant="outline" onPress={handleUpdate} disabled={disabled || isWorking}>
+              {isWorking
+                ? t("settings.host.skills.actions.working")
+                : t("settings.host.skills.actions.update")}
+            </Button>
+          ) : null}
+          <Button
+            variant="ghost"
+            leftIcon={chooseIcon}
+            onPress={handleOpen}
+            disabled={disabled || status === null || isWorking}
+            accessibilityLabel={t("settings.host.skills.choose")}
+          />
+          <Switch
+            value={value}
+            onValueChange={onValueChange}
+            // Nothing picked means nothing to install; the gear is the way forward.
+            disabled={
+              disabled || status === null || isWorking || (!value && !hasSelectedSkills(status))
+            }
+            accessibilityLabel={t("settings.host.skills.title")}
+          />
+        </View>
+      </SettingsRow>
+      {status ? (
+        <SkillSelectionSheet
+          visible={isChoosing}
+          available={status.available}
+          selection={status.selection}
+          isSaving={isWorking}
+          onSave={saveSelection}
+          onClose={handleClose}
+        />
+      ) : null}
+    </>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  rowTitleRow: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
-  installedLabel: { flexDirection: "row", alignItems: "center", gap: 4 },
+  controls: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
   mutedText: { color: theme.colors.foregroundMuted, fontSize: theme.fontSize.sm },
-  actionsRow: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
   emptyCard: { padding: theme.spacing[4] },
 }));
diff --git a/packages/app/src/agent-skills/selection-sheet.tsx b/packages/app/src/agent-skills/selection-sheet.tsx
index c161747c4c..6b2dc50f22 100644
--- a/packages/app/src/agent-skills/selection-sheet.tsx
+++ b/packages/app/src/agent-skills/selection-sheet.tsx
@@ -1,23 +1,18 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Pressable, Text, View } from "react-native";
-import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { Check } from "lucide-react-native";
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
 import { Switch } from "@/components/ui/switch";
-import { SettingsSection } from "@/components/settings/headings/settings-section";
+import { SettingsCard, SettingsRow, SettingsSection } from "@/components/settings";
 import { settingsStyles } from "@/styles/settings";
-import type { Theme } from "@/styles/theme";
 import { confirmDialog } from "@/utils/confirm-dialog";
 import type {
   AgentSkillSelection as SkillSelection,
   AgentSkillsSaveResult as SkillsSaveResult,
 } from "@getpaseo/protocol/messages";
 
-const ThemedCheck = withUnistyles(Check);
-const checkedIconMapping = (theme: Theme) => ({ color: theme.colors.accentForeground });
-
 interface SkillSelectionSheetProps {
   visible: boolean;
   available: readonly string[];
@@ -157,12 +152,11 @@ export function SkillSelectionSheet({
       footer={footer}
       testID="skill-selection-sheet"
     >
-      <View style={settingsStyles.card} testID="skill-selection-all-card">
-        <View style={settingsStyles.row}>
-          <View style={settingsStyles.rowContent}>
-            <Text style={settingsStyles.rowTitle}>{t("settings.host.skills.chooseAll")}</Text>
-            <Text style={settingsStyles.rowHint}>{t("settings.host.skills.chooseAllHint")}</Text>
-          </View>
+      <SettingsCard testID="skill-selection-all-card">
+        <SettingsRow
+          label={t("settings.host.skills.chooseAll")}
+          hint={t("settings.host.skills.chooseAllHint")}
+        >
           <Switch
             value={allSkills}
             onValueChange={handleToggleAll}
@@ -170,30 +164,29 @@ export function SkillSelectionSheet({
             accessibilityLabel={t("settings.host.skills.chooseAll")}
             testID="skill-selection-all"
           />
-        </View>
-      </View>
+        </SettingsRow>
+      </SettingsCard>
 
       {/* The sheet body already spaces its blocks apart, so the section owns
           only the gap between its label and the list the label names. */}
       <SettingsSection title={t("settings.host.skills.chooseList")} flush>
-        <View style={settingsStyles.card} testID="skill-selection-list-card">
+        <SettingsCard testID="skill-selection-list-card">
           {available.length === 0 ? (
             <View style={settingsStyles.row}>
               <Text style={settingsStyles.rowHint}>{t("settings.host.skills.chooseEmpty")}</Text>
             </View>
           ) : (
-            available.map((name, index) => (
-              <SkillCheckboxRow
+            available.map((name) => (
+              <SkillRow
                 key={name}
                 name={name}
                 checked={isSkillSelected(draft, name)}
                 disabled={allSkills || isSaving}
-                withBorder={index > 0}
                 onToggle={handleToggleSkill}
               />
             ))
           )}
-        </View>
+        </SettingsCard>
       </SettingsSection>
 
       {saveError ? <Text style={settingsStyles.rowError}>{saveError}</Text> : null}
@@ -201,52 +194,27 @@ export function SkillSelectionSheet({
   );
 }
 
-interface SkillCheckboxRowProps {
-  name: string;
-  checked: boolean;
-  disabled: boolean;
-  withBorder: boolean;
-  onToggle: (name: string) => void;
-}
-
-function SkillCheckboxRow({
+function SkillRow({
   name,
   checked,
   disabled,
-  withBorder,
   onToggle,
-}: SkillCheckboxRowProps) {
-  const handlePress = useCallback(() => onToggle(name), [name, onToggle]);
-  const accessibilityState = useMemo(() => ({ checked, disabled }), [checked, disabled]);
-  const rowStyle = useMemo(
-    () => [
-      settingsStyles.row,
-      withBorder ? settingsStyles.rowBorder : null,
-      styles.checkboxRow,
-      disabled ? styles.disabledRow : null,
-    ],
-    [disabled, withBorder],
-  );
-  const boxStyle = useMemo(
-    () => [styles.checkbox, checked ? styles.checkboxChecked : null],
-    [checked],
-  );
-
+}: {
+  name: string;
+  checked: boolean;
+  disabled: boolean;
+  onToggle: (name: string) => void;
+}) {
+  const handleValueChange = useCallback(() => onToggle(name), [name, onToggle]);
   return (
-    <Pressable
-      style={rowStyle}
-      onPress={handlePress}
-      disabled={disabled}
-      accessibilityRole="checkbox"
-      accessibilityLabel={name}
-      accessibilityState={accessibilityState}
-      aria-checked={checked}
-    >
-      <View style={boxStyle}>
-        {checked ? <ThemedCheck size={14} uniProps={checkedIconMapping} /> : null}
-      </View>
-      <Text style={settingsStyles.rowTitle}>{name}</Text>
-    </Pressable>
+    <SettingsRow label={name}>
+      <Switch
+        value={checked}
+        onValueChange={handleValueChange}
+        disabled={disabled}
+        accessibilityLabel={name}
+      />
+    </SettingsRow>
   );
 }
 
@@ -259,24 +227,4 @@ const styles = StyleSheet.create((theme) => ({
   footerButton: {
     flex: 1,
   },
-  checkboxRow: {
-    justifyContent: "flex-start",
-    gap: theme.spacing[3],
-  },
-  disabledRow: {
-    opacity: theme.opacity[50],
-  },
-  checkbox: {
-    width: 22,
-    height: 22,
-    borderRadius: theme.borderRadius.sm,
-    borderWidth: 1,
-    borderColor: theme.colors.border,
-    alignItems: "center",
-    justifyContent: "center",
-  },
-  checkboxChecked: {
-    backgroundColor: theme.colors.accent,
-    borderColor: theme.colors.accent,
-  },
 }));
diff --git a/packages/app/src/agent-skills/use-agent-skills.ts b/packages/app/src/agent-skills/use-agent-skills.ts
index d2c4612c7f..836cdb73dd 100644
--- a/packages/app/src/agent-skills/use-agent-skills.ts
+++ b/packages/app/src/agent-skills/use-agent-skills.ts
@@ -10,6 +10,9 @@ import { useToast } from "@/contexts/toast-context";
 import { useFetchQuery } from "@/data/query";
 import { useHostFeature } from "@/runtime/host-features";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { confirmDialog } from "@/utils/confirm-dialog";
+
+export type AgentSkillsController = ReturnType<typeof useAgentSkills>;
 
 export function useAgentSkills(serverId: string) {
   const { t } = useTranslation();
@@ -83,12 +86,30 @@ export function useAgentSkills(serverId: string) {
   const refresh = useCallback(async () => {
     await refetch();
   }, [refetch]);
-  const runReconcile = useCallback(async () => {
-    await reconcileAsync().catch(() => undefined);
-  }, [reconcileAsync]);
+  // Both resolve to whether the host ended in the asked-for state; failures are already toasted.
+  const runReconcile = useCallback(
+    () =>
+      reconcileAsync().then(
+        (status) => status.state !== "not-installed",
+        () => false,
+      ),
+    [reconcileAsync],
+  );
+  // Uninstalling deletes whole skill folders, including anything the user added inside them, so
+  // it always asks first. Declining resolves false, as a failure does.
   const runUninstall = useCallback(async () => {
-    await uninstallAsync().catch(() => undefined);
-  }, [uninstallAsync]);
+    const confirmed = await confirmDialog({
+      title: t("settings.host.skills.uninstallTitle"),
+      message: t("settings.host.skills.uninstallMessage"),
+      confirmLabel: t("settings.host.skills.actions.uninstall"),
+      destructive: true,
+    });
+    if (!confirmed) return false;
+    return uninstallAsync().then(
+      (status) => status.state === "not-installed",
+      () => false,
+    );
+  }, [t, uninstallAsync]);
   const saveSelection = useCallback(
     (selection: AgentSkillSelection, confirmedRemovals: readonly string[] = []) =>
       saveAsync({ selection, confirmedRemovals }),
diff --git a/packages/app/src/agent-stream/bottom-anchor-controller.test.ts b/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
index 17b6d44459..12ff114521 100644
--- a/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
+++ b/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
@@ -263,7 +263,7 @@ describe("bottom anchor controller driver", () => {
 
     expect(harness.scrollAttempts).toHaveLength(0);
 
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.scrollAttempts).toHaveLength(1);
@@ -293,7 +293,7 @@ describe("bottom anchor controller driver", () => {
     });
     harness.context.authoritativeReady = true;
     harness.driver.notifyAuthoritativeHistoryMaybeChanged();
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.scrollAttempts).toHaveLength(1);
@@ -321,7 +321,7 @@ describe("bottom anchor controller driver", () => {
       nextIsNearBottom: false,
       scrollDelta: 48,
     });
-    harness.driver.endUserScroll({ isNearBottom: false });
+    harness.driver.endUserScroll({ isAtEnd: false });
     harness.context.authoritativeReady = true;
     harness.driver.notifyAuthoritativeHistoryMaybeChanged();
     harness.driver.reevaluate();
@@ -340,10 +340,7 @@ describe("bottom anchor controller driver", () => {
     const harness = createDriverHarness();
 
     harness.driver.detachByUser();
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1500,
-    });
+    harness.driver.handleContentSizeChange();
     harness.driver.handleViewportMetricsChange({
       previousViewportWidth: 800,
       viewportWidth: 640,
@@ -356,7 +353,9 @@ describe("bottom anchor controller driver", () => {
     expect(harness.scrollAttempts).toHaveLength(0);
   });
 
-  it("pauses sticky maintenance while a user scroll owns the viewport", () => {
+  // While following, the list keeps its end through every content change, so a drag that kept
+  // following would see each streamed line move the rows under the finger.
+  it("stops following while a user scroll owns the viewport", () => {
     const harness = createDriverHarness({
       transportBehavior: {
         verificationDelayFrames: 2,
@@ -364,12 +363,8 @@ describe("bottom anchor controller driver", () => {
       },
     });
 
-    harness.driver.prepareForStickyContentChange();
     harness.driver.beginUserScroll();
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
+    harness.driver.handleContentSizeChange();
     harness.context.nearBottom = false;
     harness.driver.handleScrollNearBottomChange({
       nextIsNearBottom: false,
@@ -377,19 +372,29 @@ describe("bottom anchor controller driver", () => {
     });
     harness.scheduler.flushAll();
 
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingRequest: null,
-      pendingVerification: null,
-    });
+    expect(harness.scrollAttempts).toHaveLength(0);
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
 
-    harness.driver.endUserScroll({ isNearBottom: false });
+    harness.driver.endUserScroll({ isAtEnd: false });
 
     expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
 
-  it("restores sticky maintenance when a user scroll returns to the bottom", () => {
+  // Resuming would scroll by the distance left to the end in one frame, right after the release.
+  it("stays detached when a user scroll ends near the end but short of it", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.beginUserScroll();
+    harness.context.nearBottom = true;
+    harness.driver.handleContentSizeChange();
+    harness.driver.endUserScroll({ isAtEnd: false });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+  });
+
+  it("resumes following when a user scroll ends at the end", () => {
     const harness = createDriverHarness({
       transportBehavior: {
         verificationDelayFrames: 2,
@@ -403,16 +408,13 @@ describe("bottom anchor controller driver", () => {
       nextIsNearBottom: false,
       scrollDelta: 48,
     });
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
+    harness.driver.handleContentSizeChange();
     harness.context.nearBottom = true;
     harness.driver.handleScrollNearBottomChange({
       nextIsNearBottom: true,
       scrollDelta: -48,
     });
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.driver.getSnapshot()).toMatchObject({
@@ -420,7 +422,55 @@ describe("bottom anchor controller driver", () => {
       pendingRequest: null,
       pendingVerification: null,
     });
-    expect(harness.scrollAttempts).toHaveLength(1);
+    // Following stopped for the gesture, so content that arrived meanwhile left the end below it.
+    expect(harness.scrollAttempts).toEqual([false]);
+  });
+
+  it("holds a disclosure detached and resumes following when it is released at the end", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
+    });
+
+    harness.driver.holdForDisclosure();
+    harness.driver.handleContentSizeChange();
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: true,
+      scrollDelta: -12,
+    });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+
+    harness.driver.releaseDisclosure({ isAtEnd: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
+  });
+
+  it("stays detached when a disclosure is released away from the end", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.holdForDisclosure();
+    harness.driver.releaseDisclosure({ isAtEnd: false });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+  });
+
+  it("leaves a disclosure release to a user scroll that owns the viewport", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.holdForDisclosure();
+    harness.driver.beginUserScroll();
+    harness.driver.releaseDisclosure({ isAtEnd: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
 
   it("switches back to sticky-bottom for explicit jump-to-bottom", () => {
@@ -441,7 +491,7 @@ describe("bottom anchor controller driver", () => {
     expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
   });
 
-  it("schedules sticky maintenance on viewport and content growth", () => {
+  it("scrolls for a viewport resize while following", () => {
     const harness = createDriverHarness();
 
     harness.driver.handleViewportMetricsChange({
@@ -452,13 +502,44 @@ describe("bottom anchor controller driver", () => {
     });
     harness.scheduler.flushAll();
 
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1600,
+    expect(harness.scrollAttempts).toHaveLength(1);
+  });
+
+  it("never scrolls for a content change while following", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
     });
+
+    harness.context.measurementState.contentHeight = 1600;
+    harness.driver.handleContentSizeChange();
+    harness.context.measurementState.contentHeight = 1250;
+    harness.driver.handleContentSizeChange();
     harness.scheduler.flushAll();
 
-    expect(harness.scrollAttempts).toHaveLength(2);
+    expect(harness.scrollAttempts).toHaveLength(0);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+  });
+
+  it("detaches when the user scrolls away after a content change", () => {
+    const harness = createDriverHarness();
+
+    harness.context.measurementState.contentHeight = 1600;
+    harness.driver.handleContentSizeChange();
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 4,
+    });
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
   });
 
   it("keeps a pending request blocked when stale container measurements arrive", () => {
@@ -556,10 +637,7 @@ describe("bottom anchor controller driver", () => {
 
     harness.context.measurementState.contentHeight = 14804;
     harness.context.nearBottom = false;
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 14322,
-      contentHeight: 14804,
-    });
+    harness.driver.handleContentSizeChange();
 
     harness.scheduler.flushFrame();
 
@@ -628,10 +706,7 @@ describe("bottom anchor controller driver", () => {
 
     harness.context.measurementState.contentHeight = 16230;
     harness.context.nearBottom = false;
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 14322,
-      contentHeight: 16230,
-    });
+    harness.driver.handleContentSizeChange();
 
     harness.scheduler.flushFrame();
     harness.scheduler.flushFrame();
@@ -685,136 +760,6 @@ describe("bottom anchor controller driver", () => {
 
     expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
-
-  it("keeps sticky-bottom during streaming growth until bottom is re-verified", () => {
-    const harness = createDriverHarness();
-    harness.context.nearBottom = false;
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 900;
-    });
-
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
-    harness.scheduler.flushAll();
-
-    expect(harness.scrollAttempts).toHaveLength(4);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingRequest: null,
-      pendingVerification: null,
-    });
-
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 0,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-
-    harness.context.nearBottom = true;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: true,
-      scrollDelta: 0,
-    });
-    harness.scheduler.flushAll();
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 64,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("detached");
-  });
-
-  it("keeps initial native content growth anchored before layout scroll events arrive", () => {
-    const harness = createDriverHarness({
-      transportBehavior: {
-        verificationDelayFrames: 2,
-        verificationRetryMode: "recheck",
-      },
-      measurementState: createMeasurementState({
-        containerKey: "native-virtualized",
-        viewportWidth: 0,
-        viewportHeight: 0,
-        contentHeight: 0,
-        offsetY: 0,
-        viewportMeasuredForKey: null,
-        contentMeasuredForKey: null,
-      }),
-    });
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 0;
-    });
-
-    harness.context.measurementState.contentHeight = 1348;
-    harness.context.measurementState.contentMeasuredForKey = "native-virtualized";
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 0,
-      contentHeight: 1348,
-    });
-
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingVerification: {
-        requestId: null,
-      },
-    });
-
-    harness.context.measurementState.viewportWidth = 390;
-    harness.context.measurementState.viewportHeight = 546;
-    harness.context.measurementState.viewportMeasuredForKey = "native-virtualized";
-    harness.context.measurementState.offsetY = 50;
-    harness.context.nearBottom = false;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 50,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-  });
-
-  it("keeps native sticky content changes anchored when measured height is unchanged", () => {
-    const harness = createDriverHarness({
-      transportBehavior: {
-        verificationDelayFrames: 2,
-        verificationRetryMode: "recheck",
-      },
-      measurementState: createMeasurementState({
-        containerKey: "native-virtualized",
-        viewportWidth: 390,
-        viewportHeight: 546,
-        contentHeight: 546,
-        offsetY: 0,
-        viewportMeasuredForKey: "native-virtualized",
-        contentMeasuredForKey: "native-virtualized",
-      }),
-    });
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 0;
-      harness.context.nearBottom = true;
-    });
-
-    harness.driver.prepareForStickyContentChange();
-
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingVerification: {
-        requestId: null,
-      },
-    });
-
-    harness.context.measurementState.offsetY = 50;
-    harness.context.nearBottom = false;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 50,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-  });
 });
 
 describe("controller helper predicates", () => {
@@ -864,13 +809,6 @@ describe("controller helper predicates", () => {
   it("suppresses auto-anchor helpers while detached", () => {
     const mode: BottomAnchorMode = "detached";
 
-    expect(
-      __private__.shouldRestickOnContentChange({
-        mode,
-        previousContentHeight: 1000,
-        contentHeight: 1100,
-      }),
-    ).toBe(false);
     expect(
       __private__.shouldRestickOnViewportChange({
         mode,
diff --git a/packages/app/src/agent-stream/bottom-anchor-controller.ts b/packages/app/src/agent-stream/bottom-anchor-controller.ts
index 93b3c075e7..f666481be8 100644
--- a/packages/app/src/agent-stream/bottom-anchor-controller.ts
+++ b/packages/app/src/agent-stream/bottom-anchor-controller.ts
@@ -65,24 +65,21 @@ interface BottomAnchorControllerDriver {
     pendingVerification: AttemptContext | null;
     blockedReason: BottomAnchorBlockedReason | null;
   };
-  resetForAgent: () => void;
   applyRouteRequest: (request: BottomAnchorRouteRequest | null) => void;
   requestLocalAnchor: (request: BottomAnchorLocalRequest) => void;
   beginUserScroll: () => void;
-  endUserScroll: (params: { isNearBottom: boolean }) => void;
+  endUserScroll: (params: { isAtEnd: boolean }) => void;
   detachByUser: () => void;
+  holdForDisclosure: () => void;
+  releaseDisclosure: (params: { isAtEnd: boolean }) => void;
   handleViewportMetricsChange: (params: {
     previousViewportWidth: number;
     viewportWidth: number;
     previousViewportHeight: number;
     viewportHeight: number;
   }) => void;
-  handleContentSizeChange: (params: {
-    previousContentHeight: number;
-    contentHeight: number;
-  }) => void;
+  handleContentSizeChange: () => void;
   prepareForStickyViewportChange: () => void;
-  prepareForStickyContentChange: () => void;
   handleScrollNearBottomChange: (params: {
     nextIsNearBottom: boolean;
     scrollDelta: number;
@@ -415,6 +412,7 @@ function createBottomAnchorControllerDriver(
       | "content_size_change"
       | "scroll_near_bottom_change"
       | "user_scroll_end"
+      | "disclosure_released"
       | "history_readiness_change"
       | "manual_reevaluate"
       | "retry_scroll",
@@ -481,17 +479,6 @@ function createBottomAnchorControllerDriver(
         blockedReason,
       };
     },
-    resetForAgent() {
-      lastRouteRequestKey = null;
-      pendingRequest = null;
-      blockedReason = null;
-      cancelPendingAttempt();
-      stickyMeasurementRevision = 0;
-      lastVerifiedStickyMeasurementRevision = 0;
-      isUserScrollActive = false;
-      mode = "sticky-bottom";
-      input.onModeChange("sticky-bottom");
-    },
     applyRouteRequest(request) {
       if (!request) {
         return;
@@ -505,13 +492,19 @@ function createBottomAnchorControllerDriver(
     requestLocalAnchor(request) {
       createRequest(request);
     },
+    // The gesture owns the viewport, so following stops until it ends: content growing at the end
+    // must not move the rows under the finger. The gesture's end decides whether following resumes.
     beginUserScroll() {
       isUserScrollActive = true;
       cancelPendingAttempt();
+      setModeInternal("detached");
     },
+    // Following resumes only for a gesture that ends at the end. Resuming from short of it would
+    // scroll the rows the finger just let go of, so a release above the end, or with output that
+    // arrived below it during the gesture, stays detached with the pill.
     endUserScroll(params) {
       isUserScrollActive = false;
-      if (params.isNearBottom) {
+      if (params.isAtEnd) {
         if (mode === "detached") {
           setModeInternal("sticky-bottom");
           pendingVerification = { requestId: null, retries: 0 };
@@ -533,9 +526,8 @@ function createBottomAnchorControllerDriver(
         markStickyMeasurementVerified();
         return;
       }
-      if (mode === "sticky-bottom") {
-        this.detachByUser();
-      }
+      cancelPendingRequest("user_scrolled_away");
+      setModeInternal("detached");
     },
     detachByUser() {
       if (mode === "detached") {
@@ -544,6 +536,21 @@ function createBottomAnchorControllerDriver(
       cancelPendingRequest("user_scrolled_away");
       setModeInternal("detached");
     },
+    // A disclosure keeps its trigger in place, so following output stops while it applies.
+    holdForDisclosure() {
+      cancelPendingRequest("disclosure");
+      setModeInternal("detached");
+    },
+    // Following resumes only if the applied change left the list at its end. Scroll events
+    // during the hold never re-stick: before the change lands the list is still at the end.
+    releaseDisclosure(params) {
+      if (isUserScrollActive || mode !== "detached" || !params.isAtEnd) {
+        return;
+      }
+      setModeInternal("sticky-bottom");
+      pendingVerification = { requestId: null, retries: 0 };
+      evaluate(false, "disclosure_released");
+    },
     handleViewportMetricsChange(params) {
       if (
         params.previousViewportWidth !== params.viewportWidth ||
@@ -568,30 +575,13 @@ function createBottomAnchorControllerDriver(
         evaluate(false, "viewport_change");
       }
     },
-    handleContentSizeChange(params) {
-      if (params.previousContentHeight !== params.contentHeight) {
-        markStickyMeasurementChanged();
-      }
-      if (isUserScrollActive) {
+    // The list keeps its own end through content changes while following, so a change in content
+    // height never scrolls from here. It only gives a pending jump another look at the new geometry.
+    handleContentSizeChange() {
+      if (isUserScrollActive || !pendingRequest) {
         return;
       }
-      const shouldRestick = __private__.shouldRestickOnContentChange({
-        mode,
-        previousContentHeight: params.previousContentHeight,
-        contentHeight: params.contentHeight,
-      });
-      if (shouldRestick && !pendingRequest) {
-        pendingVerification = { requestId: null, retries: 0 };
-        if (attemptHandle) {
-          input.cancelFrame(attemptHandle);
-          attemptHandle = null;
-        }
-        runAttempt(false);
-        return;
-      }
-      if (shouldRestick || pendingRequest) {
-        evaluate(false, "content_size_change");
-      }
+      evaluate(false, "content_size_change");
     },
     prepareForStickyViewportChange() {
       if (mode !== "sticky-bottom") {
@@ -599,25 +589,6 @@ function createBottomAnchorControllerDriver(
       }
       markStickyMeasurementChanged();
     },
-    prepareForStickyContentChange() {
-      if (mode !== "sticky-bottom") {
-        return;
-      }
-      markStickyMeasurementChanged();
-      if (isUserScrollActive) {
-        return;
-      }
-      if (!pendingRequest) {
-        pendingVerification = { requestId: null, retries: 0 };
-        if (attemptHandle) {
-          input.cancelFrame(attemptHandle);
-          attemptHandle = null;
-        }
-        runAttempt(false);
-        return;
-      }
-      evaluate(false, "content_size_change");
-    },
     handleScrollNearBottomChange(params) {
       const { nextIsNearBottom, scrollDelta } = params;
       if (isUserScrollActive) {
@@ -695,13 +666,6 @@ export const __private__ = {
           input.previousViewportWidth !== input.viewportWidth))
     );
   },
-  shouldRestickOnContentChange(input: {
-    mode: BottomAnchorMode;
-    previousContentHeight: number;
-    contentHeight: number;
-  }): boolean {
-    return input.mode === "sticky-bottom" && input.contentHeight > input.previousContentHeight;
-  },
   shouldDetachFromScrollAway(input: {
     mode: BottomAnchorMode;
     nextIsNearBottom: boolean;
@@ -765,10 +729,6 @@ export function useBottomAnchorController(input: {
     });
   }
 
-  useEffect(() => {
-    driverRef.current?.resetForAgent();
-  }, [input.agentId]);
-
   useEffect(() => {
     driverRef.current?.applyRouteRequest(input.routeRequest);
   }, [input.routeRequest]);
@@ -792,12 +752,18 @@ export function useBottomAnchorController(input: {
     beginUserScroll() {
       driverRef.current?.beginUserScroll();
     },
-    endUserScroll(params: { isNearBottom: boolean }) {
+    endUserScroll(params: { isAtEnd: boolean }) {
       driverRef.current?.endUserScroll(params);
     },
     detachByUser() {
       driverRef.current?.detachByUser();
     },
+    holdForDisclosure() {
+      driverRef.current?.holdForDisclosure();
+    },
+    releaseDisclosure(params: { isAtEnd: boolean }) {
+      driverRef.current?.releaseDisclosure(params);
+    },
     handleViewportLayout() {},
     handleViewportMetricsChange(params: {
       previousViewportWidth: number;
@@ -807,15 +773,12 @@ export function useBottomAnchorController(input: {
     }) {
       driverRef.current?.handleViewportMetricsChange(params);
     },
-    handleContentSizeChange(params: { previousContentHeight: number; contentHeight: number }) {
-      driverRef.current?.handleContentSizeChange(params);
+    handleContentSizeChange() {
+      driverRef.current?.handleContentSizeChange();
     },
     prepareForStickyViewportChange() {
       driverRef.current?.prepareForStickyViewportChange();
     },
-    prepareForStickyContentChange() {
-      driverRef.current?.prepareForStickyContentChange();
-    },
     handleScrollNearBottomChange(params: { nextIsNearBottom: boolean; scrollDelta: number }) {
       driverRef.current?.handleScrollNearBottomChange(params);
     },
diff --git a/packages/app/src/agent-stream/chat-find/index.web.tsx b/packages/app/src/agent-stream/chat-find/index.web.tsx
index a083dc5d9e..eadcec4e22 100644
--- a/packages/app/src/agent-stream/chat-find/index.web.tsx
+++ b/packages/app/src/agent-stream/chat-find/index.web.tsx
@@ -15,7 +15,7 @@ import { PaneFind, findShortcutPlatform, isFindShortcut, type PaneFindHandle } f
 import { Button } from "@/components/ui/button";
 import { usePaneFocus } from "@/panels/pane-context";
 import { useRetainedPanelActive } from "@/components/retained-panel";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
+import { hasActiveOverlay } from "@/keyboard";
 import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { planTimelinePromptJump } from "@/timeline/timeline-sync-plan";
@@ -104,7 +104,7 @@ export function ChatFind({
   useEffect(() => {
     if (!active || !isInteractive) return;
     const onKeyDown = (event: KeyboardEvent) => {
-      if (event.defaultPrevented || hasActiveWebOverlay() || isImeComposingKeyboardEvent(event))
+      if (event.defaultPrevented || hasActiveOverlay() || isImeComposingKeyboardEvent(event))
         return;
       if (isFindShortcut(event, findShortcutPlatform())) {
         event.preventDefault();
@@ -147,7 +147,7 @@ export function ChatFind({
           {state.failure && (
             <View style={styles.error}>
               <Text style={styles.errorText}>{t(FAILURE_TEXT[state.failure])}</Text>
-              <Button size="xs" variant="ghost" onPress={model.retry}>
+              <Button size="sm" variant="ghost" onPress={model.retry}>
                 {t("paneFind.retry")}
               </Button>
             </View>
diff --git a/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts b/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
index 1b4b8d18e8..876c615577 100644
--- a/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
+++ b/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
@@ -24,7 +24,9 @@ function viewport(root: HTMLElement, capture: Capture) {
   const handle: StreamViewportHandle = {
     scrollToBottom() {},
     prepareForViewportChange() {},
-    holdReadingPosition() {},
+    holdRow(_rowId, apply) {
+      apply();
+    },
     scrollToMessage(_messageId, occurrence) {
       if (occurrence) capture.occurrence = occurrence;
     },
diff --git a/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx b/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
index ae2d3385dd..f6af94ac41 100644
--- a/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
+++ b/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
@@ -265,7 +265,7 @@ describe("useChatOutline", () => {
     const viewport: StreamViewportHandle = {
       scrollToBottom: vi.fn(),
       prepareForViewportChange: vi.fn(),
-      holdReadingPosition: vi.fn(),
+      holdRow: vi.fn(),
       scrollToMessage,
     };
     const viewportRef = { current: viewport };
@@ -317,7 +317,7 @@ describe("useChatOutline", () => {
       current: {
         scrollToBottom: vi.fn(),
         prepareForViewportChange: vi.fn(),
-        holdReadingPosition: vi.fn(),
+        holdRow: vi.fn(),
         scrollToMessage,
       },
     };
@@ -373,7 +373,7 @@ describe("useChatOutline", () => {
     const viewport: StreamViewportHandle = {
       scrollToBottom: vi.fn(),
       prepareForViewportChange: vi.fn(),
-      holdReadingPosition: vi.fn(),
+      holdRow: vi.fn(),
       scrollToMessage,
     };
     const livePrompt = {
diff --git a/packages/app/src/agent-stream/disclosure.browser.test.tsx b/packages/app/src/agent-stream/disclosure.browser.test.tsx
new file mode 100644
index 0000000000..74c61c4988
--- /dev/null
+++ b/packages/app/src/agent-stream/disclosure.browser.test.tsx
@@ -0,0 +1,147 @@
+import React, { act, createRef, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { within } from "@testing-library/dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { i18n as testI18n } from "@/i18n/i18next";
+import { PlanCard } from "@/components/plan-card";
+import { MessagePreview } from "@/components/user-message";
+import { DisclosureRow } from "./disclosure";
+import type { DisclosureTriggerEdge, StreamViewportHandle } from "./strategy";
+
+// Load translations so the toggles expose their real accessible names.
+void testI18n;
+
+// App sources compile against the classic JSX runtime, which expects React on the global.
+beforeEach(() => vi.stubGlobal("React", React));
+
+let root: Root;
+let container: HTMLDivElement;
+// The plan body renders through the app's Markdown renderer, which reads through React Query.
+let queryClient: QueryClient;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  queryClient = new QueryClient();
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  queryClient.clear();
+  container.remove();
+});
+
+interface Hold {
+  rowId: string;
+  triggerEdge: DisclosureTriggerEdge;
+  /** Whether the expanded content was already on screen when the strategy received the hold. */
+  appliedBefore: boolean;
+}
+
+/**
+ * A timeline row whose viewport records each hold. Like the strategies, it runs `apply` itself, so
+ * a toggle that skips the hold still changes state but leaves no record.
+ */
+function mountRow(rowId: string, isApplied: () => boolean, children: ReactNode) {
+  const holds: Hold[] = [];
+  const viewport: StreamViewportHandle = {
+    scrollToBottom: vi.fn(),
+    prepareForViewportChange: vi.fn(),
+    holdRow: (heldRowId, apply, triggerEdge) => {
+      holds.push({ rowId: heldRowId, triggerEdge, appliedBefore: isApplied() });
+      apply();
+    },
+  };
+  const viewportRef = createRef<StreamViewportHandle>();
+  viewportRef.current = viewport;
+  act(() =>
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <DisclosureRow rowId={rowId} viewportRef={viewportRef}>
+          {children}
+        </DisclosureRow>
+      </QueryClientProvider>,
+    ),
+  );
+  return holds;
+}
+
+const view = () => within(container);
+
+const preLine = { whiteSpace: "pre-line" } as const;
+
+async function waitForLayout() {
+  await act(async () => {
+    for (let frame = 0; frame < 2; frame += 1) {
+      await new Promise((resolve) => requestAnimationFrame(resolve));
+    }
+  });
+}
+
+describe("timeline disclosures hold their row", () => {
+  it("routes user message show more and show less through the row's hold", async () => {
+    const longText = Array.from({ length: 60 }, (_, line) => `Line ${line + 1}`).join("\n");
+    const holds = mountRow(
+      "message-1",
+      () => view().queryByRole("button", { name: "Show less" }) !== null,
+      <MessagePreview>
+        <span style={preLine}>{longText}</span>
+      </MessagePreview>,
+    );
+    // The preview learns it overflows from its first layout.
+    await waitForLayout();
+
+    act(() => view().getByRole("button", { name: "Show more" }).click());
+    expect(view().getByRole("button", { name: "Show less" })).toBeTruthy();
+
+    act(() => view().getByRole("button", { name: "Show less" }).click());
+    expect(view().getByRole("button", { name: "Show more" })).toBeTruthy();
+
+    expect(holds).toEqual([
+      // Show more sits under the text it opens.
+      { rowId: "message-1", triggerEdge: "bottom", appliedBefore: false },
+      { rowId: "message-1", triggerEdge: "bottom", appliedBefore: true },
+    ]);
+  });
+
+  it("routes plan card collapse and expand through the row's hold", () => {
+    const header = () => view().getByRole("button", { name: "Approved plan" });
+    const isExpanded = () => header().getAttribute("aria-expanded") === "true";
+    const holds = mountRow(
+      "plan-1",
+      isExpanded,
+      <PlanCard title="Plan" text="Step one" outcome="approved" />,
+    );
+
+    act(() => header().click());
+    expect(isExpanded()).toBe(false);
+
+    act(() => header().click());
+    expect(isExpanded()).toBe(true);
+
+    expect(holds).toEqual([
+      { rowId: "plan-1", triggerEdge: "top", appliedBefore: true },
+      { rowId: "plan-1", triggerEdge: "top", appliedBefore: false },
+    ]);
+  });
+
+  it("toggles a plan card outside a timeline row, as the pending permission card renders", () => {
+    act(() =>
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <PlanCard title="Plan" text="Step one" outcome="pending" />
+        </QueryClientProvider>,
+      ),
+    );
+    const header = () => view().getByRole("button", { name: "Plan" });
+    const isExpanded = () => header().getAttribute("aria-expanded") === "true";
+
+    act(() => header().click());
+    expect(isExpanded()).toBe(false);
+
+    act(() => header().click());
+    expect(isExpanded()).toBe(true);
+  });
+});
diff --git a/packages/app/src/agent-stream/disclosure.tsx b/packages/app/src/agent-stream/disclosure.tsx
new file mode 100644
index 0000000000..2deb42554f
--- /dev/null
+++ b/packages/app/src/agent-stream/disclosure.tsx
@@ -0,0 +1,44 @@
+import { createContext, useContext, useMemo, type ReactNode, type RefObject } from "react";
+import type { DisclosureTriggerEdge, StreamViewportHandle } from "./strategy";
+
+/**
+ * Runs a disclosure's state change. Inside a timeline row, the trigger keeps its screen
+ * position through the change; elsewhere `apply` runs as is. A trigger below the content it
+ * opens passes `triggerEdge: "bottom"`.
+ */
+export type DisclosureHold = (
+  apply: () => void,
+  options?: { triggerEdge?: DisclosureTriggerEdge },
+) => void;
+
+const applyInPlace: DisclosureHold = (apply) => apply();
+
+const DisclosureHoldContext = createContext<DisclosureHold>(applyInPlace);
+
+export function DisclosureRow({
+  rowId,
+  viewportRef,
+  children,
+}: {
+  rowId: string;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+  children: ReactNode;
+}) {
+  const hold = useMemo<DisclosureHold>(
+    () => (apply, options) => {
+      const viewport = viewportRef.current;
+      if (viewport) {
+        viewport.holdRow(rowId, apply, options?.triggerEdge ?? "top");
+      } else {
+        apply();
+      }
+    },
+    [rowId, viewportRef],
+  );
+  return <DisclosureHoldContext.Provider value={hold}>{children}</DisclosureHoldContext.Provider>;
+}
+
+/** Call with the toggle's state change: `hold(() => setExpanded(!expanded))`. */
+export function useDisclosureHold(): DisclosureHold {
+  return useContext(DisclosureHoldContext);
+}
diff --git a/packages/app/src/agent-stream/footer-spacing.test.ts b/packages/app/src/agent-stream/footer-spacing.test.ts
index 341ce75583..e3e28ab0bc 100644
--- a/packages/app/src/agent-stream/footer-spacing.test.ts
+++ b/packages/app/src/agent-stream/footer-spacing.test.ts
@@ -3,32 +3,13 @@ import type { TurnTiming } from "@/timeline/turn-time";
 import type { StreamItem } from "@/types/stream";
 import { layoutStream } from "./layout";
 import type { StreamStrategy } from "./strategy";
+import { resolveStreamRenderStrategy } from "./strategy-resolver";
 
 function strategyFor(platform: "web" | "native"): StreamStrategy {
-  const inverted = platform === "native";
-  const neighborStep = inverted ? 1 : -1;
-  const getHistoryBoundaryIndex = (items: StreamItem[]) => {
-    if (items.length === 0) return null;
-    return inverted ? 0 : items.length - 1;
-  };
-  const getLiveHeadBoundaryIndex = (items: StreamItem[]) => {
-    if (items.length === 0) return null;
-    return inverted ? items.length - 1 : 0;
-  };
-  return {
-    orderTail: (items) => (inverted ? [...items].toReversed() : items),
-    orderHead: (items) => (inverted ? [...items].toReversed() : items),
-    getNeighborIndex: (index, relation) =>
-      relation === "above" ? index + neighborStep : index - neighborStep,
-    getNeighborItem: (items, index, relation) => {
-      const neighborIndex = relation === "above" ? index + neighborStep : index - neighborStep;
-      return items[neighborIndex];
-    },
-    getHistoryLiveBoundaryIndex: getHistoryBoundaryIndex,
-    getLiveHeadHistoryBoundaryIndex: getLiveHeadBoundaryIndex,
-    getLatestItemIndex: getHistoryBoundaryIndex,
-    getFrameChildOrder: () => (inverted ? "footer-then-content" : "content-then-footer"),
-  } as StreamStrategy;
+  return resolveStreamRenderStrategy({
+    platform: platform === "native" ? "android" : "web",
+    isMobileBreakpoint: false,
+  });
 }
 
 function userMessage(id: string): Extract<StreamItem, { kind: "user_message" }> {
diff --git a/packages/app/src/agent-stream/history-start-pagination.test.ts b/packages/app/src/agent-stream/history-start-pagination.test.ts
index 9663d87e23..4867bcce2e 100644
--- a/packages/app/src/agent-stream/history-start-pagination.test.ts
+++ b/packages/app/src/agent-stream/history-start-pagination.test.ts
@@ -1,197 +1,310 @@
-import { describe, expect, it } from "vitest";
+import { nativeHistoryStartGeometry } from "./native-history-start-geometry";
+import { describe, expect, it, vi } from "vitest";
 import {
-  abandonHistoryStartPaginationRequest,
-  createHistoryStartPaginationState,
-  evaluateHistoryStartPagination,
-  isHistoryStartLoadingOperation,
-  rearmHistoryStartPagination,
-  settleHistoryStartPagination,
+  createHistoryStartPagination,
   type HistoryStartPaginationInput,
 } from "./history-start-pagination";
 
-function createArmedHistoryStartPaginationState() {
-  return rearmHistoryStartPagination(createHistoryStartPaginationState());
-}
-
-const visibleHistoryStart: HistoryStartPaginationInput = {
+const initial: HistoryStartPaginationInput = {
   distanceFromHistoryStart: 0,
+  isUnderfilled: true,
   hasOlderHistory: true,
   isLoadingOlderHistory: false,
   isReady: true,
-  progressKey: "epoch-1:20",
+  progressKey: "20",
 };
 
+function harness(initiallyVisible = false) {
+  let geometry = { ...initial };
+  const requests: Array<(value: boolean) => void> = [];
+  let settles = 0;
+  const pagination = createHistoryStartPagination({
+    initiallyVisible,
+    read: () => geometry,
+    load: () => new Promise<boolean>((resolve) => requests.push(resolve)),
+    changed: () => {},
+    scheduleSettle: () => {
+      settles++;
+    },
+  });
+  return {
+    pagination,
+    requests,
+    get settles() {
+      return settles;
+    },
+    set(patch: Partial<HistoryStartPaginationInput>) {
+      geometry = { ...geometry, ...patch };
+      pagination.update();
+    },
+  };
+}
+
 describe("history start pagination", () => {
-  it("treats locally revealed history as progress before remote pagination", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const localReveal = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      progressKey: "epoch-1:20:local-60",
-    });
-
-    expect(first.shouldLoad).toBe(true);
-    expect(localReveal.state).toEqual({
-      status: "settling",
-      loadedProgressKey: "epoch-1:20:local-60",
-    });
+  it("waits for a delayed request and its committed page before settling", async () => {
+    const h = harness();
+    h.pagination.update();
+    h.set({ progressKey: "10" });
+    expect(h.settles).toBe(0);
+    h.requests[0](true);
+    await Promise.resolve();
+    expect(h.settles).toBe(1);
+    expect(h.pagination.state.visible).toBe(false);
+    h.set({ isUnderfilled: false });
+    h.pagination.settle();
+    expect(h.pagination.state).toEqual({ status: "dormant", visible: true });
+    h.pagination.dispose();
   });
-  it("waits for user scroll intent before loading", () => {
-    const dormant = createHistoryStartPaginationState();
-    const evaluated = evaluateHistoryStartPagination(dormant, visibleHistoryStart);
-
-    expect(evaluated).toEqual({ state: { status: "dormant" }, shouldLoad: false });
+  it("waits for the committed page after a request completes", async () => {
+    const h = harness();
+    h.pagination.update();
+    h.requests[0](true);
+    await Promise.resolve();
+    expect(h.settles).toBe(0);
+    h.set({ progressKey: "10" });
+    expect(h.settles).toBe(1);
+    h.pagination.dispose();
   });
-
-  it("waits for anchored page geometry before authorizing another page", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const inFlight = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      isLoadingOlderHistory: true,
-    });
-    const pageApplied = evaluateHistoryStartPagination(inFlight.state, {
-      ...visibleHistoryStart,
-      isLoadingOlderHistory: true,
-      progressKey: "epoch-1:10",
-    });
-
-    expect([first.shouldLoad, inFlight.shouldLoad, pageApplied.shouldLoad]).toEqual([
-      true,
-      false,
-      false,
-    ]);
-    expect(pageApplied.state).toEqual({ status: "settling", loadedProgressKey: "epoch-1:10" });
+  it("continues short pages and reveals on exhaustion", async () => {
+    const h = harness();
+    h.pagination.update();
+    h.set({ progressKey: "10" });
+    h.requests[0](true);
+    await Promise.resolve();
+    h.pagination.settle();
+    expect(h.requests).toHaveLength(2);
+    h.set({ hasOlderHistory: false });
+    h.requests[1](true);
+    await Promise.resolve();
+    expect(h.pagination.state).toEqual({ status: "dormant", visible: true });
+    h.pagination.dispose();
   });
-
-  it("loads one page each time anchored geometry leaves and returns to history start", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const pageApplied = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      progressKey: "epoch-1:10",
-    });
-    const settledAway = settleHistoryStartPagination(pageApplied.state, {
-      ...visibleHistoryStart,
-      distanceFromHistoryStart: 300,
-      progressKey: "epoch-1:10",
-    });
-    const returned = evaluateHistoryStartPagination(settledAway.state, {
-      ...visibleHistoryStart,
-      progressKey: "epoch-1:10",
-    });
-
-    expect([
-      first.shouldLoad,
-      pageApplied.shouldLoad,
-      settledAway.shouldLoad,
-      returned.shouldLoad,
-    ]).toEqual([true, false, false, true]);
+  it("releases a failed or stalled request and allows retry", async () => {
+    vi.useFakeTimers();
+    const h = harness();
+    h.pagination.update();
+    vi.advanceTimersByTime(15_000);
+    expect(h.pagination.state).toEqual({ status: "failed", visible: true });
+    h.pagination.rearm();
+    expect(h.requests).toHaveLength(2);
+    h.requests[1](false);
+    await Promise.resolve();
+    expect(h.pagination.state.status).toBe("failed");
+    h.pagination.dispose();
+    vi.useRealTimers();
   });
-
-  it("continues the same loading operation when anchored geometry remains at history start", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const pageApplied = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      progressKey: "epoch-1:10",
-    });
-    const continued = settleHistoryStartPagination(pageApplied.state, {
-      ...visibleHistoryStart,
-      progressKey: "epoch-1:10",
-    });
-
-    expect(continued.shouldLoad).toBe(true);
-    expect(isHistoryStartLoadingOperation(first.state)).toBe(true);
-    expect(isHistoryStartLoadingOperation(pageApplied.state)).toBe(true);
-    expect(isHistoryStartLoadingOperation(continued.state)).toBe(true);
+  it("keeps visible history visible while filling", () => {
+    const h = harness(true);
+    h.pagination.update();
+    expect(h.pagination.state.visible).toBe(true);
+    h.pagination.dispose();
   });
-
-  it("latches a request that finishes without cursor progress", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const inFlight = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      isLoadingOlderHistory: true,
-    });
-    const finished = evaluateHistoryStartPagination(inFlight.state, visibleHistoryStart);
-    const duplicate = evaluateHistoryStartPagination(finished.state, visibleHistoryStart);
-    const away = evaluateHistoryStartPagination(duplicate.state, {
-      ...visibleHistoryStart,
-      distanceFromHistoryStart: 300,
-    });
-
-    expect(finished.state).toEqual({ status: "latched" });
-    expect([finished.shouldLoad, duplicate.shouldLoad, away.shouldLoad]).toEqual([
-      false,
-      false,
-      false,
-    ]);
-    expect(away.state).toEqual({ status: "ready" });
+  it("does not load a full viewport until user intent and respects inactive views", () => {
+    const h = harness();
+    h.set({ isUnderfilled: false });
+    expect(h.requests).toHaveLength(0);
+    h.set({ isReady: false });
+    h.pagination.rearm();
+    expect(h.requests).toHaveLength(0);
+    h.set({ isReady: true });
+    expect(h.requests).toHaveLength(1);
+    h.pagination.dispose();
   });
-
-  it("allows another user attempt after a request finishes without progress", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const inFlight = evaluateHistoryStartPagination(first.state, {
-      ...visibleHistoryStart,
-      isLoadingOlderHistory: true,
-    });
-    const failed = evaluateHistoryStartPagination(inFlight.state, visibleHistoryStart);
-    const retried = evaluateHistoryStartPagination(
-      rearmHistoryStartPagination(failed.state),
-      visibleHistoryStart,
-    );
-
-    expect(failed.state).toEqual({ status: "latched" });
-    expect(retried.shouldLoad).toBe(true);
-  });
-
-  it("latches an attempt that becomes invalid before entering flight", () => {
-    const requested = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-
-    expect(abandonHistoryStartPaginationRequest(requested.state, "epoch-1:20")).toEqual({
-      status: "latched",
-    });
-  });
-
-  it("does not mistake repeated edge observations for a finished request", () => {
-    const first = evaluateHistoryStartPagination(
-      createArmedHistoryStartPaginationState(),
-      visibleHistoryStart,
-    );
-    const repeated = evaluateHistoryStartPagination(first.state, visibleHistoryStart);
-
-    expect(repeated.state).toBe(first.state);
-    expect(repeated.shouldLoad).toBe(false);
-  });
-
-  it("waits while history loading is unavailable or already active", () => {
-    const state = createArmedHistoryStartPaginationState();
-
-    expect([
-      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, isReady: false }).shouldLoad,
-      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, hasOlderHistory: false })
-        .shouldLoad,
-      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, isLoadingOlderHistory: true })
-        .shouldLoad,
-      evaluateHistoryStartPagination(state, { ...visibleHistoryStart, progressKey: null })
-        .shouldLoad,
-    ]).toEqual([false, false, false, false]);
+  it("preserves the reading position after an anchored page moves away from the start", async () => {
+    const h = harness(true);
+    h.set({ isUnderfilled: false });
+    h.pagination.rearm();
+    h.set({ progressKey: "10", distanceFromHistoryStart: 300 });
+    h.requests[0](true);
+    await Promise.resolve();
+    h.pagination.settle();
+    expect(h.requests).toHaveLength(1);
+    h.set({ distanceFromHistoryStart: 0 });
+    expect(h.requests).toHaveLength(2);
+    h.pagination.dispose();
   });
 });
+
+it("ignores a timed-out response after the reader retries", async () => {
+  vi.useFakeTimers();
+  const h = harness();
+  h.pagination.update();
+  vi.advanceTimersByTime(15_000);
+  h.pagination.rearm();
+  h.requests[0](true);
+  await Promise.resolve();
+  expect(h.pagination.state.status).toBe("loading");
+  expect(h.settles).toBe(0);
+  h.requests[1](false);
+  await Promise.resolve();
+  expect(h.pagination.state.status).toBe("failed");
+  h.pagination.dispose();
+  vi.useRealTimers();
+});
+
+it("does not repeat a successful page that made no progress", async () => {
+  vi.useFakeTimers();
+  const h = harness();
+  h.pagination.update();
+  h.requests[0](true);
+  await Promise.resolve();
+  h.pagination.update();
+  expect(h.requests).toHaveLength(1);
+  vi.advanceTimersByTime(15_000);
+  expect(h.pagination.state).toEqual({ status: "failed", visible: true });
+  h.pagination.dispose();
+  vi.useRealTimers();
+});
+
+it("waits until the cursor and active history are available", () => {
+  const h = harness();
+  h.set({ isReady: false, progressKey: null });
+  h.set({ isReady: true, isLoadingOlderHistory: true });
+  h.set({ isLoadingOlderHistory: false });
+  expect(h.requests).toHaveLength(0);
+  h.set({ progressKey: "20" });
+  expect(h.requests).toHaveLength(1);
+  h.pagination.dispose();
+});
+
+it("reveals immediately on exhausted history without offering retry", () => {
+  const h = harness();
+  h.set({ hasOlderHistory: false });
+  expect(h.requests).toHaveLength(0);
+  expect(h.pagination.state).toEqual({ status: "dormant", visible: true });
+  h.pagination.dispose();
+});
+
+it("keeps a settled page pending while its view is inactive", async () => {
+  const h = harness();
+  h.pagination.update();
+  h.set({ progressKey: "10" });
+  h.requests[0](true);
+  await Promise.resolve();
+  h.set({ isReady: false });
+  h.pagination.settle();
+  expect(h.pagination.state.status).toBe("settling");
+  expect(h.requests).toHaveLength(1);
+  h.set({ isReady: true, isUnderfilled: false });
+  h.pagination.settle();
+  expect(h.pagination.state).toEqual({ status: "dormant", visible: true });
+  h.pagination.dispose();
+});
+
+it("keeps cached history visible after synchronization and subsequent pagination", async () => {
+  const h = harness();
+  h.pagination.reveal();
+  h.pagination.update();
+  h.set({ progressKey: "10" });
+  h.requests[0](true);
+  await Promise.resolve();
+  h.pagination.settle();
+  expect(h.pagination.state.visible).toBe(true);
+  expect(h.requests).toHaveLength(2);
+  h.pagination.dispose();
+});
+
+it.each([true, false])(
+  "handles native padding when short history has older=%s",
+  (hasOlderHistory) => {
+    const geometry = nativeHistoryStartGeometry({
+      contentHeight: 825,
+      viewportHeight: 700,
+      offsetY: 125,
+      topOverlayInset: 123,
+    });
+    let requests = 0;
+    const pagination = createHistoryStartPagination({
+      initiallyVisible: false,
+      read: () => ({ ...initial, ...geometry, hasOlderHistory }),
+      load: () => {
+        requests++;
+        return new Promise<boolean>(() => {});
+      },
+      changed: () => {},
+      scheduleSettle: () => {},
+    });
+    pagination.update();
+    expect(requests).toBe(hasOlderHistory ? 1 : 0);
+    expect(pagination.state.visible).toBe(!hasOlderHistory);
+    pagination.dispose();
+  },
+);
+
+it("uses the forward native list's top edge to request older history", () => {
+  let offsetY = 1300;
+  let requests = 0;
+  const pagination = createHistoryStartPagination({
+    initiallyVisible: true,
+    read: () => ({
+      ...initial,
+      ...nativeHistoryStartGeometry({
+        contentHeight: 2000,
+        viewportHeight: 700,
+        offsetY,
+        topOverlayInset: 123,
+      }),
+    }),
+    load: () => {
+      requests++;
+      return new Promise<boolean>(() => {});
+    },
+    changed: () => {},
+    scheduleSettle: () => {},
+  });
+  pagination.rearm();
+  expect(requests).toBe(0);
+  offsetY = 155;
+  pagination.update();
+  expect(requests).toBe(1);
+  pagination.dispose();
+});
+
+it.each([null, { ...initial, isReady: false }])(
+  "resumes a completed page after its view stays inactive beyond the deadline (%j)",
+  async (inactive) => {
+    vi.useFakeTimers();
+    let geometry: HistoryStartPaginationInput | null = { ...initial };
+    let complete!: (applied: boolean) => void;
+    let requests = 0;
+    const pagination = createHistoryStartPagination({
+      initiallyVisible: false,
+      read: () => geometry,
+      load: () => {
+        requests++;
+        return new Promise<boolean>((resolve) => {
+          complete = resolve;
+        });
+      },
+      changed: () => {},
+      scheduleSettle: () => {},
+    });
+    try {
+      pagination.update();
+      geometry = inactive;
+      pagination.update();
+      complete(true);
+      await Promise.resolve();
+      vi.advanceTimersByTime(30_000);
+      expect(pagination.state.status).toBe("loading");
+      geometry = { ...initial, progressKey: "10" };
+      pagination.update();
+      expect(pagination.state.status).toBe("settling");
+      geometry = inactive;
+      pagination.update();
+      pagination.settle();
+      vi.advanceTimersByTime(30_000);
+      expect(pagination.state.status).toBe("settling");
+      geometry = { ...initial, progressKey: "10" };
+      pagination.update();
+      pagination.settle();
+      expect(requests).toBe(2);
+      expect(pagination.state.status).toBe("loading");
+      vi.advanceTimersByTime(15_000);
+      expect(pagination.state.status).toBe("failed");
+    } finally {
+      pagination.dispose();
+      vi.useRealTimers();
+    }
+  },
+);
diff --git a/packages/app/src/agent-stream/history-start-pagination.ts b/packages/app/src/agent-stream/history-start-pagination.ts
index 46914ae3e1..9931d4d469 100644
--- a/packages/app/src/agent-stream/history-start-pagination.ts
+++ b/packages/app/src/agent-stream/history-start-pagination.ts
@@ -1,138 +1,149 @@
 export const HISTORY_START_THRESHOLD_PX = 96;
 
-export type HistoryStartPaginationState =
-  | { status: "dormant" }
-  | { status: "ready" }
-  | { status: "loading"; requestedProgressKey: string; requestObserved: boolean }
-  | { status: "settling"; loadedProgressKey: string }
-  | { status: "latched" };
-
 export interface HistoryStartPaginationInput {
   distanceFromHistoryStart: number;
+  isUnderfilled: boolean;
   hasOlderHistory: boolean;
   isLoadingOlderHistory: boolean;
   isReady: boolean;
   progressKey: string | null;
 }
 
-export interface HistoryStartPaginationTransition {
-  state: HistoryStartPaginationState;
-  shouldLoad: boolean;
-}
-
-export function createHistoryStartPaginationState(): HistoryStartPaginationState {
-  return { status: "dormant" };
+export interface HistoryStartPaginationState {
+  status: "dormant" | "ready" | "loading" | "settling" | "failed";
+  visible: boolean;
 }
 
 export function isHistoryStartLoadingOperation(state: HistoryStartPaginationState): boolean {
   return state.status === "loading" || state.status === "settling";
 }
 
-export function rearmHistoryStartPagination(
-  state: HistoryStartPaginationState,
-): HistoryStartPaginationState {
-  return state.status === "dormant" || state.status === "latched" ? { status: "ready" } : state;
-}
+/** Owns one pagination operation, including the initial viewport reveal. */
+export function createHistoryStartPagination(input: {
+  initiallyVisible: boolean;
+  read: () => HistoryStartPaginationInput | null;
+  load: () => Promise<boolean>;
+  changed: (state: HistoryStartPaginationState) => void;
+  scheduleSettle: () => void;
+}) {
+  let state: HistoryStartPaginationState = { status: "dormant", visible: input.initiallyVisible };
+  let requestedKey: string | null = null;
+  let completed = false;
+  let fill = false;
+  let generation = 0;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
 
-export function abandonHistoryStartPaginationRequest(
-  state: HistoryStartPaginationState,
-  requestedProgressKey: string,
-): HistoryStartPaginationState {
-  if (
-    state.status !== "loading" ||
-    state.requestObserved ||
-    state.requestedProgressKey !== requestedProgressKey
-  ) {
-    return state;
-  }
-  return { status: "latched" };
-}
+  const publish = (status: HistoryStartPaginationState["status"], visible = state.visible) => {
+    if (status === state.status && visible === state.visible) return;
+    state = { status, visible };
+    input.changed(state);
+  };
+  const clear = () => {
+    generation++;
+    clearTimeout(timeout);
+    timeout = undefined;
+  };
+  const finish = (status: HistoryStartPaginationState["status"]) => {
+    clear();
+    publish(status, true);
+  };
+  const fail = () => finish("failed");
 
-export function evaluateHistoryStartPagination(
-  state: HistoryStartPaginationState,
-  input: HistoryStartPaginationInput,
-): HistoryStartPaginationTransition {
-  if (state.status === "dormant") {
-    return { state, shouldLoad: false };
-  }
-  if (state.status === "loading") {
-    if (input.progressKey !== null && input.progressKey !== state.requestedProgressKey) {
-      return {
-        state: { status: "settling", loadedProgressKey: input.progressKey },
-        shouldLoad: false,
-      };
+  const watchProgress = (geometry: HistoryStartPaginationInput | null) => {
+    if (completed && !geometry?.isReady) {
+      clearTimeout(timeout);
+      timeout = undefined;
+    } else if (timeout === undefined) {
+      const request = generation;
+      timeout = setTimeout(() => {
+        timeout = undefined;
+        // A completed request waits for its retained view to become measurable again.
+        // Unfinished requests still time out even while the view is inactive.
+        if (request === generation && (!completed || input.read()?.isReady)) fail();
+      }, 15_000);
     }
-    if (input.isLoadingOlderHistory && !state.requestObserved) {
-      return { state: { ...state, requestObserved: true }, shouldLoad: false };
-    }
-    if (!input.isLoadingOlderHistory && !input.hasOlderHistory) {
-      return { state: { status: "latched" }, shouldLoad: false };
-    }
-    if (
-      state.requestObserved &&
-      !input.isLoadingOlderHistory &&
-      input.progressKey === state.requestedProgressKey
-    ) {
-      return { state: { status: "latched" }, shouldLoad: false };
-    }
-    return { state, shouldLoad: false };
-  }
+  };
 
-  if (state.status === "settling") {
-    return { state, shouldLoad: false };
-  }
-
-  const isAtHistoryStart = input.distanceFromHistoryStart <= HISTORY_START_THRESHOLD_PX;
-  if (!isAtHistoryStart) {
-    return state.status === "ready"
-      ? { state, shouldLoad: false }
-      : { state: { status: "ready" }, shouldLoad: false };
-  }
-  if (
-    state.status === "latched" ||
-    !input.isReady ||
-    !input.hasOlderHistory ||
-    input.isLoadingOlderHistory ||
-    input.progressKey === null
-  ) {
-    return { state, shouldLoad: false };
-  }
+  const update = () => {
+    const geometry = input.read();
+    if (isHistoryStartLoadingOperation(state)) watchProgress(geometry);
+    if (!geometry) return;
+    if (state.status === "loading") {
+      if (!completed) return;
+      if (geometry.progressKey !== null && geometry.progressKey !== requestedKey) {
+        publish("settling");
+        input.scheduleSettle();
+      } else if (!geometry.hasOlderHistory) {
+        finish("dormant");
+      }
+      return;
+    }
+    if (state.status === "settling" || state.status === "failed" || !geometry.isReady) return;
+    const atStart = geometry.distanceFromHistoryStart <= HISTORY_START_THRESHOLD_PX;
+    if (state.status === "dormant" && !geometry.isUnderfilled) {
+      publish("dormant", true);
+      return;
+    }
+    if (!atStart || (!geometry.isUnderfilled && state.status !== "ready")) return;
+    if (!geometry.hasOlderHistory) {
+      finish("dormant");
+      return;
+    }
+    if (geometry.isLoadingOlderHistory || geometry.progressKey === null) return;
+    fill = geometry.isUnderfilled;
+    requestedKey = geometry.progressKey;
+    completed = false;
+    publish("loading");
+    const request = ++generation;
+    watchProgress(geometry);
+    void input.load().then(
+      (applied) => {
+        if (request !== generation) return undefined;
+        if (!applied) {
+          fail();
+          return undefined;
+        }
+        completed = true;
+        update();
+        return undefined;
+      },
+      () => {
+        if (request === generation) fail();
+      },
+    );
+  };
   return {
-    state: {
-      status: "loading",
-      requestedProgressKey: input.progressKey,
-      requestObserved: false,
+    get state() {
+      return state;
     },
-    shouldLoad: true,
-  };
-}
-
-export function settleHistoryStartPagination(
-  state: HistoryStartPaginationState,
-  input: HistoryStartPaginationInput,
-): HistoryStartPaginationTransition {
-  if (state.status !== "settling") {
-    return { state, shouldLoad: false };
-  }
-  const isAtHistoryStart = input.distanceFromHistoryStart <= HISTORY_START_THRESHOLD_PX;
-  if (
-    !isAtHistoryStart ||
-    !input.isReady ||
-    !input.hasOlderHistory ||
-    input.isLoadingOlderHistory ||
-    input.progressKey === null
-  ) {
-    return {
-      state: isAtHistoryStart ? { status: "latched" } : { status: "ready" },
-      shouldLoad: false,
-    };
-  }
-  return {
-    state: {
-      status: "loading",
-      requestedProgressKey: input.progressKey,
-      requestObserved: false,
+    update,
+    settle() {
+      if (state.status !== "settling") return;
+      const geometry = input.read();
+      if (!geometry?.isReady) return;
+      clear();
+      if (fill && !geometry.isUnderfilled) {
+        publish("dormant", true);
+      } else if (geometry.distanceFromHistoryStart > HISTORY_START_THRESHOLD_PX) {
+        publish("ready", true);
+      } else if (!geometry.hasOlderHistory) {
+        publish("dormant", true);
+      } else {
+        publish("ready");
+        update();
+      }
     },
-    shouldLoad: true,
+    rearm() {
+      if (state.status === "dormant" || state.status === "failed") publish("ready", true);
+      update();
+    },
+    reveal() {
+      publish(state.status, true);
+    },
+    reset(visible: boolean) {
+      clear();
+      publish("dormant", visible);
+    },
+    dispose: clear,
   };
 }
diff --git a/packages/app/src/agent-stream/layout.test.ts b/packages/app/src/agent-stream/layout.test.ts
index a86817b6a7..fde9a3a342 100644
--- a/packages/app/src/agent-stream/layout.test.ts
+++ b/packages/app/src/agent-stream/layout.test.ts
@@ -289,7 +289,7 @@ describe("layoutStream", () => {
     expect(layout.auxiliaryTurnFooter).toBeNull();
     expect(assistantRow.completedFooter?.itemId).toBe(assistant.id);
     expect(assistantRow.belowItem?.id).toBe("u2");
-    expect(assistantRow.frameOrder).toBe("footer-then-content");
+    expect(assistantRow.frameOrder).toBe("content-then-footer");
   });
 
   it("keeps an accepted steer inline while its canonical turn is active", () => {
diff --git a/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx b/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
new file mode 100644
index 0000000000..338fa84008
--- /dev/null
+++ b/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
@@ -0,0 +1,266 @@
+import { LegendList, type LegendListRef } from "@legendapp/list/react-native";
+import React, { act, useSyncExternalStore } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { View } from "react-native";
+import { afterEach, beforeEach, expect, it } from "vitest";
+import { disclosureAnchor } from "./native-disclosure-hold";
+
+// The native chat timeline runs on the patched LegendList (patches/@legendapp+list+3.7.1.patch).
+// A disclosure hold keeps only the held row in place: `shouldRestorePosition` accepts no other row.
+// The native build applies its scroll adjustments through native scroll props that
+// react-native-web ignores, so these tests read the offset LegendList holds, not the DOM's.
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const VIEWPORT_HEIGHT = 100;
+
+interface Row {
+  id: string;
+  height: number;
+}
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  host.style.cssText = `display:flex;flex-direction:column;width:300px;height:${VIEWPORT_HEIGHT}px`;
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  grownHeights.clear();
+  host.remove();
+});
+
+function wait(ms: number): Promise<void> {
+  return act(() => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+}
+
+const LIST_STYLE = { flex: 1 };
+const rowStyles = new Map<number, { height: number }>();
+
+function rowStyle(height: number) {
+  let style = rowStyles.get(height);
+  if (!style) {
+    style = { height };
+    rowStyles.set(height, style);
+  }
+  return style;
+}
+
+// A row that changes its own height without a data change, like a todo card toggling its details.
+const grownHeights = new Map<string, number>();
+const heightListeners = new Set<() => void>();
+
+function subscribeToHeights(listener: () => void) {
+  heightListeners.add(listener);
+  return () => heightListeners.delete(listener);
+}
+
+function growRow(id: string, height: number) {
+  grownHeights.set(id, height);
+  for (const listener of heightListeners) listener();
+}
+
+function RowView({ row }: { row: Row }) {
+  const height = useSyncExternalStore(
+    subscribeToHeights,
+    () => grownHeights.get(row.id) ?? row.height,
+  );
+  return <View style={rowStyle(height)} />;
+}
+
+function renderRow({ item }: { item: Row }) {
+  return <RowView row={item} />;
+}
+
+function holdOnly(heldRowId: string) {
+  return {
+    data: true,
+    size: true,
+    shouldRestorePosition: (item: Row) => item.id === heldRowId,
+  };
+}
+
+function keyExtractor(item: Row) {
+  return item.id;
+}
+
+function mountList(heldRowId: string) {
+  const listRef = React.createRef<LegendListRef>();
+  const maintainVisibleContentPosition = holdOnly(heldRowId);
+  const render = (data: Row[]) =>
+    act(() =>
+      root.render(
+        <LegendList
+          ref={listRef}
+          data={data}
+          renderItem={renderRow}
+          keyExtractor={keyExtractor}
+          estimatedItemSize={40}
+          recycleItems={false}
+          scrollEventThrottle={16}
+          maintainVisibleContentPosition={maintainVisibleContentPosition}
+          style={LIST_STYLE}
+        />,
+      ),
+    );
+  const scrollElement = () => {
+    const scroller = [...host.querySelectorAll<HTMLElement>("div")].find(
+      (element) => element.scrollHeight > element.clientHeight + 1,
+    );
+    if (!scroller) throw new Error("The list has no scroll element");
+    return scroller;
+  };
+  // Small steps: a large jump suspends LegendList's anchoring until the rows re-measure.
+  const scrollTo = async (offset: number) => {
+    for (let step = 20; step <= offset; step += 20) {
+      scrollElement().scrollTop = step;
+      await wait(150);
+    }
+  };
+  const heldRowTop = () => {
+    const state = listRef.current?.getState();
+    const position = state?.positionByKey(heldRowId);
+    if (state === undefined || position === undefined) {
+      throw new Error("The held row is not laid out");
+    }
+    return position - state.scroll;
+  };
+  const rowSize = (rowId: string) => listRef.current?.getState().sizes.get(rowId);
+  const rowBottom = (rowId: string) => {
+    const state = listRef.current?.getState();
+    const position = state?.positionByKey(rowId);
+    const size = state?.sizes.get(rowId);
+    if (state === undefined || position === undefined || size === undefined) {
+      throw new Error(`Row ${rowId} is not laid out`);
+    }
+    return position + size - state.scroll;
+  };
+  return { render, scrollTo, heldRowTop, rowSize, rowBottom };
+}
+
+it("anchors a data change on a held row whose top is above the viewport", async () => {
+  // The held row is a turn host whose prompt bubble is cut off at the top of the viewport, with a
+  // fully visible row below it. LegendList's ids in view start at that fully visible row.
+  const rows: Row[] = Array.from({ length: 10 }, (_, index) => ({
+    id: `row-${index}`,
+    height: index === 3 ? 60 : 40,
+  }));
+  const list = mountList("row-3");
+  list.render(rows);
+  await wait(150);
+  await list.scrollTo(140);
+  expect(list.heldRowTop()).toBe(-20);
+
+  const inserted: Row = { id: "inserted", height: 30 };
+  list.render([...rows.slice(0, 2), inserted, ...rows.slice(2)]);
+  await wait(150);
+
+  expect(list.heldRowTop()).toBe(-20);
+});
+
+it("anchors a size change on a held row whose top is above the viewport", async () => {
+  // The same cut-off row grows from its own state, so LegendList sees a size change only.
+  const rows: Row[] = Array.from({ length: 10 }, (_, index) => ({
+    id: `row-${index}`,
+    height: index === 3 ? 60 : 40,
+  }));
+  const list = mountList("row-3");
+  list.render(rows);
+  await wait(150);
+  await list.scrollTo(140);
+  expect(list.heldRowTop()).toBe(-20);
+
+  act(() => growRow("row-3", 260));
+  await wait(150);
+
+  expect(list.heldRowTop()).toBe(-20);
+});
+
+// A long message's show more sits under the text it opens, on the bottom edge of its row. The
+// strategy anchors the row below it, whose top is that bottom edge.
+const bottomTriggerRows: Row[] = Array.from({ length: 10 }, (_, index) => ({
+  id: `row-${index}`,
+  height: index === 3 ? 60 : 40,
+}));
+
+function mountBottomTriggerHold(rowId: string) {
+  const anchor = disclosureAnchor(bottomTriggerRows, rowId, "bottom");
+  if (anchor.kind !== "row") throw new Error(`Row ${rowId} has no row below it`);
+  return mountList(anchor.rowId);
+}
+
+it("keeps the bottom of a row whose trigger sits under its growing content", async () => {
+  const list = mountBottomTriggerHold("row-3");
+  list.render(bottomTriggerRows);
+  await wait(150);
+  await list.scrollTo(100);
+  const triggerBottom = list.rowBottom("row-3");
+  expect(triggerBottom).toBe(80);
+
+  act(() => growRow("row-3", 260));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(triggerBottom);
+
+  act(() => growRow("row-3", 60));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(triggerBottom);
+});
+
+it("keeps the bottom of a bottom-trigger row whose top is above the viewport", async () => {
+  const list = mountBottomTriggerHold("row-3");
+  list.render(bottomTriggerRows);
+  await wait(150);
+  await list.scrollTo(140);
+  const triggerBottom = list.rowBottom("row-3");
+  expect(triggerBottom).toBe(40);
+
+  act(() => growRow("row-3", 260));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(triggerBottom);
+
+  act(() => growRow("row-3", 60));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(triggerBottom);
+});
+
+it("keeps the bottom of a bottom-trigger row that ends below the viewport", async () => {
+  // In the app the row ends with the message's timestamp under the trigger, so a trigger near the
+  // bottom of the viewport has its row's bottom, and the row below, out of view.
+  const list = mountBottomTriggerHold("row-3");
+  list.render(bottomTriggerRows);
+  await wait(150);
+  await list.scrollTo(40);
+  const rowBottom = list.rowBottom("row-3");
+  expect(rowBottom).toBe(140);
+
+  act(() => growRow("row-3", 260));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(rowBottom);
+
+  act(() => growRow("row-3", 60));
+  await wait(150);
+  expect(list.rowBottom("row-3")).toBe(rowBottom);
+});
+
+it("keeps measured row sizes while the list is not laid out", async () => {
+  // A hidden retained tab is display: none. Its rows still render, and a row measured there
+  // reports 0 x 0. When the tab shows again, a row whose frame did not change gets no new layout
+  // event, so a 0 recorded while hidden would stay and the next row would overlap it.
+  const rows: Row[] = Array.from({ length: 3 }, (_, index) => ({ id: `row-${index}`, height: 40 }));
+  const list = mountList("row-0");
+  list.render(rows);
+  await wait(150);
+  expect(rows.map((row) => list.rowSize(row.id))).toEqual([40, 40, 40]);
+
+  host.style.display = "none";
+  await wait(150);
+  list.render(rows.map((row) => ({ ...row })));
+  await wait(150);
+
+  expect(rows.map((row) => list.rowSize(row.id))).toEqual([40, 40, 40]);
+});
diff --git a/packages/app/src/agent-stream/model.test.ts b/packages/app/src/agent-stream/model.test.ts
index 9c6ef3384d..bf6ce27f75 100644
--- a/packages/app/src/agent-stream/model.test.ts
+++ b/packages/app/src/agent-stream/model.test.ts
@@ -47,7 +47,7 @@ describe("buildAgentStreamRenderModel", () => {
       historyStart: 2,
     });
 
-    expect(model.history.map((item) => item.id)).toEqual(["a3", "u3", "a2", "u2"]);
+    expect(model.history.map((item) => item.id)).toEqual(["u2", "a2", "u3", "a3"]);
     expect(model.segments.historyVirtualized).toHaveLength(0);
   });
 
@@ -98,7 +98,7 @@ describe("buildAgentStreamRenderModel", () => {
       historyStart,
     });
 
-    expect(model.history.map((item) => item.id)).toEqual(["visible-a", "visible-u"]);
+    expect(model.history.map((item) => item.id)).toEqual(["visible-u", "visible-a"]);
   });
 
   it("keeps head separate from committed history on desktop web", () => {
@@ -207,7 +207,7 @@ describe("buildAgentStreamRenderModel", () => {
     });
   });
 
-  it("derives the same timing for native inverted rendering", () => {
+  it("derives the same timing on native", () => {
     const tail = [userMessage("u1", 1), assistantMessage("a1", 4)];
 
     const model = buildAgentStreamRenderModel({
@@ -219,7 +219,7 @@ describe("buildAgentStreamRenderModel", () => {
       isMobileBreakpoint: false,
     });
 
-    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["a1", "u1"]);
+    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["u1", "a1"]);
     expect(model.turnTiming.byItemId.get("a1")).toEqual({
       completedAt: tail[1]?.timestamp,
       durationMs: 3000,
diff --git a/packages/app/src/agent-stream/native-disclosure-hold.test.ts b/packages/app/src/agent-stream/native-disclosure-hold.test.ts
new file mode 100644
index 0000000000..507ca07700
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.test.ts
@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest";
+import {
+  createNativeDisclosureHold,
+  disclosureAnchor,
+  createEndHoldDistance,
+  type DisclosureAnchor,
+} from "./native-disclosure-hold";
+
+function createFrames() {
+  let nextId = 1;
+  const pending = new Map<number, () => void>();
+  return {
+    requestFrame: (callback: () => void) => {
+      const id = nextId++;
+      pending.set(id, callback);
+      return id;
+    },
+    cancelFrame: (id: number) => {
+      pending.delete(id);
+    },
+    runFrame: () => {
+      const callbacks = [...pending.values()];
+      pending.clear();
+      for (const callback of callbacks) {
+        callback();
+      }
+    },
+  };
+}
+
+function createHarness() {
+  const frames = createFrames();
+  const releases: string[] = [];
+  const hold = createNativeDisclosureHold({
+    quietFrames: 2,
+    requestFrame: frames.requestFrame,
+    cancelFrame: frames.cancelFrame,
+    onRelease: () => releases.push("released"),
+  });
+  return { frames, hold, releases };
+}
+
+describe("native disclosure hold", () => {
+  it("holds the row until two frames pass without an item size change", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold({ kind: "row", rowId: "turn-1" });
+    frames.runFrame();
+
+    expect(hold.anchorRowId()).toBe("turn-1");
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(hold.anchorRowId()).toBeNull();
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("restarts the quiet frames on every item size change", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold({ kind: "row", rowId: "turn-1" });
+    frames.runFrame();
+    hold.noteItemSizeChanged();
+    frames.runFrame();
+
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("ignores item size changes outside a hold", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.noteItemSizeChanged();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(releases).toEqual([]);
+  });
+
+  it("moves the hold to the latest toggled row and releases once", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold({ kind: "row", rowId: "turn-1" });
+    frames.runFrame();
+    hold.hold({ kind: "row", rowId: "turn-2" });
+
+    expect(hold.anchorRowId()).toBe("turn-2");
+
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("drops the hold without releasing when cancelled", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold({ kind: "row", rowId: "turn-1" });
+    hold.cancel();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(hold.anchorRowId()).toBeNull();
+    expect(releases).toEqual([]);
+  });
+
+  it("holds the content end until two quiet frames pass, with no row to anchor on", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold({ kind: "end" });
+    frames.runFrame();
+    hold.noteItemSizeChanged();
+    frames.runFrame();
+
+    expect(hold.anchorRowId()).toBeNull();
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(releases).toEqual(["released"]);
+  });
+});
+
+describe("next-frame disclosure hold", () => {
+  it("anchors the row a reply landed as while the toggle waited for its frame", () => {
+    const { frames, hold } = createHarness();
+    let anchor: DisclosureAnchor = { kind: "end" };
+    const applied: DisclosureAnchor[] = [];
+
+    hold.holdNextFrame(
+      () => anchor,
+      (resolved) => applied.push(resolved),
+    );
+    expect(applied).toEqual([]);
+
+    anchor = { kind: "row", rowId: "turn-2" };
+    frames.runFrame();
+
+    expect(hold.anchorRowId()).toBe("turn-2");
+    expect(applied).toEqual([{ kind: "row", rowId: "turn-2" }]);
+  });
+
+  it("still lands the toggle when the hold is cancelled before its frame", () => {
+    const { frames, hold, releases } = createHarness();
+    const applied: DisclosureAnchor[] = [];
+
+    hold.holdNextFrame(
+      () => ({ kind: "end" }),
+      (resolved) => applied.push(resolved),
+    );
+    hold.cancel();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(applied).toEqual([{ kind: "end" }]);
+    expect(releases).toEqual([]);
+  });
+
+  it("lands a waiting toggle before the next hold starts", () => {
+    const { frames, hold } = createHarness();
+    const applied: DisclosureAnchor[] = [];
+
+    hold.holdNextFrame(
+      () => ({ kind: "end" }),
+      (resolved) => applied.push(resolved),
+    );
+    hold.hold({ kind: "row", rowId: "turn-1" });
+
+    expect(applied).toEqual([{ kind: "end" }]);
+    frames.runFrame();
+    expect(applied).toEqual([{ kind: "end" }]);
+    expect(hold.anchorRowId()).toBe("turn-1");
+  });
+});
+
+describe("disclosure anchor", () => {
+  const rows = [{ id: "message-1" }, { id: "turn-1" }, { id: "message-2" }];
+
+  it("keeps the top of a row whose trigger sits on its top edge", () => {
+    expect(disclosureAnchor(rows, "turn-1", "top")).toEqual({ kind: "row", rowId: "turn-1" });
+  });
+
+  it("keeps the top of the row below a row whose trigger sits on its bottom edge", () => {
+    expect(disclosureAnchor(rows, "message-1", "bottom")).toEqual({
+      kind: "row",
+      rowId: "turn-1",
+    });
+  });
+
+  // A prompt the agent has not answered yet is the last row; the running indicator is the footer.
+  it("keeps the content end for a bottom-edge trigger on the last row", () => {
+    expect(disclosureAnchor(rows, "message-2", "bottom")).toEqual({ kind: "end" });
+  });
+
+  // The strategy re-derives this each render, so a reply lets go of the end in the commit it lands.
+  it("stops keeping the content end once a reply lands below the row", () => {
+    expect(disclosureAnchor([...rows, { id: "turn-2" }], "message-2", "bottom")).toEqual({
+      kind: "row",
+      rowId: "turn-2",
+    });
+  });
+});
+
+describe("end hold distance", () => {
+  const viewportHeight = 600;
+
+  it("keeps the distance from the end the toggle started at", () => {
+    const distance = createEndHoldDistance(20);
+
+    distance.noteContentSize({ contentHeight: 2000, viewportHeight });
+
+    expect(distance.current()).toBe(20);
+  });
+
+  it("shrinks to the scroll room a collapse leaves", () => {
+    const distance = createEndHoldDistance(20);
+
+    distance.noteContentSize({ contentHeight: 610, viewportHeight });
+
+    expect(distance.current()).toBe(10);
+  });
+
+  it("stays at the end when output grows the content after a collapse reached the end", () => {
+    const distance = createEndHoldDistance(20);
+
+    distance.noteContentSize({ contentHeight: 600, viewportHeight });
+    distance.noteContentSize({ contentHeight: 700, viewportHeight });
+
+    expect(distance.current()).toBe(0);
+  });
+});
diff --git a/packages/app/src/agent-stream/native-disclosure-hold.ts b/packages/app/src/agent-stream/native-disclosure-hold.ts
new file mode 100644
index 0000000000..7dc7a55bd0
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.ts
@@ -0,0 +1,142 @@
+import type { DisclosureTriggerEdge } from "./strategy";
+
+/** What a disclosure hold keeps in place: the top of a row, or the end of the content. */
+export type DisclosureAnchor = { kind: "row"; rowId: string } | { kind: "end" };
+
+/**
+ * The native viewport's disclosure hold. While it holds a row anchor, that row is the only row the
+ * list may anchor on (`disclosureAnchor`). The hold ends once item sizes stop changing for
+ * `quietFrames` frames: the list measures the toggled row and any rows it inserted over one or more
+ * frames, and end following must not resume between the change and the list's last layout
+ * correction.
+ */
+export interface NativeDisclosureHold {
+  /** The row the list may anchor on; null outside a hold and while the hold keeps the end. */
+  anchorRowId(): string | null;
+  hold(anchor: DisclosureAnchor): void;
+  /**
+   * Holds on the next frame and runs `apply` there, for a toggle that has to land after a commit
+   * already on its way. `resolveAnchor` runs in that frame, because rows may land while it waits.
+   * A later hold or a cancel lands a waiting toggle right away.
+   */
+  holdNextFrame(
+    resolveAnchor: () => DisclosureAnchor,
+    apply: (anchor: DisclosureAnchor) => void,
+  ): void;
+  noteItemSizeChanged(): void;
+  /** Drops the hold without releasing it. */
+  cancel(): void;
+}
+
+export function createNativeDisclosureHold(input: {
+  quietFrames: number;
+  requestFrame: (callback: () => void) => number;
+  cancelFrame: (id: number) => void;
+  onRelease: () => void;
+}): NativeDisclosureHold {
+  let anchor: DisclosureAnchor | null = null;
+  let frameId: number | null = null;
+  let remainingFrames = 0;
+  let waitingToggle: { frameId: number; land: () => void } | null = null;
+
+  const stopCountdown = () => {
+    if (frameId !== null) {
+      input.cancelFrame(frameId);
+      frameId = null;
+    }
+  };
+
+  const tick = () => {
+    remainingFrames -= 1;
+    if (remainingFrames > 0) {
+      frameId = input.requestFrame(tick);
+      return;
+    }
+    frameId = null;
+    anchor = null;
+    input.onRelease();
+  };
+
+  const restartCountdown = () => {
+    stopCountdown();
+    remainingFrames = input.quietFrames;
+    frameId = input.requestFrame(tick);
+  };
+
+  const landWaitingToggle = () => {
+    if (!waitingToggle) return;
+    const { frameId: waitingFrameId, land } = waitingToggle;
+    waitingToggle = null;
+    input.cancelFrame(waitingFrameId);
+    land();
+  };
+
+  const startHold = (nextAnchor: DisclosureAnchor) => {
+    anchor = nextAnchor;
+    restartCountdown();
+  };
+
+  return {
+    anchorRowId: () => (anchor?.kind === "row" ? anchor.rowId : null),
+    hold(nextAnchor) {
+      landWaitingToggle();
+      startHold(nextAnchor);
+    },
+    holdNextFrame(resolveAnchor, apply) {
+      landWaitingToggle();
+      const waitingFrameId = input.requestFrame(() => {
+        waitingToggle = null;
+        const nextAnchor = resolveAnchor();
+        startHold(nextAnchor);
+        apply(nextAnchor);
+      });
+      waitingToggle = { frameId: waitingFrameId, land: () => apply(resolveAnchor()) };
+    },
+    noteItemSizeChanged() {
+      if (anchor !== null) {
+        restartCountdown();
+      }
+    },
+    cancel() {
+      landWaitingToggle();
+      stopCountdown();
+      anchor = null;
+    },
+  };
+}
+
+/**
+ * What the list keeps in place while a disclosure toggles `rowId`. LegendList restores row tops, so
+ * a trigger on the bottom edge of its row anchors the row below: that row's top is the toggled
+ * row's bottom. The last row's bottom is the end of the content.
+ */
+export function disclosureAnchor(
+  rows: readonly { id: string }[],
+  rowId: string,
+  triggerEdge: DisclosureTriggerEdge,
+): DisclosureAnchor {
+  if (triggerEdge === "top") return { kind: "row", rowId };
+  const index = rows.findIndex((row) => row.id === rowId);
+  const below = rows[index + 1];
+  return below ? { kind: "row", rowId: below.id } : { kind: "end" };
+}
+
+/**
+ * The list's distance from the end during an end hold. The end pin keeps the distance through every
+ * content size change, and the scroll view clamps it to the scroll room the content has at that
+ * moment. A clamp is permanent: content that grows afterwards does not bring the distance back.
+ */
+export function createEndHoldDistance(distanceAtToggle: number): EndHoldDistance {
+  let distance = distanceAtToggle;
+  return {
+    noteContentSize({ contentHeight, viewportHeight }) {
+      distance = Math.min(distance, Math.max(0, contentHeight - viewportHeight));
+    },
+    current: () => distance,
+  };
+}
+
+export interface EndHoldDistance {
+  noteContentSize(input: { contentHeight: number; viewportHeight: number }): void;
+  current(): number;
+}
diff --git a/packages/app/src/agent-stream/native-end-pin.tsx b/packages/app/src/agent-stream/native-end-pin.tsx
new file mode 100644
index 0000000000..dced2bf4a0
--- /dev/null
+++ b/packages/app/src/agent-stream/native-end-pin.tsx
@@ -0,0 +1,61 @@
+import { forwardRef, type ReactNode } from "react";
+import {
+  Animated,
+  type ScrollView,
+  type ScrollViewProps,
+  View,
+  type ViewStyle,
+} from "react-native";
+
+// While the stream follows its end, React Native's native content-position keeping holds a
+// zero-height view at the bottom of the content still. It runs on the UI thread around each mount,
+// so a row that grows or lands at the end scrolls in the same frame it lays out. LegendList's
+// `maintainScrollAtEnd` scrolls from JS after the mount, which paints the growth below the viewport
+// for a frame or more first.
+//
+// The anchor has to be the content's first native child: content-position keeping anchors on the
+// first child at or after `minIndexForVisible` that reaches into the viewport, and every child
+// LegendList renders can be flattened away. Absolute positioning keeps it out of the flow.
+//
+// A drag owns the offset from the frame it begins, but the pin stays until JS stops following a
+// round trip later. The scroll view subclasses in `modules/paseo-scroll` recognise the pin by its
+// native ID and skip its correction while the user drags, so a line mounting in those frames grows
+// below the rows under the finger.
+const END_PIN_NATIVE_ID = "paseo-end-pin";
+const END_ANCHOR_STYLE: ViewStyle = {
+  position: "absolute",
+  bottom: 0,
+  left: 0,
+  height: 0,
+  width: 0,
+};
+const END_ANCHOR_POSITION = { minIndexForVisible: 0 };
+
+interface EndPinnedScrollViewProps extends ScrollViewProps {
+  pinEnd: boolean;
+  children?: ReactNode;
+}
+
+export const EndPinnedScrollView = forwardRef<ScrollView, EndPinnedScrollViewProps>(
+  function EndPinnedScrollView({ pinEnd, children, maintainVisibleContentPosition, ...rest }, ref) {
+    return (
+      <Animated.ScrollView
+        {...rest}
+        ref={ref}
+        maintainVisibleContentPosition={
+          pinEnd ? END_ANCHOR_POSITION : maintainVisibleContentPosition
+        }
+      >
+        {pinEnd ? (
+          <View
+            collapsable={false}
+            nativeID={END_PIN_NATIVE_ID}
+            pointerEvents="none"
+            style={END_ANCHOR_STYLE}
+          />
+        ) : null}
+        {children}
+      </Animated.ScrollView>
+    );
+  },
+);
diff --git a/packages/app/src/agent-stream/native-history-start-geometry.ts b/packages/app/src/agent-stream/native-history-start-geometry.ts
new file mode 100644
index 0000000000..6df65f48a1
--- /dev/null
+++ b/packages/app/src/agent-stream/native-history-start-geometry.ts
@@ -0,0 +1,12 @@
+export function nativeHistoryStartGeometry(input: {
+  contentHeight: number;
+  viewportHeight: number;
+  offsetY: number;
+  topOverlayInset: number;
+}) {
+  const contentHeight = input.contentHeight - 32 - input.topOverlayInset;
+  return {
+    distanceFromHistoryStart: Math.max(0, input.offsetY - input.topOverlayInset - 32),
+    isUnderfilled: contentHeight < input.viewportHeight,
+  };
+}
diff --git a/packages/app/src/agent-stream/native-scroll-animation.test.ts b/packages/app/src/agent-stream/native-scroll-animation.test.ts
index 947b8c3d1d..10508154a8 100644
--- a/packages/app/src/agent-stream/native-scroll-animation.test.ts
+++ b/packages/app/src/agent-stream/native-scroll-animation.test.ts
@@ -4,31 +4,48 @@ import { shouldAnimateNativeScrollToBottom } from "./native-scroll-animation";
 describe("native scroll-to-bottom animation", () => {
   it("jumps across unmounted history instead of animating through blank rows", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 60_000, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 60_000,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 
-  it("keeps near-bottom movement eligible for animation", () => {
+  it("keeps near-end movement eligible for animation", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 300, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 300,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(true);
   });
 
-  it("bounds travel by the bottom-side overscan, not the whole window", () => {
+  it("bounds travel by the rows mounted below the viewport", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 2700, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 1000,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(true);
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 2701, viewportHeight: 600, windowSize: 10 }),
-    ).toBe(false);
-    expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 1500, viewportHeight: 600, windowSize: 5 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 1001,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 
   it("does not animate before the viewport has been measured", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 0, viewportHeight: 0, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 0,
+        viewportHeight: 0,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 });
diff --git a/packages/app/src/agent-stream/native-scroll-animation.ts b/packages/app/src/agent-stream/native-scroll-animation.ts
index 72bc39108c..bd5a4966b6 100644
--- a/packages/app/src/agent-stream/native-scroll-animation.ts
+++ b/packages/app/src/agent-stream/native-scroll-animation.ts
@@ -1,10 +1,10 @@
 export function shouldAnimateNativeScrollToBottom(input: {
-  offsetY: number;
+  distanceFromEnd: number;
   viewportHeight: number;
-  windowSize: number;
+  drawDistance: number;
 }): boolean {
-  // VirtualizedList splits the extra window around the viewport. An animated
-  // jump farther than the bottom-side overscan crosses unmounted history.
-  const bottomOverscanHeight = ((input.windowSize - 1) / 2) * input.viewportHeight;
-  return input.viewportHeight > 0 && input.offsetY <= bottomOverscanHeight;
+  // Scrolled away from the end, LegendList keeps half its draw distance mounted below the
+  // viewport. An animated jump farther than that crosses rows it has not rendered.
+  const mountedBelowViewport = input.drawDistance / 2;
+  return input.viewportHeight > 0 && input.distanceFromEnd <= mountedBelowViewport;
 }
diff --git a/packages/app/src/agent-stream/near-bottom.ts b/packages/app/src/agent-stream/near-bottom.ts
new file mode 100644
index 0000000000..19de04b11a
--- /dev/null
+++ b/packages/app/src/agent-stream/near-bottom.ts
@@ -0,0 +1,44 @@
+import { useState, useSyncExternalStore } from "react";
+
+/**
+ * Whether the reader is at the end of the timeline. The viewport writes it and only the
+ * scroll-to-bottom button reads it, so detaching from the end (a scroll, or a disclosure
+ * that opens below its trigger) re-renders the button and not the timeline.
+ */
+export interface NearBottom {
+  set: (value: boolean) => void;
+  subscribe: (listener: () => void) => () => void;
+  get: () => boolean;
+}
+
+function createNearBottom(): NearBottom {
+  let value = true;
+  const listeners = new Set<() => void>();
+  return {
+    set: (next) => {
+      if (next === value) return;
+      value = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    get: () => value,
+  };
+}
+
+/** One per viewed agent; a newly viewed agent starts at the end. */
+export function useNearBottom(agentId: string): NearBottom {
+  const [owner, setOwner] = useState(() => ({ agentId, nearBottom: createNearBottom() }));
+  if (owner.agentId === agentId) return owner.nearBottom;
+  const next = { agentId, nearBottom: createNearBottom() };
+  setOwner(next);
+  return next.nearBottom;
+}
+
+export function useIsNearBottom(nearBottom: NearBottom): boolean {
+  return useSyncExternalStore(nearBottom.subscribe, nearBottom.get, nearBottom.get);
+}
diff --git a/packages/app/src/agent-stream/new-row-estimates.test.ts b/packages/app/src/agent-stream/new-row-estimates.test.ts
new file mode 100644
index 0000000000..d38c3fe3e0
--- /dev/null
+++ b/packages/app/src/agent-stream/new-row-estimates.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { createNewRowEstimates } from "./new-row-estimates";
+
+interface Row {
+  id: string;
+  kind: string;
+}
+
+function row(id: string, kind = "assistant_message"): Row {
+  return { id, kind };
+}
+
+describe("new row estimates", () => {
+  it("leaves rows of the first list to the list's averages", () => {
+    const estimates = createNewRowEstimates<Row>();
+    const first = row("a");
+
+    estimates.noteRows([first]);
+
+    expect(estimates.estimate(first)).toBeUndefined();
+  });
+
+  it("estimates a new row at the first measured size of the last new row of its kind", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([row("a")]);
+    const second = row("b");
+    estimates.noteRows([row("a"), second]);
+
+    expect(estimates.estimate(second)).toBeUndefined();
+
+    estimates.noteMeasured(second, 34);
+    estimates.noteMeasured(second, 56);
+    const third = row("c");
+    estimates.noteRows([row("a"), second, third]);
+
+    expect(estimates.estimate(third)).toBe(34);
+  });
+
+  it("keeps sizes per kind", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    const text = row("a");
+    const tool = row("b", "tool_call");
+    estimates.noteRows([text, tool]);
+    estimates.noteMeasured(text, 34);
+    estimates.noteMeasured(tool, 36);
+    const nextTool = row("c", "tool_call");
+    const nextText = row("d");
+    estimates.noteRows([text, tool, nextTool, nextText]);
+
+    expect(estimates.estimate(nextTool)).toBe(36);
+    expect(estimates.estimate(nextText)).toBe(34);
+  });
+
+  it("records the kind a row has when it is measured", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    estimates.noteRows([row("a", "thought")]);
+    estimates.noteMeasured(row("a", "tool_call"), 36);
+    const thought = row("b", "thought");
+    const tool = row("c", "tool_call");
+    estimates.noteRows([row("a", "tool_call"), thought, tool]);
+
+    expect(estimates.estimate(thought)).toBeUndefined();
+    expect(estimates.estimate(tool)).toBe(36);
+  });
+
+  it("estimates new rows anywhere in the list", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([row("b"), row("d")]);
+    const appendedTool = row("e", "tool_call");
+    estimates.noteRows([row("b"), row("d"), appendedTool]);
+    estimates.noteMeasured(appendedTool, 36);
+    const older = row("a", "tool_call");
+    const revealed = row("c", "tool_call");
+    estimates.noteRows([older, row("b"), revealed, row("d"), appendedTool]);
+
+    expect(estimates.estimate(older)).toBe(36);
+    expect(estimates.estimate(revealed)).toBe(36);
+    expect(estimates.estimate(row("b", "tool_call"))).toBeUndefined();
+  });
+
+  it("stops estimating a measured row", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    const first = row("a");
+    estimates.noteRows([first]);
+    estimates.noteMeasured(first, 34);
+
+    expect(estimates.estimate(first)).toBeUndefined();
+  });
+});
diff --git a/packages/app/src/agent-stream/new-row-estimates.ts b/packages/app/src/agent-stream/new-row-estimates.ts
new file mode 100644
index 0000000000..f13a32697a
--- /dev/null
+++ b/packages/app/src/agent-stream/new-row-estimates.ts
@@ -0,0 +1,47 @@
+interface EstimatedRow {
+  id: string;
+  kind: string;
+}
+
+export interface NewRowEstimates<Row extends EstimatedRow> {
+  /** Called with every row list; a row whose id the previous list did not have is new. */
+  noteRows: (rows: readonly Row[]) => void;
+  /** Estimated size of an unmeasured new row, or undefined to use the list's average for its type. */
+  estimate: (row: Row) => number | undefined;
+  /** A row can change kind under the same id (a thought becomes a tool call); its current kind counts. */
+  noteMeasured: (row: Row, size: number) => void;
+}
+
+// A row that enters the list is a streamed row at the end, a tool call an expanded summary reveals,
+// or an older row loaded at the start. Its first measured size is close to constant per kind: one
+// line of text, a tool call header, a thought line. So a new row is estimated at the first measured
+// size of the last new row of its kind, and is laid out near its real size before it is measured.
+// The list's average for a type is the size of whole turns and is far off for any of these. Rows of
+// the first list are not new; they keep the average until measured.
+export function createNewRowEstimates<Row extends EstimatedRow>(): NewRowEstimates<Row> {
+  let previousRowIds: ReadonlySet<string> | null = null;
+  const unmeasuredRowIds = new Set<string>();
+  const firstSizeByKind = new Map<string, number>();
+
+  return {
+    noteRows(rows) {
+      const rowIds = new Set(rows.map((row) => row.id));
+      if (previousRowIds) {
+        for (const row of rows) {
+          if (!previousRowIds.has(row.id)) unmeasuredRowIds.add(row.id);
+        }
+      }
+      for (const rowId of unmeasuredRowIds) {
+        if (!rowIds.has(rowId)) unmeasuredRowIds.delete(rowId);
+      }
+      previousRowIds = rowIds;
+    },
+    estimate(row) {
+      return unmeasuredRowIds.has(row.id) ? firstSizeByKind.get(row.kind) : undefined;
+    },
+    noteMeasured(row, size) {
+      if (!unmeasuredRowIds.delete(row.id)) return;
+      firstSizeByKind.set(row.kind, size);
+    },
+  };
+}
diff --git a/packages/app/src/agent-stream/presentation.test.ts b/packages/app/src/agent-stream/presentation.test.ts
index b48297481b..e3649e9806 100644
--- a/packages/app/src/agent-stream/presentation.test.ts
+++ b/packages/app/src/agent-stream/presentation.test.ts
@@ -69,6 +69,9 @@ function installProbe(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
   };
 }
 
@@ -590,6 +593,98 @@ describe("timeline presentation", () => {
   });
 });
 
+it("folds work before a plugin-rendered reply and leaves the reply visible", () => {
+  const timestamp = new Date("2026-01-01T00:00:00.000Z");
+  const tail: StreamItem[] = [
+    { kind: "user_message", id: "prompt", text: "Calculate", timestamp },
+    toolCall("one", "Bash"),
+    { kind: "assistant_message", id: "reply", text: "$$x^2$$", timestamp },
+  ];
+  const result = createStreamPresentation()({
+    ...presentationOptions,
+    transform: installedTransform(installProbe("assistant_message", "phase === 'complete'")),
+    tail,
+    head: [],
+    display: "collapseTurns",
+    isTurnActive: false,
+  });
+  expect(result.tail.map((item) => item.id)).toEqual([
+    "prompt",
+    "turn-summary:prompt",
+    "probe-plugin/reply/0",
+  ]);
+  expect(pluginData(result.tail)).toEqual([{ text: "$$x^2$$", phase: "complete" }]);
+});
+
+it("keeps streaming replies native, then folds work without losing manual expansion", () => {
+  const timestamp = new Date("2026-01-01T00:00:00.000Z");
+  const work: StreamItem[] = [
+    { kind: "user_message", id: "prompt", text: "Calculate", timestamp },
+    toolCall("one", "Bash"),
+  ];
+  const reply: StreamItem = {
+    kind: "assistant_message",
+    id: "reply",
+    text: "$$x^2$$",
+    timestamp,
+  };
+  const input = {
+    ...presentationOptions,
+    transform: installedTransform(installProbe("assistant_message", "phase === 'complete'")),
+    display: "collapseTurns" as const,
+  };
+  const present = createStreamPresentation();
+  const live = present({ ...input, tail: work, head: [reply], isTurnActive: true });
+  expect(rows(live).map((item) => item.id)).toEqual(["prompt", "tool-one", "reply"]);
+  const completed = { ...input, tail: [...work, reply], head: [], isTurnActive: false };
+  expect(present(completed).tail.map((item) => item.id)).toEqual([
+    "prompt",
+    "turn-summary:prompt",
+    "probe-plugin/reply/0",
+  ]);
+  const expandedTurnHostIds = new Set(["prompt"]);
+  const opened = present({ ...completed, expandedTurnHostIds });
+  expect(opened.tail.map((item) => item.id)).toEqual([
+    "prompt",
+    "turn-summary:prompt",
+    "tool-one",
+    "probe-plugin/reply/0",
+  ]);
+  expect(opened.turns.nestedItemIds.has("probe-plugin/reply/0")).toBe(false);
+  expect(present({ ...completed, expandedTurnHostIds }).tail).toEqual(opened.tail);
+  expect(present(completed).tail.map((item) => item.id)).toEqual([
+    "prompt",
+    "turn-summary:prompt",
+    "probe-plugin/reply/0",
+  ]);
+});
+
+it.each(["full", "collapseToolCalls"] as const)(
+  "leaves plugin replies and individual work visible in %s",
+  (display) => {
+    const timestamp = new Date("2026-01-01T00:00:00.000Z");
+    const tail: StreamItem[] = [
+      { kind: "user_message", id: "prompt", text: "Calculate", timestamp },
+      toolCall("one", "Bash"),
+      { kind: "assistant_message", id: "reply", text: "$$x^2$$", timestamp },
+    ];
+    const result = createStreamPresentation()({
+      ...presentationOptions,
+      transform: installedTransform(installProbe("assistant_message")),
+      tail,
+      head: [],
+      display,
+      isTurnActive: false,
+    });
+    expect(result.tail.map((item) => item.id)).toEqual([
+      "prompt",
+      "tool-one",
+      "probe-plugin/reply/0",
+    ]);
+    expect(result.turns.summaryRowsByHostId.size).toBe(0);
+  },
+);
+
 it("opening a turn reveals individual calls rather than another tool group", () => {
   const present = createStreamPresentation();
   const timestamp = new Date();
@@ -608,7 +703,13 @@ it("opening a turn reveals individual calls rather than another tool group", ()
     isTurnActive: false,
     expandedTurnHostIds: new Set(["prompt"]),
   });
-  expect(result.tail.map((item) => item.id)).toEqual(tail.map((item) => item.id));
+  expect(result.tail.map((item) => item.id)).toEqual([
+    "prompt",
+    "turn-summary:prompt",
+    "tool-one",
+    "tool-two",
+    "reply",
+  ]);
   expect(result.groupsByHostId.size).toBe(0);
   expect(result.readingRowReplacements.get("tool-two")).toBeUndefined();
 });
@@ -650,7 +751,7 @@ it.each(["collapseToolCalls", "collapseTurns"] as const)(
         { kind: "assistant_message", id: "reply", text: "Done", timestamp },
       ],
     });
-    // Both the original partial group and its replacement resolve directly to the turn.
+    // Both the original partial group and its replacement resolve directly to the turn's host.
     expect(folded.readingRowReplacements.get(calls[1]!.id)).toBe("prompt");
     expect(anchor.getRowId(folded.readingRowReplacements)).toBe("prompt");
     const opened = present({ ...input, tail: calls, display: "full" });
@@ -699,7 +800,7 @@ it("does not reopen the previous turn while a new run waits for its first row",
     isTurnActive: true,
     activeTurnId: "new",
   });
-  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "reply"]);
+  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "turn-summary:prompt", "reply"]);
 });
 
 // A sent prompt counts as activity before the daemon opens its turn, so the only known turn is
@@ -721,7 +822,7 @@ it("keeps the previous turn folded while a sent prompt waits for its turn to ope
     isTurnActive: true,
     activeTurnId: null,
   });
-  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "reply"]);
+  expect(result.tail.map((item) => item.id)).toEqual(["prompt", "turn-summary:prompt", "reply"]);
 });
 
 it("groups reasoning with tools unless Expand thinking is enabled, including setting changes", () => {
@@ -778,7 +879,13 @@ it.each([false, true])(
     const closed = present(input);
     expect(closed.tail.some((item) => item.id === "thought")).toBe(false);
     const opened = present({ ...input, expandedTurnHostIds: new Set(["prompt"]) });
-    expect(opened.tail).toEqual(tail);
+    expect(opened.tail.map((item) => item.id)).toEqual([
+      "prompt",
+      "turn-summary:prompt",
+      "thought",
+      "tool-one",
+      "reply",
+    ]);
     expect(opened.turns.nestedItemIds.has("thought")).toBe(true);
     expect(opened.groupsByHostId.size).toBe(0);
   },
diff --git a/packages/app/src/agent-stream/presentation.ts b/packages/app/src/agent-stream/presentation.ts
index 94140ca395..8e197aed23 100644
--- a/packages/app/src/agent-stream/presentation.ts
+++ b/packages/app/src/agent-stream/presentation.ts
@@ -50,6 +50,7 @@ const NO_COLLAPSED_TURNS: StreamPresentation["turns"] = collapseTurns({
   isLatestTurnOpen: false,
   expandedHostIds: new Set(),
   getGroupedCalls: () => undefined,
+  previousSummaryRowsByHostId: new Map(),
 });
 
 /** Source messages reach plugins before display projection. */
@@ -134,6 +135,8 @@ export function createStreamPresentation() {
         isLatestTurnOpen,
         expandedHostIds: input.expandedTurnHostIds,
         getGroupedCalls: (itemId) => projection.groupsByHostId.get(itemId)?.run.calls,
+        previousSummaryRowsByHostId:
+          collapsed?.summaryRowsByHostId ?? NO_COLLAPSED_TURNS.summaryRowsByHostId,
       });
       collapsedSource = projection.tail;
       collapsedIsLatestTurnOpen = isLatestTurnOpen;
diff --git a/packages/app/src/agent-stream/reading-anchor.test.ts b/packages/app/src/agent-stream/reading-anchor.test.ts
index d7d1b2beb4..a726203fc2 100644
--- a/packages/app/src/agent-stream/reading-anchor.test.ts
+++ b/packages/app/src/agent-stream/reading-anchor.test.ts
@@ -7,7 +7,7 @@ describe("reading anchor", () => {
     anchor.reconcile(0, [{ id: "tool", top: 48, height: 200 }]);
     const replacements = new Map([["tool", "prompt"]]);
     expect(anchor.getRowId(replacements)).toBe("prompt");
-    expect(anchor.project(0, { id: "prompt", top: 1048 }, replacements)).toBe(1000);
+    expect(anchor.project(0, { id: "prompt", top: 1048, height: 100 }, replacements)).toBe(1000);
     // Projection does not consume the correction; an unmounted host keeps the pin.
     expect(anchor.reconcile(0, [], false, replacements)).toBe(0);
     expect(anchor.getRowId()).toBe("tool");
@@ -56,6 +56,35 @@ describe("reading anchor", () => {
     ).toBe(1100);
   });
 
+  it("keeps a pinned row in place instead of the row under the reading line", () => {
+    const anchor = createReadingAnchor();
+    anchor.reconcile(600, rows);
+    anchor.pin(rows[2]!, "top", 600);
+    // The row being read grows; only the pinned row below it holds its position.
+    expect(
+      anchor.reconcile(600, [rows[0]!, { ...rows[1]!, height: 800 }, { ...rows[2]!, top: 1300 }]),
+    ).toBe(900);
+  });
+
+  it("keeps the bottom of a row pinned by a trigger below its content", () => {
+    const anchor = createReadingAnchor();
+    anchor.reconcile(600, rows);
+    anchor.pin(rows[2]!, "bottom", 600);
+    // The pinned row grows downward; its bottom, where the trigger sits, holds its position.
+    const grown = { ...rows[2]!, height: rows[2]!.height + 300 };
+    expect(anchor.reconcile(600, [rows[0]!, rows[1]!, grown])).toBe(900);
+  });
+
+  it("measures a pinned row's correction from the offset at the toggle", () => {
+    const anchor = createReadingAnchor();
+    anchor.reconcile(900, rows);
+    anchor.pin(rows[2]!, "bottom", 900);
+    // The row shrinks and the browser clamps the offset to the shorter content before the
+    // reconcile reads it.
+    const shrunk = { ...rows[2]!, height: rows[2]!.height - 300 };
+    expect(anchor.reconcile(700, [rows[0]!, rows[1]!, shrunk])).toBe(600);
+  });
+
   it("leaves expansion of the row being read in place", () => {
     const anchor = createReadingAnchor();
     anchor.reconcile(600, rows);
@@ -99,8 +128,8 @@ describe("reading anchor", () => {
   it("projects a prepend range without consuming the correction before layout commits", () => {
     const anchor = createReadingAnchor();
     anchor.reconcile(600, rows);
-    expect(anchor.project(440, { id: "reading", top: 2500 })).toBe(2440);
-    expect(anchor.project(440, { id: "reading", top: 2500 })).toBe(2440);
+    expect(anchor.project(440, { id: "reading", top: 2500, height: 100 })).toBe(2440);
+    expect(anchor.project(440, { id: "reading", top: 2500, height: 100 })).toBe(2440);
     expect(
       anchor.reconcile(
         440,
diff --git a/packages/app/src/agent-stream/reading-anchor.ts b/packages/app/src/agent-stream/reading-anchor.ts
index aa915c6ae7..88ea9e7a9d 100644
--- a/packages/app/src/agent-stream/reading-anchor.ts
+++ b/packages/app/src/agent-stream/reading-anchor.ts
@@ -1,9 +1,14 @@
+import type { DisclosureTriggerEdge } from "./strategy";
+
 interface RowGeometry {
   id: string;
   top: number;
   height: number;
 }
 
+const edgeOf = (row: RowGeometry, edge: DisclosureTriggerEdge) =>
+  edge === "top" ? row.top : row.top + row.height;
+
 // A row must clear the reading line before the next row takes ownership.
 const READING_POSITION_OFFSET_PX = 8;
 export interface ReadingRowReplacements {
@@ -14,7 +19,16 @@ const NO_REPLACEMENTS: ReadingRowReplacements = new Map();
 // Content coordinates survive user scrolling. Layout commits replace the geometry;
 // scroll events reuse it, without another DOM measurement pass.
 export function createReadingAnchor() {
-  let anchor: { id: string; top: number } | null = null;
+  // The row being read keeps its top. A disclosure pins the edge of its row the trigger sits on,
+  // with the offset at the toggle: a toggle that shrinks the content lets the browser clamp the
+  // offset before the next reconcile reads it.
+  let anchor: {
+    id: string;
+    edge: DisclosureTriggerEdge;
+    position: number;
+    pinnedScrollTop?: number;
+  } | null = null;
+  const anchorTop = (row: RowGeometry) => ({ id: row.id, edge: "top" as const, position: row.top });
   let geometry: readonly RowGeometry[] = [];
   const readingRow = (scrollTop: number) =>
     geometry.find((row) => row.top + row.height > scrollTop + READING_POSITION_OFFSET_PX);
@@ -22,9 +36,12 @@ export function createReadingAnchor() {
     anchor ? (replacements.get(anchor.id) ?? anchor.id) : null;
   const project = (
     scrollTop: number,
-    row: Pick<RowGeometry, "id" | "top"> | undefined,
+    row: RowGeometry | undefined,
     replacements = NO_REPLACEMENTS,
-  ) => scrollTop + (anchor && row && row.id === getRowId(replacements) ? row.top - anchor.top : 0);
+  ) =>
+    anchor && row && row.id === getRowId(replacements)
+      ? (anchor.pinnedScrollTop ?? scrollTop) + edgeOf(row, anchor.edge) - anchor.position
+      : scrollTop;
   return {
     getRowId,
     getReadingRowId: (scrollTop: number) =>
@@ -33,9 +50,14 @@ export function createReadingAnchor() {
     reset() {
       anchor = null;
     },
+    // A disclosure names the row that owns its trigger and the edge the trigger sits on. That
+    // edge stays in place through the toggle, even when another row sits under the reading line.
+    pin(row: RowGeometry, edge: DisclosureTriggerEdge, scrollTop: number) {
+      anchor = { id: row.id, edge, position: edgeOf(row, edge), pinnedScrollTop: scrollTop };
+    },
     scroll(scrollTop: number) {
       const next = readingRow(scrollTop);
-      anchor = next ? { id: next.id, top: next.top } : null;
+      anchor = next ? anchorTop(next) : null;
     },
     reconcile(
       scrollTop: number,
@@ -52,7 +74,7 @@ export function createReadingAnchor() {
       // A prepend can expose the bottom of an estimated row above the reader.
       // Do not transfer ownership to it until the user moves the reading position.
       const next = previous && !userScrolled ? previous : readingRow(correctedTop);
-      anchor = next ? { id: next.id, top: next.top } : null;
+      anchor = next ? anchorTop(next) : null;
       return correctedTop;
     },
   };
diff --git a/packages/app/src/agent-stream/render-strategy.test.ts b/packages/app/src/agent-stream/render-strategy.test.ts
index 59a2f7aed3..5e5ab7f7a2 100644
--- a/packages/app/src/agent-stream/render-strategy.test.ts
+++ b/packages/app/src/agent-stream/render-strategy.test.ts
@@ -12,7 +12,6 @@ import {
   isNearBottomForStreamRenderStrategy,
   orderHeadForStreamRenderStrategy,
   orderTailForStreamRenderStrategy,
-  resolveBottomAnchorTransportBehavior,
 } from "./strategy";
 import { resolveStreamRenderStrategy } from "./strategy-resolver";
 
@@ -64,8 +63,6 @@ describe("resolveStreamRenderStrategy", () => {
     });
 
     expect(strategy.shouldUseVirtualizedList()).toBe(false);
-    expect(strategy.getFlatListInverted()).toBe(false);
-    expect(strategy.getOverlayScrollbarInverted()).toBe(false);
     expect(strategy.shouldAnchorBottomOnContentSizeChange()).toBe(true);
     expect(strategy.getBottomAnchorTransportBehavior()).toEqual({
       verificationDelayFrames: 0,
@@ -73,57 +70,27 @@ describe("resolveStreamRenderStrategy", () => {
     });
   });
 
-  it("uses inverted_stream on native", () => {
+  it("uses a virtualized forward stream on native", () => {
     const strategy = resolveStreamRenderStrategy({
       platform: "ios",
       isMobileBreakpoint: false,
     });
 
     expect(strategy.shouldUseVirtualizedList()).toBe(true);
-    expect(strategy.getFlatListInverted()).toBe(true);
-    expect(strategy.getOverlayScrollbarInverted()).toBe(true);
     expect(strategy.shouldAnchorBottomOnContentSizeChange()).toBe(false);
     expect(strategy.getBottomAnchorTransportBehavior()).toEqual({
       verificationDelayFrames: 2,
       verificationRetryMode: "recheck",
     });
   });
-
-  it("delays native verification while viewport settling is in flight", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: true,
-      }),
-    ).toEqual({
-      verificationDelayFrames: 4,
-      verificationRetryMode: "recheck",
-    });
-  });
-
-  it("does not inflate forward-stream verification delays during web resize", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: true,
-      }),
-    ).toEqual({
-      verificationDelayFrames: 0,
-      verificationRetryMode: "rescroll",
-    });
-  });
 });
 
+const PLATFORMS = ["web", "ios", "android"] as const;
+
+function strategyFor(platform: (typeof PLATFORMS)[number]) {
+  return resolveStreamRenderStrategy({ platform, isMobileBreakpoint: false });
+}
+
 describe("stream ordering", () => {
   const streamItems: StreamItem[] = [
     userMessage("u1", "user-1", 1),
@@ -131,11 +98,8 @@ describe("stream ordering", () => {
     assistantMessage("a2", "assistant-2", 3),
   ];
 
-  it("keeps forward_stream order unchanged for tail and head", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("keeps oldest-to-newest order for tail and head on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
     const tail = orderTailForStreamRenderStrategy({ strategy, streamItems });
     const head = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
@@ -143,73 +107,31 @@ describe("stream ordering", () => {
     expect(tail.map((item) => item.id)).toEqual(["u1", "a1", "a2"]);
     expect(head.map((item) => item.id)).toEqual(["u1", "a1", "a2"]);
   });
-
-  it("reverses inverted_stream order for tail and head", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-
-    const tail = orderTailForStreamRenderStrategy({ strategy, streamItems });
-    const head = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
-
-    expect(tail.map((item) => item.id)).toEqual(["a2", "a1", "u1"]);
-    expect(head.map((item) => item.id)).toEqual(["a2", "a1", "u1"]);
-  });
 });
 
 describe("neighbor and traversal semantics", () => {
-  it("maps above/below indices for forward and inverted streams", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("maps above/below indices on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
-    expect(getStreamNeighborIndex({ strategy: forward, index: 3, relation: "above" })).toBe(2);
-    expect(getStreamNeighborIndex({ strategy: forward, index: 3, relation: "below" })).toBe(4);
-    expect(getStreamNeighborIndex({ strategy: inverted, index: 3, relation: "above" })).toBe(4);
-    expect(getStreamNeighborIndex({ strategy: inverted, index: 3, relation: "below" })).toBe(2);
+    expect(getStreamNeighborIndex({ strategy, index: 3, relation: "above" })).toBe(2);
+    expect(getStreamNeighborIndex({ strategy, index: 3, relation: "below" })).toBe(4);
   });
 
-  it("collects assistant response content with strategy traversal direction", () => {
+  it.each(PLATFORMS)("collects assistant response content on %s", (platform) => {
     const chronological: StreamItem[] = [
       userMessage("u1", "user-1", 1),
       assistantMessage("a1", "assistant-1", 2),
       assistantMessage("a2", "assistant-2", 3),
       userMessage("u2", "user-2", 4),
     ];
+    const strategy = strategyFor(platform);
+    const items = orderTailForStreamRenderStrategy({ strategy, streamItems: chronological });
 
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const forwardStartIndex = chronological.findIndex((item) => item.id === "a2");
     expect(
       collectAssistantResponseContentForStreamRenderStrategy({
-        strategy: forward,
-        items: chronological,
-        startIndex: forwardStartIndex,
-      }),
-    ).toBe("assistant-1\n\nassistant-2");
-
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-    const invertedItems = orderTailForStreamRenderStrategy({
-      strategy: inverted,
-      streamItems: chronological,
-    });
-    const invertedStartIndex = invertedItems.findIndex((item) => item.id === "a2");
-    expect(
-      collectAssistantResponseContentForStreamRenderStrategy({
-        strategy: inverted,
-        items: invertedItems,
-        startIndex: invertedStartIndex,
+        strategy,
+        items,
+        startIndex: items.findIndex((item) => item.id === "a2"),
       }),
     ).toBe("assistant-1\n\nassistant-2");
   });
@@ -220,7 +142,7 @@ describe("neighbor and traversal semantics", () => {
       { ...toolCall("tool", 2), turnId: "turn-2" },
       { ...assistantMessage("a2", "second turn", 3), turnId: "turn-2" },
     ];
-    const strategy = resolveStreamRenderStrategy({ platform: "web", isMobileBreakpoint: false });
+    const strategy = strategyFor("web");
 
     expect(
       collectAssistantResponseContentForStreamRenderStrategy({
@@ -232,37 +154,17 @@ describe("neighbor and traversal semantics", () => {
   });
 
   it("returns undefined neighbor when index would be out of bounds", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+    const strategy = strategyFor("web");
     const items: StreamItem[] = [userMessage("u1", "user-1", 1)];
 
-    expect(
-      getStreamNeighborItem({
-        strategy: forward,
-        items,
-        index: 0,
-        relation: "above",
-      }),
-    ).toBeUndefined();
-    expect(
-      getStreamNeighborItem({
-        strategy: forward,
-        items,
-        index: 0,
-        relation: "below",
-      }),
-    ).toBeUndefined();
+    expect(getStreamNeighborItem({ strategy, items, index: 0, relation: "above" })).toBeUndefined();
+    expect(getStreamNeighborItem({ strategy, items, index: 0, relation: "below" })).toBeUndefined();
   });
 });
 
 describe("scroll/bottom calculations", () => {
-  it("computes near-bottom using forward_stream distance-from-bottom math", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("computes near-bottom from the distance to the end on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
     expect(
       isNearBottomForStreamRenderStrategy({
@@ -284,48 +186,10 @@ describe("scroll/bottom calculations", () => {
     ).toBe(false);
   });
 
-  it("computes near-bottom and scroll-to-bottom offset for inverted_stream", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      isNearBottomForStreamRenderStrategy({
-        strategy,
-        offsetY: 12,
-        viewportHeight: 300,
-        contentHeight: 1000,
-        threshold: 24,
-      }),
-    ).toBe(true);
-    expect(
-      isNearBottomForStreamRenderStrategy({
-        strategy,
-        offsetY: 40,
-        viewportHeight: 300,
-        contentHeight: 1000,
-        threshold: 24,
-      }),
-    ).toBe(false);
+  it.each(PLATFORMS)("maps scroll-to-bottom to the max offset on %s", (platform) => {
     expect(
       getBottomOffsetForStreamRenderStrategy({
-        strategy,
-        viewportHeight: 300,
-        contentHeight: 1000,
-      }),
-    ).toBe(0);
-  });
-
-  it("maps scroll-to-bottom to max offset for forward_stream", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      getBottomOffsetForStreamRenderStrategy({
-        strategy,
+        strategy: strategyFor(platform),
         viewportHeight: 320,
         contentHeight: 1000,
       }),
@@ -334,36 +198,15 @@ describe("scroll/bottom calculations", () => {
 });
 
 describe("edge slot semantics", () => {
-  it("uses footer slot for forward_stream and header slot for inverted_stream", () => {
+  it.each(PLATFORMS)("uses the footer slot on %s", (platform) => {
     const EdgeSlot = () => null;
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
 
-    const forwardProps = getStreamEdgeSlotProps({
-      strategy: forward,
-      component: EdgeSlot,
-      gapSize: 4,
-    });
-    const invertedProps = getStreamEdgeSlotProps({
-      strategy: inverted,
-      component: EdgeSlot,
-      gapSize: 4,
-    });
-
-    expect(forwardProps).toEqual({
+    expect(
+      getStreamEdgeSlotProps({ strategy: strategyFor(platform), component: EdgeSlot, gapSize: 4 }),
+    ).toEqual({
       ListFooterComponent: EdgeSlot,
       ListFooterComponentStyle: { marginTop: 4 },
     });
-    expect(invertedProps).toEqual({
-      ListHeaderComponent: EdgeSlot,
-      ListHeaderComponentStyle: { marginBottom: 4 },
-    });
   });
 });
 
@@ -373,81 +216,31 @@ describe("layout strategy edges", () => {
     assistantMessage("a1", "assistant-1", 2),
   ];
 
-  it("uses the newest history edge as the history/live boundary", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)(
+    "uses the newest history edge as the history/live boundary on %s",
+    (platform) => {
+      const strategy = strategyFor(platform);
+      const history = orderTailForStreamRenderStrategy({ strategy, streamItems });
 
-    const forwardHistory = orderTailForStreamRenderStrategy({ strategy: forward, streamItems });
-    const invertedHistory = orderTailForStreamRenderStrategy({ strategy: inverted, streamItems });
+      expect(getHistoryLiveBoundaryIndexForStreamRenderStrategy({ strategy, history })).toBe(1);
+    },
+  );
 
-    expect(
-      getHistoryLiveBoundaryIndexForStreamRenderStrategy({
-        strategy: forward,
-        history: forwardHistory,
-      }),
-    ).toBe(1);
-    expect(
-      getHistoryLiveBoundaryIndexForStreamRenderStrategy({
-        strategy: inverted,
-        history: invertedHistory,
-      }),
-    ).toBe(0);
-  });
+  it.each(PLATFORMS)(
+    "uses the oldest live-head edge as the live-head/history boundary on %s",
+    (platform) => {
+      const strategy = strategyFor(platform);
+      const liveHead = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
 
-  it("uses the oldest live-head edge as the live-head/history boundary", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
+      expect(getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({ strategy, liveHead })).toBe(
+        0,
+      );
+    },
+  );
 
-    const forwardHead = orderHeadForStreamRenderStrategy({
-      strategy: forward,
-      streamHead: streamItems,
-    });
-    const invertedHead = orderHeadForStreamRenderStrategy({
-      strategy: inverted,
-      streamHead: streamItems,
-    });
-
-    expect(
-      getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({
-        strategy: forward,
-        liveHead: forwardHead,
-      }),
-    ).toBe(0);
-    expect(
-      getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({
-        strategy: inverted,
-        liveHead: invertedHead,
-      }),
-    ).toBe(1);
-  });
-
-  it("names the frame child order needed by native inverted cells", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-
-    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: forward })).toBe(
+  it.each(PLATFORMS)("renders a cell's content before its footer on %s", (platform) => {
+    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: strategyFor(platform) })).toBe(
       "content-then-footer",
     );
-    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: inverted })).toBe(
-      "footer-then-content",
-    );
   });
 });
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
index 9d22d2b90c..d459ca8ba8 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
@@ -41,23 +41,23 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1040, y: 8 },
-          { ts: 1080, y: 16 },
-          { ts: 1120, y: 24 },
+          { ts: 1040, y: -8 },
+          { ts: 1080, y: -16 },
+          { ts: 1120, y: -24 },
         ],
-        { ts: 1160, y: 32 },
+        { ts: 1160, y: -32 },
       ),
     ).toBe(false);
   });
 
-  it("dismisses for an upward flick", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: 120 }], { ts: 1080, y: 240 })).toBe(
+  it("dismisses for a flick toward older messages", () => {
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: -120 }], { ts: 1080, y: -240 })).toBe(
       true,
     );
   });
 
-  it("keeps the keyboard up when the inverted list moves toward newer messages", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: -120 }], { ts: 1080, y: -240 })).toBe(
+  it("keeps the keyboard up when the list moves toward newer messages", () => {
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: 120 }], { ts: 1080, y: 240 })).toBe(
       false,
     );
   });
@@ -67,17 +67,17 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1100, y: 500 },
-          { ts: 1200, y: 590 },
-          { ts: 1270, y: 598 },
+          { ts: 1100, y: -500 },
+          { ts: 1200, y: -590 },
+          { ts: 1270, y: -598 },
         ],
-        { ts: 1300, y: 600 },
+        { ts: 1300, y: -600 },
       ),
     ).toBe(false);
   });
 
   it("uses the whole drag when the gesture is too short to sample", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1020, y: 60 })).toBe(true);
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1020, y: -60 })).toBe(true);
   });
 
   it("steps back a sample when release lands immediately after one", () => {
@@ -85,22 +85,22 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1040, y: 120 },
-          { ts: 1075, y: 225 },
+          { ts: 1040, y: -120 },
+          { ts: 1075, y: -225 },
         ],
-        { ts: 1080, y: 240 },
+        { ts: 1080, y: -240 },
       ),
     ).toBe(true);
   });
 
   it("keeps the keyboard up when release has no measurable time span", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1000, y: 90 })).toBe(false);
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1000, y: -90 })).toBe(false);
   });
 
   it("ignores scroll events that arrive before the minimum sample span", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1029, y: 1000 }], { ts: 1060, y: 1000 })).toBe(
-      true,
-    );
+    expect(
+      shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1029, y: -1000 }], { ts: 1060, y: -1000 }),
+    ).toBe(true);
   });
 
   it("uses native gesture time when delayed callbacks arrive in a burst", () => {
@@ -108,32 +108,32 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 5000, nativeTs: 1000, y: 0 },
         [
-          { ts: 5001, nativeTs: 1200, y: 40 },
-          { ts: 5002, nativeTs: 1400, y: 80 },
+          { ts: 5001, nativeTs: 1200, y: -40 },
+          { ts: 5002, nativeTs: 1400, y: -80 },
         ],
-        { ts: 5003, nativeTs: 1600, y: 120 },
+        { ts: 5003, nativeTs: 1600, y: -120 },
       ),
     ).toBe(false);
   });
 
   it("falls back to synthetic event time when native time is absent", () => {
     expect(
-      shouldDismiss({ ts: 1000, nativeTs: null, y: 0 }, [{ ts: 1040, nativeTs: null, y: 120 }], {
+      shouldDismiss({ ts: 1000, nativeTs: null, y: 0 }, [{ ts: 1040, nativeTs: null, y: -120 }], {
         ts: 1080,
         nativeTs: null,
-        y: 240,
+        y: -240,
       }),
     ).toBe(true);
   });
 
   it("ignores scroll and release events without a matching drag", () => {
-    const idle = recordScroll(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE, event({ ts: 1000, y: 200 }));
+    const idle = recordScroll(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE, event({ ts: 1000, y: -200 }));
     expect(idle).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
-    expect(releaseDrag(idle, event({ ts: 1010, y: 300 })).shouldDismiss).toBe(false);
+    expect(releaseDrag(idle, event({ ts: 1010, y: -300 })).shouldDismiss).toBe(false);
   });
 
   it("returns to idle after release", () => {
-    const release = releaseDrag(beginDrag(event({ ts: 1000, y: 0 })), event({ ts: 1020, y: 60 }));
+    const release = releaseDrag(beginDrag(event({ ts: 1000, y: 0 })), event({ ts: 1020, y: -60 }));
     expect(release.gesture).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
   });
 });
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
index 73e0d19a76..374bb84762 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
@@ -2,8 +2,7 @@
  * Pure state machine for the chat history's flick-to-dismiss gesture.
  *
  * Native keyboardDismissMode cannot express this interaction: "on-drag"
- * dismisses on the first pixel, while "interactive" behaves incorrectly on an
- * inverted list. We therefore classify the list's existing scroll gesture at
+ * dismisses on the first pixel, while "interactive" is iOS-only. We therefore classify the list's existing scroll gesture at
  * release instead of introducing a competing pan recognizer.
  */
 
@@ -114,11 +113,12 @@ export function releaseDrag(
     spanStartY = samples.previousSampleY;
   }
 
+  // The list runs oldest to newest, so moving toward older messages lowers the offset.
   const spanDurationMs = releaseTs - spanStartTs;
-  const releaseVelocity = spanDurationMs > 0 ? (releaseY - spanStartY) / spanDurationMs : 0;
+  const towardOlderVelocity = spanDurationMs > 0 ? (spanStartY - releaseY) / spanDurationMs : 0;
 
   return {
     gesture: IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE,
-    shouldDismiss: releaseVelocity > DISMISS_VELOCITY_POINTS_PER_MS,
+    shouldDismiss: towardOlderVelocity > DISMISS_VELOCITY_POINTS_PER_MS,
   };
 }
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
index fb78eea9b5..e0455687ea 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
@@ -18,7 +18,7 @@ type ScrollEvent = NativeSyntheticEvent<NativeScrollEvent>;
 
 /**
  * Owns the chat history's flick-to-dismiss behavior. The native stream only
- * forwards the FlatList scroll lifecycle; removing this hook and those three
+ * forwards the LegendList scroll lifecycle; removing this hook and those three
  * calls removes the feature completely.
  */
 export function useScrollKeyboardDismiss() {
diff --git a/packages/app/src/agent-stream/spacing.test.ts b/packages/app/src/agent-stream/spacing.test.ts
index 07e9f185ff..3f84f0df5e 100644
--- a/packages/app/src/agent-stream/spacing.test.ts
+++ b/packages/app/src/agent-stream/spacing.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { getAssistantMessageSpacing, getGapBetweenStreamItems } from "./spacing";
+import { summarizeToolCalls } from "@/tool-calls/detail-level/overview/model";
 import type { StreamItem } from "@/types/stream";
 const message: StreamItem = {
   kind: "assistant_message",
@@ -7,6 +8,27 @@ const message: StreamItem = {
   text: "First\n\nSecond",
   timestamp: new Date(0),
 };
+const prompt: StreamItem = {
+  kind: "user_message",
+  id: "p",
+  text: "Fix it",
+  timestamp: new Date(0),
+};
+const thought: StreamItem = {
+  kind: "thought",
+  id: "t",
+  text: "Reading",
+  timestamp: new Date(0),
+  status: "ready",
+};
+const summary: StreamItem = {
+  kind: "turn_summary",
+  id: "turn-summary:p",
+  hostId: "p",
+  expanded: false,
+  timestamp: new Date(0),
+  tools: summarizeToolCalls([]),
+};
 describe("whole-message spacing", () => {
   it("compacts only the gap to its turn footer", () => {
     expect(getAssistantMessageSpacing({ item: message })).toBe("default");
@@ -17,4 +39,18 @@ describe("whole-message spacing", () => {
   it("keeps separate messages separated", () => {
     expect(getGapBetweenStreamItems(message, { ...message, id: "next" })).toBeGreaterThan(0);
   });
+  it("sets a prompt the same distance above whatever answers it", () => {
+    const belowPrompt = getGapBetweenStreamItems(prompt, thought);
+    expect(belowPrompt).toBeGreaterThan(0);
+    expect(getGapBetweenStreamItems(prompt, message)).toBe(belowPrompt);
+    expect(getGapBetweenStreamItems(prompt, summary)).toBe(belowPrompt);
+  });
+  it("spaces a turn's summary row like the work rows it stands for", () => {
+    expect(getGapBetweenStreamItems(summary, message)).toBe(
+      getGapBetweenStreamItems(thought, message),
+    );
+    expect(getGapBetweenStreamItems(thought, summary)).toBe(
+      getGapBetweenStreamItems(thought, thought),
+    );
+  });
 });
diff --git a/packages/app/src/agent-stream/spacing.ts b/packages/app/src/agent-stream/spacing.ts
index 55761f71f3..3caaa9f21e 100644
--- a/packages/app/src/agent-stream/spacing.ts
+++ b/packages/app/src/agent-stream/spacing.ts
@@ -11,8 +11,12 @@ export function getAssistantMessageSpacing(params: {
 }
 
 const isUserMessageItem = (item?: StreamItem | null) => item?.kind === "user_message";
-const isToolSequenceItem = (item?: StreamItem | null) =>
-  item?.kind === "tool_call" || item?.kind === "thought" || item?.kind === "todo_list";
+/** A row of the agent's work, including the summary row that stands in for a folded turn's. */
+const isWorkItem = (item?: StreamItem | null) =>
+  item?.kind === "tool_call" ||
+  item?.kind === "thought" ||
+  item?.kind === "todo_list" ||
+  item?.kind === "turn_summary";
 
 export function getGapBetweenStreamItems(
   item: StreamItem | null,
@@ -25,19 +29,16 @@ export function getGapBetweenStreamItems(
   if (isUserMessageItem(item) && isUserMessageItem(belowItem)) {
     return SPACING[1];
   }
-  if (item.kind === "user_message" && belowItem.kind === "assistant_message") {
-    return 0;
-  }
-  if (isToolSequenceItem(item) && isToolSequenceItem(belowItem)) {
-    return 0;
-  }
-  if (item.kind === "user_message" && isToolSequenceItem(belowItem)) {
+  if (isUserMessageItem(item)) {
     return SPACING[4];
   }
-  if (item.kind === "assistant_message" && isToolSequenceItem(belowItem)) {
+  if (isWorkItem(item) && isWorkItem(belowItem)) {
+    return 0;
+  }
+  if (item.kind === "assistant_message" && isWorkItem(belowItem)) {
     return SPACING[1];
   }
-  if (isToolSequenceItem(item) && belowItem.kind === "assistant_message") {
+  if (isWorkItem(item) && belowItem.kind === "assistant_message") {
     return SPACING[1];
   }
   return SPACING[4];
diff --git a/packages/app/src/agent-stream/strategy-native.tsx b/packages/app/src/agent-stream/strategy-native.tsx
index 7dc6e8d521..106c9c3bb4 100644
--- a/packages/app/src/agent-stream/strategy-native.tsx
+++ b/packages/app/src/agent-stream/strategy-native.tsx
@@ -1,59 +1,67 @@
 import {
-  Fragment,
   type ReactElement,
+  type ReactNode,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
 } from "react";
 import {
-  FlatList,
-  Platform,
   View,
   type LayoutChangeEvent,
-  type ListRenderItemInfo,
   type NativeScrollEvent,
   type NativeSyntheticEvent,
+  type ScrollView,
+  type ScrollViewProps,
   type ViewStyle,
 } from "react-native";
+import {
+  LegendList,
+  type LegendListRef,
+  type LegendListRenderItemProps,
+  useSyncLayout,
+} from "@legendapp/list/react-native";
 import { withUnistyles } from "react-native-unistyles";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
+import { Button } from "@/components/ui/button";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+import { useTranslation } from "react-i18next";
 import type { StreamItem } from "@/types/stream";
 import type { Theme } from "@/styles/theme";
 import { useStableEvent } from "@/hooks/use-stable-event";
-import { useKeyboardStreamInset } from "@/keyboard/shift";
 import { shouldAnimateNativeScrollToBottom } from "./native-scroll-animation";
 import { useRevisedHistoryRows } from "./history-row-revision";
 import { useBottomAnchorController } from "./bottom-anchor-controller";
 import { useScrollKeyboardDismiss } from "./scroll-keyboard-dismiss/use-scroll-keyboard-dismiss";
-import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./strategy";
 import {
-  createStreamStrategy,
-  isNearBottomForStreamRenderStrategy,
-  resolveBottomAnchorTransportBehavior,
+  createNativeDisclosureHold,
+  disclosureAnchor,
+  createEndHoldDistance,
+  type EndHoldDistance,
+} from "./native-disclosure-hold";
+import { EndPinnedScrollView } from "./native-end-pin";
+import { createNewRowEstimates } from "./new-row-estimates";
+import type {
+  DisclosureTriggerEdge,
+  StreamRenderInput,
+  StreamStrategy,
+  StreamViewportHandle,
 } from "./strategy";
+import { createStreamStrategy, isNearBottomForStreamRenderStrategy } from "./strategy";
 import {
-  abandonHistoryStartPaginationRequest,
-  createHistoryStartPaginationState,
-  evaluateHistoryStartPagination,
   isHistoryStartLoadingOperation,
-  rearmHistoryStartPagination,
-  settleHistoryStartPagination,
   type HistoryStartPaginationInput,
-  type HistoryStartPaginationTransition,
 } from "./history-start-pagination";
+import { useHistoryStartPagination } from "./use-history-start-pagination";
+import { nativeHistoryStartGeometry } from "./native-history-start-geometry";
 import { useStreamTopOverlayInset } from "./top-overlay";
 import {
   createHistoryStartSettleScheduler,
   type HistoryStartSettleScheduler,
 } from "./history-start-settle-scheduler";
 
-const DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION = Object.freeze({
-  minIndexForVisible: 0,
-  autoscrollToTopThreshold: 0,
-});
-
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const foregroundMutedColorMapping = (theme: Theme) => ({
   color: theme.colors.foregroundMuted,
@@ -65,7 +73,60 @@ const historyStartSlotStyle: ViewStyle = {
   flexShrink: 0,
 };
 const HISTORY_START_SETTLE_FRAMES = 2;
-const NATIVE_STREAM_WINDOW_SIZE = 10;
+// Rendered distance on each side of the viewport. Smaller values blank the viewport while a fling
+// crosses rows that were never measured (docs/agent-stream-disclosure.md).
+const NATIVE_STREAM_DRAW_DISTANCE = 2000;
+// Following resumes after a disclosure or a user scroll only from the end, so resuming never moves
+// the rows the user is looking at. Web resumes within the same distance (strategy-web.tsx).
+const AT_END_OFFSET_PX = 1;
+// A disclosure settles after this many frames without an item size change.
+const DISCLOSURE_QUIET_FRAMES = 2;
+const BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR = Object.freeze({
+  verificationDelayFrames: 2,
+  verificationRetryMode: "recheck" as const,
+});
+
+type RowLayoutSyncRegistry = Map<string, () => void>;
+
+// A disclosure toggle changes a row from the row's own state, so LegendList's container does not
+// re-render and would learn the new height from onLayout a task later, a frame after the change
+// painted. The row's measurement trigger, called next to the toggle, batches the measurement and
+// the corrected positions into the toggle's own commit.
+function RowLayoutSync(props: {
+  rowId: string;
+  registry: RowLayoutSyncRegistry;
+  children: ReactNode;
+}) {
+  const { rowId, registry } = props;
+  const syncLayout = useSyncLayout();
+  useLayoutEffect(() => {
+    registry.set(rowId, syncLayout);
+    return () => {
+      if (registry.get(rowId) === syncLayout) {
+        registry.delete(rowId);
+      }
+    };
+  }, [registry, rowId, syncLayout]);
+  return props.children;
+}
+
+function distanceFromEnd(input: {
+  offsetY: number;
+  contentHeight: number;
+  viewportHeight: number;
+}): number {
+  return Math.max(0, input.contentHeight - input.viewportHeight - input.offsetY);
+}
+const viewportStyle: ViewStyle = { flex: 1 };
+const initialFillStyle: ViewStyle = {
+  position: "absolute",
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  alignItems: "center",
+  justifyContent: "center",
+};
 
 function keyExtractor(item: { id: string }): string {
   return item.id;
@@ -83,6 +144,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     viewportRef,
     routeBottomAnchorRequest,
     isAuthoritativeHistoryReady,
+    isInitialHistoryLoading,
+    revealInitialHistory,
     onNearBottomChange,
     onNearHistoryStart,
     isLoadingOlderHistory,
@@ -93,8 +156,14 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     baseListContentContainerStyle,
     strategy,
   } = props;
+  const isActive = useRetainedPanelActive();
+  const { t } = useTranslation();
   const { renderHistoryMountedRow, renderLiveHeadRow, renderLiveAuxiliary } = renderers;
-  const flatListRef = useRef<FlatList<StreamItem>>(null);
+  const listRef = useRef<LegendListRef>(null);
+  // LegendList places the rows once, behind a hidden reveal, when the list mounts.
+  const [isListPlaced, setIsListPlaced] = useState(false);
+  const isListPlacedRef = useRef(isListPlaced);
+  isListPlacedRef.current = isListPlaced;
   const streamViewportMetricsRef = useRef({
     containerKey: "native-virtualized",
     contentHeight: 0,
@@ -107,16 +176,10 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   const scrollOffsetYRef = useRef(0);
   const isUserScrollActiveRef = useRef(false);
   const scrollKeyboardDismiss = useScrollKeyboardDismiss();
-  const streamKeyboardInset = useKeyboardStreamInset();
   const userScrollEndFrameIdRef = useRef<number | null>(null);
+  const isReleasedAtEndRef = useRef(false);
   const programmaticScrollEventBudgetRef = useRef(0);
-  const isNativeViewportSettlingRef = useRef(false);
-  const nativeViewportSettlingFrameIdRef = useRef<number | null>(null);
   const historyStartReadyRef = useRef(false);
-  const [historyStartPaginationState, setHistoryStartPaginationState] = useState(
-    createHistoryStartPaginationState,
-  );
-  const historyStartPaginationStateRef = useRef(historyStartPaginationState);
   const historyStartSettleSchedulerRef = useRef<HistoryStartSettleScheduler | null>(null);
 
   const historyItems = useMemo(() => {
@@ -126,54 +189,57 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     return [...segments.historyVirtualized, ...segments.historyMounted];
   }, [segments.historyMounted, segments.historyVirtualized]);
   const historyRows = useRevisedHistoryRows(historyItems, historyRowRevision);
+  // Live rows are the tail of the list, so a row that finishes keeps its id, container and measured
+  // size when it moves into history. A fresh identity per live-head change re-renders every live
+  // row, which is how they pick up neighbour and expansion changes (`liveHeadRowRevision`).
+  const liveRows = useMemo(() => {
+    void liveHeadRowRevision;
+    return segments.liveHead.map((item) => ({ ...item }));
+  }, [segments.liveHead, liveHeadRowRevision]);
+  const liveRowIds = useMemo(() => new Set(liveRows.map((item) => item.id)), [liveRows]);
+  const [newRowEstimates] = useState(() => createNewRowEstimates<StreamItem>());
+  const rows = useMemo(() => {
+    const nextRows = [...historyRows, ...liveRows];
+    newRowEstimates.noteRows(nextRows);
+    return nextRows;
+  }, [newRowEstimates, historyRows, liveRows]);
+  const getEstimatedItemSize = useStableEvent((item: StreamItem) => newRowEstimates.estimate(item));
   const getHistoryStartPaginationInput = useStableEvent((): HistoryStartPaginationInput => {
     const metrics = streamViewportMetricsRef.current;
     const hasMeasuredViewport =
       metrics.viewportMeasuredForKey === metrics.containerKey &&
       metrics.contentMeasuredForKey === metrics.containerKey;
     return {
-      distanceFromHistoryStart: metrics.contentHeight - metrics.viewportHeight - metrics.offsetY,
+      ...nativeHistoryStartGeometry({
+        contentHeight: metrics.contentHeight,
+        viewportHeight: metrics.viewportHeight,
+        offsetY: metrics.offsetY,
+        topOverlayInset,
+      }),
       hasOlderHistory,
       isLoadingOlderHistory,
-      isReady: historyStartReadyRef.current && hasMeasuredViewport,
+      isReady:
+        isActive &&
+        isAuthoritativeHistoryReady &&
+        historyStartReadyRef.current &&
+        hasMeasuredViewport,
       progressKey: olderHistoryProgressKey,
     };
   });
-  const applyHistoryStartPaginationTransition = useStableEvent(
-    (transition: HistoryStartPaginationTransition) => {
-      const previousState = historyStartPaginationStateRef.current;
-      historyStartPaginationStateRef.current = transition.state;
-      if (transition.state !== previousState) {
-        setHistoryStartPaginationState(transition.state);
-      }
-      if (transition.shouldLoad) {
-        const requestedProgressKey = olderHistoryProgressKey;
-        if (requestedProgressKey === null) {
-          return;
-        }
-        void (async () => {
-          const started = await onNearHistoryStart();
-          if (started === true) {
-            return;
-          }
-          applyHistoryStartPaginationTransition({
-            state: abandonHistoryStartPaginationRequest(
-              historyStartPaginationStateRef.current,
-              requestedProgressKey,
-            ),
-            shouldLoad: false,
-          });
-        })();
-      }
-    },
+  const { state: historyStartPaginationState, controller: historyStartPagination } =
+    useHistoryStartPagination({
+      initiallyVisible: !isInitialHistoryLoading,
+      read: getHistoryStartPaginationInput,
+      load: async () => onNearHistoryStart(),
+      scheduleSettle: () => scheduleHistoryStartSettle(),
+    });
+  const evaluateHistoryStart = useStableEvent(() => historyStartPagination.update());
+  const disposeHistoryStart = useStableEvent(() => historyStartPagination.dispose());
+  const isHistoryStartSettling = useStableEvent(
+    () => historyStartPagination.state.status === "settling",
   );
-  const evaluateHistoryStart = useStableEvent(() => {
-    const transition = evaluateHistoryStartPagination(
-      historyStartPaginationStateRef.current,
-      getHistoryStartPaginationInput(),
-    );
-    applyHistoryStartPaginationTransition(transition);
-  });
+  const finishInitialFill = useStableEvent(() => historyStartPagination.reveal());
+  const retryHistoryStart = useStableEvent(() => historyStartPagination.rearm());
   const scheduleHistoryStartSettle = useStableEvent(() => {
     let scheduler = historyStartSettleSchedulerRef.current;
     if (!scheduler) {
@@ -181,28 +247,15 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
         settleFrames: HISTORY_START_SETTLE_FRAMES,
         requestFrame: requestAnimationFrame,
         cancelFrame: cancelAnimationFrame,
-        isSettling: () => historyStartPaginationStateRef.current.status === "settling",
+        isSettling: () => isHistoryStartSettling(),
         isLoading: () => getHistoryStartPaginationInput().isLoadingOlderHistory,
-        onSettle: () => {
-          const transition = settleHistoryStartPagination(
-            historyStartPaginationStateRef.current,
-            getHistoryStartPaginationInput(),
-          );
-          applyHistoryStartPaginationTransition(transition);
-        },
+        onSettle: () => historyStartPagination.settle(),
       });
       historyStartSettleSchedulerRef.current = scheduler;
     }
     scheduler.schedule();
   });
 
-  const clearNativeViewportSettling = useCallback(() => {
-    if (nativeViewportSettlingFrameIdRef.current !== null) {
-      cancelAnimationFrame(nativeViewportSettlingFrameIdRef.current);
-      nativeViewportSettlingFrameIdRef.current = null;
-    }
-  }, []);
-
   const clearPendingUserScrollEnd = useCallback(() => {
     if (userScrollEndFrameIdRef.current !== null) {
       cancelAnimationFrame(userScrollEndFrameIdRef.current);
@@ -210,49 +263,30 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     }
   }, []);
 
-  const markNativeViewportSettling = useCallback(() => {
-    clearNativeViewportSettling();
-    isNativeViewportSettlingRef.current = true;
-    let remainingFrames = 4;
-    const tick = () => {
-      if (remainingFrames <= 0) {
-        nativeViewportSettlingFrameIdRef.current = null;
-        isNativeViewportSettlingRef.current = false;
-        return;
-      }
-      remainingFrames -= 1;
-      nativeViewportSettlingFrameIdRef.current = requestAnimationFrame(tick);
-    };
-    nativeViewportSettlingFrameIdRef.current = requestAnimationFrame(tick);
-  }, [clearNativeViewportSettling]);
-
-  const getBottomAnchorTransportBehavior = useCallback(
-    () =>
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: isNativeViewportSettlingRef.current,
-      }),
-    [strategy],
-  );
+  const getBottomAnchorTransportBehavior = useCallback(() => BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR, []);
 
   const scrollToBottom = useCallback(
     (animated: boolean) => {
       programmaticScrollEventBudgetRef.current = 3;
-      flatListRef.current?.scrollToOffset({
-        offset: 0,
+      const metrics = streamViewportMetricsRef.current;
+      // The native scroll view finds its end from the content it has mounted, and the end pin holds
+      // it from there. LegendList's own scrollToEnd keeps re-aiming at the end its JS sizes predict
+      // until it lands, which runs ahead of the mount and scrolls the end out of view.
+      const list = listRef.current;
+      list?.cancelScroll();
+      // The scroll component is `EndPinnedScrollView`, a ScrollView.
+      (list?.getNativeScrollRef() as ScrollView | undefined)?.scrollToEnd({
         animated:
           animated &&
           shouldAnimateNativeScrollToBottom({
-            offsetY: scrollOffsetYRef.current,
-            viewportHeight: streamViewportMetricsRef.current.viewportHeight,
-            windowSize: NATIVE_STREAM_WINDOW_SIZE,
+            distanceFromEnd: distanceFromEnd(metrics),
+            viewportHeight: metrics.viewportHeight,
+            drawDistance: NATIVE_STREAM_DRAW_DISTANCE,
           }),
       });
-      scrollOffsetYRef.current = 0;
-      streamViewportMetricsRef.current = {
-        ...streamViewportMetricsRef.current,
-        offsetY: 0,
-      };
+      const endOffsetY = Math.max(0, metrics.contentHeight - metrics.viewportHeight);
+      scrollOffsetYRef.current = endOffsetY;
+      streamViewportMetricsRef.current = { ...metrics, offsetY: endOffsetY };
       onNearBottomChange(true);
     },
     [onNearBottomChange],
@@ -262,7 +296,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     agentId,
     routeRequest: routeBottomAnchorRequest,
     isAuthoritativeHistoryReady,
-    renderStrategy: "inverted-stream",
+    renderStrategy: "legend-stream",
     getTransportBehavior: getBottomAnchorTransportBehavior,
     getMeasurementState: () => streamViewportMetricsRef.current,
     isNearBottom: () => {
@@ -277,60 +311,130 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     },
     scrollToBottom,
   });
-  // Android's maintainVisibleContentPosition ignores the list inversion transform and
-  // fights the controller's offset-zero correction while the live header grows.
-  const maintainVisibleContentPosition =
-    Platform.OS === "android" && bottomAnchorController.mode === "sticky-bottom"
-      ? undefined
-      : DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION;
-  const topOverlayInset = useStreamTopOverlayInset();
-  // The list is inverted, so its content's bottom padding is the visual top.
-  const listContentContainerStyle = useMemo(
-    () => [
-      baseListContentContainerStyle,
-      {
-        paddingBottom: streamKeyboardInset.contentContainerPaddingBottom + topOverlayInset,
-      },
-    ],
-    [
-      baseListContentContainerStyle,
-      streamKeyboardInset.contentContainerPaddingBottom,
-      topOverlayInset,
-    ],
+
+  const [rowLayoutSyncRegistry] = useState<RowLayoutSyncRegistry>(() => new Map());
+  const isAtEnd = useStableEvent(
+    () => distanceFromEnd(streamViewportMetricsRef.current) <= AT_END_OFFSET_PX,
   );
-  const listInsetProps = useMemo(
-    () =>
-      streamKeyboardInset.contentInset
-        ? {
-            automaticallyAdjustContentInsets: false,
-            automaticallyAdjustsScrollIndicatorInsets: false,
-            contentInsetAdjustmentBehavior: "never" as const,
-            contentInset: streamKeyboardInset.contentInset,
-            scrollIndicatorInsets: streamKeyboardInset.contentInset,
-          }
-        : {},
-    [streamKeyboardInset.contentInset],
+  // A hold on the content end mounts the end pin while detached (`holdRow`). The release reads the
+  // tracked distance instead of the offset: the content size reaches JS before the pin's scroll does.
+  const [endHold, setEndHold] = useState<{ rowId: string; distance: EndHoldDistance } | null>(null);
+  const releaseDisclosure = useStableEvent(() => {
+    setEndHold(null);
+    bottomAnchorController.releaseDisclosure({
+      isAtEnd: endHold ? endHold.distance.current() <= AT_END_OFFSET_PX : isAtEnd(),
+    });
+  });
+  const [disclosureHold] = useState(() =>
+    createNativeDisclosureHold({
+      quietFrames: DISCLOSURE_QUIET_FRAMES,
+      requestFrame: requestAnimationFrame,
+      cancelFrame: cancelAnimationFrame,
+      onRelease: releaseDisclosure,
+    }),
+  );
+  const cancelDisclosureHold = useStableEvent(() => {
+    disclosureHold.cancel();
+    setEndHold(null);
+  });
+  useEffect(() => () => cancelDisclosureHold(), [cancelDisclosureHold]);
+  // The hold detaches the controller in the same event as `apply`, so the toggle's commit already
+  // has end following off and LegendList anchoring on the held row, or on the row below it for a
+  // trigger on the row's bottom edge. The row's measurement trigger makes that same commit carry
+  // the row's new height. While following, a bottom trigger keeps following: the end pin holds the
+  // content end, and with it the bottom of the row, in the frame the new height mounts.
+  // The last row's bottom is the content end, which LegendList cannot anchor. The end pin can, from
+  // any offset, but only once it is mounted: a pin that mounts with the new height anchors nothing.
+  // So the toggle lands a frame after the pin's commit, whose mount runs before the frame's timers.
+  const latestDisclosureAnchor = useStableEvent(
+    (rowId: string, triggerEdge: DisclosureTriggerEdge) =>
+      disclosureAnchor(rows, rowId, triggerEdge),
+  );
+  const holdRow = useStableEvent(
+    (rowId: string, apply: () => void, triggerEdge: DisclosureTriggerEdge) => {
+      const applyAndMeasure = () => {
+        apply();
+        rowLayoutSyncRegistry.get(rowId)?.();
+      };
+      if (triggerEdge === "bottom" && bottomAnchorController.mode === "sticky-bottom") {
+        applyAndMeasure();
+        return;
+      }
+      const anchor = disclosureAnchor(rows, rowId, triggerEdge);
+      bottomAnchorController.holdForDisclosure();
+      if (anchor.kind === "row" || !isListPlacedRef.current) {
+        setEndHold(null);
+        disclosureHold.hold(anchor);
+        applyAndMeasure();
+        return;
+      }
+      setEndHold({
+        rowId,
+        distance: createEndHoldDistance(distanceFromEnd(streamViewportMetricsRef.current)),
+      });
+      disclosureHold.holdNextFrame(
+        () => latestDisclosureAnchor(rowId, triggerEdge),
+        (latestAnchor) => {
+          if (latestAnchor.kind === "row") setEndHold(null);
+          applyAndMeasure();
+        },
+      );
+    },
+  );
+  const handleItemSizeChanged = useStableEvent(
+    (info: { size: number; previous: number; itemKey: string; itemData: StreamItem }) => {
+      newRowEstimates.noteMeasured(info.itemData, info.size);
+      disclosureHold.noteItemSizeChanged();
+    },
+  );
+  const shouldRestorePosition = useStableEvent((item: StreamItem) => {
+    const anchorRowId = disclosureHold.anchorRowId();
+    return anchorRowId === null || item.id === anchorRowId;
+  });
+  // One owner keeps the scroll offset at any moment:
+  // - Before the list has placed its rows for the agent: LegendList's initial scroll to the end. It
+  //   keeps the rows hidden until they are measured and in place, so neither the pin nor the
+  //   controller acts; the content does not count as measured yet (`handleContentSizeChange`).
+  // - Following the end: the end pin. Rows added, rows resized and footer changes never scroll from
+  //   JS; the pin holds the end in the frame the change mounts. The controller scrolls only for a
+  //   viewport resize (the composer growing or shrinking), which the pin cannot see, and for an
+  //   explicit jump, and both go to the native end (`scrollToBottom`). The keyboard does not resize
+  //   the viewport: it translates the list with the composer. LegendList's end keeping stays off: it
+  //   scrolls to the end its JS sizes predict, which runs ahead of the native mount, so it lands
+  //   short of the real end and the controller reads that as the user scrolling away.
+  // - A disclosure hold: the held row. The hold detaches the controller, which removes the pin, and
+  //   LegendList keeps only the held row in place, or the row below it when the trigger sits on the
+  //   held row's bottom edge. A bottom-edge hold while following leaves the end pin in charge, and
+  //   one on the last row mounts the pin for the hold: the row's bottom is the content end.
+  // - A user scroll: the finger. The controller detaches for the gesture, so streamed lines grow below
+  //   the rows the user is dragging, and resumes following if the gesture ends at the end.
+  // - Detached: the visible rows. LegendList keeps the first visible row in place, so history loading
+  //   above or rows growing below leave what the user is reading where it is.
+  const isFollowingEnd = bottomAnchorController.mode === "sticky-bottom";
+  // An end hold pins the end only while its row's bottom is the end. A reply landing below the row
+  // drops the pin in the commit that mounts the reply, so the reply grows below the held row.
+  const isEndHeld =
+    endHold !== null && disclosureAnchor(rows, endHold.rowId, "bottom").kind === "end";
+  const isEndPinned = isFollowingEnd || isEndHeld;
+  const pinsEnd = isEndPinned && isListPlaced;
+  const maintainVisibleContentPosition = useMemo(
+    () => (isEndPinned ? false : { data: true, size: true, shouldRestorePosition }),
+    [isEndPinned, shouldRestorePosition],
+  );
+  // A new identity re-renders LegendList's scroll component, which is how the pin follows the mode.
+  const renderScrollComponent = useCallback(
+    (scrollProps: ScrollViewProps) => <EndPinnedScrollView {...scrollProps} pinEnd={pinsEnd} />,
+    [pinsEnd],
+  );
+  const topOverlayInset = useStreamTopOverlayInset();
+  // No keyboard inset: one committed after the keyboard settles moves every row when the end pin is
+  // not holding the offset (docs/agent-stream-disclosure.md).
+  const listContentContainerStyle = useMemo(
+    () => [baseListContentContainerStyle, { paddingTop: topOverlayInset }],
+    [baseListContentContainerStyle, topOverlayInset],
   );
 
   useEffect(() => {
-    streamViewportMetricsRef.current = {
-      containerKey: "native-virtualized",
-      contentHeight: 0,
-      viewportWidth: 0,
-      viewportHeight: 0,
-      offsetY: 0,
-      viewportMeasuredForKey: null,
-      contentMeasuredForKey: null,
-    };
-    scrollOffsetYRef.current = 0;
-    isUserScrollActiveRef.current = false;
-    clearPendingUserScrollEnd();
-    clearNativeViewportSettling();
-    isNativeViewportSettlingRef.current = false;
-    historyStartReadyRef.current = false;
-    const initialHistoryStartState = createHistoryStartPaginationState();
-    historyStartPaginationStateRef.current = initialHistoryStartState;
-    setHistoryStartPaginationState(initialHistoryStartState);
     const frame = requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
       evaluateHistoryStart();
@@ -338,16 +442,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     return () => {
       cancelAnimationFrame(frame);
       clearPendingUserScrollEnd();
+      disposeHistoryStart();
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd, evaluateHistoryStart]);
-
-  useEffect(() => () => clearNativeViewportSettling(), [clearNativeViewportSettling]);
-
-  useEffect(() => {
-    bottomAnchorController.prepareForStickyContentChange();
-  }, [bottomAnchorController, historyRows, segments.liveHead]);
+  }, [clearPendingUserScrollEnd, disposeHistoryStart, evaluateHistoryStart]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -359,9 +458,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       },
       prepareForViewportChange: () => {
         bottomAnchorController.prepareForStickyViewportChange();
-        markNativeViewportSettling();
       },
-      holdReadingPosition: () => bottomAnchorController.detachByUser(),
+      holdRow,
     };
     viewportRef.current = handle;
     return () => {
@@ -369,7 +467,32 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
         viewportRef.current = null;
       }
     };
-  }, [agentId, bottomAnchorController, markNativeViewportSettling, viewportRef]);
+  }, [agentId, bottomAnchorController, holdRow, viewportRef]);
+
+  // The scroll-to-bottom button shows whenever following would not resume on its own. A detached
+  // list resumes only from the end, so the button shows anywhere short of it. While following, the
+  // offset can trail content growth for a frame, so the controller's wider threshold keeps the
+  // button from flashing.
+  const publishNearBottom = useStableEvent(() => {
+    const metrics = streamViewportMetricsRef.current;
+    onNearBottomChange(
+      bottomAnchorController.mode === "detached"
+        ? distanceFromEnd(metrics) <= AT_END_OFFSET_PX
+        : isNearBottomForStreamRenderStrategy({
+            strategy,
+            offsetY: metrics.offsetY,
+            threshold: 32,
+            contentHeight: metrics.contentHeight,
+            viewportHeight: metrics.viewportHeight,
+          }),
+    );
+  });
+
+  // Following starts and stops without a scroll, for example when a disclosure hold begins short of
+  // the end, and the button follows it.
+  useEffect(() => {
+    publishNearBottom();
+  }, [isFollowingEnd, publishNearBottom]);
 
   const isScrollEventNearBottom = useStableEvent(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -384,6 +507,17 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     },
   );
 
+  const isScrollEventAtEnd = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+    return (
+      distanceFromEnd({
+        offsetY: contentOffset.y,
+        contentHeight: contentSize.height,
+        viewportHeight: layoutMeasurement.height,
+      }) <= AT_END_OFFSET_PX
+    );
+  });
+
   const handleScroll = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
     const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
     const previousOffsetY = scrollOffsetYRef.current;
@@ -401,14 +535,18 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     };
 
     const nearBottom = isScrollEventNearBottom(event);
-    onNearBottomChange(nearBottom);
+    publishNearBottom();
 
     evaluateHistoryStart();
 
     if (
       !isUserScrollActiveRef.current &&
       programmaticScrollEventBudgetRef.current > 0 &&
-      contentOffset.y <= 8
+      distanceFromEnd({
+        offsetY: contentOffset.y,
+        contentHeight: contentSize.height,
+        viewportHeight: layoutMeasurement.height,
+      }) <= 8
     ) {
       programmaticScrollEventBudgetRef.current -= 1;
     } else {
@@ -421,29 +559,38 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   });
 
   const handleScrollBeginDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    finishInitialFill();
     clearPendingUserScrollEnd();
     isUserScrollActiveRef.current = true;
     scrollKeyboardDismiss.onScrollBeginDrag(event);
+    // The gesture takes the viewport from a disclosure hold. Size changes from a streaming row can
+    // keep the hold's quiet frames from ever passing, and a held row that scrolls away would leave
+    // no row LegendList may anchor a history page on. The gesture's end decides following.
+    cancelDisclosureHold();
     bottomAnchorController.beginUserScroll();
-    const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
-    if (rearmed !== historyStartPaginationStateRef.current) {
-      historyStartPaginationStateRef.current = rearmed;
-      setHistoryStartPaginationState(rearmed);
-      evaluateHistoryStart();
-    }
+    historyStartPagination.rearm();
   });
 
-  // Defer drag end so momentum can take ownership, but capture the terminal
-  // gesture position now because layout may move the viewport in the meantime.
+  useEffect(() => {
+    if (revealInitialHistory) finishInitialFill();
+  }, [finishInitialFill, revealInitialHistory]);
+
+  // A gesture ends at the end when the finger lifts at or past it, or when its momentum stops there.
+  // A release past the end bounces back to it on iOS, and lines that land during the bounce scroll
+  // in as they do while following. Momentum stopping short of the end, or output that arrived below
+  // the viewport before the decision, leaves the list detached.
+  // Drag end is deferred a frame so momentum can take ownership.
   const handleScrollEndDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
-    const isNearBottom = isScrollEventNearBottom(event);
     scrollKeyboardDismiss.onScrollEndDrag(event);
+    isReleasedAtEndRef.current = isScrollEventAtEnd(event);
 
     clearPendingUserScrollEnd();
     userScrollEndFrameIdRef.current = requestAnimationFrame(() => {
       userScrollEndFrameIdRef.current = null;
       isUserScrollActiveRef.current = false;
-      bottomAnchorController.endUserScroll({ isNearBottom });
+      bottomAnchorController.endUserScroll({
+        isAtEnd: isReleasedAtEndRef.current || isAtEnd(),
+      });
     });
   });
 
@@ -458,10 +605,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       if (!isUserScrollActiveRef.current) {
         return;
       }
-      const isNearBottom = isScrollEventNearBottom(event);
       clearPendingUserScrollEnd();
       isUserScrollActiveRef.current = false;
-      bottomAnchorController.endUserScroll({ isNearBottom });
+      bottomAnchorController.endUserScroll({
+        isAtEnd: isReleasedAtEndRef.current || isScrollEventAtEnd(event),
+      });
     },
   );
 
@@ -470,9 +618,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     const previousViewportHeight = streamViewportMetricsRef.current.viewportHeight;
     const viewportWidth = Math.max(0, event.nativeEvent.layout.width);
     const viewportHeight = Math.max(0, event.nativeEvent.layout.height);
-    const viewportChanged =
-      (previousViewportWidth > 0 && previousViewportWidth !== viewportWidth) ||
-      (previousViewportHeight > 0 && previousViewportHeight !== viewportHeight);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       containerKey: "native-virtualized",
@@ -480,9 +625,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       viewportHeight,
       viewportMeasuredForKey: "native-virtualized",
     };
-    if (viewportChanged) {
-      markNativeViewportSettling();
-    }
     bottomAnchorController.handleViewportMetricsChange({
       previousViewportWidth,
       viewportWidth,
@@ -493,149 +635,166 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   });
 
   const handleContentSizeChange = useStableEvent((_width: number, height: number) => {
-    const previousContentHeight = streamViewportMetricsRef.current.contentHeight;
     const nextContentHeight = Math.max(0, height);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       containerKey: "native-virtualized",
       contentHeight: nextContentHeight,
-      contentMeasuredForKey: "native-virtualized",
+      contentMeasuredForKey: isListPlacedRef.current ? "native-virtualized" : null,
     };
-    bottomAnchorController.handleContentSizeChange({
-      previousContentHeight,
-      contentHeight: nextContentHeight,
-    });
+    endHold?.distance.noteContentSize(streamViewportMetricsRef.current);
+    bottomAnchorController.handleContentSizeChange();
+    // Content growing below a detached viewport moves the end away without a scroll event.
+    if (
+      bottomAnchorController.mode === "detached" &&
+      streamViewportMetricsRef.current.viewportHeight > 0
+    ) {
+      publishNearBottom();
+    }
     evaluateHistoryStart();
-    if (historyStartPaginationStateRef.current.status === "settling") {
+    if (isHistoryStartSettling()) {
       scheduleHistoryStartSettle();
     }
   });
 
+  const handleListPlaced = useStableEvent(() => {
+    isListPlacedRef.current = true;
+    setIsListPlaced(true);
+    streamViewportMetricsRef.current = {
+      ...streamViewportMetricsRef.current,
+      contentMeasuredForKey: "native-virtualized",
+    };
+    bottomAnchorController.handleContentSizeChange();
+    evaluateHistoryStart();
+  });
+
   useEffect(() => {
     evaluateHistoryStart();
-    if (historyStartPaginationStateRef.current.status === "settling") {
+    if (isHistoryStartSettling()) {
       scheduleHistoryStartSettle();
     }
   }, [
     evaluateHistoryStart,
     hasOlderHistory,
+    isActive,
+    isAuthoritativeHistoryReady,
     isLoadingOlderHistory,
     olderHistoryProgressKey,
     scheduleHistoryStartSettle,
+    isHistoryStartSettling,
   ]);
 
+  // LegendList re-renders a mounted row only when its item or `extraData` changes, not when
+  // renderItem does. Item identity carries content and display changes (`useRevisedHistoryRows`);
+  // `extraData` carries the history renderer, whose identity changes with the history layout (a
+  // reply gaining its completed footer when the next prompt arrives) and keeps its row's item.
+  // StreamRow's memo limits that pass to the rows whose layout item changed.
   const renderItem = useStableEvent(
-    ({ item, index }: ListRenderItemInfo<StreamItem>): ReactElement | null => {
-      const rendered = renderHistoryMountedRow(item, index, historyItems);
-      return (rendered ?? null) as ReactElement | null;
-    },
+    ({ item, index }: LegendListRenderItemProps<StreamItem>): ReactElement => (
+      <RowLayoutSync rowId={item.id} registry={rowLayoutSyncRegistry}>
+        {liveRowIds.has(item.id)
+          ? renderLiveHeadRow(item, index - historyRows.length, segments.liveHead)
+          : renderHistoryMountedRow(item, index, historyItems)}
+      </RowLayoutSync>
+    ),
   );
 
-  const liveHeaderContent = useMemo(() => {
-    // Stable render events read the latest expansion state; this revision makes
-    // the memo invoke them again when that state changes.
-    void liveHeadRowRevision;
-    const liveHeadRows = segments.liveHead.map((item, index) => (
-      <Fragment key={item.id}>{renderLiveHeadRow(item, index, segments.liveHead)}</Fragment>
-    ));
+  const liveAuxiliaryContent = useMemo(() => {
     const liveAuxiliary = renderLiveAuxiliary();
     if (
-      liveHeadRows.length === 0 &&
+      liveRows.length === 0 &&
       !liveAuxiliary &&
       !boundary.hasMountedHistory &&
       !boundary.hasVirtualizedHistory
     ) {
       return (listEmptyComponent ?? null) as ReactElement | null;
     }
-    return (
-      <Fragment>
-        {liveHeadRows}
-        {liveAuxiliary}
-      </Fragment>
-    );
-  }, [
-    boundary,
-    listEmptyComponent,
-    liveHeadRowRevision,
-    renderLiveAuxiliary,
-    renderLiveHeadRow,
-    segments.liveHead,
-  ]);
+    return <View>{liveAuxiliary}</View>;
+  }, [boundary, listEmptyComponent, liveRows.length, renderLiveAuxiliary]);
 
-  const historyFooterContent = useMemo(() => {
+  const historyStartContent = useMemo(() => {
     const isLoadingOperation = isHistoryStartLoadingOperation(historyStartPaginationState);
     return (
       <View style={historyStartSlotStyle} testID="older-history-slot">
-        {isLoadingOperation ? (
+        {isLoadingOperation && (
           <View testID="load-older-history-spinner">
             <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
           </View>
-        ) : null}
+        )}
+        {!isLoadingOperation &&
+          historyStartPaginationState.status === "failed" &&
+          hasOlderHistory && (
+            <Button variant="ghost" size="sm" onPress={retryHistoryStart}>
+              {t("paneFind.retry")}
+            </Button>
+          )}
       </View>
     );
-  }, [historyStartPaginationState]);
+  }, [historyStartPaginationState, hasOlderHistory, retryHistoryStart, t]);
 
-  // RN's FlatList strictMode keeps its internal renderItem wrapper stable when
-  // data or the live header changes, preserving the row identities above.
   return (
-    <FlatList
-      {...listInsetProps}
-      ref={flatListRef}
-      data={historyRows}
-      renderItem={renderItem}
-      keyExtractor={keyExtractor}
-      strictMode
-      testID="agent-chat-scroll"
-      nativeID="agent-chat-scroll-native-virtualized"
-      ListHeaderComponent={liveHeaderContent ?? undefined}
-      ListFooterComponent={historyFooterContent ?? undefined}
-      contentContainerStyle={listContentContainerStyle}
-      style={listStyle}
-      onLayout={handleListLayout}
-      onScroll={handleScroll}
-      onScrollBeginDrag={handleScrollBeginDrag}
-      onScrollEndDrag={handleScrollEndDrag}
-      onMomentumScrollBegin={handleMomentumScrollBegin}
-      onMomentumScrollEnd={handleMomentumScrollEnd}
-      scrollEventThrottle={16}
-      onContentSizeChange={handleContentSizeChange}
-      maintainVisibleContentPosition={maintainVisibleContentPosition}
-      // Tall Markdown rows exhaust a shallow window during flings. Keep the initial
-      // render small, then refill a deeper window in batches large enough to keep up.
-      initialNumToRender={2}
-      maxToRenderPerBatch={10}
-      windowSize={NATIVE_STREAM_WINDOW_SIZE}
-      removeClippedSubviews={false}
-      scrollEnabled={scrollEnabled}
-      showsVerticalScrollIndicator
-      inverted
-    />
+    <View style={viewportStyle}>
+      <LegendList<StreamItem>
+        ref={listRef}
+        data={rows}
+        renderItem={renderItem}
+        extraData={renderHistoryMountedRow}
+        keyExtractor={keyExtractor}
+        testID="agent-chat-scroll"
+        nativeID="agent-chat-scroll-native-virtualized"
+        ListHeaderComponent={historyStartContent}
+        ListFooterComponent={liveAuxiliaryContent ?? undefined}
+        contentContainerStyle={listContentContainerStyle}
+        automaticallyAdjustContentInsets={false}
+        automaticallyAdjustsScrollIndicatorInsets={false}
+        contentInsetAdjustmentBehavior="never"
+        style={[listStyle, { opacity: historyStartPaginationState.visible ? 1 : 0 }]}
+        onLayout={handleListLayout}
+        onScroll={handleScroll}
+        onScrollBeginDrag={handleScrollBeginDrag}
+        onScrollEndDrag={handleScrollEndDrag}
+        onMomentumScrollBegin={handleMomentumScrollBegin}
+        onMomentumScrollEnd={handleMomentumScrollEnd}
+        scrollEventThrottle={16}
+        onContentSizeChange={handleContentSizeChange}
+        onItemSizeChanged={handleItemSizeChanged}
+        onReady={handleListPlaced}
+        maintainVisibleContentPosition={maintainVisibleContentPosition}
+        renderScrollComponent={renderScrollComponent}
+        recycleItems={false}
+        alignItemsAtEnd
+        initialScrollAtEnd
+        drawDistance={NATIVE_STREAM_DRAW_DISTANCE}
+        getEstimatedItemSize={getEstimatedItemSize}
+        scrollEnabled={scrollEnabled}
+        showsVerticalScrollIndicator
+      />
+      {!historyStartPaginationState.visible ? (
+        <View pointerEvents="none" testID="agent-initial-fill" style={initialFillStyle}>
+          <ThemedLoadingSpinner size="large" uniProps={foregroundMutedColorMapping} />
+        </View>
+      ) : null}
+    </View>
   );
 }
 
 export function createNativeStreamStrategy(): StreamStrategy {
   const strategy = createStreamStrategy({
     render: (renderInput) => <NativeStreamViewport {...renderInput} strategy={strategy} />,
-    orderTailReverse: true,
-    orderHeadReverse: true,
-    assistantTurnTraversalStep: 1,
-    edgeSlot: "header",
-    historyLiveBoundaryEdge: "first",
-    liveHeadHistoryBoundaryEdge: "last",
-    frameChildOrder: "footer-then-content",
-    flatListInverted: true,
-    overlayScrollbarInverted: true,
-    maintainVisibleContentPosition: DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION,
-    bottomAnchorTransportBehavior: {
-      verificationDelayFrames: 2,
-      verificationRetryMode: "recheck",
-    },
+    orderTailReverse: false,
+    orderHeadReverse: false,
+    assistantTurnTraversalStep: -1,
+    edgeSlot: "footer",
+    historyLiveBoundaryEdge: "last",
+    liveHeadHistoryBoundaryEdge: "first",
+    frameChildOrder: "content-then-footer",
+    bottomAnchorTransportBehavior: BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR,
     disableParentScrollOnInlineDetailsExpansion: false,
     anchorBottomOnContentSizeChange: false,
     animateManualScrollToBottom: true,
     useVirtualizedList: true,
-    isNearBottom: (input) => input.offsetY <= input.threshold,
-    getBottomOffset: () => 0,
+    isNearBottom: (input) => distanceFromEnd(input) <= input.threshold,
+    getBottomOffset: (metrics) => Math.max(0, metrics.contentHeight - metrics.viewportHeight),
   });
   return strategy;
 }
diff --git a/packages/app/src/agent-stream/strategy-web.browser.test.tsx b/packages/app/src/agent-stream/strategy-web.browser.test.tsx
new file mode 100644
index 0000000000..12127ea630
--- /dev/null
+++ b/packages/app/src/agent-stream/strategy-web.browser.test.tsx
@@ -0,0 +1,210 @@
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
+import type { StreamItem } from "@/types/stream";
+import type { DisclosureTriggerEdge, StreamRenderInput, StreamViewportHandle } from "./strategy";
+import { createWebStreamStrategy } from "./strategy-web";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const VIEWPORT_HEIGHT = 100;
+const ROW_HEIGHT = 40;
+
+// A row's height comes from its text, so a disclosure that opens or grows a row is a new item
+// for that row, as it is in the app.
+function row(index: number, height = ROW_HEIGHT): Extract<StreamItem, { kind: "user_message" }> {
+  return {
+    kind: "user_message",
+    id: `message-${index}`,
+    text: String(height),
+    timestamp: new Date(`2026-04-20T00:00:${String(index % 60).padStart(2, "0")}.000Z`),
+  };
+}
+
+const rowStyleByHeight = new Map<number, { height: number }>();
+
+function renderRow(item: StreamItem) {
+  const height = item.kind === "user_message" ? Number(item.text) : ROW_HEIGHT;
+  let style = rowStyleByHeight.get(height);
+  if (!style) {
+    style = { height };
+    rowStyleByHeight.set(height, style);
+  }
+  return <div style={style}>{item.id}</div>;
+}
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  host.style.cssText = `display:flex;flex-direction:column;width:500px;height:${VIEWPORT_HEIGHT}px`;
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+function mountTimeline(historyMounted: StreamItem[]) {
+  const strategy = createWebStreamStrategy({ isMobileBreakpoint: true });
+  const viewportRef = React.createRef<StreamViewportHandle>();
+  const input: StreamRenderInput = {
+    agentId: "agent",
+    segments: { historyVirtualized: [], historyMounted, liveHead: [] },
+    boundary: { hasVirtualizedHistory: false, hasMountedHistory: true, hasLiveHead: false },
+    renderers: {
+      renderHistoryVirtualizedRow: renderRow,
+      renderHistoryMountedRow: renderRow,
+      renderLiveHeadRow: renderRow,
+      renderLiveAuxiliary: () => null,
+    },
+    listEmptyComponent: null,
+    viewportRef,
+    routeBottomAnchorRequest: null,
+    isAuthoritativeHistoryReady: true,
+    onNearBottomChange: () => {},
+    onNearHistoryStart: async () => true,
+    isLoadingOlderHistory: false,
+    hasOlderHistory: false,
+    olderHistoryProgressKey: null,
+    scrollEnabled: true,
+    listStyle: null,
+    baseListContentContainerStyle: null,
+    forwardListContentContainerStyle: null,
+    contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
+  };
+  const render = (segments: Partial<StreamRenderInput["segments"]>) =>
+    root.render(strategy.render({ ...input, segments: { ...input.segments, ...segments } }));
+  act(() => render({}));
+
+  const scrollContainer = host.querySelector<HTMLElement>('[data-testid="agent-chat-scroll"]');
+  if (!scrollContainer) throw new Error("Expected agent chat scroll container");
+  const rowElement = (id: string) => {
+    const element = host.querySelector<HTMLElement>(`[data-history-row-id="${id}"]`);
+    if (!element) throw new Error(`Expected row ${id}`);
+    return element;
+  };
+
+  return {
+    render: (segments: Partial<StreamRenderInput["segments"]>) => act(() => render(segments)),
+    hold: (rowId: string, apply: () => void, triggerEdge: DisclosureTriggerEdge = "top") =>
+      act(() => viewportRef.current!.holdRow(rowId, apply, triggerEdge)),
+    rowTop: (id: string) =>
+      rowElement(id).getBoundingClientRect().top - scrollContainer.getBoundingClientRect().top,
+    rowBottom: (id: string) =>
+      rowElement(id).getBoundingClientRect().bottom - scrollContainer.getBoundingClientRect().top,
+    scrollTo: (top: number) => {
+      scrollContainer.scrollTop = top;
+    },
+    distanceFromEnd: () =>
+      scrollContainer.scrollHeight - scrollContainer.clientHeight - scrollContainer.scrollTop,
+    // Resize observers and the hold's settle run on animation frames.
+    settle: () =>
+      act(async () => {
+        for (let frame = 0; frame < 4; frame += 1) {
+          await new Promise((resolve) => requestAnimationFrame(resolve));
+        }
+      }),
+  };
+}
+
+describe("web disclosure hold", () => {
+  it("keeps the trigger's top when an anchored toggle at the bottom opens rows below it, and stops following", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    expect(timeline.distanceFromEnd()).toBeLessThanOrEqual(1);
+    const triggerTop = timeline.rowTop("message-5");
+
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 5), row(7, 200), history[5]!] }),
+    );
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+
+    timeline.render({ liveHead: [row(8)] });
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+  });
+
+  it("keeps the trigger's top when its row grows while following output", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    const triggerTop = timeline.rowTop("message-5");
+
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 4), row(5, 240), history[5]!] }),
+    );
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+  });
+
+  // A long message's show more sits under the text it opens, on the bottom edge of its row.
+  it("keeps the bottom of a bottom-trigger row through show more and show less while following output", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    const triggerBottom = timeline.rowBottom("message-5");
+
+    timeline.hold(
+      "message-5",
+      () => timeline.render({ historyMounted: [...history.slice(0, 4), row(5, 240), history[5]!] }),
+      "bottom",
+    );
+    await timeline.settle();
+    expect(timeline.rowBottom("message-5")).toBe(triggerBottom);
+
+    timeline.hold("message-5", () => timeline.render({ historyMounted: history }), "bottom");
+    await timeline.settle();
+    expect(timeline.rowBottom("message-5")).toBe(triggerBottom);
+  });
+
+  it("keeps the bottom of a bottom-trigger row through show more and show less when scrolled up", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    timeline.scrollTo(60);
+    await timeline.settle();
+    // message-2 is cut off at the top; message-3 is fully in view.
+    for (const index of [2, 3]) {
+      const triggerBottom = timeline.rowBottom(`message-${index}`);
+      const grown = history.map((item, position) =>
+        position === index - 1 ? row(index, 240) : item,
+      );
+
+      timeline.hold(`message-${index}`, () => timeline.render({ historyMounted: grown }), "bottom");
+      await timeline.settle();
+      expect(timeline.rowBottom(`message-${index}`)).toBe(triggerBottom);
+
+      timeline.hold(
+        `message-${index}`,
+        () => timeline.render({ historyMounted: history }),
+        "bottom",
+      );
+      await timeline.settle();
+      expect(timeline.rowBottom(`message-${index}`)).toBe(triggerBottom);
+    }
+  });
+
+  it("resumes following when collapsing an anchored row lands back at the end", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 4), row(5, 240), history[5]!] }),
+    );
+    await timeline.settle();
+
+    timeline.hold("message-5", () => timeline.render({ historyMounted: history }));
+    await timeline.settle();
+
+    timeline.render({ liveHead: [row(8)] });
+    await timeline.settle();
+    expect(timeline.distanceFromEnd()).toBeLessThanOrEqual(1);
+  });
+});
diff --git a/packages/app/src/agent-stream/strategy-web.test.tsx b/packages/app/src/agent-stream/strategy-web.test.tsx
index 5ad0be03c2..3601c8b0b2 100644
--- a/packages/app/src/agent-stream/strategy-web.test.tsx
+++ b/packages/app/src/agent-stream/strategy-web.test.tsx
@@ -152,7 +152,7 @@ describe("createWebStreamStrategy", () => {
         routeBottomAnchorRequest: null,
         isAuthoritativeHistoryReady: true,
         onNearBottomChange: () => {},
-        onNearHistoryStart: () => true,
+        onNearHistoryStart: async () => true,
         isLoadingOlderHistory: false,
         hasOlderHistory: false,
         olderHistoryProgressKey: null,
@@ -274,7 +274,7 @@ describe("createWebStreamStrategy", () => {
       routeBottomAnchorRequest: null,
       isAuthoritativeHistoryReady: true,
       onNearBottomChange: () => {},
-      onNearHistoryStart: () => true,
+      onNearHistoryStart: async () => true,
       isLoadingOlderHistory: false,
       hasOlderHistory: false,
       olderHistoryProgressKey: null,
diff --git a/packages/app/src/agent-stream/strategy-web.tsx b/packages/app/src/agent-stream/strategy-web.tsx
index 9dae42bcc0..c47e0720f4 100644
--- a/packages/app/src/agent-stream/strategy-web.tsx
+++ b/packages/app/src/agent-stream/strategy-web.tsx
@@ -20,6 +20,7 @@ import { withUnistyles } from "react-native-unistyles";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useStableEvent } from "@/hooks/use-stable-event";
+import { useTranslation } from "react-i18next";
 import { getStreamItemMessageId, type StreamItem } from "@/types/stream";
 import type { Theme } from "@/styles/theme";
 import { WEB_SCROLLBAR_SIZE_PX } from "@/styles/web-scrollbar";
@@ -30,15 +31,10 @@ import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./
 import { useRevisedHistoryRows } from "./history-row-revision";
 import { createStreamStrategy } from "./strategy";
 import {
-  abandonHistoryStartPaginationRequest,
-  createHistoryStartPaginationState,
-  evaluateHistoryStartPagination,
   isHistoryStartLoadingOperation,
-  rearmHistoryStartPagination,
-  settleHistoryStartPagination,
   type HistoryStartPaginationInput,
-  type HistoryStartPaginationTransition,
 } from "./history-start-pagination";
+import { useHistoryStartPagination } from "./use-history-start-pagination";
 import {
   createHistoryStartSettleScheduler,
   type HistoryStartSettleScheduler,
@@ -77,7 +73,17 @@ const historyStartSlotStyle: CSSProperties = {
 };
 
 const streamRowsHostStyle: CSSProperties = { position: "relative", width: "100%" };
+const initialFillStyle: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  pointerEvents: "none",
+};
 
+// Rows and the live auxiliary (turn footer, pending permissions) center their content with
+// `alignSelf`, which only applies inside a flex container.
 const streamRowStyle: CSSProperties = {
   display: "flex",
   flexDirection: "column",
@@ -298,6 +304,8 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     viewportRef,
     routeBottomAnchorRequest,
     isAuthoritativeHistoryReady,
+    isInitialHistoryLoading,
+    revealInitialHistory,
     onNearBottomChange,
     onReadingPositionChange,
     onNearHistoryStart,
@@ -318,6 +326,9 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     [historyMounted, historyVirtualized, inputSegments],
   );
   const isActive = useRetainedPanelActive();
+  const { t } = useTranslation();
+  const rowsHostRef = useRef<HTMLDivElement | null>(null);
+  const auxiliaryRef = useRef<HTMLDivElement | null>(null);
   const isActiveRef = useRef(isActive);
   const scrollContainerRef = useRef<HTMLElement | null>(null);
   const contentRef = useRef<HTMLElement | null>(null);
@@ -351,10 +362,6 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const pendingAutoScrollFrameRef = useRef<number | null>(null);
   const pendingAutoScrollTimeoutRef = useRef<number | null>(null);
   const historyStartReadyRef = useRef(false);
-  const [historyStartPaginationState, setHistoryStartPaginationState] = useState(
-    createHistoryStartPaginationState,
-  );
-  const historyStartPaginationStateRef = useRef(historyStartPaginationState);
   const readingAnchor = useMemo(createReadingAnchor, []);
   const measuredRowHeights = useRef(new Map<string, { width: number; height: number }>());
   const historyStartSettleSchedulerRef = useRef<HistoryStartSettleScheduler | null>(null);
@@ -363,6 +370,8 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const wasFollowOutputLayoutActiveRef = useRef(false);
   const resumedUnchangedLayoutRef = useRef(false);
   const pendingResumeGeometryCheckRef = useRef(false);
+  // Set by holdRow; the next reading reconcile sees the disclosure's layout.
+  const disclosurePendingRef = useRef(false);
   const shouldUseVirtualizer = segments.historyVirtualized.length > 0;
   const {
     renderHistoryVirtualizedRow,
@@ -409,6 +418,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
               {
                 id: String(measurement.key),
                 top: measurement.start,
+                height: measurement.size,
               },
               props.readingRowReplacements,
             )
@@ -479,60 +489,36 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       !followOutputRef.current || isScrollContainerNearBottom(scrollContainer);
     return {
       distanceFromHistoryStart: scrollContainer.scrollTop,
+      isUnderfilled:
+        (rowsHostRef.current?.getBoundingClientRect().height ?? 0) +
+          (auxiliaryRef.current?.getBoundingClientRect().height ?? 0) <
+        scrollContainer.clientHeight,
       hasOlderHistory,
       isLoadingOlderHistory,
       // An explicit jump owns the landing position. Revealing another local
       // page here changes the virtual index before the target has mounted.
-      isReady: historyStartReadyRef.current && bottomAnchorSettled && !isJumpSettling(),
+      isReady:
+        historyStartReadyRef.current &&
+        isAuthoritativeHistoryReady &&
+        bottomAnchorSettled &&
+        !isJumpSettling(),
       progressKey: olderHistoryProgressKey,
     };
   });
-  const applyHistoryStartPaginationTransition = useStableEvent(
-    (transition: HistoryStartPaginationTransition) => {
-      const previousState = historyStartPaginationStateRef.current;
-      historyStartPaginationStateRef.current = transition.state;
-      if (transition.state !== previousState) {
-        setHistoryStartPaginationState(transition.state);
-      }
-      if (!transition.shouldLoad || olderHistoryProgressKey === null) {
-        return;
-      }
-      const requestedProgressKey = olderHistoryProgressKey;
-      void (async () => {
-        const started = await onNearHistoryStart();
-        if (started === true) {
-          return;
-        }
-        applyHistoryStartPaginationTransition({
-          state: abandonHistoryStartPaginationRequest(
-            historyStartPaginationStateRef.current,
-            requestedProgressKey,
-          ),
-          shouldLoad: false,
-        });
-      })();
-    },
+  const { state: historyStartPaginationState, controller: historyStartPagination } =
+    useHistoryStartPagination({
+      initiallyVisible: !isInitialHistoryLoading,
+      read: getHistoryStartPaginationInput,
+      load: async () => onNearHistoryStart(),
+      scheduleSettle: () => scheduleHistoryStartPrependSettle(),
+    });
+  const evaluateHistoryStart = useStableEvent(() => historyStartPagination.update());
+  const disposeHistoryStart = useStableEvent(() => historyStartPagination.dispose());
+  const isHistoryStartSettling = useStableEvent(
+    () => historyStartPagination.state.status === "settling",
   );
-  const evaluateHistoryStart = useStableEvent(() => {
-    const input = getHistoryStartPaginationInput();
-    if (!input) {
-      return;
-    }
-    const transition = evaluateHistoryStartPagination(
-      historyStartPaginationStateRef.current,
-      input,
-    );
-    applyHistoryStartPaginationTransition(transition);
-  });
-  const rearmHistoryStartFromUserIntent = useStableEvent(() => {
-    const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
-    if (rearmed === historyStartPaginationStateRef.current) {
-      return;
-    }
-    historyStartPaginationStateRef.current = rearmed;
-    setHistoryStartPaginationState(rearmed);
-    evaluateHistoryStart();
-  });
+  const finishInitialFill = useStableEvent(() => historyStartPagination.reveal());
+  const rearmHistoryStartFromUserIntent = useStableEvent(() => historyStartPagination.rearm());
   const scheduleHistoryStartPrependSettle = useStableEvent(() => {
     let scheduler = historyStartSettleSchedulerRef.current;
     if (!scheduler) {
@@ -540,22 +526,12 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         settleFrames: HISTORY_START_SETTLE_FRAMES,
         requestFrame: (callback) => window.requestAnimationFrame(callback),
         cancelFrame: (frame) => window.cancelAnimationFrame(frame),
-        isSettling: () => historyStartPaginationStateRef.current.status === "settling",
+        isSettling: () => isHistoryStartSettling(),
         isLoading: () => {
           const input = getHistoryStartPaginationInput();
           return !input || input.isLoadingOlderHistory;
         },
-        onSettle: () => {
-          const input = getHistoryStartPaginationInput();
-          if (!input) {
-            return;
-          }
-          const transition = settleHistoryStartPagination(
-            historyStartPaginationStateRef.current,
-            input,
-          );
-          applyHistoryStartPaginationTransition(transition);
-        },
+        onSettle: () => historyStartPagination.settle(),
       });
       historyStartSettleSchedulerRef.current = scheduler;
     }
@@ -728,22 +704,27 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     onNearBottomChange,
   });
 
-  const reconcileReadingPosition = useStableEvent(() => {
+  // Row tops in content coordinates, which survive scrolling.
+  const measureRows = useStableEvent(() => {
     const container = scrollContainerRef.current;
     const content = contentRef.current;
-    if (!isActiveRef.current || !container || !content) return;
+    if (!container || !content) return null;
     const viewportTop = container.getBoundingClientRect().top;
     const scrollTop = container.scrollTop;
     const width = content.getBoundingClientRect().width;
-    const rows = Array.from(
-      content.querySelectorAll<HTMLElement>("[data-history-row-id]"),
-      (element) => {
-        const bounds = element.getBoundingClientRect();
-        const id = element.dataset.historyRowId!;
-        measuredRowHeights.current.set(id, { width, height: bounds.height });
-        return { id, top: bounds.top - viewportTop + scrollTop, height: bounds.height };
-      },
-    );
+    return Array.from(content.querySelectorAll<HTMLElement>("[data-history-row-id]"), (element) => {
+      const bounds = element.getBoundingClientRect();
+      const id = element.dataset.historyRowId!;
+      measuredRowHeights.current.set(id, { width, height: bounds.height });
+      return { id, top: bounds.top - viewportTop + scrollTop, height: bounds.height };
+    });
+  });
+
+  const reconcileReadingPosition = useStableEvent(() => {
+    const container = scrollContainerRef.current;
+    if (!isActiveRef.current || !container) return;
+    const rows = measureRows();
+    if (!rows) return;
     const shouldAnchor = !followOutputRef.current && !isJumpSettling();
     if (!shouldAnchor) readingAnchor.reset();
     const correctedTop = readingAnchor.reconcile(
@@ -763,6 +744,11 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       // this layout so the reader does not get a frame containing only the pin.
       virtualOffsetListener.current?.(container.scrollTop, false);
     }
+    // A disclosure that closes back to the end of the list rejoins the output.
+    if (disclosurePendingRef.current) {
+      disclosurePendingRef.current = false;
+      if (isScrollContainerAtBottom(container)) setFollowOutput(true);
+    }
   });
 
   // Apply row positions and their scroll correction in the same paint, including
@@ -782,6 +768,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   ]);
 
   const stopFollowingOutputFromUserIntent = useStableEvent(() => {
+    finishInitialFill();
     cancelPendingStickToBottom();
     if (followOutputRef.current) {
       setFollowOutput(false);
@@ -789,6 +776,10 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     rearmHistoryStartFromUserIntent();
   });
 
+  useEffect(() => {
+    if (revealInitialHistory) finishInitialFill();
+  }, [finishInitialFill, revealInitialHistory]);
+
   const handleDomScroll = useCallback(() => {
     const scrollContainer = scrollContainerRef.current;
     if (!isActiveRef.current || !scrollContainer || !isScrollContainerMeasurable(scrollContainer)) {
@@ -827,10 +818,6 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   ]);
 
   useEffect(() => {
-    const initialHistoryStartState = createHistoryStartPaginationState();
-    historyStartPaginationStateRef.current = initialHistoryStartState;
-    setHistoryStartPaginationState(initialHistoryStartState);
-    readingAnchor.reset();
     const frame = window.requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
       evaluateHistoryStart();
@@ -838,10 +825,11 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     return () => {
       window.cancelAnimationFrame(frame);
       historyStartReadyRef.current = false;
+      disposeHistoryStart();
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [evaluateHistoryStart, props.agentId, readingAnchor]);
+  }, [disposeHistoryStart, evaluateHistoryStart]);
 
   useLayoutEffect(() => {
     if (!isActiveRef.current || !isActivationReady) {
@@ -930,16 +918,18 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       updateScrollMetrics();
     }
     evaluateHistoryStart();
-    if (historyStartPaginationStateRef.current.status === "settling") {
+    if (isHistoryStartSettling()) {
       scheduleHistoryStartPrependSettle();
     }
   }, [
     evaluateHistoryStart,
     hasOlderHistory,
     isActive,
+    isAuthoritativeHistoryReady,
     isLoadingOlderHistory,
     olderHistoryProgressKey,
     scheduleHistoryStartPrependSettle,
+    isHistoryStartSettling,
     segments.historyMounted.length,
     segments.historyVirtualized.length,
     segments.liveHead.length,
@@ -978,7 +968,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         lastObservedViewportGeometryRef.current = nextGeometry;
       }
       reconcileReadingPosition();
-      if (historyStartPaginationStateRef.current.status === "settling") {
+      if (isHistoryStartSettling()) {
         scheduleHistoryStartPrependSettle();
       }
       updateScrollMetrics();
@@ -1012,6 +1002,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     isActive,
     reportReadingPosition,
     scheduleHistoryStartPrependSettle,
+    isHistoryStartSettling,
     forceStickToBottom,
     updateScrollMetrics,
     measureVirtualizedRows,
@@ -1182,10 +1173,14 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         }
         scheduleStickToBottom();
       },
-      holdReadingPosition: () => {
+      holdRow: (rowId, apply, triggerEdge) => {
         cancelPendingStickToBottom();
         setFollowOutput(false);
-        readingAnchor.scroll(scrollContainerRef.current?.scrollTop ?? 0);
+        const row = measureRows()?.find((candidate) => candidate.id === rowId);
+        const scrollTop = scrollContainerRef.current?.scrollTop;
+        if (row && scrollTop !== undefined) readingAnchor.pin(row, triggerEdge, scrollTop);
+        disclosurePendingRef.current = true;
+        apply();
       },
       scrollToMessage,
     };
@@ -1199,6 +1194,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   }, [
     cancelPendingStickToBottom,
     forceStickToBottom,
+    measureRows,
     readingAnchor,
     scheduleStickToBottom,
     scrollToMessage,
@@ -1229,8 +1225,9 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       // Detached reading has one owner: reconcileReadingPosition.
       overflowAnchor: followOutput ? "auto" : "none",
       scrollbarWidth: overlayScrollbarEnabled ? "none" : undefined,
+      opacity: historyStartPaginationState.visible ? 1 : 0,
     };
-  }, [followOutput, isMobileBreakpoint, scrollEnabled]);
+  }, [followOutput, historyStartPaginationState.visible, isMobileBreakpoint, scrollEnabled]);
   const viewportStyle = useMemo(
     (): CSSProperties => ({
       position: "relative",
@@ -1307,14 +1304,21 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     const isLoadingOperation = isHistoryStartLoadingOperation(historyStartPaginationState);
     return (
       <div style={historyStartSlotStyle} data-testid="older-history-slot">
-        {isLoadingOperation ? (
+        {isLoadingOperation && (
           <div data-testid="load-older-history-spinner">
             <ThemedLoadingSpinner size="small" uniProps={foregroundMutedColorMapping} />
           </div>
-        ) : null}
+        )}
+        {!isLoadingOperation &&
+          historyStartPaginationState.status === "failed" &&
+          hasOlderHistory && (
+            <button type="button" onClick={rearmHistoryStartFromUserIntent}>
+              {t("paneFind.retry")}
+            </button>
+          )}
       </div>
     );
-  }, [historyStartPaginationState]);
+  }, [historyStartPaginationState, hasOlderHistory, rearmHistoryStartFromUserIntent, t]);
   const shouldRenderEmpty =
     !boundary.hasMountedHistory &&
     !boundary.hasVirtualizedHistory &&
@@ -1334,7 +1338,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       >
         <div ref={handleContentRef} style={contentContainerStyle}>
           {historyStartSlot}
-          <div style={streamRowsHostStyle}>
+          <div ref={rowsHostRef} style={streamRowsHostStyle}>
             <div style={virtualRowsContainerStyle} />
             {[
               ...virtualRows.map((virtualRow) => {
@@ -1362,10 +1366,17 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
               ...mountedRows,
             ]}
           </div>
-          {liveAuxiliary}
+          <div ref={auxiliaryRef} style={streamRowStyle}>
+            {liveAuxiliary}
+          </div>
           {shouldRenderEmpty ? listEmptyComponent : null}
         </div>
       </div>
+      {!historyStartPaginationState.visible ? (
+        <div data-testid="agent-initial-fill" style={initialFillStyle}>
+          <ThemedLoadingSpinner size="large" uniProps={foregroundMutedColorMapping} />
+        </div>
+      ) : null}
       {scrollEnabled && !isMobileBreakpoint ? (
         <DomOverlayScrollbar
           scrollContainerRef={scrollContainerRef}
@@ -1379,11 +1390,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 export function createWebStreamStrategy(input: CreateWebStreamStrategyInput): StreamStrategy {
   return createStreamStrategy({
     render: (renderInput) => (
-      <WebStreamViewport
-        key={renderInput.agentId}
-        {...renderInput}
-        isMobileBreakpoint={input.isMobileBreakpoint}
-      />
+      <WebStreamViewport {...renderInput} isMobileBreakpoint={input.isMobileBreakpoint} />
     ),
     orderTailReverse: false,
     orderHeadReverse: false,
@@ -1392,9 +1399,6 @@ export function createWebStreamStrategy(input: CreateWebStreamStrategyInput): St
     historyLiveBoundaryEdge: "last",
     liveHeadHistoryBoundaryEdge: "first",
     frameChildOrder: "content-then-footer",
-    flatListInverted: false,
-    overlayScrollbarInverted: false,
-    maintainVisibleContentPosition: undefined,
     bottomAnchorTransportBehavior: {
       verificationDelayFrames: 0,
       verificationRetryMode: "rescroll",
diff --git a/packages/app/src/agent-stream/strategy.ts b/packages/app/src/agent-stream/strategy.ts
index 364eba1043..aab5b0413e 100644
--- a/packages/app/src/agent-stream/strategy.ts
+++ b/packages/app/src/agent-stream/strategy.ts
@@ -14,11 +14,6 @@ type NeighborRelation = "above" | "below";
 type AssistantTurnTraversalStep = -1 | 1;
 export type StreamFrameChildOrder = "content-then-footer" | "footer-then-content";
 
-export type MaintainVisibleContentPositionConfig = Readonly<{
-  minIndexForVisible: number;
-  autoscrollToTopThreshold: number;
-}>;
-
 export type BottomAnchorTransportBehavior = Readonly<{
   verificationDelayFrames: number;
   verificationRetryMode: "rescroll" | "recheck";
@@ -51,13 +46,23 @@ export interface ScrollToMessageOccurrence {
   targetTop(): number | null;
 }
 
+/**
+ * The edge of its row a disclosure's trigger sits on. A header trigger sits on the top: the content
+ * it opens grows below it. A trigger under the content it opens, such as a long message's show
+ * more, sits on the bottom.
+ */
+export type DisclosureTriggerEdge = "top" | "bottom";
+
 export interface StreamViewportHandle {
   /** Give keyboard navigation back to the scrolling surface on web. */
   focus?: () => void;
   scrollToBottom: (reason?: BottomAnchorLocalRequest["reason"]) => void;
   prepareForViewportChange: () => void;
-  /** Stop following output so the rows on screen stay put while rows below them open or close. */
-  holdReadingPosition: () => void;
+  /**
+   * Run a disclosure's state change so the row that owns its trigger keeps the edge the trigger
+   * sits on in place. Following output stops; it resumes if the change leaves the list at its end.
+   */
+  holdRow: (rowId: string, apply: () => void, triggerEdge: DisclosureTriggerEdge) => void;
   scrollToMessage?: (messageId: string, occurrence?: ScrollToMessageOccurrence) => void;
 }
 
@@ -87,11 +92,13 @@ export interface StreamRenderInput {
   viewportRef: RefObject<StreamViewportHandle | null>;
   routeBottomAnchorRequest: BottomAnchorRouteRequest | null;
   isAuthoritativeHistoryReady: boolean;
+  isInitialHistoryLoading?: boolean;
+  revealInitialHistory?: boolean;
   onNearBottomChange: (value: boolean) => void;
   // The history row under the top of the viewport, for surfaces that mark where the reader
   // is in the transcript. Only the web viewport measures it today.
   onReadingPositionChange?: (rowId: string | null) => void;
-  onNearHistoryStart: () => boolean | Promise<boolean>;
+  onNearHistoryStart: () => Promise<boolean>;
   isLoadingOlderHistory: boolean;
   hasOlderHistory: boolean;
   olderHistoryProgressKey: string | null;
@@ -125,14 +132,11 @@ export interface StreamStrategy {
     component: ReactElement | ComponentType<unknown> | null,
     gapSize: number,
   ) => StreamEdgeSlotProps;
-  getMaintainVisibleContentPosition: () => MaintainVisibleContentPositionConfig | undefined;
   getBottomAnchorTransportBehavior: () => BottomAnchorTransportBehavior;
   getHistoryLiveBoundaryIndex: (history: StreamItem[]) => number | null;
   getLiveHeadHistoryBoundaryIndex: (liveHead: StreamItem[]) => number | null;
   getLatestItemIndex: (items: StreamItem[]) => number | null;
   getFrameChildOrder: () => StreamFrameChildOrder;
-  getFlatListInverted: () => boolean;
-  getOverlayScrollbarInverted: () => boolean;
   shouldDisableParentScrollOnInlineDetailsExpansion: () => boolean;
   shouldAnchorBottomOnContentSizeChange: () => boolean;
   shouldAnimateManualScrollToBottom: () => boolean;
@@ -148,9 +152,6 @@ interface StreamStrategyConfig {
   historyLiveBoundaryEdge: "first" | "last";
   liveHeadHistoryBoundaryEdge: "first" | "last";
   frameChildOrder: StreamFrameChildOrder;
-  flatListInverted: boolean;
-  overlayScrollbarInverted: boolean;
-  maintainVisibleContentPosition?: MaintainVisibleContentPositionConfig;
   bottomAnchorTransportBehavior: BottomAnchorTransportBehavior;
   disableParentScrollOnInlineDetailsExpansion: boolean;
   anchorBottomOnContentSizeChange: boolean;
@@ -160,8 +161,6 @@ interface StreamStrategyConfig {
   getBottomOffset: (metrics: StreamViewportMetrics) => number;
 }
 
-const NATIVE_SETTLING_VERIFICATION_DELAY_FRAMES = 4;
-
 export function createStreamStrategy(config: StreamStrategyConfig): StreamStrategy {
   return {
     render: config.render,
@@ -216,7 +215,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
         ListFooterComponentStyle: { marginTop: gapSize },
       };
     },
-    getMaintainVisibleContentPosition: () => config.maintainVisibleContentPosition,
     getBottomAnchorTransportBehavior: () => config.bottomAnchorTransportBehavior,
     getHistoryLiveBoundaryIndex: (history) => {
       if (history.length === 0) {
@@ -237,8 +235,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
       return config.historyLiveBoundaryEdge === "first" ? 0 : items.length - 1;
     },
     getFrameChildOrder: () => config.frameChildOrder,
-    getFlatListInverted: () => config.flatListInverted,
-    getOverlayScrollbarInverted: () => config.overlayScrollbarInverted,
     shouldDisableParentScrollOnInlineDetailsExpansion: () =>
       config.disableParentScrollOnInlineDetailsExpansion,
     shouldAnchorBottomOnContentSizeChange: () => config.anchorBottomOnContentSizeChange,
@@ -247,23 +243,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
   };
 }
 
-export function resolveBottomAnchorTransportBehavior(input: {
-  strategy: StreamStrategy;
-  isViewportSettling: boolean;
-}): BottomAnchorTransportBehavior {
-  const baseBehavior = input.strategy.getBottomAnchorTransportBehavior();
-  if (!input.isViewportSettling || !input.strategy.getFlatListInverted()) {
-    return baseBehavior;
-  }
-  return {
-    verificationDelayFrames: Math.max(
-      baseBehavior.verificationDelayFrames,
-      NATIVE_SETTLING_VERIFICATION_DELAY_FRAMES,
-    ),
-    verificationRetryMode: "recheck",
-  };
-}
-
 export function orderTailForStreamRenderStrategy(params: {
   strategy: StreamStrategy;
   streamItems: StreamItem[];
diff --git a/packages/app/src/agent-stream/stream-row.browser.test.tsx b/packages/app/src/agent-stream/stream-row.browser.test.tsx
new file mode 100644
index 0000000000..7608704d2d
--- /dev/null
+++ b/packages/app/src/agent-stream/stream-row.browser.test.tsx
@@ -0,0 +1,69 @@
+import { act, createRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it } from "vitest";
+import type { StreamItem } from "@/types/stream";
+import type { StreamLayoutItem } from "./layout";
+import type { StreamViewportHandle } from "./strategy";
+import { renderStreamRow } from "./stream-row";
+
+// stream-row.tsx is compiled with the React Compiler here, as Expo compiles it.
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+const turnHost: StreamItem = {
+  kind: "user_message",
+  id: "host",
+  text: "Fix the build",
+  timestamp: new Date(0),
+};
+
+const turnHostLayout: StreamLayoutItem = {
+  item: turnHost,
+  aboveItem: null,
+  // The turn's rows land below another row, so opening it leaves the host's layout unchanged.
+  belowItem: null,
+  gapBelow: 0,
+  assistantSpacing: "default",
+  completedFooter: null,
+  toolSequence: "none",
+  isFirstInUserGroup: true,
+  isLastInUserGroup: true,
+  isLastInToolSequence: false,
+  frameOrder: "content-then-footer",
+  phase: "complete",
+};
+
+it("renders a revised row again when its layout is unchanged", () => {
+  // The turn's open state lives outside the row, as `getCollapsedTurn` reads it in view.tsx.
+  let turnOpen = false;
+  const renderStreamItem = () => <span>{turnOpen ? "open" : "closed"}</span>;
+  const viewportRef = createRef<StreamViewportHandle>();
+  const layoutItemById = new Map([[turnHost.id, turnHostLayout]]);
+  const renderRow = (item: StreamItem) =>
+    act(() =>
+      root.render(renderStreamRow({ item, layoutItemById, renderStreamItem, viewportRef })),
+    );
+
+  renderRow(turnHost);
+  expect(host.textContent).toBe("closed");
+
+  turnOpen = true;
+  // useRevisedHistoryRows hands the row a fresh item when its display state changes.
+  renderRow({ ...turnHost });
+
+  expect(host.textContent).toBe("open");
+});
diff --git a/packages/app/src/agent-stream/stream-row.tsx b/packages/app/src/agent-stream/stream-row.tsx
new file mode 100644
index 0000000000..874b032f1d
--- /dev/null
+++ b/packages/app/src/agent-stream/stream-row.tsx
@@ -0,0 +1,58 @@
+import { memo, type ReactNode, type RefObject } from "react";
+import type { StreamItem } from "@/types/stream";
+import { DisclosureRow } from "./disclosure";
+import type { StreamLayoutItem } from "./layout";
+import type { StreamViewportHandle } from "./strategy";
+
+/**
+ * Renders a timeline row from the item the row was handed. The item is a revision of
+ * `layoutItem.item` with the same content: render from it, so a revision that leaves the layout
+ * unchanged still renders the row again.
+ */
+export type RenderStreamItem = (item: StreamItem, layoutItem: StreamLayoutItem) => ReactNode;
+
+// Live and retained rows use the same boundary so completion preserves the message
+// subtree, including measured diagrams and selections. LegendList renders every mounted row
+// again when `extraData` (the history renderer) changes, and history rows shift index when older
+// history loads. This boundary limits that pass: a row renders again only when its stream item
+// identity, its layout item identity, or the renderer itself changes. Item identity is the
+// revision signal the strategy already uses (`useRevisedHistoryRows` clones items whose content or
+// display state changed). The row passes the item to the renderer, so the React Compiler's cache
+// of the rendered content keys on it too.
+const StreamRow = memo(function StreamRow({
+  item,
+  layoutItem,
+  renderStreamItem,
+  viewportRef,
+}: {
+  item: StreamItem;
+  layoutItem: StreamLayoutItem;
+  renderStreamItem: RenderStreamItem;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+}) {
+  return (
+    <DisclosureRow rowId={item.id} viewportRef={viewportRef}>
+      {renderStreamItem(item, layoutItem)}
+    </DisclosureRow>
+  );
+});
+
+export function renderStreamRow(input: {
+  item: StreamItem;
+  layoutItemById: Map<string, StreamLayoutItem>;
+  renderStreamItem: RenderStreamItem;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+}): ReactNode {
+  const layoutItem = input.layoutItemById.get(input.item.id);
+  if (!layoutItem) {
+    return null;
+  }
+  return (
+    <StreamRow
+      item={input.item}
+      layoutItem={layoutItem}
+      renderStreamItem={input.renderStreamItem}
+      viewportRef={input.viewportRef}
+    />
+  );
+}
diff --git a/packages/app/src/agent-stream/top-overlay.ts b/packages/app/src/agent-stream/top-overlay.ts
index 24cd7f9592..12652580e2 100644
--- a/packages/app/src/agent-stream/top-overlay.ts
+++ b/packages/app/src/agent-stream/top-overlay.ts
@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
 import { isNative } from "@/constants/platform";
 
-/** The native inverted viewport reserves visual-top clearance; web stays in flow. */
+/** The native viewport reserves top clearance under the overlay; web stays in flow. */
 export const supportsStreamTopOverlay = isNative;
 
 const StreamTopOverlayContext = createContext(0);
diff --git a/packages/app/src/agent-stream/turn-collapse/model.test.ts b/packages/app/src/agent-stream/turn-collapse/model.test.ts
index eca6d8757c..9cb3718b10 100644
--- a/packages/app/src/agent-stream/turn-collapse/model.test.ts
+++ b/packages/app/src/agent-stream/turn-collapse/model.test.ts
@@ -12,6 +12,21 @@ function reply(id: string): StreamItem {
   return { kind: "assistant_message", id, text: id, timestamp: at };
 }
 
+function pluginReply(sourceId: string, part = "0"): StreamItem {
+  return {
+    kind: "plugin",
+    id: `math/${sourceId}/${part}`,
+    sourceId,
+    sourceKind: "assistant_message",
+    timestamp: at,
+    pluginId: "math",
+    pluginItemId: `${sourceId}/${part}`,
+    itemKind: "formula",
+    version: 1,
+    data: { text: "$$x^2$$" },
+  };
+}
+
 function thought(id: string): StreamItem {
   return { kind: "thought", id, text: id, timestamp: at, status: "ready" };
 }
@@ -41,6 +56,7 @@ function collapse(tail: StreamItem[], options: Partial<CollapseTurnsInput> = {})
     isLatestTurnOpen: false,
     expandedHostIds: new Set(),
     getGroupedCalls: () => undefined,
+    previousSummaryRowsByHostId: new Map(),
     ...options,
   });
 }
@@ -48,7 +64,91 @@ function collapse(tail: StreamItem[], options: Partial<CollapseTurnsInput> = {})
 const ids = (items: StreamItem[]) => items.map((item) => item.id);
 
 describe("collapseTurns", () => {
-  it("maps hidden rows only while their turn is closed", () => {
+  it("keeps every card of the final reply outside the folded turn", () => {
+    const items = [
+      user("prompt"),
+      reply("acknowledgment"),
+      shell("call"),
+      pluginReply("final", "left"),
+      pluginReply("final", "right"),
+    ];
+    const result = collapse(items);
+    expect(ids(result.tail)).toEqual([
+      "prompt",
+      "turn-summary:prompt",
+      "math/final/left",
+      "math/final/right",
+    ]);
+    expect(result.hostIdByFoldedMessageId.get("acknowledgment")).toBe("prompt");
+    expect(result.hostIdByFoldedMessageId.has("final")).toBe(false);
+    const expanded = collapse(items, { expandedHostIds: new Set(["prompt"]) });
+    expect(ids(expanded.tail)).toEqual([
+      "prompt",
+      "turn-summary:prompt",
+      "acknowledgment",
+      "call",
+      "math/final/left",
+      "math/final/right",
+    ]);
+    expect([...expanded.nestedItemIds]).toEqual(["acknowledgment", "call"]);
+  });
+
+  it("folds intermediate plugin replies even without tool calls", () => {
+    const result = collapse([user("prompt"), pluginReply("intermediate"), pluginReply("final")]);
+    expect(ids(result.tail)).toEqual(["prompt", "turn-summary:prompt", "math/final/0"]);
+    expect(result.hostIdByFoldedMessageId.get("intermediate")).toBe("prompt");
+  });
+
+  it.each([undefined, "thought", "tool_call"] as const)(
+    "does not treat a plugin row with source kind %s as a reply",
+    (sourceKind) => {
+      const card = { ...pluginReply("card"), sourceKind };
+      const items = [user("prompt"), shell("call"), card];
+      expect(collapse(items).tail).toEqual(items);
+      expect(collapse(items).summaryRowsByHostId.size).toBe(0);
+    },
+  );
+
+  it("keeps a plugin-rendered reply and its work unfolded while the turn is open", () => {
+    const items = [user("prompt"), shell("call"), pluginReply("final")];
+    expect(collapse(items, { isLatestTurnOpen: true }).tail).toEqual(items);
+  });
+
+  // A mounted row renders again only when its item changes, so a turn whose work and open state
+  // are unchanged keeps its summary row object across folds of the same history.
+  it("keeps a summary row until its turn's work or open state changes", () => {
+    const first = collapse([user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2")], {
+      isLatestTurnOpen: true,
+    });
+    const closed = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), reply("r2")],
+      { previousSummaryRowsByHostId: first.summaryRowsByHostId },
+    );
+    expect(closed.summaryRowsByHostId.get("u1")).toBe(first.summaryRowsByHostId.get("u1"));
+    const moreWork = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), shell("c3"), reply("r2")],
+      { previousSummaryRowsByHostId: closed.summaryRowsByHostId },
+    );
+    expect(moreWork.summaryRowsByHostId.get("u1")).toBe(closed.summaryRowsByHostId.get("u1"));
+    expect(moreWork.summaryRowsByHostId.get("u2")).not.toBe(closed.summaryRowsByHostId.get("u2"));
+    const opened = collapse(moreWork.tail, {
+      previousSummaryRowsByHostId: moreWork.summaryRowsByHostId,
+      expandedHostIds: new Set(["u1"]),
+    });
+    expect(opened.summaryRowsByHostId.get("u1")).not.toBe(moreWork.summaryRowsByHostId.get("u1"));
+  });
+  it("stands at its host's timeline position, taking a new row when that position lands", () => {
+    const live = collapse([user("u1"), shell("c1"), reply("r1")]);
+    expect(live.summaryRowsByHostId.get("u1")).not.toHaveProperty("timelineCursor");
+    const cursor = { epoch: "epoch-1", seq: 7, anchorSeq: 7 };
+    const placed = [{ ...user("u1"), timelineCursor: cursor }, shell("c1"), reply("r1")];
+    const canonical = collapse(placed, { previousSummaryRowsByHostId: live.summaryRowsByHostId });
+    expect(canonical.summaryRowsByHostId.get("u1")).not.toBe(live.summaryRowsByHostId.get("u1"));
+    expect(canonical.summaryRowsByHostId.get("u1")?.timelineCursor).toEqual(cursor);
+    const again = collapse(placed, { previousSummaryRowsByHostId: canonical.summaryRowsByHostId });
+    expect(again.summaryRowsByHostId.get("u1")).toBe(canonical.summaryRowsByHostId.get("u1"));
+  });
+  it("maps hidden rows to their turn's host only while the turn is closed", () => {
     const result = collapse([user("u1"), shell("c1"), reply("final")]);
     expect(result.hostIdByHiddenRowId.get("c1")).toBe("u1");
     const expanded = collapse([user("u1"), shell("c1"), reply("final")], {
@@ -83,15 +183,15 @@ describe("collapseTurns", () => {
       reply("done"),
     ].map((item) => Object.assign(item, { turnId: "same-run" }));
     const result = collapse(items);
-    expect(ids(result.tail)).toEqual(["u1", "finished", "compaction", "done"]);
-    expect(result.turnsByHostId.get("u1")?.summary.tools).toMatchObject({
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "finished", "compaction", "done"]);
+    expect(result.summaryRowsByHostId.get("u1")?.tools).toMatchObject({
       commandCount: 1,
       otherToolCount: 0,
       paseoActions: { "Created agent": 1 },
     });
   });
 
-  it("folds a finished turn's work into its user message and keeps the reply", () => {
+  it("folds a finished turn's work into a summary row under its user message and keeps the reply", () => {
     const result = collapse([
       user("u1"),
       thought("t1"),
@@ -101,14 +201,16 @@ describe("collapseTurns", () => {
       reply("final"),
     ]);
 
-    expect(ids(result.tail)).toEqual(["u1", "final"]);
-    expect(result.turnsByHostId.get("u1")).toEqual({
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "final"]);
+    expect(result.tail[1]).toEqual({
+      kind: "turn_summary",
+      id: "turn-summary:u1",
       hostId: "u1",
+      timestamp: at,
       expanded: false,
-      summary: {
-        tools: expect.objectContaining({ commandCount: 2 }),
-      },
+      tools: expect.objectContaining({ commandCount: 2 }),
     });
+    expect(result.summaryRowsByHostId.get("u1")).toBe(result.tail[1]);
     expect(result.hostIdByFoldedMessageId.get("early")).toBe("u1");
   });
 
@@ -117,9 +219,9 @@ describe("collapseTurns", () => {
       expandedHostIds: new Set(["u1"]),
     });
 
-    expect(ids(result.tail)).toEqual(["u1", "t1", "c1", "final"]);
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "t1", "c1", "final"]);
     expect([...result.nestedItemIds]).toEqual(["t1", "c1"]);
-    expect(result.turnsByHostId.get("u1")?.expanded).toBe(true);
+    expect(result.summaryRowsByHostId.get("u1")?.expanded).toBe(true);
   });
 
   it("leaves the latest turn alone while it is still producing output", () => {
@@ -127,8 +229,8 @@ describe("collapseTurns", () => {
 
     const result = collapse(tail, { isLatestTurnOpen: true });
 
-    expect(ids(result.tail)).toEqual(["u1", "r1", "u2", "c2", "r2"]);
-    expect([...result.turnsByHostId.keys()]).toEqual(["u1"]);
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "r1", "u2", "c2", "r2"]);
+    expect([...result.summaryRowsByHostId.keys()]).toEqual(["u1"]);
   });
 
   it("keeps rows after the reply, and turns with no work before the reply, as they are", () => {
@@ -141,8 +243,8 @@ describe("collapseTurns", () => {
       reply("r2"),
     ]);
 
-    expect(ids(result.tail)).toEqual(["u1", "r1", "after", "u2", "r2"]);
-    expect([...result.turnsByHostId.keys()]).toEqual(["u1"]);
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "r1", "after", "u2", "r2"]);
+    expect([...result.summaryRowsByHostId.keys()]).toEqual(["u1"]);
   });
 
   it("does not fold a turn that only thought before its reply", () => {
@@ -151,7 +253,7 @@ describe("collapseTurns", () => {
     const result = collapse(tail);
 
     expect(result.tail).toBe(tail);
-    expect(result.turnsByHostId.size).toBe(0);
+    expect(result.summaryRowsByHostId.size).toBe(0);
   });
 
   it("does not fold a turn without a reply or whose prompt is above the loaded history", () => {
@@ -160,7 +262,7 @@ describe("collapseTurns", () => {
     const result = collapse(tail);
 
     expect(result.tail).toBe(tail);
-    expect(result.turnsByHostId.size).toBe(0);
+    expect(result.summaryRowsByHostId.size).toBe(0);
   });
 
   it("keeps a completed response folded when a promptless canonical turn starts", () => {
@@ -169,15 +271,15 @@ describe("collapseTurns", () => {
     );
     const next = { ...shell("heartbeat"), turnId: "second" };
     const result = collapse([...first, next], { isLatestTurnOpen: true });
-    expect(ids(result.tail)).toEqual(["u1", "r1", "heartbeat"]);
-    expect(result.turnsByHostId.has("u1")).toBe(true);
+    expect(ids(result.tail)).toEqual(["u1", "turn-summary:u1", "r1", "heartbeat"]);
+    expect(result.tail[1]).toMatchObject({ kind: "turn_summary", turnId: "first" });
   });
 
   it("keeps mid-turn messages visible when work is folded", () => {
     const tail = [user("prompt"), shell("work"), user("steer"), shell("more"), reply("done")];
     for (const item of tail) item.turnId = "same-turn";
     const result = collapse(tail);
-    expect(ids(result.tail)).toEqual(["prompt", "steer", "done"]);
+    expect(ids(result.tail)).toEqual(["prompt", "turn-summary:prompt", "steer", "done"]);
     expect(result.hostIdByFoldedMessageId.has("steer")).toBe(false);
   });
 
@@ -187,7 +289,7 @@ describe("collapseTurns", () => {
       expandedHostIds: new Set(["prompt"]),
       getGroupedCalls: (id) => (id === "one" ? calls : undefined),
     });
-    expect(ids(result.tail)).toEqual(["prompt", "one", "two", "done"]);
+    expect(ids(result.tail)).toEqual(["prompt", "turn-summary:prompt", "one", "two", "done"]);
     expect([...result.nestedItemIds]).toEqual(["one", "two"]);
   });
 
@@ -197,8 +299,6 @@ describe("collapseTurns", () => {
       getGroupedCalls: (itemId) => (itemId === "c1" ? group : undefined),
     });
 
-    expect(result.turnsByHostId.get("u1")?.summary).toMatchObject({
-      tools: { commandCount: 3 },
-    });
+    expect(result.summaryRowsByHostId.get("u1")?.tools).toMatchObject({ commandCount: 3 });
   });
 });
diff --git a/packages/app/src/agent-stream/turn-collapse/model.ts b/packages/app/src/agent-stream/turn-collapse/model.ts
index a5985e600f..fe931afed5 100644
--- a/packages/app/src/agent-stream/turn-collapse/model.ts
+++ b/packages/app/src/agent-stream/turn-collapse/model.ts
@@ -3,30 +3,25 @@ import {
   getStreamItemMessageId,
   type StreamItem,
   type ThoughtItem,
+  type TimelinePosition,
   type ToolCallItem,
+  type TurnSummaryItem,
 } from "@/types/stream";
 import { summarizeToolCalls, type OverviewSummary } from "@/tool-calls/detail-level/overview/model";
 
-export interface TurnSummary {
-  tools: OverviewSummary;
-}
-
-export interface CollapsedTurn {
-  /** The input or first loaded row that carries the turn's summary line. */
-  hostId: string;
-  expanded: boolean;
-  summary: TurnSummary;
-}
-
 export interface TurnCollapse {
   tail: StreamItem[];
-  turnsByHostId: ReadonlyMap<string, CollapsedTurn>;
   /** Rows of expanded turns, which render inside the turn's indent rail. */
   nestedItemIds: ReadonlySet<string>;
-  /** The turn a folded message belongs to, for surfaces that must reveal it. */
+  /** The host of the turn a folded message belongs to, for surfaces that must reveal it. */
   hostIdByFoldedMessageId: ReadonlyMap<string, string>;
   /** Mounted rows replaced by a closed turn's host, for preserving the reading position. */
   hostIdByHiddenRowId: ReadonlyMap<string, string>;
+  /**
+   * The summary rows by host. A mounted row renders again only when its item changes, so a fold
+   * keeps the previous row object for a turn whose work and open state are unchanged.
+   */
+  summaryRowsByHostId: ReadonlyMap<string, TurnSummaryItem>;
 }
 
 export interface CollapseTurnsInput {
@@ -36,50 +31,111 @@ export interface CollapseTurnsInput {
   expandedHostIds: ReadonlySet<string>;
   /** The calls a tool-call group row stands for; undefined for a single call. */
   getGroupedCalls: (itemId: string) => readonly (ToolCallItem | ThoughtItem)[] | undefined;
+  /** The previous fold of the same history, whose unchanged summary rows are reused. */
+  previousSummaryRowsByHostId: ReadonlyMap<string, TurnSummaryItem>;
 }
 
-const EMPTY_TURNS: ReadonlyMap<string, CollapsedTurn> = new Map();
 const EMPTY_IDS: ReadonlySet<string> = new Set();
+const EMPTY_ROWS: ReadonlyMap<string, TurnSummaryItem> = new Map();
 const EMPTY_HOSTS: ReadonlyMap<string, string> = new Map();
 
 function summarizeTurn(
   items: readonly StreamItem[],
   getGroupedCalls: CollapseTurnsInput["getGroupedCalls"],
-): TurnSummary {
+): OverviewSummary {
   const calls: (ToolCallItem | ThoughtItem)[] = [];
   for (const item of items) {
     if ((item.kind === "tool_call" || item.kind === "thought") && !isTurnTrigger(item))
       calls.push(...(getGroupedCalls(item.id) ?? [item]));
   }
-  return { tools: summarizeToolCalls(calls) };
+  return summarizeToolCalls(calls);
 }
 
-function hasWork(summary: TurnSummary): boolean {
-  const { paseoActions, thoughtCount: _thoughtCount, ...counts } = summary.tools;
+function hasWork(tools: OverviewSummary): boolean {
+  const { paseoActions, thoughtCount: _thoughtCount, ...counts } = tools;
   return Object.keys(paseoActions).length > 0 || Object.values(counts).some((count) => count > 0);
 }
 
+function hasSameWork(a: OverviewSummary, b: OverviewSummary): boolean {
+  const { paseoActions: actionsA, ...countsA } = a;
+  const { paseoActions: actionsB, ...countsB } = b;
+  return hasSameCounts(countsA, countsB) && hasSameCounts(actionsA, actionsB);
+}
+
+function hasSamePosition(a: TimelinePosition | undefined, b: TimelinePosition | undefined) {
+  return a === b || (a !== undefined && b !== undefined && a.epoch === b.epoch && a.seq === b.seq);
+}
+
+function hasSameCounts(a: Record<string, number>, b: Record<string, number>): boolean {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
+
+function summaryRow(
+  host: StreamItem,
+  expanded: boolean,
+  tools: OverviewSummary,
+  previous: TurnSummaryItem | undefined,
+): TurnSummaryItem {
+  if (
+    previous &&
+    previous.expanded === expanded &&
+    hasSameWork(previous.tools, tools) &&
+    hasSamePosition(previous.timelineCursor, host.timelineCursor)
+  ) {
+    return previous;
+  }
+  return {
+    kind: "turn_summary",
+    id: `turn-summary:${host.id}`,
+    // The row stands at its host's place in the timeline, so the reading position over it
+    // still resolves to the turn's prompt.
+    ...(host.timelineCursor !== undefined ? { timelineCursor: host.timelineCursor } : {}),
+    ...(host.turnId !== undefined ? { turnId: host.turnId } : {}),
+    timestamp: host.timestamp,
+    hostId: host.id,
+    expanded,
+    tools,
+  };
+}
+
 function staysVisibleWhenCollapsed(item: StreamItem): boolean {
   return isTurnTrigger(item) || item.kind === "compaction";
 }
 
-function findLastAssistantIndex(tail: StreamItem[], start: number, end: number): number {
+function isAssistantReply(item: StreamItem): boolean {
+  return (
+    item.kind === "assistant_message" ||
+    (item.kind === "plugin" && item.sourceKind === "assistant_message")
+  );
+}
+
+function findLastReplyIndex(tail: StreamItem[], start: number, end: number): number {
   for (let index = end - 1; index >= start; index -= 1) {
-    if (tail[index]?.kind === "assistant_message") return index;
+    const item = tail[index]!;
+    if (!isAssistantReply(item)) continue;
+    const messageId = getStreamItemMessageId(item);
+    // A transformer can split one reply into several cards; keep the whole reply visible.
+    while (index > start) {
+      const previous = tail[index - 1]!;
+      if (!isAssistantReply(previous) || getStreamItemMessageId(previous) !== messageId) break;
+      index -= 1;
+    }
+    return index;
   }
   return -1;
 }
 
 /**
- * Folds each answered turn into its user message: everything the agent did before its last
- * message collapses into one summary line, and that message stays in the chat. A turn folds
- * only once it is complete, its user message is loaded, and it sent messages or called tools
- * before its reply. Reasoning is revealed only when the turn opens.
+ * Folds each answered turn behind a summary row under its user message: everything the agent
+ * did before its last message collapses into that row, and the last message stays in the chat.
+ * A turn folds only once it is complete, its user message is loaded, and it sent messages or
+ * called tools before its reply. Reasoning is revealed only when the turn opens.
  */
 export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   const { tail } = input;
   const output: StreamItem[] = [];
-  const turnsByHostId = new Map<string, CollapsedTurn>();
+  const summaryRowsByHostId = new Map<string, TurnSummaryItem>();
   const nestedItemIds = new Set<string>();
   const hostIdByFoldedMessageId = new Map<string, string>();
   const hostIdByHiddenRowId = new Map<string, string>();
@@ -88,7 +144,7 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   const flushRun = (runEnd: number) => {
     const host = tail[runStart - 1];
     const isClosed = runEnd < tail.length || !input.isLatestTurnOpen;
-    const replyIndex = findLastAssistantIndex(tail, runStart, runEnd);
+    const replyIndex = findLastReplyIndex(tail, runStart, runEnd);
     if (
       !host ||
       (host.kind !== "user_message" && host.kind !== "tool_call") ||
@@ -99,13 +155,19 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
       return;
     }
     const folded = tail.slice(runStart, replyIndex);
-    const summary = summarizeTurn(folded, input.getGroupedCalls);
-    if (!hasWork(summary) && !folded.some((item) => item.kind === "assistant_message")) {
+    const tools = summarizeTurn(folded, input.getGroupedCalls);
+    if (!hasWork(tools) && !folded.some(isAssistantReply)) {
       output.push(...tail.slice(runStart, runEnd));
       return;
     }
     const expanded = input.expandedHostIds.has(host.id);
-    turnsByHostId.set(host.id, { hostId: host.id, expanded, summary });
+    const summary = summaryRow(
+      host,
+      expanded,
+      tools,
+      input.previousSummaryRowsByHostId.get(host.id),
+    );
+    summaryRowsByHostId.set(host.id, summary);
     const revealed = expanded
       ? folded.flatMap<StreamItem>((item) =>
           item.kind === "tool_call" || item.kind === "thought"
@@ -120,6 +182,7 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
       else hostIdByHiddenRowId.set(item.id, host.id);
     }
     output.push(
+      summary,
       ...(expanded ? revealed : folded.filter((item) => staysVisibleWhenCollapsed(item))),
     );
     output.push(...tail.slice(replyIndex, runEnd));
@@ -137,23 +200,20 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   }
   flushRun(tail.length);
 
-  if (turnsByHostId.size === 0) {
+  if (summaryRowsByHostId.size === 0) {
     return {
       tail,
-      turnsByHostId: EMPTY_TURNS,
       nestedItemIds: EMPTY_IDS,
       hostIdByFoldedMessageId: EMPTY_HOSTS,
       hostIdByHiddenRowId: EMPTY_HOSTS,
+      summaryRowsByHostId: EMPTY_ROWS,
     };
   }
   return {
-    tail:
-      output.length === tail.length && output.every((item, index) => item === tail[index])
-        ? tail
-        : output,
-    turnsByHostId,
+    tail: output,
     nestedItemIds,
     hostIdByFoldedMessageId,
     hostIdByHiddenRowId,
+    summaryRowsByHostId,
   };
 }
diff --git a/packages/app/src/agent-stream/turn-collapse/summary-line.tsx b/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
index 191ac706d5..289a6f748f 100644
--- a/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
+++ b/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
@@ -1,26 +1,28 @@
 import { memo, useCallback } from "react";
 import { useTranslation } from "react-i18next";
 import { Summary } from "lucide-react-native";
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { ExpandableBadge } from "@/components/message";
 import { useOverviewSummaryLabel } from "@/tool-calls/detail-level/overview/label";
-import type { CollapsedTurn } from "./model";
+import type { TurnSummaryItem } from "@/types/stream";
 
 /**
  * The row a collapsed turn leaves under its user message, styled like a tool-call group.
  * Pressing it opens the turn's rows beneath it.
  */
 export const TurnSummaryLine = memo(function TurnSummaryLine({
-  turn,
+  item,
   onExpandedChange,
 }: {
-  turn: CollapsedTurn;
+  item: TurnSummaryItem;
   onExpandedChange: (hostId: string, expanded: boolean) => void;
 }) {
   const { t } = useTranslation();
-  const label = useOverviewSummaryLabel(turn.summary.tools) || t("turnSummary.details");
+  const label = useOverviewSummaryLabel(item.tools) || t("turnSummary.details");
+  const hold = useDisclosureHold();
   const toggle = useCallback(
-    () => onExpandedChange(turn.hostId, !turn.expanded),
-    [onExpandedChange, turn.expanded, turn.hostId],
+    () => hold(() => onExpandedChange(item.hostId, !item.expanded)),
+    [hold, onExpandedChange, item.expanded, item.hostId],
   );
 
   return (
@@ -28,7 +30,7 @@ export const TurnSummaryLine = memo(function TurnSummaryLine({
       testID="turn-summary"
       label={label}
       icon={Summary}
-      isExpanded={turn.expanded}
+      isExpanded={item.expanded}
       onToggle={toggle}
       borderlessWhenExpanded
     />
diff --git a/packages/app/src/agent-stream/turn-footer.browser.test.tsx b/packages/app/src/agent-stream/turn-footer.browser.test.tsx
new file mode 100644
index 0000000000..dec9b7fe15
--- /dev/null
+++ b/packages/app/src/agent-stream/turn-footer.browser.test.tsx
@@ -0,0 +1,94 @@
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { i18n } from "@/i18n/i18next";
+import type { TurnTiming } from "@/timeline/turn-time";
+import type { StreamItem } from "@/types/stream";
+import { createNativeStreamStrategy } from "./strategy-native";
+import { CompletedTurnFooterRow } from "./turn-footer";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+// A Sunday, so a turn that ended on Friday shows a weekday timestamp.
+const NOW = new Date(2026, 10, 8, 5, 0);
+const FRIDAY_NIGHT = new Date(2026, 10, 6, 23, 11);
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  vi.stubGlobal("React", React);
+  vi.useFakeTimers({ toFake: ["Date"], now: NOW });
+  host = document.createElement("div");
+  host.style.width = "880px";
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(async () => {
+  act(() => root.unmount());
+  host.remove();
+  vi.useRealTimers();
+  await i18n.changeLanguage("en");
+  vi.unstubAllGlobals();
+});
+
+const reply: StreamItem = {
+  kind: "assistant_message",
+  id: "reply",
+  text: "Done.",
+  timestamp: FRIDAY_NIGHT,
+};
+
+function renderCompletedFooter(timing: TurnTiming): void {
+  act(() =>
+    root.render(
+      <CompletedTurnFooterRow
+        strategy={createNativeStreamStrategy()}
+        items={[reply]}
+        timing={timing}
+        startIndex={0}
+        supportsTimelineCursor={false}
+      />,
+    ),
+  );
+}
+
+/** How many painted lines each footer label takes. */
+function paintedLinesByLabel(element: HTMLElement): Record<string, number> {
+  const lines: Record<string, number> = {};
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  while (walker.nextNode()) {
+    const text = walker.currentNode.textContent ?? "";
+    if (!text.trim()) continue;
+    const range = document.createRange();
+    range.selectNodeContents(walker.currentNode);
+    lines[text] = new Set(Array.from(range.getClientRects(), (rect) => Math.round(rect.top))).size;
+  }
+  return lines;
+}
+
+// The footer shows the duration and swaps to the end timestamp on hover or tap. Neither label
+// may be sized by the other: a timestamp with more characters can still paint narrower.
+it.each([
+  {
+    language: "en",
+    timing: { completedAt: FRIDAY_NIGHT, durationMs: 26_000 },
+    duration: "Worked for 26s",
+  },
+  // CJK glyphs make the shorter string paint wider in every font.
+  {
+    language: "ja",
+    timing: { completedAt: FRIDAY_NIGHT, durationMs: 59 * 60_000 + 58_000 },
+    duration: "作業時間 59m 58s",
+  },
+])("keeps both timing labels on one line when the chat has room ($language)", async (input) => {
+  await i18n.changeLanguage(input.language);
+
+  renderCompletedFooter(input.timing);
+
+  expect(paintedLinesByLabel(host)).toEqual({
+    [input.duration]: 1,
+    "Friday 11:11 PM": 1,
+  });
+});
diff --git a/packages/app/src/agent-stream/turn-footer.tsx b/packages/app/src/agent-stream/turn-footer.tsx
index 5d04f9eca9..6699fb800b 100644
--- a/packages/app/src/agent-stream/turn-footer.tsx
+++ b/packages/app/src/agent-stream/turn-footer.tsx
@@ -23,6 +23,10 @@ import { useRetainedPanelActive } from "@/components/retained-panel";
 const ThemedSyncedLoader = withUnistyles(SyncedLoader);
 const workingIndicatorColorMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 export const TURN_FOOTER_BOTTOM_SPACING = SPACING[8];
+// Every footer variant (running, completed with Copy, completed with only its duration) gets
+// this content height, so a turn ending swaps the footer's controls without moving the rows
+// above it.
+const TURN_FOOTER_CONTENT_HEIGHT = 24;
 
 export type TurnContentStrategy = StreamStrategy;
 export type AssistantTurnForkHandler = (input: {
@@ -208,7 +212,11 @@ function CompletedTurnFooter({
 
 function TurnFooterRow({ children }: { children: ReactNode }) {
   const rowStyle = useMemo(() => [stylesheet.streamItemWrapper, stylesheet.turnFooterRow], []);
-  return <View style={rowStyle}>{children}</View>;
+  return (
+    <View style={rowStyle} testID="turn-footer">
+      {children}
+    </View>
+  );
 }
 
 const stylesheet = StyleSheet.create((theme) => ({
@@ -218,18 +226,22 @@ const stylesheet = StyleSheet.create((theme) => ({
     alignSelf: "center",
     paddingHorizontal: theme.spacing[2],
   },
+  // The message above drops its bottom padding for the footer (compactBottom), so this margin
+  // alone sets the gap. 20 puts the footer as far below the text as the text sits below a
+  // tool row: 12 message padding + 4 stream gap + 5 badge padding/border, less the footer's
+  // 1px taller row.
   turnFooterRow: {
-    marginTop: theme.spacing[2] + 5,
+    marginTop: theme.spacing[4] + theme.spacing[1],
   },
   turnFooterSlot: {
     flexDirection: "row",
     alignItems: "center",
-    alignSelf: "flex-start",
-    minHeight: 24,
+    alignSelf: "stretch",
+    minHeight: TURN_FOOTER_CONTENT_HEIGHT + TURN_FOOTER_BOTTOM_SPACING,
     paddingBottom: TURN_FOOTER_BOTTOM_SPACING,
   },
   turnFooterContent: {
-    height: 24,
+    height: TURN_FOOTER_CONTENT_HEIGHT,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "flex-start",
diff --git a/packages/app/src/agent-stream/use-history-start-pagination.ts b/packages/app/src/agent-stream/use-history-start-pagination.ts
new file mode 100644
index 0000000000..1fb6168857
--- /dev/null
+++ b/packages/app/src/agent-stream/use-history-start-pagination.ts
@@ -0,0 +1,33 @@
+import { useRef, useState } from "react";
+import { useStableEvent } from "@/hooks/use-stable-event";
+import {
+  createHistoryStartPagination,
+  type HistoryStartPaginationInput,
+  type HistoryStartPaginationState,
+} from "./history-start-pagination";
+
+export function useHistoryStartPagination(input: {
+  initiallyVisible: boolean;
+  read: () => HistoryStartPaginationInput | null;
+  load: () => Promise<boolean>;
+  scheduleSettle: () => void;
+}) {
+  const read = useStableEvent(input.read);
+  const load = useStableEvent(input.load);
+  const scheduleSettle = useStableEvent(input.scheduleSettle);
+  const [state, setState] = useState<HistoryStartPaginationState>(() => ({
+    status: "dormant",
+    visible: input.initiallyVisible,
+  }));
+  const controller = useRef<ReturnType<typeof createHistoryStartPagination> | null>(null);
+  if (!controller.current) {
+    controller.current = createHistoryStartPagination({
+      initiallyVisible: input.initiallyVisible,
+      read,
+      load,
+      scheduleSettle,
+      changed: setState,
+    });
+  }
+  return { state, controller: controller.current };
+}
diff --git a/packages/app/src/agent-stream/use-stream-history-window.test.tsx b/packages/app/src/agent-stream/use-stream-history-window.test.tsx
index 2d8f0b4326..1db49ecdfd 100644
--- a/packages/app/src/agent-stream/use-stream-history-window.test.tsx
+++ b/packages/app/src/agent-stream/use-stream-history-window.test.tsx
@@ -21,7 +21,7 @@ describe("useStreamHistoryWindow", () => {
     ]).flat();
 
     const { result } = renderHook(() =>
-      useStreamHistoryWindow({ agentId: "agent-1", items, loadRemoteOlder: vi.fn() }),
+      useStreamHistoryWindow({ items, loadRemoteOlder: vi.fn() }),
     );
 
     expect(result.current.start).toBe(2);
@@ -35,7 +35,6 @@ describe("useStreamHistoryWindow", () => {
     const loadRemoteOlder = vi.fn(async () => true);
     const { result } = renderHook(() =>
       useStreamHistoryWindow({
-        agentId: "agent-1",
         items: [
           message("u1", "user_message"),
           message("a1", "assistant_message"),
@@ -67,8 +66,7 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -91,8 +89,7 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -108,8 +105,7 @@ describe("useStreamHistoryWindow", () => {
       configurable: true,
     });
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       {
         initialProps: {
           history: [
@@ -142,7 +138,6 @@ describe("useStreamHistoryWindow", () => {
     });
     const { result } = renderHook(() =>
       useStreamHistoryWindow({
-        agentId: "agent-1",
         items: [
           message("u1", "user_message"),
           message("a1", "assistant_message"),
diff --git a/packages/app/src/agent-stream/use-stream-history-window.ts b/packages/app/src/agent-stream/use-stream-history-window.ts
index 340ecb4da4..cc6d5425d6 100644
--- a/packages/app/src/agent-stream/use-stream-history-window.ts
+++ b/packages/app/src/agent-stream/use-stream-history-window.ts
@@ -28,22 +28,17 @@ function findEarlierHistoryWindowStart(input: {
 }
 
 interface HistoryWindowBoundary {
-  agentId: string;
   boundaryItemId: string | null;
   initialized: boolean;
 }
 
 function reconcileHistoryWindow(input: {
   current: HistoryWindowBoundary;
-  agentId: string;
   boundaryIndex: number;
   initialBoundaryItemId: string | null;
   hasItems: boolean;
 }): HistoryWindowBoundary {
-  const { current, agentId, boundaryIndex, initialBoundaryItemId, hasItems } = input;
-  if (current.agentId !== agentId) {
-    return { agentId, boundaryItemId: initialBoundaryItemId, initialized: hasItems };
-  }
+  const { current, boundaryIndex, initialBoundaryItemId, hasItems } = input;
   if (!current.initialized && hasItems) {
     return { ...current, boundaryItemId: initialBoundaryItemId, initialized: true };
   }
@@ -54,28 +49,26 @@ function reconcileHistoryWindow(input: {
 }
 
 export function useStreamHistoryWindow(input: {
-  agentId: string;
   items: StreamItem[];
   loadRemoteOlder: () => boolean | Promise<boolean>;
 }) {
-  const { agentId, items, loadRemoteOlder } = input;
+  const { items, loadRemoteOlder } = input;
   const initialStart = useMemo(
     () => findMountedWindowStart({ items, minMountedCount: getMountedRecentStreamItems() }),
     [items],
   );
   const initialBoundaryItemId = initialStart === 0 ? null : (items[initialStart]?.id ?? null);
   const [window, setWindow] = useState(() => ({
-    agentId,
     boundaryItemId: initialBoundaryItemId,
     initialized: items.length > 0,
   }));
-  const boundaryItemId = window.agentId === agentId ? window.boundaryItemId : null;
+  const boundaryItemId = window.boundaryItemId;
   const boundaryIndex = useMemo(
     () => (boundaryItemId === null ? -1 : items.findIndex((item) => item.id === boundaryItemId)),
     [boundaryItemId, items],
   );
   let start = initialStart;
-  if (window.agentId === agentId && window.initialized) {
+  if (window.initialized) {
     if (window.boundaryItemId === null) {
       start = 0;
     } else if (boundaryIndex >= 0) {
@@ -87,13 +80,12 @@ export function useStreamHistoryWindow(input: {
     setWindow((current) =>
       reconcileHistoryWindow({
         current,
-        agentId,
         boundaryIndex,
         initialBoundaryItemId,
         hasItems: items.length > 0,
       }),
     );
-  }, [agentId, boundaryIndex, initialBoundaryItemId, items.length]);
+  }, [boundaryIndex, initialBoundaryItemId, items.length]);
 
   const revealLoadedHistory = useCallback(
     (itemId?: string): boolean => {
@@ -106,13 +98,12 @@ export function useStreamHistoryWindow(input: {
         return false;
       }
       setWindow({
-        agentId,
         boundaryItemId: items[nextStart]?.id ?? null,
         initialized: true,
       });
       return true;
     },
-    [agentId, items, start],
+    [items, start],
   );
   const loadOlder = useCallback(async (): Promise<boolean> => {
     return revealLoadedHistory() || (await loadRemoteOlder());
diff --git a/packages/app/src/agent-stream/view.tsx b/packages/app/src/agent-stream/view.tsx
index cb9999745b..761e73bac6 100644
--- a/packages/app/src/agent-stream/view.tsx
+++ b/packages/app/src/agent-stream/view.tsx
@@ -74,6 +74,8 @@ import { TurnSummaryLine } from "./turn-collapse/summary-line";
 import { type AgentStreamRenderModel, buildAgentStreamRenderModel } from "./model";
 import { resolveStreamRenderStrategy } from "./strategy-resolver";
 import { type StreamSegmentRenderers, type StreamViewportHandle } from "./strategy";
+import { renderStreamRow, type RenderStreamItem } from "./stream-row";
+import { type NearBottom, useIsNearBottom, useNearBottom } from "./near-bottom";
 import { ChatOutlineRail } from "@/agent-stream/chat-outline/rail";
 import { useChatOutline } from "@/agent-stream/chat-outline/use-chat-outline";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
@@ -230,41 +232,6 @@ function renderListEmptyComponent(input: {
   );
 }
 
-// Live and retained rows use the same boundary so completion preserves the message
-// subtree, including measured diagrams and selections. FlatList recreates history
-// cells with fresh refs and shifted indexes on data changes. This boundary is
-// what stops that churn: a row renders again only when its stream item identity, its layout item
-// identity, or the renderer itself changes. Item identity is the revision signal the strategy
-// already uses (`useRevisedHistoryRows` clones items whose content or display state changed).
-const StreamRow = memo(function StreamRow({
-  layoutItem,
-  renderStreamItem,
-}: {
-  item: StreamItem;
-  layoutItem: StreamLayoutItem;
-  renderStreamItem: (layoutItem: StreamLayoutItem) => ReactNode;
-}) {
-  return <>{renderStreamItem(layoutItem)}</>;
-});
-
-function renderStreamRow(input: {
-  item: StreamItem;
-  layoutItemById: Map<string, StreamLayoutItem>;
-  renderStreamItem: (layoutItem: StreamLayoutItem) => ReactNode;
-}): ReactNode {
-  const layoutItem = input.layoutItemById.get(input.item.id);
-  if (!layoutItem) {
-    return null;
-  }
-  return (
-    <StreamRow
-      item={input.item}
-      layoutItem={layoutItem}
-      renderStreamItem={input.renderStreamItem}
-    />
-  );
-}
-
 export interface AgentStreamViewHandle {
   scrollToBottom(reason?: BottomAnchorLocalRequest["reason"]): void;
   prepareForViewportChange(): void;
@@ -281,6 +248,8 @@ export interface AgentStreamViewProps {
   turnPresentation: TurnPresentation;
   routeBottomAnchorRequest?: BottomAnchorRouteRequest | null;
   isAuthoritativeHistoryReady?: boolean;
+  isInitialHistoryLoading?: boolean;
+  revealInitialHistory?: boolean;
   /** Tail space required by a transparent overlay rendered at the bottom edge. */
   bottomOverlayTailClearance?: number;
   /** Bottom offset required for controls floating above that overlay. */
@@ -324,6 +293,47 @@ function resolveBottomOverlayControlOffset(clearance: number | undefined): numbe
   return Math.max(16, clearance ?? 0);
 }
 
+// Keep entry/exit animations off on Android due to RN dispatchDraw crashes
+// tracked in react-native-reanimated#8422.
+const shouldDisableEntryExitAnimations = Platform.OS === "android";
+const scrollIndicatorFadeIn = shouldDisableEntryExitAnimations ? undefined : FadeIn.duration(200);
+const scrollIndicatorFadeOut = shouldDisableEntryExitAnimations ? undefined : FadeOut.duration(200);
+
+function ScrollToBottomButton({
+  nearBottom,
+  isTimelineDetached,
+  bottomOffset,
+  onPress,
+}: {
+  nearBottom: NearBottom;
+  isTimelineDetached: boolean;
+  bottomOffset: number;
+  onPress: () => void;
+}) {
+  const { t } = useTranslation();
+  const isNearBottom = useIsNearBottom(nearBottom);
+  const containerStyle = useMemo(
+    () => [stylesheet.scrollToBottomContainer, { bottom: bottomOffset }],
+    [bottomOffset],
+  );
+  if (isNearBottom && !isTimelineDetached) return null;
+  return (
+    <View style={containerStyle} pointerEvents="box-none">
+      <Animated.View entering={scrollIndicatorFadeIn} exiting={scrollIndicatorFadeOut}>
+        <Pressable
+          style={stylesheet.scrollToBottomButton}
+          onPress={onPress}
+          accessibilityRole="button"
+          accessibilityLabel={t("agentStream.scrollToBottom")}
+          testID="scroll-to-bottom-button"
+        >
+          <ChevronDown size={24} color={stylesheet.scrollToBottomIcon.color} />
+        </Pressable>
+      </Animated.View>
+    </View>
+  );
+}
+
 const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamViewProps>(
   function AgentStreamView(
     {
@@ -337,6 +347,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       turnPresentation,
       routeBottomAnchorRequest = null,
       isAuthoritativeHistoryReady = true,
+      isInitialHistoryLoading,
+      revealInitialHistory,
       bottomOverlayTailClearance = 0,
       bottomOverlayControlClearance,
       toast,
@@ -365,7 +377,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         }),
       [isMobile],
     );
-    const [isNearBottom, setIsNearBottom] = useState(true);
+    const nearBottom = useNearBottom(agentId);
     const [expandedInlineToolCallIds, setExpandedInlineToolCallIds] = useState<Set<string>>(
       new Set(),
     );
@@ -422,21 +434,6 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           loadOlder: historyPagination.onLoadOlder,
         }
       : agentHistoryPagination;
-    // Keep entry/exit animations off on Android due to RN dispatchDraw crashes
-    // tracked in react-native-reanimated#8422.
-    const shouldDisableEntryExitAnimations = Platform.OS === "android";
-    const scrollIndicatorFadeIn = shouldDisableEntryExitAnimations
-      ? undefined
-      : FadeIn.duration(200);
-    const scrollIndicatorFadeOut = shouldDisableEntryExitAnimations
-      ? undefined
-      : FadeOut.duration(200);
-
-    useEffect(() => {
-      setIsNearBottom(true);
-      setExpandedInlineToolCallIds(new Set());
-      setExpandedTurnHostIds(new Set());
-    }, [agentId]);
 
     const isActive = useRetainedPanelActive();
     const openInlineFile = useStableEvent(
@@ -468,6 +465,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       () =>
         createInlinePathOpener({
           workspaceRoot,
+          resolveRelativeFiles: true,
           client,
           openFile: openInlineFile,
           openDirectory: openInlineDirectory,
@@ -478,7 +476,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     useEffect(() => {
       if (!isActive) inlinePathOpener.cancel();
       return () => inlinePathOpener.cancel();
-    }, [inlinePathOpener, isActive, agentId]);
+    }, [inlinePathOpener, isActive]);
     const handleInlinePathPress = useStableEvent(
       (target: InlinePathTarget, disposition: OpenFileDisposition) => {
         if (isActive) void inlinePathOpener.open(target, disposition);
@@ -553,7 +551,6 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       revealLoadedHistory,
       loadOlder,
     } = useStreamHistoryWindow({
-      agentId,
       items: presentation.tail,
       loadRemoteOlder,
     });
@@ -674,9 +671,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       [streamRenderStrategy],
     );
 
+    // The summary line holds its row around this; chat find opens a turn without a hold.
     const setTurnExpanded = useCallback((hostId: string, expanded: boolean) => {
-      // A turn opens below its summary line; keep that line under the reader's pointer.
-      viewportRef.current?.holdReadingPosition();
       setExpandedTurnHostIds((previous) => {
         if (previous.has(hostId) === expanded) return previous;
         const next = new Set(previous);
@@ -697,26 +693,23 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       }
       return revealLoadedHistory(messageId);
     });
-    // Read through stable events so a collapse rerun does not change the renderer identity;
-    // rows whose turn state changed are revised through `historyRowRevision`.
-    const getCollapsedTurn = useStableEvent((hostId: string) =>
-      presentation.turns.turnsByHostId.get(hostId),
-    );
+    // Read through a stable event so a collapse rerun does not change the renderer identity;
+    // nested rows are revised through `historyRowRevision`.
     const getTurnIndent = useStableEvent((layoutItem: StreamLayoutItem): TurnIndent => {
       const { nestedItemIds } = presentation.turns;
-      if (nestedItemIds.has(layoutItem.item.id)) {
+      const { item } = layoutItem;
+      if (nestedItemIds.has(item.id)) {
         const below = layoutItem.belowItem;
         return below && nestedItemIds.has(below.id) ? "nested" : "lastNested";
       }
-      return getCollapsedTurn(layoutItem.item.id)?.expanded ? "openedHost" : "none";
+      return item.kind === "turn_summary" && item.expanded ? "openedHost" : "none";
     });
 
     const setToolCallGroupExpanded = toolCallExpansion.setGroupExpanded;
 
     const renderUserMessageItem = useCallback(
       (layoutItem: StreamLayoutItem, item: Extract<StreamItem, { kind: "user_message" }>) => {
-        const collapsedTurn = getCollapsedTurn(item.id);
-        const message = (
+        return (
           <UserMessage
             serverId={resolvedServerId}
             agentId={agentId}
@@ -736,25 +729,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             }
           />
         );
-        if (!collapsedTurn) {
-          return message;
-        }
-        return (
-          <>
-            {message}
-            <TurnSummaryLine turn={collapsedTurn} onExpandedChange={setTurnExpanded} />
-          </>
-        );
       },
-      [
-        context.capabilities,
-        agentId,
-        client,
-        getCollapsedTurn,
-        pendingClientMessageIds,
-        resolvedServerId,
-        setTurnExpanded,
-      ],
+      [context.capabilities, agentId, client, pendingClientMessageIds, resolvedServerId],
     );
 
     const renderAssistantMessageItem = useCallback(
@@ -927,8 +903,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     );
 
     const renderStreamItemContent = useCallback(
-      (layoutItem: StreamLayoutItem) => {
-        const item = layoutItem.item;
+      (item: StreamItem, layoutItem: StreamLayoutItem) => {
         switch (item.kind) {
           case "user_message":
             return renderUserMessageItem(layoutItem, item);
@@ -940,17 +915,10 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             return renderToolCallItem(layoutItem, item);
 
           case "tool_call":
-            return (
-              <>
-                {renderToolCallItem(layoutItem, item)}
-                {getCollapsedTurn(item.id) ? (
-                  <TurnSummaryLine
-                    turn={getCollapsedTurn(item.id)!}
-                    onExpandedChange={setTurnExpanded}
-                  />
-                ) : null}
-              </>
-            );
+            return renderToolCallItem(layoutItem, item);
+
+          case "turn_summary":
+            return <TurnSummaryLine item={item} onExpandedChange={setTurnExpanded} />;
 
           case "notification":
             return <Notification level={item.level} message={item.message} />;
@@ -981,7 +949,6 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         renderUserMessageItem,
         renderAssistantMessageItem,
         renderToolCallItem,
-        getCollapsedTurn,
         setTurnExpanded,
         resolvedServerId,
       ],
@@ -989,9 +956,9 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
 
     const bottomTurnFooterHost = streamLayout.auxiliaryTurnFooter;
 
-    const renderStreamItem = useCallback(
-      (layoutItem: StreamLayoutItem) => {
-        const content = renderStreamItemContent(layoutItem);
+    const renderStreamItem = useCallback<RenderStreamItem>(
+      (item, layoutItem) => {
+        const content = renderStreamItemContent(item, layoutItem);
         return renderStreamItemWithTurnFooter({
           content,
           layoutItem,
@@ -1060,13 +1027,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     }, [baseRenderModel, pendingPermissionsNode, turnFooterNode]);
 
     const emptyStateStyle = useMemo(() => [stylesheet.emptyState, stylesheet.contentWrapper], []);
-    const scrollToBottomContainerStyle = useMemo(
-      () => [
-        stylesheet.scrollToBottomContainer,
-        { bottom: resolveBottomOverlayControlOffset(bottomOverlayControlClearance) },
-      ],
-      [bottomOverlayControlClearance],
-    );
+    const scrollToBottomOffset = resolveBottomOverlayControlOffset(bottomOverlayControlClearance);
     const listEmptyComponent = useMemo(
       () =>
         renderListEmptyComponent({
@@ -1109,6 +1070,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutHistoryItemById,
           renderStreamItem,
+          viewportRef,
         }),
       [layoutHistoryItemById, renderStreamItem],
     );
@@ -1130,6 +1092,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutLiveHeadItemById,
           renderStreamItem,
+          viewportRef,
         }),
     );
     const renderLiveAuxiliary = useCallback<StreamSegmentRenderers["renderLiveAuxiliary"]>(() => {
@@ -1167,13 +1130,14 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     const { nestedItemIds } = presentation.turns;
     const historyRowRevision = useMemo(
       () => ({
-        contentById: presentation.historyGroupUpdatesByHostId,
+        contentById: {
+          has: (id: string) => presentation.historyGroupUpdatesByHostId.has(id),
+        },
         displayStateById: {
           // An opened lone call also marks its future group open; that row stays unrevised
           // until a group actually forms there.
           has: (id: string) =>
             (expandedToolCallGroups.has(id) && getToolCallGroup(id) !== undefined) ||
-            expandedTurnHostIds.has(id) ||
             nestedItemIds.has(id),
         },
         globalDisplayState: isMobile,
@@ -1181,7 +1145,6 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       [
         expandedToolCallGroups,
         getToolCallGroup,
-        expandedTurnHostIds,
         isMobile,
         nestedItemIds,
         presentation.historyGroupUpdatesByHostId,
@@ -1218,7 +1181,9 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
                   viewportRef,
                   routeBottomAnchorRequest,
                   isAuthoritativeHistoryReady,
-                  onNearBottomChange: setIsNearBottom,
+                  isInitialHistoryLoading,
+                  revealInitialHistory,
+                  onNearBottomChange: nearBottom.set,
                   onReadingPositionChange: handleReadingPositionChange,
                   onNearHistoryStart: loadOlder,
                   isLoadingOlderHistory: isLoadingOlder,
@@ -1237,21 +1202,12 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
               activePrompt={chatOutline.activePrompt}
               onJumpToPrompt={chatOutline.jumpToPrompt}
             />
-            {(!isNearBottom || isTimelineDetached) && (
-              <View style={scrollToBottomContainerStyle} pointerEvents="box-none">
-                <Animated.View entering={scrollIndicatorFadeIn} exiting={scrollIndicatorFadeOut}>
-                  <Pressable
-                    style={stylesheet.scrollToBottomButton}
-                    onPress={scrollToBottom}
-                    accessibilityRole="button"
-                    accessibilityLabel={t("agentStream.scrollToBottom")}
-                    testID="scroll-to-bottom-button"
-                  >
-                    <ChevronDown size={24} color={stylesheet.scrollToBottomIcon.color} />
-                  </Pressable>
-                </Animated.View>
-              </View>
-            )}
+            <ScrollToBottomButton
+              nearBottom={nearBottom}
+              isTimelineDetached={isTimelineDetached}
+              bottomOffset={scrollToBottomOffset}
+              onPress={scrollToBottom}
+            />
           </AssistantSelectionCopySurface>
         </ToolCallSheetProvider>
       </ChatFind>
@@ -1303,7 +1259,8 @@ function collectAgentSetupDiffs(left: AgentScreenAgent, right: AgentScreenAgent)
   if (left.runtimeInfo?.thinkingOptionId !== right.runtimeInfo?.thinkingOptionId) {
     reasons.push("agent.runtimeInfo.thinkingOptionId");
   }
-  if (left.features !== right.features) reasons.push("agent.features");
+  if (left.options !== right.options) reasons.push("agent.options");
+  if (left.controls !== right.controls) reasons.push("agent.controls");
   return reasons;
 }
 
@@ -1369,6 +1326,12 @@ function agentStreamViewPropsEqual(
   if (left.isAuthoritativeHistoryReady !== right.isAuthoritativeHistoryReady) {
     reasons.push("isAuthoritativeHistoryReady");
   }
+  if (left.isInitialHistoryLoading !== right.isInitialHistoryLoading) {
+    reasons.push("isInitialHistoryLoading");
+  }
+  if (left.revealInitialHistory !== right.revealInitialHistory) {
+    reasons.push("revealInitialHistory");
+  }
   if (left.bottomOverlayTailClearance !== right.bottomOverlayTailClearance) {
     reasons.push("bottomOverlayTailClearance");
   }
@@ -1788,10 +1751,6 @@ const stylesheet = StyleSheet.create((theme) => ({
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,
   },
-  invertedWrapper: {
-    transform: [{ scaleY: -1 }],
-    width: "100%",
-  },
   emptyStateText: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/agent-stream/web-virtualization.ts b/packages/app/src/agent-stream/web-virtualization.ts
index daf01af558..f397c7cb5d 100644
--- a/packages/app/src/agent-stream/web-virtualization.ts
+++ b/packages/app/src/agent-stream/web-virtualization.ts
@@ -65,6 +65,7 @@ export function estimateStreamItemHeight({
     case "tool_call":
       return COLLAPSED_TOOL_SEQUENCE_ROW_HEIGHT_ESTIMATE;
     case "thought":
+    case "turn_summary":
       return COLLAPSED_TOOL_SEQUENCE_ROW_HEIGHT_ESTIMATE;
     case "todo_list":
       return 144;
diff --git a/packages/app/src/app/_layout.tsx b/packages/app/src/app/_layout.tsx
index 083c6b2144..b4ca122f77 100644
--- a/packages/app/src/app/_layout.tsx
+++ b/packages/app/src/app/_layout.tsx
@@ -1,3 +1,13 @@
+import { useHardwareKeyboardPresent } from "@/keyboard";
+import {
+  WindowLayoutProvider,
+  WindowLayoutActionsHost,
+  WindowLayoutSurface,
+  WindowLayoutDivisionGap,
+  useWindowLayout,
+  resolveDesktopDivisionLayout,
+} from "@/window-layout";
+import { AddHostProvider, AddHostFlowHost } from "@/hosts/add-host";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useActiveWorkspaceSelection } from "@/stores/navigation-active-workspace-store";
 import { useIsExplorerSidebarOpen } from "@/workspace-tabs/explorer-sidebar";
@@ -15,6 +25,7 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useState,
   useSyncExternalStore,
@@ -35,6 +46,7 @@ import { DownloadToast } from "@/components/download-toast";
 import { QuittingOverlay } from "@/components/quitting-overlay";
 import { KeyboardShortcutsDialog } from "@/components/keyboard-shortcuts-dialog";
 import { ChangelogHost } from "@/changelog";
+import { OnboardingHost, useIsSetupDecisionPending } from "@/onboarding";
 import { AppDiagnosticHost } from "@/components/app-diagnostic-host";
 import { AppearanceStyleBoundary } from "@/components/appearance-style-boundary";
 import { LeftSidebar } from "@/components/left-sidebar";
@@ -43,6 +55,7 @@ import { DesktopWindowControls } from "@/components/desktop/window-controls";
 import { SidebarModelProvider } from "@/components/sidebar/sidebar-model";
 import { WorkspacePinShortcutHandler } from "@/components/workspace-pin-shortcut-handler";
 import { WorkspaceRenameHost } from "@/components/workspace-rename-host";
+import { WorkspaceArchiveUndoShortcutHost } from "@/workspace/archive-undo";
 import { WorkspaceExplorerOpenGesture } from "@/mobile-panels/explorer-open-gesture";
 import { ProviderSettingsHost } from "@/components/provider-settings-host";
 import { WorkspaceSetupDialog } from "@/components/workspace-setup-dialog";
@@ -56,6 +69,8 @@ import {
   resolveDesktopAppChromeLayout,
   resolveDesktopAppContentMinimum,
   resolveDesktopSidebarVisibility,
+  resolveSidebarActivity,
+  resolveLeftSidebarPresentation,
 } from "@/components/desktop-sidebar-layout";
 import { isNative, isWeb } from "@/constants/platform";
 import { HorizontalScrollProvider } from "@/contexts/horizontal-scroll-context";
@@ -88,7 +103,7 @@ import { useActiveWorktreeNewAction } from "@/hooks/use-active-worktree-new-acti
 import { useGlobalNewWorkspaceAction } from "@/hooks/use-global-new-workspace-action";
 import { useLatchedBoolean } from "@/hooks/use-latched-boolean";
 import { useFaviconStatus } from "@/hooks/use-favicon-status";
-import { useKeyboardShortcuts } from "@/hooks/use-keyboard-shortcuts";
+import { useKeyboardShortcuts } from "@/keyboard/use-shortcuts";
 import { KeyboardShiftProvider } from "@/keyboard/shift";
 import { useCompactWebViewportZoomLock } from "@/hooks/use-compact-web-viewport-zoom-lock";
 import { useOpenProject } from "@/hooks/use-open-project";
@@ -109,7 +124,7 @@ import {
   useHosts,
 } from "@/runtime/host-runtime";
 import { getDaemonStartService } from "@/runtime/daemon-start-service";
-import { usePanelStore } from "@/stores/panel-store";
+import { usePanelStore, type LeftSidebarPresentation } from "@/stores/panel-store";
 import { flushDraftPersistStorage } from "@/stores/draft-store";
 import { getNextThemePreference, ICON_STROKE_WIDTH } from "@/styles/theme";
 import { useSessionStore } from "@/stores/session-store";
@@ -137,6 +152,7 @@ export interface HostRuntimeBootstrapState {
   splashError: string | null;
   retry: () => void;
   hasGivenUpWaitingForHost: boolean;
+  isWaitingForSetup: boolean;
   storeReady: boolean;
   startupBlocker: StartupBlocker;
 }
@@ -145,6 +161,7 @@ const HostRuntimeBootstrapContext = createContext<HostRuntimeBootstrapState>({
   splashError: null,
   retry: () => {},
   hasGivenUpWaitingForHost: false,
+  isWaitingForSetup: false,
   storeReady: false,
   startupBlocker: { kind: "none" },
 });
@@ -241,6 +258,9 @@ function useDaemonStartIsRunning(): boolean {
 }
 
 const STARTUP_GIVE_UP_TIMEOUT_MS = 5_000;
+// How long the splash waits on top of host startup to learn whether setup opens. A slow host
+// lands on the home instead, and setup opens over it once it is decided.
+const STARTUP_SETUP_WAIT_TIMEOUT_MS = 3_000;
 
 async function shouldStartBuiltInDaemon(): Promise<boolean> {
   if (!shouldUseDesktopDaemon()) {
@@ -302,6 +322,23 @@ function HostRuntimeBootstrapProvider({ children }: { children: ReactNode }) {
     };
   }, [shouldRunGiveUpTimer]);
 
+  const isSetupDecisionPending = useIsSetupDecisionPending();
+  const [hasGivenUpWaitingForSetup, setHasGivenUpWaitingForSetup] = useState(false);
+  const isWaitingForSetup = isSetupDecisionPending && !hasGivenUpWaitingForSetup;
+  const shouldRunSetupWaitTimer = isWaitingForSetup && startupBlocker.kind === "none";
+
+  useEffect(() => {
+    if (!shouldRunSetupWaitTimer) {
+      return;
+    }
+    const handle = setTimeout(() => {
+      setHasGivenUpWaitingForSetup(true);
+    }, STARTUP_SETUP_WAIT_TIMEOUT_MS);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [shouldRunSetupWaitTimer]);
+
   const retry = useCallback(() => {
     const daemonStartService = getDaemonStartService({ store: getHostRuntimeStore() });
     void daemonStartService.startIfEnabled({ shouldStart: shouldStartBuiltInDaemon });
@@ -312,8 +349,15 @@ function HostRuntimeBootstrapProvider({ children }: { children: ReactNode }) {
   const storeReady = resolveStartupNavigationReady({ startupBlocker });
 
   const state = useMemo<HostRuntimeBootstrapState>(
-    () => ({ splashError, retry, hasGivenUpWaitingForHost, storeReady, startupBlocker }),
-    [splashError, retry, hasGivenUpWaitingForHost, storeReady, startupBlocker],
+    () => ({
+      splashError,
+      retry,
+      hasGivenUpWaitingForHost,
+      isWaitingForSetup,
+      storeReady,
+      startupBlocker,
+    }),
+    [splashError, retry, hasGivenUpWaitingForHost, isWaitingForSetup, storeReady, startupBlocker],
   );
 
   return (
@@ -352,9 +396,16 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const isFocusModeEnabled = usePanelStore((state) => state.desktop.focusModeEnabled);
   const isDesktopAgentListOpen = usePanelStore((state) => state.desktop.agentListOpen);
   const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
-  const { width: windowWidth } = useWindowDimensions();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const insets = useSafeAreaInsets();
   const viewportWidth = windowWidth - insets.left - insets.right;
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
+  });
 
   const cycleTheme = useCallback(() => {
     void updateSettings({ theme: getNextThemePreference(settings.theme) });
@@ -415,12 +466,24 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
     isCompactLayout,
     isMounted: desktopSidebarMounted,
     isOpen: isDesktopAgentListOpen,
+    divisionLayout,
     canShare: canDesktopAppSidebarShare({
       contentMinimumWidth: appContentMinimumWidth,
       requestedSidebarWidth: sidebarWidth,
       viewportWidth,
     }),
   });
+  const sidebarPresentation = resolveLeftSidebarPresentation({
+    chromeEnabled,
+    isCompactLayout,
+    isFocusModeEnabled: isWorkspaceFocusModeEnabled,
+    desktopSidebarVisible,
+  });
+  const applyPanelLayout = usePanelStore((state) => state.applyPanelLayout);
+  // Publishes the layout to the store, which owns the panel targets each layout allows.
+  useLayoutEffect(() => {
+    applyPanelLayout({ isCompact: isCompactLayout, leftSidebar: sidebarPresentation });
+  }, [applyPanelLayout, isCompactLayout, sidebarPresentation]);
   const hasTopLeftWindowControls = useHasWindowChromeObstruction("top-left");
   const appChromeLayout = resolveDesktopAppChromeLayout({
     desktopSidebarRendered: desktopSidebarVisible,
@@ -430,7 +493,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const sidebarChrome = (
     <SidebarChrome
       mounted={isCompactLayout ? chromeEnabled : desktopSidebarMounted}
-      visible={isCompactLayout ? chromeEnabled : desktopSidebarVisible}
+      presentation={sidebarPresentation}
       keyboardShortcutsEnabled={keyboardShortcutsEnabled}
     />
   );
@@ -438,18 +501,19 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   if (isWeb) {
     themedSidebarChrome = <AppearanceStyleBoundary>{sidebarChrome}</AppearanceStyleBoundary>;
   }
-  const workspaceChromeStyle = useMemo(
-    () => [rowStyle, !isCompactLayout && { paddingLeft: insets.left, paddingRight: insets.right }],
-    [insets.left, insets.right, isCompactLayout],
-  );
   const workspaceChrome = (
-    <View style={workspaceChromeStyle}>
+    <WindowLayoutSurface compact={isCompactLayout} style={rowStyle}>
       <WorkspaceLayoutModePublisher />
       {!isCompactLayout ? (
         <WindowChromeRegion corners={appChromeLayout.sidebarCorners}>
           {themedSidebarChrome}
         </WindowChromeRegion>
       ) : null}
+      <WindowLayoutDivisionGap
+        layout={divisionLayout}
+        sidebarVisible={desktopSidebarVisible}
+        compact={isCompactLayout}
+      />
       <WorkspaceExplorerOpenGesture enabled={chromeEnabled && isCompactLayout}>
         <WindowChromeRegion
           corners={isCompactLayout && chromeEnabled ? "both" : appChromeLayout.contentCorners}
@@ -457,7 +521,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
           <View style={flexStyle}>{children}</View>
         </WindowChromeRegion>
       </WorkspaceExplorerOpenGesture>
-    </View>
+    </WindowLayoutSurface>
   );
 
   // Native panel gesture hosts outlive appearance keys, like native navigators.
@@ -465,6 +529,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const surface = (
     <View style={layoutStyles.surfaceFill}>
       {workspaceChrome}
+      <AddHostFlowHost />
       <AppearanceStyleBoundary>
         {!isCompactLayout && appChromeLayout.sidebarToggleOwner === "window" ? (
           <WindowChromeRegion corners="top-left">
@@ -493,6 +558,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
         <PluginCommandCenterActions />
         <WorkspacePinShortcutHandler />
         <WorkspaceRenameHost />
+        <WorkspaceArchiveUndoShortcutHost />
         <CommandCenter />
         <AddProjectFlowHost />
         <HostChooserModal />
@@ -504,11 +570,15 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
         <ChangelogHost />
         <QuittingOverlay />
       </AppearanceStyleBoundary>
+      {/* Setup changes the theme while it is open, so it stays out of the remount above. Its
+          colors are CSS variables and themed props, which update in place, and setup changes no
+          font size. */}
+      <OnboardingHost />
     </View>
   );
 
   return (
-    <AppContainerLifetime compactGesturesEnabled={chromeEnabled && isCompactLayout}>
+    <AppContainerLifetime sidebarGesturesEnabled={sidebarPresentation === "overlay"}>
       <SheetHostScope enabled={isCompactLayout}>{surface}</SheetHostScope>
     </AppContainerLifetime>
   );
@@ -516,15 +586,15 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
 
 function AppContainerLifetime({
   children,
-  compactGesturesEnabled,
+  sidebarGesturesEnabled,
 }: {
   children: ReactNode;
-  compactGesturesEnabled: boolean;
+  sidebarGesturesEnabled: boolean;
 }) {
   return (
     <ComposerEditingSessionsProvider>
       <CommandCenterProvider>
-        <MobileGestureWrapper chromeEnabled={compactGesturesEnabled}>
+        <MobileGestureWrapper chromeEnabled={sidebarGesturesEnabled}>
           {children}
         </MobileGestureWrapper>
       </CommandCenterProvider>
@@ -534,20 +604,26 @@ function AppContainerLifetime({
 
 function SidebarChrome({
   mounted,
-  visible,
+  presentation,
   keyboardShortcutsEnabled,
 }: {
   mounted: boolean;
-  visible: boolean;
+  presentation: LeftSidebarPresentation;
   keyboardShortcutsEnabled: boolean;
 }) {
   const isCompactLayout = useIsCompactFormFactor();
   const isMobileActive = useIsMobilePanelActive("agent-list");
-  const isDesktopOpen = usePanelStore((state) => state.desktop.agentListOpen);
-  const active = visible && (isCompactLayout ? isMobileActive : isDesktopOpen);
+  const overlay = presentation === "overlay";
+  const active = resolveSidebarActivity(presentation !== "hidden", overlay, isMobileActive);
+  const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   return (
-    <SidebarModelProvider active={active}>
-      {mounted ? <LeftSidebar active={active} /> : null}
+    <SidebarModelProvider
+      active={active}
+      keyboardNavigationActive={keyboardShortcutsEnabled && hardwareKeyboardPresent}
+    >
+      {mounted ? (
+        <LeftSidebar active={active} desktopOverlay={overlay && !isCompactLayout} />
+      ) : null}
       <WorkspaceShortcutTargetsSubscriber enabled={keyboardShortcutsEnabled} />
     </SidebarModelProvider>
   );
@@ -560,8 +636,8 @@ function MobileGestureWrapper({
   children: ReactNode;
   chromeEnabled: boolean;
 }) {
-  const openGesture = useOpenAgentListGesture(chromeEnabled);
   const isCompactLayout = useIsCompactFormFactor();
+  const openGesture = useOpenAgentListGesture(chromeEnabled);
 
   return (
     <GestureDetector gesture={openGesture} touchAction={MOBILE_WEB_GESTURE_TOUCH_ACTION}>
@@ -805,7 +881,6 @@ function RootStack() {
         <Stack.Screen name="open-project" />
         <Stack.Screen name="sessions" />
         <Stack.Screen name="schedules" />
-        <Stack.Screen name="pair-scan" />
       </Stack.Protected>
       <Stack.Screen name="h/[serverId]" />
       <Stack.Screen name="settings/hosts/[serverId]/index" />
@@ -867,20 +942,31 @@ function RuntimeProviders({ children }: { children: ReactNode }) {
 // auth, settings, ...) must wrap PortalProvider, not be wrapped by it.
 // BottomSheetModalProvider is the exception: Gorhom modals consume portal
 // context and need one shared provider for sibling sheets to stack.
+function RootOverlayProviders({ children }: { children: ReactNode }) {
+  return (
+    <ToastProvider>
+      <PortalProvider>
+        <BottomSheetModalProvider>
+          {children}
+          <WindowLayoutActionsHost />
+        </BottomSheetModalProvider>
+      </PortalProvider>
+    </ToastProvider>
+  );
+}
+
 function RootProviders({ children }: { children: ReactNode }) {
   return (
     <KeyboardActionDispatcherProvider>
-      <WindowChromeProvider>
-        <KeyboardProvider>
-          <KeyboardShiftProvider>
-            <ToastProvider>
-              <PortalProvider>
-                <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
-              </PortalProvider>
-            </ToastProvider>
-          </KeyboardShiftProvider>
-        </KeyboardProvider>
-      </WindowChromeProvider>
+      <WindowLayoutProvider>
+        <WindowChromeProvider>
+          <KeyboardProvider>
+            <KeyboardShiftProvider>
+              <RootOverlayProviders>{children}</RootOverlayProviders>
+            </KeyboardShiftProvider>
+          </KeyboardProvider>
+        </WindowChromeProvider>
+      </WindowLayoutProvider>
     </KeyboardActionDispatcherProvider>
   );
 }
@@ -890,11 +976,13 @@ function RootAppTree() {
     <GestureHandlerRootView style={flexStyle}>
       <View style={layoutStyles.surfaceFill}>
         <LucideProvider strokeWidth={ICON_STROKE_WIDTH}>
-          <RootProviders>
-            <RuntimeProviders>
-              <AppShell />
-            </RuntimeProviders>
-          </RootProviders>
+          <AddHostProvider>
+            <RootProviders>
+              <RuntimeProviders>
+                <AppShell />
+              </RuntimeProviders>
+            </RootProviders>
+          </AddHostProvider>
         </LucideProvider>
       </View>
     </GestureHandlerRootView>
diff --git a/packages/app/src/app/index.tsx b/packages/app/src/app/index.tsx
index e0649f65a1..f6850a2a57 100644
--- a/packages/app/src/app/index.tsx
+++ b/packages/app/src/app/index.tsx
@@ -45,11 +45,19 @@ export default function Index() {
     }),
     isWorkspaceSelectionLoaded,
     hasGivenUpWaitingForHost: bootstrapState.hasGivenUpWaitingForHost,
+    isWaitingForSetup: bootstrapState.isWaitingForSetup,
   });
 
+  const splash = <StartupSplashScreen bootstrapState={isDesktop ? bootstrapState : undefined} />;
   if (startupRoute.kind === "redirect") {
-    return <Redirect href={startupRoute.href} />;
+    // The loading screen stays up until the target route paints; a redirect alone renders nothing.
+    return (
+      <>
+        {splash}
+        <Redirect href={startupRoute.href} />
+      </>
+    );
   }
 
-  return <StartupSplashScreen bootstrapState={isDesktop ? bootstrapState : undefined} />;
+  return splash;
 }
diff --git a/packages/app/src/app/settings/[section].tsx b/packages/app/src/app/settings/[section].tsx
index 8b036e2aac..583428864c 100644
--- a/packages/app/src/app/settings/[section].tsx
+++ b/packages/app/src/app/settings/[section].tsx
@@ -35,10 +35,9 @@ function SettingsDaemonRedirect() {
 }
 
 export default function SettingsSectionRoute() {
-  const params = useLocalSearchParams<{ section?: string; addHost?: string }>();
+  const params = useLocalSearchParams<{ section?: string }>();
   const rawSection = typeof params.section === "string" ? params.section : "";
   const section: SettingsSectionSlug = isSettingsSectionSlug(rawSection) ? rawSection : "general";
-  const openAddHostIntent = typeof params.addHost === "string" ? params.addHost : null;
   const view = useMemo(() => ({ kind: "section" as const, section }), [section]);
 
   // COMPAT(settingsDaemonRedirect): added 2026-07-08, remove after 2027-01-08.
@@ -50,5 +49,5 @@ export default function SettingsSectionRoute() {
     );
   }
 
-  return <SettingsScreen view={view} openAddHostIntent={openAddHostIntent} />;
+  return <SettingsScreen view={view} />;
 }
diff --git a/packages/app/src/appearance/theme-picker.tsx b/packages/app/src/appearance/theme-picker.tsx
new file mode 100644
index 0000000000..cb2ebf5983
--- /dev/null
+++ b/packages/app/src/appearance/theme-picker.tsx
@@ -0,0 +1,292 @@
+import { useCallback, useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { Text, View, type PressableStateCallbackType } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { PressHighlight } from "@/components/ui/press-highlight";
+import { DEFAULT_THEME_PREFERENCE, useAppSettings, type AppSettings } from "@/hooks/use-settings";
+import type { PluginThemeOption } from "@/plugins/themes";
+import {
+  THEME_OPTIONS,
+  PLUGIN_THEME_PREFERENCE,
+  darkTheme,
+  lightTheme,
+  type Theme,
+} from "@/styles/theme";
+import { useContributedThemes } from "./provider";
+
+type BuiltInThemePreference = Exclude<AppSettings["theme"], typeof PLUGIN_THEME_PREFERENCE>;
+
+// System leads the grid because it is the default.
+const PICKER_THEME_OPTIONS = [
+  ...THEME_OPTIONS.filter((option) => option.name === "auto"),
+  ...THEME_OPTIONS.filter((option) => option.name !== "auto"),
+];
+
+const PREVIEW_ASPECT_RATIO = 16 / 9;
+
+/**
+ * Every theme as a tile with a small preview drawn from its own tokens. Picking a tile applies
+ * the theme to the whole app at once. Settings → Appearance and first-run setup share it.
+ */
+export function ThemePicker() {
+  const { t } = useTranslation();
+  const { settings, updateSettings } = useAppSettings();
+  const { options: pluginThemes, selected: selectedPluginTheme, select } = useContributedThemes();
+  // A selected contribution that is no longer installed shows the fallback the app renders.
+  const builtInValue =
+    settings.theme === PLUGIN_THEME_PREFERENCE ? DEFAULT_THEME_PREFERENCE : settings.theme;
+
+  const selectBuiltIn = useCallback(
+    (theme: BuiltInThemePreference) => {
+      void updateSettings({ theme });
+    },
+    [updateSettings],
+  );
+
+  return (
+    <View
+      style={styles.grid}
+      accessibilityRole="radiogroup"
+      accessibilityLabel={t("settings.appearance.theme.title")}
+    >
+      {PICKER_THEME_OPTIONS.map((option) => (
+        <BuiltInThemeTile
+          key={option.name}
+          value={option.name}
+          selected={selectedPluginTheme === null && builtInValue === option.name}
+          onSelect={selectBuiltIn}
+        />
+      ))}
+      {pluginThemes.map((option) => (
+        <PluginThemeTile
+          key={option.id}
+          option={option}
+          selected={selectedPluginTheme?.id === option.id}
+          onSelect={select}
+        />
+      ))}
+    </View>
+  );
+}
+
+function BuiltInThemeTile({
+  value,
+  selected,
+  onSelect,
+}: {
+  value: BuiltInThemePreference;
+  selected: boolean;
+  onSelect: (value: BuiltInThemePreference) => void;
+}) {
+  const { t } = useTranslation();
+  const handlePress = useCallback(() => onSelect(value), [onSelect, value]);
+  const option = THEME_OPTIONS.find((candidate) => candidate.name === value);
+  return (
+    <ThemeTile
+      label={t(`settings.appearance.theme.options.${value}`)}
+      selected={selected}
+      onPress={handlePress}
+      previewTheme={option && "theme" in option ? option.theme : "system"}
+    />
+  );
+}
+
+function PluginThemeTile({
+  option,
+  selected,
+  onSelect,
+}: {
+  option: PluginThemeOption;
+  selected: boolean;
+  onSelect: (option: PluginThemeOption) => void;
+}) {
+  const handlePress = useCallback(() => onSelect(option), [onSelect, option]);
+  return (
+    <ThemeTile
+      label={option.name}
+      selected={selected}
+      onPress={handlePress}
+      previewTheme={option.theme}
+    />
+  );
+}
+
+function ThemeTile({
+  label,
+  selected,
+  onPress,
+  previewTheme,
+}: {
+  label: string;
+  selected: boolean;
+  onPress: () => void;
+  /** "system" follows the OS, so its preview shows both halves. */
+  previewTheme: Theme | "system";
+}) {
+  const accessibilityState = useMemo(() => ({ checked: selected }), [selected]);
+  const tileStyle = useCallback(
+    ({ hovered }: PressableStateCallbackType & { hovered?: boolean }) => [
+      styles.tile,
+      hovered && !selected && styles.tileHovered,
+      selected && styles.tileSelected,
+    ],
+    [selected],
+  );
+  return (
+    <View style={styles.cell}>
+      <PressHighlight
+        style={tileStyle}
+        onPress={onPress}
+        accessibilityRole="radio"
+        accessibilityLabel={label}
+        accessibilityState={accessibilityState}
+        aria-checked={selected}
+      >
+        <View style={styles.previewFrame}>
+          {previewTheme === "system" ? (
+            <SystemThemePreview />
+          ) : (
+            <ThemePreview theme={previewTheme} />
+          )}
+        </View>
+        <Text style={styles.label} numberOfLines={1}>
+          {label}
+        </Text>
+      </PressHighlight>
+    </View>
+  );
+}
+
+/** A sketch of the app — sidebar, a few lines of text and an accent bubble — in `theme`'s colors. */
+function ThemePreview({ theme }: { theme: Theme }) {
+  const colors = theme.colors;
+  const previewStyles = useMemo(
+    () => ({
+      root: [styles.preview, { backgroundColor: colors.surface0 }],
+      sidebar: [styles.previewSidebar, { backgroundColor: colors.surfaceSidebar }],
+      mutedLine: { backgroundColor: colors.foregroundMuted },
+      strongLine: { backgroundColor: colors.foreground },
+      bubble: [styles.previewBubble, { backgroundColor: colors.accent }],
+    }),
+    [colors],
+  );
+  return (
+    <View style={previewStyles.root}>
+      <View style={previewStyles.sidebar}>
+        <View style={[styles.previewLine, styles.sidebarLineWide, previewStyles.mutedLine]} />
+        <View style={[styles.previewLine, styles.sidebarLineNarrow, previewStyles.mutedLine]} />
+        <View style={[styles.previewLine, styles.sidebarLineMedium, previewStyles.mutedLine]} />
+      </View>
+      <View style={styles.previewMain}>
+        <View style={[styles.previewTitle, previewStyles.strongLine]} />
+        <View style={[styles.previewLine, styles.mainLineWide, previewStyles.mutedLine]} />
+        <View style={[styles.previewLine, styles.mainLineNarrow, previewStyles.mutedLine]} />
+        <View style={previewStyles.bubble} />
+      </View>
+    </View>
+  );
+}
+
+/** "System" follows the OS: light on the left half, dark on the right. */
+function SystemThemePreview() {
+  return (
+    <View style={styles.preview}>
+      <ThemePreview theme={lightTheme} />
+      <View style={styles.systemDarkHalf}>
+        <View style={styles.systemDarkOffset}>
+          <ThemePreview theme={darkTheme} />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  // Columns fill the row: each cell is a fixed fraction of it, and the half-gap padding on every
+  // cell plus the negative margin here leaves exactly one gap between neighbors.
+  grid: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    margin: -theme.spacing[3] / 2,
+  },
+  cell: {
+    width: { xs: "50%", md: "25%" },
+    padding: theme.spacing[3] / 2,
+  },
+  tile: {
+    padding: theme.spacing[1],
+    gap: theme.spacing[1],
+    borderRadius: theme.borderRadius.lg,
+    borderWidth: theme.borderWidth[2],
+    borderColor: "transparent",
+  },
+  tileHovered: {
+    backgroundColor: theme.colors.surface2,
+  },
+  tileSelected: {
+    borderColor: theme.colors.accent,
+  },
+  previewFrame: {
+    borderRadius: theme.borderRadius.md,
+    borderWidth: theme.borderWidth[1],
+    borderColor: theme.colors.border,
+    overflow: "hidden",
+  },
+  label: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.sm,
+    paddingHorizontal: theme.spacing[1],
+  },
+  preview: {
+    width: "100%",
+    aspectRatio: PREVIEW_ASPECT_RATIO,
+    flexDirection: "row",
+    overflow: "hidden",
+  },
+  previewSidebar: {
+    width: 36,
+    paddingHorizontal: 6,
+    paddingVertical: 8,
+    gap: 5,
+  },
+  previewMain: {
+    flex: 1,
+    padding: 8,
+    gap: 5,
+  },
+  previewLine: {
+    height: 4,
+    borderRadius: 2,
+    opacity: 0.6,
+  },
+  previewTitle: {
+    width: "55%",
+    height: 5,
+    borderRadius: 2,
+  },
+  sidebarLineWide: { width: "100%" },
+  sidebarLineNarrow: { width: "60%" },
+  sidebarLineMedium: { width: "80%" },
+  mainLineWide: { width: "90%" },
+  mainLineNarrow: { width: "65%" },
+  previewBubble: {
+    marginTop: "auto",
+    alignSelf: "flex-end",
+    width: "45%",
+    height: 10,
+    borderRadius: 5,
+  },
+  systemDarkHalf: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    left: "50%",
+    width: "50%",
+    overflow: "hidden",
+  },
+  // A full-width dark preview shifted left by half, so only its right half shows.
+  systemDarkOffset: {
+    width: "200%",
+    marginLeft: "-100%",
+  },
+}));
diff --git a/packages/app/src/assets/acp-provider-icons.ts b/packages/app/src/assets/acp-provider-icons.ts
index 703473e6be..c04e0c42af 100644
--- a/packages/app/src/assets/acp-provider-icons.ts
+++ b/packages/app/src/assets/acp-provider-icons.ts
@@ -38,6 +38,7 @@ export const ACP_PROVIDER_ICON_SVGS = {
     '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 900 900" fill="none"><path fill="currentColor" d="M622.037 192.524a10.58 10.58 0 0 1-4.056-2.001 10.573 10.573 0 0 1-3.98-7.89 10.595 10.595 0 0 1 .804-4.452c20.214-49.194 29.134-88.555 14.74-105.033-38.123-43.716-191.004 43.219-239.75 72.663a10.596 10.596 0 0 1-10.841.041 10.576 10.576 0 0 1-4.396-5.07c-20.491-49.089-42.031-83.233-63.865-84.714-57.871-3.96-104.516 165.624-118.17 220.895a10.574 10.574 0 0 1-1.993 4.057 10.572 10.572 0 0 1-7.884 3.977 10.586 10.586 0 0 1-4.447-.802c-49.194-20.215-88.572-29.134-105.033-14.74-43.717 38.123 43.202 191.005 72.644 239.75a10.553 10.553 0 0 1 1.454 4.279 10.573 10.573 0 0 1-6.481 10.958c-49.072 20.491-83.216 42.031-84.715 63.864-3.944 57.871 165.624 104.516 220.913 118.171a10.566 10.566 0 0 1 5.658 3.601 10.57 10.57 0 0 1 2.355 6.281 10.58 10.58 0 0 1-.799 4.442c-20.214 49.194-29.134 88.572-14.739 105.033 38.121 43.717 191.021-43.202 239.767-72.644a10.566 10.566 0 0 1 15.238 5.027c20.489 49.072 42.013 83.216 63.862 84.715 57.871 3.944 104.516-165.624 118.153-220.913a10.603 10.603 0 0 1 9.895-8.021 10.566 10.566 0 0 1 4.449.808c49.193 20.214 88.553 29.116 105.032 14.738 43.718-38.121-43.219-191.022-72.663-239.767a10.602 10.602 0 0 1 1.326-12.655 10.604 10.604 0 0 1 3.703-2.582c49.089-20.49 83.233-42.031 84.714-63.863 3.96-57.871-165.624-104.516-220.895-118.153Zm-66.394-55.478c11.123 19.938-46.196 152.797-88.83 245.724a8.36 8.36 0 0 1-8.239 4.855 8.374 8.374 0 0 1-7.412-6.043c-17.219-60.42-36.899-131.411-57.957-191.675a10.557 10.557 0 0 1 4.924-12.759c52.586-28.721 142.568-66.86 157.514-40.102ZM303.635 153.49c21.953 6.233 75.365 140.709 110.92 236.564a8.364 8.364 0 0 1-2.394 9.249 8.364 8.364 0 0 1-9.504.978c-54.943-30.493-119.013-66.824-176.522-94.546a10.565 10.565 0 0 1-5.528-12.501c16.926-57.44 53.532-148.095 83.028-139.744ZM137.064 343.322c19.921-11.123 152.795 46.197 245.707 88.83a8.369 8.369 0 0 1-1.189 15.652c-60.401 17.219-131.411 36.899-191.675 57.957a10.552 10.552 0 0 1-12.742-4.925c-28.668-52.584-66.876-142.568-40.101-157.514Zm16.443 252.009c6.217-21.953 140.709-75.365 236.564-110.921a8.368 8.368 0 0 1 10.227 11.898c-30.511 54.945-66.842 119.014-94.563 176.507a10.548 10.548 0 0 1-5.229 5.075 10.544 10.544 0 0 1-7.271.468c-57.441-16.822-148.095-53.531-139.728-83.027ZM343.34 761.902c-11.14-19.922 46.197-152.796 88.829-245.707a8.383 8.383 0 0 1 5.713-4.66 8.38 8.38 0 0 1 7.182 1.664 8.371 8.371 0 0 1 2.758 4.184c17.217 60.403 36.898 131.412 57.957 191.675a10.558 10.558 0 0 1-4.942 12.743c-52.568 28.668-142.568 66.875-157.445 40.101h-.052Zm252.009-16.443c-21.971-6.216-75.383-140.709-110.939-236.564a8.37 8.37 0 0 1 11.916-10.228c54.926 30.494 119.014 66.842 176.506 94.563a10.538 10.538 0 0 1 5.527 12.502c-16.909 57.526-53.515 148.094-83.01 139.727Zm166.57-189.834c-19.938 11.141-152.796-46.197-245.724-88.83a8.367 8.367 0 0 1-2.993-12.892 8.378 8.378 0 0 1 4.182-2.759c60.419-17.218 131.41-36.899 191.675-57.958a10.577 10.577 0 0 1 12.758 4.943c28.652 52.568 66.86 142.569 40.102 157.496Zm-16.444-252.009c-6.232 21.971-140.709 75.383-236.562 110.94a8.371 8.371 0 0 1-10.229-11.917c30.495-54.926 66.825-119.012 94.547-176.505a10.555 10.555 0 0 1 12.5-5.528c57.441 16.909 148.096 53.516 139.744 83.01Z"/></svg>\n',
   "fast-agent":
     '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 360" width="16" height="16">\n  <g fill="currentColor">\n    <circle cx="100.50" cy="40.50" r="4.50"/>\n    <circle cx="112.50" cy="40.50" r="4.50"/>\n    <circle cx="124.50" cy="40.50" r="4.50"/>\n    <circle cx="136.50" cy="40.50" r="4.50"/>\n    <circle cx="148.50" cy="40.50" r="4.50"/>\n    <circle cx="76.50" cy="52.50" r="4.50"/>\n    <circle cx="88.50" cy="52.50" r="4.50"/>\n    <circle cx="100.50" cy="52.50" r="4.50"/>\n    <circle cx="136.50" cy="52.50" r="4.50"/>\n    <circle cx="148.50" cy="52.50" r="4.50"/>\n    <circle cx="160.50" cy="52.50" r="4.50"/>\n    <circle cx="64.50" cy="64.50" r="4.50"/>\n    <circle cx="76.50" cy="64.50" r="4.50"/>\n    <circle cx="88.50" cy="64.50" r="4.50"/>\n    <circle cx="100.50" cy="64.50" r="4.50"/>\n    <circle cx="136.50" cy="64.50" r="4.50"/>\n    <circle cx="148.50" cy="64.50" r="4.50"/>\n    <circle cx="160.50" cy="64.50" r="4.50"/>\n    <circle cx="172.50" cy="64.50" r="4.50"/>\n    <circle cx="52.50" cy="76.50" r="4.50"/>\n    <circle cx="64.50" cy="76.50" r="4.50"/>\n    <circle cx="76.50" cy="76.50" r="4.50"/>\n    <circle cx="88.50" cy="76.50" r="4.50"/>\n    <circle cx="100.50" cy="76.50" r="4.50"/>\n    <circle cx="136.50" cy="76.50" r="4.50"/>\n    <circle cx="148.50" cy="76.50" r="4.50"/>\n    <circle cx="160.50" cy="76.50" r="4.50"/>\n    <circle cx="52.50" cy="88.50" r="4.50"/>\n    <circle cx="64.50" cy="88.50" r="4.50"/>\n    <circle cx="76.50" cy="88.50" r="4.50"/>\n    <circle cx="88.50" cy="88.50" r="4.50"/>\n    <circle cx="100.50" cy="88.50" r="4.50"/>\n    <circle cx="148.50" cy="88.50" r="4.50"/>\n    <circle cx="52.50" cy="100.50" r="4.50"/>\n    <circle cx="64.50" cy="100.50" r="4.50"/>\n    <circle cx="76.50" cy="100.50" r="4.50"/>\n    <circle cx="88.50" cy="100.50" r="4.50"/>\n    <circle cx="100.50" cy="100.50" r="4.50"/>\n    <circle cx="52.50" cy="112.50" r="4.50"/>\n    <circle cx="64.50" cy="112.50" r="4.50"/>\n    <circle cx="76.50" cy="112.50" r="4.50"/>\n    <circle cx="88.50" cy="112.50" r="4.50"/>\n    <circle cx="100.50" cy="112.50" r="4.50"/>\n    <circle cx="52.50" cy="124.50" r="4.50"/>\n    <circle cx="64.50" cy="124.50" r="4.50"/>\n    <circle cx="76.50" cy="124.50" r="4.50"/>\n    <circle cx="88.50" cy="124.50" r="4.50"/>\n    <circle cx="100.50" cy="124.50" r="4.50"/>\n    <circle cx="232.50" cy="124.50" r="4.50"/>\n    <circle cx="244.50" cy="124.50" r="4.50"/>\n    <circle cx="256.50" cy="124.50" r="4.50"/>\n    <circle cx="28.50" cy="136.50" r="4.50"/>\n    <circle cx="40.50" cy="136.50" r="4.50"/>\n    <circle cx="52.50" cy="136.50" r="4.50"/>\n    <circle cx="64.50" cy="136.50" r="4.50"/>\n    <circle cx="76.50" cy="136.50" r="4.50"/>\n    <circle cx="88.50" cy="136.50" r="4.50"/>\n    <circle cx="100.50" cy="136.50" r="4.50"/>\n    <circle cx="112.50" cy="136.50" r="4.50"/>\n    <circle cx="124.50" cy="136.50" r="4.50"/>\n    <circle cx="196.50" cy="136.50" r="4.50"/>\n    <circle cx="208.50" cy="136.50" r="4.50"/>\n    <circle cx="220.50" cy="136.50" r="4.50"/>\n    <circle cx="232.50" cy="136.50" r="4.50"/>\n    <circle cx="244.50" cy="136.50" r="4.50"/>\n    <circle cx="256.50" cy="136.50" r="4.50"/>\n    <circle cx="268.50" cy="136.50" r="4.50"/>\n    <circle cx="280.50" cy="136.50" r="4.50"/>\n    <circle cx="28.50" cy="148.50" r="4.50"/>\n    <circle cx="40.50" cy="148.50" r="4.50"/>\n    <circle cx="52.50" cy="148.50" r="4.50"/>\n    <circle cx="64.50" cy="148.50" r="4.50"/>\n    <circle cx="76.50" cy="148.50" r="4.50"/>\n    <circle cx="88.50" cy="148.50" r="4.50"/>\n    <circle cx="100.50" cy="148.50" r="4.50"/>\n    <circle cx="112.50" cy="148.50" r="4.50"/>\n    <circle cx="124.50" cy="148.50" r="4.50"/>\n    <circle cx="172.50" cy="148.50" r="4.50"/>\n    <circle cx="184.50" cy="148.50" r="4.50"/>\n    <circle cx="196.50" cy="148.50" r="4.50"/>\n    <circle cx="256.50" cy="148.50" r="4.50"/>\n    <circle cx="268.50" cy="148.50" r="4.50"/>\n    <circle cx="280.50" cy="148.50" r="4.50"/>\n    <circle cx="292.50" cy="148.50" r="4.50"/>\n    <circle cx="52.50" cy="160.50" r="4.50"/>\n    <circle cx="64.50" cy="160.50" r="4.50"/>\n    <circle cx="76.50" cy="160.50" r="4.50"/>\n    <circle cx="88.50" cy="160.50" r="4.50"/>\n    <circle cx="100.50" cy="160.50" r="4.50"/>\n    <circle cx="160.50" cy="160.50" r="4.50"/>\n    <circle cx="172.50" cy="160.50" r="4.50"/>\n    <circle cx="184.50" cy="160.50" r="4.50"/>\n    <circle cx="196.50" cy="160.50" r="4.50"/>\n    <circle cx="256.50" cy="160.50" r="4.50"/>\n    <circle cx="268.50" cy="160.50" r="4.50"/>\n    <circle cx="280.50" cy="160.50" r="4.50"/>\n    <circle cx="292.50" cy="160.50" r="4.50"/>\n    <circle cx="304.50" cy="160.50" r="4.50"/>\n    <circle cx="52.50" cy="172.50" r="4.50"/>\n    <circle cx="64.50" cy="172.50" r="4.50"/>\n    <circle cx="76.50" cy="172.50" r="4.50"/>\n    <circle cx="88.50" cy="172.50" r="4.50"/>\n    <circle cx="100.50" cy="172.50" r="4.50"/>\n    <circle cx="160.50" cy="172.50" r="4.50"/>\n    <circle cx="172.50" cy="172.50" r="4.50"/>\n    <circle cx="184.50" cy="172.50" r="4.50"/>\n    <circle cx="196.50" cy="172.50" r="4.50"/>\n    <circle cx="208.50" cy="172.50" r="4.50"/>\n    <circle cx="256.50" cy="172.50" r="4.50"/>\n    <circle cx="268.50" cy="172.50" r="4.50"/>\n    <circle cx="280.50" cy="172.50" r="4.50"/>\n    <circle cx="292.50" cy="172.50" r="4.50"/>\n    <circle cx="304.50" cy="172.50" r="4.50"/>\n    <circle cx="52.50" cy="184.50" r="4.50"/>\n    <circle cx="64.50" cy="184.50" r="4.50"/>\n    <circle cx="76.50" cy="184.50" r="4.50"/>\n    <circle cx="88.50" cy="184.50" r="4.50"/>\n    <circle cx="100.50" cy="184.50" r="4.50"/>\n    <circle cx="160.50" cy="184.50" r="4.50"/>\n    <circle cx="172.50" cy="184.50" r="4.50"/>\n    <circle cx="184.50" cy="184.50" r="4.50"/>\n    <circle cx="196.50" cy="184.50" r="4.50"/>\n    <circle cx="208.50" cy="184.50" r="4.50"/>\n    <circle cx="256.50" cy="184.50" r="4.50"/>\n    <circle cx="268.50" cy="184.50" r="4.50"/>\n    <circle cx="280.50" cy="184.50" r="4.50"/>\n    <circle cx="292.50" cy="184.50" r="4.50"/>\n    <circle cx="304.50" cy="184.50" r="4.50"/>\n    <circle cx="52.50" cy="196.50" r="4.50"/>\n    <circle cx="64.50" cy="196.50" r="4.50"/>\n    <circle cx="76.50" cy="196.50" r="4.50"/>\n    <circle cx="88.50" cy="196.50" r="4.50"/>\n    <circle cx="100.50" cy="196.50" r="4.50"/>\n    <circle cx="172.50" cy="196.50" r="4.50"/>\n    <circle cx="184.50" cy="196.50" r="4.50"/>\n    <circle cx="196.50" cy="196.50" r="4.50"/>\n    <circle cx="256.50" cy="196.50" r="4.50"/>\n    <circle cx="268.50" cy="196.50" r="4.50"/>\n    <circle cx="280.50" cy="196.50" r="4.50"/>\n    <circle cx="292.50" cy="196.50" r="4.50"/>\n    <circle cx="304.50" cy="196.50" r="4.50"/>\n    <circle cx="52.50" cy="208.50" r="4.50"/>\n    <circle cx="64.50" cy="208.50" r="4.50"/>\n    <circle cx="76.50" cy="208.50" r="4.50"/>\n    <circle cx="88.50" cy="208.50" r="4.50"/>\n    <circle cx="100.50" cy="208.50" r="4.50"/>\n    <circle cx="244.50" cy="208.50" r="4.50"/>\n    <circle cx="256.50" cy="208.50" r="4.50"/>\n    <circle cx="268.50" cy="208.50" r="4.50"/>\n    <circle cx="280.50" cy="208.50" r="4.50"/>\n    <circle cx="292.50" cy="208.50" r="4.50"/>\n    <circle cx="304.50" cy="208.50" r="4.50"/>\n    <circle cx="52.50" cy="220.50" r="4.50"/>\n    <circle cx="64.50" cy="220.50" r="4.50"/>\n    <circle cx="76.50" cy="220.50" r="4.50"/>\n    <circle cx="88.50" cy="220.50" r="4.50"/>\n    <circle cx="100.50" cy="220.50" r="4.50"/>\n    <circle cx="220.50" cy="220.50" r="4.50"/>\n    <circle cx="232.50" cy="220.50" r="4.50"/>\n    <circle cx="256.50" cy="220.50" r="4.50"/>\n    <circle cx="268.50" cy="220.50" r="4.50"/>\n    <circle cx="280.50" cy="220.50" r="4.50"/>\n    <circle cx="292.50" cy="220.50" r="4.50"/>\n    <circle cx="304.50" cy="220.50" r="4.50"/>\n    <circle cx="52.50" cy="232.50" r="4.50"/>\n    <circle cx="64.50" cy="232.50" r="4.50"/>\n    <circle cx="76.50" cy="232.50" r="4.50"/>\n    <circle cx="88.50" cy="232.50" r="4.50"/>\n    <circle cx="100.50" cy="232.50" r="4.50"/>\n    <circle cx="196.50" cy="232.50" r="4.50"/>\n    <circle cx="208.50" cy="232.50" r="4.50"/>\n    <circle cx="220.50" cy="232.50" r="4.50"/>\n    <circle cx="256.50" cy="232.50" r="4.50"/>\n    <circle cx="268.50" cy="232.50" r="4.50"/>\n    <circle cx="280.50" cy="232.50" r="4.50"/>\n    <circle cx="292.50" cy="232.50" r="4.50"/>\n    <circle cx="304.50" cy="232.50" r="4.50"/>\n    <circle cx="52.50" cy="244.50" r="4.50"/>\n    <circle cx="64.50" cy="244.50" r="4.50"/>\n    <circle cx="76.50" cy="244.50" r="4.50"/>\n    <circle cx="88.50" cy="244.50" r="4.50"/>\n    <circle cx="100.50" cy="244.50" r="4.50"/>\n    <circle cx="184.50" cy="244.50" r="4.50"/>\n    <circle cx="196.50" cy="244.50" r="4.50"/>\n    <circle cx="208.50" cy="244.50" r="4.50"/>\n    <circle cx="256.50" cy="244.50" r="4.50"/>\n    <circle cx="268.50" cy="244.50" r="4.50"/>\n    <circle cx="280.50" cy="244.50" r="4.50"/>\n    <circle cx="292.50" cy="244.50" r="4.50"/>\n    <circle cx="304.50" cy="244.50" r="4.50"/>\n    <circle cx="52.50" cy="256.50" r="4.50"/>\n    <circle cx="64.50" cy="256.50" r="4.50"/>\n    <circle cx="76.50" cy="256.50" r="4.50"/>\n    <circle cx="88.50" cy="256.50" r="4.50"/>\n    <circle cx="100.50" cy="256.50" r="4.50"/>\n    <circle cx="172.50" cy="256.50" r="4.50"/>\n    <circle cx="184.50" cy="256.50" r="4.50"/>\n    <circle cx="196.50" cy="256.50" r="4.50"/>\n    <circle cx="208.50" cy="256.50" r="4.50"/>\n    <circle cx="256.50" cy="256.50" r="4.50"/>\n    <circle cx="268.50" cy="256.50" r="4.50"/>\n    <circle cx="280.50" cy="256.50" r="4.50"/>\n    <circle cx="292.50" cy="256.50" r="4.50"/>\n    <circle cx="304.50" cy="256.50" r="4.50"/>\n    <circle cx="52.50" cy="268.50" r="4.50"/>\n    <circle cx="64.50" cy="268.50" r="4.50"/>\n    <circle cx="76.50" cy="268.50" r="4.50"/>\n    <circle cx="88.50" cy="268.50" r="4.50"/>\n    <circle cx="100.50" cy="268.50" r="4.50"/>\n    <circle cx="160.50" cy="268.50" r="4.50"/>\n    <circle cx="172.50" cy="268.50" r="4.50"/>\n    <circle cx="184.50" cy="268.50" r="4.50"/>\n    <circle cx="196.50" cy="268.50" r="4.50"/>\n    <circle cx="256.50" cy="268.50" r="4.50"/>\n    <circle cx="268.50" cy="268.50" r="4.50"/>\n    <circle cx="280.50" cy="268.50" r="4.50"/>\n    <circle cx="292.50" cy="268.50" r="4.50"/>\n    <circle cx="304.50" cy="268.50" r="4.50"/>\n    <circle cx="52.50" cy="280.50" r="4.50"/>\n    <circle cx="64.50" cy="280.50" r="4.50"/>\n    <circle cx="76.50" cy="280.50" r="4.50"/>\n    <circle cx="88.50" cy="280.50" r="4.50"/>\n    <circle cx="100.50" cy="280.50" r="4.50"/>\n    <circle cx="160.50" cy="280.50" r="4.50"/>\n    <circle cx="172.50" cy="280.50" r="4.50"/>\n    <circle cx="184.50" cy="280.50" r="4.50"/>\n    <circle cx="196.50" cy="280.50" r="4.50"/>\n    <circle cx="208.50" cy="280.50" r="4.50"/>\n    <circle cx="256.50" cy="280.50" r="4.50"/>\n    <circle cx="268.50" cy="280.50" r="4.50"/>\n    <circle cx="280.50" cy="280.50" r="4.50"/>\n    <circle cx="292.50" cy="280.50" r="4.50"/>\n    <circle cx="304.50" cy="280.50" r="4.50"/>\n    <circle cx="52.50" cy="292.50" r="4.50"/>\n    <circle cx="64.50" cy="292.50" r="4.50"/>\n    <circle cx="76.50" cy="292.50" r="4.50"/>\n    <circle cx="88.50" cy="292.50" r="4.50"/>\n    <circle cx="100.50" cy="292.50" r="4.50"/>\n    <circle cx="160.50" cy="292.50" r="4.50"/>\n    <circle cx="172.50" cy="292.50" r="4.50"/>\n    <circle cx="184.50" cy="292.50" r="4.50"/>\n    <circle cx="196.50" cy="292.50" r="4.50"/>\n    <circle cx="208.50" cy="292.50" r="4.50"/>\n    <circle cx="220.50" cy="292.50" r="4.50"/>\n    <circle cx="232.50" cy="292.50" r="4.50"/>\n    <circle cx="244.50" cy="292.50" r="4.50"/>\n    <circle cx="256.50" cy="292.50" r="4.50"/>\n    <circle cx="268.50" cy="292.50" r="4.50"/>\n    <circle cx="280.50" cy="292.50" r="4.50"/>\n    <circle cx="292.50" cy="292.50" r="4.50"/>\n    <circle cx="304.50" cy="292.50" r="4.50"/>\n    <circle cx="52.50" cy="304.50" r="4.50"/>\n    <circle cx="64.50" cy="304.50" r="4.50"/>\n    <circle cx="76.50" cy="304.50" r="4.50"/>\n    <circle cx="88.50" cy="304.50" r="4.50"/>\n    <circle cx="100.50" cy="304.50" r="4.50"/>\n    <circle cx="160.50" cy="304.50" r="4.50"/>\n    <circle cx="172.50" cy="304.50" r="4.50"/>\n    <circle cx="184.50" cy="304.50" r="4.50"/>\n    <circle cx="196.50" cy="304.50" r="4.50"/>\n    <circle cx="208.50" cy="304.50" r="4.50"/>\n    <circle cx="220.50" cy="304.50" r="4.50"/>\n    <circle cx="232.50" cy="304.50" r="4.50"/>\n    <circle cx="256.50" cy="304.50" r="4.50"/>\n    <circle cx="268.50" cy="304.50" r="4.50"/>\n    <circle cx="280.50" cy="304.50" r="4.50"/>\n    <circle cx="292.50" cy="304.50" r="4.50"/>\n    <circle cx="304.50" cy="304.50" r="4.50"/>\n    <circle cx="316.50" cy="304.50" r="4.50"/>\n    <circle cx="328.50" cy="304.50" r="4.50"/>\n    <circle cx="28.50" cy="316.50" r="4.50"/>\n    <circle cx="40.50" cy="316.50" r="4.50"/>\n    <circle cx="52.50" cy="316.50" r="4.50"/>\n    <circle cx="64.50" cy="316.50" r="4.50"/>\n    <circle cx="76.50" cy="316.50" r="4.50"/>\n    <circle cx="88.50" cy="316.50" r="4.50"/>\n    <circle cx="100.50" cy="316.50" r="4.50"/>\n    <circle cx="112.50" cy="316.50" r="4.50"/>\n    <circle cx="124.50" cy="316.50" r="4.50"/>\n    <circle cx="172.50" cy="316.50" r="4.50"/>\n    <circle cx="184.50" cy="316.50" r="4.50"/>\n    <circle cx="196.50" cy="316.50" r="4.50"/>\n    <circle cx="208.50" cy="316.50" r="4.50"/>\n    <circle cx="220.50" cy="316.50" r="4.50"/>\n    <circle cx="268.50" cy="316.50" r="4.50"/>\n    <circle cx="280.50" cy="316.50" r="4.50"/>\n    <circle cx="292.50" cy="316.50" r="4.50"/>\n    <circle cx="304.50" cy="316.50" r="4.50"/>\n    <circle cx="316.50" cy="316.50" r="4.50"/>\n  </g>\n</svg>\n',
+  fx: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="166.241 0 155.861 155.75" fill="currentColor"><path d="M237.892 0C243.178 8.73262e-05 249.383 1.41857 253.025 3.07422L255.093 4.01367L250.076 18.6299L247.677 17.7461C244.901 16.7234 241.938 15.7998 238.491 15.7998C234.984 15.7998 232.787 16.5601 231.08 18.3213C229.231 20.2297 227.629 23.6395 226.229 29.7578L226.227 29.7617L226.228 29.7627L225.136 34.8506H241.669L260.432 34.9502L260.694 34.9512L260.842 35.1689L278.854 61.6328L296.736 34.9502H320.866L291.676 76.7402L322.102 119.75H299.331L299.182 119.546L241.144 40.4775L239.35 49.4004H222.069L205.688 127.208C203.927 135.709 201.185 142.838 196.777 147.866C192.27 153.008 186.201 155.75 178.342 155.75C174.181 155.75 170.746 155.109 167.909 154.107L166.241 153.519V137.182L166.899 137.4L169.531 138.278C172.182 139.162 174.414 139.8 177.142 139.8C178.528 139.8 179.703 139.526 180.732 138.98C181.764 138.434 182.677 137.6 183.52 136.442C185.304 133.989 186.716 130.135 187.897 124.672L203.76 49.4004H189.874L191.759 39.4375L192.039 39.3457L206.818 34.4668L208.154 28.6416C210.516 18.2065 213.772 10.9381 218.708 6.31836C223.737 1.61217 230.127 3.08752e-05 237.892 0ZM273.987 99.084L260.073 120.25H234.541L261.003 82.0215L273.987 99.084Z"/></svg>',
   gemini:
     '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24">\n  <path fill="currentColor" d="M11.04 19.32Q12 21.51 12 24q0-2.49.93-4.68.96-2.19 2.58-3.81t3.81-2.55Q21.51 12 24 12q-2.49 0-4.68-.93a12.3 12.3 0 0 1-3.81-2.58 12.3 12.3 0 0 1-2.58-3.81Q12 2.49 12 0q0 2.49-.96 4.68-.93 2.19-2.55 3.81a12.3 12.3 0 0 1-3.81 2.58Q2.49 12 0 12q2.49 0 4.68.96 2.19.93 3.81 2.55t2.55 3.81"/>\n</svg>\n',
   "github-copilot-cli":
diff --git a/packages/app/src/assistant-file-links/path-open.test.ts b/packages/app/src/assistant-file-links/path-open.test.ts
index a85d4c8ec0..f54ee88765 100644
--- a/packages/app/src/assistant-file-links/path-open.test.ts
+++ b/packages/app/src/assistant-file-links/path-open.test.ts
@@ -64,7 +64,10 @@ it("ignores an older probe after a newer file link opens", async () => {
   const opened: string[] = [];
   const opener = createInlinePathOpener({
     workspaceRoot: "/repo",
-    client: { listDirectory: () => pendingProbe },
+    client: {
+      listDirectory: () => pendingProbe,
+      getDirectorySuggestions: async () => ({ entries: [], error: null }),
+    },
     openFile: (location) => {
       opened.push(location.path);
     },
@@ -91,7 +94,10 @@ it("ignores a pending probe when its view is left", async () => {
   const opened: string[] = [];
   const opener = createInlinePathOpener({
     workspaceRoot: "/repo",
-    client: { listDirectory: () => pendingProbe },
+    client: {
+      listDirectory: () => pendingProbe,
+      getDirectorySuggestions: async () => ({ entries: [], error: null }),
+    },
     openFile: (location) => {
       opened.push(location.path);
     },
@@ -130,3 +136,45 @@ it("sends folders outside the workspace away from the workspace Files panel", as
   expect(outsideFolders).toEqual(["~/Downloads/contracts", "/tmp/reports"]);
   expect(workspaceFolders).toEqual(["docs"]);
 });
+
+it("keeps a later selection when an earlier nested-file lookup finishes last", async () => {
+  const { createInlinePathOpener } = await import("./path-open");
+  const lookup = Promise.withResolvers<{
+    entries: Array<{ path: string; kind: "file" }>;
+    error: null;
+  }>();
+  const queries: string[] = [];
+  const opened: string[] = [];
+  const opener = createInlinePathOpener({
+    workspaceRoot: "/repo",
+    resolveRelativeFiles: true,
+    client: {
+      listDirectory: async () => {
+        throw new Error("Not a directory");
+      },
+      getDirectorySuggestions: async ({ query }: { query: string }) => {
+        queries.push(query);
+        return lookup.promise;
+      },
+    },
+    openFile: (location) => {
+      opened.push(location.path);
+    },
+    openDirectory: (directory) => {
+      opened.push(directory);
+    },
+    openOutsideDirectory: (directory) => {
+      opened.push(directory);
+    },
+  });
+  const earlier = opener.open(
+    { raw: "schema/x.md:2", path: "/repo/schema/x.md", lineStart: 2 },
+    "side",
+  );
+  await Promise.resolve();
+  expect(queries).toEqual(["schema/x.md"]);
+  await opener.open({ raw: "./guide.md:2", path: "/repo/guide.md", lineStart: 2 }, "side");
+  lookup.resolve({ entries: [{ path: "repo-a/schema/x.md", kind: "file" }], error: null });
+  await earlier;
+  expect(opened).toEqual(["guide.md"]);
+});
diff --git a/packages/app/src/assistant-file-links/path-open.ts b/packages/app/src/assistant-file-links/path-open.ts
index 7c9cf228f4..7ff50c9a1a 100644
--- a/packages/app/src/assistant-file-links/path-open.ts
+++ b/packages/app/src/assistant-file-links/path-open.ts
@@ -5,6 +5,7 @@ import {
   type OpenFileDisposition,
 } from "@/workspace/file-open";
 import { isAbsolutePath } from "@/utils/path";
+import { resolveMissingNestedRelativeFile, type GetDirectorySuggestions } from "./resolver";
 
 interface PathOpenInput {
   file?: string;
@@ -50,7 +51,11 @@ export async function resolveInlinePathOpen(input: PathOpenInput): Promise<PathO
 
 export function createInlinePathOpener(input: {
   workspaceRoot: string;
-  client: PathOpenInput["client"];
+  client: {
+    listDirectory(root: string, path: string): Promise<unknown>;
+    getDirectorySuggestions: GetDirectorySuggestions;
+  } | null;
+  resolveRelativeFiles?: boolean;
   openFile: (location: WorkspaceFileLocation, disposition: OpenFileDisposition) => void;
   openDirectory: (path: string) => void;
   openOutsideDirectory: (path: string) => void;
@@ -73,10 +78,21 @@ export function createInlinePathOpener(input: {
       } else if (destination.kind === "outsideDirectory") {
         input.openOutsideDirectory(destination.directoryPath);
       } else if (normalized.file) {
+        const resolvedTarget =
+          input.resolveRelativeFiles && input.client
+            ? await resolveMissingNestedRelativeFile({
+                target,
+                workspaceRoot: input.workspaceRoot,
+                getDirectorySuggestions: input.client.getDirectorySuggestions.bind(input.client),
+              })
+            : target;
+        if (ownGeneration !== generation) return;
+        const resolved = normalizeInlinePathTarget(resolvedTarget.path, input.workspaceRoot);
+        if (!resolved?.file) return;
         const location = normalizeWorkspaceFileLocation({
-          path: normalized.file,
-          lineStart: target.lineStart,
-          lineEnd: target.lineEnd,
+          path: resolved.file,
+          lineStart: resolvedTarget.lineStart,
+          lineEnd: resolvedTarget.lineEnd,
         });
         if (location) input.openFile(location, disposition);
       }
diff --git a/packages/app/src/assistant-file-links/resolver.test.ts b/packages/app/src/assistant-file-links/resolver.test.ts
index 121c60f5a0..dc38c24c68 100644
--- a/packages/app/src/assistant-file-links/resolver.test.ts
+++ b/packages/app/src/assistant-file-links/resolver.test.ts
@@ -7,6 +7,7 @@ import {
   classifyForResolution,
   fetchDaemonResolution,
   getAssistantFileLinkToken,
+  resolveMissingNestedRelativeFile,
   UnresolvedFileLinkError,
   type AssistantFileLinkContext,
   type DirectorySuggestionEntry,
@@ -424,6 +425,174 @@ describe("fetchDaemonResolution", () => {
   });
 });
 
+describe("resolveMissingNestedRelativeFile", () => {
+  const target = {
+    raw: "schema/x.md:12-14",
+    path: "/Users/test/project/schema/x.md",
+    lineStart: 12,
+    lineEnd: 14,
+  };
+
+  it("opens a nested-repo suffix when the workspace-root path is missing", async () => {
+    const { getDirectorySuggestions, searches } = suggestionsFromMap({
+      "schema/x.md": [{ path: "repo-a/schema/x.md", kind: "file" }],
+    });
+
+    const result = await resolveMissingNestedRelativeFile({
+      target,
+      workspaceRoot: "/Users/test/project",
+      getDirectorySuggestions,
+    });
+
+    expect(searches).toEqual([
+      {
+        query: "schema/x.md",
+        cwd: "/Users/test/project",
+        matchMode: "suffix",
+        limit: 1,
+      },
+    ]);
+    expect(result).toEqual({
+      ...target,
+      path: "/Users/test/project/repo-a/schema/x.md",
+    });
+  });
+
+  it("keeps the exact workspace path when suggestions return that relative path", async () => {
+    const { getDirectorySuggestions } = suggestionsFromMap({
+      "schema/x.md": [{ path: "schema/x.md", kind: "file" }],
+    });
+
+    const result = await resolveMissingNestedRelativeFile({
+      target,
+      workspaceRoot: "/Users/test/project",
+      getDirectorySuggestions,
+    });
+
+    expect(result).toEqual(target);
+  });
+
+  it("keeps the original target when suggestions are empty", async () => {
+    const { getDirectorySuggestions } = suggestionsFromMap({});
+
+    await expect(
+      resolveMissingNestedRelativeFile({
+        target,
+        workspaceRoot: "/Users/test/project",
+        getDirectorySuggestions,
+      }),
+    ).resolves.toEqual(target);
+  });
+
+  it("keeps the original target when the daemon throws", async () => {
+    await expect(
+      resolveMissingNestedRelativeFile({
+        target,
+        workspaceRoot: "/Users/test/project",
+        getDirectorySuggestions: unavailableSuggestions,
+      }),
+    ).resolves.toEqual(target);
+  });
+
+  it.each([
+    ["a bare filename", { ...target, path: "/Users/test/project/file.ts" }],
+    ["a path outside the workspace", { ...target, path: "/tmp/schema/x.md" }],
+    ["a home-relative path", { ...target, path: "~/schema/x.md" }],
+  ])("does not search %s", async (_label, candidate) => {
+    const { getDirectorySuggestions, searches } = suggestionsFromMap({
+      "schema/x.md": [{ path: "repo-a/schema/x.md", kind: "file" }],
+    });
+
+    const result = await resolveMissingNestedRelativeFile({
+      target: candidate,
+      workspaceRoot: "/Users/test/project",
+      getDirectorySuggestions,
+    });
+
+    expect(searches).toEqual([]);
+    expect(result).toEqual(candidate);
+  });
+
+  it("does not search when the workspace root is blank", async () => {
+    const { getDirectorySuggestions, searches } = suggestionsFromMap({});
+
+    const result = await resolveMissingNestedRelativeFile({
+      target,
+      workspaceRoot: "   ",
+      getDirectorySuggestions,
+    });
+
+    expect(searches).toEqual([]);
+    expect(result).toEqual(target);
+  });
+
+  it.each([
+    ["/Users/test/project/schema/x.md", "/Users/test/project"],
+    ["file:///Users/test/project/schema/x.md", "/Users/test/project"],
+    ["C:/repo/schema/x.md", "C:/repo"],
+    ["\\\\server\\share\\schema\\x.md", "//server/share"],
+  ])("keeps absolute destination %s", async (raw, workspaceRoot) => {
+    const { getDirectorySuggestions, searches } = suggestionsFromMap({
+      "schema/x.md": [{ path: "repo-a/schema/x.md", kind: "file" }],
+    });
+    const absoluteTarget = { raw, path: `${workspaceRoot}/schema/x.md` };
+    await expect(
+      resolveMissingNestedRelativeFile({
+        target: absoluteTarget,
+        workspaceRoot,
+        getDirectorySuggestions,
+      }),
+    ).resolves.toEqual(absoluteTarget);
+    expect(searches).toEqual([]);
+  });
+
+  it.each(["docs/guides", "./docs/guides", "docs/guides/"])(
+    "keeps folder href %s direct",
+    async (raw) => {
+      const { getDirectorySuggestions, searches } = suggestionsFromMap({
+        "docs/guides": [{ path: "repo-a/docs/guides", kind: "file" }],
+      });
+      const folderTarget = { raw, path: "/Users/test/project/docs/guides" };
+      await expect(
+        resolveMissingNestedRelativeFile({
+          target: folderTarget,
+          workspaceRoot: "/Users/test/project",
+          getDirectorySuggestions,
+        }),
+      ).resolves.toEqual(folderTarget);
+      expect(searches).toEqual([]);
+    },
+  );
+
+  it("normalizes a Windows workspace root before the suffix lookup", async () => {
+    const windowsTarget = {
+      raw: "schema/x.md",
+      path: "C:\\repo\\schema\\x.md",
+      lineStart: undefined,
+      lineEnd: undefined,
+    };
+    const { getDirectorySuggestions, searches } = suggestionsFromMap({
+      "schema/x.md": [{ path: "repo-a/schema/x.md", kind: "file" }],
+    });
+
+    const result = await resolveMissingNestedRelativeFile({
+      target: windowsTarget,
+      workspaceRoot: "C:\\repo\\",
+      getDirectorySuggestions,
+    });
+
+    expect(searches).toEqual([
+      {
+        query: "schema/x.md",
+        cwd: "C:\\repo\\",
+        matchMode: "suffix",
+        limit: 1,
+      },
+    ]);
+    expect(result.path).toBe("C:/repo/repo-a/schema/x.md");
+  });
+});
+
 describe("getAssistantFileLinkToken", () => {
   it("uses rendered text for markdown-it linkified tokens and href for explicit links", () => {
     expect(
diff --git a/packages/app/src/assistant-file-links/resolver.ts b/packages/app/src/assistant-file-links/resolver.ts
index 66c4137e2d..f77800b75b 100644
--- a/packages/app/src/assistant-file-links/resolver.ts
+++ b/packages/app/src/assistant-file-links/resolver.ts
@@ -5,6 +5,7 @@ import {
   type InlinePathTarget,
 } from "./parse";
 import { i18n } from "@/i18n/i18next";
+import { isAbsolutePath } from "@/utils/path";
 
 export interface AssistantFileLinkSource {
   href: string;
@@ -105,6 +106,62 @@ export async function fetchDaemonResolution({
   };
 }
 
+/** Only file-looking paths nested inside the workspace need suffix search. */
+function nestedRelativeLookupQuery(
+  targetPath: string,
+  workspaceRoot: string | undefined,
+): string | null {
+  const root = workspaceRoot?.trim();
+  if (!root) {
+    return null;
+  }
+  const normalizedRoot = root.replace(/\\/g, "/").replace(/\/+$/, "");
+  const normalizedPath = targetPath.replace(/\\/g, "/");
+  const prefix = `${normalizedRoot}/`;
+  if (!normalizedPath.startsWith(prefix)) {
+    return null;
+  }
+  const relative = normalizedPath.slice(prefix.length);
+  if (!relative.includes("/") || !isFileLookingAssistantToken(encodeURI(relative))) {
+    return null;
+  }
+  return relative;
+}
+
+/** When a markdown link points at workspaceRoot/schema/x.md and that file is
+ * missing, ask the same suffix lookup bare names already use. An exact hit
+ * stays on that path. A suffix hit such as repo-a/schema/x.md replaces it.
+ * Lookup failure keeps the original target.
+ */
+export async function resolveMissingNestedRelativeFile(input: {
+  target: InlinePathTarget;
+  workspaceRoot?: string;
+  getDirectorySuggestions: GetDirectorySuggestions;
+}): Promise<InlinePathTarget> {
+  if (
+    isAbsoluteInlineCodeToken(input.target.raw) ||
+    input.target.raw.startsWith("~/") ||
+    input.target.raw.endsWith("/")
+  ) {
+    return input.target;
+  }
+  const query = nestedRelativeLookupQuery(input.target.path, input.workspaceRoot);
+  if (!query) {
+    return input.target;
+  }
+  try {
+    return await fetchDaemonResolution({
+      ambiguousQuery: query,
+      token: input.target.raw,
+      target: input.target,
+      workspaceRoot: input.workspaceRoot,
+      getDirectorySuggestions: input.getDirectorySuggestions,
+    });
+  } catch {
+    return input.target;
+  }
+}
+
 export function classifyForResolution(
   source: AssistantFileLinkSource,
   context: AssistantFileLinkContext,
@@ -215,11 +272,7 @@ export function shouldResolveDirectFileThroughSuggestions(input: {
 }
 
 function isAbsoluteInlineCodeToken(token: string): boolean {
-  return (
-    token.startsWith("/") ||
-    token.toLowerCase().startsWith("file://") ||
-    /^[A-Za-z]:[\\/]/.test(token)
-  );
+  return isAbsolutePath(token) || token.toLowerCase().startsWith("file://");
 }
 
 function isLinkifiedSource(source: AssistantFileLinkSource): boolean {
diff --git a/packages/app/src/background-work/host.test.ts b/packages/app/src/background-work/host.test.ts
new file mode 100644
index 0000000000..9142f56df4
--- /dev/null
+++ b/packages/app/src/background-work/host.test.ts
@@ -0,0 +1,97 @@
+import { expect, test } from "vitest";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { createHostBackgroundWorkModel } from "./host";
+
+test("retries a failed observation and receives subsequent updates", async () => {
+  interface Observer {
+    snapshot(): void;
+    update(message: SessionOutboundMessage): void;
+    error(error: unknown): void;
+  }
+  const observers: Observer[] = [];
+  let releases = 0;
+  const item = {
+    id: "shell",
+    kind: "shell",
+    description: "sleep",
+    startedAt: "2026-01-01T00:00:00Z",
+  };
+  const client = {
+    getLastServerInfoMessage: () => ({ features: { agentBackgroundWork: true } }),
+    stopAgentBackgroundWork: async () => {},
+    listAgentBackgroundWork: async () => [item],
+    observeAgentBackgroundWork: () => ({
+      subscribe: (observer: Observer) => {
+        observers.push(observer);
+      },
+      release: async () => {
+        releases++;
+      },
+    }),
+  };
+  const model = createHostBackgroundWorkModel("host", "agent", {
+    getClient: () => client,
+    subscribe: () => () => {},
+  });
+  const unsubscribe = model.subscribe(() => {});
+  observers[0].snapshot();
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [item] });
+  observers[0].error(new Error("subscription failed"));
+  expect(model.getSnapshot()).toEqual({ status: "error", items: [item] });
+  model.retry();
+  expect(observers).toHaveLength(2);
+  expect(releases).toBe(1);
+  observers[1].snapshot();
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [item] });
+  observers[0].error(new Error("late error"));
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [item] });
+  observers[1].update({
+    type: "agent.background_work.update",
+    payload: { agentId: "agent", items: [] },
+  });
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [] });
+  unsubscribe();
+});
+
+test("starts observing after the same client reconnects", async () => {
+  let connected = false;
+  let notify = () => {};
+  let snapshot = () => {};
+  const item = {
+    id: "shell",
+    kind: "shell",
+    description: "sleep",
+    startedAt: "2026-01-01T00:00:00Z",
+  };
+  const client = {
+    getLastServerInfoMessage: () =>
+      connected ? { features: { agentBackgroundWork: true } } : null,
+    stopAgentBackgroundWork: async () => {},
+    listAgentBackgroundWork: async () => [item],
+    observeAgentBackgroundWork: () => ({
+      subscribe: (observer: { snapshot(): void }) => {
+        snapshot = observer.snapshot;
+      },
+      release: async () => {},
+    }),
+  };
+  const model = createHostBackgroundWorkModel("host", "agent", {
+    getClient: () => client,
+    subscribe: (listener) => {
+      notify = listener;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  connected = true;
+  notify();
+  snapshot();
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [item] });
+  unsubscribe();
+});
diff --git a/packages/app/src/background-work/host.ts b/packages/app/src/background-work/host.ts
new file mode 100644
index 0000000000..00134f18f0
--- /dev/null
+++ b/packages/app/src/background-work/host.ts
@@ -0,0 +1,115 @@
+import type { PaseoAgentBackgroundWorkItem } from "@getpaseo/client";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { createBackgroundWorkModel } from "./model";
+
+interface BackgroundWorkClient {
+  getLastServerInfoMessage(): {
+    features?: { agentBackgroundWork?: boolean; agentBackgroundWorkStop?: boolean } | null;
+  } | null;
+  stopAgentBackgroundWork(agentId: string, item: PaseoAgentBackgroundWorkItem): Promise<void>;
+  listAgentBackgroundWork(agentId: string): Promise<PaseoAgentBackgroundWorkItem[]>;
+  observeAgentBackgroundWork(): {
+    subscribe(observer: {
+      snapshot(): void;
+      update(message: SessionOutboundMessage): void;
+      error(error: unknown): void;
+    }): unknown;
+    release(): Promise<void>;
+  };
+}
+
+interface BackgroundWorkHost {
+  getClient(): BackgroundWorkClient | null;
+  subscribe(listener: () => void): () => void;
+}
+
+function hostFor(serverId: string): BackgroundWorkHost {
+  const host = getHostRuntimeStore();
+  return {
+    getClient: () => host.getSnapshot(serverId)?.client ?? null,
+    subscribe: (listener) => host.subscribe(serverId, listener),
+  };
+}
+
+export function createHostBackgroundWorkModel(
+  serverId: string,
+  agentId: string,
+  host: BackgroundWorkHost = hostFor(serverId),
+) {
+  let client: BackgroundWorkClient | null = null;
+  const controls = (items: PaseoAgentBackgroundWorkItem[]) => {
+    // COMPAT(agentBackgroundWorkStop): added after v0.15.0, remove after 2027-05-03.
+    if (client?.getLastServerInfoMessage()?.features?.agentBackgroundWorkStop === true)
+      return items;
+    return items.map(({ canStop: _canStop, stopToken: _stopToken, ...item }) => item);
+  };
+  return createBackgroundWorkModel({
+    stop: (item) => {
+      if (!client) return Promise.reject(new Error("Host disconnected"));
+      return client.stopAgentBackgroundWork(agentId, item);
+    },
+    list: () => {
+      if (!client) return Promise.reject(new Error("Host disconnected"));
+      return client.listAgentBackgroundWork(agentId).then(controls);
+    },
+    observe: ({ snapshot, update, disconnected, failed }) => {
+      let release: (() => void) | undefined;
+      let currentObservation:
+        | ReturnType<BackgroundWorkClient["observeAgentBackgroundWork"]>
+        | undefined;
+      const sync = () => {
+        const candidate = host.getClient();
+        // The runtime keeps the client across reconnects, but clears server info until handshake.
+        const next = candidate?.getLastServerInfoMessage() ? candidate : null;
+        if (next === client) return;
+        const previousRelease = release;
+        client = next;
+        release = undefined;
+        disconnected();
+        previousRelease?.();
+        if (!client) return;
+        // COMPAT(agentBackgroundWork): added after v0.11.0-beta.5, remove gate after 2027-04-06.
+        if (client.getLastServerInfoMessage()?.features?.agentBackgroundWork !== true) {
+          failed();
+          return;
+        }
+        const observedClient = client;
+        const observation = client.observeAgentBackgroundWork();
+        currentObservation = observation;
+        observation.subscribe({
+          snapshot: () => {
+            if (client === observedClient && currentObservation === observation) snapshot();
+          },
+          update: (message) => {
+            if (
+              client === observedClient &&
+              currentObservation === observation &&
+              message.type === "agent.background_work.update" &&
+              message.payload.agentId === agentId
+            )
+              update(controls(message.payload.items));
+          },
+          error: () => {
+            if (client === observedClient && currentObservation === observation) failed();
+          },
+        });
+        release = () => {
+          if (currentObservation === observation) currentObservation = undefined;
+          void observation
+            .release()
+            .catch((error: unknown) =>
+              console.error("Background work subscription cleanup failed", error),
+            );
+        };
+      };
+      const unsubscribe = host.subscribe(sync);
+      sync();
+      return () => {
+        unsubscribe();
+        client = null;
+        release?.();
+      };
+    },
+  });
+}
diff --git a/packages/app/src/background-work/index.tsx b/packages/app/src/background-work/index.tsx
new file mode 100644
index 0000000000..34dfbb83ff
--- /dev/null
+++ b/packages/app/src/background-work/index.tsx
@@ -0,0 +1,155 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { Text, View } from "react-native";
+import { useTranslation } from "react-i18next";
+import { StyleSheet } from "react-native-unistyles";
+import { ComposerTrackPill, ComposerTrackRow } from "@/composer/tracks";
+import { LiveElapsed } from "@/components/message";
+import { Button } from "@/components/ui/button";
+import type { PaseoAgentBackgroundWorkItem } from "@getpaseo/client";
+import { createHostBackgroundWorkModel } from "./host";
+import { backgroundWorkText } from "./presentation";
+export { createHostBackgroundWorkModel } from "./host";
+
+function kindKey(kind: string): "shell" | "monitor" | "other" {
+  if (kind === "shell" || kind === "monitor") return kind;
+  return "other";
+}
+
+export function BackgroundWorkTrack({
+  model,
+  count,
+}: {
+  model: ReturnType<typeof createHostBackgroundWorkModel>;
+  count: number;
+}) {
+  const { t } = useTranslation();
+  const { items, status, stops } = useSyncExternalStore(
+    model.subscribe,
+    model.getSnapshot,
+    model.getSnapshot,
+  );
+  const missing = Object.values(stops ?? {}).filter(
+    (entry) => !items?.some((item) => item.stopToken === entry.item.stopToken),
+  );
+  const rows = [...(items ?? []), ...missing.map((entry) => entry.item)];
+  if (count === 0 && rows.length === 0) return null;
+  const visibleCount = items?.length || count;
+  return (
+    <ComposerTrackPill
+      testID="background-work"
+      panelTitle={t("message.backgroundWork.title")}
+      segments={[
+        {
+          bucket: "running",
+          text:
+            visibleCount === 1
+              ? t("message.backgroundWork.pillOne")
+              : t("message.backgroundWork.pillMany", { count: visibleCount }),
+        },
+      ]}
+    >
+      {status === "loading" || status === "stale" ? (
+        <ComposerTrackRow>
+          <Text style={styles.facts}>{t("message.backgroundWork.waiting")}</Text>
+        </ComposerTrackRow>
+      ) : null}
+      {status === "error" ? (
+        <>
+          <ComposerTrackRow>
+            <Text style={styles.facts}>{t("message.backgroundWork.error")}</Text>
+          </ComposerTrackRow>
+          <ComposerTrackRow
+            onPress={model.retry}
+            closeOnSelect={false}
+            accessibilityLabel={t("message.backgroundWork.retry")}
+          >
+            <Text style={styles.title}>{t("message.backgroundWork.retry")}</Text>
+          </ComposerTrackRow>
+        </>
+      ) : null}
+      {rows.map((item) => (
+        <BackgroundWorkRow
+          key={item.stopToken ?? item.id}
+          item={item}
+          model={model}
+          live={Boolean(items?.some((entry) => entry.stopToken === item.stopToken))}
+          ready={status === "ready"}
+          stopStatus={stops?.[item.stopToken ?? ""]?.status}
+        />
+      ))}
+    </ComposerTrackPill>
+  );
+}
+
+function BackgroundWorkRow({
+  item,
+  model,
+  live,
+  ready,
+  stopStatus,
+}: {
+  item: PaseoAgentBackgroundWorkItem;
+  model: ReturnType<typeof createHostBackgroundWorkModel>;
+  live: boolean;
+  ready: boolean;
+  stopStatus?: "pending" | "error";
+}) {
+  const { t } = useTranslation();
+  const kind = t(`message.backgroundWork.${kindKey(item.kind)}`);
+  const stop = useCallback(() => {
+    void model.stopItem(item);
+  }, [model, item]);
+  const dismiss = useCallback(
+    () => model.dismissStop(item.stopToken ?? ""),
+    [model, item.stopToken],
+  );
+  let detail = t("message.backgroundWork.notRunning");
+  if (stopStatus === "pending") detail = t("message.backgroundWork.stopping");
+  const { title, command } = backgroundWorkText(item, kind);
+  const action = item.canStop && ready && live;
+  const label =
+    stopStatus === "pending"
+      ? t("message.backgroundWork.stopping")
+      : t("message.backgroundWork.stop");
+  return (
+    <ComposerTrackRow>
+      <View style={styles.row}>
+        <Text style={styles.title}>{title}</Text>
+        {command ? <Text style={styles.facts}>{command}</Text> : null}
+        <Text style={styles.facts}>
+          {kind} ·{" "}
+          {live ? (
+            <LiveElapsed startedAt={new Date(item.startedAt)} active style={styles.facts} />
+          ) : (
+            detail
+          )}
+        </Text>
+        {stopStatus === "error" ? (
+          <Text style={styles.facts}>{t("message.backgroundWork.stopError")}</Text>
+        ) : null}
+      </View>
+      {action ? (
+        <Button
+          variant="ghost"
+          size="sm"
+          accessibilityLabel={`${t("message.backgroundWork.stop")} ${title}`}
+          disabled={stopStatus === "pending"}
+          onPress={stop}
+        >
+          {label}
+        </Button>
+      ) : null}
+      {!live && stopStatus === "error" ? (
+        <Button variant="ghost" size="sm" onPress={dismiss}>
+          {t("message.backgroundWork.dismiss")}
+        </Button>
+      ) : null}
+    </ComposerTrackRow>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  row: { flexGrow: 1, flexShrink: 1, flexBasis: "auto", minWidth: 0 },
+  title: { fontSize: theme.fontSize.base, color: theme.colors.foreground },
+  facts: { fontSize: theme.fontSize.sm, color: theme.colors.foregroundMuted },
+}));
diff --git a/packages/app/src/background-work/model.test.ts b/packages/app/src/background-work/model.test.ts
new file mode 100644
index 0000000000..46fcaf8e95
--- /dev/null
+++ b/packages/app/src/background-work/model.test.ts
@@ -0,0 +1,233 @@
+import { expect, test } from "vitest";
+import { createBackgroundWorkModel } from "./model";
+
+test("keeps a newer update when an earlier list resolves after it", async () => {
+  let resolve!: (
+    value: Array<{ id: string; kind: string; description: string | null; startedAt: string }>,
+  ) => void;
+  let update!: (
+    items: Array<{ id: string; kind: string; description: string | null; startedAt: string }>,
+  ) => void;
+  let snapshot!: () => void;
+  const model = createBackgroundWorkModel({
+    list: () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+    observe: (callbacks) => {
+      snapshot = callbacks.snapshot;
+      update = callbacks.update;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  expect(model.getSnapshot().items).toBeNull();
+  snapshot();
+  const item = { id: "1", kind: "shell", description: "sleep", startedAt: "2026-01-01T00:00:00Z" };
+  update([item]);
+  resolve([]);
+  await Promise.resolve();
+  expect(model.getSnapshot().items).toEqual([item]);
+  unsubscribe();
+});
+
+test("retains the last inventory while reconnecting and replaces it after resync", async () => {
+  const item = { id: "1", kind: "shell", description: "sleep", startedAt: "2026-01-01T00:00:00Z" };
+  const reads: Array<(value: (typeof item)[]) => void> = [];
+  let snapshot!: () => void;
+  const model = createBackgroundWorkModel({
+    list: () => new Promise((resolve) => reads.push(resolve)),
+    observe: (callbacks) => {
+      snapshot = callbacks.snapshot;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  snapshot();
+  reads[0]([item]);
+  await Promise.resolve();
+  snapshot();
+  expect(model.getSnapshot().items).toEqual([item]);
+  reads[1]([]);
+  await Promise.resolve();
+  expect(model.getSnapshot().items).toEqual([]);
+  unsubscribe();
+});
+
+test("ignores a list response from a connection that was replaced", async () => {
+  let snapshot!: () => void;
+  let disconnected!: () => void;
+  let resolve!: (
+    items: Array<{ id: string; kind: string; description: string | null; startedAt: string }>,
+  ) => void;
+  const model = createBackgroundWorkModel({
+    list: () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+    observe: (callbacks) => {
+      snapshot = callbacks.snapshot;
+      disconnected = callbacks.disconnected;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  snapshot();
+  disconnected();
+  resolve([{ id: "old", kind: "shell", description: null, startedAt: "2026-01-01T00:00:00Z" }]);
+  await Promise.resolve();
+  expect(model.getSnapshot().items).toBeNull();
+  unsubscribe();
+});
+
+test("retains stale items on failure and retries the inventory", async () => {
+  const item = { id: "1", kind: "shell", description: "sleep", startedAt: "2026-01-01T00:00:00Z" };
+  let snapshot!: () => void;
+  let resolve!: (items: (typeof item)[]) => void;
+  let reject!: (error: Error) => void;
+  const model = createBackgroundWorkModel({
+    list: () =>
+      new Promise((done, fail) => {
+        resolve = done;
+        reject = fail;
+      }),
+    observe: (callbacks) => {
+      snapshot = callbacks.snapshot;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  snapshot();
+  resolve([item]);
+  await Promise.resolve();
+  snapshot();
+  expect(model.getSnapshot()).toEqual({ status: "stale", items: [item] });
+  reject(new Error("offline"));
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "error", items: [item] });
+  model.retry();
+  expect(model.getSnapshot()).toEqual({ status: "stale", items: [item] });
+  resolve([]);
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [] });
+  unsubscribe();
+});
+
+test("reports an initial read failure without claiming an empty inventory", async () => {
+  let snapshot!: () => void;
+  const model = createBackgroundWorkModel({
+    list: async () => {
+      throw new Error("offline");
+    },
+    observe: (callbacks) => {
+      snapshot = callbacks.snapshot;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  snapshot();
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "error", items: null });
+  unsubscribe();
+});
+
+test("recreates a failed observation on retry and resumes live updates", async () => {
+  const item = { id: "1", kind: "shell", description: "sleep", startedAt: "2026-01-01T00:00:00Z" };
+  let observation!: Parameters<Parameters<typeof createBackgroundWorkModel>[0]["observe"]>[0];
+  let starts = 0;
+  let releases = 0;
+  const model = createBackgroundWorkModel({
+    list: async () => [item],
+    observe: (callbacks) => {
+      observation = callbacks;
+      starts++;
+      return () => {
+        releases++;
+      };
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  observation.failed();
+  expect(model.getSnapshot()).toEqual({ status: "error", items: null });
+  model.retry();
+  expect(starts).toBe(2);
+  expect(releases).toBe(1);
+  observation.snapshot();
+  await Promise.resolve();
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [item] });
+  observation.update([]);
+  expect(model.getSnapshot()).toEqual({ status: "ready", items: [] });
+  unsubscribe();
+});
+
+test("keeps a stop pending across a roster removal and exposes a failed outcome", async () => {
+  const item = {
+    id: "1",
+    kind: "shell",
+    description: "sleep",
+    startedAt: "2026-01-01",
+    canStop: true,
+    stopToken: "generation-1",
+  };
+  let update!: (items: (typeof item)[]) => void;
+  let reject!: (error: Error) => void;
+  const model = createBackgroundWorkModel({
+    list: async () => [item],
+    stop: () =>
+      new Promise((_, fail) => {
+        reject = fail;
+      }),
+    observe: (callbacks) => {
+      update = callbacks.update;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  update([item]);
+  const pending = model.stopItem(item);
+  update([]);
+  expect(model.getSnapshot().stops?.["generation-1"]).toEqual({ status: "pending", item });
+  reject(new Error("connection lost"));
+  await pending;
+  expect(model.getSnapshot().stops?.["generation-1"]).toEqual({ status: "error", item });
+  model.dismissStop("generation-1");
+  expect(model.getSnapshot().stops).toEqual({});
+  unsubscribe();
+});
+
+test("ignores a stop response from a disconnected generation", async () => {
+  const first = {
+    id: "1",
+    kind: "shell",
+    description: "old",
+    startedAt: "2026-01-01",
+    canStop: true,
+    stopToken: "first",
+  };
+  const replacement = { ...first, description: "new", stopToken: "second" };
+  let update!: (items: (typeof first)[]) => void;
+  let disconnect!: () => void;
+  let resolve!: () => void;
+  const model = createBackgroundWorkModel({
+    list: async () => [],
+    stop: () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+    observe: (callbacks) => {
+      update = callbacks.update;
+      disconnect = callbacks.disconnected;
+      return () => {};
+    },
+  });
+  const unsubscribe = model.subscribe(() => {});
+  update([first]);
+  const pending = model.stopItem(first);
+  disconnect();
+  update([replacement]);
+  resolve();
+  await pending;
+  expect(model.getSnapshot().items).toEqual([replacement]);
+  expect(model.getSnapshot().stops?.first).toEqual({ status: "error", item: first });
+  unsubscribe();
+});
diff --git a/packages/app/src/background-work/model.ts b/packages/app/src/background-work/model.ts
new file mode 100644
index 0000000000..311abc92e7
--- /dev/null
+++ b/packages/app/src/background-work/model.ts
@@ -0,0 +1,121 @@
+import type { PaseoAgentBackgroundWorkItem as AgentBackgroundWorkItem } from "@getpaseo/client";
+
+interface Port {
+  list(): Promise<AgentBackgroundWorkItem[]>;
+  stop?(item: AgentBackgroundWorkItem): Promise<void>;
+  observe(callbacks: {
+    snapshot(): void;
+    disconnected(): void;
+    failed(): void;
+    update(items: AgentBackgroundWorkItem[]): void;
+  }): () => void;
+}
+
+interface BackgroundWorkState {
+  status: "loading" | "stale" | "ready" | "error";
+  items: AgentBackgroundWorkItem[] | null;
+  stops?: Record<string, { status: "pending" | "error"; item: AgentBackgroundWorkItem }>;
+}
+
+export function createBackgroundWorkModel(port: Port) {
+  let state: BackgroundWorkState = { status: "loading", items: null };
+  let sequence = 0;
+  let stopGeneration = 0;
+  let stop: (() => void) | undefined;
+  let observationFailed = false;
+  const listeners = new Set<() => void>();
+  const publish = (next: BackgroundWorkState) => {
+    state =
+      next.stops === undefined && state.stops === undefined
+        ? next
+        : { ...next, stops: next.stops ?? state.stops };
+    for (const listener of listeners) listener();
+  };
+  const refresh = async () => {
+    const request = ++sequence;
+    publish({ status: state.items === null ? "loading" : "stale", items: state.items });
+    try {
+      const items = await port.list();
+      if (request === sequence) publish({ status: "ready", items });
+    } catch {
+      if (request === sequence) publish({ status: "error", items: state.items });
+    }
+  };
+  const start = () => {
+    observationFailed = false;
+    stop = port.observe({
+      snapshot: () => {
+        void refresh();
+      },
+      disconnected: () => {
+        sequence++;
+        stopGeneration++;
+        const stops =
+          state.stops &&
+          Object.fromEntries(
+            Object.entries(state.stops).map(([id, entry]) => [
+              id,
+              { ...entry, status: "error" as const },
+            ]),
+          );
+        publish({ status: state.items === null ? "loading" : "stale", items: state.items, stops });
+      },
+      failed: () => {
+        observationFailed = true;
+        sequence++;
+        publish({ status: "error", items: state.items });
+      },
+      update: (items) => {
+        sequence++;
+        publish({ status: "ready", items });
+      },
+    });
+  };
+  return {
+    getSnapshot: () => state,
+    dismissStop: (token: string) => {
+      const stops = { ...state.stops };
+      delete stops[token];
+      publish({ ...state, stops });
+    },
+    stopItem: async (item: AgentBackgroundWorkItem) => {
+      const token = item.stopToken;
+      if (!port.stop || !token || state.stops?.[token]?.status === "pending") return;
+      if (!state.items?.some((entry) => entry.stopToken === token)) return;
+      const generation = stopGeneration;
+      publish({ ...state, stops: { ...state.stops, [token]: { status: "pending", item } } });
+      try {
+        await port.stop(item);
+        if (generation !== stopGeneration) return;
+        const stops = { ...state.stops };
+        delete stops[token];
+        publish({ ...state, stops });
+      } catch {
+        if (generation === stopGeneration)
+          publish({ ...state, stops: { ...state.stops, [token]: { status: "error", item } } });
+      }
+    },
+    retry: () => {
+      if (observationFailed) {
+        stop?.();
+        stop = undefined;
+        publish({ status: state.items === null ? "loading" : "stale", items: state.items });
+        start();
+      } else {
+        void refresh();
+      }
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      if (!stop) start();
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size) {
+          sequence++;
+          stop?.();
+          stop = undefined;
+        }
+      };
+    },
+  };
+}
diff --git a/packages/app/src/background-work/presentation.test.ts b/packages/app/src/background-work/presentation.test.ts
new file mode 100644
index 0000000000..738dde76ca
--- /dev/null
+++ b/packages/app/src/background-work/presentation.test.ts
@@ -0,0 +1,20 @@
+import { expect, test } from "vitest";
+import { backgroundWorkText } from "./presentation";
+
+test("shows descriptions and commands once, with useful fallbacks", () => {
+  expect(
+    backgroundWorkText({ description: "Watch build", command: "tail -f build.log" }, "Monitor"),
+  ).toEqual({ title: "Watch build", command: "tail -f build.log" });
+  expect(backgroundWorkText({ description: null, command: "sleep 10" }, "Shell")).toEqual({
+    title: "sleep 10",
+    command: null,
+  });
+  expect(backgroundWorkText({ description: "sleep 10", command: "sleep 10" }, "Shell")).toEqual({
+    title: "sleep 10",
+    command: null,
+  });
+  expect(backgroundWorkText({ description: null }, "Shell")).toEqual({
+    title: "Shell",
+    command: null,
+  });
+});
diff --git a/packages/app/src/background-work/presentation.ts b/packages/app/src/background-work/presentation.ts
new file mode 100644
index 0000000000..4913289501
--- /dev/null
+++ b/packages/app/src/background-work/presentation.ts
@@ -0,0 +1,7 @@
+export function backgroundWorkText(
+  item: { description: string | null; command?: string },
+  kind: string,
+): { title: string; command: string | null } {
+  const title = item.description ?? item.command ?? kind;
+  return { title, command: item.command && item.command !== title ? item.command : null };
+}
diff --git a/packages/app/src/changelog/internal/changelog-sheet.tsx b/packages/app/src/changelog/internal/changelog-sheet.tsx
index 04afdcafb0..fd7bc82450 100644
--- a/packages/app/src/changelog/internal/changelog-sheet.tsx
+++ b/packages/app/src/changelog/internal/changelog-sheet.tsx
@@ -1,4 +1,4 @@
-import { memo, useCallback, useMemo } from "react";
+import { memo, useCallback, useMemo, useState } from "react";
 import { Pressable, Text, View, type PressableStateCallbackType } from "react-native";
 import { ExternalLink, Gift } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
@@ -118,7 +118,7 @@ function ChangelogBody({ state, shownReleases, onShowMore, onRetry }: ChangelogB
           description={t("changelog.error.description")}
           testID="changelog-error"
         >
-          <Button variant="outline" size="sm" onPress={onRetry} testID="changelog-retry">
+          <Button variant="outline" onPress={onRetry} testID="changelog-retry">
             {t("common.actions.retry")}
           </Button>
         </Alert>
@@ -156,9 +156,19 @@ interface ReleaseViewProps {
   isCurrent: boolean;
 }
 
+/**
+ * A release that has highlights shows only them until the reader asks for the
+ * sections, which are the full record. A release without highlights has nothing
+ * to stand in for its sections, so it shows them as it always did.
+ */
 const ReleaseView = memo(function ReleaseView({ release, isCurrent }: ReleaseViewProps) {
   const { t } = useTranslation();
   const date = formatChangelogDate(release.date);
+  const [showingAllChanges, setShowingAllChanges] = useState(false);
+  const toggleAllChanges = useCallback(() => setShowingAllChanges((value) => !value), []);
+  const allChangesState = useMemo(() => ({ expanded: showingAllChanges }), [showingAllChanges]);
+  const hasHighlights = release.highlights.length > 0;
+  const showsSections = !hasHighlights || showingAllChanges;
 
   return (
     <View style={styles.release} testID={`changelog-release-${release.version}`}>
@@ -168,26 +178,40 @@ const ReleaseView = memo(function ReleaseView({ release, isCurrent }: ReleaseVie
         <View style={styles.headingSpacer} />
         {date ? <Text style={styles.date}>{date}</Text> : null}
       </View>
-      {keyChangelogSections(release.sections).map(({ key, section }) => (
-        <View key={key} style={styles.section}>
-          {section.title ? <Text style={styles.sectionTitle}>{section.title}</Text> : null}
-          {section.body ? <MarkdownRenderer text={section.body} compact /> : null}
-        </View>
-      ))}
+      {hasHighlights ? <MarkdownRenderer text={release.highlights} compact /> : null}
+      {hasHighlights && release.sections.length > 0 ? (
+        <Button
+          variant="ghost"
+          style={styles.allChangesToggle}
+          accessibilityState={allChangesState}
+          onPress={toggleAllChanges}
+        >
+          {t(showingAllChanges ? "changelog.hideAllChanges" : "changelog.showAllChanges")}
+        </Button>
+      ) : null}
+      {showsSections ? <ReleaseSections sections={release.sections} /> : null}
     </View>
   );
 });
 
+function ReleaseSections({ sections }: { sections: readonly ChangelogSection[] }) {
+  return keyChangelogSections(sections).map(({ key, section }) => (
+    <View key={key} style={styles.section}>
+      {section.title ? <Text style={styles.sectionTitle}>{section.title}</Text> : null}
+      {section.body ? <MarkdownRenderer text={section.body} compact /> : null}
+    </View>
+  ));
+}
+
 /** A release can repeat a section title; the occurrence keeps the key stable. */
 function keyChangelogSections(
   sections: readonly ChangelogSection[],
 ): { key: string; section: ChangelogSection }[] {
   const seen = new Map<string, number>();
   return sections.map((section) => {
-    const title = section.title ?? "";
-    const occurrence = seen.get(title) ?? 0;
-    seen.set(title, occurrence + 1);
-    return { key: `${title}:${occurrence}`, section };
+    const occurrence = seen.get(section.title) ?? 0;
+    seen.set(section.title, occurrence + 1);
+    return { key: `${section.title}:${occurrence}`, section };
   });
 }
 
@@ -236,6 +260,12 @@ const styles = StyleSheet.create((theme) => ({
     textTransform: "uppercase",
     letterSpacing: 0.5,
   },
+  // Flush with the highlights above it, so the label's ink sits on their rail.
+  allChangesToggle: {
+    alignSelf: "flex-start",
+    paddingHorizontal: 0,
+    borderWidth: 0,
+  },
   showMore: {
     alignSelf: "center",
   },
diff --git a/packages/app/src/changelog/internal/parse-changelog.test.ts b/packages/app/src/changelog/internal/parse-changelog.test.ts
index 958be560ff..7a83f56099 100644
--- a/packages/app/src/changelog/internal/parse-changelog.test.ts
+++ b/packages/app/src/changelog/internal/parse-changelog.test.ts
@@ -8,15 +8,15 @@ import {
   type ChangelogSection,
 } from "./parse-changelog";
 
-function bodies(markdown: string, releaseIndex = 0): string[] {
-  return parseChangelog(markdown)[releaseIndex].sections.map(sectionBody);
+function bodies(markdown: string): string[] {
+  return parseChangelog(markdown)[0].sections.map(sectionBody);
 }
 
 function sectionBody(section: ChangelogSection): string {
   return section.body;
 }
 
-function sectionTitle(section: ChangelogSection): string | null {
+function sectionTitle(section: ChangelogSection): string {
   return section.title;
 }
 
@@ -25,17 +25,36 @@ function releaseDate(release: ChangelogRelease): string {
 }
 
 function authoredLines(release: ChangelogRelease): string[] {
-  return release.sections.flatMap(sectionLines);
+  return [...release.highlights.split("\n"), ...release.sections.flatMap(sectionLines)];
 }
 
 function sectionLines(section: ChangelogSection): string[] {
-  return [...(section.title ? [`### ${section.title}`] : []), ...section.body.split("\n")];
+  return [`### ${section.title}`, ...section.body.split("\n")];
 }
 
 function isNotBlank(line: string): boolean {
   return line.trim().length > 0;
 }
 
+function readRepositoryFile(path: string): string {
+  return readFileSync(fileURLToPath(new URL(`../../../../../${path}`, import.meta.url)), "utf8");
+}
+
+/** The cases the app, the website and the release scripts must all split the same way. */
+interface ChangelogStructureCases {
+  document: string[];
+  releases: {
+    version: string;
+    date: string;
+    highlights: string[];
+    sectionTitles: string[];
+  }[];
+}
+
+const structureCases: ChangelogStructureCases = JSON.parse(
+  readRepositoryFile("scripts/test-support/changelog-structure.json"),
+);
+
 describe("parseChangelog", () => {
   it("reads the shape the changelog is authored in today", () => {
     const releases = parseChangelog(
@@ -44,7 +63,8 @@ describe("parseChangelog", () => {
         "",
         "## 0.8.0-beta.1 - 2026-09-08",
         "",
-        "This release extends what plugins can do.",
+        "- **Plugin providers:** Plugins can add providers.",
+        "- **Faster diffs:** Diffs load sooner.",
         "",
         "### Plugins",
         "",
@@ -67,8 +87,9 @@ describe("parseChangelog", () => {
       {
         version: "0.8.0-beta.1",
         date: "2026-09-08",
+        highlights:
+          "- **Plugin providers:** Plugins can add providers.\n- **Faster diffs:** Diffs load sooner.",
         sections: [
-          { title: null, body: "This release extends what plugins can do." },
           {
             title: "Plugins",
             body: "- Added provider contributions ([#4314](https://example.com/4314))",
@@ -79,6 +100,7 @@ describe("parseChangelog", () => {
       {
         version: "0.7.2",
         date: "2026-09-02",
+        highlights: "",
         sections: [{ title: "Fixed", body: "- Fixed a thing" }],
       },
     ]);
@@ -89,7 +111,7 @@ describe("parseChangelog", () => {
       "# Changelog\n\nAll notable changes.\n\n## 1.0.0 - 2026-01-01\n\n- One\n",
     );
     expect(releases).toHaveLength(1);
-    expect(releases[0].sections).toEqual([{ title: null, body: "- One" }]);
+    expect(releases[0]).toMatchObject({ highlights: "- One", sections: [] });
   });
 
   it("returns nothing for a document with no releases", () => {
@@ -136,13 +158,13 @@ describe("parseChangelog", () => {
     it("does not treat a deeper heading as a release", () => {
       const releases = parseChangelog("## 1.0.0 - 2026-01-01\n\n#### Deep\n\n- One\n");
       expect(releases).toHaveLength(1);
-      expect(releases[0].sections).toEqual([{ title: null, body: "#### Deep\n\n- One" }]);
+      expect(releases[0].highlights).toBe("#### Deep\n\n- One");
     });
 
     it("does not treat an unspaced hash run as a heading", () => {
       const releases = parseChangelog("## 1.0.0 - 2026-01-01\n\n##notaheading\n");
       expect(releases).toHaveLength(1);
-      expect(releases[0].sections[0].body).toBe("##notaheading");
+      expect(releases[0].highlights).toBe("##notaheading");
     });
   });
 
@@ -162,14 +184,34 @@ describe("parseChangelog", () => {
       ]);
     });
 
-    it("drops an empty lead section", () => {
+    it("keeps a bare section heading as an untitled section", () => {
+      const releases = parseChangelog("## 1.0.0 - 2026-01-01\n\n###\n\n- One\n");
+      expect(releases[0].sections).toEqual([{ title: "", body: "- One" }]);
+    });
+  });
+
+  describe("highlights", () => {
+    it("has none when the release opens with a section", () => {
       const releases = parseChangelog("## 1.0.0 - 2026-01-01\n\n### Fixed\n\n- One\n");
-      expect(releases[0].sections).toEqual([{ title: "Fixed", body: "- One" }]);
+      expect(releases[0]).toMatchObject({
+        highlights: "",
+        sections: [{ title: "Fixed", body: "- One" }],
+      });
+    });
+
+    it("reads the summary paragraphs older entries opened with as highlights", () => {
+      const releases = parseChangelog(
+        "## 1.0.0 - 2026-01-01\n\nDaemon restarts keep terminals.\n\nMore here.\n\n### Added\n\n- One\n",
+      );
+      expect(releases[0]).toMatchObject({
+        highlights: "Daemon restarts keep terminals.\n\nMore here.",
+        sections: [{ title: "Added", body: "- One" }],
+      });
     });
 
     it("keeps a release that is only prose", () => {
       const releases = parseChangelog("## 1.0.0 - 2026-01-01\n\nJust a note.\n");
-      expect(releases[0].sections).toEqual([{ title: null, body: "Just a note." }]);
+      expect(releases[0]).toMatchObject({ highlights: "Just a note.", sections: [] });
     });
   });
 
@@ -256,7 +298,12 @@ describe("parseChangelog", () => {
   it("reads CRLF documents", () => {
     const releases = parseChangelog("## 1.0.0 - 2026-01-01\r\n\r\n### Fixed\r\n\r\n- One\r\n");
     expect(releases).toEqual([
-      { version: "1.0.0", date: "2026-01-01", sections: [{ title: "Fixed", body: "- One" }] },
+      {
+        version: "1.0.0",
+        date: "2026-01-01",
+        highlights: "",
+        sections: [{ title: "Fixed", body: "- One" }],
+      },
     ]);
   });
 });
@@ -272,19 +319,45 @@ describe("formatChangelogDate", () => {
   });
 });
 
+describe("the structure every changelog surface shares", () => {
+  for (const lineEnding of ["\n", "\r\n"]) {
+    it(`splits the shared cases with ${JSON.stringify(lineEnding)} line endings`, () => {
+      const releases = parseChangelog(structureCases.document.join(lineEnding));
+
+      expect(
+        releases.map((release) => ({
+          version: release.version,
+          date: release.date,
+          highlights: release.highlights.split("\n").filter(isNotBlank),
+          sectionTitles: release.sections.map(sectionTitle),
+        })),
+      ).toEqual(
+        structureCases.releases.map((release) => ({
+          version: release.version,
+          date: release.date,
+          highlights: release.highlights.filter(isNotBlank),
+          sectionTitles: release.sectionTitles,
+        })),
+      );
+    });
+  }
+});
+
 describe("the repository's own CHANGELOG.md", () => {
-  const markdown = readFileSync(
-    fileURLToPath(new URL("../../../../../CHANGELOG.md", import.meta.url)),
-    "utf8",
-  );
+  const markdown = readRepositoryFile("CHANGELOG.md");
   const releases = parseChangelog(markdown);
 
+  it("finds a release for every release heading line", () => {
+    const headingLines = markdown.split("\n").filter((line) => line.startsWith("## "));
+    expect(releases).toHaveLength(headingLines.length);
+  });
+
   it("parses every release heading", () => {
     expect(releases.length).toBeGreaterThan(50);
     for (const release of releases) {
       expect(release.version).toMatch(/^\d+\.\d+\.\d+/);
       expect(release.date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
-      expect(release.sections.length).toBeGreaterThan(0);
+      expect(release.highlights.length + release.sections.length).toBeGreaterThan(0);
     }
   });
 
diff --git a/packages/app/src/changelog/internal/parse-changelog.ts b/packages/app/src/changelog/internal/parse-changelog.ts
index 693538574f..e91c39f3ae 100644
--- a/packages/app/src/changelog/internal/parse-changelog.ts
+++ b/packages/app/src/changelog/internal/parse-changelog.ts
@@ -3,7 +3,10 @@
  *
  * The document is authored in the repository, fetched at runtime, and rewritten
  * on every release, so this parser commits to exactly two facts: a `##` heading
- * starts a release and a `###` heading starts a section inside it. Everything
+ * starts a release and a `###` heading starts a section inside it. Whatever sits
+ * between the release heading and its first section is the release's
+ * highlights: the list a release now leads with, or the summary paragraphs and
+ * notices older entries opened with. Everything
  * else — prose, callouts, block quotes, fenced code, images, video and embed
  * HTML, tables, nested lists — is carried through verbatim and handed to the
  * Markdown renderer. A new block kind in the changelog therefore needs no
@@ -17,8 +20,8 @@
  */
 
 export interface ChangelogSection {
-  /** The `###` heading text, or null for content that precedes the first one. */
-  title: string | null;
+  /** The `###` heading text. Empty for a bare `###`. */
+  title: string;
   /** Verbatim markdown under the heading. */
   body: string;
 }
@@ -28,7 +31,9 @@ export interface ChangelogRelease {
   version: string;
   /** The heading tail after the version. Empty when the heading carried none. */
   date: string;
-  /** Sections in document order; the untitled lead section comes first. */
+  /** Verbatim markdown before the first section. Empty when the release opens with one. */
+  highlights: string;
+  /** The `###` sections in document order. */
   sections: ChangelogSection[];
 }
 
@@ -46,13 +51,14 @@ const LEADING_V = /^v(?=\d)/i;
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 
 interface SectionDraft {
-  title: string | null;
+  title: string;
   lines: string[];
 }
 
 interface ReleaseDraft {
   version: string;
   date: string;
+  highlights: string[];
   sections: SectionDraft[];
 }
 
@@ -75,7 +81,8 @@ export function parseChangelog(markdown: string): ChangelogRelease[] {
       if (releaseHeading) {
         releases.push({
           ...splitReleaseHeading(releaseHeading[1] ?? ""),
-          sections: [{ title: null, lines: [] }],
+          highlights: [],
+          sections: [],
         });
         continue;
       }
@@ -83,7 +90,7 @@ export function parseChangelog(markdown: string): ChangelogRelease[] {
       const sectionHeading = line.match(SECTION_HEADING);
       if (sectionHeading && releases.length > 0) {
         releases[releases.length - 1].sections.push({
-          title: (sectionHeading[1] ?? "").replace(ATX_CLOSING, "").trim() || null,
+          title: (sectionHeading[1] ?? "").replace(ATX_CLOSING, "").trim(),
           lines: [],
         });
         continue;
@@ -91,19 +98,22 @@ export function parseChangelog(markdown: string): ChangelogRelease[] {
     }
 
     const release = releases.at(-1);
-    if (release) release.sections[release.sections.length - 1].lines.push(line);
+    if (release) (release.sections.at(-1)?.lines ?? release.highlights).push(line);
   }
 
   return releases.map(materializeRelease);
 }
 
 function materializeRelease(draft: ReleaseDraft): ChangelogRelease {
-  const sections = draft.sections
-    .map((section) => ({ title: section.title, body: trimBlankLines(section.lines) }))
-    // A heading with an empty body still names something; an empty lead section
-    // is just the gap between the release heading and the first section.
-    .filter((section) => section.title !== null || section.body.length > 0);
-  return { version: draft.version, date: draft.date, sections };
+  return {
+    version: draft.version,
+    date: draft.date,
+    highlights: trimBlankLines(draft.highlights),
+    sections: draft.sections.map((section) => ({
+      title: section.title,
+      body: trimBlankLines(section.lines),
+    })),
+  };
 }
 
 function trimBlankLines(lines: string[]): string {
diff --git a/packages/app/src/client-slash-commands/index.test.ts b/packages/app/src/client-slash-commands/index.test.ts
index c6e86be582..dc2850615f 100644
--- a/packages/app/src/client-slash-commands/index.test.ts
+++ b/packages/app/src/client-slash-commands/index.test.ts
@@ -40,16 +40,7 @@ function createAgent(overrides: Partial<Agent> = {}): Agent {
     cwd: "/repo",
     model: "agent-model",
     thinkingOptionId: "think-hard",
-    features: [
-      { type: "toggle", id: "web-search", label: "Web search", value: true },
-      {
-        type: "select",
-        id: "effort",
-        label: "Effort",
-        value: "high",
-        options: [{ id: "high", label: "High" }],
-      },
-    ],
+    options: { "web-search": true, effort: "high" },
     parentAgentId: null,
     labels: {},
     ...overrides,
@@ -114,7 +105,7 @@ describe("buildDraftAgentSetup", () => {
       modeId: "mode-current",
       model: "agent-model",
       thinkingOptionId: "think-hard",
-      featureValues: {
+      providerOptions: {
         "web-search": true,
         effort: "high",
       },
diff --git a/packages/app/src/client-slash-commands/index.ts b/packages/app/src/client-slash-commands/index.ts
index 5d1a31f7d2..9a85d01591 100644
--- a/packages/app/src/client-slash-commands/index.ts
+++ b/packages/app/src/client-slash-commands/index.ts
@@ -65,17 +65,12 @@ export function resolveClientSlashCommand(input: {
 }
 
 export function buildDraftAgentSetup(agent: Agent): WorkspaceDraftTabSetup {
-  const featureValues: Record<string, unknown> = {};
-  for (const feature of agent.features ?? []) {
-    featureValues[feature.id] = feature.value;
-  }
-
   return {
     provider: agent.provider,
     cwd: agent.cwd,
     modeId: agent.currentModeId ?? agent.runtimeInfo?.modeId ?? null,
     model: agent.model ?? agent.runtimeInfo?.model ?? null,
     thinkingOptionId: agent.thinkingOptionId ?? agent.runtimeInfo?.thinkingOptionId ?? null,
-    featureValues,
+    providerOptions: { ...agent.options },
   };
 }
diff --git a/packages/app/src/command-center/agent-control-contributions.test.ts b/packages/app/src/command-center/agent-control-contributions.test.ts
index 6fe8f91bb6..929804d913 100644
--- a/packages/app/src/command-center/agent-control-contributions.test.ts
+++ b/packages/app/src/command-center/agent-control-contributions.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import type { AgentFeature, AgentMode, AgentSelectOption } from "@getpaseo/protocol/agent-types";
+import type {
+  AgentMode,
+  AgentOptionControl,
+  AgentSelectOption,
+} from "@getpaseo/protocol/agent-types";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import type { CommandCenterContribution } from "./contributions";
 import {
@@ -31,7 +35,7 @@ const ICONS: AgentControlContributionSource["icons"] = {
   thinking: TestIcon,
   planMode: TestIcon,
   mode: () => TestIcon,
-  feature: () => TestIcon,
+  control: () => TestIcon,
 };
 
 function provider(input: {
@@ -65,8 +69,8 @@ function provider(input: {
   };
 }
 
-function toggleFeature(id: string, value = false, icon?: string): AgentFeature {
-  return { type: "toggle", id, label: id, value, icon };
+function toggleControl(key: string, icon?: string): AgentOptionControl {
+  return { type: "toggle", key, label: key, icon };
 }
 
 function makeSource(
@@ -75,7 +79,7 @@ function makeSource(
     models?: Partial<AgentControlContributionSource["models"]>;
     thinking?: Partial<AgentControlContributionSource["thinking"]>;
     modes?: Partial<NonNullable<AgentControlContributionSource["modes"]>>;
-    features?: Partial<AgentControlContributionSource["features"]>;
+    optionControls?: Partial<AgentControlContributionSource["optionControls"]>;
   } = {},
 ): AgentControlContributionSource {
   return {
@@ -104,10 +108,11 @@ function makeSource(
       select: () => undefined,
       ...overrides.modes,
     },
-    features: {
-      list: [],
-      set: () => undefined,
-      ...overrides.features,
+    optionControls: {
+      controls: [],
+      options: {},
+      onSetOption: () => undefined,
+      ...overrides.optionControls,
     },
   };
 }
@@ -133,7 +138,7 @@ describe("Command Center agent-control contributions", () => {
     const contributions = buildAgentControlContributions({
       ...makeSource({
         models: { providers: [provider({ id: "claude", label: "Claude" })] },
-        features: { list: [toggleFeature("plan_mode", true)] },
+        optionControls: { controls: [toggleControl("plan_mode")], options: { plan_mode: true } },
       }),
       modes: undefined,
     });
@@ -323,9 +328,10 @@ describe("Command Center agent-control contributions", () => {
           selectedId: "default",
           defaultModeId: "default",
         },
-        features: {
-          list: [toggleFeature("plan_mode", true, "list-todo")],
-          set: (id, value) => {
+        optionControls: {
+          controls: [toggleControl("plan_mode", "list-todo")],
+          options: { plan_mode: true },
+          onSetOption: (id, value) => {
             calls.push([id, value]);
           },
         },
@@ -341,9 +347,10 @@ describe("Command Center agent-control contributions", () => {
     const calls: [string, unknown][] = [];
     const contributions = buildAgentControlContributions(
       makeSource({
-        features: {
-          list: [toggleFeature("fast_mode", false, "zap"), toggleFeature("auto_accept", true)],
-          set: (id, value) => {
+        optionControls: {
+          controls: [toggleControl("fast_mode", "zap"), toggleControl("auto_accept")],
+          options: { fast_mode: false, auto_accept: true },
+          onSetOption: (id, value) => {
             calls.push([id, value]);
           },
         },
@@ -376,7 +383,7 @@ describe("Command Center agent-control contributions", () => {
           selectedId: "default",
           defaultModeId: "default",
         },
-        features: { list: [toggleFeature("fast_mode")] },
+        optionControls: { controls: [toggleControl("fast_mode")], options: {} },
       }),
     );
     const ranks = new Map<string, number>();
diff --git a/packages/app/src/command-center/agent-control-contributions.ts b/packages/app/src/command-center/agent-control-contributions.ts
index d8f31523e9..b16ee90549 100644
--- a/packages/app/src/command-center/agent-control-contributions.ts
+++ b/packages/app/src/command-center/agent-control-contributions.ts
@@ -1,9 +1,10 @@
 import type {
-  AgentFeature,
   AgentMode,
+  AgentOptionControl,
   AgentProvider,
   AgentSelectOption,
 } from "@getpaseo/protocol/agent-types";
+import { readToggleOption, type ComposerOptionControls } from "@/agent-controls/option-controls";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { formatAgentModeLabel, formatThinkingOptionLabel } from "@/agent-controls/labels";
 import {
@@ -61,7 +62,7 @@ export interface AgentControlContributionIcons {
   thinking: CommandCenterIcon;
   planMode: CommandCenterIcon;
   mode(modeId: string): CommandCenterIcon;
-  feature(feature: AgentFeature): CommandCenterIcon;
+  control(control: AgentOptionControl): CommandCenterIcon;
 }
 
 interface CommandCenterChoice {
@@ -105,10 +106,7 @@ export interface AgentControlContributionSource {
     defaultModeId: string | null;
     select(modeId: string): void | Promise<void>;
   };
-  features: {
-    list: readonly AgentFeature[];
-    set(featureId: string, value: unknown): void | Promise<void>;
-  };
+  optionControls: ComposerOptionControls;
 }
 
 function buildContributions(
@@ -242,18 +240,19 @@ function toggleChoices(input: {
 }
 
 function buildPlanModeGroup(source: AgentControlContributionSource): CommandCenterChoiceGroup {
-  const planFeature = source.features.list.find(
-    (feature) => feature.id === PLAN_MODE_FEATURE_ID && feature.type === "toggle",
+  const { controls, options, onSetOption } = source.optionControls;
+  const planControl = controls.find(
+    (control) => control.key === PLAN_MODE_FEATURE_ID && control.type === "toggle",
   );
   let choices: CommandCenterChoice[] = [];
-  if (planFeature?.type === "toggle") {
+  if (planControl?.type === "toggle") {
     choices = toggleChoices({
       source,
       key: "plan",
-      icon: source.icons.feature(planFeature),
-      isOn: planFeature.value,
-      turnOn: () => source.features.set(PLAN_MODE_FEATURE_ID, true),
-      turnOff: () => source.features.set(PLAN_MODE_FEATURE_ID, false),
+      icon: source.icons.control(planControl),
+      isOn: readToggleOption(planControl, options),
+      turnOn: () => onSetOption(PLAN_MODE_FEATURE_ID, true),
+      turnOff: () => onSetOption(PLAN_MODE_FEATURE_ID, false),
     });
   } else if (source.modes) {
     const modes = source.modes;
@@ -280,18 +279,19 @@ function buildPlanModeGroup(source: AgentControlContributionSource): CommandCent
 }
 
 function buildFastModeGroup(source: AgentControlContributionSource): CommandCenterChoiceGroup {
-  const fastFeature = source.features.list.find(
-    (feature) => feature.id === FAST_MODE_FEATURE_ID && feature.type === "toggle",
+  const { controls, options, onSetOption } = source.optionControls;
+  const fastControl = controls.find(
+    (control) => control.key === FAST_MODE_FEATURE_ID && control.type === "toggle",
   );
   const choices =
-    fastFeature?.type === "toggle"
+    fastControl?.type === "toggle"
       ? toggleChoices({
           source,
           key: "fast",
-          icon: source.icons.feature(fastFeature),
-          isOn: fastFeature.value,
-          turnOn: () => source.features.set(FAST_MODE_FEATURE_ID, true),
-          turnOff: () => source.features.set(FAST_MODE_FEATURE_ID, false),
+          icon: source.icons.control(fastControl),
+          isOn: readToggleOption(fastControl, options),
+          turnOn: () => onSetOption(FAST_MODE_FEATURE_ID, true),
+          turnOff: () => onSetOption(FAST_MODE_FEATURE_ID, false),
         })
       : [];
   return {
diff --git a/packages/app/src/command-center/agent-control-registration.tsx b/packages/app/src/command-center/agent-control-registration.tsx
index 21ce492373..81391dba10 100644
--- a/packages/app/src/command-center/agent-control-registration.tsx
+++ b/packages/app/src/command-center/agent-control-registration.tsx
@@ -1,11 +1,6 @@
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import type {
-  AgentFeature,
-  AgentMode,
-  AgentProvider,
-  AgentSelectOption,
-} from "@getpaseo/protocol/agent-types";
+import type { AgentMode, AgentProvider, AgentSelectOption } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import {
   getAgentFeatureIcon,
@@ -14,6 +9,7 @@ import {
   ThinkingIcon,
 } from "@/agent-controls/icons";
 import { useProviderIcons } from "@/components/provider-icons";
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import {
   buildAgentControlContributions,
@@ -44,15 +40,15 @@ export interface AgentControlCommandCenterSource {
     selectedId: string | null | undefined;
     select(modeId: string): void | Promise<void>;
   };
-  features: {
-    list: readonly AgentFeature[] | undefined;
-    set?: (featureId: string, value: unknown) => void | Promise<void>;
-  };
+  /** Absent when the surface cannot change options (the agent has no client). */
+  optionControls: ComposerOptionControls | null;
 }
 
-function ignoreAgentFeatureChange(): void {
-  return;
-}
+const NO_OPTION_CONTROLS: ComposerOptionControls = {
+  controls: [],
+  options: {},
+  onSetOption: () => undefined,
+};
 
 function resolveDefaultModeId(
   provider: string | null | undefined,
@@ -87,7 +83,7 @@ export function useAgentControlCommandCenterActions(input: {
 }): void {
   const { t } = useTranslation();
   const { controls } = input;
-  const { features, models, modes, thinking } = controls;
+  const { optionControls, models, modes, thinking } = controls;
   const getProviderIcon = useProviderIcons(controls.serverId);
   const actions = useMemo(
     () =>
@@ -104,7 +100,7 @@ export function useAgentControlCommandCenterActions(input: {
             getCommandCenterIcon(
               getAgentModeIcon(controls.provider ?? "", modeId, controls.providerDefinitions),
             ),
-          feature: (feature) => getCommandCenterIcon(getAgentFeatureIcon(feature.icon)),
+          control: (control) => getCommandCenterIcon(getAgentFeatureIcon(control.icon)),
         },
         models: {
           providers: models.providers,
@@ -123,10 +119,7 @@ export function useAgentControlCommandCenterActions(input: {
           modes?.select,
           resolveDefaultModeId(controls.provider, controls.providerDefinitions),
         ),
-        features: {
-          list: features.set ? (features.list ?? []) : [],
-          set: features.set ?? ignoreAgentFeatureChange,
-        },
+        optionControls: optionControls ?? NO_OPTION_CONTROLS,
       }),
     [
       getProviderIcon,
@@ -134,8 +127,7 @@ export function useAgentControlCommandCenterActions(input: {
       controls.provider,
       controls.providerDefinitions,
       controls.serverId,
-      features.list,
-      features.set,
+      optionControls,
       models.providers,
       models.select,
       models.selectedModelId,
diff --git a/packages/app/src/command-center/command-center.tsx b/packages/app/src/command-center/command-center.tsx
index 309564bcea..1c20f0725d 100644
--- a/packages/app/src/command-center/command-center.tsx
+++ b/packages/app/src/command-center/command-center.tsx
@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import equal from "fast-deep-equal";
 import { recordRenderProfileReasons } from "@/utils/render-profiler";
@@ -52,11 +53,7 @@ import { useProjects } from "@/hooks/use-projects";
 import { useTimeAgo } from "@/hooks/use-time-ago";
 import { createProjectIconTarget } from "@/projects/icon-target";
 import { useProjectIcons } from "@/projects/icons";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import {
   useKeyboardShortcutsStore,
@@ -763,6 +760,10 @@ function SectionRow({ row }: { row: Extract<CommandCenterListRow, { kind: "secti
   );
 }
 
+// Escape arrives without asking; it is registered for `agent.interrupt` anyway.
+// Backspace stays off deliberately — the palette pops its scope with it on web,
+// but a registered command would stop the search field deleting text.
+
 export function CommandCenter() {
   const { t } = useTranslation();
   const isCompact = useIsCompactFormFactor();
@@ -780,7 +781,7 @@ export function CommandCenter() {
     interaction,
   );
   const showBottomSheet = isCompact && isNative;
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && state.open && !showBottomSheet);
+  const modalLayer = useGlobalOverlayLayer("modal", state.open);
   const { sheetRef, handleSheetChange, handleSheetDismiss } = useIsolatedBottomSheetVisibility({
     visible: state.open,
     isEnabled: showBottomSheet,
@@ -874,23 +875,20 @@ export function CommandCenter() {
       : {}),
     scrollEventThrottle: 16,
   };
-  const keyPress = useCallback(
-    ({ nativeEvent: { key } }: { nativeEvent: { key: string } }) => state.key(key),
-    [state],
-  );
   const submit = useCallback(() => state.key("Enter"), [state]);
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (!state.key(event.key)) return false;
       event.preventDefault();
       return true;
     },
     [state],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && state.open && !showBottomSheet,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: state.open,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   if (showBottomSheet) {
@@ -911,45 +909,46 @@ export function CommandCenter() {
         keyboardBlurBehavior="restore"
         accessible={false}
       >
-        <View style={[styles.bottomSheetHeader, styles.searchRow]} testID="command-center-header">
-          {state.scope === "files" ? (
-            <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />
-          ) : null}
-          <ThemedBottomSheetTextInput
-            testID="command-center-input"
-            ref={bottomSheetInputRef}
-            initialValue={state.query}
-            variant="bottom-sheet"
-            onChangeText={state.setQuery}
-            onKeyPress={keyPress}
-            onSubmitEditing={submit}
-            placeholder={
-              state.scope === "files"
-                ? t("shell.commandCenter.filePlaceholder")
-                : t("shell.commandCenter.placeholder")
-            }
-            style={[styles.input, styles.growingInput]}
-            autoCapitalize="none"
-            autoCorrect={false}
-            autoFocus
-          />
-          <FileSearchLoadingIndicator
-            loading={state.fileSearchLoading}
-            label={t("shell.commandCenter.searchingFiles")}
-          />
-        </View>
-        {fileSearchError}
-        <BottomSheetFlatList ref={bottomSheetListRef} {...commonListProps} />
+        <OverlayLayerProvider layer={modalLayer}>
+          <View style={[styles.bottomSheetHeader, styles.searchRow]} testID="command-center-header">
+            {state.scope === "files" ? (
+              <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />
+            ) : null}
+            <ThemedBottomSheetTextInput
+              testID="command-center-input"
+              ref={bottomSheetInputRef}
+              initialValue={state.query}
+              variant="bottom-sheet"
+              onChangeText={state.setQuery}
+              onSubmitEditing={submit}
+              placeholder={
+                state.scope === "files"
+                  ? t("shell.commandCenter.filePlaceholder")
+                  : t("shell.commandCenter.placeholder")
+              }
+              style={[styles.input, styles.growingInput]}
+              autoCapitalize="none"
+              autoCorrect={false}
+              autoFocus
+            />
+            <FileSearchLoadingIndicator
+              loading={state.fileSearchLoading}
+              label={t("shell.commandCenter.searchingFiles")}
+            />
+          </View>
+          {fileSearchError}
+          <BottomSheetFlatList ref={bottomSheetListRef} {...commonListProps} />
+        </OverlayLayerProvider>
       </IsolatedBottomSheetModal>
     );
   }
   if (!state.open) return null;
   return (
-    <OverlayLayerProvider layer={isWeb ? modalLayer : 0}>
+    <OverlayLayerProvider layer={modalLayer}>
       <Modal visible transparent animationType="fade" onRequestClose={state.close}>
         <View style={styles.overlay}>
           <Pressable style={styles.backdrop} onPress={state.close} />
-          <View ref={setWebOverlayScope} testID="command-center-panel" style={styles.panel}>
+          <View ref={setOverlayScope} testID="command-center-panel" style={styles.panel}>
             <View style={[styles.header, styles.searchRow]} testID="command-center-header">
               {state.scope === "files" ? (
                 <ScopeChip label={t("shell.commandCenter.files")} onRemove={state.clearScope} />
diff --git a/packages/app/src/command-center/root-registration.tsx b/packages/app/src/command-center/root-registration.tsx
index bb39882630..9978aed6e1 100644
--- a/packages/app/src/command-center/root-registration.tsx
+++ b/packages/app/src/command-center/root-registration.tsx
@@ -1,3 +1,4 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useMemo } from "react";
 import { router, type Href } from "expo-router";
 import { useTranslation } from "react-i18next";
@@ -15,12 +16,12 @@ import {
   Settings,
 } from "lucide-react-native";
 import { withUnistyles } from "react-native-unistyles";
-import { getIsElectronRuntime, useIsCompactFormFactor } from "@/constants/layout";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { useOpenAddProject } from "@/hooks/use-open-add-project";
 import { useImportSession } from "@/hooks/use-import-session";
 import { useKeyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher-context";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { resolveShortcutKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { usePanelStore } from "@/stores/panel-store";
@@ -111,7 +112,7 @@ export function CommandCenterRootActions() {
   const keyboardActionDispatcher = useKeyboardActionDispatcher();
   const { t } = useTranslation();
   const { overrides } = useKeyboardShortcutOverrides();
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAddProject = useOpenAddProject();
   const { open: openImportSession, sheet: importSessionSheet } = useImportSession();
   const settingsRoute = useMemo<Href>(() => buildSettingsRoute(), []);
@@ -128,7 +129,7 @@ export function CommandCenterRootActions() {
   const toggleDesktopAgentList = usePanelStore((state) => state.toggleDesktopAgentList);
   const toggleAgentList = isCompact ? toggleMobileAgentList : toggleDesktopAgentList;
   const shortcutPlatform = useMemo(
-    () => ({ isMac: getShortcutOs() === "mac", isDesktop: getIsElectronRuntime() }),
+    () => ({ isMac: getShortcutOs() === "mac", usesDesktopBindings }),
     [],
   );
   const actions = useMemo<CommandCenterContribution[]>(() => {
diff --git a/packages/app/src/command-center/workspace-registration.tsx b/packages/app/src/command-center/workspace-registration.tsx
index cd9d008c55..41416d30eb 100644
--- a/packages/app/src/command-center/workspace-registration.tsx
+++ b/packages/app/src/command-center/workspace-registration.tsx
@@ -1,3 +1,4 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useCallback, useMemo, type ReactElement } from "react";
 import { useTranslation } from "react-i18next";
 import {
@@ -105,7 +106,7 @@ function staticIcon(element: ReactElement | undefined): CommandCenterIcon | unde
 }
 
 function resolveWorkspaceShortcuts(overrides: ShortcutOverrides): WorkspaceCommandCenterShortcuts {
-  const platform = { isMac: getShortcutOs() === "mac", isDesktop: getIsElectron() };
+  const platform = { isMac: getShortcutOs() === "mac", usesDesktopBindings };
   return resolveWorkspaceCommandCenterShortcuts({ overrides, platform });
 }
 
diff --git a/packages/app/src/command-center/workspace-shortcuts.test.ts b/packages/app/src/command-center/workspace-shortcuts.test.ts
index bfffce9577..bb8d66c983 100644
--- a/packages/app/src/command-center/workspace-shortcuts.test.ts
+++ b/packages/app/src/command-center/workspace-shortcuts.test.ts
@@ -6,7 +6,7 @@ describe("resolveWorkspaceCommandCenterShortcuts", () => {
     expect(
       resolveWorkspaceCommandCenterShortcuts({
         overrides: {},
-        platform: { isMac: true, isDesktop: true },
+        platform: { isMac: true, usesDesktopBindings: true },
       }).newAgent,
     ).toEqual([["mod", "shift", "A"]]);
   });
diff --git a/packages/app/src/command-center/workspace-shortcuts.ts b/packages/app/src/command-center/workspace-shortcuts.ts
index c51a1fcc60..98be2986cd 100644
--- a/packages/app/src/command-center/workspace-shortcuts.ts
+++ b/packages/app/src/command-center/workspace-shortcuts.ts
@@ -6,7 +6,7 @@ import type { WorkspaceCommandCenterShortcuts } from "./workspace-contributions"
 
 interface ResolveWorkspaceCommandCenterShortcutsInput {
   overrides: ShortcutOverrides;
-  platform: { isMac: boolean; isDesktop: boolean };
+  platform: { isMac: boolean; usesDesktopBindings: boolean };
 }
 
 export function resolveWorkspaceCommandCenterShortcuts({
diff --git a/packages/app/src/components/adaptive-modal-sheet.tsx b/packages/app/src/components/adaptive-modal-sheet.tsx
index 4ddf872daa..3ff2020955 100644
--- a/packages/app/src/components/adaptive-modal-sheet.tsx
+++ b/packages/app/src/components/adaptive-modal-sheet.tsx
@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import type { ComponentProps, ReactNode } from "react";
 import { createPortal } from "react-dom";
@@ -6,12 +7,7 @@ import { Keyboard, Pressable, Text, View } from "react-native";
 import type { DimensionValue, StyleProp, ViewProps, ViewStyle } from "react-native";
 import { StyleSheet, useUnistyles, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "../lib/overlay-root";
+import { getOverlayRoot, OverlayLayerProvider, useGlobalOverlayLayer } from "../lib/overlay-root";
 import {
   BottomSheetHandle,
   useBottomSheetGestureHandlers,
@@ -32,6 +28,7 @@ import { isWeb } from "@/constants/platform";
 import { useKeyboardVisibility } from "@/hooks/use-keyboard-visibility";
 import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
 import { AdaptiveTextInput } from "@/components/adaptive-text-input";
+import { useDismissibleOverlay } from "@/components/ui/overlay-dismissal";
 export { AdaptiveTextInput, type AdaptiveTextInputProps } from "@/components/adaptive-text-input";
 
 // Horizontal indent token shared by the sheet header (title, back arrow,
@@ -99,7 +96,7 @@ const styles = StyleSheet.create((theme) => ({
     maxHeight: "85%",
     flexShrink: 1,
     minHeight: 0,
-    backgroundColor: theme.colors.surface1,
+    backgroundColor: theme.colors.surface0,
     borderRadius: theme.borderRadius.xl,
     borderWidth: 1,
     borderColor: theme.colors.surface2,
@@ -140,6 +137,12 @@ const styles = StyleSheet.create((theme) => ({
     padding: theme.spacing[SHEET_HEADER_CLOSE_PADDING_SCALE],
     borderRadius: theme.borderRadius.lg,
   },
+  // Without a header the close button floats over the card's top-right corner.
+  floatingClose: {
+    position: "absolute",
+    top: theme.spacing[4],
+    right: theme.spacing[4],
+  },
   searchRow: {
     flexDirection: "row",
     alignItems: "center",
@@ -230,6 +233,28 @@ const styles = StyleSheet.create((theme) => ({
 }));
 
 const WEB_EXIT_DURATION_MS = 160;
+const WEB_ENTER_DURATION_MS = 160;
+const WEB_ENTER_ANIMATION_NAME = "paseo-modal-enter";
+
+// The desktop card fades in; the dim lands at once, so the screen behind is never seen undimmed
+// while the dialog arrives. A CSS animation runs from the card's first paint, so a dialog that opens
+// on its own, like first-run setup, never pops in. Closing fades the whole overlay. With reduced
+// motion the keyframes are never defined, so the card appears at once.
+function ensureWebEnterKeyframes() {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(WEB_ENTER_ANIMATION_NAME)) return;
+  const style = document.createElement("style");
+  style.id = WEB_ENTER_ANIMATION_NAME;
+  style.textContent = `@media (prefers-reduced-motion: no-preference) { @keyframes ${WEB_ENTER_ANIMATION_NAME} { from { opacity: 0; } to { opacity: 1; } } }`;
+  document.head.appendChild(style);
+}
+ensureWebEnterKeyframes();
+// The CSS animation props are not part of ViewStyle without the generated expo-env.d.ts.
+const WEB_ENTER_STYLE = {
+  animationName: WEB_ENTER_ANIMATION_NAME,
+  animationDuration: `${WEB_ENTER_DURATION_MS}ms`,
+  animationTimingFunction: "ease-out",
+} as unknown as ViewStyle;
 
 /** The compact sheet's surface: Gorhom's `backgroundComponent` for every bottom sheet. */
 export function SheetBackground({ style }: BottomSheetBackgroundProps) {
@@ -493,8 +518,27 @@ export function InlineHeaderView({ header }: { header: SheetHeader }) {
   );
 }
 
+/**
+ * The sheet's action row: a top border, the sheet's side inset, and children spread across it.
+ * The sheet draws it for `footer`; a body that splits into panes renders it at the bottom of one.
+ */
+export function SheetFooter({
+  style,
+  children,
+}: {
+  style?: StyleProp<ViewStyle>;
+  children: ReactNode;
+}) {
+  return <View style={[styles.footer, style]}>{children}</View>;
+}
+
 export interface AdaptiveModalSheetProps {
-  header: SheetHeader;
+  /**
+   * The title row with the close button. Leave it out when the body draws its own chrome, such as
+   * a full-height side rail: the desktop card then floats the close button over its top-right
+   * corner, and the compact sheet closes from its handle.
+   */
+  header?: SheetHeader;
   visible: boolean;
   onClose: () => void;
   onDismiss?: () => void;
@@ -534,7 +578,7 @@ function CompactSheetBody({
   contentStyle,
   children,
 }: {
-  header: SheetHeader;
+  header?: SheetHeader;
   onClose: () => void;
   testID?: string;
   footer: ReactNode;
@@ -564,7 +608,7 @@ function CompactSheetBody({
   );
   return (
     <SheetVisibleFrame footer={footerView}>
-      <SheetHeaderView header={header} onClose={onClose} testID={testID} />
+      {header ? <SheetHeaderView header={header} onClose={onClose} testID={testID} /> : null}
       <View style={[styles.compactStaticContent, bodyStyle]}>
         {scrollable ? (
           <ScrollView
@@ -611,8 +655,11 @@ export function AdaptiveModalSheet({
   const isMobile = useIsCompactFormFactor();
   const isKeyboardVisible = useKeyboardVisibility(visible);
   const resolvedSnapPoints = useMemo(() => snapPoints ?? ["65%", "90%"], [snapPoints]);
+  const isSheet = isMobile || !isWeb;
+  // The sheet registers itself; the desktop dialog does not use it.
+  useDismissibleOverlay(visible && !isSheet, onClose);
   const footerView = useMemo(
-    () => (footer ? <View style={[styles.footer, footerContainerStyle]}>{footer}</View> : null),
+    () => (footer ? <SheetFooter style={footerContainerStyle}>{footer}</SheetFooter> : null),
     [footer, footerContainerStyle],
   );
   useEffect(() => {
@@ -625,12 +672,12 @@ export function AdaptiveModalSheet({
 
   const { sheetRef, handleSheetChange, handleSheetDismiss } = useIsolatedBottomSheetVisibility({
     visible,
-    isEnabled: isMobile || !isWeb,
+    isEnabled: isSheet,
     onClose,
   });
   const [shouldRenderWeb, setShouldRenderWeb] = useState(visible);
   const [isWebClosing, setIsWebClosing] = useState(false);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && !isMobile && shouldRenderWeb);
+  const modalLayer = useGlobalOverlayLayer("modal", visible || shouldRenderWeb);
   const handleDismiss = useCallback(() => {
     handleSheetDismiss();
     onDismiss?.();
@@ -641,6 +688,7 @@ export function AdaptiveModalSheet({
       styles.desktopCard,
       desktopHeight != null && { height: desktopHeight },
       desktopMaxWidth != null && { maxWidth: desktopMaxWidth },
+      isWeb && WEB_ENTER_STYLE,
     ],
     [desktopMaxWidth, desktopHeight],
   );
@@ -658,8 +706,8 @@ export function AdaptiveModalSheet({
     [isWebClosing, modalLayer],
   );
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key !== "Escape") return false;
       event.preventDefault();
       event.stopPropagation();
@@ -668,10 +716,11 @@ export function AdaptiveModalSheet({
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && !isMobile && visible,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: visible,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   useEffect(() => {
@@ -710,18 +759,20 @@ export function AdaptiveModalSheet({
         accessible={false}
         presentation={presentation}
       >
-        <CompactSheetBody
-          header={header}
-          onClose={onClose}
-          testID={testID}
-          footer={footerView}
-          isKeyboardVisible={isKeyboardVisible}
-          scrollable={scrollable}
-          bodyStyle={bodyStyle}
-          contentStyle={contentStyle}
-        >
-          {children}
-        </CompactSheetBody>
+        <OverlayLayerProvider layer={modalLayer}>
+          <CompactSheetBody
+            header={header}
+            onClose={onClose}
+            testID={testID}
+            footer={footerView}
+            isKeyboardVisible={isKeyboardVisible}
+            scrollable={scrollable}
+            bodyStyle={bodyStyle}
+            contentStyle={contentStyle}
+          >
+            {children}
+          </CompactSheetBody>
+        </OverlayLayerProvider>
       </IsolatedBottomSheetModal>
     );
   }
@@ -730,7 +781,7 @@ export function AdaptiveModalSheet({
     desktopHeight == null ? styles.desktopStaticContent : styles.compactStaticContent;
   const cardInner = (
     <OverlayLayerProvider layer={modalLayer}>
-      <SheetHeaderView header={header} onClose={onClose} />
+      {header ? <SheetHeaderView header={header} onClose={onClose} /> : null}
       <View style={[scrollable ? styles.desktopScrollContainer : desktopStaticStyle, bodyStyle]}>
         {scrollable ? (
           <ScrollView
@@ -746,6 +797,15 @@ export function AdaptiveModalSheet({
         )}
       </View>
       {footerView}
+      {header ? null : (
+        <View style={styles.floatingClose}>
+          <SheetHeaderIconButton
+            icon={X}
+            accessibilityLabel={t("common.actions.close")}
+            onPress={onClose}
+          />
+        </View>
+      )}
     </OverlayLayerProvider>
   );
 
@@ -756,13 +816,7 @@ export function AdaptiveModalSheet({
         style={ABSOLUTE_FILL_STYLE}
         onPress={onClose}
       />
-      <View
-        ref={setWebOverlayScope}
-        style={desktopCardStyle}
-        role="dialog"
-        aria-modal
-        tabIndex={-1}
-      >
+      <View ref={setOverlayScope} style={desktopCardStyle} role="dialog" aria-modal tabIndex={-1}>
         {cardInner}
       </View>
     </View>
diff --git a/packages/app/src/components/add-project-flow.tsx b/packages/app/src/components/add-project-flow.tsx
index 7fdf21dd83..038e026c76 100644
--- a/packages/app/src/components/add-project-flow.tsx
+++ b/packages/app/src/components/add-project-flow.tsx
@@ -1,3 +1,5 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
 import { usePanelStore } from "@/stores/panel-store";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
@@ -68,19 +70,15 @@ import {
 } from "@/components/project-picker-options";
 import { Shortcut } from "@/components/ui/shortcut";
 import { useRevealActiveItem } from "@/components/ui/scroll-reveal";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { getIsElectronRuntime } from "@/constants/layout";
-import { isNative, isWeb } from "@/constants/platform";
+import { isWeb } from "@/constants/platform";
 import { pickDirectory } from "@/desktop/pick-directory";
 import { useFetchQuery } from "@/data/query";
 import { getOpenProjectFailureReason, registerProjectDescriptor } from "@/hooks/open-project";
 import { useIsLocalDaemon, useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import { useCloneGithubProject, useOpenProject } from "@/hooks/use-open-project";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import {
   useHosts,
   useHostRuntimeClient,
@@ -92,7 +90,7 @@ import { useRecommendedProjectPaths } from "@/stores/session-store-hooks";
 import type { AddProjectFlowRequest } from "@/stores/add-project-flow-store";
 import type { Theme } from "@/styles/theme";
 import { shortenPath } from "@/utils/shorten-path";
-import { buildNewWorkspaceRoute, buildSettingsAddHostRoute } from "@/utils/host-routes";
+import { buildNewWorkspaceRoute } from "@/utils/host-routes";
 
 interface AddProjectFlowProps {
   request: AddProjectFlowRequest;
@@ -301,7 +299,7 @@ function FlowRow({
 }
 
 function FlowHint({ keys, action }: { keys: string[]; action: string }) {
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   if (!shortcutsAvailable) return null;
 
   return (
@@ -325,6 +323,7 @@ function setPageStatus(
 // The product flow is intentionally one cohesive page-stack state machine.
 // eslint-disable-next-line complexity
 export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
+  const addHost = useAddHost();
   const hosts = useHosts();
   const hostIds = useMemo(() => hosts.map((host) => host.serverId), [hosts]);
   const connectionStatuses = useHostRuntimeConnectionStatuses(hostIds);
@@ -458,13 +457,10 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
   });
 
   const handleBack = useCallback(() => {
-    setState((current) => {
-      const previous = backAddProjectPage(current);
-      if (previous) return previous;
-      onClose();
-      return current;
-    });
-  }, [onClose]);
+    const previous = backAddProjectPage(state);
+    if (previous) setState(previous);
+    else onClose();
+  }, [onClose, state]);
 
   const openNewWorkspaceForProject = useCallback(
     (serverId: string, project: WorkspaceProjectDescriptorPayload) => {
@@ -616,9 +612,9 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
           icon: Plus,
           testID: "add-project-flow-add-host",
           select: () => {
+            // The native project Modal must release its window before the root sheet opens.
             onClose();
-            usePanelStore.getState().showMobileAgent();
-            router.push(buildSettingsAddHostRoute(Date.now()));
+            addHost();
           },
         });
       }
@@ -717,6 +713,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     directoryPaths,
     githubQuery.data,
     host,
+    addHost,
     onClose,
     openAddedProject,
     page,
@@ -812,30 +809,22 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     [activeIndex, handleBack, rows, submitActive],
   );
 
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb);
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const modalLayer = useGlobalOverlayLayer("modal", true);
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (!handleKey(event.key)) return false;
       event.preventDefault();
       return true;
     },
     [handleKey],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: true,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
-  const handleNativeKeyPress = useCallback(
-    ({ nativeEvent: { key } }: { nativeEvent: { key: string } }) => {
-      if (key === "ArrowDown" || key === "ArrowUp" || key === "Escape") {
-        handleKey(key);
-      }
-    },
-    [handleKey],
-  );
-
   const handleInputChange = useCallback((value: string) => {
     setState((current) =>
       currentAddProjectPage(current).kind === "new-directory-name"
@@ -870,7 +859,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
       <View style={styles.overlay} testID="add-project-flow">
         <Pressable style={styles.backdrop} onPress={onClose} testID="add-project-flow-backdrop" />
         <View
-          ref={setWebOverlayScope}
+          ref={setOverlayScope}
           style={styles.panel}
           testID={`add-project-flow-page-${page.kind}`}
           accessibilityLabel={`Add project: ${page.kind}`}
@@ -889,29 +878,11 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
                 ) : null}
               </View>
             </View>
-            {page.kind === "method" && isNative ? (
-              // Native hardware-keyboard events need a focused responder even without a visible field.
-              <TextInput
-                ref={inputRef}
-                onKeyPress={handleNativeKeyPress}
-                onSubmitEditing={submitActive}
-                showSoftInputOnFocus={false}
-                caretHidden
-                contextMenuHidden
-                accessible={false}
-                accessibilityElementsHidden
-                importantForAccessibility="no-hide-descendants"
-                pointerEvents="none"
-                style={styles.keyboardCapture}
-                testID="add-project-flow-keyboard-capture"
-              />
-            ) : null}
             {page.kind !== "method" ? (
               <ThemedTextInput
                 ref={inputRef}
                 initialValue={pageInput(page)}
                 onChangeText={handleInputChange}
-                onKeyPress={isWeb ? undefined : handleNativeKeyPress}
                 onSubmitEditing={isWeb ? undefined : submitActive}
                 placeholder={pagePlaceholder(page)}
                 style={styles.input}
@@ -993,7 +964,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     </Modal>
   );
 
-  return createElement(OverlayLayerProvider, { layer: isWeb ? modalLayer : 0 }, modal);
+  return createElement(OverlayLayerProvider, { layer: modalLayer }, modal);
 }
 
 const styles = StyleSheet.create((theme) => ({
@@ -1067,12 +1038,6 @@ const styles = StyleSheet.create((theme) => ({
     paddingVertical: theme.spacing[1],
     outlineStyle: "none",
   } as object,
-  keyboardCapture: {
-    position: "absolute",
-    width: 1,
-    height: 1,
-    opacity: 0,
-  },
   results: { flexGrow: 0, flexShrink: 1, minHeight: 0 },
   resultsContent: { paddingVertical: theme.spacing[2] },
   row: {
diff --git a/packages/app/src/components/archived-agent-callout.tsx b/packages/app/src/components/archived-agent-callout.tsx
index ed29423173..668731cec5 100644
--- a/packages/app/src/components/archived-agent-callout.tsx
+++ b/packages/app/src/components/archived-agent-callout.tsx
@@ -46,7 +46,6 @@ export function ArchivedAgentCallout({ serverId, agentId }: ArchivedAgentCallout
             <View style={styles.callout}>
               <Text style={styles.calloutText}>{t("agentPanel.archived.callout")}</Text>
               <Button
-                size="sm"
                 variant="secondary"
                 onPress={handleUnarchive}
                 disabled={!isConnected || isUnarchiving}
diff --git a/packages/app/src/components/attachment-lightbox.test.tsx b/packages/app/src/components/attachment-lightbox.test.tsx
index 82fe6b139f..4920195258 100644
--- a/packages/app/src/components/attachment-lightbox.test.tsx
+++ b/packages/app/src/components/attachment-lightbox.test.tsx
@@ -11,6 +11,7 @@ const { theme, imageMetadata, useAttachmentPreviewUrlMock } = vi.hoisted(() => {
     spacing: { 1: 4, 2: 8, 3: 12, 4: 16 },
     iconSize: { sm: 14, md: 18, lg: 22 },
     borderWidth: { 1: 1 },
+    opacity: { 50: 0.5 },
     borderRadius: { full: 999, md: 6, lg: 8 },
     fontSize: { xs: 11, sm: 13, base: 15 },
     fontWeight: { normal: "400" },
diff --git a/packages/app/src/components/attachment-lightbox.tsx b/packages/app/src/components/attachment-lightbox.tsx
index 08c6042bf8..29ad351976 100644
--- a/packages/app/src/components/attachment-lightbox.tsx
+++ b/packages/app/src/components/attachment-lightbox.tsx
@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
 import { Pressable, Text, View } from "react-native";
@@ -8,12 +9,12 @@ import { X } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import type { AttachmentMetadata } from "@/attachments/types";
 import { useAttachmentPreviewUrl } from "@/attachments/use-attachment-preview-url";
-import { isNative, isWeb } from "@/constants/platform";
+import { isNative } from "@/constants/platform";
 import { SPACING } from "@/styles/theme";
 import { WindowChromeRootRegion } from "@/utils/desktop-window";
 import { ZoomableImage } from "@/components/zoomable-viewport/image";
 import type { ViewportSize } from "@/components/zoomable-viewport/geometry";
-import { useGlobalWebOverlayLayer, useWebOverlayRegistration } from "@/lib/overlay-root";
+import { useGlobalOverlayLayer } from "@/lib/overlay-root";
 
 export type ImageLightboxSource =
   | { type: "attachment"; metadata: AttachmentMetadata }
@@ -34,14 +35,14 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
   const url = source?.type === "uri" ? source.uri : attachmentUrl;
   const contentSize = source?.type === "uri" ? source.contentSize : undefined;
   const [errored, setErrored] = useState(false);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && source !== null);
+  const modalLayer = useGlobalOverlayLayer("modal", source !== null);
 
   useEffect(() => {
     setErrored(false);
   }, [metadata?.id, url]);
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key !== "Escape") return false;
       event.preventDefault();
       event.stopPropagation();
@@ -50,10 +51,11 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && source !== null,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: source !== null,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   const actions = useMemo(
@@ -83,7 +85,7 @@ export function AttachmentLightbox({ source, onClose }: AttachmentLightboxProps)
             image was opened (inside a sheet tab, the bottom one is already spent). */}
         <SafeAreaProvider>
           <WindowChromeRootRegion corners="both">
-            <View ref={setWebOverlayScope} style={styles.root}>
+            <View ref={setOverlayScope} style={styles.root}>
               <Pressable
                 testID="attachment-lightbox-backdrop"
                 accessibilityRole="button"
diff --git a/packages/app/src/components/branch-switcher.tsx b/packages/app/src/components/branch-switcher.tsx
index 737035d540..2b23ff775e 100644
--- a/packages/app/src/components/branch-switcher.tsx
+++ b/packages/app/src/components/branch-switcher.tsx
@@ -41,7 +41,15 @@ export function BranchSwitcher({
   const toast = useToast();
   const queryClient = useQueryClient();
 
-  const { branchOptions, isOpen, setIsOpen, handleBranchSelect } = useBranchSwitcher({
+  const {
+    branchOptions,
+    isLoadingBranches,
+    isFetchingBranches,
+    branchError,
+    isOpen,
+    setIsOpen,
+    handleBranchSelect,
+  } = useBranchSwitcher({
     client,
     normalizedServerId: serverId,
     normalizedWorkspaceId: workspaceId,
@@ -73,6 +81,22 @@ export function BranchSwitcher({
     [branchLeadingSlot],
   );
 
+  let emptyText = t("branchSwitcher.empty");
+  if (isLoadingBranches) emptyText = t("common.states.loading");
+  else if (branchError) emptyText = "";
+
+  const errorFooter = useMemo(
+    () =>
+      branchError ? (
+        <View style={styles.footer}>
+          <Text accessibilityRole="alert" style={styles.error}>
+            {isFetchingBranches ? t("common.states.loading") : t("branchSwitcher.failedToLoad")}
+          </Text>
+        </View>
+      ) : undefined,
+    [branchError, isFetchingBranches, t],
+  );
+
   if (!currentBranchName) {
     return null;
   }
@@ -85,6 +109,7 @@ export function BranchSwitcher({
             testID={testID}
             label={currentBranchName}
             open={isOpen}
+            disabled={!isConnected}
             onPress={handleOpen}
             accessibilityRole="button"
             accessibilityLabel={t("branchSwitcher.currentBranch", {
@@ -103,7 +128,8 @@ export function BranchSwitcher({
         searchable
         placeholder={t("branchSwitcher.placeholder")}
         searchPlaceholder={t("branchSwitcher.searchPlaceholder")}
-        emptyText={t("branchSwitcher.empty")}
+        emptyText={emptyText}
+        footer={errorFooter}
         title={t("branchSwitcher.title")}
         open={isOpen}
         onOpenChange={setIsOpen}
@@ -122,6 +148,8 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 1,
     minWidth: 0,
   },
+  footer: { padding: theme.spacing[3], gap: theme.spacing[2] },
+  error: { color: theme.colors.destructive, fontSize: theme.fontSize.sm },
   tooltipText: {
     color: theme.colors.popoverForeground,
     fontSize: theme.fontSize.sm,
diff --git a/packages/app/src/components/combined-model-selector.tsx b/packages/app/src/components/combined-model-selector.tsx
index 8473760c92..05b118b866 100644
--- a/packages/app/src/components/combined-model-selector.tsx
+++ b/packages/app/src/components/combined-model-selector.tsx
@@ -13,6 +13,11 @@ import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
+import {
+  TOOLBAR_GLYPH_SIZES,
+  toolbarContentSlot,
+  type ToolbarGlyph,
+} from "@/components/ui/control-geometry";
 
 const EMPTY_COMBOBOX_OPTIONS: ComboboxOption[] = [];
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
@@ -60,7 +65,7 @@ interface CombinedModelSelectorProps {
    */
   triggerFill?: boolean;
   toolbar?: {
-    glyphSize: number;
+    glyph: ToolbarGlyph;
     showCaret: boolean;
   };
 }
@@ -252,11 +257,13 @@ export function CombinedModelSelector({
           chevron={toolbar?.showCaret === false ? null : undefined}
         >
           {selectedProvider.trim().length > 0 ? (
-            <View style={toolbar?.glyphSize === 20 ? styles.toolbarGlyph20 : styles.toolbarGlyph16}>
+            <View style={toolbar ? styles.toolbarGlyph : styles.glyph}>
               <ModelProviderGlyph
                 provider={selectedProvider}
                 serverId={serverId}
-                size={toolbar?.glyphSize ?? ICON_SIZE.md}
+                size={toolbar?.glyph.size ?? ICON_SIZE.md}
+                strokeWidth={toolbar?.glyph.strokeWidth}
+                tone={toolbar?.glyph.tone}
               />
             </View>
           ) : null}
@@ -292,31 +299,30 @@ const styles = StyleSheet.create((theme) => ({
     paddingHorizontal: 0,
   },
   trigger: {
-    height: 28,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
     alignItems: "center",
     backgroundColor: "transparent",
     gap: theme.spacing[1],
-    paddingHorizontal: theme.spacing[2],
-    borderRadius: theme.borderRadius["2xl"],
+    ...toolbarContentSlot(),
+    borderRadius: theme.borderRadius.full,
   },
   triggerHovered: {
     backgroundColor: theme.colors.surface2,
   },
-  toolbarGlyph16: {
-    width: 16,
-    height: 16,
+  glyph: {
+    width: ICON_SIZE.md,
+    height: ICON_SIZE.md,
     flexShrink: 0,
   },
-  toolbarGlyph20: {
-    width: 20,
-    height: 20,
+  toolbarGlyph: {
+    width: TOOLBAR_GLYPH_SIZES.label,
+    height: TOOLBAR_GLYPH_SIZES.label,
     flexShrink: 0,
   },
   triggerPressed: {
-    backgroundColor: theme.colors.surface0,
+    backgroundColor: theme.colors.surface2,
   },
   triggerDisabled: {
     opacity: 0.5,
@@ -328,6 +334,7 @@ const styles = StyleSheet.create((theme) => ({
     fontSize: theme.fontSize.base,
     fontWeight: theme.fontWeight.normal,
   },
+  // A custom trigger, such as a form field, owns its own box: none of the toolbar slot applies.
   customTriggerWrapper: {
     paddingHorizontal: 0,
     paddingVertical: 0,
diff --git a/packages/app/src/components/community-links.tsx b/packages/app/src/components/community-links.tsx
index bbecedc8d2..1c177da4d8 100644
--- a/packages/app/src/components/community-links.tsx
+++ b/packages/app/src/components/community-links.tsx
@@ -27,7 +27,6 @@ export function CommunityLinks() {
     <View style={styles.row}>
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={renderGitHubIcon}
         onPress={handleOpenGitHub}
         testID="community-links-github-star"
@@ -36,7 +35,6 @@ export function CommunityLinks() {
       </Button>
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={Heart}
         onPress={handleOpenSponsor}
         testID="community-links-sponsor"
@@ -45,7 +43,6 @@ export function CommunityLinks() {
       </Button>
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={renderDiscordIcon}
         onPress={handleOpenDiscord}
         testID="community-links-discord"
@@ -59,6 +56,9 @@ export function CommunityLinks() {
 const styles = StyleSheet.create(() => ({
   row: {
     flexDirection: "row",
+    // Shrinks and wraps rather than running off a narrow phone screen.
+    flexShrink: 1,
+    flexWrap: "wrap",
     justifyContent: "center",
     alignItems: "center",
     gap: 0,
diff --git a/packages/app/src/components/context-window-meter.tsx b/packages/app/src/components/context-window-meter.tsx
index 32c739c073..e0ed5b22a8 100644
--- a/packages/app/src/components/context-window-meter.tsx
+++ b/packages/app/src/components/context-window-meter.tsx
@@ -1,5 +1,11 @@
 import { useCallback, useMemo, useState } from "react";
-import { Pressable, Text, View, useWindowDimensions } from "react-native";
+import {
+  Pressable,
+  type PressableStateCallbackType,
+  Text,
+  View,
+  useWindowDimensions,
+} from "react-native";
 import Svg, { Circle } from "react-native-svg";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
@@ -9,6 +15,7 @@ import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
 import { useHostReportsUsage } from "@/usage";
 import type { Theme } from "@/styles/theme";
+import { TOOLBAR_DISC_SIZE, type ToolbarRing } from "@/components/ui/control-geometry";
 import { ContextWindowDetails } from "./context-window-details";
 import { ContextWindowSheet } from "./context-window-sheet";
 import { formatContextPercentage } from "./context-window-meter.utils";
@@ -20,8 +27,8 @@ interface ContextWindowMeterProps {
   usedTokens: number | null;
   totalCostUsd?: number | null;
   showPercentage?: boolean;
-  /** Optional glyph envelope for icon-toolbar alignment. */
-  glyphSize?: number;
+  /** The ring's box and stroke when it sits in an icon toolbar. */
+  toolbarRing?: ToolbarRing;
 }
 
 const SVG_SIZE = 14;
@@ -70,7 +77,7 @@ function getProgressColor(percentage: number, theme: Theme): string {
   return theme.colors.foregroundMuted;
 }
 
-function getMeterGeometry(showPercentage: boolean, glyphSize?: number) {
+function getMeterGeometry(showPercentage: boolean, ring?: ToolbarRing) {
   if (showPercentage) {
     return {
       svgSize: COMPACT_SVG_SIZE,
@@ -79,8 +86,8 @@ function getMeterGeometry(showPercentage: boolean, glyphSize?: number) {
       containerStyle: styles.containerWithLabel,
     };
   }
-  const resolvedSize = glyphSize ?? SVG_SIZE;
-  const resolvedStrokeWidth = glyphSize ? 2 : STROKE_WIDTH;
+  const resolvedSize = ring?.size ?? SVG_SIZE;
+  const resolvedStrokeWidth = ring?.strokeWidth ?? STROKE_WIDTH;
   return {
     svgSize: resolvedSize,
     radius: (resolvedSize - resolvedStrokeWidth) / 2,
@@ -150,7 +157,7 @@ export function ContextWindowMeter({
   usedTokens,
   totalCostUsd,
   showPercentage = false,
-  glyphSize,
+  toolbarRing,
 }: ContextWindowMeterProps) {
   const { t, i18n } = useTranslation();
   const { width } = useWindowDimensions();
@@ -164,7 +171,7 @@ export function ContextWindowMeter({
   const closeSheet = useCallback(() => setIsSheetOpen(false), []);
   const percentage =
     maxTokens !== null && usedTokens !== null ? getUsagePercentage(maxTokens, usedTokens) : null;
-  const geometry = getMeterGeometry(showPercentage, glyphSize);
+  const geometry = getMeterGeometry(showPercentage, toolbarRing);
 
   const context = useMemo(
     () =>
@@ -183,6 +190,10 @@ export function ContextWindowMeter({
   const formattedSessionCost =
     typeof totalCostUsd === "number" ? formatSessionCost(totalCostUsd) : null;
   const containerStyle = geometry.containerStyle;
+  const pressableStyle = useCallback(
+    ({ pressed }: PressableStateCallbackType) => [containerStyle, pressed && styles.pressed],
+    [containerStyle],
+  );
   const ring = (
     <ContextWindowRing
       size={geometry.svgSize}
@@ -206,7 +217,7 @@ export function ContextWindowMeter({
     return (
       <>
         <Pressable
-          style={containerStyle}
+          style={pressableStyle}
           testID="context-window-meter"
           accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
@@ -240,7 +251,7 @@ export function ContextWindowMeter({
       <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile>
         <TooltipTrigger asChild triggerRefProp="ref">
           <Pressable
-            style={containerStyle}
+            style={pressableStyle}
             testID="context-window-meter"
             accessibilityRole="image"
             accessibilityLabel={accessibilityLabel}
@@ -306,20 +317,23 @@ export function ContextWindowMeter({
 
 const styles = StyleSheet.create((theme) => ({
   container: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
   containerWithLabel: {
-    height: 28,
+    height: TOOLBAR_DISC_SIZE,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
     gap: theme.spacing[1],
     borderRadius: theme.borderRadius.full,
   },
+  pressed: {
+    backgroundColor: theme.colors.surface2,
+  },
   percentageLabel: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/components/desktop-sidebar-layout.test.ts b/packages/app/src/components/desktop-sidebar-layout.test.ts
index 969bbb581f..41a663a9e3 100644
--- a/packages/app/src/components/desktop-sidebar-layout.test.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.test.ts
@@ -1,13 +1,99 @@
 import { describe, expect, it } from "vitest";
+import {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+  type WindowLayout,
+} from "@/window-layout";
 import {
   canDesktopAppSidebarShare,
   resolveDesktopAppChromeLayout,
   resolveDesktopAppContentMinimum,
+  resolveDesktopSidebarInsetLeft,
   resolveDesktopSidebarVisibility,
+  resolveSidebarActivity,
   resolveDesktopSidebarWidth,
+  resolveLeftSidebarPresentation,
 } from "@/components/desktop-sidebar-layout";
 
 describe("desktop sidebar layout", () => {
+  const geometry: WindowLayout = {
+    bounds: { x: 0, y: 0, width: 951, height: 669 },
+    verticalBarEdge: "trailing",
+    verticalBar: { x: 875, y: 160, width: 44, height: 450 },
+    divisions: [{ x: 465, y: 0, width: 21, height: 669 }],
+  };
+
+  it("places workspace action symbols in the reported trailing bar", () => {
+    expect(resolveWorkspaceActionPlacement(geometry)).toBe("vertical-bar");
+    expect(resolveWorkspaceActionPlacement(null)).toBe("header");
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBarEdge: "none" })).toBe(
+      "header",
+    );
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBar: null })).toBe("header");
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBarEdge: "leading" })).toBe(
+      "header",
+    );
+  });
+
+  it("shows the tab count only for the compact header selection", () => {
+    expect(resolveWorkspaceBarActions("compact")).toEqual(["tab-count", "overflow", "explorer"]);
+    expect(resolveWorkspaceBarActions("full")).toEqual(["overflow", "explorer"]);
+  });
+
+  it("allocates both panels around a live division without clamping to saved sidebar widths", () => {
+    const input = {
+      geometry,
+      windowWidth: 951,
+      windowHeight: 669,
+      leftInset: 0,
+      rightInset: 84,
+    };
+    expect(resolveDesktopDivisionLayout(input)).toEqual({
+      sidebarWidth: 465,
+      gap: 21,
+      contentWidth: 381,
+    });
+    expect(
+      resolveDesktopDivisionLayout({ ...input, geometry: { ...geometry, divisions: [] } }),
+    ).toBeNull();
+    expect(
+      resolveDesktopDivisionLayout({ ...input, windowWidth: 669, windowHeight: 951 }),
+    ).toBeNull();
+    expect(resolveDesktopDivisionLayout({ ...input, geometry: null })).toBeNull();
+    expect(
+      resolveDesktopDivisionLayout({
+        ...input,
+        geometry: { ...geometry, divisions: [{ x: 0, y: 325, width: 951, height: 19 }] },
+      }),
+    ).toBeNull();
+  });
+
+  it("activates a revealed folded sidebar while preserving closed desktop intent", () => {
+    expect(resolveSidebarActivity(true, false, false)).toBe(true);
+    expect(resolveSidebarActivity(false, false, false)).toBe(false);
+    expect(resolveSidebarActivity(true, true, false)).toBe(false);
+    expect(resolveSidebarActivity(true, true, true)).toBe(true);
+  });
+
+  it("temporarily reveals navigation for a division without changing the saved closed intent", () => {
+    const visibility = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isMounted: true,
+      isOpen: false,
+      canShare: false,
+    };
+    expect(
+      resolveDesktopSidebarVisibility({
+        ...visibility,
+        divisionLayout: { sidebarWidth: 465, gap: 21, contentWidth: 381 },
+      }),
+    ).toBe(true);
+    expect(resolveDesktopSidebarVisibility({ ...visibility, divisionLayout: null })).toBe(false);
+    expect(visibility.isOpen).toBe(false);
+  });
+
   it("keeps a retained sidebar hidden while app chrome is suppressed", () => {
     expect(
       resolveDesktopSidebarVisibility({
@@ -20,6 +106,40 @@ describe("desktop sidebar layout", () => {
     ).toBe(false);
   });
 
+  it("offers an overlay only after wide navigation yields its dock", () => {
+    const input = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isFocusModeEnabled: false,
+    };
+    expect(resolveLeftSidebarPresentation({ ...input, desktopSidebarVisible: true })).toBe("dock");
+    expect(resolveLeftSidebarPresentation({ ...input, desktopSidebarVisible: false })).toBe(
+      "overlay",
+    );
+  });
+
+  it("does not reveal navigation over a focused workspace or suppressed chrome", () => {
+    const input = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isFocusModeEnabled: false,
+      desktopSidebarVisible: false,
+    };
+    expect(resolveLeftSidebarPresentation({ ...input, isFocusModeEnabled: true })).toBe("hidden");
+    expect(resolveLeftSidebarPresentation({ ...input, chromeEnabled: false })).toBe("hidden");
+  });
+
+  it("keeps phone navigation available independently of saved wide focus mode", () => {
+    expect(
+      resolveLeftSidebarPresentation({
+        chromeEnabled: true,
+        isCompactLayout: true,
+        isFocusModeEnabled: true,
+        desktopSidebarVisible: false,
+      }),
+    ).toBe("overlay");
+  });
+
   it("keeps the sidebar toggle window-owned beside left window controls", () => {
     expect(
       resolveDesktopAppChromeLayout({
@@ -123,3 +243,8 @@ it("reserves room for Explorer and the workspace before showing app navigation",
     }),
   ).toBe(true);
 });
+
+it("insets an overlay sidebar's content by the left safe area and leaves the dock to app chrome", () => {
+  expect(resolveDesktopSidebarInsetLeft({ overlay: true, safeAreaLeft: 20 })).toBe(20);
+  expect(resolveDesktopSidebarInsetLeft({ overlay: false, safeAreaLeft: 20 })).toBe(0);
+});
diff --git a/packages/app/src/components/desktop-sidebar-layout.ts b/packages/app/src/components/desktop-sidebar-layout.ts
index d8518bcb82..692934d73e 100644
--- a/packages/app/src/components/desktop-sidebar-layout.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.ts
@@ -1,6 +1,11 @@
 import { EXPLORER_WORKSPACE_MIN_WIDTH } from "@/components/explorer-sidebar-layout";
 import { SETTINGS_DESKTOP_SPLIT_MIN_WIDTH } from "@/constants/layout";
-import { MAX_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+import {
+  MAX_SIDEBAR_WIDTH,
+  MIN_SIDEBAR_WIDTH,
+  type LeftSidebarPresentation,
+} from "@/stores/panel-store";
+import type { DesktopDivisionLayout } from "@/window-layout";
 
 const MIN_DESKTOP_CENTER_WIDTH = 400;
 
@@ -10,16 +15,43 @@ export function resolveDesktopSidebarVisibility(input: {
   isMounted: boolean;
   isOpen: boolean;
   canShare: boolean;
+  divisionLayout?: DesktopDivisionLayout | null;
 }): boolean {
   return (
     input.chromeEnabled &&
     !input.isCompactLayout &&
     input.isMounted &&
-    input.isOpen &&
-    input.canShare
+    (input.divisionLayout != null || (input.isOpen && input.canShare))
   );
 }
 
+/**
+ * Compact layouts always present navigation as a drawer overlay. Wide layouts dock it when it is
+ * visible and fall back to an overlay when the dock is collapsed or yields its width.
+ */
+export function resolveLeftSidebarPresentation(input: {
+  chromeEnabled: boolean;
+  isCompactLayout: boolean;
+  isFocusModeEnabled: boolean;
+  desktopSidebarVisible: boolean;
+}): LeftSidebarPresentation {
+  if (!input.chromeEnabled) return "hidden";
+  if (input.isCompactLayout) return "overlay";
+  if (input.isFocusModeEnabled) return "hidden";
+  return input.desktopSidebarVisible ? "dock" : "overlay";
+}
+
+/**
+ * The overlay sidebar starts at the window's left edge, over the workspace's safe-area padding, so
+ * its content takes the left inset itself. The dock sits inside app chrome, which already pads it.
+ */
+export function resolveDesktopSidebarInsetLeft(input: {
+  overlay: boolean;
+  safeAreaLeft: number;
+}): number {
+  return input.overlay ? input.safeAreaLeft : 0;
+}
+
 export function resolveDesktopAppChromeLayout(input: {
   desktopSidebarRendered: boolean;
   hasTopLeftWindowControls: boolean;
@@ -85,3 +117,11 @@ export function canDesktopAppSidebarShare(input: {
     input.contentMinimumWidth
   );
 }
+
+export function resolveSidebarActivity(
+  visible: boolean,
+  compact: boolean,
+  mobileActive: boolean,
+): boolean {
+  return visible && (!compact || mobileActive);
+}
diff --git a/packages/app/src/components/direct-connection-host.test.ts b/packages/app/src/components/direct-connection-host.test.ts
new file mode 100644
index 0000000000..0a2411215a
--- /dev/null
+++ b/packages/app/src/components/direct-connection-host.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { buildDirectConnectionUri, normalizeDirectConnectionHost } from "./direct-connection-host";
+
+const labels = {
+  hostRequired: "host required",
+  invalidPort: "invalid port",
+};
+
+function buildUri(host: string, port = "6767"): string {
+  return buildDirectConnectionUri({ host, port, useTls: false, password: "" }, labels);
+}
+
+describe("normalizeDirectConnectionHost", () => {
+  it.each([
+    ["100.66.69.36", { host: "100.66.69.36", port: null, isIpv6: false }],
+    ["  100.66.69.36  ", { host: "100.66.69.36", port: null, isIpv6: false }],
+    ["100.66.69.36:6767", { host: "100.66.69.36", port: "6767", isIpv6: false }],
+    ["tcp://100.66.69.36:6767", { host: "100.66.69.36", port: "6767", isIpv6: false }],
+    ["http://100.66.69.36:6767/path?x=1#y", { host: "100.66.69.36", port: "6767", isIpv6: false }],
+    ["HTTPS://example.test", { host: "example.test", port: null, isIpv6: false }],
+    ["my-host.local:7000", { host: "my-host.local", port: "7000", isIpv6: false }],
+    ["[::1]", { host: "::1", port: null, isIpv6: true }],
+    ["[::1]:7000", { host: "::1", port: "7000", isIpv6: true }],
+    ["::1", { host: "::1", port: null, isIpv6: true }],
+    ["fe80::1", { host: "fe80::1", port: null, isIpv6: true }],
+    ["", { host: "", port: null, isIpv6: false }],
+  ])("normalizes %j", (input, expected) => {
+    expect(normalizeDirectConnectionHost(input)).toEqual(expected);
+  });
+});
+
+describe("buildDirectConnectionUri", () => {
+  it.each([
+    ["100.66.69.36", "tcp://100.66.69.36:6767"],
+    ["100.66.69.36:6767", "tcp://100.66.69.36:6767"],
+    ["tcp://100.66.69.36:6767", "tcp://100.66.69.36:6767"],
+    ["http://100.66.69.36:6767/path?x", "tcp://100.66.69.36:6767"],
+    ["my-host.local:6767", "tcp://my-host.local:6767"],
+    ["[::1]", "tcp://[::1]:6767"],
+    ["[::1]:7000", "tcp://[::1]:7000"],
+    ["::1", "tcp://[::1]:6767"],
+    ["fe80::1", "tcp://[fe80::1]:6767"],
+  ])("builds a tcp URI from host %j", (host, expected) => {
+    expect(buildUri(host)).toBe(expected);
+  });
+
+  it("lets a port typed in the host field override the port field", () => {
+    expect(buildUri("100.66.69.36:7000", "6767")).toBe("tcp://100.66.69.36:7000");
+  });
+
+  it("keeps TLS and password settings", () => {
+    expect(
+      buildDirectConnectionUri(
+        { host: "tcp://example.test:443", port: "6767", useTls: true, password: "secret" },
+        labels,
+      ),
+    ).toBe("tcp://example.test:443?ssl=true&password=secret");
+  });
+
+  it.each(["", "   ", "tcp://", "http:///path"])("requires a host for %j", (host) => {
+    expect(() => buildUri(host)).toThrow("host required");
+  });
+
+  it("rejects an invalid port", () => {
+    expect(() => buildUri("100.66.69.36", "70000")).toThrow("invalid port");
+    expect(() => buildUri("100.66.69.36:0")).toThrow("invalid port");
+  });
+});
diff --git a/packages/app/src/components/direct-connection-host.ts b/packages/app/src/components/direct-connection-host.ts
new file mode 100644
index 0000000000..db694dd7c2
--- /dev/null
+++ b/packages/app/src/components/direct-connection-host.ts
@@ -0,0 +1,70 @@
+import { serializeConnectionUriForStorage } from "@/utils/daemon-endpoints";
+
+export interface DirectConnectionHostInput {
+  host: string;
+  port: string;
+  useTls: boolean;
+  password: string;
+}
+
+export interface DirectConnectionHostLabels {
+  hostRequired: string;
+  invalidPort: string;
+}
+
+export interface NormalizedDirectConnectionHost {
+  host: string;
+  /** Port typed into the host field, if any. Overrides the separate port field. */
+  port: string | null;
+  isIpv6: boolean;
+}
+
+const SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+const BRACKETED_IPV6_PATTERN = /^\[([^\]]*)\](?::(\d*))?$/;
+const HOST_WITH_PORT_PATTERN = /^([^:]+):(\d+)$/;
+
+/**
+ * Users often paste `host:port` or a full URL into the host field.
+ * Reduce it to a bare host (plus an optional port) before building the URI.
+ */
+export function normalizeDirectConnectionHost(input: string): NormalizedDirectConnectionHost {
+  let host = input.trim().replace(SCHEME_PATTERN, "");
+  const suffixIndex = host.search(/[/?#]/);
+  if (suffixIndex !== -1) {
+    host = host.slice(0, suffixIndex);
+  }
+
+  const bracketed = BRACKETED_IPV6_PATTERN.exec(host);
+  if (bracketed) {
+    return { host: bracketed[1] ?? "", port: bracketed[2] || null, isIpv6: true };
+  }
+
+  const hostWithPort = HOST_WITH_PORT_PATTERN.exec(host);
+  if (hostWithPort) {
+    return { host: hostWithPort[1] ?? "", port: hostWithPort[2] ?? null, isIpv6: false };
+  }
+
+  return { host, port: null, isIpv6: host.split(":").length > 2 };
+}
+
+export function buildDirectConnectionUri(
+  draft: DirectConnectionHostInput,
+  labels: DirectConnectionHostLabels,
+): string {
+  const normalized = normalizeDirectConnectionHost(draft.host);
+  const port = Number((normalized.port ?? draft.port).trim());
+  if (!normalized.host) {
+    throw new Error(labels.hostRequired);
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(labels.invalidPort);
+  }
+
+  return serializeConnectionUriForStorage({
+    host: normalized.host,
+    port,
+    isIpv6: normalized.isIpv6,
+    useTls: draft.useTls,
+    ...(draft.password ? { password: draft.password } : {}),
+  });
+}
diff --git a/packages/app/src/components/explorer-sidebar-layout.test.ts b/packages/app/src/components/explorer-sidebar-layout.test.ts
index 3681ad4e16..adad890abe 100644
--- a/packages/app/src/components/explorer-sidebar-layout.test.ts
+++ b/packages/app/src/components/explorer-sidebar-layout.test.ts
@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest";
 import {
+  beginExplorerSidebarResize,
+  finishExplorerSidebarResize,
+  reconcileExplorerSidebarResize,
   resolveExplorerSidebarDockSizes,
+  resolveExplorerSidebarFrameWidth,
   resolveExplorerSidebarWidth,
+  type ExplorerSidebarResize,
 } from "@/components/explorer-sidebar-layout";
 
 describe("Explorer sidebar layout", () => {
@@ -19,4 +24,196 @@ describe("Explorer sidebar layout", () => {
     expect(resolveExplorerSidebarWidth({ requestedWidth: 900, containerWidth: 1200 })).toBe(840);
     expect(resolveExplorerSidebarWidth({ requestedWidth: 600, containerWidth: 750 })).toBe(390);
   });
+
+  describe("native resize ownership", () => {
+    const allocation = {
+      width: 320,
+      containerWidth: 1200,
+      overlay: false,
+      resizeEnabled: true,
+    };
+    const dragging: ExplorerSidebarResize = {
+      sourceWidths: [allocation.width],
+      restoreWidth: allocation.width,
+      containerWidth: allocation.containerWidth,
+      pendingWidth: null,
+    };
+
+    it.each([false, true])(
+      "keeps a second drag through the previous release acknowledgement (released=%s)",
+      (releaseSecond) => {
+        const first = finishExplorerSidebarResize(dragging, 480, true);
+        const second = beginExplorerSidebarResize(first, allocation);
+        const current = releaseSecond ? finishExplorerSidebarResize(second, 600, true) : second;
+        const acknowledged = reconcileExplorerSidebarResize(current, { ...allocation, width: 480 });
+        expect(
+          resolveExplorerSidebarFrameWidth({
+            ...allocation,
+            width: 480,
+            resize: acknowledged,
+            resizeWidth: 600,
+          }),
+        ).toBe(600);
+        const released = finishExplorerSidebarResize(acknowledged, 600, true);
+        expect(released?.pendingWidth).toBe(600);
+        expect(reconcileExplorerSidebarResize(released, { ...allocation, width: 600 })).toBeNull();
+      },
+    );
+
+    it("keeps a return to the minimum while an earlier wider release is acknowledged", () => {
+      const initial = { ...allocation, width: 240 };
+      const wider = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(null, initial),
+        540,
+        true,
+      );
+      const returned = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(wider, initial),
+        240,
+        true,
+      );
+      const awaiting = reconcileExplorerSidebarResize(returned, initial);
+      const intermediate = reconcileExplorerSidebarResize(awaiting, { ...initial, width: 540 });
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...initial,
+          width: 540,
+          resize: intermediate,
+          resizeWidth: 240,
+        }),
+      ).toBe(240);
+      expect(reconcileExplorerSidebarResize(intermediate, initial)).toBeNull();
+    });
+
+    it("cancels back to the latest release when earlier widths repeat", () => {
+      const first = finishExplorerSidebarResize(dragging, 480, true);
+      const second = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(first, allocation),
+        600,
+        true,
+      );
+      const third = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(second, allocation),
+        480,
+        true,
+      );
+      const fourth = beginExplorerSidebarResize(third, allocation);
+      const canceled = finishExplorerSidebarResize(fourth, 700, false);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 700 }),
+      ).toBe(480);
+    });
+
+    it("cancels a newer gesture back to its last released width", () => {
+      const first = finishExplorerSidebarResize(dragging, 480, true);
+      const second = beginExplorerSidebarResize(first, allocation);
+      const canceled = finishExplorerSidebarResize(second, 600, false);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 600 }),
+      ).toBe(480);
+      expect(reconcileExplorerSidebarResize(canceled, { ...allocation, width: 480 })).toBeNull();
+    });
+
+    it("keeps the drag width after release while the JS commit still has the old prop", () => {
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: dragging, resizeWidth: 480 }),
+      ).toBe(480);
+
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      expect(reconcileExplorerSidebarResize(released, allocation)).toBe(released);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: released, resizeWidth: 480 }),
+      ).toBe(480);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: released, resizeWidth: 320 }),
+      ).toBe(480);
+    });
+
+    it("acknowledges the committed width and immediately follows subsequent props", () => {
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      const acknowledgedAllocation = { ...allocation, width: 480 };
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...acknowledgedAllocation,
+          resize: released,
+          resizeWidth: 480,
+        }),
+      ).toBe(480);
+      const acknowledged = reconcileExplorerSidebarResize(released, acknowledgedAllocation);
+      expect(acknowledged).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...allocation,
+          width: 360,
+          resize: acknowledged,
+          resizeWidth: 480,
+        }),
+      ).toBe(360);
+    });
+
+    it.each([
+      { name: "a new width prop", next: { ...allocation, width: 360 }, expected: 360 },
+      {
+        name: "a window allocation with an unchanged width prop",
+        next: { ...allocation, containerWidth: 900 },
+        expected: 320,
+      },
+      {
+        name: "a window allocation that clamps the width prop",
+        next: { ...allocation, width: 540, containerWidth: 900 },
+        expected: 540,
+      },
+      { name: "overlay presentation", next: { ...allocation, overlay: true }, expected: 1200 },
+      { name: "an inactive dock", next: { ...allocation, resizeEnabled: false }, expected: 320 },
+    ])(
+      "yields synchronously to $name and does not resurrect the old handoff",
+      ({ next, expected }) => {
+        const released = finishExplorerSidebarResize(dragging, 600, true);
+        expect(
+          resolveExplorerSidebarFrameWidth({ ...next, resize: released, resizeWidth: 600 }),
+        ).toBe(expected);
+        const interrupted = reconcileExplorerSidebarResize(released, next);
+        expect(interrupted).toBeNull();
+        expect(
+          resolveExplorerSidebarFrameWidth({
+            ...allocation,
+            resize: interrupted,
+            resizeWidth: 600,
+          }),
+        ).toBe(320);
+      },
+    );
+
+    it("restores canonical intent when a drag is canceled", () => {
+      const canceled = finishExplorerSidebarResize(dragging, 480, false);
+      expect(canceled).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 480 }),
+      ).toBe(320);
+    });
+
+    it("cannot finish an interrupted drag over a newer allocation", () => {
+      const next = { ...allocation, width: 360, containerWidth: 1000 };
+      const interrupted = reconcileExplorerSidebarResize(dragging, next);
+      const released = finishExplorerSidebarResize(interrupted, 480, true);
+      expect(released).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...next, resize: released, resizeWidth: 480 }),
+      ).toBe(360);
+    });
+
+    it("settles a release at the already-committed width without retaining ownership", () => {
+      const released = finishExplorerSidebarResize(dragging, allocation.width, true);
+      expect(reconcileExplorerSidebarResize(released, allocation)).toBeNull();
+    });
+
+    it("keeps an earlier released handoff when a later touch fails before activation", () => {
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      const finalized = finishExplorerSidebarResize(released, 480, false);
+      expect(finalized).toBe(released);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: finalized, resizeWidth: 480 }),
+      ).toBe(480);
+    });
+  });
 });
diff --git a/packages/app/src/components/explorer-sidebar-layout.ts b/packages/app/src/components/explorer-sidebar-layout.ts
index 8a39e2e9f4..9bb09600eb 100644
--- a/packages/app/src/components/explorer-sidebar-layout.ts
+++ b/packages/app/src/components/explorer-sidebar-layout.ts
@@ -16,6 +16,85 @@ export function resolveExplorerSidebarWidth(input: {
   return Math.max(MIN_EXPLORER_SIDEBAR_WIDTH, Math.min(maximumVisibleWidth, requestedWidth));
 }
 
+// A release keeps its UI width until React acknowledges it or replaces its allocation.
+// Null pendingWidth means the gesture still owns the live resizeWidth instead.
+export interface ExplorerSidebarResize {
+  sourceWidths: number[];
+  restoreWidth: number;
+  containerWidth: number;
+  pendingWidth: number | null;
+}
+
+interface ExplorerSidebarAllocation {
+  width: number;
+  containerWidth: number;
+  overlay: boolean;
+  resizeEnabled: boolean;
+}
+
+export function reconcileExplorerSidebarResize(
+  resize: ExplorerSidebarResize | null,
+  allocation: ExplorerSidebarAllocation,
+): ExplorerSidebarResize | null {
+  "worklet";
+  if (
+    !resize ||
+    allocation.overlay ||
+    !allocation.resizeEnabled ||
+    allocation.containerWidth !== resize.containerWidth ||
+    !resize.sourceWidths.includes(allocation.width) ||
+    (allocation.width === resize.pendingWidth &&
+      resize.sourceWidths.indexOf(allocation.width) === resize.sourceWidths.length - 1)
+  ) {
+    return null;
+  }
+  const acknowledgedIndex = resize.sourceWidths.indexOf(allocation.width);
+  return acknowledgedIndex > 0
+    ? { ...resize, sourceWidths: resize.sourceWidths.slice(acknowledgedIndex) }
+    : resize;
+}
+
+export function beginExplorerSidebarResize(
+  previous: ExplorerSidebarResize | null,
+  allocation: ExplorerSidebarAllocation,
+): ExplorerSidebarResize {
+  "worklet";
+  const current = reconcileExplorerSidebarResize(previous, allocation);
+  // Released widths remain expected allocations while a newer gesture owns the frame.
+  const sourceWidths = current ? [...current.sourceWidths] : [allocation.width];
+  if (current && current.pendingWidth !== null && !sourceWidths.includes(current.pendingWidth))
+    sourceWidths.push(current.pendingWidth);
+  return {
+    sourceWidths,
+    restoreWidth: current ? (current.pendingWidth ?? current.restoreWidth) : allocation.width,
+    containerWidth: allocation.containerWidth,
+    pendingWidth: null,
+  };
+}
+
+export function finishExplorerSidebarResize(
+  resize: ExplorerSidebarResize | null,
+  width: number,
+  success: boolean,
+): ExplorerSidebarResize | null {
+  "worklet";
+  if (!resize || resize.pendingWidth !== null) return resize;
+  if (success) return { ...resize, pendingWidth: width };
+  return resize.sourceWidths.length > 1 ? { ...resize, pendingWidth: resize.restoreWidth } : null;
+}
+
+export function resolveExplorerSidebarFrameWidth(
+  allocation: ExplorerSidebarAllocation & {
+    resize: ExplorerSidebarResize | null;
+    resizeWidth: number;
+  },
+): number {
+  "worklet";
+  if (allocation.overlay) return allocation.containerWidth;
+  const resize = reconcileExplorerSidebarResize(allocation.resize, allocation);
+  return resize ? (resize.pendingWidth ?? allocation.resizeWidth) : allocation.width;
+}
+
 export function resolveExplorerSidebarDockSizes(input: {
   requestedWidth?: number;
   containerWidth: number;
diff --git a/packages/app/src/components/file-explorer-pane.tsx b/packages/app/src/components/file-explorer-pane.tsx
index 80bc9b0257..2625407d60 100644
--- a/packages/app/src/components/file-explorer-pane.tsx
+++ b/packages/app/src/components/file-explorer-pane.tsx
@@ -64,10 +64,15 @@ import { useIsLocalDaemon } from "@/hooks/use-is-local-daemon";
 import { buildWorkspaceExplorerStateKey } from "@/hooks/use-file-explorer-actions";
 import { usePanelStore, type ExpandedPathsUpdate, type SortOption } from "@/stores/panel-store";
 import { buildAbsoluteExplorerPath } from "@/utils/explorer-paths";
+import {
+  DIRECTORY_LISTING_INVALIDATED,
+  type DirectoryListingResult,
+} from "@/file-explorer/directory-listings";
 import { isHiddenExplorerPath } from "@/file-explorer/visibility";
 import {
   flattenExplorerTree,
   reconcileRestoredExpandedPaths,
+  refreshExplorerDirectories,
   restoreExpandedDirectories,
   setExpandedDirectoryPath,
   showHiddenFilesAndRestoreExpandedDirectories,
@@ -435,6 +440,7 @@ export function FileExplorerPane({
 
   const {
     requestDirectoryListing,
+    invalidateDirectoryListings,
     createEntry,
     renameEntry,
     duplicateEntry,
@@ -886,9 +892,11 @@ export function FileExplorerPane({
       refreshExplorerDirectories({
         hasWorkspaceScope,
         expandedPaths,
+        showHiddenFiles: usePanelStore.getState().explorerShowHiddenFiles,
         requestDirectoryListing,
+        invalidateDirectoryListings,
       }),
-    [expandedPaths, hasWorkspaceScope, requestDirectoryListing],
+    [invalidateDirectoryListings, expandedPaths, hasWorkspaceScope, requestDirectoryListing],
   );
   const { refetch: refetchExplorer, isFetching: isRefreshFetching } = useQuery({
     queryKey: ["fileExplorerRefresh", serverId, workspaceStateKey],
@@ -1424,7 +1432,7 @@ function toggleDirectory({
   requestDirectoryListing: (
     path: string,
     opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<ExplorerDirectory | null>;
+  ) => Promise<DirectoryListingResult>;
   setExpandedPathsForWorkspace: (workspaceStateKey: string, paths: ExpandedPathsUpdate) => void;
 }): void {
   if (!workspaceStateKey) {
@@ -1561,7 +1569,7 @@ async function initializeExplorer({
   requestDirectoryListing: (
     path: string,
     opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<ExplorerDirectory | null>;
+  ) => Promise<DirectoryListingResult>;
   setExpandedPathsForWorkspace: (workspaceStateKey: string, paths: ExpandedPathsUpdate) => void;
 }): Promise<void> {
   if (!hasWorkspaceScope || hasInitializedRef.current) {
@@ -1572,6 +1580,7 @@ async function initializeExplorer({
     recordHistory: false,
     setCurrentPath: false,
   });
+  if (rootDirectory === DIRECTORY_LISTING_INVALIDATED) return;
   if (!rootDirectory) {
     hasInitializedRef.current = false;
     return;
@@ -1593,7 +1602,10 @@ async function initializeExplorer({
   const hiddenPersistedPaths = showHiddenFiles
     ? []
     : Array.from(persistedExpandedPaths).filter(isHiddenExplorerPath);
-  const restoredPathsWithHidden = [...restoredPaths, ...hiddenPersistedPaths];
+  const restoredPathsWithHidden =
+    restoredPaths === DIRECTORY_LISTING_INVALIDATED
+      ? DIRECTORY_LISTING_INVALIDATED
+      : [...restoredPaths, ...hiddenPersistedPaths];
   setExpandedPathsForWorkspace(workspaceStateKey, (currentPaths) =>
     reconcileRestoredExpandedPaths({
       persistedExpandedPaths,
@@ -1603,39 +1615,6 @@ async function initializeExplorer({
   );
 }
 
-async function refreshExplorerDirectories({
-  hasWorkspaceScope,
-  expandedPaths,
-  requestDirectoryListing,
-}: {
-  hasWorkspaceScope: boolean;
-  expandedPaths: Set<string>;
-  requestDirectoryListing: (
-    path: string,
-    opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
-  ) => Promise<ExplorerDirectory | null>;
-}): Promise<null> {
-  if (!hasWorkspaceScope) {
-    return null;
-  }
-  const showHiddenFiles = usePanelStore.getState().explorerShowHiddenFiles;
-  const directoryPaths = Array.from(expandedPaths).filter(
-    (path) => showHiddenFiles || !isHiddenExplorerPath(path),
-  );
-  if (!directoryPaths.includes(".")) {
-    directoryPaths.unshift(".");
-  }
-  await Promise.all(
-    directoryPaths.map((path) =>
-      requestDirectoryListing(path, {
-        recordHistory: false,
-        setCurrentPath: false,
-      }),
-    ),
-  );
-  return null;
-}
-
 function getErrorRecoveryPath(state: AgentFileExplorerState | undefined): string {
   if (!state) {
     return ".";
diff --git a/packages/app/src/components/floating-header/index.tsx b/packages/app/src/components/floating-header/index.tsx
index 6e4cd525f1..cd59ec4d30 100644
--- a/packages/app/src/components/floating-header/index.tsx
+++ b/packages/app/src/components/floating-header/index.tsx
@@ -1,8 +1,26 @@
-import { useCallback, useState, type ReactNode } from "react";
+import { createContext, useContext, useCallback, useState, useId, type ReactNode } from "react";
 import { View, type LayoutChangeEvent } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { Portal, PortalHost } from "@gorhom/portal";
+import { useRetainedPanelActive } from "@/components/retained-panel";
 import { EdgeFade } from "@/components/ui/edge-fade";
 
+const OverlayClearanceContext = createContext(0);
+const OverlayHostContext = createContext<string | null>(null);
+
+/** Keep status overlays above the fade without lifting the scrolling content. */
+export function FloatingHeaderOverlay({ children }: { children: ReactNode }) {
+  const hostName = useContext(OverlayHostContext);
+  const active = useRetainedPanelActive();
+  if (!hostName) return children;
+  return active ? <Portal hostName={hostName}>{children}</Portal> : null;
+}
+
+/** Clearance for stationary overlays inside this layout, measured to the header bottom. */
+export function useFloatingHeaderOverlayClearance(): number {
+  return useContext(OverlayClearanceContext);
+}
+
 /** How far the fade runs past the header's bottom edge, so content dissolves instead of clipping. */
 const FADE_OVERHANG = 48;
 /** Share of the fade that stays opaque, so the header's title and icons keep contrast. */
@@ -20,15 +38,24 @@ interface FloatingHeaderLayoutProps {
  * same tree position in both modes, so toggling `floating` never remounts them.
  */
 export function FloatingHeaderLayout({ header, floating, children }: FloatingHeaderLayoutProps) {
+  const overlayHostName = useId();
   const [headerHeight, setHeaderHeight] = useState(0);
   const handleHeaderLayout = useCallback((event: LayoutChangeEvent) => {
     setHeaderHeight(Math.round(event.nativeEvent.layout.height));
   }, []);
 
+  const overlayClearance = floating ? headerHeight : 0;
+
   return (
     <View style={styles.root}>
       {floating ? null : header}
-      <View style={styles.content}>{children(floating ? headerHeight : 0)}</View>
+      <View style={styles.content}>
+        <OverlayClearanceContext.Provider value={overlayClearance}>
+          <OverlayHostContext.Provider value={floating ? overlayHostName : null}>
+            {children(floating ? headerHeight : 0)}
+          </OverlayHostContext.Provider>
+        </OverlayClearanceContext.Provider>
+      </View>
       {floating ? (
         <View style={styles.overlay} pointerEvents="box-none">
           <EdgeFade
@@ -37,11 +64,19 @@ export function FloatingHeaderLayout({ header, floating, children }: FloatingHea
             backdrop="surfaceWorkspace"
             style={styles.fade}
           />
-          <View pointerEvents="box-none" onLayout={handleHeaderLayout}>
+          <View
+            testID="floating-header"
+            collapsable={false}
+            pointerEvents="box-none"
+            onLayout={handleHeaderLayout}
+          >
             {header}
           </View>
         </View>
       ) : null}
+      <View style={styles.statusOverlay} pointerEvents="box-none">
+        <PortalHost name={overlayHostName} />
+      </View>
     </View>
   );
 }
@@ -55,6 +90,13 @@ const styles = StyleSheet.create({
     flex: 1,
     minHeight: 0,
   },
+  statusOverlay: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0,
+  },
   overlay: {
     position: "absolute",
     top: 0,
diff --git a/packages/app/src/components/headers/compact-header.tsx b/packages/app/src/components/headers/compact-header.tsx
index cbc161ae66..1c3b45e0b3 100644
--- a/packages/app/src/components/headers/compact-header.tsx
+++ b/packages/app/src/components/headers/compact-header.tsx
@@ -12,8 +12,13 @@ import {
   iconButtonChromeGlyphSize,
   mutedIconColorMapping,
 } from "@/components/ui/icon-button-chrome";
-import { HEADER_INNER_HEIGHT_MOBILE, HEADER_TOP_PADDING_MOBILE } from "@/constants/layout";
+import {
+  HEADER_INNER_HEIGHT,
+  HEADER_INNER_HEIGHT_MOBILE,
+  HEADER_TOP_PADDING_MOBILE,
+} from "@/constants/layout";
 import type { ShortcutKey } from "@/utils/format-shortcut";
+import { useTopBand } from "@/window-layout";
 
 const ThemedArrowLeft = withUnistyles(ArrowLeft);
 
@@ -39,7 +44,8 @@ interface CompactHeaderProps {
  * left-aligned between them. Neither the header nor its islands draw a background, so it reads the
  * same in flow and floating over content (see `FloatingHeaderLayout`, whose fade gives the icons
  * contrast). Its height matches the old flat header, so anything
- * offset by the header height still lines up.
+ * offset by the header height still lines up. In a window's top band it takes the top bar's
+ * place, like the full header. The column hosting it reserves any window-chrome corner it owns.
  */
 export function CompactHeader({
   navigation,
@@ -51,22 +57,23 @@ export function CompactHeader({
   actions,
 }: CompactHeaderProps) {
   const insets = useSafeAreaInsets();
+  const inTopBand = useTopBand() !== null;
   const rootStyle = useMemo(
     () => [
       styles.root,
       {
-        paddingTop: insets.top + HEADER_TOP_PADDING_MOBILE,
+        paddingTop: insets.top + (inTopBand ? 0 : HEADER_TOP_PADDING_MOBILE),
         marginLeft: insets.left,
         marginRight: insets.right,
       },
     ],
-    [insets.top, insets.left, insets.right],
+    [inTopBand, insets.top, insets.left, insets.right],
   );
 
   return (
     <IconButtonChromeProvider value="header-island">
       <View style={rootStyle}>
-        <View style={styles.row}>
+        <View style={inTopBand ? styles.topBandRow : styles.row}>
           <View style={styles.island}>
             {navigation === "menu" ? <SidebarMenuToggle /> : <BackButton onBack={onBack} />}
           </View>
@@ -148,6 +155,12 @@ const styles = StyleSheet.create((theme) => ({
     alignItems: "center",
     gap: theme.spacing[2],
   },
+  topBandRow: {
+    height: HEADER_INNER_HEIGHT,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
   titleGroup: {
     flex: 1,
     minWidth: 0,
diff --git a/packages/app/src/components/highlighted-code-block.tsx b/packages/app/src/components/highlighted-code-block.tsx
index 292ec53618..9b7939daf1 100644
--- a/packages/app/src/components/highlighted-code-block.tsx
+++ b/packages/app/src/components/highlighted-code-block.tsx
@@ -46,6 +46,7 @@ const LANGUAGE_ALIASES: Record<string, string> = {
   "objective-c": "m",
   markdown: "md",
   elixir: "ex",
+  terraform: "tf",
 };
 
 function fenceLanguageToExtension(info: string | null | undefined): string | null {
diff --git a/packages/app/src/components/icons/apple-icon.tsx b/packages/app/src/components/icons/apple-icon.tsx
new file mode 100644
index 0000000000..1bc80a14f4
--- /dev/null
+++ b/packages/app/src/components/icons/apple-icon.tsx
@@ -0,0 +1,9 @@
+import { SvgPathIcon, type SvgPathIconProps } from "./svg-path-icon";
+
+// Same mark as the website's download buttons (packages/website/src/downloads.tsx).
+const APPLE_PATH =
+  "M12.152 6.896c-.948 0-2.415-1.078-3.96-1.04-2.04.027-3.91 1.183-4.961 3.014-2.117 3.675-.546 9.103 1.519 12.09 1.013 1.454 2.208 3.09 3.792 3.039 1.52-.065 2.09-.987 3.935-.987 1.831 0 2.35.987 3.96.948 1.637-.026 2.676-1.48 3.676-2.948 1.156-1.688 1.636-3.325 1.662-3.415-.039-.013-3.182-1.221-3.22-4.857-.026-3.04 2.48-4.494 2.597-4.559-1.429-2.09-3.623-2.324-4.39-2.376-2-.156-3.675 1.09-4.61 1.09zM15.53 3.83c.843-1.012 1.4-2.427 1.245-3.83-1.207.052-2.662.805-3.532 1.818-.78.896-1.454 2.338-1.273 3.714 1.338.104 2.715-.688 3.559-1.701";
+
+export function AppleIcon(props: SvgPathIconProps) {
+  return <SvgPathIcon {...props} path={APPLE_PATH} viewBox="0 0 24 24" />;
+}
diff --git a/packages/app/src/components/icons/google-play-icon.tsx b/packages/app/src/components/icons/google-play-icon.tsx
new file mode 100644
index 0000000000..0a377d22af
--- /dev/null
+++ b/packages/app/src/components/icons/google-play-icon.tsx
@@ -0,0 +1,19 @@
+import Svg, { Path } from "react-native-svg";
+
+/**
+ * The four-colour Play mark, the same one as the website's download buttons
+ * (packages/website/src/downloads.tsx). Brand colours are fixed, so it takes no color.
+ */
+export function GooglePlayIcon({ size = 16 }: { size?: number }) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+      <Path d="M3.27 2.17c-.2.21-.32.55-.32 1v17.66c0 .45.12.79.33 1l9.87-9.84z" fill="#00F076" />
+      <Path
+        d="m16.43 8.72-3.28 3.27 3.29 3.28 3.9-2.22c1.13-.64 1.13-1.42 0-2.06z"
+        fill="#FFCE00"
+      />
+      <Path d="m13.15 11.99 3.28-3.27L4.63 2.01c-.56-.32-1.04-.28-1.36.16z" fill="#00D6FF" />
+      <Path d="M3.28 21.83c.32.44.8.48 1.36.16l11.8-6.72-3.29-3.28z" fill="#FF3A44" />
+    </Svg>
+  );
+}
diff --git a/packages/app/src/components/import-session-sheet.tsx b/packages/app/src/components/import-session-sheet.tsx
index 21296e54e0..aa7294bf49 100644
--- a/packages/app/src/components/import-session-sheet.tsx
+++ b/packages/app/src/components/import-session-sheet.tsx
@@ -206,7 +206,7 @@ function ProviderErrorBannerRow({
       </Text>
       <Button
         variant="ghost"
-        size="xs"
+        size="sm"
         onPress={handleRetry}
         testID={`import-session-retry-${row.provider}`}
       >
@@ -266,7 +266,7 @@ function ScopeSubtitle({
       {isScoped ? (
         <Button
           variant="ghost"
-          size="xs"
+          size="sm"
           onPress={onShowAll}
           testID="import-session-show-all"
           style={styles.subtitleAction}
diff --git a/packages/app/src/components/keyboard-shortcuts-dialog.tsx b/packages/app/src/components/keyboard-shortcuts-dialog.tsx
index 0dfd634d80..4e5228f59e 100644
--- a/packages/app/src/components/keyboard-shortcuts-dialog.tsx
+++ b/packages/app/src/components/keyboard-shortcuts-dialog.tsx
@@ -1,8 +1,8 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { getIsElectronRuntime } from "@/constants/layout";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Shortcut } from "@/components/ui/shortcut";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
@@ -24,14 +24,13 @@ export function KeyboardShortcutsDialog() {
 
   const shortcutOs = getShortcutOs();
   const isMac = shortcutOs === "mac";
-  const isDesktopApp = getIsElectronRuntime();
   const { overrides } = useKeyboardShortcutOverrides();
   // Effective bindings, so a shortcut the user unassigned lists no keys here
   // instead of advertising a default that no longer fires.
   const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
   const sections = useMemo(
-    () => buildKeyboardShortcutHelpSections({ isMac, isDesktop: isDesktopApp }, bindings),
-    [bindings, isDesktopApp, isMac],
+    () => buildKeyboardShortcutHelpSections({ isMac, usesDesktopBindings }, bindings),
+    [bindings, isMac],
   );
   const visibleSections = useMemo(
     () => filterShortcutHelpSections({ sections, query, translate: t, shortcutOs }),
diff --git a/packages/app/src/components/left-sidebar.tsx b/packages/app/src/components/left-sidebar.tsx
index 983d142beb..ba40ab41fd 100644
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -1,3 +1,5 @@
+import { SidebarViewSlot } from "@/plugins/sidebar-view";
+import { useAddHost } from "@/hosts/add-host";
 import { router } from "expo-router";
 import {
   CircleGauge,
@@ -11,19 +13,25 @@ import { useTranslation } from "react-i18next";
 import { memo, useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
 import {
   Pressable,
+  ScrollView,
   StyleSheet as RNStyleSheet,
   Text,
   useWindowDimensions,
   View,
+  type LayoutChangeEvent,
 } from "react-native";
-import { Gesture } from "react-native-gesture-handler";
+import { Gesture, ScrollView as GHScrollView } from "react-native-gesture-handler";
 import Animated, { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
 import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
-import { resolveDesktopSidebarWidth } from "@/components/desktop-sidebar-layout";
+import {
+  resolveDesktopSidebarInsetLeft,
+  resolveDesktopSidebarWidth,
+} from "@/components/desktop-sidebar-layout";
+import { useTopBand, useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
@@ -31,15 +39,28 @@ import {
 import { HostPicker } from "@/components/hosts/host-picker";
 import { SidebarDisplayPreferencesMenu } from "@/components/sidebar/display-preferences/menu";
 import { SidebarSeparator } from "@/components/sidebar/sidebar-separator";
+import { SidebarToastRegion } from "@/components/sidebar/sidebar-toast-region";
 import { SidebarNavRows } from "@/components/sidebar/sidebar-nav-rows";
 import { SidebarFooterIconHighlight } from "@/components/sidebar/sidebar-footer-icon-highlight";
 import { SidebarHelpMenu } from "@/components/sidebar/sidebar-help-menu";
+import { SidebarFooterOverflowMenu } from "@/components/sidebar/sidebar-footer-overflow-menu";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+  type SidebarFooterAction,
+} from "@/components/sidebar-footer-layout";
+import {
+  controlSizingForLayout,
+  mapLayout,
+  TOOLBAR_CONTROL_SIZES,
+} from "@/components/ui/control-geometry";
 import { SidebarResizeHandle } from "@/components/sidebar-resize-handle";
 import { DensityIcon } from "@/components/ui/density-icon";
 import { SidebarSectionHeader } from "@/components/sidebar/sidebar-section-header";
 import { Shortcut } from "@/components/ui/shortcut";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { HEADER_INNER_HEIGHT, useIsCompactFormFactor } from "@/constants/layout";
+import { isNative as platformIsNative } from "@/constants/platform";
 import { useOpenAddProject } from "@/hooks/use-open-add-project";
 import { useImportSession } from "@/hooks/use-import-session";
 import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
@@ -48,6 +69,7 @@ import {
   type SidebarWorkspaceEntry,
 } from "@/hooks/use-sidebar-workspaces-list";
 import { density } from "@/styles/density";
+import { SPACING } from "@/styles/theme";
 import { useSidebarModel } from "@/components/sidebar/sidebar-model";
 import type { PinnedSidebarGroups } from "@/hooks/use-sidebar-pins";
 import { RetainedPanelActivity } from "@/components/retained-panel";
@@ -61,8 +83,9 @@ import { useSidebarNavItems } from "@/sidebar-nav/use-sidebar-nav-items";
 import { usePanelStore } from "@/stores/panel-store";
 import { useOwnsWindowChromeCorner, WindowChromeSafeArea } from "@/utils/desktop-window";
 import { useCloseAgentListGesture } from "@/mobile-panels/gestures";
+import { useLeftPanelWidth } from "@/mobile-panels/provider";
 import { MobilePanelOverlay } from "@/mobile-panels/presentation";
-import { buildSettingsAddHostRoute, buildSettingsRoute } from "@/utils/host-routes";
+import { buildSettingsRoute } from "@/utils/host-routes";
 import { openHostOverview } from "@/navigation/settings-navigation";
 import { UsageSidebarItem, UsageSidebarRoot, useUsageSummary, useOpenSidebarUsage } from "@/usage";
 import { SidebarAgentListSkeleton } from "./sidebar-agent-list-skeleton";
@@ -71,6 +94,9 @@ import { SidebarWorkspaceList } from "./sidebar-workspace-list";
 
 type SidebarTheme = ReturnType<typeof useUnistyles>["theme"];
 
+/** The footer icon line's inset; the overflow layout counts it as space the buttons can't use. */
+const FOOTER_ROW_PADDING = SPACING[2];
+
 const DEV_BUILD_LABEL = process.env.EXPO_PUBLIC_PASEO_DEV_BUILD_LABEL?.trim() || null;
 
 interface SidebarSharedProps {
@@ -117,9 +143,16 @@ interface MobileSidebarProps extends SidebarSharedProps {
 interface DesktopSidebarProps extends SidebarSharedProps {
   insetsTop: number;
   active: boolean;
+  overlay: boolean;
 }
 
-export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boolean }) {
+export const LeftSidebar = memo(function LeftSidebar({
+  active,
+  desktopOverlay,
+}: {
+  active: boolean;
+  desktopOverlay: boolean;
+}) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
@@ -160,33 +193,20 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
   const openProjectPicker = useOpenAddProject();
   const { open: openImportSession, sheet: importSessionSheet } = useImportSession();
 
-  const handleOpenProjectMobile = useCallback(() => {
+  // Each destination closes the navigation overlay first. Closing is idempotent, so a docked
+  // sidebar runs the same handler.
+  const handleOpenProject = useCallback(() => {
     void openProjectPicker();
   }, [openProjectPicker]);
 
-  const handleOpenProjectDesktop = useCallback(() => {
-    void openProjectPicker();
-  }, [openProjectPicker]);
-
-  const handleSettingsMobile = useCallback(() => {
+  const handleSettings = useCallback(() => {
     showMobileAgent();
     router.push(buildSettingsRoute());
   }, [showMobileAgent]);
 
-  const handleSettingsDesktop = useCallback(() => {
-    router.push(buildSettingsRoute());
-  }, []);
+  const handleAddHost = useAddHost();
 
-  const handleAddHostMobile = useCallback(() => {
-    showMobileAgent();
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, [showMobileAgent]);
-
-  const handleAddHostDesktop = useCallback(() => {
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, []);
-
-  const handleOpenHostSettingsMobile = useCallback(
+  const handleOpenHostSettings = useCallback(
     (serverId: string) => {
       showMobileAgent();
       openHostOverview(serverId);
@@ -194,14 +214,6 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
     [showMobileAgent],
   );
 
-  const handleOpenHostSettingsDesktop = useCallback((serverId: string) => {
-    openHostOverview(serverId);
-  }, []);
-
-  const handleImportSessionMobile = useCallback(() => {
-    openImportSession();
-  }, [openImportSession]);
-
   const labels = useMemo(
     (): SidebarLabels => ({
       addProject: t("sidebar.actions.addProject"),
@@ -234,41 +246,35 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
     labels,
   };
 
-  if (isCompactLayout) {
-    return (
-      <>
-        <RetainedPanelActivity active={active}>
-          <MobileSidebar
-            {...sharedProps}
-            active={active}
-            insetsTop={insets.top}
-            insetsBottom={insets.bottom}
-            closeSidebar={showMobileAgent}
-            handleOpenProject={handleOpenProjectMobile}
-            handleImportSession={handleImportSessionMobile}
-            handleSettings={handleSettingsMobile}
-            handleAddHost={handleAddHostMobile}
-            handleOpenHostSettings={handleOpenHostSettingsMobile}
-          />
-        </RetainedPanelActivity>
-        {importSessionSheet}
-      </>
-    );
-  }
+  const handlers = {
+    handleOpenProject,
+    handleImportSession: openImportSession,
+    handleSettings,
+    handleAddHost,
+    handleOpenHostSettings,
+  };
 
   return (
     <>
       <RetainedPanelActivity active={active}>
-        <DesktopSidebar
-          {...sharedProps}
-          insetsTop={insets.top}
-          active={active}
-          handleOpenProject={handleOpenProjectDesktop}
-          handleImportSession={openImportSession}
-          handleSettings={handleSettingsDesktop}
-          handleAddHost={handleAddHostDesktop}
-          handleOpenHostSettings={handleOpenHostSettingsDesktop}
-        />
+        {isCompactLayout ? (
+          <MobileSidebar
+            {...sharedProps}
+            {...handlers}
+            active={active}
+            insetsTop={insets.top}
+            insetsBottom={insets.bottom}
+            closeSidebar={showMobileAgent}
+          />
+        ) : (
+          <DesktopSidebar
+            {...sharedProps}
+            {...handlers}
+            insetsTop={insets.top}
+            active={active}
+            overlay={desktopOverlay}
+          />
+        )}
       </RetainedPanelActivity>
       {importSessionSheet}
     </>
@@ -422,35 +428,72 @@ function SidebarFooter({
 }) {
   const newAgentKeys = useShortcutKeys("new-agent");
   const settingsKeys = useShortcutKeys("toggle-settings");
+  const isCompactLayout = useIsCompactFormFactor();
+  const [rowWidth, setRowWidth] = useState(0);
+  const handleRowLayout = useCallback((event: LayoutChangeEvent) => {
+    setRowWidth(event.nativeEvent.layout.width);
+  }, []);
+  const { inline, overflow } = useMemo(
+    () =>
+      resolveSidebarFooterLayout({
+        rowWidth,
+        controlSize: TOOLBAR_CONTROL_SIZES[controlSizingForLayout(isCompactLayout)],
+        rowPadding: FOOTER_ROW_PADDING,
+        actions: SIDEBAR_FOOTER_ACTIONS,
+      }),
+    [rowWidth, isCompactLayout],
+  );
+  const isInline = (action: SidebarFooterAction) => inline.includes(action);
 
-  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end.
+  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end. Actions that
+  // don't fit move behind a caret before Settings.
   return (
     <UsageSidebarRoot>
       <View style={styles.footerContainer} testID="sidebar-footer">
         <SidebarFooterRows onBeforeNavigate={onBeforeNavigate} />
-        <View style={styles.sidebarFooter} testID="sidebar-footer-bottom-line">
-          <FooterIconButton
-            onPress={handleOpenProject}
-            testID="sidebar-add-project"
-            label={labels.addProject}
-            icon={FolderPlus}
-            shortcutKeys={newAgentKeys}
-          />
-          <SidebarUsageIcon label={labels.usage} />
-          <SidebarHostPicker
-            label={labels.hosts}
-            onAddHost={handleAddHost}
-            onOpenHostSettings={handleOpenHostSettings}
-          />
+        <View
+          style={styles.sidebarFooter}
+          onLayout={handleRowLayout}
+          testID="sidebar-footer-bottom-line"
+        >
+          {isInline("add-project") ? (
+            <FooterIconButton
+              onPress={handleOpenProject}
+              testID="sidebar-add-project"
+              label={labels.addProject}
+              icon={FolderPlus}
+              shortcutKeys={newAgentKeys}
+            />
+          ) : null}
+          {isInline("usage") ? <SidebarUsageIcon label={labels.usage} /> : null}
+          {isInline("hosts") ? (
+            <SidebarHostPicker
+              label={labels.hosts}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
           <View style={styles.footerSpacer} />
-          <SidebarHelpMenu />
-          <FooterIconButton
-            onPress={handleSettings}
-            testID="sidebar-settings"
-            label={labels.settings}
-            icon={Settings}
-            shortcutKeys={settingsKeys}
-          />
+          {isInline("help") ? <SidebarHelpMenu /> : null}
+          {overflow.length > 0 ? (
+            <SidebarFooterOverflowMenu
+              actions={overflow}
+              labels={labels}
+              onAddProject={handleOpenProject}
+              onSettings={handleSettings}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
+          {isInline("settings") ? (
+            <FooterIconButton
+              onPress={handleSettings}
+              testID="sidebar-settings"
+              label={labels.settings}
+              icon={Settings}
+              shortcutKeys={settingsKeys}
+            />
+          ) : null}
         </View>
       </View>
     </UsageSidebarRoot>
@@ -531,6 +574,7 @@ function MobileSidebar({
   insetsBottom,
   closeSidebar,
 }: MobileSidebarProps) {
+  const insets = useSafeAreaInsets();
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
   const { gesture: closeGesture, gestureRef: closeGestureRef } = useCloseAgentListGesture();
 
@@ -545,10 +589,10 @@ function MobileSidebar({
         onPress={closeSidebar}
         testID="sidebar-close"
         nativeID="sidebar-close"
-        style={styles.mobileCloseButton}
+        style={styles.mobileCloseButton(insets.right)}
       />
     ),
-    [labels.closeSidebar, closeSidebar],
+    [labels.closeSidebar, closeSidebar, insets.right],
   );
 
   const mobileSidebarInsetStyle = useMemo(
@@ -560,6 +604,14 @@ function MobileSidebar({
     [insetsTop, insetsBottom, theme.colors.surfaceSidebar],
   );
 
+  const navRows = (
+    <SidebarNavRows
+      style={styles.mobileNavRowsGroup}
+      onBeforeNavigate={closeSidebar}
+      firstRowTrailing={closeButton}
+    />
+  );
+
   return (
     <MobilePanelOverlay
       panel="agent-list"
@@ -568,37 +620,59 @@ function MobileSidebar({
     >
       <View style={styles.sidebarContent} pointerEvents="auto">
         <WindowChromeSafeArea placement="below" />
-        <SidebarNavRows
-          style={styles.sidebarHeaderGroup}
-          onBeforeNavigate={closeSidebar}
-          firstRowTrailing={closeButton}
-        />
-
-        {isInitialLoad && !hasActiveHostFilter ? (
-          <SidebarAgentListSkeleton />
+        {platformIsNative ? (
+          <GHScrollView
+            // Same contract as the workspace list: vertical drags scroll the nav
+            // block, a clear horizontal intent still activates the close pan.
+            simultaneousHandlers={closeGestureRef}
+            style={styles.mobileNavScroll}
+            showsVerticalScrollIndicator={false}
+            alwaysBounceVertical={false}
+            testID="sidebar-nav-scroll"
+          >
+            {navRows}
+          </GHScrollView>
         ) : (
-          <SidebarWorkspaceList
-            collapsedProjectKeys={collapsedProjectKeys}
-            onToggleProjectCollapsed={toggleProjectCollapsed}
-            shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
-            groupMode={groupMode}
-            workspaceGroups={workspaceGroups}
-            projectIconTargets={projectIconTargets}
-            pinnedGroups={pinnedGroups}
-            projects={projects}
-            hasProjectsBeforeFilter={hasProjectsBeforeFilter}
-            hasActiveProjectFilter={hasActiveProjectFilter}
-            workspaceEntriesByKey={workspaceEntriesByKey}
-            isRefreshing={isManualRefresh && isRevalidating}
-            onRefresh={handleRefresh}
-            onWorkspacePress={handleWorkspacePress}
-            onAddProject={handleOpenProject}
-            onImportSession={handleImportSession}
-            parentGestureRef={closeGestureRef}
-            dragGestureHostActive={active}
-            listHeaderComponent={workspacesSectionHeaderElement}
-          />
+          <ScrollView
+            style={styles.mobileNavScroll}
+            showsVerticalScrollIndicator={false}
+            alwaysBounceVertical={false}
+            testID="sidebar-nav-scroll"
+          >
+            {navRows}
+          </ScrollView>
         )}
+        <SidebarSeparator />
+
+        <SidebarViewSlot dismiss={handleWorkspacePress}>
+          <SidebarToastRegion active={active}>
+            {isInitialLoad && !hasActiveHostFilter ? (
+              <SidebarAgentListSkeleton />
+            ) : (
+              <SidebarWorkspaceList
+                collapsedProjectKeys={collapsedProjectKeys}
+                onToggleProjectCollapsed={toggleProjectCollapsed}
+                shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
+                groupMode={groupMode}
+                workspaceGroups={workspaceGroups}
+                projectIconTargets={projectIconTargets}
+                pinnedGroups={pinnedGroups}
+                projects={projects}
+                hasProjectsBeforeFilter={hasProjectsBeforeFilter}
+                hasActiveProjectFilter={hasActiveProjectFilter}
+                workspaceEntriesByKey={workspaceEntriesByKey}
+                isRefreshing={isManualRefresh && isRevalidating}
+                onRefresh={handleRefresh}
+                onWorkspacePress={handleWorkspacePress}
+                onAddProject={handleOpenProject}
+                onImportSession={handleImportSession}
+                parentGestureRef={closeGestureRef}
+                dragGestureHostActive={active}
+                listHeaderComponent={workspacesSectionHeaderElement}
+              />
+            )}
+          </SidebarToastRegion>
+        </SidebarViewSlot>
 
         <SidebarFooter
           handleOpenProject={handleOpenProject}
@@ -638,20 +712,27 @@ function DesktopSidebar({
   handleOpenHostSettings,
   insetsTop,
   active,
+  overlay,
 }: DesktopSidebarProps) {
   const ownsTopLeft = useOwnsWindowChromeCorner("top-left");
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
-  const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
   const setSidebarWidth = usePanelStore((state) => state.setSidebarWidth);
-  const { width: windowWidth } = useWindowDimensions();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const insets = useSafeAreaInsets();
   const viewportWidth = windowWidth - insets.left - insets.right;
-  const visibleSidebarWidth = resolveDesktopSidebarWidth({
-    requestedWidth: sidebarWidth,
-    viewportWidth,
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
   });
+  const visibleSidebarWidth = useLeftPanelWidth();
 
-  const startWidthRef = useRef(visibleSidebarWidth);
+  const closeSidebar = usePanelStore((state) => state.showMobileAgent);
+  const { gesture: closeGesture, gestureRef: closeGestureRef } = useCloseAgentListGesture(overlay);
+
+  const startWidth = useSharedValue(visibleSidebarWidth);
   const resizeWidth = useSharedValue(visibleSidebarWidth);
   const [resizePressed, setResizePressed] = useState(false);
   const showResizeGrip = useCallback(() => setResizePressed(true), []);
@@ -664,6 +745,7 @@ function DesktopSidebar({
   const resizeGesture = useMemo(
     () =>
       Gesture.Pan()
+        .enabled(divisionLayout === null)
         .hitSlop({ left: 8, right: 8, top: 0, bottom: 0 })
         .onBegin(() => {
           scheduleOnRN(showResizeGrip);
@@ -674,129 +756,148 @@ function DesktopSidebar({
         .activeOffsetX([-SIDEBAR_RESIZE_ACTIVATION_OFFSET, SIDEBAR_RESIZE_ACTIVATION_OFFSET])
         .failOffsetY([-SIDEBAR_RESIZE_FAIL_OFFSET, SIDEBAR_RESIZE_FAIL_OFFSET])
         .onStart((event) => {
-          startWidthRef.current = visibleSidebarWidth - event.translationX;
+          startWidth.value = visibleSidebarWidth - event.translationX;
           resizeWidth.value = visibleSidebarWidth;
         })
         .onUpdate((event) => {
           // Dragging right (positive translationX) increases width
-          const newWidth = startWidthRef.current + event.translationX;
+          const newWidth = startWidth.value + event.translationX;
           resizeWidth.value = resolveDesktopSidebarWidth({
             requestedWidth: newWidth,
             viewportWidth,
           });
         })
-        .onEnd(() => {
-          runOnJS(setSidebarWidth)(resizeWidth.value);
+        .onEnd((_event, success) => {
+          if (success) runOnJS(setSidebarWidth)(resizeWidth.value);
         })
         .onFinalize(() => {
           scheduleOnRN(hideResizeGrip);
         }),
     [
+      divisionLayout,
       hideResizeGrip,
       resizeWidth,
       setSidebarWidth,
       showResizeGrip,
+      startWidth,
       viewportWidth,
       visibleSidebarWidth,
     ],
   );
 
   const resizeAnimatedStyle = useAnimatedStyle(() => ({
-    width: resizeWidth.value,
+    width: divisionLayout?.sidebarWidth ?? resizeWidth.value,
   }));
-
+  // The panel host gets no width of its own: the dock sizes to this view and the overlay fills the
+  // window. A Reanimated width on the host reached Android after React had switched presentation,
+  // and a lost update left the workspace at the dock width after the dock collapsed.
   const desktopSidebarStyle = useMemo(
-    () => [
-      staticStyles.desktopSidebar,
-      !active && staticStyles.desktopSidebarHidden,
-      resizeAnimatedStyle,
-    ],
-    [active, resizeAnimatedStyle],
+    () => [staticStyles.desktopSidebar, resizeAnimatedStyle],
+    [resizeAnimatedStyle],
   );
   const desktopSidebarBorderStyle = useMemo(
     () => [
-      styles.desktopSidebarBorder,
-      { flex: 1, paddingTop: insetsTop, paddingBottom: insets.bottom },
+      styles.desktopSidebarBorder(divisionLayout !== null),
+      {
+        flex: 1,
+        paddingTop: insetsTop,
+        paddingBottom: insets.bottom,
+        paddingLeft: resolveDesktopSidebarInsetLeft({ overlay, safeAreaLeft: insets.left }),
+      },
     ],
-    [insetsTop, insets.bottom],
+    [insetsTop, insets.bottom, insets.left, overlay, divisionLayout],
   );
+  // Below the window controls' row, or in the top band's place, the first row starts flush.
+  const inTopBand = useTopBand() !== null;
   const sidebarHeaderGroupStyle = useMemo(
-    () => [styles.sidebarHeaderGroup, ownsTopLeft && styles.sidebarHeaderGroupBelowChrome],
-    [ownsTopLeft],
+    () => [styles.sidebarHeaderGroup, (ownsTopLeft || inTopBand) && styles.sidebarHeaderGroupFlush],
+    [ownsTopLeft, inTopBand],
   );
   return (
-    <Animated.View
-      accessibilityElementsHidden={!active}
-      importantForAccessibility={active ? "auto" : "no-hide-descendants"}
-      pointerEvents={active ? "auto" : "none"}
-      style={desktopSidebarStyle}
+    <MobilePanelOverlay
+      panel="agent-list"
+      presentation={overlay ? "overlay" : "dock"}
+      dockVisible={active}
+      closeGesture={closeGesture}
     >
-      <View style={desktopSidebarBorderStyle}>
-        <View style={styles.sidebarDragArea}>
-          {ownsTopLeft || DEV_BUILD_LABEL ? (
-            <View style={styles.desktopChromeRow}>
+      <Animated.View style={desktopSidebarStyle}>
+        <View style={desktopSidebarBorderStyle}>
+          <View style={styles.sidebarDragArea}>
+            {ownsTopLeft || DEV_BUILD_LABEL ? (
+              <View style={styles.desktopChromeRow}>
+                <TitlebarDragRegion />
+                {DEV_BUILD_LABEL ? (
+                  <View
+                    pointerEvents="none"
+                    style={styles.devBuildBadge}
+                    testID="dev-build-label"
+                    accessibilityLabel={`Development build: ${DEV_BUILD_LABEL}`}
+                  >
+                    <GitBranch size={12} color={theme.colors.accentForeground} />
+                    <Text numberOfLines={1} ellipsizeMode="tail" style={styles.devBuildBadgeText}>
+                      {DEV_BUILD_LABEL}
+                    </Text>
+                  </View>
+                ) : null}
+              </View>
+            ) : (
               <TitlebarDragRegion />
-              {DEV_BUILD_LABEL ? (
-                <View
-                  pointerEvents="none"
-                  style={styles.devBuildBadge}
-                  testID="dev-build-label"
-                  accessibilityLabel={`Development build: ${DEV_BUILD_LABEL}`}
-                >
-                  <GitBranch size={12} color={theme.colors.accentForeground} />
-                  <Text numberOfLines={1} ellipsizeMode="tail" style={styles.devBuildBadgeText}>
-                    {DEV_BUILD_LABEL}
-                  </Text>
-                </View>
-              ) : null}
-            </View>
-          ) : (
-            <TitlebarDragRegion />
-          )}
-          <SidebarNavRows style={sidebarHeaderGroupStyle} />
-        </View>
+            )}
+            <SidebarNavRows style={sidebarHeaderGroupStyle} onBeforeNavigate={closeSidebar} />
+          </View>
 
-        {isInitialLoad && !hasActiveHostFilter ? (
-          <SidebarAgentListSkeleton />
-        ) : (
-          <SidebarWorkspaceList
-            collapsedProjectKeys={collapsedProjectKeys}
-            onToggleProjectCollapsed={toggleProjectCollapsed}
-            shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
-            groupMode={groupMode}
-            workspaceGroups={workspaceGroups}
-            projectIconTargets={projectIconTargets}
-            pinnedGroups={pinnedGroups}
-            projects={projects}
-            hasProjectsBeforeFilter={hasProjectsBeforeFilter}
-            hasActiveProjectFilter={hasActiveProjectFilter}
-            workspaceEntriesByKey={workspaceEntriesByKey}
-            isRefreshing={isManualRefresh && isRevalidating}
-            onRefresh={handleRefresh}
-            onAddProject={handleOpenProject}
-            onImportSession={handleImportSession}
-            listHeaderComponent={workspacesSectionHeaderElement}
+          <SidebarViewSlot dismiss={closeSidebar}>
+            <SidebarToastRegion active={active}>
+              {isInitialLoad && !hasActiveHostFilter ? (
+                <SidebarAgentListSkeleton />
+              ) : (
+                <SidebarWorkspaceList
+                  collapsedProjectKeys={collapsedProjectKeys}
+                  onToggleProjectCollapsed={toggleProjectCollapsed}
+                  shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
+                  groupMode={groupMode}
+                  workspaceGroups={workspaceGroups}
+                  projectIconTargets={projectIconTargets}
+                  pinnedGroups={pinnedGroups}
+                  projects={projects}
+                  hasProjectsBeforeFilter={hasProjectsBeforeFilter}
+                  hasActiveProjectFilter={hasActiveProjectFilter}
+                  workspaceEntriesByKey={workspaceEntriesByKey}
+                  isRefreshing={isManualRefresh && isRevalidating}
+                  onRefresh={handleRefresh}
+                  onAddProject={handleOpenProject}
+                  onImportSession={handleImportSession}
+                  onWorkspacePress={closeSidebar}
+                  parentGestureRef={closeGestureRef}
+                  dragGestureHostActive={active}
+                  listHeaderComponent={workspacesSectionHeaderElement}
+                />
+              )}
+            </SidebarToastRegion>
+          </SidebarViewSlot>
+
+          <SidebarCalloutSlot />
+
+          <SidebarFooter
+            handleOpenProject={handleOpenProject}
+            handleSettings={handleSettings}
+            labels={labels}
+            handleAddHost={handleAddHost}
+            handleOpenHostSettings={handleOpenHostSettings}
+            onBeforeNavigate={closeSidebar}
           />
-        )}
 
-        <SidebarCalloutSlot />
-
-        <SidebarFooter
-          handleOpenProject={handleOpenProject}
-          handleSettings={handleSettings}
-          labels={labels}
-          handleAddHost={handleAddHost}
-          handleOpenHostSettings={handleOpenHostSettings}
-        />
-
-        <SidebarResizeHandle
-          edge="right"
-          gesture={resizeGesture}
-          pressed={resizePressed}
-          testID="left-sidebar-resize-handle"
-        />
-      </View>
-    </Animated.View>
+          {!overlay && divisionLayout === null ? (
+            <SidebarResizeHandle
+              edge="right"
+              gesture={resizeGesture}
+              pressed={resizePressed}
+              testID="left-sidebar-resize-handle"
+            />
+          ) : null}
+        </View>
+      </Animated.View>
+    </MobilePanelOverlay>
   );
 }
 
@@ -827,9 +928,7 @@ const workspacesSectionHeaderElement = <WorkspacesSectionHeader />;
 const staticStyles = RNStyleSheet.create({
   desktopSidebar: {
     position: "relative" as const,
-  },
-  desktopSidebarHidden: {
-    display: "none",
+    flex: 1,
   },
 });
 
@@ -841,21 +940,33 @@ const styles = StyleSheet.create((theme) => ({
     borderBottomWidth: 1,
     borderBottomColor: theme.colors.border,
   },
-  sidebarHeaderGroupBelowChrome: {
+  sidebarHeaderGroupFlush: {
     paddingTop: 0,
   },
+  // The nav block caps at half the sidebar; a long item list scrolls inside the
+  // cap instead of crowding the workspace list off a short screen.
+  mobileNavScroll: {
+    flexGrow: 0,
+    flexShrink: 1,
+    maxHeight: "50%",
+  },
+  mobileNavRowsGroup: {
+    paddingTop: theme.spacing[2],
+    gap: 2,
+    paddingBottom: theme.spacing[1.5],
+  },
   sidebarContent: {
     flex: 1,
     minHeight: 0,
   },
-  mobileCloseButton: {
-    marginRight: theme.spacing[2],
-  },
-  desktopSidebarBorder: {
-    borderRightWidth: 1,
+  mobileCloseButton: (rightInset: number) => ({
+    marginRight: theme.spacing[2] + rightInset,
+  }),
+  desktopSidebarBorder: (hasDivision: boolean) => ({
+    borderRightWidth: hasDivision ? 0 : 1,
     borderRightColor: theme.colors.border,
     backgroundColor: theme.colors.surfaceSidebar,
-  },
+  }),
   sidebarDragArea: {
     position: "relative",
   },
@@ -891,10 +1002,12 @@ const styles = StyleSheet.create((theme) => ({
     borderTopColor: theme.colors.border,
   },
   // Buttons sit edge to edge; their own inset spaces the glyphs.
+  // As tall as its buttons from the first frame, which places none until the row has measured.
   sidebarFooter: {
     flexDirection: "row",
     alignItems: "center",
-    paddingHorizontal: theme.spacing[2],
+    minHeight: mapLayout(density.iconButton, (height) => height + theme.spacing[1.5] * 2),
+    paddingHorizontal: FOOTER_ROW_PADDING,
     paddingVertical: theme.spacing[1.5],
   },
   // Pushes Help and Settings to the end of the icon line.
diff --git a/packages/app/src/components/markdown/fence/mermaid/host.web.tsx b/packages/app/src/components/markdown/fence/mermaid/host.web.tsx
index 9370bc90c0..94d6ccc666 100644
--- a/packages/app/src/components/markdown/fence/mermaid/host.web.tsx
+++ b/packages/app/src/components/markdown/fence/mermaid/host.web.tsx
@@ -72,7 +72,7 @@ function MermaidFenceHostImpl({
     () => [
       getDiagramBoxStyle(textStyle),
       containerStyle,
-      { height: runtimeHeight, minHeight: MIN_DIAGRAM_BOX_HEIGHT },
+      { height: Math.min(runtimeHeight, MAX_PREVIEW_HEIGHT), minHeight: MIN_DIAGRAM_BOX_HEIGHT },
     ],
     [runtimeHeight, textStyle],
   );
@@ -111,20 +111,22 @@ function MermaidFenceHostImpl({
           ) : null}
         </View>
       ) : null}
-      <ZoomableViewport
-        accessibilityLabel={t("message.diagram.diagram")}
-        actions={actions}
-        contentSize={diagramSize}
-        style={viewportStyle}
-        testID="mermaid-viewport"
-        wheelActivation="modifier"
-      >
-        <MermaidIframeRuntime
-          request={request}
-          onRendered={handleRendered}
-          onRenderFailed={renderFailed}
-        />
-      </ZoomableViewport>
+      <div inert={!diagramVisible} style={boundaryStyle}>
+        <ZoomableViewport
+          accessibilityLabel={t("message.diagram.diagram")}
+          actions={actions}
+          contentSize={diagramSize}
+          style={viewportStyle}
+          testID="mermaid-viewport"
+          wheelActivation="modifier"
+        >
+          <MermaidIframeRuntime
+            request={request}
+            onRendered={handleRendered}
+            onRenderFailed={renderFailed}
+          />
+        </ZoomableViewport>
+      </div>
       {isFullscreen && visible ? (
         <MermaidFullscreenViewer
           source={visible.source}
@@ -142,6 +144,8 @@ const MEASURING_SIZE = { width: 240, height: 240 };
  * with `overflow: hidden`, so a shorter box leaves the buttons half-clipped and unclickable.
  */
 const MIN_DIAGRAM_BOX_HEIGHT = 56;
+const MAX_PREVIEW_HEIGHT = 480;
+const boundaryStyle: React.CSSProperties = { display: "contents" };
 const sourceContainerStyle: ViewStyle = { position: "relative" };
 /**
  * The viewport's own root is `flex: 1`, so as a flex item it has `flex-basis: 0%` and that basis
diff --git a/packages/app/src/components/markdown/images.ts b/packages/app/src/components/markdown/images.ts
index 83b24b481b..9a52491125 100644
--- a/packages/app/src/components/markdown/images.ts
+++ b/packages/app/src/components/markdown/images.ts
@@ -35,11 +35,21 @@ export interface MarkdownImageContext {
   filePath?: string;
 }
 
-export function useMarkdownSource(text: string, context: MarkdownImageContext) {
+export function useMarkdownSource(
+  text: string,
+  context: MarkdownImageContext,
+  links: { commandNames?: ReadonlySet<string>; forgeReferencePattern?: string } = {},
+) {
   const occurrenceKey = useId();
+  const { commandNames, forgeReferencePattern } = links;
   const prepared = useMemo(
-    () => prepareMarkdownSource(text, context.workspaceRoot, { supportsSvg: isWeb }),
-    [text, context.workspaceRoot],
+    () =>
+      prepareMarkdownSource(text, context.workspaceRoot, {
+        supportsSvg: isWeb,
+        commandNames,
+        forgeReferencePattern,
+      }),
+    [text, context.workspaceRoot, commandNames, forgeReferencePattern],
   );
   const sources = [...new Set(prepared.images.map((image) => image.source))];
   const acquisitions = sources.map((source) => {
diff --git a/packages/app/src/components/markdown/renderer.test.ts b/packages/app/src/components/markdown/renderer.test.ts
index bb5679f6f8..6ce7e59ca2 100644
--- a/packages/app/src/components/markdown/renderer.test.ts
+++ b/packages/app/src/components/markdown/renderer.test.ts
@@ -2,6 +2,9 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { toNativeLinkRecognition } from "react-native-enriched-markdown/src/utils/regexParser";
 import { parseMarkdown } from "react-native-enriched-markdown/src/web/parseMarkdown";
 import { recognizeTextLinks } from "react-native-enriched-markdown/src/web/recognizeTextLinks";
+import { matchCommandLink } from "@/agent-commands";
+import { createForgeShorthand } from "@/git/forge-shorthand";
+
 import { classifyAssistantFileLink } from "@/assistant-file-links";
 import { markInlineImages } from "react-native-enriched-markdown/src/web/utils";
 import type { ASTNode } from "react-native-enriched-markdown/src/web/types";
@@ -13,6 +16,28 @@ import { createMarkdownStyles } from "./styles";
 import { prepareMarkdownSource, PENDING_MARKDOWN_IMAGE } from "./source";
 import { normalizeMarkdownHtml } from "./html";
 
+it("recognizes complete known commands in inline code", () => {
+  const names = new Set(["code-review", "review:fast"]);
+  const prepared = prepareMarkdownSource("`/code-review` `/unknown`", undefined, {
+    commandNames: names,
+  });
+  expect(prepared.linkRecognition.inlineCode.test("/code-review")).toBe(true);
+  expect(prepared.linkRecognition.inlineCode.test("/unknown")).toBe(
+    prepareMarkdownSource("`/unknown`").linkRecognition.inlineCode.test("/unknown"),
+  );
+  const nonPath = prepareMarkdownSource("`/review:fast`", undefined, { commandNames: names });
+  expect(nonPath.linkRecognition.inlineCode.test("/review:fast")).toBe(true);
+  expect(matchCommandLink("/code-review", "inline-code", names)).toBe("/code-review");
+});
+
+it("resolves authored root-relative links only when the target is a known command", () => {
+  const names = new Set(["code-review"]);
+  expect(matchCommandLink("/code-review", "markdown", names)).toBe("/code-review");
+  expect(matchCommandLink("/code-review/file", "markdown", names)).toBeNull();
+  expect(matchCommandLink("/code-review", "text", names)).toBeNull();
+  expect(matchCommandLink("https://example.com/code-review", "markdown", names)).toBeNull();
+});
+
 describe("shared Markdown source adaptation", () => {
   it("keeps paragraphs, fences and quotes together for the library", () => {
     const source = "First paragraph.\n\nSecond paragraph.\n\n```ts\nconst n = 1;\n```\n\n> Quote";
@@ -86,6 +111,37 @@ describe("shared Markdown source adaptation", () => {
       ["https://x/q.png", false],
     ]);
   });
+  it("renders linked images that share a line with text inline", async () => {
+    // A review bot's summary header: linked badges inside a heading with the score text.
+    const reviewHeader =
+      '<h2><a href="https://x/retrigger"><picture><source media="(prefers-color-scheme: dark)" srcset="https://x/r-dark.svg"><img alt="Retrigger" src="https://x/r.svg" align="right"></picture></a>Confidence Score: 5/5</h2>';
+    const source = [
+      reviewHeader,
+      "[![Alone](https://x/alone.png)](https://x)",
+      "[![a](https://x/a.png)](https://x) [![b](https://x/b.png)](https://x)",
+      "See [![gh](https://x/gh.png) GitHub](https://x) for more.",
+    ].join("\n\n");
+    const tree = await parseMarkdown(prepareMarkdownSource(source).render(), {
+      hardSoftBreaks: true,
+      latexMath: false,
+    });
+    markInlineImages(tree);
+    const images: ASTNode[] = [];
+    const collect = (node: ASTNode) => {
+      if (node.type === "Image") images.push(node);
+      node.children?.forEach(collect);
+    };
+    collect(tree);
+    expect(
+      images.map((image) => [image.attributes?.url, image.attributes?.isInline === true]),
+    ).toEqual([
+      ["https://x/r.svg", true],
+      ["https://x/alone.png", false],
+      ["https://x/a.png", true],
+      ["https://x/b.png", true],
+      ["https://x/gh.png", true],
+    ]);
+  });
   it("escapes spoiler delimiters only in prose", () => {
     expect(prepareMarkdownSource("Show ||words|| and `||code||`.").render()).toBe(
       "Show \\|\\|words\\|\\| and `||code||`.",
@@ -106,6 +162,186 @@ it("preserves empty table cells while escaping spoilers in cell text", () => {
   );
 });
 
+it("renders a table directly after a paragraph through the library parser", async () => {
+  const source = "**Notes**\n| Item | Detail |\n| --- | --- |\n| A | one |\n| B | two |";
+  const separated = "**Notes**\n\n| Item | Detail |\n| --- | --- |\n| A | one |\n| B | two |";
+  const flags = { hardSoftBreaks: true, latexMath: false };
+  const expected = await parseMarkdown(separated, flags);
+  expect(expected.children?.map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+  expect(await parseMarkdown(prepareMarkdownSource(source).render(), flags)).toEqual(expected);
+});
+
+it.each([
+  [
+    "a quote",
+    "> Notes\n> | Item |\n> | --- |\n> | A |",
+    "> Notes\n>\n> | Item |\n> | --- |\n> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item",
+    "- Notes\n  | Item |\n  | --- |\n  | A |\n- Next",
+    "- Notes\n\n  | Item |\n  | --- |\n  | A |\n- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a quoted list item",
+    "> - Notes\n>   | Item |\n>   | --- |\n>   | A |",
+    "> - Notes\n>\n>   | Item |\n>   | --- |\n>   | A |",
+    ["Document", ["Blockquote", ["UnorderedList", ["ListItem", "Paragraph", "Table"]]]],
+  ],
+  [
+    "a quote inside a list item",
+    "- > Notes\n  > | Item |\n  > | --- |\n  > | A |",
+    "- > Notes\n  >\n  > | Item |\n  > | --- |\n  > | A |",
+    ["Document", ["UnorderedList", ["ListItem", ["Blockquote", "Paragraph", "Table"]]]],
+  ],
+  [
+    "aligned columns without outer pipes",
+    "Notes\nItem | Detail\n:--- | ---:\nA | one",
+    "Notes\n\nItem | Detail\n:--- | ---:\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "an entity at the start of a header without outer pipes",
+    "Notes\nAT&amp;T | Detail\n--- | ---\nA | one",
+    "Notes\n\nAT\\&T | Detail\n--- | ---\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a local image at the start of a header without outer pipes",
+    "Notes\n![Local](assets/a.png) | Detail\n--- | ---\nA | one",
+    "Notes\n\nLocal | Detail\n--- | ---\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "CRLF lines",
+    "Notes\r\n| Item |\r\n| --- |\r\n| A |",
+    "Notes\r\n\r\n| Item |\r\n| --- |\r\n| A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "CR lines",
+    "Notes\r| Item |\r| --- |\r| A |",
+    "Notes\r\r| Item |\r| --- |\r| A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a quote with CRLF lines",
+    "> Notes\r\n> | Item |\r\n> | --- |\r\n> | A |",
+    "> Notes\r\n>\r\n> | Item |\r\n> | --- |\r\n> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item with CRLF lines",
+    "- Notes\r\n  | Item |\r\n  | --- |\r\n  | A |\r\n- Next",
+    "- Notes\r\n\r\n  | Item |\r\n  | --- |\r\n  | A |\r\n- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a quote with CR lines",
+    "> Notes\r> | Item |\r> | --- |\r> | A |",
+    "> Notes\r>\r> | Item |\r> | --- |\r> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item with CR lines",
+    "- Notes\r  | Item |\r  | --- |\r  | A |\r- Next",
+    "- Notes\r\r  | Item |\r  | --- |\r  | A |\r- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a non-interrupting ordered marker with tildes",
+    "Intro\n2. ~~~\n   Notes\n   | A |\n   | --- |\n   | x |",
+    "Intro\n2. ~~~\n   Notes\n\n   | A |\n   | --- |\n   | x |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a non-interrupting ordered marker with backticks",
+    "Notes\n2. ```\n   | Item |\n   | --- |\n   | A |",
+    "Notes\n2. ```\n\n   | Item |\n   | --- |\n   | A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+])("preserves tables after paragraphs in %s", async (_name, source, separated, expected) => {
+  const rendered = prepareMarkdownSource(source).render();
+  expect(rendered).toEqual(separated);
+  const flags = { hardSoftBreaks: true, latexMath: false };
+  function blocks(node: ASTNode): unknown {
+    if (node.type === "Paragraph" || node.type === "Table") return node.type;
+    return [node.type, ...(node.children ?? []).map(blocks)];
+  }
+  expect(blocks(await parseMarkdown(rendered, flags))).toEqual(expected);
+});
+
+it.each([
+  [
+    "a literal backslash",
+    "Notes\\\n| Item |\n| --- |\n| A |",
+    "Notes\\\n\n| Item |\n| --- |\n| A |",
+    "Notes\\",
+  ],
+  [
+    "an entity and literal backslash with LF lines",
+    "AT&amp;T\\\n| Item |\n| --- |\n| A |",
+    "AT\\&T\\\n\n| Item |\n| --- |\n| A |",
+    "AT&T\\",
+  ],
+  [
+    "an entity and literal backslash with CRLF lines",
+    "AT&amp;T\\\r\n| Item |\r\n| --- |\r\n| A |",
+    "AT\\&T\\\r\n\r\n| Item |\r\n| --- |\r\n| A |",
+    "AT&T\\",
+  ],
+  [
+    "an entity and literal backslash with CR lines",
+    "AT&amp;T\\\r| Item |\r| --- |\r| A |",
+    "AT\\&T\\\r\r| Item |\r| --- |\r| A |",
+    "AT&T\\",
+  ],
+])(
+  "preserves paragraph text before an interrupting table in %s",
+  async (_name, source, separated, text) => {
+    const rendered = prepareMarkdownSource(source).render();
+    expect(rendered).toEqual(separated);
+    const tree = await parseMarkdown(rendered, { hardSoftBreaks: true, latexMath: false });
+    expect(tree.children?.map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+    expect(tree.children?.[0]?.children?.map((node) => node.content).join("")).toEqual(text);
+  },
+);
+
+it.each([
+  "```yaml\n---\nkey: value\n---\n```\n",
+  "~~~md\n| Item |\n| --- |\n| A |\n~~~\n",
+  "````md\n```\n| Item |\n| --- |\n```\n`````\n",
+  "> ```md\n> | Item |\n> | --- |\n> ```\n",
+  "> ```md\n> Code\n",
+  "- ```md\n  Code\n",
+  "    ```\n\n",
+  "```not`a-fence\n",
+])("renders a table after a fence without changing its code: %s", async (prefix) => {
+  const table = "| Item |\n| --- |\n| A |";
+  const rendered = prepareMarkdownSource(`${prefix}Notes\n${table}`).render();
+  expect(rendered).toEqual(`${prefix}Notes\n\n${table}`);
+  const tree = await parseMarkdown(rendered, { hardSoftBreaks: true, latexMath: false });
+  expect(tree.children?.slice(-2).map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+});
+
+it.each([
+  "| Item | Detail |\n| --- | --- |\n" + "| A | one |\n".repeat(100),
+  "Notes\n\n| Item | Detail |\n| --- | --- |\n" + "| A | one |\n".repeat(100),
+  "Notes\n\n| Item |\n| --- |\n| A |",
+  "| Item |\n| --- |\n| A |",
+  "```md\nNotes\n| Item |\n| --- |\n| A |\n```",
+  "```yaml\n---\nkey: value\n---\n```",
+  "```yaml\n---\nkey: value",
+  "~~~md\n| Item |\n| --- |\n| A |\n~~~",
+  "````md\n```\n| Item |\n| --- |\n```\n````",
+  "    Notes\n    | Item |\n    | --- |\n    | A |",
+  "Notes\n| Item | Detail |\n| --- |\n| A |",
+])("leaves separated tables and table-like text unchanged: %s", (source) => {
+  expect(prepareMarkdownSource(source).render()).toEqual(source);
+});
+
 it.each([
   "src/components/message.tsx",
   "C:\\repo\\file.ts",
@@ -208,6 +444,47 @@ it("lets the engine own code boundaries while classifying candidate values", asy
   ]);
 });
 
+it("recognizes forge references in prose but not in code, links or paths", async () => {
+  const shorthand = createForgeShorthand({
+    forge: "gitlab",
+    remoteUrl: "git@gitlab.com:g/p.git",
+  })!;
+  const source = [
+    "Fixed in #12 and !13, see g/sub/q#14 and https://example.com/a#15.",
+    "`#16` and [#17](https://example.com) and src/app/index.ts and src/a/b/c#18",
+    "```\n#19\n```",
+  ].join("\n\n");
+  const prepared = prepareMarkdownSource(source, "/repo", {
+    forgeReferencePattern: shorthand.pattern,
+  });
+  const tree = recognizeTextLinks(
+    await parseMarkdown(prepared.render(), { latexMath: false }),
+    prepared.linkRecognition.text,
+    prepared.linkRecognition.inlineCode,
+  );
+  const recognized: string[] = [];
+  function collect(node: ASTNode) {
+    if (node.type === "Link" && node.attributes?.recognizedLink === "true") {
+      recognized.push(String(node.attributes.url));
+    }
+    node.children?.forEach(collect);
+  }
+  collect(tree);
+  expect(recognized).toEqual(["#12", "!13", "g/sub/q#14", "src/app/index.ts", "src/a/b/c#18"]);
+  expect(recognized.map((url) => shorthand.resolve(url))).toEqual([
+    "https://gitlab.com/g/p/-/issues/12",
+    "https://gitlab.com/g/p/-/merge_requests/13",
+    "https://gitlab.com/g/sub/q/-/issues/14",
+    null,
+    "https://gitlab.com/src/a/b/c/-/issues/18",
+  ]);
+  // A rejected native regex silently falls back to no recognition at all.
+  expect(toNativeLinkRecognition(prepared.linkRecognition).text).toMatchObject({
+    isDisabled: false,
+    isDefault: false,
+  });
+});
+
 describe("bare URL sentence punctuation", () => {
   it.each([".", ",", ";", ":", "!", "?", ")", ").", "...", "?!"])(
     "leaves %s outside the link and preserves the rendered sentence",
diff --git a/packages/app/src/components/markdown/renderer.tsx b/packages/app/src/components/markdown/renderer.tsx
index 8e51495369..19d3134eec 100644
--- a/packages/app/src/components/markdown/renderer.tsx
+++ b/packages/app/src/components/markdown/renderer.tsx
@@ -6,6 +6,9 @@ import {
   useAssistantFileLinkEnvironment,
 } from "@/assistant-file-links";
 import { useStableEvent } from "@/hooks/use-stable-event";
+import { matchCommandLink, useAgentCommandHints, type CommandHints } from "@/agent-commands";
+import { useForgeShorthand } from "@/git/forge-shorthand";
+import { openExternalUrl } from "@/utils/open-external-url";
 import { AttachmentLightbox, type ImageLightboxSource } from "@/components/attachment-lightbox";
 import type { Theme } from "@/styles/theme";
 import { isWeb } from "@/constants/platform";
@@ -48,6 +51,7 @@ export interface MarkdownRendererProps extends MarkdownImageContext {
   selectable?: boolean;
   streaming?: boolean;
   onLinkPress?: (url: string) => unknown;
+  agentCommands?: boolean;
 }
 
 /** All Markdown surfaces share the same engine and source adaptation. */
@@ -59,15 +63,21 @@ export const MarkdownRenderer = memo(function MarkdownRenderer(props: MarkdownRe
     () => splitStreamingMarkdown(completeLines, true).head.length,
     [completeLines],
   );
-  if (!streaming || boundary === 0) return <MarkdownPart {...props} />;
+  const Part = props.agentCommands ? CommandMarkdownPart : MarkdownPart;
+  if (!streaming || boundary === 0) return <Part {...props} />;
   return (
     <MarkdownBlockStack>
-      <MarkdownPart {...props} text={props.text.slice(0, boundary)} />
-      <MarkdownPart {...props} text={props.text.slice(boundary)} />
+      <Part {...props} text={props.text.slice(0, boundary)} />
+      <Part {...props} text={props.text.slice(boundary)} />
     </MarkdownBlockStack>
   );
 });
 
+const CommandMarkdownPart = memo(function CommandMarkdownPart(props: MarkdownRendererProps) {
+  const commandHints = useAgentCommandHints();
+  return <MarkdownPart {...props} commandHints={commandHints} />;
+});
+
 const MarkdownPart = memo(function MarkdownPart({
   text,
   compact = false,
@@ -75,23 +85,40 @@ const MarkdownPart = memo(function MarkdownPart({
   selectable = true,
   streaming = false,
   onLinkPress,
+  agentCommands: _agentCommands,
+  commandHints = null,
   ...imageContext
-}: MarkdownRendererProps) {
+}: MarkdownRendererProps & { commandHints?: CommandHints | null }) {
   const environment = useAssistantFileLinkEnvironment();
   const actions = useAssistantFileLinkActions();
+  const forgeShorthand = useForgeShorthand();
   const client =
     imageContext.client ??
     (environment.client?.readFile
       ? { readFile: environment.client.readFile.bind(environment.client) }
       : undefined);
-  const { markdown, imageSources, linkRecognition, linkSource } = useMarkdownSource(text, {
-    workspaceRoot: environment.workspaceRoot,
-    serverId: environment.serverId,
-    ...imageContext,
-    client,
-  });
+  const { markdown, imageSources, linkRecognition, linkSource } = useMarkdownSource(
+    text,
+    {
+      workspaceRoot: environment.workspaceRoot,
+      serverId: environment.serverId,
+      ...imageContext,
+      client,
+    },
+    { commandNames: commandHints?.names, forgeReferencePattern: forgeShorthand?.pattern },
+  );
   const [image, setImage] = useState<ImageLightboxSource | null>(null);
   const pressLink = useStableEvent(({ url, sourceType }: LinkPressEvent) => {
+    const command = commandHints && matchCommandLink(url, sourceType, commandHints.names);
+    if (command) {
+      commandHints.insert(command);
+      return;
+    }
+    const forgeUrl = sourceType === "text" ? forgeShorthand?.resolve(url) : null;
+    if (forgeUrl) {
+      void openExternalUrl(forgeUrl);
+      return;
+    }
     const source = linkSource(url, sourceType);
     if (onLinkPress && !actions.canResolveFile(source)) onLinkPress(url);
     else actions.open(source, "preferred");
diff --git a/packages/app/src/components/markdown/renderers.web.tsx b/packages/app/src/components/markdown/renderers.web.tsx
index 1d05b3b603..dd1b23f097 100644
--- a/packages/app/src/components/markdown/renderers.web.tsx
+++ b/packages/app/src/components/markdown/renderers.web.tsx
@@ -7,6 +7,7 @@ import type {
 } from "react-native-enriched-markdown";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useFileLink } from "@/assistant-file-links";
+import { useForgeShorthand } from "@/git/forge-shorthand";
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
 import { HighlightedCodeBlock } from "@/components/highlighted-code-block";
 import type { Theme } from "@/styles/theme";
@@ -31,7 +32,13 @@ function WebCodeBlock({ code, language }: CodeBlockRendererProps) {
 const LINK_HOVER_STYLE = { textDecoration: "underline" } as const;
 
 function WebLink({ link, anchorProps, children }: LinkRendererProps) {
-  const { tooltipPath, onHoverIn } = useFileLink(markdownLinkSource(link.url, link.sourceType));
+  const forgeShorthand = useForgeShorthand();
+  // A forge reference like `#12` carries its web URL so hover, copy and new-tab opens work.
+  const forgeUrl = link.sourceType === "text" ? forgeShorthand?.resolve(link.url) : null;
+  const { tooltipPath, onHoverIn } = useFileLink(
+    forgeUrl ? markdownLinkSource(forgeUrl) : markdownLinkSource(link.url, link.sourceType),
+  );
+  const tooltip = forgeUrl ?? tooltipPath;
   const [hovered, setHovered] = useState(false);
   const handleMouseEnter = useCallback(() => setHovered(true), []);
   const handleMouseLeave = useCallback(() => setHovered(false), []);
@@ -46,6 +53,7 @@ function WebLink({ link, anchorProps, children }: LinkRendererProps) {
   const anchor = (
     <a
       {...anchorProps}
+      href={forgeUrl ?? anchorProps.href}
       style={anchorStyle}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
@@ -58,10 +66,10 @@ function WebLink({ link, anchorProps, children }: LinkRendererProps) {
       <TooltipTrigger asChild onHoverIn={onHoverIn}>
         <InlineLinkTrigger>{anchor}</InlineLinkTrigger>
       </TooltipTrigger>
-      {tooltipPath ? (
+      {tooltip ? (
         <TooltipContent side="top" align="start" maxWidth={520}>
           <Text selectable={false} style={styles.tooltipPath}>
-            {tooltipPath}
+            {tooltip}
           </Text>
         </TooltipContent>
       ) : null}
diff --git a/packages/app/src/components/markdown/source.ts b/packages/app/src/components/markdown/source.ts
index 5c82088898..8b15b8ff98 100644
--- a/packages/app/src/components/markdown/source.ts
+++ b/packages/app/src/components/markdown/source.ts
@@ -24,10 +24,12 @@ const FILE_NAME = String.raw`${PATH_SEGMENT}\.(?:${FILE_EXTENSIONS})`;
 // Bare prose paths need a known extension, a line suffix, or at least two separators.
 const PROSE_PATH = String.raw`(?:${PATH_PREFIX}${HAS_PATH_LETTER}${SEPARATED_PATH}|${HAS_PATH_LETTER}(?:${PATH_SEGMENT}(?:[\\/]${PATH_SEGMENT})*[\\/]${FILE_NAME}|${PATH_SEGMENT}(?:[\\/]${PATH_SEGMENT}){2,}|${SEPARATED_PATH}(?=:)))`;
 
-function createFilePattern(path: string): RegExp {
+function createTextPattern(path: string, forgeReferencePattern?: string): RegExp {
+  // Forge references come before paths so `group/project#12` is not read as a path.
+  const forgeReference = forgeReferencePattern ? `|${forgeReferencePattern}` : "";
   // The native adapter mistakes a literal + in lookbehind for a quantifier; use its hex escape.
   return new RegExp(
-    String.raw`(?:${BARE_URL}|(?<![a-zA-Z0-9\u0080-\uFFFF_@.%\x2b~:/\\-])(?:${path}|${FILE_NAME})${LINE_SUFFIX}(?![a-zA-Z0-9\u0080-\uFFFF_@%+:/\\-]|\.${PATH_CHARACTER}))`,
+    String.raw`(?:${BARE_URL}${forgeReference}|(?<![a-zA-Z0-9\u0080-\uFFFF_@.%\x2b~:/\\-])(?:${path}|${FILE_NAME})${LINE_SUFFIX}(?![a-zA-Z0-9\u0080-\uFFFF_@%+:/\\-]|\.${PATH_CHARACTER}))`,
     "g",
   );
 }
@@ -38,8 +40,20 @@ const URL_CHARACTER = String.raw`[^\s<>()"'\x60]`;
 const URL_GROUP = String.raw`\(${URL_CHARACTER}*\)`;
 const BARE_URL = String.raw`https?://(?:${URL_CHARACTER}|${URL_GROUP})*(?:[^\s<>()"'\x60.,;:!?]|${URL_GROUP})`;
 
-const FILE_PATTERN = createFilePattern(PROSE_PATH);
-function linkMetadata(inlineCodePaths: ReadonlySet<string>) {
+const TEXT_PATTERN = createTextPattern(PROSE_PATH);
+// One entry per distinct workspace forge remote; reuse keeps the engine's regex identity stable.
+const textPatternsByForgeReference = new Map<string, RegExp>();
+function textPattern(forgeReferencePattern?: string): RegExp {
+  if (!forgeReferencePattern) return TEXT_PATTERN;
+  let pattern = textPatternsByForgeReference.get(forgeReferencePattern);
+  if (!pattern) {
+    pattern = createTextPattern(PROSE_PATH, forgeReferencePattern);
+    textPatternsByForgeReference.set(forgeReferencePattern, pattern);
+  }
+  return pattern;
+}
+
+function linkMetadata(inlineCodePaths: ReadonlySet<string>, forgeReferencePattern?: string) {
   // The engine accepts regexes on both platforms. Classify complete code spans
   // first, then pass literal matches rather than maintaining a second path grammar.
   const alternatives = [...inlineCodePaths].map((path) =>
@@ -47,7 +61,7 @@ function linkMetadata(inlineCodePaths: ReadonlySet<string>) {
   );
   return {
     linkRecognition: {
-      text: FILE_PATTERN,
+      text: textPattern(forgeReferencePattern),
       inlineCode: new RegExp(
         String.raw`^(?:https?://[^\s<>]+${alternatives.length ? `|${alternatives.join("|")}` : ""})$`,
       ),
@@ -56,7 +70,11 @@ function linkMetadata(inlineCodePaths: ReadonlySet<string>) {
   };
 }
 
-function collectInlineCodePaths(source: string, workspaceRoot?: string): ReadonlySet<string> {
+function collectInlineCodePaths(
+  source: string,
+  workspaceRoot?: string,
+  commandNames?: ReadonlySet<string>,
+): ReadonlySet<string> {
   const paths = new Set<string>();
   const previousEnds = new Map<number, number>();
   // Collect candidates between consecutive runs of equal length. The engine owns
@@ -74,7 +92,11 @@ function collectInlineCodePaths(source: string, workspaceRoot?: string): Readonl
       value = value.slice(1, -1);
     }
     const classification = classifyAssistantFileLink(value, { workspaceRoot });
-    if (classification && classification.kind !== "external") paths.add(value);
+    if (
+      (classification && classification.kind !== "external") ||
+      (value.startsWith("/") && commandNames?.has(value.slice(1)))
+    )
+      paths.add(value);
   }
   return paths;
 }
@@ -112,7 +134,12 @@ function workspaceHoverTitle(link: Link, markup: string, workspaceRoot?: string)
 export function prepareMarkdownSource(
   source: string,
   workspaceRoot?: string,
-  options: { supportsSvg?: boolean } = {},
+  options: {
+    supportsSvg?: boolean;
+    commandNames?: ReadonlySet<string>;
+    /** Regex source for forge references such as `#12`; see `@/git/forge-shorthand`. */
+    forgeReferencePattern?: string;
+  } = {},
 ) {
   source = normalizeMarkdownHtml(source);
   const images: MarkdownImage[] = [];
@@ -122,12 +149,19 @@ export function prepareMarkdownSource(
       extensions: [gfmTable()],
       mdastExtensions: [gfmTableFromMarkdown()],
     }));
-  const metadata = linkMetadata(collectInlineCodePaths(source, workspaceRoot));
+  const metadata = linkMetadata(
+    collectInlineCodePaths(source, workspaceRoot, options.commandNames),
+    options.forgeReferencePattern,
+  );
   const edits: { start: number; end: number; text: string }[] = [];
   if (
     !source.includes("![") &&
     !source.includes("||") &&
     !source.includes("&") &&
+    // Match content, header, and delimiter lines; quote-only lines count as blank.
+    !/^[\t >]*[^\t >\r\n][^\r\n]*(?:\r\n|\r|\n)[^\r\n]+(?:\r\n|\r|\n)(?=[\t >:|-]*\|)[\t >|]*:?-[-\t :|]*$/m.test(
+      source,
+    ) &&
     !(workspaceRoot && source.includes("]("))
   ) {
     return { images, ...metadata, render: () => source };
@@ -202,11 +236,25 @@ export function prepareMarkdownSource(
       if (lineEnd < end) split(lineEnd);
     }
   }
-  function visit(node: Nodes) {
-    const start = node.position?.start.offset;
-    const end = node.position?.end.offset;
-    if (start !== undefined && end !== undefined) {
+  function visit(node: Nodes, previous?: Nodes) {
+    const position = node.position;
+    if (position?.start.offset !== undefined && position.end.offset !== undefined) {
+      const start = position.start.offset;
+      const end = position.end.offset;
       if (node.type === "paragraph") splitStandaloneImages(node, start, end);
+      if (
+        node.type === "table" &&
+        previous?.type === "paragraph" &&
+        previous.position?.end.line === position.start.line - 1
+      ) {
+        // MD4C only recognizes a table header on the first line of a paragraph.
+        const lineStart =
+          Math.max(source.lastIndexOf("\n", start - 1), source.lastIndexOf("\r", start - 1)) + 1;
+        const newline = source.slice(lineStart - 2, lineStart).replace(/[^\r\n]/g, "");
+        const blank = source.slice(lineStart, start).replace(/[^>]/g, " ").trimEnd();
+        const boundary = lineStart - newline.length;
+        edits.push({ start: boundary, end: lineStart, text: `${newline}${blank}${newline}` });
+      }
       if (node.type === "link") {
         const title = workspaceHoverTitle(node, source.slice(start, end), workspaceRoot);
         if (title !== null)
@@ -234,7 +282,8 @@ export function prepareMarkdownSource(
         if (text !== source.slice(start, end)) edits.push({ start, end, text });
       }
     }
-    if ("children" in node) node.children.forEach(visit);
+    if ("children" in node)
+      node.children.forEach((child, index) => visit(child, node.children[index - 1]));
   }
   visit(getTree());
   return {
diff --git a/packages/app/src/components/message.tsx b/packages/app/src/components/message.tsx
index 2c6165d305..2bc96f6b97 100644
--- a/packages/app/src/components/message.tsx
+++ b/packages/app/src/components/message.tsx
@@ -1,3 +1,4 @@
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { MessagePreview, MessageSender } from "@/components/user-message";
 import { useStableEvent } from "@/hooks/use-stable-event";
 import { getAgentAttachmentPillContent } from "@/attachments/attachment-pill-content";
@@ -556,6 +557,15 @@ interface AssistantTurnFooterProps {
 
 const assistantTurnFooterStylesheet = StyleSheet.create((theme) => ({
   container: {
+    flex: 1,
+    minWidth: 0,
+    minHeight: 24,
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: theme.spacing[2],
+  },
+  actions: {
+    height: 24,
     flexDirection: "row",
     alignItems: "center",
     gap: theme.spacing[2],
@@ -567,21 +577,25 @@ const assistantTurnFooterStylesheet = StyleSheet.create((theme) => ({
     marginTop: 0,
     marginLeft: -theme.spacing[1],
   },
-  labelWrapper: {
-    position: "relative",
+  labelButton: {
+    flex: 1,
+    minHeight: 24,
+    flexDirection: "row",
+    alignItems: "center",
+    minWidth: 0,
   },
-  labelSizer: {
+  label: {
+    width: "100%",
+    flexShrink: 0,
     color: theme.colors.foregroundMuted,
     fontSize: STREAM_METADATA_FONT_SIZE,
+  },
+  overlappingLabel: {
+    marginLeft: "-100%",
+  },
+  hiddenLabel: {
     opacity: 0,
   },
-  labelOverlay: {
-    position: "absolute",
-    top: 0,
-    left: 0,
-    color: theme.colors.foregroundMuted,
-    fontSize: STREAM_METADATA_FONT_SIZE,
-  },
 }));
 
 const TIMESTAMP_REVEAL_MS = 3000;
@@ -648,31 +662,51 @@ export const AssistantTurnFooter = memo(function AssistantTurnFooter({
 
   return (
     <View style={assistantTurnFooterStylesheet.container}>
-      {getContent ? (
-        <TurnCopyButton
-          getContent={getContent}
-          containerStyle={assistantTurnFooterStylesheet.copyButton}
-        />
+      {getContent || canFork ? (
+        <View style={assistantTurnFooterStylesheet.actions}>
+          {getContent ? (
+            <TurnCopyButton
+              getContent={getContent}
+              containerStyle={assistantTurnFooterStylesheet.copyButton}
+            />
+          ) : null}
+          {canFork ? <AssistantForkMenu onFork={handleFork} /> : null}
+        </View>
       ) : null}
-      {canFork ? <AssistantForkMenu onFork={handleFork} /> : null}
       {primaryLabel ? (
         <Pressable
+          style={assistantTurnFooterStylesheet.labelButton}
           onPress={handlePress}
           onHoverIn={handleHoverIn}
           onHoverOut={handleHoverOut}
           accessibilityRole={canSwap ? "button" : undefined}
           accessibilityLabel={canSwap ? `${durationLabel}, ended ${timestampLabel}` : primaryLabel}
         >
-          <View style={assistantTurnFooterStylesheet.labelWrapper}>
-            {/* Sizer reserves space for whichever label is longer so the
-                container width is stable across hover transitions. */}
-            <Text style={assistantTurnFooterStylesheet.labelSizer} aria-hidden>
-              {primaryLabel.length >= timestampLabel.length ? primaryLabel : timestampLabel}
+          {/* Both labels participate in layout at the available width. Overlapping their
+              columns reserves the taller wrapped height without measuring text or characters. */}
+          <Text
+            testID={!showTimestamp ? "turn-footer-timing-label" : undefined}
+            aria-hidden={showTimestamp}
+            style={[
+              assistantTurnFooterStylesheet.label,
+              showTimestamp && assistantTurnFooterStylesheet.hiddenLabel,
+            ]}
+          >
+            {primaryLabel}
+          </Text>
+          {canSwap ? (
+            <Text
+              testID={showTimestamp ? "turn-footer-timing-label" : undefined}
+              aria-hidden={!showTimestamp}
+              style={[
+                assistantTurnFooterStylesheet.label,
+                assistantTurnFooterStylesheet.overlappingLabel,
+                !showTimestamp && assistantTurnFooterStylesheet.hiddenLabel,
+              ]}
+            >
+              {timestampLabel}
             </Text>
-            <Text style={assistantTurnFooterStylesheet.labelOverlay}>
-              {showTimestamp ? timestampLabel : primaryLabel}
-            </Text>
-          </View>
+          ) : null}
         </Pressable>
       ) : null}
     </View>
@@ -1199,6 +1233,7 @@ export const AssistantMessage = memo(function AssistantMessage({
     >
       <MarkdownRenderer
         text={revealedMessage}
+        agentCommands
         streaming={phase !== "complete" || revealedMessage.length < renderedMessage.text.length}
         client={client}
         workspaceRoot={workspaceRoot}
@@ -1482,9 +1517,9 @@ export const TodoListCard = memo(function TodoListCard({
     };
   }, [activity, t]);
 
-  const handleToggle = useCallback(() => {
-    setIsExpanded((prev) => !prev);
-  }, []);
+  const hold = useDisclosureHold();
+  const toggleExpanded = useCallback(() => setIsExpanded((prev) => !prev), []);
+  const handleToggle = useCallback(() => hold(toggleExpanded), [hold, toggleExpanded]);
 
   const renderDetails = useCallback(() => {
     return (
@@ -2278,6 +2313,7 @@ export const ToolCall = memo(function ToolCall({
 
   const isMobile = useIsCompactFormFactor();
   const shouldRenderInline = !isMobile || forceInline;
+  const hold = useDisclosureHold();
 
   const effectiveDetail = useMemo<ToolCallDetail | undefined>(() => {
     if (detail) {
@@ -2329,9 +2365,10 @@ export const ToolCall = memo(function ToolCall({
         showLoadingSkeleton: presentation.isLoadingDetails,
       });
     } else {
-      toggleExpanded();
+      hold(toggleExpanded);
     }
   }, [
+    hold,
     shouldRenderInline,
     toggleExpanded,
     openToolCall,
diff --git a/packages/app/src/components/model-browser.tsx b/packages/app/src/components/model-browser.tsx
index 2ca6b6a9c2..82edd1458d 100644
--- a/packages/app/src/components/model-browser.tsx
+++ b/packages/app/src/components/model-browser.tsx
@@ -216,17 +216,19 @@ export function ModelProviderGlyph({
   provider,
   serverId,
   size,
+  strokeWidth,
   tone = "muted",
 }: {
   provider: string;
   serverId: string | null;
   size: number;
+  strokeWidth?: number;
   tone?: ProviderGlyphTone;
 }) {
   const Icon = useProviderIcon(provider, serverId);
   const color =
     tone === "foreground" ? styles.providerIconForeground.color : styles.providerIconMuted.color;
-  return <Icon size={size} color={color} />;
+  return <Icon size={size} strokeWidth={strokeWidth} color={color} />;
 }
 
 function HeaderSettingsIcon({ disabled }: { disabled: boolean }) {
@@ -1235,7 +1237,7 @@ function ProviderErrorEmptyState({
       <ThemedAlertTriangle size={ICON_SIZE.md} uniProps={foregroundMutedMapping} />
       <Text style={styles.emptyStateText}>{message}</Text>
       {onRetryProvider ? (
-        <Button variant="default" size="sm" onPress={handleRetry} disabled={isRetryingProvider}>
+        <Button variant="default" onPress={handleRetry} disabled={isRetryingProvider}>
           {isRetryingProvider ? t("modelSelector.retrying") : t("modelSelector.retry")}
         </Button>
       ) : null}
diff --git a/packages/app/src/components/plan-card.tsx b/packages/app/src/components/plan-card.tsx
index c0456f524d..65aaa96e92 100644
--- a/packages/app/src/components/plan-card.tsx
+++ b/packages/app/src/components/plan-card.tsx
@@ -1,3 +1,4 @@
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { MarkdownRenderer } from "@/components/markdown/renderer";
 import { isWeb } from "@/constants/platform";
 import type { Theme } from "@/styles/theme";
@@ -50,7 +51,8 @@ function PlanCardContent({
     () => (isWeb ? ({ "aria-expanded": expanded } as const) : null),
     [expanded],
   );
-  const toggleExpanded = useCallback(() => setExpanded((value) => !value), []);
+  const hold = useDisclosureHold();
+  const toggleExpanded = useCallback(() => hold(() => setExpanded((value) => !value)), [hold]);
   const containerStyle = useMemo(
     () => [styles.container, disableOuterSpacing && styles.containerCompact],
     [disableOuterSpacing],
diff --git a/packages/app/src/components/project-edit-sheet.tsx b/packages/app/src/components/project-edit-sheet.tsx
index d80fa2bad0..2da515b5c8 100644
--- a/packages/app/src/components/project-edit-sheet.tsx
+++ b/packages/app/src/components/project-edit-sheet.tsx
@@ -9,9 +9,8 @@ import type { ProjectIconSource } from "@getpaseo/protocol/messages";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { ProjectIconView } from "@/components/project-icon-view";
 import { Button } from "@/components/ui/button";
-import type { FieldControlSize } from "@/components/ui/control-geometry";
+import type { ControlSize } from "@/components/ui/control-geometry";
 import { Field, FormTextInput } from "@/components/ui/form-field";
-import { useIsCompactFormFactor } from "@/constants/layout";
 import { useToast } from "@/contexts/toast-context";
 import { useFilePicker } from "@/hooks/use-file-picker";
 import {
@@ -50,7 +49,7 @@ export function ProjectEditSheet({
   const queryClient = useQueryClient();
   const toast = useToast();
   const { pickFiles } = useFilePicker();
-  const size: FieldControlSize = useIsCompactFormFactor() ? "md" : "sm";
+  const size: ControlSize = "md";
   const [form] = useState(() => openProjectEditForm(snapshot));
   const state = useSyncExternalStore(form.subscribe, form.getState, form.getState);
 
@@ -96,7 +95,6 @@ export function ProjectEditSheet({
       <View style={styles.footer}>
         <Button
           variant="secondary"
-          size="md"
           style={styles.footerButton}
           onPress={handleClose}
           disabled={isSaving}
@@ -105,7 +103,6 @@ export function ProjectEditSheet({
         </Button>
         <Button
           variant="default"
-          size="md"
           style={styles.footerButton}
           onPress={handleSubmit}
           disabled={!state.canSubmit}
diff --git a/packages/app/src/components/provider-catalog-list.tsx b/packages/app/src/components/provider-catalog-list.tsx
index 3e75765919..b911f10553 100644
--- a/packages/app/src/components/provider-catalog-list.tsx
+++ b/packages/app/src/components/provider-catalog-list.tsx
@@ -89,7 +89,7 @@ function CatalogTile({ entry, width, installing, onInstall }: CatalogTileProps)
         </View>
       </View>
       <Button
-        size="xs"
+        size="sm"
         variant="outline"
         disabled={installing}
         loading={installing}
diff --git a/packages/app/src/components/provider-diagnostic-sheet.tsx b/packages/app/src/components/provider-diagnostic-sheet.tsx
index 61d42882e8..60231e4e48 100644
--- a/packages/app/src/components/provider-diagnostic-sheet.tsx
+++ b/packages/app/src/components/provider-diagnostic-sheet.tsx
@@ -222,10 +222,10 @@ function AddCustomModelSubSheet({
         />
         {error ? <Text style={sheetStyles.errorText}>{error}</Text> : null}
         <View style={sheetStyles.formActions}>
-          <Button variant="secondary" size="sm" onPress={onClose} disabled={saving}>
+          <Button variant="secondary" onPress={onClose} disabled={saving}>
             {t("common.actions.cancel")}
           </Button>
-          <Button variant="default" size="sm" onPress={handleAdd} disabled={!canAdd || saving}>
+          <Button variant="default" onPress={handleAdd} disabled={!canAdd || saving}>
             {saving ? t("settings.providers.models.adding") : t("settings.providers.models.add")}
           </Button>
         </View>
@@ -436,18 +436,11 @@ function renderProviderSheetFooter({
         <ProviderUpdatedLabel fetchedAt={fetchedAt} isCompact={isCompact} />
       ) : null}
       <View style={actionsStyle}>
-        <Button
-          variant="secondary"
-          size="sm"
-          leftIcon={Plus}
-          onPress={onOpenAddSheet}
-          style={buttonStyle}
-        >
+        <Button variant="secondary" leftIcon={Plus} onPress={onOpenAddSheet} style={buttonStyle}>
           {t("settings.providers.models.addModel")}
         </Button>
         <Button
           variant="secondary"
-          size="sm"
           leftIcon={FileText}
           onPress={onOpenDiagSheet}
           style={buttonStyle}
@@ -456,7 +449,6 @@ function renderProviderSheetFooter({
         </Button>
         <Button
           variant="default"
-          size="sm"
           leftIcon={modelsRefreshing ? undefined : RotateCw}
           onPress={onRefreshModels}
           disabled={modelsRefreshing}
@@ -520,7 +512,7 @@ function ProviderModalBody(props: ProviderModalBodyProps) {
       <View style={sheetStyles.emptyState}>
         <AlertTriangle size={theme.iconSize.md} color={theme.colors.foregroundMuted} />
         <Text style={sheetStyles.mutedText}>{providerErrorMessage}</Text>
-        <Button variant="default" size="sm" onPress={onRefresh} disabled={modelsRefreshing}>
+        <Button variant="default" onPress={onRefresh} disabled={modelsRefreshing}>
           {modelsRefreshing
             ? t("settings.providers.models.retrying")
             : t("settings.providers.models.retry")}
diff --git a/packages/app/src/components/provider-icons.ts b/packages/app/src/components/provider-icons.ts
index d8548cbd16..995c0876da 100644
--- a/packages/app/src/components/provider-icons.ts
+++ b/packages/app/src/components/provider-icons.ts
@@ -20,6 +20,8 @@ import { resolveProviderIconName } from "@/components/provider-icon-name";
 export interface ProviderIconProps {
   size: number;
   color: string;
+  /** Honoured by outline glyphs such as the fallback; brand marks are filled and ignore it. */
+  strokeWidth?: number;
 }
 
 export type ProviderIconComponent = ComponentType<ProviderIconProps>;
diff --git a/packages/app/src/components/question-form-card.browser.test.tsx b/packages/app/src/components/question-form-card.browser.test.tsx
index 0b2a5df25d..a91ba41215 100644
--- a/packages/app/src/components/question-form-card.browser.test.tsx
+++ b/packages/app/src/components/question-form-card.browser.test.tsx
@@ -39,7 +39,10 @@ afterEach(() => {
   }
 });
 
-function buildPermission(question: Record<string, unknown>): PendingPermission {
+function buildPermission(
+  question: Record<string, unknown>,
+  following: Record<string, unknown>[] = [],
+): PendingPermission {
   return {
     key: "perm-1",
     agentId: "agent-1",
@@ -48,12 +51,12 @@ function buildPermission(question: Record<string, unknown>): PendingPermission {
       provider: "claude",
       name: "AskUserQuestion",
       kind: "question",
-      input: { questions: [question] },
+      input: { questions: [question, ...following] },
     },
   };
 }
 
-function mountCard(question: Record<string, unknown>) {
+function mountCard(question: Record<string, unknown>, following: Record<string, unknown>[] = []) {
   const onRespond = vi.fn<(response: AgentPermissionResponse) => void>();
   const container = document.createElement("div");
   document.body.appendChild(container);
@@ -61,7 +64,7 @@ function mountCard(question: Record<string, unknown>) {
   act(() =>
     root.render(
       <QuestionFormCard
-        permission={buildPermission(question)}
+        permission={buildPermission(question, following)}
         onRespond={onRespond}
         isResponding={false}
         responseError={null}
@@ -71,10 +74,14 @@ function mountCard(question: Record<string, unknown>) {
   mounted.push({ root, container });
 
   const view = within(container);
-  const optionRole = question.multiSelect ? "checkbox" : "radio";
   const otherInput = () =>
     view.getByRole<HTMLInputElement>("textbox", { name: String(question.question) });
-  const check = (label: string) => act(() => view.getByRole(optionRole, { name: label }).click());
+  const check = (label: string) =>
+    act(() =>
+      (
+        view.queryByRole("radio", { name: label }) ?? view.getByRole("checkbox", { name: label })
+      ).click(),
+    );
   const type = (text: string) => {
     const input = otherInput();
     const valueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
@@ -90,7 +97,7 @@ function mountCard(question: Record<string, unknown>) {
     if (!response || response.behavior !== "allow") throw new Error("card did not submit");
     return (response.updatedInput as { answers: Record<string, string> }).answers;
   };
-  return { check, type, otherInput, submit, submittedAnswers };
+  return { check, type, otherInput, submit, submittedAnswers, view, onRespond };
 }
 
 const multiSelectQuestion = {
@@ -154,3 +161,31 @@ describe("QuestionFormCard other answers", () => {
     expect(card.submittedAnswers()).toEqual({ Provider: "Codex" });
   });
 });
+
+describe("QuestionFormCard explicit navigation", () => {
+  it("keeps a picked option visible until Next and submits only on Submit", () => {
+    const card = mountCard(singleSelectQuestion, [multiSelectQuestion]);
+    card.check("Codex");
+    expect(card.view.getByRole("radio", { name: "Codex" }).getAttribute("aria-checked")).toBe(
+      "true",
+    );
+    expect(card.onRespond).not.toHaveBeenCalled();
+    act(() => card.view.getByRole("button", { name: "Next" }).click());
+    card.check("Apple");
+    expect(card.onRespond).not.toHaveBeenCalled();
+    card.submit();
+    expect(card.submittedAnswers()).toEqual({ Provider: "Codex", Fruits: "Apple" });
+  });
+
+  it("selects an option when its description is clicked without submitting", () => {
+    const card = mountCard({
+      ...singleSelectQuestion,
+      options: [{ label: "Codex", description: "Use this provider" }],
+    });
+    act(() => card.view.getByText("Use this provider").click());
+    expect(card.view.getByRole("radio", { name: "Codex" }).getAttribute("aria-checked")).toBe(
+      "true",
+    );
+    expect(card.onRespond).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/app/src/components/question-form-card.tsx b/packages/app/src/components/question-form-card.tsx
index 8ff81963d1..7417cf64c4 100644
--- a/packages/app/src/components/question-form-card.tsx
+++ b/packages/app/src/components/question-form-card.tsx
@@ -43,20 +43,16 @@ const IS_WEB = isWeb;
 // drag to the preview's nested scroll, so lines past a cap would be unreachable.
 const OPTION_PREVIEW_MAX_HEIGHT = IS_WEB ? 240 : undefined;
 
-// Web clicks that must not answer: a link in the label, anything in the description, and the
-// second click of a double-click, which would otherwise land on the next question's options.
-function isNonAnsweringClick(event: GestureResponderEvent, description: View | null): boolean {
+// Links are independent actions. Ignore repeat clicks so double-click text selection
+// toggles an option only once.
+function isNonAnsweringClick(event: GestureResponderEvent): boolean {
   if (!IS_WEB) return false;
   const click = event.nativeEvent as unknown as MouseEvent;
   if (click.detail > 1) return true;
   const target = click.target as Element | null;
-  const descriptionElement = description as unknown as Element | null;
-  return Boolean(target?.closest("a") || descriptionElement?.contains(target));
+  return Boolean(target?.closest("a"));
 }
 
-// The description is selectable text, so a touch on it belongs to the text, not the option.
-const claimResponder = () => true;
-
 function getQuestionInputPlaceholder({
   question,
   answerPlaceholder,
@@ -92,10 +88,9 @@ function QuestionOptionRow({
 }: QuestionOptionRowProps) {
   const { theme } = useUnistyles();
 
-  const descriptionRef = useRef<View>(null);
   const handlePress = useCallback(
     (event: GestureResponderEvent) => {
-      if (isNonAnsweringClick(event, descriptionRef.current)) return;
+      if (isNonAnsweringClick(event)) return;
       onToggle(qIndex, optIndex, multiSelect);
     },
     [onToggle, qIndex, optIndex, multiSelect],
@@ -152,11 +147,7 @@ function QuestionOptionRow({
         <View style={styles.optionTextBlock}>
           <MarkdownRenderer text={option.label} compact muted={!isSelected} selectable={false} />
           {option.description ? (
-            <View
-              ref={descriptionRef}
-              testID="question-form-option-description"
-              onStartShouldSetResponder={claimResponder}
-            >
+            <View testID="question-form-option-description">
               <MarkdownRenderer text={option.description} compact muted />
             </View>
           ) : null}
@@ -413,12 +404,8 @@ export function QuestionFormCard({
         });
         otherInputRef.current?.replaceText("");
       }
-
-      if (!multiSelect && next.size > 0 && qIndex === activeQuestionIndex && questions) {
-        setActiveQuestionIndex(Math.min(qIndex + 1, questions.length - 1));
-      }
     },
-    [activeQuestionIndex, otherTexts, questions, selections],
+    [otherTexts, selections],
   );
 
   const setOtherText = useCallback(
diff --git a/packages/app/src/components/rename-modal.tsx b/packages/app/src/components/rename-modal.tsx
index 5741abb087..85043de236 100644
--- a/packages/app/src/components/rename-modal.tsx
+++ b/packages/app/src/components/rename-modal.tsx
@@ -145,7 +145,6 @@ export function AdaptiveRenameModal({
         <View style={styles.actions}>
           <Button
             variant="secondary"
-            size="sm"
             style={styles.actionButton}
             onPress={handleCancel}
             disabled={isPending}
@@ -155,7 +154,6 @@ export function AdaptiveRenameModal({
           </Button>
           <Button
             variant="default"
-            size="sm"
             style={styles.actionButton}
             onPress={handleSubmitVoid}
             disabled={submitDisabled}
diff --git a/packages/app/src/components/resize-handle.tsx b/packages/app/src/components/resize-handle.tsx
index c3930688c2..8bb2434ae8 100644
--- a/packages/app/src/components/resize-handle.tsx
+++ b/packages/app/src/components/resize-handle.tsx
@@ -3,7 +3,7 @@ import { View, type PointerEvent as RNPointerEvent } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { startResizeHandleDrag, type ResizeHandleDrag } from "@/components/resize-handle-drag";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
@@ -47,7 +47,7 @@ export function ResizeHandle({
   onResizeSplit,
 }: ResizeHandleProps) {
   const { theme } = useUnistyles();
-  const finePointer = useHasFinePointer();
+  const { finePointer } = usePointerCapabilities();
   const pointerStatesRef = useRef(new Map<number, PointerState>());
   const touchStateRef = useRef<PointerState | null>(null);
   const cursorBeforeDragRef = useRef<string | null>(null);
diff --git a/packages/app/src/components/schedules/cadence-editor.tsx b/packages/app/src/components/schedules/cadence-editor.tsx
index 2774edd187..2c91054a27 100644
--- a/packages/app/src/components/schedules/cadence-editor.tsx
+++ b/packages/app/src/components/schedules/cadence-editor.tsx
@@ -2,7 +2,7 @@ import { useCallback, useMemo, useReducer, useState, type ReactNode } from "reac
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import type { ScheduleCadence } from "@getpaseo/protocol/schedule/types";
-import type { FieldControlSize } from "@/components/ui/control-geometry";
+import type { ControlSize } from "@/components/ui/control-geometry";
 import { Field, FormTextInput } from "@/components/ui/form-field";
 import { SelectField, type SelectFieldOption } from "@/components/ui/select-field";
 import {
@@ -20,7 +20,7 @@ export interface CadenceEditorProps {
   value: ScheduleCadence;
   onChange: (next: ScheduleCadence) => void;
   error?: string;
-  size?: FieldControlSize;
+  size?: ControlSize;
 }
 
 const PRESET_OPTIONS: SelectFieldOption<string>[] = CADENCE_PRESET_OPTIONS.map((option) => ({
diff --git a/packages/app/src/components/schedules/schedule-form-sheet.tsx b/packages/app/src/components/schedules/schedule-form-sheet.tsx
index 230a41e2e9..f66e70b520 100644
--- a/packages/app/src/components/schedules/schedule-form-sheet.tsx
+++ b/packages/app/src/components/schedules/schedule-form-sheet.tsx
@@ -19,9 +19,8 @@ import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-moda
 import { ComboboxItem } from "@/components/ui/combobox";
 import { Button } from "@/components/ui/button";
 import { CombinedModelSelector } from "@/components/combined-model-selector";
-import { useIsCompactFormFactor } from "@/constants/layout";
 import { HostStatusDotSlot } from "@/components/hosts/host-picker";
-import { createControlGeometry, type FieldControlSize } from "@/components/ui/control-geometry";
+import { createControlGeometry, type ControlSize } from "@/components/ui/control-geometry";
 import { Field, FormTextInput } from "@/components/ui/form-field";
 import { Switch } from "@/components/ui/switch";
 import { useProviderIcon } from "@/components/provider-icons";
@@ -239,7 +238,7 @@ function OpenScheduleFormSheet({
   mode,
   schedule,
 }: ScheduleFormSheetProps & { onDismiss: () => void }): ReactElement {
-  const controlSize: FieldControlSize = useIsCompactFormFactor() ? "md" : "sm";
+  const controlSize: ControlSize = "md";
   const { projects } = useProjects();
   const hostProfiles = useHosts();
   const hosts = useStoreWithEqualityFn(
@@ -460,7 +459,7 @@ interface ScheduleFormFieldsProps {
   state: ScheduleFormState;
   providerSnapshot: ReturnType<typeof useScheduleFormProviderSnapshot>;
   agentTargetLabel: string | null;
-  controlSize: FieldControlSize;
+  controlSize: ControlSize;
   cadenceError: string | null;
   mutationServerId: string;
 }
@@ -557,7 +556,7 @@ interface ScheduleTargetFieldsProps {
   state: ScheduleFormState;
   providerSnapshot: ReturnType<typeof useScheduleFormProviderSnapshot>;
   agentTargetLabel: string | null;
-  controlSize: FieldControlSize;
+  controlSize: ControlSize;
   mutationServerId: string;
 }
 
@@ -819,7 +818,7 @@ function ScheduleIsolationField({
 }: {
   model: ScheduleFormModel;
   state: ScheduleFormState;
-  size: FieldControlSize;
+  size: ControlSize;
 }): ReactElement {
   const options = useMemo<SelectFieldOption<"local" | "worktree">[]>(
     () => [
@@ -892,7 +891,7 @@ function ScheduleAgentTargetField({
   size,
 }: {
   label: string | null;
-  size: FieldControlSize;
+  size: ControlSize;
 }): ReactElement {
   const fieldStyle = useMemo(
     () => [styles.readonlyField, size === "sm" ? styles.readonlyFieldSm : styles.readonlyFieldMd],
diff --git a/packages/app/src/components/settings/detail-row.tsx b/packages/app/src/components/settings/detail-row.tsx
index f256babe50..0838d06ca4 100644
--- a/packages/app/src/components/settings/detail-row.tsx
+++ b/packages/app/src/components/settings/detail-row.tsx
@@ -1,12 +1,19 @@
+import type { ReactNode } from "react";
 import { SettingsRowHeader } from "./row-header";
 
 interface SettingsDetailRowProps {
   label: string;
+  /** Shown beside the label, such as a badge. */
+  labelAccessory?: ReactNode;
+  /** A line under the label saying what the row leads to. */
+  hint?: string;
   /** What the detail is set to, so the row says it without being opened. */
   summary?: string;
   onPress: () => void;
   /** A row that cannot be opened keeps its summary and drops the chevron. */
   disabled?: boolean;
+  /** Opens a page outside the app; an outward arrow replaces the chevron. */
+  external?: boolean;
   testID?: string;
 }
 
@@ -14,20 +21,6 @@ interface SettingsDetailRowProps {
  * A settings row that opens a detail, such as a sheet, for one setting. The label, a one-line
  * summary of the current value and a chevron pointing right. Sits inside a `SettingsCard`.
  */
-export function SettingsDetailRow({
-  label,
-  summary,
-  onPress,
-  disabled,
-  testID,
-}: SettingsDetailRowProps) {
-  return (
-    <SettingsRowHeader
-      label={label}
-      summary={summary}
-      onPress={onPress}
-      disabled={disabled}
-      testID={testID}
-    />
-  );
+export function SettingsDetailRow(props: SettingsDetailRowProps) {
+  return <SettingsRowHeader {...props} />;
 }
diff --git a/packages/app/src/components/settings/headings/settings-section.tsx b/packages/app/src/components/settings/headings/settings-section.tsx
index 28b19f3589..c0460ae15a 100644
--- a/packages/app/src/components/settings/headings/settings-section.tsx
+++ b/packages/app/src/components/settings/headings/settings-section.tsx
@@ -1,6 +1,7 @@
 import { useMemo, type ReactNode } from "react";
 import { Text, View, type StyleProp, type ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { ExternalLink, type ExternalLinkProps } from "@/components/ui/external-link";
 import { SettingsInfoTip } from "./settings-info-tip";
 import { settingsStyles } from "@/styles/settings";
 
@@ -11,6 +12,12 @@ interface SettingsSectionProps {
    * paragraph between the header and the card is wrong (docs/design.md §7).
    */
   info?: ReactNode;
+  /**
+   * A page outside the app, such as the docs, shown at the header's end as "Label ↗". Its glyph
+   * sits as far inside the card's edge as the title does on the other side.
+   */
+  link?: Pick<ExternalLinkProps, "href" | "label" | "accessibilityLabel" | "tooltip" | "testID">;
+  /** An action at the header's end, such as Refresh or Add. A link to a page is `link`. */
   trailing?: ReactNode;
   testID?: string;
   style?: StyleProp<ViewStyle>;
@@ -30,6 +37,7 @@ interface SettingsSectionProps {
 export function SettingsSection({
   title,
   info,
+  link,
   trailing,
   testID,
   style,
@@ -53,6 +61,11 @@ export function SettingsSection({
             />
           ) : null}
         </View>
+        {link ? (
+          <View style={styles.link}>
+            <ExternalLink {...link} />
+          </View>
+        ) : null}
         {trailing}
       </View>
       <View style={styles.content}>{children}</View>
@@ -69,6 +82,10 @@ const styles = StyleSheet.create((theme) => ({
     marginBottom: theme.spacing[3],
     marginLeft: theme.spacing[1],
   },
+  // Mirrors the header's marginLeft, so the link's glyph and the title's sit on matching rails.
+  link: {
+    marginRight: theme.spacing[1],
+  },
   titleRow: {
     flexDirection: "row",
     alignItems: "center",
diff --git a/packages/app/src/components/settings/row-density.tsx b/packages/app/src/components/settings/row-density.tsx
index d4bcdce33e..3682899624 100644
--- a/packages/app/src/components/settings/row-density.tsx
+++ b/packages/app/src/components/settings/row-density.tsx
@@ -1,8 +1,8 @@
 import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { StyleProp, TextStyle, ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { CONTROL_HEIGHTS } from "@/components/ui/control-geometry";
-import type { ContainedControlSize } from "@/components/ui/control-size";
+import { CONTROL_HEIGHTS, mapLayout, type ControlSize } from "@/components/ui/control-geometry";
+
 import { settingsStyles } from "@/styles/settings";
 
 // Rows revealed under a collapsible row belong to it, so they sit one step smaller than the rows
@@ -19,7 +19,7 @@ export interface SettingsRowLayout {
   title: StyleProp<TextStyle>;
   hint: StyleProp<TextStyle>;
   /** The size of the controls in the row's trailing slot. */
-  controlSize: ContainedControlSize;
+  controlSize: ControlSize;
 }
 
 /** How a row lays out where it is rendered: in a card, or nested under a collapsible row. */
@@ -32,24 +32,24 @@ export function useSettingsRowLayout(): SettingsRowLayout {
             row: [settingsStyles.row, styles.nestedRow],
             title: [settingsStyles.rowTitle, styles.nestedText],
             hint: [settingsStyles.rowHint, styles.nestedText],
-            controlSize: "xs",
+            controlSize: "sm",
           }
         : {
             row: settingsStyles.row,
             title: settingsStyles.rowTitle,
             hint: settingsStyles.rowHint,
-            controlSize: "sm",
+            controlSize: "md",
           },
     [nested],
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  // Every nested row is as tall as one holding an `xs` control, so rows with and without a
+  // Every nested row is as tall as one holding an `sm` control, so rows with and without a
   // trailing button line up.
   nestedRow: {
     paddingVertical: theme.spacing[2],
-    minHeight: CONTROL_HEIGHTS.tight + theme.spacing[2] * 2,
+    minHeight: mapLayout(CONTROL_HEIGHTS.sm, (height) => height + theme.spacing[2] * 2),
   },
   nestedText: {
     fontSize: theme.fontSize.sm,
diff --git a/packages/app/src/components/settings/row-header.tsx b/packages/app/src/components/settings/row-header.tsx
index 9c3c415c34..e1fa077cce 100644
--- a/packages/app/src/components/settings/row-header.tsx
+++ b/packages/app/src/components/settings/row-header.tsx
@@ -1,7 +1,8 @@
 import { ChevronRight } from "lucide-react-native";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, type ReactNode } from "react";
 import { Text, View, type AccessibilityState, type PressableStateCallbackType } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { ExternalLinkLabel } from "@/components/ui/external-link";
 import { mutedIconColorMapping } from "@/components/ui/icon-color";
 import { PressHighlight } from "@/components/ui/press-highlight";
 import { settingsStyles } from "@/styles/settings";
@@ -15,12 +16,18 @@ type HoverState = PressableStateCallbackType & { hovered?: boolean };
 
 export interface SettingsRowHeaderProps {
   label: string;
+  /** Shown beside the label, such as a badge. */
+  labelAccessory?: ReactNode;
+  /** A line under the label saying what the row leads to. */
+  hint?: string;
   /** A short status shown before the chevron. */
   summary?: string;
   onPress: () => void;
   disabled?: boolean;
   /** Turns the chevron down, for a row whose children are revealed in place. */
   expanded?: boolean;
+  /** The row leaves the app, such as to a docs page: the summary and an outward arrow are drawn as an external link in place of the chevron. */
+  external?: boolean;
   accessibilityState?: AccessibilityState;
   /** Props React Native Web does not derive from `accessibilityState`, such as `aria-expanded`. */
   webAccessibilityProps?: Record<string, unknown> | null;
@@ -34,10 +41,13 @@ export interface SettingsRowHeaderProps {
  */
 export function SettingsRowHeader({
   label,
+  labelAccessory,
+  hint,
   summary,
   onPress,
   disabled,
   expanded = false,
+  external = false,
   accessibilityState,
   webAccessibilityProps,
   testID,
@@ -58,7 +68,7 @@ export function SettingsRowHeader({
   return (
     <PressHighlight
       {...webAccessibilityProps}
-      accessibilityRole="button"
+      accessibilityRole={external ? "link" : "button"}
       accessibilityLabel={summary ? `${label}, ${summary}` : label}
       accessibilityState={accessibilityState}
       disabled={disabled}
@@ -70,20 +80,35 @@ export function SettingsRowHeader({
       {({ hovered }: HoverState) => (
         <>
           <View style={settingsStyles.rowContent}>
-            <Text style={layout.title}>{label}</Text>
+            {labelAccessory ? (
+              <View style={styles.labelRow}>
+                <Text style={layout.title}>{label}</Text>
+                {labelAccessory}
+              </View>
+            ) : (
+              <Text style={layout.title}>{label}</Text>
+            )}
+            {hint ? <Text style={layout.hint}>{hint}</Text> : null}
           </View>
-          {summary ? (
-            <Text style={styles.summary} numberOfLines={1}>
-              {summary}
-            </Text>
-          ) : null}
-          {disabled ? null : (
-            <View style={chevronStyle}>
-              <ThemedChevron
-                size={ICON_SIZE.sm}
-                uniProps={hovered ? hoveredIconColorMapping : mutedIconColorMapping}
-              />
-            </View>
+          {external ? (
+            // Drawn the same as a section header's docs link, so the two read as one thing.
+            <ExternalLinkLabel hovered={hovered}>{summary}</ExternalLinkLabel>
+          ) : (
+            <>
+              {summary ? (
+                <Text style={styles.summary} numberOfLines={1}>
+                  {summary}
+                </Text>
+              ) : null}
+              {disabled ? null : (
+                <View style={chevronStyle}>
+                  <ThemedChevron
+                    size={ICON_SIZE.sm}
+                    uniProps={hovered ? hoveredIconColorMapping : mutedIconColorMapping}
+                  />
+                </View>
+              )}
+            </>
           )}
         </>
       )}
@@ -92,6 +117,7 @@ export function SettingsRowHeader({
 }
 
 const styles = StyleSheet.create((theme) => ({
+  labelRow: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
   summary: {
     flexShrink: 1,
     color: theme.colors.foregroundMuted,
diff --git a/packages/app/src/components/sidebar-agent-list-skeleton.tsx b/packages/app/src/components/sidebar-agent-list-skeleton.tsx
index 9214bbd428..1274ab3d3e 100644
--- a/packages/app/src/components/sidebar-agent-list-skeleton.tsx
+++ b/packages/app/src/components/sidebar-agent-list-skeleton.tsx
@@ -1,7 +1,8 @@
-import { useEffect, useMemo, useRef } from "react";
-import { Animated, View, type StyleProp, type ViewStyle } from "react-native";
+import { useMemo } from "react";
+import { Animated, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { projectIconRadius } from "@/components/project-icon-view";
+import { SkeletonPulse, useSkeletonPulse } from "@/components/ui/skeleton";
 
 const PROJECT_ICON_SIZE = 16;
 
@@ -11,17 +12,6 @@ const ROW_KEYS_BY_SECTION: readonly (readonly string[])[] = SECTION_OPACITIES.ma
   [0, 1, 2].map((r) => `skeleton-row-${sIdx}-${r}`),
 );
 
-function SkeletonPulse({ pulse, style }: { pulse: Animated.Value; style: StyleProp<ViewStyle> }) {
-  const opacity = pulse.interpolate({
-    inputRange: [0, 1],
-    outputRange: [0.4, 0.8],
-  });
-
-  const pulseStyle = useMemo(() => [style, { opacity }], [style, opacity]);
-
-  return <Animated.View style={pulseStyle} />;
-}
-
 function SkeletonSection({
   pulse,
   sectionOpacity,
@@ -57,27 +47,7 @@ function SkeletonSection({
 }
 
 export function SidebarAgentListSkeleton() {
-  const pulse = useRef(new Animated.Value(0)).current;
-
-  useEffect(() => {
-    const animation = Animated.loop(
-      Animated.sequence([
-        Animated.timing(pulse, {
-          toValue: 1,
-          duration: 1000,
-          useNativeDriver: true,
-        }),
-        Animated.timing(pulse, {
-          toValue: 0,
-          duration: 1000,
-          useNativeDriver: true,
-        }),
-      ]),
-    );
-
-    animation.start();
-    return () => animation.stop();
-  }, [pulse]);
+  const pulse = useSkeletonPulse();
 
   return (
     <View style={styles.container}>
diff --git a/packages/app/src/components/sidebar-footer-layout.test.ts b/packages/app/src/components/sidebar-footer-layout.test.ts
new file mode 100644
index 0000000000..b4ec0584f7
--- /dev/null
+++ b/packages/app/src/components/sidebar-footer-layout.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+} from "@/components/sidebar-footer-layout";
+import { DEFAULT_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+
+const TOUCH = 44;
+const POINTER = 28;
+const ROW_PADDING = 8;
+
+function layout(rowWidth: number, controlSize: number) {
+  return resolveSidebarFooterLayout({
+    rowWidth,
+    controlSize,
+    rowPadding: ROW_PADDING,
+    actions: SIDEBAR_FOOTER_ACTIONS,
+  });
+}
+
+describe("sidebar footer layout", () => {
+  it("keeps every action inline at the default width with either sizing", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(DEFAULT_SIDEBAR_WIDTH, controlSize)).toEqual({
+        inline: ["add-project", "usage", "hosts", "help", "settings"],
+        overflow: [],
+      });
+    }
+  });
+
+  it("keeps every action inline at the minimum width with pointer sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, POINTER).overflow).toEqual([]);
+  });
+
+  // The iPhone Duo report: the folded sidebar column is about the minimum width, and touch
+  // sizing makes five 44pt buttons plus padding 236pt wide.
+  it("moves Help and Usage behind the caret at the minimum width with touch sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, TOUCH)).toEqual({
+      inline: ["add-project", "hosts", "settings"],
+      overflow: ["usage", "help"],
+    });
+  });
+
+  it("keeps Settings and Add project inline longest", () => {
+    // Three slots: two actions and the caret.
+    expect(layout(3 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["add-project", "settings"],
+      overflow: ["usage", "hosts", "help"],
+    });
+    // Two slots: Settings and the caret.
+    expect(layout(2 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["settings"],
+      overflow: ["add-project", "usage", "hosts", "help"],
+    });
+  });
+
+  it("puts everything behind the caret when only the caret fits", () => {
+    expect(layout(TOUCH + 2 * ROW_PADDING - 10, TOUCH)).toEqual({
+      inline: [],
+      overflow: ["add-project", "usage", "hosts", "help", "settings"],
+    });
+  });
+
+  it("fits all five actions exactly at their combined width", () => {
+    const exact = 5 * TOUCH + 2 * ROW_PADDING;
+    expect(layout(exact, TOUCH).overflow).toEqual([]);
+    // Browser layout rounds a little below the exact width.
+    expect(layout(exact - 0.4, TOUCH).overflow).toEqual([]);
+    expect(layout(exact - 1, TOUCH).overflow).toEqual(["usage", "help"]);
+  });
+
+  it("only places the actions it is given", () => {
+    expect(
+      resolveSidebarFooterLayout({
+        rowWidth: 3 * TOUCH + 2 * ROW_PADDING,
+        controlSize: TOUCH,
+        rowPadding: ROW_PADDING,
+        actions: ["add-project", "hosts", "settings"],
+      }),
+    ).toEqual({ inline: ["add-project", "hosts", "settings"], overflow: [] });
+  });
+
+  // Laying out against a guessed width would paint a clipped row for a frame on narrow sidebars.
+  it("places nothing before the row has been measured", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(0, controlSize)).toEqual({ inline: [], overflow: [] });
+    }
+  });
+});
diff --git a/packages/app/src/components/sidebar-footer-layout.ts b/packages/app/src/components/sidebar-footer-layout.ts
new file mode 100644
index 0000000000..5513d59d09
--- /dev/null
+++ b/packages/app/src/components/sidebar-footer-layout.ts
@@ -0,0 +1,62 @@
+/** The sidebar footer's icon line, in row order. */
+export const SIDEBAR_FOOTER_ACTIONS = [
+  "add-project",
+  "usage",
+  "hosts",
+  "help",
+  "settings",
+] as const;
+
+export type SidebarFooterAction = (typeof SIDEBAR_FOOTER_ACTIONS)[number];
+
+/** The order actions keep their place in a row too narrow for all of them. */
+const KEEP_ORDER: readonly SidebarFooterAction[] = [
+  "settings",
+  "add-project",
+  "hosts",
+  "usage",
+  "help",
+];
+
+/** Measured widths land a hair under the exact sum of their parts. */
+const MEASUREMENT_TOLERANCE = 0.5;
+
+export interface SidebarFooterLayout {
+  /** Actions drawn in the row, in row order. */
+  inline: SidebarFooterAction[];
+  /** Actions behind the overflow caret, in row order. Empty when everything fits. */
+  overflow: SidebarFooterAction[];
+}
+
+/**
+ * Splits the footer's actions between the row and the overflow menu. Buttons keep their full size;
+ * when they don't all fit, the caret takes one slot and the actions that lose their place move
+ * behind it, Help first and Settings last. Nothing is placed until the row has a measured width.
+ */
+export function resolveSidebarFooterLayout(input: {
+  rowWidth: number;
+  controlSize: number;
+  rowPadding: number;
+  actions: readonly SidebarFooterAction[];
+}): SidebarFooterLayout {
+  const { rowWidth, controlSize, rowPadding, actions } = input;
+  // An unmeasured row stays empty: any guess would paint a clipped row for a frame on a narrow
+  // sidebar before the real width arrives.
+  if (rowWidth <= 0) {
+    return { inline: [], overflow: [] };
+  }
+  const slots = Math.floor(
+    (rowWidth - rowPadding * 2 + MEASUREMENT_TOLERANCE) / Math.max(controlSize, 1),
+  );
+  if (slots >= actions.length) {
+    return { inline: [...actions], overflow: [] };
+  }
+  const inlineCount = Math.max(slots - 1, 0);
+  const kept = new Set(
+    KEEP_ORDER.filter((action) => actions.includes(action)).slice(0, inlineCount),
+  );
+  return {
+    inline: actions.filter((action) => kept.has(action)),
+    overflow: actions.filter((action) => !kept.has(action)),
+  };
+}
diff --git a/packages/app/src/components/sidebar-resize-handle.tsx b/packages/app/src/components/sidebar-resize-handle.tsx
index d842f0f008..37eef984b9 100644
--- a/packages/app/src/components/sidebar-resize-handle.tsx
+++ b/packages/app/src/components/sidebar-resize-handle.tsx
@@ -7,7 +7,7 @@ import {
   type SidebarResizeEdge,
 } from "@/components/sidebar-resize-handle-layout";
 import { isWeb } from "@/constants/platform";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 
 interface SidebarResizeHandleProps {
   edge: SidebarResizeEdge;
@@ -29,7 +29,7 @@ function edgeOffsetStyle(edge: SidebarResizeEdge, edgeOffset: number) {
 }
 
 export function SidebarResizeHandle({ edge, gesture, pressed, testID }: SidebarResizeHandleProps) {
-  const finePointer = useHasFinePointer();
+  const { finePointer } = usePointerCapabilities();
 
   if (finePointer) {
     return <PointerResizeHandle edge={edge} gesture={gesture} pressed={pressed} testID={testID} />;
diff --git a/packages/app/src/components/sidebar-workspace-list.test.tsx b/packages/app/src/components/sidebar-workspace-list.test.tsx
index fc57dc2dce..9532c422dd 100644
--- a/packages/app/src/components/sidebar-workspace-list.test.tsx
+++ b/packages/app/src/components/sidebar-workspace-list.test.tsx
@@ -462,7 +462,7 @@ describe("sidebar group visibility", () => {
 
   it.each([0, 7, 8])("limits %i Done rows to seven", (count) => {
     const items = entries(Array(count).fill("done"));
-    const { result } = renderHook(() => useLimitedSidebarGroup(items, policy));
+    const { result } = renderHook(() => useLimitedSidebarGroup({ items, selection: null, policy }));
     expect(result.current.visibleItems).toEqual(items.slice(0, 7));
     expect(result.current.canToggle).toBe(count > 7);
   });
@@ -471,7 +471,9 @@ describe("sidebar group visibility", () => {
     "keeps row twelve visible for %s without filling gaps",
     (status) => {
       const items = entries([...Array(11).fill("done"), status]);
-      const { result } = renderHook(() => useLimitedSidebarGroup(items, policy));
+      const { result } = renderHook(() =>
+        useLimitedSidebarGroup({ items, selection: null, policy }),
+      );
       expect(names(result.current.visibleItems)).toEqual([
         "row-1",
         "row-2",
@@ -492,7 +494,11 @@ describe("sidebar group visibility", () => {
     const hydrated = new Map(items.slice(0, 9).map((item) => [item.workspaceKey, item]));
     for (const entriesByKey of [new Map(), hydrated]) {
       const { result } = renderHook(() =>
-        useLimitedSidebarGroup(items, createWorkspaceVisibilityPolicy(entriesByKey)),
+        useLimitedSidebarGroup({
+          items,
+          selection: null,
+          policy: createWorkspaceVisibilityPolicy(entriesByKey),
+        }),
       );
       expect(result.current.canToggle).toBe(true);
       expect(names(result.current.visibleItems)).toEqual(
@@ -512,7 +518,7 @@ describe("sidebar group visibility", () => {
       "needs_input",
       "failed",
     ]);
-    const { result } = renderHook(() => useLimitedSidebarGroup(items, policy));
+    const { result } = renderHook(() => useLimitedSidebarGroup({ items, selection: null, policy }));
     expect(result.current.visibleItems).toEqual(items);
     expect(result.current.canToggle).toBe(false);
   });
@@ -527,7 +533,7 @@ describe("sidebar group visibility", () => {
       "attention",
     ]);
     const { result, rerender, unmount } = renderHook(
-      ({ rows }) => useLimitedSidebarGroup(rows, policy),
+      ({ rows }) => useLimitedSidebarGroup({ items: rows, selection: null, policy }),
       { initialProps: { rows: items } },
     );
     expect(names(result.current.visibleItems)).toEqual([
@@ -568,7 +574,7 @@ describe("sidebar group visibility", () => {
     expect(result.current.expanded).toBe(false);
     act(() => result.current.toggleExpanded());
     unmount();
-    const remounted = renderHook(() => useLimitedSidebarGroup(items, policy));
+    const remounted = renderHook(() => useLimitedSidebarGroup({ items, selection: null, policy }));
     expect(remounted.result.current.expanded).toBe(false);
     expect(remounted.result.current.visibleItems).toHaveLength(10);
   });
@@ -592,7 +598,12 @@ describe("sidebar group visibility", () => {
       lifecycle: "active" as const,
     };
     const { result, rerender } = renderHook(
-      ({ last }) => useLimitedSidebarGroup([...items.slice(0, 11), last], policy),
+      ({ last }) =>
+        useLimitedSidebarGroup({
+          items: [...items.slice(0, 11), last],
+          selection: null,
+          policy,
+        }),
       { initialProps: { last: items[11] } },
     );
     expect(result.current.visibleItems).toHaveLength(7);
@@ -630,7 +641,7 @@ describe("sidebar group visibility", () => {
 
   it("preserves the twenty-row pinned policy regardless of status", () => {
     const items = entries(Array(21).fill("running"));
-    const { result } = renderHook(() => useLimitedSidebarGroup(items));
+    const { result } = renderHook(() => useLimitedSidebarGroup({ items, selection: null }));
     expect(result.current.visibleItems).toEqual(items.slice(0, 20));
     expect(result.current.canToggle).toBe(true);
     act(() => result.current.toggleExpanded());
diff --git a/packages/app/src/components/sidebar-workspace-list.tsx b/packages/app/src/components/sidebar-workspace-list.tsx
index 333eb68221..d6a810e74e 100644
--- a/packages/app/src/components/sidebar-workspace-list.tsx
+++ b/packages/app/src/components/sidebar-workspace-list.tsx
@@ -154,6 +154,7 @@ import type { HostBadgeModel } from "@/hosts/appearance";
 import { useHostBadges } from "@/hosts/use-host-badges";
 import { useSidebarRowItems } from "@/components/sidebar/display-preferences/model";
 import { PullRequestStateIcon } from "@/git/pull-request-state-icon";
+import { bySizing } from "@/components/ui/control-geometry";
 
 const workspaceKeyExtractor = (workspace: SidebarWorkspacePlacement) => workspace.workspaceKey;
 
@@ -648,6 +649,7 @@ function WorkspaceRowRightGroup({
   const {
     trailingPresentation,
     showKebab: showKebabInSlot,
+    showArchiveButton,
     showScrim,
     renderSlot,
     reserveSlotWidth,
@@ -674,6 +676,8 @@ function WorkspaceRowRightGroup({
           <SidebarWorkspaceTrailingActionOverlay
             visible={kebab.showKebab}
             scrimBackdrop={showScrim ? backdrop : undefined}
+            workspaceKey={workspace.workspaceKey}
+            onArchiveButtonPress={showArchiveButton ? onArchive : undefined}
           >
             {onArchive ? (
               <SidebarWorkspaceMenu
@@ -1598,11 +1602,16 @@ function ProjectBlock({
     [workspaceEntriesByKey],
   );
   const {
+    leadingItem: leadingWorkspace,
     visibleItems: visibleWorkspaces,
     expanded: workspacesExpanded,
     canToggle: canToggleWorkspaces,
     toggleExpanded: toggleWorkspacesExpanded,
-  } = useLimitedSidebarGroup(project.workspaces, visibilityPolicy);
+  } = useLimitedSidebarGroup({
+    items: project.workspaces,
+    selection: selectionEnabled ? activeWorkspaceSelection : null,
+    policy: visibilityPolicy,
+  });
   const activeServerId = activeWorkspaceSelection?.serverId ?? null;
   const activeHostStatus = useHostRuntimeConnectionStatus(activeServerId ?? "");
   const preferredServerId = activeHostStatus === "online" ? activeServerId : null;
@@ -1761,28 +1770,33 @@ function ProjectBlock({
   let projectChildren = null;
   if (!collapsed) {
     if (project.workspaces.length > 0) {
+      const leadingWorkspaceRow = leadingWorkspace ? renderWorkspaceRow(leadingWorkspace) : null;
       projectChildren = (
         <>
           {manualSort ? (
-            <DraggableList
-              testID={`sidebar-workspace-list-${project.viewKey}`}
-              data={visibleWorkspaces}
-              keyExtractor={workspaceKeyExtractor}
-              renderItem={renderWorkspace}
-              onDragEnd={handleWorkspaceDragEnd}
-              extraData={activeWorkspaceSelectionKey(activeWorkspaceSelection)}
-              scrollEnabled={false}
-              useDragHandle
-              nestable={useNestable}
-              simultaneousGestureRef={parentGestureRef}
-              gestureHostPresented={dragGestureHostActive}
-              containerStyle={styles.workspaceListContainer}
-            />
+            <>
+              {leadingWorkspaceRow}
+              <DraggableList
+                testID={`sidebar-workspace-list-${project.viewKey}`}
+                data={visibleWorkspaces}
+                keyExtractor={workspaceKeyExtractor}
+                renderItem={renderWorkspace}
+                onDragEnd={handleWorkspaceDragEnd}
+                extraData={activeWorkspaceSelectionKey(activeWorkspaceSelection)}
+                scrollEnabled={false}
+                useDragHandle
+                nestable={useNestable}
+                simultaneousGestureRef={parentGestureRef}
+                gestureHostPresented={dragGestureHostActive}
+                containerStyle={styles.workspaceListContainer}
+              />
+            </>
           ) : (
             <View
               testID={`sidebar-workspace-list-${project.viewKey}`}
               style={styles.workspaceListContainer}
             >
+              {leadingWorkspaceRow}
               {visibleWorkspaces.map((item) => renderWorkspaceRow(item))}
             </View>
           )}
@@ -2188,11 +2202,15 @@ function ProjectModeList({
   const activeWorkspaceSelection = useActiveWorkspaceSelection();
   const { pinnedChats, unpinnedProjects } = pinnedGroups;
   const {
+    leadingItem: leadingPinnedChat,
     visibleItems: visiblePinnedChats,
     expanded: pinnedChatsExpanded,
     canToggle: canTogglePinnedChats,
     toggleExpanded: togglePinnedChatsExpanded,
-  } = useLimitedSidebarGroup(pinnedChats);
+  } = useLimitedSidebarGroup({
+    items: pinnedChats,
+    selection: selectionEnabled ? activeWorkspaceSelection : null,
+  });
   const nativeScrollGestureProps = useMemo(
     () =>
       parentGestureRef
@@ -2395,37 +2413,38 @@ function ProjectModeList({
     [renderProjectBlock],
   );
 
-  const renderPinnedChat = useCallback(
-    ({
-      item: workspace,
-      drag,
-      isActive,
-      dragHandleProps,
-    }: DraggableRenderItemInfo<SidebarWorkspacePlacement>) => {
-      return (
-        <MemoWorkspaceRowItem
-          workspace={workspace}
-          workspaceEntry={workspaceEntriesByKey.get(workspace.workspaceKey) ?? null}
-          hostBadge={hostBadgeByServerId.get(workspace.serverId) ?? null}
-          leadingProjectName={workspace.projectName}
-          leadingProjectIconDataUri={
-            projectIconByProjectViewKey.get(workspace.projectViewKey) ?? null
-          }
-          shortcutNumber={shortcutIndexByWorkspaceKey.get(workspace.workspaceKey) ?? null}
-          showShortcutBadge={showShortcutBadges}
-          canCopyBranchName={workspace.projectKind === "git"}
-          canPin={supportsPinningByServerId.get(workspace.serverId) === true}
-          onToggleWorkspacePin={onToggleWorkspacePin}
-          isCreating={creatingWorkspaceIds.has(workspace.workspaceId)}
-          selectionEnabled={selectionEnabled}
-          activeWorkspaceSelection={activeWorkspaceSelection}
-          onWorkspacePress={onWorkspacePress}
-          drag={drag}
-          isDragging={isActive}
-          dragHandleProps={dragHandleProps}
-        />
-      );
-    },
+  const renderPinnedChatRow = useCallback(
+    (
+      workspace: SidebarWorkspacePlacement,
+      input?: {
+        drag?: () => void;
+        isDragging?: boolean;
+        dragHandleProps?: DraggableListDragHandleProps;
+      },
+    ) => (
+      <MemoWorkspaceRowItem
+        key={workspace.workspaceKey}
+        workspace={workspace}
+        workspaceEntry={workspaceEntriesByKey.get(workspace.workspaceKey) ?? null}
+        hostBadge={hostBadgeByServerId.get(workspace.serverId) ?? null}
+        leadingProjectName={workspace.projectName}
+        leadingProjectIconDataUri={
+          projectIconByProjectViewKey.get(workspace.projectViewKey) ?? null
+        }
+        shortcutNumber={shortcutIndexByWorkspaceKey.get(workspace.workspaceKey) ?? null}
+        showShortcutBadge={showShortcutBadges}
+        canCopyBranchName={workspace.projectKind === "git"}
+        canPin={supportsPinningByServerId.get(workspace.serverId) === true}
+        onToggleWorkspacePin={onToggleWorkspacePin}
+        isCreating={creatingWorkspaceIds.has(workspace.workspaceId)}
+        selectionEnabled={selectionEnabled}
+        activeWorkspaceSelection={activeWorkspaceSelection}
+        onWorkspacePress={onWorkspacePress}
+        drag={input?.drag}
+        isDragging={input?.isDragging}
+        dragHandleProps={input?.dragHandleProps}
+      />
+    ),
     [
       activeWorkspaceSelection,
       creatingWorkspaceIds,
@@ -2441,6 +2460,22 @@ function ProjectModeList({
     ],
   );
 
+  const renderPinnedChat = useCallback(
+    ({
+      item: workspace,
+      drag,
+      isActive,
+      dragHandleProps,
+    }: DraggableRenderItemInfo<SidebarWorkspacePlacement>) => {
+      return renderPinnedChatRow(workspace, {
+        drag,
+        isDragging: isActive,
+        dragHandleProps,
+      });
+    },
+    [renderPinnedChatRow],
+  );
+
   const projectBody =
     projects.length === 0 ? (
       <SidebarProjectEmptyState onAddProject={onAddProject} onImportSession={onImportSession} />
@@ -2473,6 +2508,7 @@ function ProjectModeList({
           />
           {pinnedCollapsed ? null : (
             <>
+              {leadingPinnedChat ? renderPinnedChatRow(leadingPinnedChat) : null}
               <DraggableList
                 testID="sidebar-pinned-list"
                 data={visiblePinnedChats}
@@ -2705,12 +2741,12 @@ const styles = StyleSheet.create((theme) => ({
     marginRight: -6,
   },
   projectKebabButton: {
-    // Larger on compact so the kebab is an easy tap target. The negative margins keep its
-    // dots on the same rail as the 24px desktop box and the row at its 44px height.
-    width: { xs: 32, md: 24 },
-    height: { xs: 32, md: 24 },
-    marginRight: { xs: -4, md: 0 },
-    marginVertical: { xs: -4, md: 0 },
+    // Larger on touch so the kebab is an easy tap target. The negative margins keep its
+    // dots on the same rail as the 24px pointer box and the row at its 44px height.
+    width: bySizing({ touch: 32, pointer: 24 }),
+    height: bySizing({ touch: 32, pointer: 24 }),
+    marginRight: bySizing({ touch: -4, pointer: 0 }),
+    marginVertical: bySizing({ touch: -4, pointer: 0 }),
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
     justifyContent: "center",
diff --git a/packages/app/src/components/sidebar/empty-states.tsx b/packages/app/src/components/sidebar/empty-states.tsx
index c9f6b7c568..ed5162f65b 100644
--- a/packages/app/src/components/sidebar/empty-states.tsx
+++ b/packages/app/src/components/sidebar/empty-states.tsx
@@ -56,7 +56,7 @@ export function SidebarFilterEmptyState() {
     >
       <Button
         variant="secondary"
-        size="xs"
+        size="sm"
         style={styles.action}
         textStyle={styles.actionText}
         onPress={clearFilters}
@@ -84,7 +84,7 @@ export function SidebarProjectEmptyState({
     >
       <Button
         variant="secondary"
-        size="xs"
+        size="sm"
         leftIcon={Plus}
         style={styles.action}
         textStyle={styles.actionText}
@@ -94,7 +94,7 @@ export function SidebarProjectEmptyState({
       </Button>
       <Button
         variant="outline"
-        size="xs"
+        size="sm"
         leftIcon={Import}
         style={styles.action}
         textStyle={styles.actionText}
diff --git a/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx b/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx
new file mode 100644
index 0000000000..fd165efa79
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx
@@ -0,0 +1,69 @@
+import type { ReactElement } from "react";
+import { Text, View } from "react-native";
+import type { LucideIcon } from "lucide-react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
+import { DensityIcon } from "@/components/ui/density-icon";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { density } from "@/styles/density";
+import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
+
+/**
+ * A footer icon that opens a menu. Sized and drawn like the footer's other icon buttons; the
+ * tooltip stays out of the way while the menu is open.
+ */
+export function SidebarFooterMenuTrigger({
+  icon,
+  label,
+  menuOpen,
+  testID,
+}: {
+  icon: LucideIcon;
+  label: string;
+  menuOpen: boolean;
+  testID: string;
+}): ReactElement {
+  return (
+    <Tooltip delayDuration={300} enabledOnDesktop={!menuOpen}>
+      <TooltipTrigger asChild>
+        <View>
+          <DropdownMenuTrigger
+            style={styles.trigger}
+            testID={testID}
+            accessibilityRole="button"
+            accessibilityLabel={label}
+          >
+            {({ hovered, pressed, open }) => (
+              <>
+                <SidebarFooterIconHighlight visible={pressed || open} />
+                <DensityIcon
+                  icon={icon}
+                  size="md"
+                  color={hovered ? "foreground" : "foregroundMuted"}
+                />
+              </>
+            )}
+          </DropdownMenuTrigger>
+        </View>
+      </TooltipTrigger>
+      <TooltipContent side="top" align="center" offset={8}>
+        <Text style={styles.tooltipText}>{label}</Text>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  trigger: {
+    width: density.iconButton,
+    height: density.iconButton,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: theme.spacing[1],
+    paddingHorizontal: theme.spacing[1],
+  },
+  tooltipText: {
+    fontSize: theme.fontSize.base,
+    color: theme.colors.popoverForeground,
+  },
+}));
diff --git a/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx b/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx
new file mode 100644
index 0000000000..aef13f7e28
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx
@@ -0,0 +1,245 @@
+import { useCallback, useMemo, useState, type ReactElement } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  ChevronUp,
+  CircleGauge,
+  CircleHelp,
+  FolderPlus,
+  Plus,
+  Server,
+  Settings,
+} from "lucide-react-native";
+import { withUnistyles } from "react-native-unistyles";
+import { HostStatusDotSlot } from "@/components/hosts/host-picker";
+import type { SidebarFooterAction } from "@/components/sidebar-footer-layout";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSubTrigger,
+  type MenuPageDefinition,
+} from "@/components/ui/dropdown-menu";
+import { Shortcut } from "@/components/ui/shortcut";
+import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
+import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
+import { useHosts } from "@/runtime/host-runtime";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { orderHostsLocalFirst } from "@/types/host-connection";
+import { useOpenSidebarUsage } from "@/usage";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
+import { SidebarHelpMenuItems } from "./sidebar-help-menu";
+
+const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+const ThemedFolderPlus = withUnistyles(FolderPlus);
+const ThemedCircleGauge = withUnistyles(CircleGauge);
+const ThemedServer = withUnistyles(Server);
+const ThemedCircleHelp = withUnistyles(CircleHelp);
+const ThemedSettings = withUnistyles(Settings);
+const ThemedPlus = withUnistyles(Plus);
+const addProjectLeading = <ThemedFolderPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const usageLeading = <ThemedCircleGauge size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const hostsLeading = <ThemedServer size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const helpLeading = <ThemedCircleHelp size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const settingsLeading = <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const addHostLeading = <ThemedPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+
+const HOSTS_PAGE_ID = "hosts";
+const HELP_PAGE_ID = "help";
+
+export interface SidebarFooterOverflowMenuProps {
+  /** The footer actions that did not fit in the row, in row order. */
+  actions: readonly SidebarFooterAction[];
+  labels: { addProject: string; hosts: string; settings: string; usage: string };
+  onAddProject: () => void;
+  onSettings: () => void;
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}
+
+/**
+ * The caret at the end of a footer row too narrow for every action. It lists the actions that
+ * lost their place, with the same test IDs they carry in the row; Hosts and Help, menus of their
+ * own in the row, open as pages of this menu.
+ */
+export function SidebarFooterOverflowMenu({
+  actions,
+  labels,
+  onAddProject,
+  onSettings,
+  onAddHost,
+  onOpenHostSettings,
+}: SidebarFooterOverflowMenuProps): ReactElement {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+  const openUsage = useOpenSidebarUsage();
+  const newAgentKeys = useShortcutKeys("new-agent");
+  const settingsKeys = useShortcutKeys("toggle-settings");
+  const helpLabel = t("sidebar.help.trigger");
+  const addProjectTrailing = useMemo(
+    () => (newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null),
+    [newAgentKeys],
+  );
+  const settingsTrailing = useMemo(
+    () => (settingsKeys ? <Shortcut chord={settingsKeys} /> : null),
+    [settingsKeys],
+  );
+
+  const pages = useMemo((): MenuPageDefinition[] => {
+    const result: MenuPageDefinition[] = [];
+    if (actions.includes("hosts")) {
+      result.push({
+        id: HOSTS_PAGE_ID,
+        title: labels.hosts,
+        content: <HostsPage onAddHost={onAddHost} onOpenHostSettings={onOpenHostSettings} />,
+      });
+    }
+    if (actions.includes("help")) {
+      result.push({ id: HELP_PAGE_ID, title: helpLabel, content: <SidebarHelpMenuItems /> });
+    }
+    return result;
+  }, [actions, helpLabel, labels.hosts, onAddHost, onOpenHostSettings]);
+
+  function renderAction(action: SidebarFooterAction): ReactElement {
+    switch (action) {
+      case "add-project":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-add-project"
+            leading={addProjectLeading}
+            trailing={addProjectTrailing}
+            onSelect={onAddProject}
+          >
+            {labels.addProject}
+          </DropdownMenuItem>
+        );
+      case "usage":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-usage-icon"
+            leading={usageLeading}
+            onSelect={openUsage}
+          >
+            {labels.usage}
+          </DropdownMenuItem>
+        );
+      case "hosts":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HOSTS_PAGE_ID}
+            testID="sidebar-hosts-trigger"
+            leading={hostsLeading}
+          >
+            {labels.hosts}
+          </DropdownMenuSubTrigger>
+        );
+      case "help":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HELP_PAGE_ID}
+            testID="sidebar-help"
+            leading={helpLeading}
+          >
+            {helpLabel}
+          </DropdownMenuSubTrigger>
+        );
+      case "settings":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-settings"
+            leading={settingsLeading}
+            trailing={settingsTrailing}
+            onSelect={onSettings}
+          >
+            {labels.settings}
+          </DropdownMenuItem>
+        );
+    }
+  }
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={ChevronUp}
+        label={t("sidebar.actions.moreActions")}
+        menuOpen={open}
+        testID="sidebar-footer-overflow"
+      />
+      <DropdownMenuContent
+        side="top"
+        align="end"
+        offset={8}
+        width={240}
+        pages={pages}
+        scrollable
+        testID="sidebar-footer-overflow-menu"
+      >
+        {actions.map(renderAction)}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The host picker's choices as a menu page: each host opens its settings, then Add host. */
+function HostsPage({
+  onAddHost,
+  onOpenHostSettings,
+}: {
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const { t } = useTranslation();
+  const hosts = useHosts();
+  const localServerId = useLocalDaemonServerId();
+  const orderedHosts = useMemo(
+    () => orderHostsLocalFirst(hosts, localServerId),
+    [hosts, localServerId],
+  );
+
+  return (
+    <>
+      {orderedHosts.map((host) => (
+        <HostRow
+          key={host.serverId}
+          serverId={host.serverId}
+          label={host.label}
+          onOpenHostSettings={onOpenHostSettings}
+        />
+      ))}
+      {orderedHosts.length > 0 ? <DropdownMenuSeparator /> : null}
+      <DropdownMenuItem testID="sidebar-host-add" leading={addHostLeading} onSelect={onAddHost}>
+        {t("settings.addHost")}
+      </DropdownMenuItem>
+    </>
+  );
+}
+
+function HostRow({
+  serverId,
+  label,
+  onOpenHostSettings,
+}: {
+  serverId: string;
+  label: string;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const handleSelect = useCallback(
+    () => onOpenHostSettings(serverId),
+    [onOpenHostSettings, serverId],
+  );
+  const leading = useMemo(() => <HostStatusDotSlot serverId={serverId} />, [serverId]);
+  return (
+    <DropdownMenuItem
+      testID={`sidebar-host-row-${serverId}`}
+      leading={leading}
+      onSelect={handleSelect}
+    >
+      {label}
+    </DropdownMenuItem>
+  );
+}
diff --git a/packages/app/src/components/sidebar/sidebar-group-visibility.test.ts b/packages/app/src/components/sidebar/sidebar-group-visibility.test.ts
new file mode 100644
index 0000000000..acd36cd808
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-group-visibility.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import type { SidebarStateBucket } from "@/hooks/sidebar-workspaces-view-model";
+import type { ActiveWorkspaceSelection } from "@/stores/last-workspace-selection";
+import {
+  selectSidebarGroupVisibility,
+  type SidebarGroupItem,
+  type SidebarGroupVisibilityPolicy,
+} from "./sidebar-group-visibility";
+
+interface Item extends SidebarGroupItem {
+  id: number;
+  statusBucket: SidebarStateBucket;
+}
+
+const serverId = "host-a";
+
+function rows(statuses: readonly SidebarStateBucket[], rowServerId = serverId): Item[] {
+  return statuses.map((statusBucket, index) => ({
+    id: index + 1,
+    serverId: rowServerId,
+    workspaceId: `workspace-${index + 1}`,
+    statusBucket,
+  }));
+}
+
+const workspacePolicy: SidebarGroupVisibilityPolicy<Item> = {
+  kind: "workspaces",
+  getStatusBucket: (item) => item.statusBucket,
+};
+
+function selectionFor(item: SidebarGroupItem): ActiveWorkspaceSelection {
+  return { serverId: item.serverId, workspaceId: item.workspaceId };
+}
+
+describe("selectSidebarGroupVisibility", () => {
+  it("leads with a hidden open row while keeping the baseline order", () => {
+    const items = rows(Array(9).fill("done"));
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: false,
+      policy: workspacePolicy,
+      selection: selectionFor(items[8]!),
+    });
+
+    expect(result.leadingItem).toBe(items[8]);
+    expect(result.visibleItems).toEqual(items.slice(0, 7));
+    expect(result.canToggle).toBe(true);
+  });
+
+  it("leaves selected rows in place when they are already in the baseline", () => {
+    const items = rows([...Array(8).fill("done"), "running", "done"]);
+    const expected = [...items.slice(0, 7), items[8]];
+
+    for (const selectedIndex of [2, 8]) {
+      const result = selectSidebarGroupVisibility({
+        items,
+        expanded: false,
+        policy: workspacePolicy,
+        selection: selectionFor(items[selectedIndex]!),
+      });
+
+      expect(result.leadingItem).toBeNull();
+      expect(result.visibleItems).toEqual(expected);
+      expect(result.canToggle).toBe(true);
+    }
+  });
+
+  it("shows the whole group without a toggle when the open row is the only hidden row", () => {
+    const items = rows(Array(8).fill("done"));
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: false,
+      policy: workspacePolicy,
+      selection: selectionFor(items[7]!),
+    });
+
+    expect(result.leadingItem).toBeNull();
+    expect(result.visibleItems).toEqual(items);
+    expect(result.canToggle).toBe(false);
+  });
+
+  it("keeps expanded groups in their original order", () => {
+    const items = rows(Array(9).fill("done"));
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: true,
+      policy: workspacePolicy,
+      selection: selectionFor(items[8]!),
+    });
+
+    expect(result.leadingItem).toBeNull();
+    expect(result.visibleItems).toEqual(items);
+    expect(result.canToggle).toBe(true);
+  });
+
+  it("applies the twenty-row limit to pinned groups", () => {
+    const items = rows(Array(22).fill("done"));
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: false,
+      policy: { kind: "pinned" },
+      selection: selectionFor(items[21]!),
+    });
+
+    expect(result.leadingItem).toBe(items[21]);
+    expect(result.visibleItems).toEqual(items.slice(0, 20));
+    expect(result.canToggle).toBe(true);
+  });
+
+  it("preserves the current limit when selection is null", () => {
+    const items = rows(Array(8).fill("done"));
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: false,
+      policy: workspacePolicy,
+      selection: null,
+    });
+
+    expect(result.leadingItem).toBeNull();
+    expect(result.visibleItems).toEqual(items.slice(0, 7));
+    expect(result.canToggle).toBe(true);
+  });
+
+  it("matches the open row by server and workspace identity", () => {
+    const items = rows(Array(9).fill("done"), "host-b");
+    const result = selectSidebarGroupVisibility({
+      items,
+      expanded: false,
+      policy: workspacePolicy,
+      selection: { serverId: serverId, workspaceId: items[8]!.workspaceId },
+    });
+
+    expect(result.leadingItem).toBeNull();
+    expect(result.visibleItems).toEqual(items.slice(0, 7));
+    expect(result.canToggle).toBe(true);
+  });
+});
diff --git a/packages/app/src/components/sidebar/sidebar-group-visibility.ts b/packages/app/src/components/sidebar/sidebar-group-visibility.ts
index 1bc3018e9a..f109f0114a 100644
--- a/packages/app/src/components/sidebar/sidebar-group-visibility.ts
+++ b/packages/app/src/components/sidebar/sidebar-group-visibility.ts
@@ -1,4 +1,28 @@
 import type { SidebarStateBucket } from "@/hooks/sidebar-workspaces-view-model";
+import type { ActiveWorkspaceSelection } from "@/stores/last-workspace-selection";
+
+export interface SidebarGroupItem {
+  serverId: string;
+  workspaceId: string;
+}
+
+export interface SidebarGroupVisibilityInput<T> {
+  items: readonly T[];
+  expanded: boolean;
+  policy: SidebarGroupVisibilityPolicy<T>;
+  /** The workspace the group's rows highlight as selected. Null when no row can be selected. */
+  selection: ActiveWorkspaceSelection | null;
+}
+
+export interface SidebarGroupVisibility<T> {
+  /**
+   * The open workspace when the collapsed limit would hide it. Rendered before `visibleItems`,
+   * out of group order, outside any drag list. Never also present in `visibleItems`.
+   */
+  leadingItem: T | null;
+  visibleItems: T[];
+  canToggle: boolean;
+}
 
 export type SidebarGroupVisibilityPolicy<T> =
   | { kind: "pinned" }
@@ -16,18 +40,45 @@ export function createWorkspaceVisibilityPolicy<T extends { workspaceKey: string
   };
 }
 
-export function selectSidebarGroupVisibility<T>(
-  items: readonly T[],
-  expanded: boolean,
-  policy: SidebarGroupVisibilityPolicy<T>,
-) {
-  const limit = policy.kind === "pinned" ? 20 : 7;
-  const baseline = items.filter(
-    (item, index) =>
-      index < limit || (policy.kind === "workspaces" && policy.getStatusBucket(item) !== "done"),
+function isOpenWorkspace(
+  item: SidebarGroupItem,
+  selection: ActiveWorkspaceSelection | null,
+): boolean {
+  return (
+    selection !== null &&
+    item.serverId === selection.serverId &&
+    item.workspaceId === selection.workspaceId
   );
+}
+
+export function selectSidebarGroupVisibility<T extends SidebarGroupItem>(
+  input: SidebarGroupVisibilityInput<T>,
+): SidebarGroupVisibility<T> {
+  const { items, expanded, policy, selection } = input;
+  const limit = policy.kind === "pinned" ? 20 : 7;
+  const baseline: T[] = [];
+  let leadingItem: T | null = null;
+  let canToggle = false;
+
+  items.forEach((item, index) => {
+    const inBaseline =
+      index < limit || (policy.kind === "workspaces" && policy.getStatusBucket(item) !== "done");
+    if (inBaseline) {
+      baseline.push(item);
+    } else if (leadingItem === null && isOpenWorkspace(item, selection)) {
+      leadingItem = item;
+    } else {
+      canToggle = true;
+    }
+  });
+
+  if (expanded || !canToggle) {
+    return { leadingItem: null, visibleItems: items.slice(), canToggle };
+  }
+
   return {
-    visibleItems: expanded ? items.slice() : baseline,
-    canToggle: baseline.length < items.length,
+    leadingItem,
+    visibleItems: baseline,
+    canToggle,
   };
 }
diff --git a/packages/app/src/components/sidebar/sidebar-help-menu.tsx b/packages/app/src/components/sidebar/sidebar-help-menu.tsx
index 0eefa77468..d6ba4e98e1 100644
--- a/packages/app/src/components/sidebar/sidebar-help-menu.tsx
+++ b/packages/app/src/components/sidebar/sidebar-help-menu.tsx
@@ -1,5 +1,5 @@
 import { useCallback, useState } from "react";
-import { Text, View } from "react-native";
+import { View } from "react-native";
 import { Activity, CircleHelp, Gift, Keyboard } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
@@ -12,17 +12,13 @@ import {
   DropdownMenuItem,
   DropdownMenuLabel,
   DropdownMenuSeparator,
-  DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { DensityIcon } from "@/components/ui/density-icon";
-import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
 import { useAppDiagnosticStore } from "@/diagnostics/store";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { useSessionStore } from "@/stores/session-store";
-import { density } from "@/styles/density";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import type { HostProfile } from "@/types/host-connection";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -77,12 +73,32 @@ function HostVersionHint({ host }: { host: HostProfile }) {
   );
 }
 
+/** The Help menu's trigger, and the menu it opens. */
 export function SidebarHelpMenu() {
   const { t } = useTranslation();
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={CircleHelp}
+        label={t("sidebar.help.trigger")}
+        menuOpen={open}
+        testID="sidebar-help"
+      />
+      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
+        <SidebarHelpMenuItems />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The Help menu's rows, shared by the Help menu and the footer's overflow page for it. */
+export function SidebarHelpMenuItems() {
+  const { t } = useTranslation();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAppDiagnostic = useAppDiagnosticStore((state) => state.open);
   const setShortcutsDialogOpen = useKeyboardShortcutsStore((state) => state.setShortcutsDialogOpen);
-  const [open, setOpen] = useState(false);
   const version = formatVersionWithPrefix(resolveAppVersion());
   const hosts = useHosts();
 
@@ -99,105 +115,65 @@ export function SidebarHelpMenu() {
   }, []);
 
   return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <Tooltip delayDuration={300} enabledOnDesktop={!open}>
-        <TooltipTrigger asChild>
-          <View>
-            <DropdownMenuTrigger
-              style={styles.trigger}
-              testID="sidebar-help"
-              accessibilityRole="button"
-              accessibilityLabel={t("sidebar.help.trigger")}
-            >
-              {({ hovered, pressed, open: menuOpen }) => (
-                <>
-                  <SidebarFooterIconHighlight visible={pressed || menuOpen} />
-                  <DensityIcon
-                    icon={CircleHelp}
-                    size="md"
-                    color={hovered ? "foreground" : "foregroundMuted"}
-                  />
-                </>
-              )}
-            </DropdownMenuTrigger>
-          </View>
-        </TooltipTrigger>
-        <TooltipContent side="top" align="center" offset={8}>
-          <Text style={styles.tooltipText}>{t("sidebar.help.trigger")}</Text>
-        </TooltipContent>
-      </Tooltip>
-      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
-        <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
-        {shortcutsAvailable ? (
-          <DropdownMenuItem
-            testID="sidebar-help-shortcuts"
-            leading={shortcutsLeadingIcon}
-            onSelect={openKeyboardShortcuts}
-          >
-            {t("sidebar.help.shortcuts")}
-          </DropdownMenuItem>
-        ) : null}
+    <>
+      <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
+      {shortcutsAvailable ? (
         <DropdownMenuItem
-          testID="sidebar-help-changelog"
-          leading={changelogLeadingIcon}
-          onSelect={openChangelog}
+          testID="sidebar-help-shortcuts"
+          leading={shortcutsLeadingIcon}
+          onSelect={openKeyboardShortcuts}
         >
-          {t("sidebar.help.whatsNew")}
+          {t("sidebar.help.shortcuts")}
         </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-diagnostics"
-          leading={diagnosticLeadingIcon}
-          onSelect={openAppDiagnostic}
+      ) : null}
+      <DropdownMenuItem
+        testID="sidebar-help-changelog"
+        leading={changelogLeadingIcon}
+        onSelect={openChangelog}
+      >
+        {t("sidebar.help.whatsNew")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-diagnostics"
+        leading={diagnosticLeadingIcon}
+        onSelect={openAppDiagnostic}
+      >
+        {t("sidebar.help.diagnostics")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
+      <DropdownMenuItem
+        testID="sidebar-help-discord"
+        leading={discordLeadingIcon}
+        onSelect={openDiscord}
+      >
+        {t("sidebar.help.discord")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-github"
+        leading={githubLeadingIcon}
+        onSelect={openGitHubIssue}
+      >
+        {t("sidebar.help.github")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <View style={styles.versionList}>
+        <DropdownMenuHint
+          style={styles.versionHint}
+          trailing={version}
+          testID="sidebar-help-version"
         >
-          {t("sidebar.help.diagnostics")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
-        <DropdownMenuItem
-          testID="sidebar-help-discord"
-          leading={discordLeadingIcon}
-          onSelect={openDiscord}
-        >
-          {t("sidebar.help.discord")}
-        </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-github"
-          leading={githubLeadingIcon}
-          onSelect={openGitHubIssue}
-        >
-          {t("sidebar.help.github")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <View style={styles.versionList}>
-          <DropdownMenuHint
-            style={styles.versionHint}
-            trailing={version}
-            testID="sidebar-help-version"
-          >
-            {t("sidebar.help.appName")}
-          </DropdownMenuHint>
-          {hosts.map((host) => (
-            <HostVersionHint key={host.serverId} host={host} />
-          ))}
-        </View>
-      </DropdownMenuContent>
-    </DropdownMenu>
+          {t("sidebar.help.appName")}
+        </DropdownMenuHint>
+        {hosts.map((host) => (
+          <HostVersionHint key={host.serverId} host={host} />
+        ))}
+      </View>
+    </>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  trigger: {
-    width: density.iconButton,
-    height: density.iconButton,
-    alignItems: "center",
-    justifyContent: "center",
-    paddingVertical: theme.spacing[1],
-    paddingHorizontal: theme.spacing[1],
-  },
-  tooltipText: {
-    fontSize: theme.fontSize.base,
-    color: theme.colors.popoverForeground,
-  },
   versionList: {
     gap: theme.spacing[1],
     paddingVertical: theme.spacing[2],
diff --git a/packages/app/src/components/sidebar/sidebar-model.tsx b/packages/app/src/components/sidebar/sidebar-model.tsx
index cfa69428f8..9339e9bc95 100644
--- a/packages/app/src/components/sidebar/sidebar-model.tsx
+++ b/packages/app/src/components/sidebar/sidebar-model.tsx
@@ -50,13 +50,16 @@ const SidebarModelContext = createContext<SidebarModel | null>(null);
 
 export function SidebarModelProvider({
   active,
+  keyboardNavigationActive = false,
   children,
 }: {
   active?: boolean;
+  keyboardNavigationActive?: boolean;
   children: ReactNode;
 }) {
   const { t } = useTranslation();
-  const list = useSidebarWorkspacesList({ enabled: active });
+  const modelActive = active !== false || keyboardNavigationActive;
+  const list = useSidebarWorkspacesList({ enabled: modelActive });
   const showBackground = useSidebarViewStore((state) => state.showBackground);
   const groupMode = useSidebarViewStore((state) => state.groupMode);
   const labelFilter = useSidebarViewStore((state) => state.labelFilter);
@@ -98,10 +101,11 @@ export function SidebarModelProvider({
   // anything; the label filter reads `labels`, which only exists on an entry. Hydration opens a
   // live session-store subscription over every workspace on every visible host, so widening this
   // for a filter that does not need it costs a retained-but-inactive sidebar real work.
+  // Hardware keyboard navigation needs the same filtered targets while the sidebar is hidden.
   const needsWorkspaceEntries = groupMode !== "project" || hasActiveLabelFilter;
   const workspaceEntriesByKey = useSidebarWorkspaceEntries(
     list.workspacePlacements,
-    active !== false || needsWorkspaceEntries,
+    modelActive || needsWorkspaceEntries,
   );
   const filteredWorkspaceEntriesByKey = useMemo(() => {
     const byProject = filterWorkspacesByProjects({
diff --git a/packages/app/src/components/sidebar/sidebar-status-list.tsx b/packages/app/src/components/sidebar/sidebar-status-list.tsx
index 44622385a4..ed19b08857 100644
--- a/packages/app/src/components/sidebar/sidebar-status-list.tsx
+++ b/packages/app/src/components/sidebar/sidebar-status-list.tsx
@@ -147,6 +147,7 @@ export function SidebarStatusWorkspaceList({
   dragGestureHostActive,
 }: StatusWorkspaceListProps) {
   const { t } = useTranslation();
+  const activeWorkspaceSelection = useActiveWorkspaceSelection();
   const collapsedWorkspaceGroupKeys = useSidebarCollapsedSectionsStore(
     (state) => state.collapsedWorkspaceGroupKeys,
   );
@@ -155,23 +156,27 @@ export function SidebarStatusWorkspaceList({
     (state) => state.togglePinnedCollapsed,
   );
   const {
+    leadingItem: leadingPinnedWorkspace,
     visibleItems: visiblePinnedWorkspaces,
     expanded: pinnedWorkspacesExpanded,
     canToggle: canTogglePinnedWorkspaces,
     toggleExpanded: togglePinnedWorkspacesExpanded,
-  } = useLimitedSidebarGroup(pinnedWorkspaces);
+  } = useLimitedSidebarGroup({ items: pinnedWorkspaces, selection: activeWorkspaceSelection });
 
   const statusShortcutIndex = showShortcutBadges
     ? shortcutIndexByWorkspaceKey
     : EMPTY_SHORTCUT_INDEX;
-  const renderPinnedWorkspace = useCallback(
-    ({
-      item: workspace,
-      drag,
-      isActive,
-      dragHandleProps,
-    }: DraggableRenderItemInfo<SidebarWorkspaceEntry>) => (
+  const renderPinnedWorkspaceRow = useCallback(
+    (
+      workspace: SidebarWorkspaceEntry,
+      input?: {
+        drag?: () => void;
+        isDragging?: boolean;
+        dragHandleProps?: DraggableListDragHandleProps;
+      },
+    ) => (
       <StatusWorkspaceRow
+        key={workspace.workspaceKey}
         workspace={workspace}
         {...buildStatusRowProjectPresentation({
           workspace,
@@ -184,9 +189,9 @@ export function SidebarStatusWorkspaceList({
         canPin={supportsPinningByServerId.get(workspace.serverId) === true}
         onToggleWorkspacePin={onToggleWorkspacePin}
         onWorkspacePress={onWorkspacePress}
-        drag={drag}
-        isDragging={isActive}
-        dragHandleProps={dragHandleProps}
+        drag={input?.drag}
+        isDragging={input?.isDragging}
+        dragHandleProps={input?.dragHandleProps}
       />
     ),
     [
@@ -199,6 +204,20 @@ export function SidebarStatusWorkspaceList({
       supportsPinningByServerId,
     ],
   );
+  const renderPinnedWorkspace = useCallback(
+    ({
+      item: workspace,
+      drag,
+      isActive,
+      dragHandleProps,
+    }: DraggableRenderItemInfo<SidebarWorkspaceEntry>) =>
+      renderPinnedWorkspaceRow(workspace, {
+        drag,
+        isDragging: isActive,
+        dragHandleProps,
+      }),
+    [renderPinnedWorkspaceRow],
+  );
   const content = (
     <>
       {pinnedWorkspaces.length > 0 ? (
@@ -211,6 +230,7 @@ export function SidebarStatusWorkspaceList({
           />
           {pinnedCollapsed ? null : (
             <>
+              {leadingPinnedWorkspace ? renderPinnedWorkspaceRow(leadingPinnedWorkspace) : null}
               <DraggableList
                 testID="sidebar-pinned-list"
                 data={visiblePinnedWorkspaces}
@@ -345,12 +365,37 @@ function StatusGroupRows({
   supportsPinningByServerId: ReadonlyMap<string, boolean>;
   onToggleWorkspacePin: ToggleSidebarWorkspacePin;
 }) {
+  const activeWorkspaceSelection = useActiveWorkspaceSelection();
   const {
+    leadingItem: leadingWorkspace,
     visibleItems: visibleWorkspaces,
     expanded: workspacesExpanded,
     canToggle: canToggleWorkspaces,
     toggleExpanded: toggleWorkspacesExpanded,
-  } = useLimitedSidebarGroup(group.rows, STATUS_GROUP_VISIBILITY);
+  } = useLimitedSidebarGroup({
+    items: group.rows,
+    selection: activeWorkspaceSelection,
+    policy: STATUS_GROUP_VISIBILITY,
+  });
+
+  function renderWorkspaceRow(workspace: SidebarWorkspaceEntry) {
+    return (
+      <StatusWorkspaceRow
+        key={workspace.workspaceKey}
+        workspace={workspace}
+        {...buildStatusRowProjectPresentation({
+          workspace,
+          projectIconByProjectViewKey,
+          hostBadgeByServerId,
+        })}
+        shortcutNumber={shortcutIndex.get(workspace.workspaceKey) ?? null}
+        showShortcutBadge={showShortcutBadges}
+        canPin={supportsPinningByServerId.get(workspace.serverId) === true}
+        onToggleWorkspacePin={onToggleWorkspacePin}
+        onWorkspacePress={onWorkspacePress}
+      />
+    );
+  }
 
   return (
     <View style={collapsed ? undefined : styles.statusGroupBlockExpanded}>
@@ -360,22 +405,8 @@ function StatusGroupRows({
           style={styles.statusWorkspaceListContainer}
           testID={`sidebar-status-group-rows-${group.key}`}
         >
-          {visibleWorkspaces.map((workspace) => (
-            <StatusWorkspaceRow
-              key={workspace.workspaceKey}
-              workspace={workspace}
-              {...buildStatusRowProjectPresentation({
-                workspace,
-                projectIconByProjectViewKey,
-                hostBadgeByServerId,
-              })}
-              shortcutNumber={shortcutIndex.get(workspace.workspaceKey) ?? null}
-              showShortcutBadge={showShortcutBadges}
-              canPin={supportsPinningByServerId.get(workspace.serverId) === true}
-              onToggleWorkspacePin={onToggleWorkspacePin}
-              onWorkspacePress={onWorkspacePress}
-            />
-          ))}
+          {leadingWorkspace ? renderWorkspaceRow(leadingWorkspace) : null}
+          {visibleWorkspaces.map(renderWorkspaceRow)}
           {canToggleWorkspaces ? (
             <SidebarGroupToggleRow
               expanded={workspacesExpanded}
@@ -841,6 +872,7 @@ function StatusWorkspaceRowInnerContent({
         const {
           trailingPresentation,
           showKebab: showKebabInSlot,
+          showArchiveButton,
           showScrim,
           renderSlot,
           reserveSlotWidth,
@@ -920,6 +952,7 @@ function StatusWorkspaceRowInnerContent({
                     trailing={trailing}
                     trailingPresentation={trailingPresentation}
                     showKebab={showKebabInSlot}
+                    showArchiveButton={showArchiveButton}
                     showScrim={showScrim}
                     reserveSlotWidth={reserveSlotWidth}
                     isPinned={isPinned}
@@ -951,6 +984,7 @@ function StatusWorkspaceActionSlot({
   trailing,
   trailingPresentation,
   showKebab,
+  showArchiveButton,
   showScrim,
   reserveSlotWidth,
   isPinned,
@@ -971,6 +1005,7 @@ function StatusWorkspaceActionSlot({
   trailing: SidebarWorkspaceTrailing;
   trailingPresentation: SidebarWorkspaceTrailingPresentation;
   showKebab: boolean;
+  showArchiveButton: boolean;
   showScrim: boolean;
   reserveSlotWidth: boolean;
   isPinned?: boolean;
@@ -995,6 +1030,8 @@ function StatusWorkspaceActionSlot({
       <SidebarWorkspaceTrailingActionOverlay
         visible={kebab.showKebab}
         scrimBackdrop={showScrim ? backdrop : undefined}
+        workspaceKey={workspace.workspaceKey}
+        onArchiveButtonPress={showArchiveButton ? onArchive : undefined}
       >
         {kebab.showKebab && onArchive ? (
           <SidebarWorkspaceMenu
diff --git a/packages/app/src/components/sidebar/sidebar-toast-region.tsx b/packages/app/src/components/sidebar/sidebar-toast-region.tsx
new file mode 100644
index 0000000000..852ce7302d
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-toast-region.tsx
@@ -0,0 +1,52 @@
+import { useEffect, useMemo, useRef, type ReactNode } from "react";
+import { View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { ToastViewport, useToastHost, type ToastApi } from "@/components/toast-host";
+import { ToastApiProvider, useToast } from "@/contexts/toast-context";
+
+/**
+ * Shows toasts raised by the sidebar's list over its bottom edge, just above the footer.
+ *
+ * A collapsed sidebar stays mounted and its rows still handle shortcuts, so while it is hidden
+ * their toasts go to the app's host instead. The sidebar's API stays stable across open and close
+ * so that toggling the panel doesn't re-render every row.
+ */
+export function SidebarToastRegion({ active, children }: { active: boolean; children: ReactNode }) {
+  const appToast = useToast();
+  const { api: sidebarToast, toast, dismiss } = useToastHost();
+  const activeRef = useRef(active);
+
+  useEffect(() => {
+    activeRef.current = active;
+    return () => {
+      // An archive holds on to this API, so a failure that lands later needs a host on screen.
+      activeRef.current = false;
+      // A toast must not outlive its visibility: its dismissal is what ends an archive's undo.
+      dismiss();
+    };
+  }, [active, dismiss]);
+
+  const api = useMemo<ToastApi>(() => {
+    const visibleHost = () => (activeRef.current ? sidebarToast : appToast);
+    return {
+      show: (content, options) => visibleHost().show(content, options),
+      copied: (label) => visibleHost().copied(label),
+      error: (message) => visibleHost().error(message),
+    };
+  }, [appToast, sidebarToast]);
+
+  return (
+    <View style={styles.region}>
+      <ToastApiProvider api={api}>{children}</ToastApiProvider>
+      <ToastViewport toast={toast} onDismiss={dismiss} placement="sidebar" />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  region: {
+    position: "relative",
+    flex: 1,
+    minHeight: 0,
+  },
+});
diff --git a/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx b/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
index f74c43c980..ac872ffbd8 100644
--- a/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
+++ b/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
@@ -1,6 +1,6 @@
 import { useMemo, type ComponentProps, type PropsWithChildren, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import { type PressableStateCallbackType } from "react-native";
+import type { PressableStateCallbackType } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import {
   Archive,
@@ -13,6 +13,7 @@ import {
   PinOff,
   Tag,
 } from "lucide-react-native";
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { isWeb } from "@/constants/platform";
 import { getForgePresentation, normalizeForge } from "@/git/forge";
 import type { SidebarWorkspaceEntry } from "@/hooks/use-sidebar-workspaces-list";
@@ -36,6 +37,7 @@ import {
 import { Shortcut } from "@/components/ui/shortcut";
 import { OpenInFileManagerMenuItem } from "@/workspace/open-in-file-manager/menu-item";
 import { resolveSidebarWorkspaceAccessibilityLabel } from "@/components/sidebar/sidebar-workspace-title";
+import { bySizing } from "@/components/ui/control-geometry";
 import {
   workspaceServiceLabelKey,
   type WorkspaceServiceSummary,
@@ -71,6 +73,13 @@ const archiveLeadingIcon = <ThemedArchive size={14} uniProps={foregroundMutedCol
 const pinLeadingIcon = <ThemedPin size={14} uniProps={foregroundMutedColorMapping} />;
 const unpinLeadingIcon = <ThemedPinOff size={14} uniProps={foregroundMutedColorMapping} />;
 
+/** Pointer-only, so it is always the kebab's pointer size. */
+const ARCHIVE_BUTTON_SIZE = 18;
+/** Keeps a press aimed at the kebab from landing on the one-click archive. */
+const ARCHIVE_BUTTON_KEBAB_GAP = 8;
+/** The width the archive button and its gap take up left of the kebab. */
+export const ARCHIVE_BUTTON_FOOTPRINT = ARCHIVE_BUTTON_SIZE + ARCHIVE_BUTTON_KEBAB_GAP;
+
 const triggerIconProps = densityIconProps("sm", foregroundMutedColorMapping);
 const triggerIconHoveredProps = densityIconProps("sm", foregroundColorMapping);
 
@@ -78,6 +87,33 @@ function renderTriggerIcon({ hovered }: { hovered?: boolean }) {
   return <ThemedMoreVertical uniProps={hovered ? triggerIconHoveredProps : triggerIconProps} />;
 }
 
+function renderArchiveIcon({ hovered }: PressableStateCallbackType & { hovered?: boolean }) {
+  return <ThemedArchive uniProps={hovered ? triggerIconHoveredProps : triggerIconProps} />;
+}
+
+/** One-click archive beside the kebab, for pointer rows that reveal it on hover. */
+export function SidebarWorkspaceArchiveButton({
+  workspaceKey,
+  onArchive,
+}: {
+  workspaceKey: string;
+  onArchive: () => void;
+}) {
+  const { t } = useTranslation();
+  return (
+    <PressHighlight
+      hitSlop={4}
+      style={archiveButtonStyle}
+      onPress={onArchive}
+      accessibilityRole={isWeb ? undefined : "button"}
+      accessibilityLabel={t("sidebar.workspace.actions.archiveWorkspace")}
+      testID={`sidebar-workspace-archive-button-${workspaceKey}`}
+    >
+      {renderArchiveIcon}
+    </PressHighlight>
+  );
+}
+
 export interface SidebarWorkspaceMenuProps {
   workspaceKey: string;
   serverId?: string;
@@ -436,22 +472,37 @@ function triggerStyle({ hovered = false }: PressableStateCallbackType & { hovere
   return [styles.trigger, hovered && styles.triggerHovered];
 }
 
+function archiveButtonStyle({
+  hovered = false,
+}: PressableStateCallbackType & { hovered?: boolean }) {
+  return [styles.archiveButton, hovered && styles.triggerHovered];
+}
+
 const styles = StyleSheet.create((theme) => ({
   trigger: {
-    // Larger on compact so the kebab is an easy tap target.
-    width: { xs: 32, md: 18 },
-    height: { xs: 32, md: 18 },
+    // Larger on touch so the kebab is an easy tap target.
+    width: bySizing({ touch: 32, pointer: 18 }),
+    height: bySizing({ touch: 32, pointer: 18 }),
     alignItems: "center",
     justifyContent: "center",
     borderRadius: 4,
-    marginLeft: 2,
-    // Center the compact box on the 20px title line it is anchored to.
-    marginTop: { xs: -6, md: 0 },
+    // Center the touch box on the 20px title line it is anchored to.
+    marginTop: bySizing({ touch: -6, pointer: 0 }),
     // MoreVertical paints only around the center of its SVG. Keep the padded hit box, but
     // pull the painted dots through that unused view-box space onto the trailing-content rail.
-    marginRight: { xs: -14, md: -7 },
+    marginRight: bySizing({ touch: -14, pointer: -7 }),
   },
   triggerHovered: {
     backgroundColor: theme.colors.surface2,
   },
+  // The kebab's box without its offsets: the archive glyph fills its view box, so it needs
+  // none of the nudging the three dots do.
+  archiveButton: {
+    width: ARCHIVE_BUTTON_SIZE,
+    height: ARCHIVE_BUTTON_SIZE,
+    marginRight: ARCHIVE_BUTTON_KEBAB_GAP,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 4,
+  },
 }));
diff --git a/packages/app/src/components/sidebar/sidebar-workspace-row-content.tsx b/packages/app/src/components/sidebar/sidebar-workspace-row-content.tsx
index 7fc904f3b3..eda162d52c 100644
--- a/packages/app/src/components/sidebar/sidebar-workspace-row-content.tsx
+++ b/packages/app/src/components/sidebar/sidebar-workspace-row-content.tsx
@@ -29,7 +29,11 @@ import { shouldRenderSyncedStatusLoader } from "@/utils/status-loader";
 import { StatusRing } from "@/components/status-ring";
 import { resolveSidebarWorkspacePrimaryLabel } from "@/components/sidebar/sidebar-workspace-title";
 import { DensityIcon } from "@/components/ui/density-icon";
-import { TrailingActionScrim } from "@/components/ui/trailing-action-scrim";
+import { SCRIM_WIDTH, TrailingActionScrim } from "@/components/ui/trailing-action-scrim";
+import {
+  ARCHIVE_BUTTON_FOOTPRINT,
+  SidebarWorkspaceArchiveButton,
+} from "@/components/sidebar/sidebar-workspace-menu";
 import { useWorkspaceLabelDefinitions } from "@/workspace-labels";
 
 const needsInputColorMapping = (theme: Theme) => ({
@@ -156,7 +160,11 @@ export const SidebarWorkspaceRowContent = memo(function SidebarWorkspaceRowConte
         )}
         <View style={styles.workspaceContentColumn}>
           <View style={styles.workspaceTitleRow}>
-            <Text style={workspaceBranchTextStyle} numberOfLines={1}>
+            <Text
+              style={workspaceBranchTextStyle}
+              numberOfLines={1}
+              testID={`sidebar-workspace-title-${workspace.workspaceKey}`}
+            >
               {workspaceLabel}
             </Text>
             <View style={sidebarWorkspaceRowStyles.rowRight}>{children}</View>
@@ -330,6 +338,8 @@ export const sidebarWorkspaceRowStyles = StyleSheet.create((theme) => ({
     position: "absolute",
     top: 0,
     right: 0,
+    flexDirection: "row",
+    alignItems: "flex-start",
   },
 }));
 
@@ -370,6 +380,7 @@ export function resolveTrailingActionVisibility({
 }): {
   trailingPresentation: SidebarWorkspaceTrailingPresentation;
   showKebab: boolean;
+  showArchiveButton: boolean;
   showScrim: boolean;
   renderSlot: boolean;
   reserveSlotWidth: boolean;
@@ -384,6 +395,9 @@ export function resolveTrailingActionVisibility({
   return {
     trailingPresentation,
     showKebab,
+    // One-click archive is a pointer affordance: on touch it would sit a few pixels from the
+    // kebab and turn a miss into an archive.
+    showArchiveButton: showKebab && isHovered && !isTouchPlatform,
     // The scrim paints the row's own hover background, so it can only be drawn on a hovered
     // row — over an unhovered one the gradient fades to the wrong color. That is also why
     // touch, which shows the kebab without ever hovering, never gets one.
@@ -435,20 +449,40 @@ export function SidebarWorkspaceTrailingActionBase({
 export function SidebarWorkspaceTrailingActionOverlay({
   visible,
   scrimBackdrop,
+  workspaceKey,
+  onArchiveButtonPress,
   children,
 }: {
   visible: boolean;
   /** Fade the row into the kebab when something (the diff stat) is still rendered behind it. */
   scrimBackdrop?: SidebarSurfaceBackdrop;
+  workspaceKey: string;
+  /**
+   * Shows the archive button left of the kebab. It overlays the title like the kebab does, so
+   * the scrim widens to cover it rather than the slot reserving its width.
+   */
+  onArchiveButtonPress?: () => void;
   children: ReactNode;
 }) {
   if (!visible || !children) return null;
   return (
     <>
       {scrimBackdrop ? (
-        <TrailingActionScrim backdrop={scrimBackdrop} testID="sidebar-workspace-trailing-scrim" />
+        <TrailingActionScrim
+          backdrop={scrimBackdrop}
+          width={onArchiveButtonPress ? SCRIM_WIDTH + ARCHIVE_BUTTON_FOOTPRINT : SCRIM_WIDTH}
+          testID="sidebar-workspace-trailing-scrim"
+        />
       ) : null}
-      <View style={sidebarWorkspaceRowStyles.trailingActionOverlay}>{children}</View>
+      <View style={sidebarWorkspaceRowStyles.trailingActionOverlay}>
+        {onArchiveButtonPress ? (
+          <SidebarWorkspaceArchiveButton
+            workspaceKey={workspaceKey}
+            onArchive={onArchiveButtonPress}
+          />
+        ) : null}
+        {children}
+      </View>
     </>
   );
 }
diff --git a/packages/app/src/components/sidebar/sidebar-workspace-row.tsx b/packages/app/src/components/sidebar/sidebar-workspace-row.tsx
index 2488e7956e..d458b390ed 100644
--- a/packages/app/src/components/sidebar/sidebar-workspace-row.tsx
+++ b/packages/app/src/components/sidebar/sidebar-workspace-row.tsx
@@ -404,6 +404,7 @@ function WorkspaceRowTrailingActions({
   const {
     trailingPresentation,
     showKebab: showKebabInSlot,
+    showArchiveButton,
     showScrim,
     renderSlot,
     reserveSlotWidth,
@@ -430,6 +431,8 @@ function WorkspaceRowTrailingActions({
           <SidebarWorkspaceTrailingActionOverlay
             visible={kebab.showKebab}
             scrimBackdrop={showScrim ? backdrop : undefined}
+            workspaceKey={workspace.workspaceKey}
+            onArchiveButtonPress={showArchiveButton ? onArchive : undefined}
           >
             {onArchive ? (
               <SidebarWorkspaceMenu
diff --git a/packages/app/src/components/sidebar/use-limited-sidebar-group.ts b/packages/app/src/components/sidebar/use-limited-sidebar-group.ts
index 99e4476dfb..c7b77bfc16 100644
--- a/packages/app/src/components/sidebar/use-limited-sidebar-group.ts
+++ b/packages/app/src/components/sidebar/use-limited-sidebar-group.ts
@@ -1,19 +1,32 @@
 import { useCallback, useMemo, useState } from "react";
 import {
   selectSidebarGroupVisibility,
+  type SidebarGroupItem,
+  type SidebarGroupVisibility,
   type SidebarGroupVisibilityPolicy,
 } from "./sidebar-group-visibility";
+import type { ActiveWorkspaceSelection } from "@/stores/last-workspace-selection";
 
 const PINNED_POLICY = { kind: "pinned" } as const;
 
-export function useLimitedSidebarGroup<T>(
-  items: readonly T[],
-  policy: SidebarGroupVisibilityPolicy<T> = PINNED_POLICY,
-) {
+interface LimitedSidebarGroupInput<T> {
+  items: readonly T[];
+  selection: ActiveWorkspaceSelection | null;
+  policy?: SidebarGroupVisibilityPolicy<T>;
+}
+
+export function useLimitedSidebarGroup<T extends SidebarGroupItem>({
+  items,
+  selection,
+  policy = PINNED_POLICY,
+}: LimitedSidebarGroupInput<T>): SidebarGroupVisibility<T> & {
+  expanded: boolean;
+  toggleExpanded: () => void;
+} {
   const [expanded, setExpanded] = useState(false);
   const visibility = useMemo(
-    () => selectSidebarGroupVisibility(items, expanded, policy),
-    [expanded, items, policy],
+    () => selectSidebarGroupVisibility({ items, expanded, policy, selection }),
+    [expanded, items, policy, selection],
   );
   const toggleExpanded = useCallback(() => setExpanded((current) => !current), []);
 
diff --git a/packages/app/src/components/split-container.tsx b/packages/app/src/components/split-container.tsx
index 278317243a..36f3af0b28 100644
--- a/packages/app/src/components/split-container.tsx
+++ b/packages/app/src/components/split-container.tsx
@@ -1,3 +1,7 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderTabs,
+} from "@/screens/workspace/adaptive-workspace-chrome";
 import { useWorkspaceTabDrag } from "./workspace-tab-drag-context";
 import {
   Fragment,
@@ -32,6 +36,7 @@ import {
   WindowChromeSafeArea,
   useWindowChromeCorners,
   removeWindowChromeCorner,
+  resolveChildWindowChromeCorners,
   type WindowChromeCorners,
 } from "@/utils/desktop-window";
 import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
@@ -42,6 +47,7 @@ import type { WorkspacePaneContentModel } from "@/screens/workspace/workspace-pa
 import { WorkspacePanelHost } from "@/screens/workspace/workspace-panel-host";
 import {
   WorkspaceDesktopTabsRow,
+  useWorkspaceNewTabKeyboardAction,
   type WorkspaceDesktopTabRowItem,
 } from "@/screens/workspace/workspace-desktop-tabs-row";
 import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
@@ -60,7 +66,13 @@ import { isNative } from "@/constants/platform";
 
 interface SplitContainerProps {
   layout: WorkspaceLayout;
+  /** The full workspace header: title, project row and workspace actions. */
   renderMainHeader?: () => ReactNode;
+  /**
+   * The compact workspace header. With one presented pane it carries that pane's tab switcher in
+   * place of its tab rail; above a split it carries workspace controls only.
+   */
+  renderCompactHeader: (paneTabs: WorkspaceCompactHeaderTabs | null) => ReactNode;
   workspaceKey: string;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
@@ -117,6 +129,11 @@ interface SplitNodeViewProps extends Omit<
   windowChromeCorners: WindowChromeCorners;
   maximizedPaneId: string | null;
   workspaceHasMultiplePanes: boolean;
+  /**
+   * One presented pane draws the workspace header itself and may merge its tabs into the compact
+   * header. Split panes share one header above them and always show their tab rails.
+   */
+  ownsWorkspaceHeader: boolean;
   onTogglePaneMaximized: (paneId: string) => void;
 }
 
@@ -145,7 +162,6 @@ const EMPTY_SPLIT_SIZES: number[] = [];
 
 export function SplitContainer({
   layout,
-  renderMainHeader,
   workspaceKey,
   normalizedServerId,
   normalizedWorkspaceId,
@@ -174,9 +190,11 @@ export function SplitContainer({
   onReorderTabsInPane,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitContainerProps) {
   const inheritedWindowChromeCorners = useWindowChromeCorners();
-  const windowChromeCorners = focusModeEnabled ? inheritedWindowChromeCorners : "none";
+  const windowChromeCorners = inheritedWindowChromeCorners;
   const { activeDragTabId, dropPreview, tabDropPreview } = useWorkspaceTabDrag();
   const [maximizedPane, setMaximizedPane] = useState<{
     workspaceKey: string;
@@ -232,12 +250,27 @@ export function SplitContainer({
       : inheritedWindowChromeCorners;
   const mainColumnStyle = styles.mainColumn;
   const renderRoot = useMemo(() => wrapRootPaneForStableMount(splitRoot.root), [splitRoot.root]);
+  const panesShareWorkspaceHeader = hasMultipleVisiblePanes(splitRoot.root);
+  const sharedCompactHeader = useMemo(
+    () =>
+      panesShareWorkspaceHeader ? (
+        <WindowChromeSafeArea placement="inline">
+          <TitlebarDragRegion />
+          {renderCompactHeader(null)}
+        </WindowChromeSafeArea>
+      ) : null,
+    [panesShareWorkspaceHeader, renderCompactHeader],
+  );
   return (
     <RenderProfile id="SplitContainer">
       <View style={styles.workspaceShell}>
         <WindowChromeRegion corners={mainColumnWindowChromeCorners}>
           <View style={mainColumnStyle}>
-            {renderMainHeader?.()}
+            {panesShareWorkspaceHeader ? (
+              <AdaptiveWorkspaceChrome compactHeader={sharedCompactHeader}>
+                {renderMainHeader?.()}
+              </AdaptiveWorkspaceChrome>
+            ) : null}
             {splitRoot.usesFallbackStrip && <WindowChromeSafeArea placement="below" />}
             {renderRoot ? (
               <SplitNodeView
@@ -273,12 +306,19 @@ export function SplitContainer({
                 showDropZones={activeDragTabId !== null}
                 dropPreview={dropPreview}
                 tabDropPreview={tabDropPreview}
-                windowChromeCorners={splitRoot.usesFallbackStrip ? "none" : windowChromeCorners}
+                windowChromeCorners={
+                  splitRoot.usesFallbackStrip || panesShareWorkspaceHeader
+                    ? "none"
+                    : windowChromeCorners
+                }
+                ownsWorkspaceHeader={!panesShareWorkspaceHeader}
                 maximizedPaneId={maximizedPaneId}
                 workspaceHasMultiplePanes={workspaceHasMultiplePanes}
                 onTogglePaneMaximized={handleTogglePaneMaximized}
                 focusModeEnabled={focusModeEnabled}
                 onExitFocusMode={onExitFocusMode}
+                renderMainHeader={renderMainHeader}
+                renderCompactHeader={renderCompactHeader}
               />
             ) : null}
           </View>
@@ -410,6 +450,9 @@ function SplitNodeView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  ownsWorkspaceHeader,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitNodeViewProps) {
   const [groupContainerSize, setGroupContainerSize] = useState(0);
   const groupId = node.kind === "group" ? node.group.id : null;
@@ -496,6 +539,9 @@ function SplitNodeView({
             onTogglePaneMaximized={onTogglePaneMaximized}
             focusModeEnabled={focusModeEnabled}
             onExitFocusMode={onExitFocusMode}
+            ownsWorkspaceHeader={ownsWorkspaceHeader}
+            renderMainHeader={renderMainHeader}
+            renderCompactHeader={renderCompactHeader}
           />
         </WindowChromeRegion>
       </RetainedPanel>
@@ -544,12 +590,26 @@ function SplitNodeView({
               showDropZones={showDropZones}
               dropPreview={dropPreview}
               tabDropPreview={tabDropPreview}
-              windowChromeCorners={windowChromeCorners}
+              windowChromeCorners={resolveChildWindowChromeCorners({
+                corners: windowChromeCorners,
+                direction: node.group.direction,
+                isFirst:
+                  node.group.children.findIndex(
+                    (candidate) => !isSplitNodeHiddenForPresentation(candidate, maximizedPaneId),
+                  ) === index,
+                isLast:
+                  node.group.children.findLastIndex(
+                    (candidate) => !isSplitNodeHiddenForPresentation(candidate, maximizedPaneId),
+                  ) === index,
+              })}
               maximizedPaneId={maximizedPaneId}
               workspaceHasMultiplePanes={workspaceHasMultiplePanes}
               onTogglePaneMaximized={onTogglePaneMaximized}
               focusModeEnabled={focusModeEnabled}
               onExitFocusMode={onExitFocusMode}
+              ownsWorkspaceHeader={ownsWorkspaceHeader}
+              renderMainHeader={renderMainHeader}
+              renderCompactHeader={renderCompactHeader}
             />
           </SplitGroupChild>
           {index < node.group.children.length - 1 &&
@@ -608,6 +668,9 @@ const SplitPaneView = memo(function SplitPaneView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  ownsWorkspaceHeader,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitPaneViewProps) {
   recordRenderProfileReasons(`SplitPaneView:${pane.id}`, ["render"]);
   const paneRef = useRef<View | null>(null);
@@ -701,6 +764,62 @@ const SplitPaneView = memo(function SplitPaneView({
     () => onTogglePaneMaximized(paneId),
     [onTogglePaneMaximized, paneId],
   );
+  const compactHeaderActions = useMemo(
+    () => ({
+      pane: {
+        id: paneId,
+        splitRight: focusModeEnabled ? undefined : handleSplitRight,
+        splitDown: focusModeEnabled ? undefined : handleSplitDown,
+        toggleMaximized:
+          workspaceHasMultiplePanes && !focusModeEnabled ? handleTogglePaneMaximized : undefined,
+        maximized: paneId === maximizedPaneId,
+      },
+      closeAbove: handleCloseTabsToLeft,
+      closeBelow: handleCloseTabsToRight,
+      closeOthers: handleCloseOtherTabs,
+    }),
+    [
+      paneId,
+      focusModeEnabled,
+      handleSplitRight,
+      handleSplitDown,
+      workspaceHasMultiplePanes,
+      handleTogglePaneMaximized,
+      maximizedPaneId,
+      handleCloseTabsToLeft,
+      handleCloseTabsToRight,
+      handleCloseOtherTabs,
+    ],
+  );
+  const createNewTab = useCallback(() => onCreateNewTab({ paneId }), [onCreateNewTab, paneId]);
+  useWorkspaceNewTabKeyboardAction({
+    handlerName: "workspace-chrome-new-tab",
+    ownsKeyboardShortcuts: isFocused && isWorkspaceFocused,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId,
+    createNewTab,
+  });
+  const compactHeader = useMemo(
+    () =>
+      ownsWorkspaceHeader ? (
+        <WindowChromeSafeArea placement="inline">
+          <TitlebarDragRegion />
+          {renderCompactHeader({
+            tabs: paneTabs,
+            activeTabKey: activeTabDescriptor?.key ?? "",
+            actions: compactHeaderActions,
+          })}
+        </WindowChromeSafeArea>
+      ) : null,
+    [
+      ownsWorkspaceHeader,
+      renderCompactHeader,
+      paneTabs,
+      activeTabDescriptor?.key,
+      compactHeaderActions,
+    ],
+  );
   return (
     <RenderProfile id={`SplitPaneView:${pane.id}`}>
       <View
@@ -709,43 +828,49 @@ const SplitPaneView = memo(function SplitPaneView({
         style={styles.pane}
         testID={`workspace-pane-${pane.id}`}
       >
-        <WindowChromeSafeArea placement="inline" style={styles.paneTabs}>
-          <TitlebarDragRegion />
-          <WorkspaceDesktopTabsRow
-            paneId={pane.id}
-            isFocused={isFocused && isWorkspaceFocused}
-            tabs={desktopTabRowItems}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            setHoveredCloseTabKey={setHoveredCloseTabKey}
-            onNavigateTab={onNavigateTab}
-            onCloseTab={onCloseTab}
-            onCopyResumeCommand={onCopyResumeCommand}
-            onCopyAgentId={onCopyAgentId}
-            onCopyTerminalId={onCopyTerminalId}
-            onCopyFilePath={onCopyFilePath}
-            onReloadAgent={onReloadAgent}
-            onRenameTab={onRenameTab}
-            onCloseTabsToLeft={handleCloseTabsToLeft}
-            onCloseTabsToRight={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-            onCreateNewTab={onCreateNewTab}
-            onReorderTabs={handleReorderTabs}
-            externalDndContext
-            activeDragTabId={activeDragTabId}
-            tabDropPreviewIndex={
-              tabDropPreview?.paneId === pane.id ? tabDropPreview.indicatorIndex : null
-            }
-            showPaneSplitActions={!focusModeEnabled}
-            showPaneMaximizeAction={workspaceHasMultiplePanes && !focusModeEnabled}
-            paneMaximized={paneId === maximizedPaneId}
-            onTogglePaneMaximized={handleTogglePaneMaximized}
-            onSplitRight={handleSplitRight}
-            onSplitDown={handleSplitDown}
-            focusModeEnabled={Boolean(focusModeEnabled)}
-            onExitFocusMode={onExitFocusMode}
-          />
-        </WindowChromeSafeArea>
+        <AdaptiveWorkspaceChrome compactHeader={compactHeader}>
+          {ownsWorkspaceHeader ? renderMainHeader?.() : null}
+          <WindowChromeRegion corners={focusModeEnabled ? "both" : "none"}>
+            <WindowChromeSafeArea placement="inline" style={styles.paneTabs}>
+              <TitlebarDragRegion />
+              <WorkspaceDesktopTabsRow
+                paneId={pane.id}
+                isFocused={isFocused && isWorkspaceFocused}
+                tabs={desktopTabRowItems}
+                normalizedServerId={normalizedServerId}
+                normalizedWorkspaceId={normalizedWorkspaceId}
+                setHoveredCloseTabKey={setHoveredCloseTabKey}
+                onNavigateTab={onNavigateTab}
+                onCloseTab={onCloseTab}
+                onCopyResumeCommand={onCopyResumeCommand}
+                onCopyAgentId={onCopyAgentId}
+                onCopyTerminalId={onCopyTerminalId}
+                onCopyFilePath={onCopyFilePath}
+                onReloadAgent={onReloadAgent}
+                onRenameTab={onRenameTab}
+                onCloseTabsToLeft={handleCloseTabsToLeft}
+                onCloseTabsToRight={handleCloseTabsToRight}
+                onCloseOtherTabs={handleCloseOtherTabs}
+                onCreateNewTab={onCreateNewTab}
+                onReorderTabs={handleReorderTabs}
+                ownsKeyboardShortcuts={false}
+                externalDndContext
+                activeDragTabId={activeDragTabId}
+                tabDropPreviewIndex={
+                  tabDropPreview?.paneId === pane.id ? tabDropPreview.indicatorIndex : null
+                }
+                showPaneSplitActions={!focusModeEnabled}
+                showPaneMaximizeAction={workspaceHasMultiplePanes && !focusModeEnabled}
+                paneMaximized={paneId === maximizedPaneId}
+                onTogglePaneMaximized={handleTogglePaneMaximized}
+                onSplitRight={handleSplitRight}
+                onSplitDown={handleSplitDown}
+                focusModeEnabled={Boolean(focusModeEnabled)}
+                onExitFocusMode={onExitFocusMode}
+              />
+            </WindowChromeSafeArea>
+          </WindowChromeRegion>
+        </AdaptiveWorkspaceChrome>
 
         <View style={styles.paneContent}>
           <WorkspacePanelHost
diff --git a/packages/app/src/components/terminal-emulator-contract.ts b/packages/app/src/components/terminal-emulator-contract.ts
index 12638161a1..b4e3dd93e1 100644
--- a/packages/app/src/components/terminal-emulator-contract.ts
+++ b/packages/app/src/components/terminal-emulator-contract.ts
@@ -12,6 +12,7 @@ import type {
 } from "../terminal/local-links/terminal-local-link-provider";
 import type { TerminalClipboardWriter } from "../terminal/native-renderer/terminal-selection";
 import type { TerminalFile } from "../terminal/file-paste";
+import type { TerminalCharacterWidths } from "../terminal/character-widths";
 import type { PendingTerminalModifiers } from "../utils/terminal-keys";
 import type { TerminalRendererReadyChange } from "../utils/terminal-renderer-readiness";
 
@@ -32,6 +33,7 @@ export interface TerminalEmulatorProps {
   ref: Ref<TerminalEmulatorHandle>;
   streamKey: string;
   supportsTerminalInputModeReplay: boolean;
+  characterWidths: TerminalCharacterWidths;
   testId?: string;
   xtermTheme?: ITheme;
   scrollbackLines: number;
diff --git a/packages/app/src/components/terminal-emulator-native-grid.native.tsx b/packages/app/src/components/terminal-emulator-native-grid.native.tsx
index d2b92b213a..ad71316f3c 100644
--- a/packages/app/src/components/terminal-emulator-native-grid.native.tsx
+++ b/packages/app/src/components/terminal-emulator-native-grid.native.tsx
@@ -93,6 +93,7 @@ function NativeTerminalEmulator({
   testId = "terminal-surface",
   xtermTheme = DEFAULT_XTERM_THEME,
   scrollbackLines,
+  characterWidths,
   fontFamily,
   fontSize,
   keyboardInset = 0,
@@ -373,6 +374,7 @@ function NativeTerminalEmulator({
       rows: size.rows,
       cols: size.cols,
       scrollbackLines,
+      characterWidths,
     });
     terminalRef.current = terminal;
     screenModelRef.current = createNativeTerminalScreenModel({ terminal });
@@ -387,6 +389,7 @@ function NativeTerminalEmulator({
     resetInputModeTracker,
     resolveTerminalScreen,
     scrollbackLines,
+    characterWidths,
     clearSelection,
   ]);
 
diff --git a/packages/app/src/components/terminal-emulator.tsx b/packages/app/src/components/terminal-emulator.tsx
index fa6ac9faba..7504843c54 100644
--- a/packages/app/src/components/terminal-emulator.tsx
+++ b/packages/app/src/components/terminal-emulator.tsx
@@ -27,6 +27,7 @@ import {
 } from "../terminal/runtime/terminal-emulator-runtime";
 import { encodeTerminalPaste } from "../terminal/runtime/terminal-paste";
 import type { TerminalFile } from "../terminal/file-paste";
+import type { TerminalCharacterWidths } from "../terminal/character-widths";
 import type {
   TerminalLocalFileLinkSource,
   TerminalLocalFileLinkTarget,
@@ -96,6 +97,7 @@ interface TerminalEmulatorProps {
   ref: Ref<TerminalEmulatorHandle>;
   streamKey: string;
   supportsTerminalInputModeReplay: boolean;
+  characterWidths: TerminalCharacterWidths;
   testId?: string;
   xtermTheme?: ITheme;
   scrollbackLines: number;
@@ -154,6 +156,7 @@ export default function TerminalEmulator({
     cursor: "#e6e6e6",
   },
   scrollbackLines,
+  characterWidths,
   fontFamily,
   fontSize,
   swipeGesturesEnabled = false,
@@ -183,6 +186,8 @@ export default function TerminalEmulator({
   const fontSizeRef = useRef(fontSize);
   const scrollbackLinesRef = useRef(scrollbackLines);
   scrollbackLinesRef.current = scrollbackLines;
+  const characterWidthsRef = useRef(characterWidths);
+  characterWidthsRef.current = characterWidths;
   fontFamilyRef.current = fontFamily;
   fontSizeRef.current = fontSize;
   const themeKey = useMemo(() => buildXtermThemeKey(xtermTheme), [xtermTheme]);
@@ -315,6 +320,10 @@ export default function TerminalEmulator({
     runtimeRef.current?.setScrollback({ lines: scrollbackLines });
   }, [scrollbackLines]);
 
+  useEffect(() => {
+    runtimeRef.current?.setCharacterWidths({ widths: characterWidths });
+  }, [characterWidths]);
+
   useEffect(() => {
     const root = rootRef.current;
     if (!root || !swipeGesturesEnabled) {
@@ -447,6 +456,7 @@ export default function TerminalEmulator({
       },
     });
     runtime.setPendingModifiers({ pendingModifiers: pendingModifiersRef.current });
+    runtime.setCharacterWidths({ widths: characterWidthsRef.current });
     runtime.mount({
       root,
       host,
diff --git a/packages/app/src/components/terminal-pane.tsx b/packages/app/src/components/terminal-pane.tsx
index d60556e0fa..a841d70fa6 100644
--- a/packages/app/src/components/terminal-pane.tsx
+++ b/packages/app/src/components/terminal-pane.tsx
@@ -1,5 +1,6 @@
 import { TerminalFind, type TerminalPaneFindHandle } from "@/terminal/find";
 import type { TerminalFindResult } from "@/terminal/runtime/terminal-emulator-runtime";
+import type { TerminalCharacterWidths } from "@/terminal/character-widths";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -83,6 +84,7 @@ import {
 } from "./terminal-resize-debouncer";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
+import { useKeyboardFocusSurface } from "@/keyboard";
 import {
   applyTerminalRendererReadyChange,
   resolveTerminalStreamTarget,
@@ -304,6 +306,11 @@ export function TerminalPane({
   const supportsTerminalSizeOwnership = useSessionStore(
     (state) => state.sessions[serverId]?.serverInfo?.features?.["terminal-size-ownership"] === true,
   );
+  const characterWidths: TerminalCharacterWidths = useSessionStore((state) =>
+    state.sessions[serverId]?.serverInfo?.features?.["terminal-grapheme-widths"] === true
+      ? "graphemes"
+      : "legacy",
+  );
   const setFocusedTerminalId = useSessionStore((state) => state.setFocusedTerminalId);
 
   const scopeKey = useMemo(() => terminalScopeKey({ serverId, cwd }), [serverId, cwd]);
@@ -452,6 +459,8 @@ export function TerminalPane({
     }
   }, [isMobile, isPaneFocused, isWorkspaceFocused, requestTerminalFocus, scopeKey, terminalId]);
 
+  useKeyboardFocusSurface("terminal", isTerminalPresented && isPaneFocused && terminalId != null);
+
   useEffect(() => {
     const canRequest = canRequestFocusClaim({
       isWorkspaceFocused: isTerminalPresented,
@@ -1171,6 +1180,7 @@ export function TerminalPane({
             dom={TERMINAL_EMULATOR_DOM_PROPS}
             streamKey={terminalStreamKey}
             supportsTerminalInputModeReplay={supportsTerminalInputModeReplay}
+            characterWidths={characterWidths}
             testId="terminal-surface"
             xtermTheme={xtermTheme}
             scrollbackLines={settings.terminalScrollbackLines}
diff --git a/packages/app/src/components/toast-host.tsx b/packages/app/src/components/toast-host.tsx
index d9c8001f50..7be8273a79 100644
--- a/packages/app/src/components/toast-host.tsx
+++ b/packages/app/src/components/toast-host.tsx
@@ -1,13 +1,10 @@
+import {
+  FloatingHeaderOverlay,
+  useFloatingHeaderOverlayClearance,
+} from "@/components/floating-header";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { createPortal } from "react-dom";
-import {
-  Platform,
-  Pressable,
-  StyleSheet as NativeStyleSheet,
-  Text,
-  ToastAndroid,
-  View,
-} from "react-native";
+import { Platform, StyleSheet as NativeStyleSheet, Text, ToastAndroid, View } from "react-native";
 import Animated, { FadeIn, FadeOut } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
@@ -31,6 +28,8 @@ export interface ToastShowOptions {
   durationMs?: number | null;
   nativeAndroid?: boolean;
   testID?: string;
+  /** Runs once when this toast leaves the screen: timed out, dismissed, or replaced. */
+  onDismiss?: () => void;
 }
 
 export interface ToastState {
@@ -41,6 +40,7 @@ export interface ToastState {
   variant: ToastVariant;
   durationMs: number | null;
   testID?: string;
+  onDismiss?: () => void;
 }
 
 /** Dismisses the toast it was returned for; a no-op once another toast replaced it. */
@@ -52,7 +52,7 @@ export interface ToastApi {
   error: (message: string) => void;
 }
 
-type ToastViewportPlacement = "app-shell" | "panel";
+type ToastViewportPlacement = "app-shell" | "panel" | "sidebar";
 
 const DEFAULT_DURATION_MS = 2200;
 const noopDismiss: DismissToast = () => {};
@@ -74,40 +74,56 @@ export function useToastHost(): {
   dismiss: () => void;
 } {
   const { t } = useTranslation();
-  const [toast, setToast] = useState<ToastState | null>(null);
+  const [toast, setToastState] = useState<ToastState | null>(null);
+  const toastRef = useRef<ToastState | null>(null);
   const idRef = useRef(0);
 
-  const show = useCallback((content: ReactNode, options?: ToastShowOptions): DismissToast => {
-    const nativeMessage = typeof content === "string" ? content.trim() : null;
-    if (!content || nativeMessage === "") {
-      return noopDismiss;
-    }
-
-    const variant = options?.variant ?? "default";
-    const durationMs = options?.durationMs === undefined ? DEFAULT_DURATION_MS : options.durationMs;
-    const nativeAndroid = options?.nativeAndroid ?? false;
-
-    if (Platform.OS === "android" && nativeAndroid && nativeMessage) {
-      const duration =
-        durationMs !== null && durationMs <= 2500 ? ToastAndroid.SHORT : ToastAndroid.LONG;
-      ToastAndroid.showWithGravity(nativeMessage, duration, ToastAndroid.TOP);
-      return noopDismiss;
-    }
-
-    idRef.current += 1;
-    const id = idRef.current;
-    setToast({
-      id,
-      content,
-      nativeMessage,
-      icon: options?.icon,
-      variant,
-      durationMs,
-      testID: options?.testID,
-    });
-    return () => setToast((current) => (current?.id === id ? null : current));
+  const setToast = useCallback((next: ToastState | null) => {
+    const previous = toastRef.current;
+    if (previous === next) return;
+    toastRef.current = next;
+    setToastState(next);
+    previous?.onDismiss?.();
   }, []);
 
+  const show = useCallback(
+    (content: ReactNode, options?: ToastShowOptions): DismissToast => {
+      const nativeMessage = typeof content === "string" ? content.trim() : null;
+      if (!content || nativeMessage === "") {
+        return noopDismiss;
+      }
+
+      const variant = options?.variant ?? "default";
+      const durationMs =
+        options?.durationMs === undefined ? DEFAULT_DURATION_MS : options.durationMs;
+      const nativeAndroid = options?.nativeAndroid ?? false;
+
+      if (Platform.OS === "android" && nativeAndroid && nativeMessage) {
+        const duration =
+          durationMs !== null && durationMs <= 2500 ? ToastAndroid.SHORT : ToastAndroid.LONG;
+        ToastAndroid.showWithGravity(nativeMessage, duration, ToastAndroid.TOP);
+        return noopDismiss;
+      }
+
+      idRef.current += 1;
+      const id = idRef.current;
+      setToast({
+        id,
+        content,
+        nativeMessage,
+        icon: options?.icon,
+        variant,
+        durationMs,
+        testID: options?.testID,
+        onDismiss: options?.onDismiss,
+      });
+      return () => {
+        if (toastRef.current?.id === id) setToast(null);
+      };
+    },
+    [setToast],
+  );
+
   const api = useMemo<ToastApi>(
     () => ({
       show,
@@ -123,7 +139,7 @@ export function useToastHost(): {
 
   const dismiss = useCallback(() => {
     setToast(null);
-  }, []);
+  }, [setToast]);
 
   return { api, toast, dismiss };
 }
@@ -190,17 +206,25 @@ export function ToastViewport({
     return clearTimer;
   }, [clearTimer, durationMs, scheduleDismiss, toastId]);
 
+  const panelClearance = useFloatingHeaderOverlayClearance();
   const headerHeight = isMobile ? HEADER_INNER_HEIGHT_MOBILE : HEADER_INNER_HEIGHT;
   const headerTopPadding = isMobile ? HEADER_TOP_PADDING_MOBILE : 0;
-  const topOffset = placement === "app-shell" ? insets.top + headerTopPadding + headerHeight : 0;
+  const topOffset =
+    placement === "app-shell" ? insets.top + headerTopPadding + headerHeight : panelClearance;
 
   const content = (
     <View
-      style={styles.container(placement, topOffset)}
+      style={
+        placement === "sidebar" ? styles.sidebarContainer : styles.container(placement, topOffset)
+      }
       pointerEvents="box-none"
       collapsable={false}
     >
-      <View style={styles.widthBoundary} pointerEvents="box-none" collapsable={false}>
+      <View
+        style={placement === "sidebar" ? styles.sidebarWidthBoundary : styles.widthBoundary}
+        pointerEvents="box-none"
+        collapsable={false}
+      >
         {toast ? (
           <Animated.View
             entering={toastEntering}
@@ -209,7 +233,7 @@ export function ToastViewport({
             testID={toast.testID ?? "app-toast"}
             accessibilityRole="alert"
           >
-            <ToastCard toast={toast} onHoverIn={pauseDismiss} onHoverOut={resumeDismiss} />
+            <ToastCard toast={toast} onPointerEnter={pauseDismiss} onPointerLeave={resumeDismiss} />
           </Animated.View>
         ) : null}
       </View>
@@ -220,17 +244,17 @@ export function ToastViewport({
     return createPortal(content, getOverlayRoot());
   }
 
-  return content;
+  return placement === "panel" ? <FloatingHeaderOverlay>{content}</FloatingHeaderOverlay> : content;
 }
 
 function ToastCard({
   toast,
-  onHoverIn,
-  onHoverOut,
+  onPointerEnter,
+  onPointerLeave,
 }: {
   toast: ToastState;
-  onHoverIn: () => void;
-  onHoverOut: () => void;
+  onPointerEnter: () => void;
+  onPointerLeave: () => void;
 }) {
   let defaultIcon: ReactNode = null;
   if (toast.variant === "info") {
@@ -245,10 +269,9 @@ function ToastCard({
   const icon = toast.icon ?? defaultIcon;
 
   return (
-    <Pressable
-      accessible={false}
-      onHoverIn={onHoverIn}
-      onHoverOut={onHoverOut}
+    <View
+      onPointerEnter={onPointerEnter}
+      onPointerLeave={onPointerLeave}
       style={[
         styles.toast,
         toast.variant === "info" ? styles.toastInfo : null,
@@ -266,7 +289,7 @@ function ToastCard({
           {toast.content}
         </View>
       )}
-    </Pressable>
+    </View>
   );
 }
 
@@ -275,7 +298,7 @@ const animatedStyles = NativeStyleSheet.create({
 });
 
 const styles = StyleSheet.create((theme) => ({
-  container: (placement: ToastViewportPlacement, topOffset: number) => ({
+  container: (placement: Exclude<ToastViewportPlacement, "sidebar">, topOffset: number) => ({
     position: "absolute",
     left: theme.spacing[4],
     right: theme.spacing[4],
@@ -283,11 +306,23 @@ const styles = StyleSheet.create((theme) => ({
     zIndex: OVERLAY_Z.toast,
     alignItems: "center",
   }),
+  sidebarContainer: {
+    position: "absolute",
+    left: theme.spacing[2],
+    right: theme.spacing[2],
+    bottom: theme.spacing[2],
+    zIndex: OVERLAY_Z.toast,
+    alignItems: "center",
+  },
   widthBoundary: {
     width: "92%",
     maxWidth: TOAST_MAX_WIDTH,
     alignItems: "center",
   },
+  sidebarWidthBoundary: {
+    width: "100%",
+    alignItems: "center",
+  },
   toast: {
     alignSelf: "center",
     maxWidth: "100%",
diff --git a/packages/app/src/components/ui/alert.tsx b/packages/app/src/components/ui/alert.tsx
index fe9fa3ce4b..c81b30a056 100644
--- a/packages/app/src/components/ui/alert.tsx
+++ b/packages/app/src/components/ui/alert.tsx
@@ -3,14 +3,14 @@ import { type ReactNode, useMemo } from "react";
 import { Text, View } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import {
-  type ButtonControlSize,
-  buttonIconSize,
+  ALERT_ICON_SIZE,
+  type AlertSize,
   createControlGeometry,
 } from "@/components/ui/control-geometry";
 import { hexColorWithAlpha } from "@/utils/color";
 
 export type AlertVariant = "default" | "info" | "success" | "warning" | "error";
-export type AlertSize = ButtonControlSize;
+export type { AlertSize };
 
 export interface AlertProps {
   title?: string;
@@ -46,7 +46,7 @@ export function Alert({
   const sized = resolveSizeStyles(size);
   const containerStyle = [styles.container, sized.container, { borderColor }];
   const titleStyle = [styles.title, sized.text, accentColor ? { color: accentColor } : null];
-  const iconSize = buttonIconSize[size];
+  const iconSize = ALERT_ICON_SIZE[size];
 
   const resolvedIcon = useMemo(() => {
     if (variant === "default") return null;
diff --git a/packages/app/src/components/ui/anchor.test.ts b/packages/app/src/components/ui/anchor.test.ts
index cb18a86271..47ccda888c 100644
--- a/packages/app/src/components/ui/anchor.test.ts
+++ b/packages/app/src/components/ui/anchor.test.ts
@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, getTransformOrigin, type Rect } from "./anchor";
+import {
+  computePosition,
+  fitSurfaceWidth,
+  getTransformOrigin,
+  holdSurfaceEdge,
+  surfaceFrameStyles,
+  type Rect,
+} from "./anchor";
 
 const DISPLAY: Rect = { x: 0, y: 0, width: 1000, height: 800 };
 const TRIGGER: Rect = { x: 100, y: 100, width: 40, height: 20 };
@@ -78,6 +85,46 @@ describe("computePosition", () => {
   });
 });
 
+/**
+ * Where a surface's edges land when its content has resized but it has not been placed again,
+ * the frame native paints before the next placement arrives. Resolves the frame styles the way
+ * layout does: a top-held surface grows down from its top, a bottom-held one up from the
+ * holder's bottom.
+ */
+function edgesBeforeReplacement(placedHeight: number, paintedHeight: number) {
+  const placed = position({ placement: "top", triggerRect: { ...TRIGGER, y: 400 } });
+  const { holder, surface } = surfaceFrameStyles(holdSurfaceEdge(placed, placedHeight));
+  const bottom =
+    typeof surface.bottom === "number"
+      ? Number(holder.height) - surface.bottom
+      : Number(surface.top) + paintedHeight;
+  return { top: bottom - paintedHeight, bottom };
+}
+
+describe("surfaceFrameStyles", () => {
+  it("keeps a surface above its trigger off the trigger when its content grows", () => {
+    // Trigger top 400, offset 4: the surface ends at 396 however tall it becomes.
+    expect(edgesBeforeReplacement(CONTENT.height, CONTENT.height)).toEqual({
+      top: 296,
+      bottom: 396,
+    });
+    expect(edgesBeforeReplacement(CONTENT.height, 260)).toEqual({ top: 136, bottom: 396 });
+  });
+
+  it("keeps a surface above its trigger against the trigger when its content shrinks", () => {
+    expect(edgesBeforeReplacement(CONTENT.height, 40)).toEqual({ top: 356, bottom: 396 });
+  });
+
+  it("holds a surface below its trigger by its top edge", () => {
+    const { surface } = surfaceFrameStyles(holdSurfaceEdge(position(), CONTENT.height));
+    expect(surface).toMatchObject({ position: "absolute", top: 124, left: 100 });
+  });
+
+  it("waits off-screen until it is placed", () => {
+    expect(surfaceFrameStyles(null).surface).toMatchObject({ top: -9999, left: -9999 });
+  });
+});
+
 describe("getTransformOrigin", () => {
   it.each([
     ["bottom", "start", [0, 0, 0]],
@@ -97,3 +144,26 @@ describe("getTransformOrigin", () => {
     expect(getTransformOrigin(placement, alignment)).toEqual(expected);
   });
 });
+
+describe("fitSurfaceWidth", () => {
+  it("leaves a surface that fits the display alone, capped at the display", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180 }, 1000)).toEqual({
+      width: 240,
+      minWidth: 180,
+      maxWidth: 984,
+    });
+  });
+
+  it("shrinks a surface wider than a narrow display to the space inside its edge padding", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180, maxWidth: 320 }, 220)).toEqual({
+      width: 204,
+      minWidth: 180,
+      maxWidth: 204,
+    });
+    expect(fitSurfaceWidth({ minWidth: 180 }, 150)).toEqual({
+      width: undefined,
+      minWidth: 134,
+      maxWidth: 134,
+    });
+  });
+});
diff --git a/packages/app/src/components/ui/anchor.ts b/packages/app/src/components/ui/anchor.ts
index 51454a9ee5..f263df8ab7 100644
--- a/packages/app/src/components/ui/anchor.ts
+++ b/packages/app/src/components/ui/anchor.ts
@@ -1,8 +1,8 @@
-import type { View } from "react-native";
+import type { View, ViewStyle } from "react-native";
 
 /**
- * Where a floating surface goes relative to the thing that opened it. Menus and hover cards
- * place themselves with it.
+ * Where a floating surface goes relative to the thing that opened it. Menus, hover cards, and
+ * tooltips place themselves with it.
  */
 
 export type Placement = "top" | "bottom" | "left" | "right";
@@ -120,6 +120,27 @@ function clampToDisplayArea(input: {
   };
 }
 
+export interface SurfaceWidth {
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+/**
+ * Caps a surface's requested width to the display. Position clamping can move a surface but not
+ * shrink it, so a menu wider than a narrow screen would otherwise hang off the far edge.
+ */
+export function fitSurfaceWidth(requested: SurfaceWidth, displayWidth: number): SurfaceWidth {
+  const available = Math.max(displayWidth - EDGE_PADDING * 2, 0);
+  const cap = (value: number | undefined) =>
+    typeof value === "number" ? Math.min(value, available) : undefined;
+  return {
+    width: cap(requested.width),
+    minWidth: cap(requested.minWidth),
+    maxWidth: cap(requested.maxWidth) ?? available,
+  };
+}
+
 export function computePosition({
   triggerRect,
   contentSize,
@@ -156,6 +177,55 @@ export function computePosition({
   return { ...clampToDisplayArea({ ...anchored, contentSize, displayArea }), actualPlacement };
 }
 
+/** Where a placed surface sits: its left edge, and the edge that holds it vertically. */
+export type SurfacePosition = { left: number; top: number } | { left: number; bottomEdge: number };
+
+/**
+ * A surface above its trigger is held by its bottom edge, the edge that faces the trigger. When
+ * its content grows after it paints, it extends upward, away from the trigger. Held by its top,
+ * it would paint over the trigger until the next placement lands, a frame later on native.
+ */
+export function holdSurfaceEdge(
+  placed: { x: number; y: number; actualPlacement: Placement },
+  contentHeight: number,
+): SurfacePosition {
+  if (placed.actualPlacement === "top") {
+    return { left: placed.x, bottomEdge: placed.y + contentHeight };
+  }
+  return { left: placed.x, top: placed.y };
+}
+
+/**
+ * Styles for a surface and the holder it sits in. Both fill the display area's width, so the
+ * surface lays out exactly as it would without the holder. Render the holder with the
+ * `pointerEvents="box-none"` prop so presses outside the surface reach what is behind it;
+ * react-native-web drops `box-none` given as an inline style. A bottom-held surface sits on the
+ * bottom of a holder that ends at its bottom edge, so layout keeps that edge in place however
+ * the content changes. Until it is placed, the surface waits off-screen to be measured.
+ */
+export function surfaceFrameStyles(position: SurfacePosition | null): {
+  holder: ViewStyle;
+  surface: ViewStyle;
+} {
+  const fill: ViewStyle = { position: "absolute", top: 0, left: 0, right: 0 };
+  if (!position) {
+    return {
+      holder: { ...fill, bottom: 0 },
+      surface: { position: "absolute", top: -9999, left: -9999 },
+    };
+  }
+  if ("top" in position) {
+    return {
+      holder: { ...fill, bottom: 0 },
+      surface: { position: "absolute", top: position.top, left: position.left },
+    };
+  }
+  return {
+    holder: { ...fill, height: position.bottomEdge },
+    surface: { position: "absolute", bottom: 0, left: position.left },
+  };
+}
+
 export function getTransformOrigin(
   placement: Placement,
   alignment: Alignment,
diff --git a/packages/app/src/components/ui/autocomplete-popover.tsx b/packages/app/src/components/ui/autocomplete-popover.tsx
index e74c068658..c4229775bf 100644
--- a/packages/app/src/components/ui/autocomplete-popover.tsx
+++ b/packages/app/src/components/ui/autocomplete-popover.tsx
@@ -12,7 +12,11 @@ import { Portal } from "@gorhom/portal";
 import Animated, { useAnimatedReaction, useAnimatedStyle } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { Autocomplete, type AutocompleteOption } from "@/components/ui/autocomplete";
+import {
+  Autocomplete,
+  type AutocompleteOption,
+  type AutocompleteStatus,
+} from "@/components/ui/autocomplete";
 import {
   measureFloatingPanelPortalHost,
   useFloatingPanelPortalHostName,
@@ -37,10 +41,7 @@ interface AutocompletePopoverProps {
   options: readonly AutocompleteOption[];
   selectedIndex: number;
   onSelect: (option: AutocompleteOption) => void;
-  isLoading?: boolean;
-  errorMessage?: string;
-  loadingText?: string;
-  emptyText?: string;
+  status?: AutocompleteStatus | null;
 }
 
 export function AutocompletePopover({
@@ -50,10 +51,7 @@ export function AutocompletePopover({
   options,
   selectedIndex,
   onSelect,
-  isLoading,
-  errorMessage,
-  loadingText,
-  emptyText,
+  status,
 }: AutocompletePopoverProps): ReactElement | null {
   "use no memo";
   // React Compiler memoizes effect captures by reading SharedValue.value during render.
@@ -154,10 +152,7 @@ export function AutocompletePopover({
                 options={options}
                 selectedIndex={selectedIndex}
                 onSelect={onSelect}
-                isLoading={isLoading}
-                errorMessage={errorMessage}
-                loadingText={loadingText}
-                emptyText={emptyText}
+                status={status}
               />
             </Animated.View>
           </KeyboardTranslateView>
diff --git a/packages/app/src/components/ui/autocomplete.tsx b/packages/app/src/components/ui/autocomplete.tsx
index a9cb10f33e..86d62ba2b1 100644
--- a/packages/app/src/components/ui/autocomplete.tsx
+++ b/packages/app/src/components/ui/autocomplete.tsx
@@ -9,32 +9,79 @@ import {
   type NativeSyntheticEvent,
   type PressableStateCallbackType,
 } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
-import { File, Folder } from "lucide-react-native";
+import {
+  Archive,
+  CircleAlert,
+  File,
+  Folder,
+  Puzzle,
+  RotateCw,
+  Sparkles,
+  SquarePen,
+  SquareSlash,
+} from "lucide-react-native";
+import type { MatchRange } from "@getpaseo/protocol/search/text-match";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import type { Theme } from "@/styles/theme";
+import { Button } from "./button";
+import { HighlightedText } from "./highlighted-text";
+import { mutedIconColorMapping } from "./icon-color";
+import { LoadingSpinner } from "./loading-spinner";
 import { getScrollOffsetToRevealItem } from "./scroll-reveal";
+import { StatusBadge } from "./status-badge";
+
+export type AutocompleteOptionIcon =
+  | "command"
+  | "skill"
+  | "plugin"
+  | "archive"
+  | "new-draft"
+  | "file"
+  | "directory";
 
 export interface AutocompleteOption {
   id: string;
   label: string;
-  detail?: string;
+  icon: AutocompleteOptionIcon;
+  /** Spans of `label` the query matched. */
+  labelMatches?: readonly MatchRange[];
+  argumentHint?: string;
   description?: string;
-  kind?: "command" | "file" | "directory";
+  /** Where the option comes from, when that is not the provider itself: `Skill`, `Paseo`, a plugin. */
+  tag?: string;
 }
 
+/** What the list shows in place of options. */
+export type AutocompleteStatus =
+  | { kind: "loading"; message: string }
+  | { kind: "empty"; message: string }
+  | { kind: "error"; title: string; reason?: string; onRetry?: () => void };
+
 interface AutocompleteProps {
   options: readonly AutocompleteOption[];
   selectedIndex: number;
   onSelect: (option: AutocompleteOption) => void;
-  isLoading?: boolean;
-  errorMessage?: string;
-  loadingText?: string;
-  emptyText?: string;
+  status?: AutocompleteStatus | null;
   maxHeight?: number;
 }
 
-const BOLT_GLYPH_PATTERN = /\u26A1|\uFE0F/gu;
+const ROW_ICONS = {
+  command: withUnistyles(SquareSlash, mutedIconColorMapping),
+  skill: withUnistyles(Sparkles, mutedIconColorMapping),
+  plugin: withUnistyles(Puzzle, mutedIconColorMapping),
+  archive: withUnistyles(Archive, mutedIconColorMapping),
+  "new-draft": withUnistyles(SquarePen, mutedIconColorMapping),
+  file: withUnistyles(File, mutedIconColorMapping),
+  directory: withUnistyles(Folder, mutedIconColorMapping),
+} satisfies Record<AutocompleteOptionIcon, unknown>;
+const ErrorIcon = withUnistyles(CircleAlert, mutedIconColorMapping);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner, mutedIconColorMapping);
+
+const ROW_ICON_SIZE = 14;
+
+const BOLT_GLYPH_PATTERN = /⚡|️/gu;
 
 function removeBoltGlyphs(value?: string): string | undefined {
   if (!value) {
@@ -48,7 +95,7 @@ interface AutocompleteRowProps {
   index: number;
   option: AutocompleteOption;
   isSelected: boolean;
-  mutedColor: string;
+  showArgumentHint: boolean;
   onSelect: (option: AutocompleteOption) => void;
   onRowLayout: (index: number, event: LayoutChangeEvent) => void;
 }
@@ -57,13 +104,15 @@ function AutocompleteRow({
   index,
   option,
   isSelected,
-  mutedColor,
+  showArgumentHint,
   onSelect,
   onRowLayout,
 }: AutocompleteRowProps) {
-  const optionLabel = removeBoltGlyphs(option.label) ?? option.label;
-  const optionDescription = removeBoltGlyphs(option.description);
-  const isFileOrDir = option.kind === "directory" || option.kind === "file";
+  const label = removeBoltGlyphs(option.label) ?? option.label;
+  const description = removeBoltGlyphs(option.description);
+  const argumentHint = showArgumentHint ? removeBoltGlyphs(option.argumentHint) : undefined;
+  const Icon = ROW_ICONS[option.icon];
+  const labelMatches = label === option.label ? option.labelMatches : undefined;
 
   const handleLayout = useCallback(
     (event: LayoutChangeEvent) => onRowLayout(index, event),
@@ -79,41 +128,77 @@ function AutocompleteRow({
   );
 
   return (
-    <Pressable onLayout={handleLayout} onPress={handlePress} style={pressableStyle}>
-      {isFileOrDir ? (
-        <>
-          <View style={styles.itemLeading}>
-            {option.kind === "directory" ? (
-              <Folder size={14} color={mutedColor} />
-            ) : (
-              <File size={14} color={mutedColor} />
-            )}
-          </View>
-          <View style={styles.itemMain}>
-            <View style={styles.itemHeader}>
-              <Text style={styles.itemLabel}>{optionLabel}</Text>
-              {removeBoltGlyphs(option.detail) ? (
-                <Text style={styles.itemDetail}>{removeBoltGlyphs(option.detail)}</Text>
-              ) : null}
-            </View>
-            {optionDescription ? (
-              <Text style={styles.itemDescription} numberOfLines={1}>
-                {optionDescription}
-              </Text>
-            ) : null}
-          </View>
-        </>
-      ) : (
-        <View style={styles.itemMainRow}>
-          <Text style={styles.itemLabel}>{optionLabel}</Text>
-          {optionDescription ? (
-            <Text style={styles.itemDescriptionInline} numberOfLines={1}>
-              {optionDescription}
+    <Pressable
+      onLayout={handleLayout}
+      onPress={handlePress}
+      style={pressableStyle}
+      // Name and description only; the hint and tag repeat what the name implies.
+      accessibilityLabel={description ? `${label}, ${description}` : label}
+    >
+      <View style={styles.itemIcon}>
+        <Icon size={ROW_ICON_SIZE} />
+      </View>
+      <HighlightedText
+        text={label}
+        ranges={labelMatches}
+        style={styles.itemLabel}
+        numberOfLines={1}
+      />
+      {argumentHint ? (
+        <Text style={styles.itemArgumentHint} numberOfLines={1}>
+          {argumentHint}
+        </Text>
+      ) : null}
+      <Text style={styles.itemDescription} numberOfLines={1}>
+        {description ?? ""}
+      </Text>
+      {option.tag ? <StatusBadge label={option.tag} size="xs" /> : null}
+    </Pressable>
+  );
+}
+
+function AutocompleteStatusRow({ status }: { status: AutocompleteStatus }) {
+  const { t } = useTranslation();
+
+  if (status.kind === "error") {
+    return (
+      <View style={styles.statusRow} testID="composer-autocomplete-error">
+        <View style={styles.itemIcon}>
+          <ErrorIcon size={ROW_ICON_SIZE} />
+        </View>
+        <View style={styles.statusText}>
+          <Text style={styles.statusTitle} numberOfLines={2}>
+            {status.title}
+          </Text>
+          {status.reason ? (
+            <Text style={styles.statusReason} numberOfLines={2}>
+              {status.reason}
             </Text>
           ) : null}
         </View>
-      )}
-    </Pressable>
+        {status.onRetry ? (
+          <Button variant="secondary" size="sm" leftIcon={RotateCw} onPress={status.onRetry}>
+            {t("common.actions.retry")}
+          </Button>
+        ) : null}
+      </View>
+    );
+  }
+
+  return (
+    <View
+      style={styles.statusRow}
+      testID={status.kind === "loading" ? "composer-autocomplete-loading" : undefined}
+    >
+      {status.kind === "loading" ? (
+        <View style={styles.itemIcon}>
+          <ThemedLoadingSpinner size={ROW_ICON_SIZE} />
+        </View>
+      ) : null}
+      <Text style={styles.statusMessage} numberOfLines={2}>
+        {status.message}
+      </Text>
+    </View>
   );
 }
 
@@ -121,16 +206,11 @@ export function Autocomplete({
   options,
   selectedIndex,
   onSelect,
-  isLoading = false,
-  errorMessage,
-  loadingText,
-  emptyText,
+  status,
   maxHeight = 220,
 }: AutocompleteProps) {
   const { t } = useTranslation();
-  const { theme } = useUnistyles();
-  const resolvedLoadingText = loadingText ?? t("common.states.loading");
-  const resolvedEmptyText = emptyText ?? t("common.empty.noResults");
+  const isCompact = useIsCompactFormFactor();
   const scrollRef = useRef<ScrollView>(null);
   const rowLayoutsRef = useRef<Map<number, { top: number; height: number }>>(new Map());
   const viewportHeightRef = useRef(0);
@@ -210,117 +290,51 @@ export function Autocomplete({
     [ensureActiveItemVisible],
   );
 
-  const selectedOption = options[selectedIndex];
   const containerStyle = useMemo(() => [styles.container, { maxHeight }], [maxHeight]);
 
-  if (isLoading) {
-    return (
-      <View style={containerStyle}>
-        <View style={styles.emptyItem}>
-          <Text style={styles.emptyText}>{resolvedLoadingText}</Text>
-        </View>
-      </View>
-    );
-  }
+  const noResultsMessage = t("common.empty.noResults");
+  const shownStatus = useMemo<AutocompleteStatus | null>(
+    () => status ?? (options.length === 0 ? { kind: "empty", message: noResultsMessage } : null),
+    [noResultsMessage, options.length, status],
+  );
 
-  if (errorMessage) {
+  if (shownStatus) {
     return (
       <View style={containerStyle}>
-        <View style={styles.emptyItem}>
-          <Text style={styles.emptyText}>Error: {errorMessage}</Text>
-        </View>
-      </View>
-    );
-  }
-
-  if (options.length === 0) {
-    return (
-      <View style={containerStyle}>
-        <View style={styles.emptyItem}>
-          <Text style={styles.emptyText}>{resolvedEmptyText}</Text>
-        </View>
+        <AutocompleteStatusRow status={shownStatus} />
       </View>
     );
   }
 
   return (
-    <View style={styles.outerWrapper}>
-      {selectedOption?.kind === "command" && selectedOption.description ? (
-        <View style={styles.detailCard}>
-          <Text style={styles.detailLabel} numberOfLines={1}>
-            {removeBoltGlyphs(selectedOption.label) ?? selectedOption.label}
-          </Text>
-          <Text style={styles.detailDescription} numberOfLines={2} ellipsizeMode="tail">
-            {removeBoltGlyphs(selectedOption.description)}
-          </Text>
-          {selectedOption.detail ? (
-            <Text style={styles.detailHint} numberOfLines={1}>
-              {removeBoltGlyphs(selectedOption.detail)}
-            </Text>
-          ) : null}
-        </View>
-      ) : null}
-      <View style={containerStyle}>
-        <ScrollView
-          ref={scrollRef}
-          onLayout={handleScrollViewLayout}
-          onContentSizeChange={pinToBottom}
-          onScroll={handleScroll}
-          scrollEventThrottle={16}
-          style={styles.scrollView}
-          contentContainerStyle={styles.scrollContent}
-          keyboardShouldPersistTaps="always"
-        >
-          {options.map((option, index) => (
-            <AutocompleteRow
-              key={option.id}
-              index={index}
-              option={option}
-              isSelected={index === selectedIndex}
-              mutedColor={theme.colors.foregroundMuted}
-              onSelect={onSelect}
-              onRowLayout={handleRowLayout}
-            />
-          ))}
-        </ScrollView>
-      </View>
+    <View style={containerStyle}>
+      <ScrollView
+        ref={scrollRef}
+        onLayout={handleScrollViewLayout}
+        onContentSizeChange={pinToBottom}
+        onScroll={handleScroll}
+        scrollEventThrottle={16}
+        style={styles.scrollView}
+        contentContainerStyle={styles.scrollContent}
+        keyboardShouldPersistTaps="always"
+      >
+        {options.map((option, index) => (
+          <AutocompleteRow
+            key={option.id}
+            index={index}
+            option={option}
+            isSelected={index === selectedIndex}
+            showArgumentHint={!isCompact}
+            onSelect={onSelect}
+            onRowLayout={handleRowLayout}
+          />
+        ))}
+      </ScrollView>
     </View>
   );
 }
 
 const styles = StyleSheet.create((theme: Theme) => ({
-  outerWrapper: {
-    flexShrink: 1,
-    minHeight: 0,
-    gap: theme.spacing[1],
-  },
-  detailCard: {
-    flexShrink: 1,
-    minHeight: 0,
-    overflow: "hidden",
-    backgroundColor: theme.colors.surface1,
-    borderWidth: theme.borderWidth[1],
-    borderColor: theme.colors.borderAccent,
-    borderRadius: theme.borderRadius.lg,
-    paddingHorizontal: theme.spacing[3],
-    paddingVertical: theme.spacing[3],
-    ...theme.shadow.md,
-  },
-  detailLabel: {
-    color: theme.colors.foreground,
-    fontSize: theme.fontSize.base,
-    fontWeight: theme.fontWeight.normal,
-  },
-  detailDescription: {
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.sm,
-    marginTop: theme.spacing[1],
-  },
-  detailHint: {
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.sm,
-    marginTop: theme.spacing[1],
-  },
   container: {
     flexShrink: 1,
     // Keep a complete selectable row (36), list padding (8), and borders (2).
@@ -342,60 +356,63 @@ const styles = StyleSheet.create((theme: Theme) => ({
   item: {
     flexDirection: "row",
     alignItems: "center",
+    gap: theme.spacing[2],
     minHeight: 36,
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
   },
-  itemLeading: {
-    width: 18,
-    alignItems: "center",
-    justifyContent: "center",
-    marginRight: theme.spacing[1],
-  },
   itemActive: {
     backgroundColor: theme.colors.surface2,
   },
-  itemMain: {
-    flex: 1,
-    minWidth: 0,
-  },
-  itemMainRow: {
-    flex: 1,
-    minWidth: 0,
-    flexDirection: "row",
+  itemIcon: {
+    width: 16,
     alignItems: "center",
-    gap: theme.spacing[2],
-  },
-  itemHeader: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: theme.spacing[2],
+    justifyContent: "center",
   },
   itemLabel: {
+    flexShrink: 0,
+    maxWidth: "60%",
     color: theme.colors.foreground,
     fontSize: theme.fontSize.base,
     fontWeight: theme.fontWeight.normal,
   },
-  itemDetail: {
+  itemArgumentHint: {
+    flexShrink: 0,
+    maxWidth: "30%",
     color: theme.colors.foregroundMuted,
+    fontFamily: theme.fontFamily.mono,
     fontSize: theme.fontSize.sm,
   },
   itemDescription: {
+    flex: 1,
+    minWidth: 0,
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.sm,
-    marginTop: 2,
   },
-  itemDescriptionInline: {
+  statusRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+    minHeight: 44,
+    paddingHorizontal: theme.spacing[3],
+    paddingVertical: theme.spacing[2],
+  },
+  statusText: {
+    flex: 1,
+    minWidth: 0,
+    gap: 2,
+  },
+  statusTitle: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.sm,
+  },
+  statusReason: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+  },
+  statusMessage: {
     flex: 1,
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.sm,
   },
-  emptyItem: {
-    paddingHorizontal: theme.spacing[3],
-    paddingVertical: theme.spacing[3],
-  },
-  emptyText: {
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.base,
-  },
 })) as unknown as Record<string, object>;
diff --git a/packages/app/src/components/ui/button.tsx b/packages/app/src/components/ui/button.tsx
index e4a9a13b2b..55e4808b8e 100644
--- a/packages/app/src/components/ui/button.tsx
+++ b/packages/app/src/components/ui/button.tsx
@@ -20,14 +20,13 @@ import type {
 } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import {
-  buttonIconSize,
+  controlIconSize,
   createControlGeometry,
-  type ButtonControlSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
 
 type ButtonVariant = "default" | "secondary" | "outline" | "ghost" | "destructive";
-type ButtonSize = ButtonControlSize;
 
 type LeftIcon =
   | ReactElement
@@ -102,15 +101,11 @@ const styles = StyleSheet.create((theme) => {
     md: {
       ...geometry.buttonMd,
     },
-    xs: {
-      ...geometry.buttonXs,
-    },
     sm: {
       ...geometry.buttonSm,
     },
-    lg: {
-      ...geometry.buttonLg,
-    },
+    iconOnlySm: geometry.buttonIconOnlySm,
+    iconOnlyMd: geometry.buttonIconOnlyMd,
     default: {
       backgroundColor: theme.colors.accent,
       borderColor: theme.colors.accent,
@@ -139,11 +134,11 @@ const styles = StyleSheet.create((theme) => {
     },
     text: {
       color: theme.colors.foreground,
-      ...geometry.buttonText,
-      fontWeight: theme.fontWeight.normal,
+      ...geometry.buttonTextMd,
+      fontWeight: theme.fontWeight.medium,
     },
-    textXs: {
-      ...geometry.buttonTextXs,
+    textSm: {
+      ...geometry.buttonTextSm,
     },
     textDefault: {
       color: theme.colors.accentForeground,
@@ -178,7 +173,7 @@ export function Button({
   Omit<PressableProps, "style"> & {
     ref?: React.Ref<View>;
     variant?: ButtonVariant;
-    size?: ButtonSize;
+    size?: ControlSize;
     leftIcon?: LeftIcon;
     trailing?: ReactNode;
     style?: StyleProp<ViewStyle>;
@@ -205,16 +200,9 @@ export function Button({
     variantStyle = styles.destructive;
   }
 
-  let sizeStyle: ViewStyle;
-  if (size === "xs") {
-    sizeStyle = styles.xs;
-  } else if (size === "sm") {
-    sizeStyle = styles.sm;
-  } else if (size === "lg") {
-    sizeStyle = styles.lg;
-  } else {
-    sizeStyle = styles.md;
-  }
+  const isIconOnly = children == null && leftIcon != null;
+  const sizeStyle = size === "sm" ? styles.sm : styles.md;
+  const iconOnlyStyle = size === "sm" ? styles.iconOnlySm : styles.iconOnlyMd;
   const isGhostHovered = hovered && variant === "ghost";
 
   const handleHoverIn = useCallback(() => setHovered(true), []);
@@ -224,18 +212,19 @@ export function Button({
     ({ pressed }: PressableStateCallbackType): StyleProp<ViewStyle> => [
       styles.base,
       sizeStyle,
+      isIconOnly ? iconOnlyStyle : null,
       variantStyle,
       pressed ? styles.pressed : null,
       isDisabled ? styles.disabled : null,
       style,
     ],
-    [sizeStyle, variantStyle, isDisabled, style],
+    [sizeStyle, isIconOnly, iconOnlyStyle, variantStyle, isDisabled, style],
   );
 
   const resolvedTextStyle = useMemo(
     () => [
       styles.text,
-      size === "xs" ? styles.textXs : null,
+      size === "sm" ? styles.textSm : null,
       variant === "default" ? styles.textDefault : null,
       variant === "destructive" ? styles.textDestructive : null,
       variant === "ghost" ? styles.textGhost : null,
@@ -276,7 +265,7 @@ export function Button({
       <ThemedButtonIcon
         loading={loading}
         leftIcon={leftIcon}
-        iconSize={buttonIconSize[size]}
+        iconSize={controlIconSize[size]}
         uniProps={resolveIconMapping()}
       />
       {children != null ? (
diff --git a/packages/app/src/components/ui/combobox.tsx b/packages/app/src/components/ui/combobox.tsx
index adcd91afcb..cae61ea100 100644
--- a/packages/app/src/components/ui/combobox.tsx
+++ b/packages/app/src/components/ui/combobox.tsx
@@ -1,3 +1,4 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
@@ -62,12 +63,10 @@ import {
 } from "@/components/adaptive-modal-sheet";
 import { FloatingSurface } from "@/components/ui/floating";
 import { useDismissKeyboardOnOpen } from "@/components/ui/keyboard-dismiss";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { useDismissibleOverlay } from "@/components/ui/overlay-dismissal";
+import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
+import { density, densityIconBox } from "@/styles/density";
+import { DensityIcon } from "@/components/ui/density-icon";
 import { buildDesktopFrameStyle } from "./combobox-frame-style";
 
 export { buildDesktopFrameStyle } from "./combobox-frame-style";
@@ -89,6 +88,8 @@ export interface ComboboxProps {
   }) => ReactElement;
   onSearchQueryChange?: (query: string) => void;
   searchable?: boolean;
+  /** The caller answers the search query itself, so the options are shown as given. */
+  remoteSearch?: boolean;
   placeholder?: string;
   searchPlaceholder?: string;
   emptyText?: string;
@@ -207,7 +208,7 @@ export function SearchInput({
 
   return (
     <View style={styles.searchInputContainer}>
-      <Search size={16} color={theme.colors.foregroundMuted} />
+      <DensityIcon icon={Search} size="md" color="foregroundMuted" />
       <AdaptiveTextInput
         ref={inputRef}
         // @ts-expect-error - outlineStyle is web-only
@@ -254,21 +255,19 @@ export function ComboboxItem({
   onPress,
   testID,
 }: ComboboxItemProps): ReactElement {
-  const { theme } = useUnistyles();
-
   let leadingContent: ReactElement | null = null;
   if (leadingSlot) {
     leadingContent = <View style={styles.comboboxItemLeadingSlot}>{leadingSlot}</View>;
   } else if (kind === "directory") {
     leadingContent = (
       <View style={styles.comboboxItemLeadingSlot}>
-        <Folder size={16} color={theme.colors.foregroundMuted} />
+        <DensityIcon icon={Folder} size="md" color="foregroundMuted" />
       </View>
     );
   } else if (kind === "file") {
     leadingContent = (
       <View style={styles.comboboxItemLeadingSlot}>
-        <File size={16} color={theme.colors.foregroundMuted} />
+        <DensityIcon icon={File} size="md" color="foregroundMuted" />
       </View>
     );
   }
@@ -312,7 +311,7 @@ export function ComboboxItem({
       {selected || trailingSlot ? (
         <View style={styles.comboboxItemTrailingContainer}>
           <View style={styles.comboboxItemTrailingSlot}>
-            {selected ? <Check size={16} color={theme.colors.foregroundMuted} /> : null}
+            {selected ? <DensityIcon icon={Check} size="md" color="foregroundMuted" /> : null}
           </View>
           {trailingSlot}
         </View>
@@ -526,7 +525,6 @@ type DesktopKey = "ArrowDown" | "ArrowUp" | "Enter" | "Escape";
 
 interface DesktopKeyHandlerInput {
   isOpen: boolean;
-  isMobile: boolean;
   orderedVisibleOptions: ComboboxOption[];
   activeIndex: number;
   setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
@@ -871,11 +869,12 @@ function isDesktopKey(key: string): key is DesktopKey {
 function dispatchDesktopKey(
   input: DesktopKeyHandlerInput,
   key: DesktopKey,
-  event?: KeyboardEvent,
+  event?: KeyboardInputEvent,
 ): boolean {
   if (!input.isOpen) return false;
-  if (!IS_WEB && input.isMobile) return false;
-
+  // A native mobile bail used to live here because native had no key source, so
+  // nothing could call this. It has one now, and the sheet highlights an active
+  // row like the popover does, so a hardware keyboard drives both.
   if (key === "ArrowDown" || key === "ArrowUp") {
     event?.preventDefault();
     handleDesktopArrowKey(input, key);
@@ -912,6 +911,7 @@ function resolveInitialActiveIndex(
 }
 
 interface MobileBodyProps {
+  overlayLayer: number;
   isOpen: boolean;
   snapPoints: string[];
   handleIndicatorStyle: { backgroundColor: string };
@@ -990,45 +990,47 @@ function MobileComboboxSheet(props: MobileBodyProps): ReactElement {
       keyboardBlurBehavior="none"
       presentation={props.presentation}
     >
-      <ComboboxSheetFrame footer={props.footer}>
-        {props.header ? (
-          <SheetHeaderView header={props.header} onClose={props.onClose} />
-        ) : (
-          <>
-            <View style={styles.bottomSheetHeader}>
-              <Text key={props.titleColor} style={comboboxTitleStyle}>
-                {props.title}
-              </Text>
-            </View>
-            {props.stickyHeader}
-            {!props.hasChildren && props.searchable ? (
-              <SearchInput
-                placeholder={props.searchPlaceholder}
-                onChangeText={props.setSearchQueryWithCallback}
-                onSubmitEditing={props.handleSubmitSearch}
-                autoFocus={false}
-                useBottomSheetInput
-                resetKey={props.searchResetKey}
-              />
-            ) : null}
-          </>
-        )}
-        {props.hasChildren && !props.mobileChildrenScrollEnabled ? (
-          body
-        ) : (
-          <BottomSheetScrollView
-            style={styles.mobileSheetBody}
-            contentContainerStyle={[
-              styles.comboboxScrollContent,
-              props.mobileChildrenContentContainerStyle,
-            ]}
-            keyboardShouldPersistTaps="handled"
-            showsVerticalScrollIndicator={false}
-          >
-            {body}
-          </BottomSheetScrollView>
-        )}
-      </ComboboxSheetFrame>
+      <OverlayLayerProvider layer={props.overlayLayer}>
+        <ComboboxSheetFrame footer={props.footer}>
+          {props.header ? (
+            <SheetHeaderView header={props.header} onClose={props.onClose} />
+          ) : (
+            <>
+              <View style={styles.bottomSheetHeader}>
+                <Text key={props.titleColor} style={comboboxTitleStyle}>
+                  {props.title}
+                </Text>
+              </View>
+              {props.stickyHeader}
+              {!props.hasChildren && props.searchable ? (
+                <SearchInput
+                  placeholder={props.searchPlaceholder}
+                  onChangeText={props.setSearchQueryWithCallback}
+                  onSubmitEditing={props.handleSubmitSearch}
+                  autoFocus={false}
+                  useBottomSheetInput
+                  resetKey={props.searchResetKey}
+                />
+              ) : null}
+            </>
+          )}
+          {props.hasChildren && !props.mobileChildrenScrollEnabled ? (
+            body
+          ) : (
+            <BottomSheetScrollView
+              style={styles.mobileSheetBody}
+              contentContainerStyle={[
+                styles.comboboxScrollContent,
+                props.mobileChildrenContentContainerStyle,
+              ]}
+              keyboardShouldPersistTaps="handled"
+              showsVerticalScrollIndicator={false}
+            >
+              {body}
+            </BottomSheetScrollView>
+          )}
+        </ComboboxSheetFrame>
+      </OverlayLayerProvider>
     </IsolatedBottomSheetModal>
   );
 }
@@ -1062,7 +1064,8 @@ interface DesktopBodyProps {
   overlayLayer: number;
   isOpen: boolean;
   handleClose: () => void;
-  handleDesktopKey: (key: DesktopKey, event?: KeyboardEvent) => boolean;
+  setOverlayScope: (node: unknown) => void;
+  handleDesktopKey: (key: DesktopKey, event?: KeyboardInputEvent) => boolean;
   refs: ReturnType<typeof useFloating>["refs"];
   shouldUseDesktopFade: boolean;
   desktopFrameStyle: StyleProp<ViewStyle>;
@@ -1189,25 +1192,13 @@ function DesktopComboboxOptionsBody(props: {
 
 function DesktopComboboxBody(props: DesktopBodyProps): ReactElement | null {
   const active = useRetainedPanelActive();
-  const handleDesktopKey = props.handleDesktopKey;
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
-      if (!isDesktopKey(event.key)) return false;
-      return handleDesktopKey(event.key, event);
-    },
-    [handleDesktopKey],
-  );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && props.isOpen,
-    layer: props.overlayLayer,
-    onKeyDown: handleWebOverlayKeyDown,
-  });
+  const setOverlayScope = props.setOverlayScope;
   const setFloatingRef = useCallback(
     (node: View | null) => {
       props.refs.setFloating(node);
-      setWebOverlayScope(node);
+      setOverlayScope(node);
     },
-    [props.refs, setWebOverlayScope],
+    [props.refs, setOverlayScope],
   );
 
   // Remove the portal before a retained chat can freeze its closing update.
@@ -1292,6 +1283,10 @@ function DesktopComboboxBody(props: DesktopBodyProps): ReactElement | null {
   );
 }
 
+function filtersLocally(input: { searchable: boolean; remoteSearch?: boolean }): boolean {
+  return input.searchable && !input.remoteSearch;
+}
+
 export function Combobox({
   options,
   value,
@@ -1299,6 +1294,7 @@ export function Combobox({
   renderOption,
   onSearchQueryChange,
   searchable = true,
+  remoteSearch,
   placeholder,
   searchPlaceholder,
   emptyText,
@@ -1374,6 +1370,7 @@ export function Combobox({
   useEffect(() => {
     if (!active && isOpen) handleClose();
   }, [active, isOpen, handleClose]);
+  useDismissibleOverlay(isOpen, handleClose);
 
   useResetSearchOnOpen(isOpen, setSearchQueryWithCallback, bumpSearchResetKey);
 
@@ -1458,7 +1455,7 @@ export function Combobox({
       buildVisibleComboboxOptions({
         options,
         searchQuery,
-        searchable,
+        searchable: filtersLocally({ searchable, remoteSearch }),
         allowCustomValue,
         customValuePrefix,
         customValueDescription,
@@ -1470,6 +1467,7 @@ export function Combobox({
       customValueKind,
       customValuePrefix,
       options,
+      remoteSearch,
       searchQuery,
       searchable,
     ],
@@ -1531,11 +1529,10 @@ export function Combobox({
   );
 
   const handleDesktopKey = useCallback(
-    (key: DesktopKey, event?: KeyboardEvent) => {
+    (key: DesktopKey, event?: KeyboardInputEvent) => {
       return dispatchDesktopKey(
         {
           isOpen,
-          isMobile,
           orderedVisibleOptions,
           activeIndex,
           setActiveIndex,
@@ -1546,7 +1543,7 @@ export function Combobox({
         event,
       );
     },
-    [activeIndex, handleClose, handleSelect, isMobile, isOpen, orderedVisibleOptions],
+    [activeIndex, handleClose, handleSelect, isOpen, orderedVisibleOptions],
   );
 
   useDismissKeyboardOnOpen(isOpen, isMobile);
@@ -1583,12 +1580,20 @@ export function Combobox({
     [],
   );
 
+  const setOverlayScope = useOverlayRegistration({
+    active: isOpen,
+    layer: floatingLayer,
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    onKeyDown: (event) => (isDesktopKey(event.key) ? handleDesktopKey(event.key, event) : false),
+  });
+
   const effectiveSearchPlaceholder = searchPlaceholder ?? resolvedPlaceholder;
   const hasChildren = Boolean(children);
 
   if (isMobile) {
     return (
       <MobileComboboxBody
+        overlayLayer={floatingLayer}
         isOpen={isOpen}
         snapPoints={snapPoints}
         handleIndicatorStyle={handleIndicatorStyle}
@@ -1628,6 +1633,7 @@ export function Combobox({
       isOpen={isOpen}
       handleClose={handleClose}
       handleDesktopKey={handleDesktopKey}
+      setOverlayScope={setOverlayScope}
       refs={refs}
       shouldUseDesktopFade={shouldUseDesktopFade}
       desktopFrameStyle={desktopFrameStyle}
@@ -1686,7 +1692,7 @@ const styles = StyleSheet.create((theme) => ({
   comboboxItem: {
     flexDirection: "row",
     alignItems: "center",
-    minHeight: 36,
+    minHeight: density.rowHeight,
     gap: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
@@ -1717,7 +1723,7 @@ const styles = StyleSheet.create((theme) => ({
     opacity: 0.55,
   },
   comboboxItemTrailingSlot: {
-    width: 16,
+    width: densityIconBox("md"),
     alignItems: "center",
     justifyContent: "center",
   },
@@ -1737,7 +1743,7 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[2],
   },
   comboboxItemLeadingSlot: {
-    width: 16,
+    width: densityIconBox("md"),
     alignItems: "center",
     justifyContent: "center",
   },
diff --git a/packages/app/src/components/ui/control-geometry.test.ts b/packages/app/src/components/ui/control-geometry.test.ts
index 3544d9f940..2e3352397c 100644
--- a/packages/app/src/components/ui/control-geometry.test.ts
+++ b/packages/app/src/components/ui/control-geometry.test.ts
@@ -1,9 +1,31 @@
 import { describe, expect, it } from "vitest";
 import {
-  buttonControlHeight,
-  buttonIconSize,
+  ALERT_ICON_SIZE,
+  bySizing,
+  CONTROL_HEIGHTS,
+  controlHeightForLayout,
+  controlSizingForLayout,
   createControlGeometry,
+  HEADER_CONTROL_HEIGHT,
+  ICON_BUTTON_SIZES,
+  iconSizeFor,
+  resolveControlSizing,
+  switchGeometryForLayout,
   getControlInteractionPhase,
+  TOOLBAR_CONTROL_GAP,
+  TOOLBAR_CONTROL_GAPS,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_CONTROL_SIZES,
+  TOOLBAR_DISC_GLYPH_SIZES,
+  TOOLBAR_DISC_SIZE,
+  TOOLBAR_DISC_SIZES,
+  TOOLBAR_GLYPH_SIZES,
+  TOOLBAR_RINGS,
+  toolbarGlyphColor,
+  toolbarGlyphsFor,
+  toolbarGlyphTone,
+  toolbarSlot,
+  TOUCH_TARGET,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
 
@@ -26,6 +48,7 @@ const theme = {
     xs: 10,
     sm: 12,
     base: 14,
+    lg: 16,
   },
   opacity: {
     50: 0.5,
@@ -36,12 +59,116 @@ const theme = {
     1: 4,
     2: 8,
     3: 12,
+    3.5: 14,
     4: 16,
     6: 24,
+    7: 28,
     8: 32,
   },
 } as unknown as Theme;
 
+describe("control sizing gate", () => {
+  it("is touch-sized in the compact layout or on a touch screen, and pointer-sized otherwise", () => {
+    expect(resolveControlSizing({ compactLayout: true, touchScreen: true })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: true, touchScreen: false })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: false, touchScreen: true })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: false, touchScreen: false })).toBe("pointer");
+  });
+
+  it("gives a touch screen its touch sizes at every width", () => {
+    const sizes = { touch: 44, pointer: 32 };
+
+    // An iPad: touch-sized in the docked desktop layout too.
+    expect(bySizing(sizes, true)).toEqual({ xs: 44, md: 44 });
+    // A mouse-driven window: touch-sized only once it narrows into the compact layout.
+    expect(bySizing(sizes, false)).toEqual({ xs: 44, md: 32 });
+  });
+
+  it("keeps a device without a touch screen on pointer sizes from md up", () => {
+    // The unit runtime has no touch screen, which is the desktop that must not change.
+    expect(controlSizingForLayout(false)).toBe("pointer");
+    expect(controlSizingForLayout(true)).toBe("touch");
+    expect(CONTROL_HEIGHTS.md).toEqual({ xs: 44, md: 32 });
+    expect(CONTROL_HEIGHTS.sm).toEqual({ xs: 32, md: 28 });
+    expect(HEADER_CONTROL_HEIGHT).toEqual({ xs: 32, md: 26 });
+  });
+
+  it("follows the HIG on touch: a 44pt target, no control under 28pt, larger glyphs", () => {
+    expect(TOUCH_TARGET).toBe(44);
+    expect(controlHeightForLayout("md", true)).toBe(TOUCH_TARGET);
+    expect(ICON_BUTTON_SIZES.large.touch).toBe(TOUCH_TARGET);
+    expect(ICON_BUTTON_SIZES.small.touch).toBe(TOUCH_TARGET);
+    // Composer toolbar controls: a full target on touch, unchanged 28 on pointer.
+    expect(TOOLBAR_CONTROL_SIZES).toEqual({ touch: TOUCH_TARGET, pointer: 28 });
+    expect(TOOLBAR_CONTROL_HEIGHT).toEqual({ xs: TOUCH_TARGET, md: 28 });
+    // A filled toolbar control paints a 36pt disc inside its 44pt touch frame, and fills its
+    // 28pt pointer frame exactly, so desktop is unchanged. Its glyph is the `md` glyph.
+    expect(TOOLBAR_DISC_SIZES).toEqual({ touch: 36, pointer: TOOLBAR_CONTROL_SIZES.pointer });
+    expect(TOOLBAR_DISC_SIZE).toEqual({ xs: 36, md: 28 });
+    expect(iconSizeFor("md")).toEqual({ touch: 20, pointer: 16 });
+    for (const size of ["sm", "md"] as const) {
+      expect(controlHeightForLayout(size, true)).toBeGreaterThan(
+        controlHeightForLayout(size, false),
+      );
+      expect(controlHeightForLayout(size, false)).toBeGreaterThanOrEqual(28);
+    }
+    for (const size of ["xs", "sm", "md", "lg"] as const) {
+      expect(iconSizeFor(size).touch).toBeGreaterThan(iconSizeFor(size).pointer);
+    }
+  });
+});
+
+describe("toolbar glyphs and spacing", () => {
+  it("lays touch toolbar controls out at their highlight with no gap and keeps the pointer's 4px gap", () => {
+    expect(TOOLBAR_CONTROL_GAPS).toEqual({ touch: 0, pointer: 4 });
+    expect(TOOLBAR_CONTROL_GAP).toEqual({ xs: 0, md: 4 });
+    expect(toolbarSlot()).toEqual({ width: TOOLBAR_DISC_SIZE, height: TOOLBAR_DISC_SIZE });
+  });
+
+  it("paints touch toolbar glyphs at the header icons' 20pt and 1.5px stroke and leaves pointer unchanged", () => {
+    const pointerGlyph = { size: 16, strokeWidth: 1.5, tone: "muted" };
+    expect(toolbarGlyphsFor("touch").icon).toEqual({
+      size: 20,
+      strokeWidth: 1.5,
+      tone: "foreground",
+    });
+    expect(toolbarGlyphsFor("pointer")).toEqual({ icon: pointerGlyph, label: pointerGlyph });
+    expect(TOOLBAR_GLYPH_SIZES.icon).toEqual({ xs: 20, md: 16 });
+    expect(toolbarGlyphsFor("touch").icon.size).toBeLessThan(TOOLBAR_CONTROL_SIZES.touch);
+    expect(toolbarGlyphsFor("pointer").icon.size).toBeLessThan(TOOLBAR_CONTROL_SIZES.pointer);
+    // A disc's solid glyph stays at the `md` size so the stop square does not fill its disc.
+    expect(TOOLBAR_DISC_GLYPH_SIZES).toEqual({ touch: 20, pointer: 16 });
+  });
+
+  it("keeps a touch glyph beside a label at the label's 20pt scale", () => {
+    expect(toolbarGlyphsFor("touch").label).toEqual({
+      size: 20,
+      strokeWidth: 1.5,
+      tone: "foreground",
+    });
+    expect(TOOLBAR_GLYPH_SIZES.label).toEqual({ xs: 20, md: 16 });
+  });
+
+  it("sizes the touch context ring to the toolbar glyph's ink and keeps the pointer ring", () => {
+    expect(TOOLBAR_RINGS).toEqual({
+      touch: { size: 18, strokeWidth: 2 },
+      pointer: { size: 16, strokeWidth: 2 },
+    });
+  });
+
+  it("brightens a muted toolbar glyph under a hovering pointer", () => {
+    const pointer = toolbarGlyphsFor("pointer").icon;
+    const touch = toolbarGlyphsFor("touch").icon;
+    expect(toolbarGlyphTone(pointer, false)).toBe("muted");
+    expect(toolbarGlyphTone(pointer, true)).toBe("foreground");
+    expect(toolbarGlyphTone(touch, false)).toBe("foreground");
+    const colors = { foreground: "#fafafa", foregroundMuted: "#a1a5a4" };
+    const palette = { colors } as unknown as Theme;
+    expect(toolbarGlyphColor(palette, "foreground")).toBe("#fafafa");
+    expect(toolbarGlyphColor(palette, "muted")).toBe("#a1a5a4");
+  });
+});
+
 describe("control geometry", () => {
   it("keeps resting control borders transparent while preserving border geometry", () => {
     const geometry = createControlGeometry(theme);
@@ -81,95 +208,106 @@ describe("control geometry", () => {
   it("keeps field text sizing tied to control size", () => {
     const geometry = createControlGeometry(theme);
 
-    expect(geometry.fieldTextXs.fontSize).toBe(12);
-    expect(geometry.fieldTextXs.lineHeight).toBe(17);
-    expect(geometry.fieldTextSm.fontSize).toBe(14);
-    expect(geometry.fieldTextSm.lineHeight).toBe(20);
+    expect(geometry.fieldTextSm.fontSize).toBe(12);
+    expect(geometry.fieldTextSm.lineHeight).toBe(17);
     expect(geometry.fieldTextMd.fontSize).toBe(14);
     expect(geometry.fieldTextMd.lineHeight).toBe(20);
-    expect(geometry.formTextInputSm.fontSize).toBe(14);
-    expect(geometry.formTextInputSm.lineHeight).toBe(20);
+    expect(geometry.formTextInputSm.fontSize).toBe(12);
     expect(geometry.formTextInputMd.fontSize).toBe(14);
-    expect(geometry.formTextInputMd.lineHeight).toBe(20);
   });
 
   it("derives field padding from content and border without changing the control height", () => {
     const geometry = createControlGeometry(theme);
     const borderWidth = theme.borderWidth[1];
 
-    expect(geometry.fieldControlXs.minHeight).toBe(28);
-    expect(
-      geometry.fieldTextXs.lineHeight +
-        geometry.fieldControlXs.paddingVertical * 2 +
-        borderWidth * 2,
-    ).toBe(geometry.fieldControlXs.minHeight);
-
-    expect(geometry.fieldControlSm.minHeight).toBe(32);
-    expect(geometry.fieldControlSm.paddingVertical).toBe(5);
-    expect(
-      geometry.fieldTextSm.lineHeight +
-        geometry.fieldControlSm.paddingVertical * 2 +
-        borderWidth * 2,
-    ).toBe(geometry.fieldControlSm.minHeight);
-
-    expect(geometry.fieldControlMd.minHeight).toBe(44);
-    expect(geometry.fieldControlMd.paddingVertical).toBe(11);
-    expect(
-      geometry.fieldTextMd.lineHeight +
-        geometry.fieldControlMd.paddingVertical * 2 +
-        borderWidth * 2,
-    ).toBe(geometry.fieldControlMd.minHeight);
-
-    expect(geometry.formTextInputSm.paddingVertical).toBe(5);
-    expect(geometry.formTextInputMd.paddingVertical).toBe(11);
+    expect(geometry.fieldControlSm.minHeight).toEqual({ xs: 32, md: 28 });
+    // The default keeps a 44 touch target in the compact layout and is 32 from the md
+    // breakpoint up.
+    expect(geometry.fieldControlMd.minHeight).toEqual({ xs: 44, md: 32 });
+    expect(geometry.fieldControlMd.paddingVertical).toEqual({ xs: 11, md: 5 });
+    for (const layout of ["xs", "md"] as const) {
+      expect(
+        geometry.fieldTextSm.lineHeight +
+          geometry.fieldControlSm.paddingVertical[layout] * 2 +
+          borderWidth * 2,
+      ).toBe(geometry.fieldControlSm.minHeight[layout]);
+      expect(
+        geometry.fieldTextMd.lineHeight +
+          geometry.fieldControlMd.paddingVertical[layout] * 2 +
+          borderWidth * 2,
+      ).toBe(geometry.fieldControlMd.minHeight[layout]);
+    }
   });
 
   it("keeps segmented controls ghost with button-radius segments in a button-sized track", () => {
     const geometry = createControlGeometry(theme);
 
-    expect(geometry.segmentedContainerXs.padding).toBe(0);
     expect(geometry.segmentedContainerSm.padding).toBe(0);
     expect(geometry.segmentedContainerMd.padding).toBe(0);
-    expect(geometry.segmentedSegmentXs.borderRadius).toBe(geometry.buttonXs.borderRadius);
     expect(geometry.segmentedSegmentSm.borderRadius).toBe(geometry.buttonSm.borderRadius);
     expect(geometry.segmentedSegmentMd.borderRadius).toBe(geometry.buttonMd.borderRadius);
-    expect(geometry.segmentedContainerXs.minHeight).toBe(geometry.buttonXs.minHeight);
-    expect(geometry.segmentedContainerSm.minHeight).toBe(geometry.buttonSm.minHeight);
-    expect(geometry.segmentedContainerMd.minHeight).toBe(geometry.buttonMd.minHeight);
-    expect(geometry.segmentedSegmentXs.minHeight).toBe(24);
-    expect(geometry.segmentedSegmentSm.minHeight).toBe(28);
-    expect(geometry.segmentedSegmentMd.minHeight).toBe(38);
+    expect(geometry.segmentedContainerSm.minHeight).toEqual(geometry.buttonSm.minHeight);
+    expect(geometry.segmentedContainerMd.minHeight).toEqual(geometry.buttonMd.minHeight);
+    expect(geometry.segmentedSegmentSm.minHeight).toEqual({ xs: 28, md: 24 });
+    expect(geometry.segmentedSegmentMd.minHeight).toEqual({ xs: 40, md: 28 });
   });
 
-  it("keeps one size contract across buttons and segmented controls", () => {
+  it("keeps one size contract across buttons, fields, and segmented controls", () => {
     const geometry = createControlGeometry(theme);
 
-    // xs is a genuinely smaller tier, not sm with a different font.
-    expect(geometry.buttonXs.minHeight).toBe(28);
-    expect(geometry.buttonSm.minHeight).toBe(32);
-    expect(geometry.buttonMd.minHeight).toBe(44);
-    expect(geometry.buttonXs.minHeight).toBe(buttonControlHeight.xs);
-    expect(geometry.buttonSm.minHeight).toBe(buttonControlHeight.sm);
-    expect(geometry.buttonMd.minHeight).toBe(buttonControlHeight.md);
+    expect(geometry.buttonSm.minHeight).toEqual({ xs: 32, md: 28 });
+    expect(geometry.buttonMd.minHeight).toEqual({ xs: 44, md: 32 });
+    expect(geometry.buttonSm.minHeight).toEqual(CONTROL_HEIGHTS.sm);
+    expect(geometry.buttonMd.minHeight).toEqual(CONTROL_HEIGHTS.md);
+    expect(geometry.fieldControlSm.minHeight).toEqual(CONTROL_HEIGHTS.sm);
+    expect(geometry.fieldControlMd.minHeight).toEqual(CONTROL_HEIGHTS.md);
+    expect(controlHeightForLayout("md", true)).toBe(44);
+    expect(controlHeightForLayout("md", false)).toBe(32);
+    expect(controlHeightForLayout("sm", true)).toBe(32);
+    expect(controlHeightForLayout("sm", false)).toBe(28);
 
     // Same size name means the same label size on every control kind.
-    expect(geometry.segmentedLabelXs.fontSize).toBe(12);
-    expect(geometry.segmentedLabelXs.fontSize).toBe(geometry.buttonTextXs.fontSize);
-    expect(geometry.segmentedLabelSm.fontSize).toBe(14);
-    expect(geometry.segmentedLabelSm.fontSize).toBe(geometry.buttonText.fontSize);
-    expect(geometry.segmentedLabelMd.fontSize).toBe(geometry.buttonText.fontSize);
+    expect(geometry.segmentedLabelSm.fontSize).toBe(12);
+    expect(geometry.segmentedLabelSm.fontSize).toBe(geometry.buttonTextSm.fontSize);
+    expect(geometry.segmentedLabelMd.fontSize).toBe(14);
+    expect(geometry.segmentedLabelMd.fontSize).toBe(geometry.buttonTextMd.fontSize);
 
-    // Segments sit inside a track, so they run one padding step tighter than a
-    // standalone button of the same size — the gap between segments reads as the padding.
-    expect(geometry.segmentedSegmentXs.paddingHorizontal).toBeLessThan(
-      geometry.buttonXs.paddingHorizontal,
-    );
+    // Segments sit inside a track, so they run tighter than a standalone button of the same
+    // size — the gap between segments reads as the padding.
     expect(geometry.segmentedSegmentSm.paddingHorizontal).toBeLessThan(
       geometry.buttonSm.paddingHorizontal,
     );
-    expect(geometry.segmentedSegmentMd.paddingHorizontal).toBeLessThan(
-      geometry.buttonMd.paddingHorizontal,
-    );
+    for (const layout of ["xs", "md"] as const) {
+      expect(geometry.segmentedSegmentMd.paddingHorizontal).toBeLessThan(
+        geometry.buttonMd.paddingHorizontal[layout],
+      );
+    }
+  });
+
+  it("sizes switches with the same two control sizes", () => {
+    expect(switchGeometryForLayout("md", false)).toEqual({
+      trackWidth: 34,
+      trackHeight: 20,
+      thumbSize: 16,
+      thumbTravel: 14,
+      reservedHeight: 32,
+    });
+    expect(switchGeometryForLayout("md", true)).toEqual({
+      trackWidth: 44,
+      trackHeight: 26,
+      thumbSize: 22,
+      thumbTravel: 18,
+      reservedHeight: 44,
+    });
+    // Tight chrome keeps the pointer-sized track on every layout and reserves its row's height.
+    expect(switchGeometryForLayout("sm", true)).toMatchObject({
+      trackWidth: 34,
+      reservedHeight: 32,
+    });
+    expect(switchGeometryForLayout("sm", false)).toMatchObject({
+      trackWidth: 34,
+      reservedHeight: 28,
+    });
   });
 
   it("gives alert title and description one font size and a tight gap per size", () => {
@@ -188,7 +326,7 @@ describe("control geometry", () => {
     const { alert } = createControlGeometry(theme);
 
     for (const size of ["xs", "sm", "md", "lg"] as const) {
-      expect(alert[size].iconSlot.width).toBe(buttonIconSize[size]);
+      expect(alert[size].iconSlot.width).toBe(ALERT_ICON_SIZE[size]);
       expect(alert[size].indent.marginLeft).toBe(alert[size].iconSlot.width + alert[size].lead.gap);
     }
   });
diff --git a/packages/app/src/components/ui/control-geometry.ts b/packages/app/src/components/ui/control-geometry.ts
index 0a41f80039..f8d3132e38 100644
--- a/packages/app/src/components/ui/control-geometry.ts
+++ b/packages/app/src/components/ui/control-geometry.ts
@@ -1,9 +1,22 @@
 import type { StyleProp, ViewStyle } from "react-native";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { ICON_SIZE, ICON_STROKE_WIDTH, type Theme } from "@/styles/theme";
+import {
+  bySizing,
+  controlSizingForLayout,
+  mapLayout,
+  TOUCH_TARGET,
+  type ControlSizing,
+  type LayoutValue,
+  type SizingValue,
+} from "./control-sizing";
 
-export type ButtonControlSize = "xs" | "sm" | "md" | "lg";
-export type FieldControlSize = "xs" | "sm" | "md";
-export type SegmentedControlSize = "xs" | "sm" | "md";
+/**
+ * Controls come in two sizes. `md` is the default and the right size almost everywhere;
+ * `sm` is for tight chrome such as toolbars and nested rows.
+ */
+export type ControlSize = "sm" | "md";
+/** Alerts are containers, not controls, so they keep their own density scale. */
+export type AlertSize = "xs" | "sm" | "md" | "lg";
 export type ControlInteractionPhase = "rest" | "hover" | "active";
 
 export interface ControlInteractionState {
@@ -22,58 +35,214 @@ export interface ControlInteractionStyleMap {
   controlDisabled?: StyleProp<ViewStyle>;
 }
 
-const TIGHT_CONTROL_HEIGHT = 28;
-const COMPACT_CONTROL_HEIGHT = 32;
-const FIELD_CONTROL_HEIGHT = 44;
-export const HEADER_CONTROL_HEIGHT = 26;
-const SEGMENTED_TIGHT_INSET = 2;
-const SEGMENTED_COMPACT_INSET = 2;
-const SEGMENTED_FIELD_INSET = 3;
-const SWITCH_TRACK_WIDTH = 34;
-const SWITCH_TRACK_HEIGHT = 20;
-const SWITCH_THUMB_SIZE = 16;
+export {
+  bySizing,
+  controlSizingForLayout,
+  mapLayout,
+  resolveControlSizing,
+  TOUCH_TARGET,
+  type ControlSizing,
+  type ControlSizingFacts,
+  type LayoutValue,
+  type SizingValue,
+} from "./control-sizing";
+
+// Touch `md` is the iOS HIG's 44pt default control; touch `sm` stays above its 28pt minimum.
+const CONTROL_SIZES = {
+  sm: { touch: 32, pointer: 28 },
+  md: { touch: TOUCH_TARGET, pointer: 32 },
+} satisfies Record<ControlSize, SizingValue>;
+
+/** Pointer-sized header controls run tighter than `sm` so they fit the 36pt header. */
+const POINTER_HEADER_CONTROL_HEIGHT = 26;
+const SEGMENTED_INSET = 2;
 const CONTROL_FOCUS_RING_WIDTH = 2;
 const CONTROL_FOCUS_RING_OFFSET = 1;
-const CONTROL_CENTER_JUSTIFY_CONTENT = "center";
 const FIELD_TEXT_LINE_HEIGHT_RATIO = 1.4;
 
 /**
- * The three control heights every button, field, and segmented control is built from.
- * Exported so a row that hosts one of those controls can size itself from the same
- * numbers instead of guessing a height the control then outgrows.
+ * The height of every button, field, and segmented control of a size. Exported so a row that
+ * hosts one of those controls can size itself from the same numbers instead of guessing a
+ * height the control then outgrows. Breakpoint values, so they only work inside a Unistyles
+ * stylesheet.
  */
 export const CONTROL_HEIGHTS = {
-  tight: TIGHT_CONTROL_HEIGHT,
-  compact: COMPACT_CONTROL_HEIGHT,
-  field: FIELD_CONTROL_HEIGHT,
+  sm: bySizing(CONTROL_SIZES.sm),
+  md: bySizing(CONTROL_SIZES.md),
+} satisfies Record<ControlSize, LayoutValue>;
+
+/** A framed control in a header row, such as a split button. Touch-sized it is an `sm` control. */
+export const HEADER_CONTROL_HEIGHT = bySizing({
+  touch: CONTROL_SIZES.sm.touch,
+  pointer: POINTER_HEADER_CONTROL_HEIGHT,
+});
+
+/**
+ * Square icon-only buttons. Touch-sized, every icon button is one touch target; pointer-sized,
+ * header buttons are larger than toolbar buttons.
+ */
+export const ICON_BUTTON_SIZES = {
+  large: { touch: TOUCH_TARGET, pointer: POINTER_HEADER_CONTROL_HEIGHT },
+  small: { touch: TOUCH_TARGET, pointer: 20 },
+} satisfies Record<"large" | "small", SizingValue>;
+
+/**
+ * The height of a dense toolbar row, such as the composer's. Touch-sized it is one touch target;
+ * its controls are disc-sized and centre in it.
+ */
+export const TOOLBAR_CONTROL_SIZES = { touch: TOUCH_TARGET, pointer: 28 } satisfies SizingValue;
+export const TOOLBAR_CONTROL_HEIGHT = bySizing(TOOLBAR_CONTROL_SIZES);
+
+/**
+ * The disc of a filled toolbar control, such as the composer's send and stop, and the frame and
+ * highlight of every other toolbar control (`toolbarSlot`). Pointer-sized it fills the row.
+ */
+export const TOOLBAR_DISC_SIZES = { touch: 36, pointer: 28 } satisfies SizingValue;
+export const TOOLBAR_DISC_SIZE = bySizing(TOOLBAR_DISC_SIZES);
+
+/**
+ * The space between adjacent toolbar controls. Touch-sized there is none: each control lays out at
+ * its fully rounded highlight, so neighbouring highlights touch and never overlap.
+ */
+export const TOOLBAR_CONTROL_GAPS = { touch: 0, pointer: 4 } satisfies SizingValue;
+export const TOOLBAR_CONTROL_GAP = bySizing(TOOLBAR_CONTROL_GAPS);
+
+/** A labelled toolbar control's padding on each side of its content. */
+export const TOOLBAR_LABEL_PADDING = 8;
+
+/** An icon-only toolbar control's frame: a disc-sized circle, which is also its highlight. */
+export function toolbarSlot(): { width: LayoutValue; height: LayoutValue } {
+  return { width: TOOLBAR_DISC_SIZE, height: TOOLBAR_DISC_SIZE };
+}
+
+/** A toolbar control as wide as its content, such as a labelled picker: a disc-tall pill. */
+export function toolbarContentSlot(): { height: LayoutValue; paddingHorizontal: number } {
+  return { height: TOOLBAR_DISC_SIZE, paddingHorizontal: TOOLBAR_LABEL_PADDING };
+}
+
+/**
+ * Glyph sizes. Pointer glyphs sit beside 13-14pt text; touch glyphs sit beside iOS's 17pt body
+ * text, so each step is larger.
+ */
+export type IconSize = keyof typeof ICON_SIZE;
+export const TOUCH_ICON_SIZE: Record<IconSize, number> = { xs: 14, sm: 18, md: 20, lg: 24 };
+
+export function iconSizeFor(size: IconSize): SizingValue {
+  return { touch: TOUCH_ICON_SIZE[size], pointer: ICON_SIZE[size] };
+}
+
+/**
+ * The glyph a toolbar control paints. Touch-sized every toolbar glyph matches the header icons:
+ * 20pt at the app's 1.5px stroke, resting at `foreground`. Pointer-sized it is the `md` glyph at
+ * the same stroke and rests muted until hovered.
+ */
+export type ToolbarGlyphTone = "foreground" | "muted";
+
+export interface ToolbarGlyph {
+  size: number;
+  strokeWidth: number;
+  /** The tone at rest; a hovering pointer brightens it to `foreground`. */
+  tone: ToolbarGlyphTone;
+}
+
+/** `icon` is an icon-only control's glyph; `label` is a glyph paired with a label. */
+export interface ToolbarGlyphs {
+  icon: ToolbarGlyph;
+  label: ToolbarGlyph;
+}
+
+const POINTER_TOOLBAR_GLYPH: ToolbarGlyph = {
+  size: ICON_SIZE.md,
+  strokeWidth: ICON_STROKE_WIDTH,
+  tone: "muted",
 };
 
-export const buttonControlHeight: Record<ButtonControlSize, number> = {
-  xs: CONTROL_HEIGHTS.tight,
-  sm: CONTROL_HEIGHTS.compact,
-  md: CONTROL_HEIGHTS.field,
-  lg: CONTROL_HEIGHTS.field,
+const TOOLBAR_GLYPHS: Record<ControlSizing, ToolbarGlyphs> = {
+  touch: {
+    icon: { size: TOUCH_ICON_SIZE.md, strokeWidth: ICON_STROKE_WIDTH, tone: "foreground" },
+    label: { size: TOUCH_ICON_SIZE.md, strokeWidth: ICON_STROKE_WIDTH, tone: "foreground" },
+  },
+  pointer: { icon: POINTER_TOOLBAR_GLYPH, label: POINTER_TOOLBAR_GLYPH },
 };
 
-export const buttonIconSize: Record<ButtonControlSize, number> = {
-  xs: ICON_SIZE.xs,
-  sm: ICON_SIZE.sm,
-  md: ICON_SIZE.md,
-  lg: ICON_SIZE.lg,
+export function toolbarGlyphsFor(sizing: ControlSizing): ToolbarGlyphs {
+  return TOOLBAR_GLYPHS[sizing];
+}
+
+/** The slot each toolbar glyph sits in, as stylesheet values. */
+export const TOOLBAR_GLYPH_SIZES = {
+  icon: bySizing({ touch: TOOLBAR_GLYPHS.touch.icon.size, pointer: POINTER_TOOLBAR_GLYPH.size }),
+  label: bySizing({ touch: TOOLBAR_GLYPHS.touch.label.size, pointer: POINTER_TOOLBAR_GLYPH.size }),
+} satisfies Record<keyof ToolbarGlyphs, LayoutValue>;
+
+/**
+ * The context ring in a toolbar row. A full circle fills its box while an outline glyph's ink
+ * sits inset, so touch-sized the ring is 18pt, the height of a 20pt glyph's ink. Its 2px stroke
+ * is half a pixel over the glyphs' so the thin circle does not read lighter than them.
+ * Pointer-sized it is the `md` glyph.
+ */
+export interface ToolbarRing {
+  size: number;
+  strokeWidth: number;
+}
+
+export const TOOLBAR_RINGS = {
+  touch: { size: 18, strokeWidth: 2 },
+  pointer: { size: ICON_SIZE.md, strokeWidth: 2 },
+} satisfies Record<ControlSizing, ToolbarRing>;
+
+export function toolbarGlyphTone(glyph: ToolbarGlyph, hovered: boolean): ToolbarGlyphTone {
+  return hovered ? "foreground" : glyph.tone;
+}
+
+export function toolbarGlyphColor(theme: Theme, tone: ToolbarGlyphTone): string {
+  return tone === "foreground" ? theme.colors.foreground : theme.colors.foregroundMuted;
+}
+
+/**
+ * The solid glyph inside a toolbar disc, such as the stop square. It stays at the `md` glyph
+ * size: at the toolbar glyph size the square would fill half its disc. Send's outline arrow
+ * takes the toolbar glyph.
+ */
+export const TOOLBAR_DISC_GLYPH_SIZES = iconSizeFor("md");
+
+/** The height of a control of `size`, for code that has to compute with it outside a stylesheet. */
+export function controlHeightForLayout(size: ControlSize, isCompact: boolean): number {
+  return CONTROL_SIZES[size][controlSizingForLayout(isCompact)];
+}
+
+export const controlIconSize: Record<ControlSize, number> = {
+  sm: ICON_SIZE.xs,
+  md: ICON_SIZE.sm,
 };
 
-export const segmentedIconSize: Record<SegmentedControlSize, number> = {
-  xs: ICON_SIZE.xs,
-  sm: ICON_SIZE.sm,
-  md: ICON_SIZE.md,
-};
+export interface SwitchGeometry {
+  trackWidth: number;
+  trackHeight: number;
+  thumbSize: number;
+  /** How far the thumb slides between off and on. */
+  thumbTravel: number;
+  /** The control height the switch reserves, so its row lines up with one holding a button. */
+  reservedHeight: number;
+}
 
-export const switchGeometry = {
-  trackWidth: SWITCH_TRACK_WIDTH,
-  trackHeight: SWITCH_TRACK_HEIGHT,
-  thumbSize: SWITCH_THUMB_SIZE,
-  thumbTravel: SWITCH_TRACK_WIDTH - SWITCH_THUMB_SIZE - (SWITCH_TRACK_HEIGHT - SWITCH_THUMB_SIZE),
-};
+function switchSize(trackWidth: number, trackHeight: number, thumbSize: number) {
+  const inset = (trackHeight - thumbSize) / 2;
+  return { trackWidth, trackHeight, thumbSize, thumbTravel: trackWidth - thumbSize - inset * 2 };
+}
+
+const SWITCH_POINTER = switchSize(34, 20, 16);
+const SWITCH_TOUCH = switchSize(44, 26, 22);
+
+/**
+ * A switch follows the same two sizes as every other control. Its thumb travel feeds an
+ * animation, so the size is resolved to plain numbers here instead of a stylesheet breakpoint.
+ */
+export function switchGeometryForLayout(size: ControlSize, isCompact: boolean): SwitchGeometry {
+  const touchSized = controlSizingForLayout(isCompact) === "touch";
+  const track = size === "md" && touchSized ? SWITCH_TOUCH : SWITCH_POINTER;
+  return { ...track, reservedHeight: controlHeightForLayout(size, isCompact) };
+}
 
 function fieldLineHeight(fontSize: number): number {
   return Math.round(fontSize * FIELD_TEXT_LINE_HEIGHT_RATIO);
@@ -88,14 +257,21 @@ function fieldVerticalPadding(
 }
 
 /**
- * Alerts share the button's size names, text size, and icon size (`buttonIconSize`).
+ * Alert density steps. Each step's icon matches the text it leads.
  * The icon and the first text sit in one centered lead row; everything below is indented
  * by the icon slot plus its gap so it starts at the lead text's left edge. Title and
  * description use one font size; only the container gap separates them.
  */
+export const ALERT_ICON_SIZE: Record<AlertSize, number> = {
+  xs: ICON_SIZE.xs,
+  sm: ICON_SIZE.sm,
+  md: ICON_SIZE.md,
+  lg: ICON_SIZE.lg,
+};
+
 function createAlertGeometry(theme: Theme) {
   function alertSize(input: {
-    size: ButtonControlSize;
+    size: AlertSize;
     fontSize: number;
     paddingVertical: number;
     paddingHorizontal: number;
@@ -103,7 +279,7 @@ function createAlertGeometry(theme: Theme) {
     iconGap: number;
     textGap: number;
   }) {
-    const iconSize = buttonIconSize[input.size];
+    const iconSize = ALERT_ICON_SIZE[input.size];
     return {
       container: {
         paddingVertical: input.paddingVertical,
@@ -155,7 +331,7 @@ function createAlertGeometry(theme: Theme) {
       iconGap: theme.spacing[4],
       textGap: theme.spacing[1],
     }),
-  } satisfies Record<ButtonControlSize, unknown>;
+  } satisfies Record<AlertSize, unknown>;
 }
 
 export function getControlInteractionPhase(
@@ -188,45 +364,26 @@ export function resolveControlInteractionStyles(
 
 export function createControlGeometry(theme: Theme) {
   const controlBorderWidth = theme.borderWidth[1];
-  const fieldTextXsLineHeight = fieldLineHeight(theme.fontSize.sm);
-  const fieldTextSmLineHeight = fieldLineHeight(theme.fontSize.base);
+  const fieldTextSmLineHeight = fieldLineHeight(theme.fontSize.sm);
   const fieldTextMdLineHeight = fieldLineHeight(theme.fontSize.base);
-  const fieldControlXs = {
-    minHeight: CONTROL_HEIGHTS.tight,
-    paddingHorizontal: theme.spacing[2],
-    paddingVertical: fieldVerticalPadding(
-      CONTROL_HEIGHTS.tight,
-      fieldTextXsLineHeight,
-      controlBorderWidth,
-    ),
-    borderRadius: theme.borderRadius.md,
-  };
   const fieldControlSm = {
-    minHeight: CONTROL_HEIGHTS.compact,
-    paddingHorizontal: theme.spacing[3],
-    paddingVertical: fieldVerticalPadding(
-      CONTROL_HEIGHTS.compact,
-      fieldTextSmLineHeight,
-      controlBorderWidth,
+    minHeight: CONTROL_HEIGHTS.sm,
+    paddingHorizontal: theme.spacing[2],
+    paddingVertical: mapLayout(CONTROL_HEIGHTS.sm, (height) =>
+      fieldVerticalPadding(height, fieldTextSmLineHeight, controlBorderWidth),
     ),
     borderRadius: theme.borderRadius.md,
   };
   const fieldControlMd = {
-    minHeight: CONTROL_HEIGHTS.field,
-    paddingHorizontal: theme.spacing[4],
-    paddingVertical: fieldVerticalPadding(
-      CONTROL_HEIGHTS.field,
-      fieldTextMdLineHeight,
-      controlBorderWidth,
+    minHeight: CONTROL_HEIGHTS.md,
+    paddingHorizontal: theme.spacing[3],
+    paddingVertical: mapLayout(CONTROL_HEIGHTS.md, (height) =>
+      fieldVerticalPadding(height, fieldTextMdLineHeight, controlBorderWidth),
     ),
     borderRadius: theme.borderRadius.lg,
   };
-  const fieldTextXs = {
-    fontSize: theme.fontSize.sm,
-    lineHeight: fieldTextXsLineHeight,
-  };
   const fieldTextSm = {
-    fontSize: theme.fontSize.base,
+    fontSize: theme.fontSize.sm,
     lineHeight: fieldTextSmLineHeight,
   };
   const fieldTextMd = {
@@ -234,43 +391,28 @@ export function createControlGeometry(theme: Theme) {
     lineHeight: fieldTextMdLineHeight,
   };
   const alert = createAlertGeometry(theme);
-  const switchControl = {
-    minHeight: CONTROL_HEIGHTS.compact,
-    justifyContent: CONTROL_CENTER_JUSTIFY_CONTENT,
-  } satisfies { minHeight: number; justifyContent: "center" };
 
   return {
-    buttonXs: {
-      minHeight: buttonControlHeight.xs,
-      paddingHorizontal: theme.spacing[3],
-      borderRadius: theme.borderRadius.xl,
-    },
     buttonSm: {
-      minHeight: buttonControlHeight.sm,
+      minHeight: CONTROL_HEIGHTS.sm,
       paddingHorizontal: theme.spacing[3],
-      borderRadius: theme.borderRadius.xl,
+      borderRadius: theme.borderRadius.full,
     },
     buttonMd: {
-      minHeight: buttonControlHeight.md,
-      paddingHorizontal: theme.spacing[4],
-      borderRadius: theme.borderRadius["2xl"],
+      minHeight: CONTROL_HEIGHTS.md,
+      paddingHorizontal: bySizing({ touch: theme.spacing[6], pointer: theme.spacing[4] }),
+      borderRadius: theme.borderRadius.full,
     },
-    buttonLg: {
-      minHeight: buttonControlHeight.lg,
-      paddingHorizontal: theme.spacing[6],
-      borderRadius: theme.borderRadius["2xl"],
-    },
-    buttonText: {
-      fontSize: theme.fontSize.base,
-    },
-    buttonTextXs: {
+    // A button with only an icon is a circle of its size's height.
+    buttonIconOnlySm: { width: CONTROL_HEIGHTS.sm, paddingHorizontal: 0 },
+    buttonIconOnlyMd: { width: CONTROL_HEIGHTS.md, paddingHorizontal: 0 },
+    buttonTextSm: {
       fontSize: theme.fontSize.sm,
     },
-    alert,
-    formTextInputXs: {
-      ...fieldControlXs,
-      ...fieldTextXs,
+    buttonTextMd: {
+      fontSize: theme.fontSize.base,
     },
+    alert,
     formTextInputSm: {
       ...fieldControlSm,
       ...fieldTextSm,
@@ -279,14 +421,8 @@ export function createControlGeometry(theme: Theme) {
       ...fieldControlMd,
       ...fieldTextMd,
     },
-    formTextInput: {
-      ...fieldControlMd,
-      ...fieldTextMd,
-    },
-    fieldControlXs,
     fieldControlSm,
     fieldControlMd,
-    fieldTextXs,
     fieldTextSm,
     fieldTextMd,
     controlRest: {
@@ -311,39 +447,26 @@ export function createControlGeometry(theme: Theme) {
     controlDisabled: {
       opacity: theme.opacity[50],
     },
-    switchControl,
-    segmentedContainerXs: {
-      minHeight: CONTROL_HEIGHTS.tight,
-      padding: 0,
-    },
     segmentedContainerSm: {
-      minHeight: CONTROL_HEIGHTS.compact,
+      minHeight: CONTROL_HEIGHTS.sm,
       padding: 0,
     },
     segmentedContainerMd: {
-      minHeight: CONTROL_HEIGHTS.field,
+      minHeight: CONTROL_HEIGHTS.md,
       padding: 0,
     },
-    segmentedSegmentXs: {
-      minHeight: CONTROL_HEIGHTS.tight - SEGMENTED_TIGHT_INSET * 2,
-      paddingHorizontal: theme.spacing[2],
-      borderRadius: theme.borderRadius.xl,
-    },
     segmentedSegmentSm: {
-      minHeight: CONTROL_HEIGHTS.compact - SEGMENTED_COMPACT_INSET * 2,
+      minHeight: mapLayout(CONTROL_HEIGHTS.sm, (height) => height - SEGMENTED_INSET * 2),
       paddingHorizontal: theme.spacing[2],
-      borderRadius: theme.borderRadius.xl,
+      borderRadius: theme.borderRadius.full,
     },
     segmentedSegmentMd: {
-      minHeight: CONTROL_HEIGHTS.field - SEGMENTED_FIELD_INSET * 2,
+      minHeight: mapLayout(CONTROL_HEIGHTS.md, (height) => height - SEGMENTED_INSET * 2),
       paddingHorizontal: theme.spacing[3],
-      borderRadius: theme.borderRadius["2xl"],
-    },
-    segmentedLabelXs: {
-      fontSize: theme.fontSize.sm,
+      borderRadius: theme.borderRadius.full,
     },
     segmentedLabelSm: {
-      fontSize: theme.fontSize.base,
+      fontSize: theme.fontSize.sm,
     },
     segmentedLabelMd: {
       fontSize: theme.fontSize.base,
diff --git a/packages/app/src/components/ui/control-size.tsx b/packages/app/src/components/ui/control-size.tsx
index c6bcbbea78..a6a4bcb389 100644
--- a/packages/app/src/components/ui/control-size.tsx
+++ b/packages/app/src/components/ui/control-size.tsx
@@ -1,23 +1,21 @@
 import { createContext, useContext, type ReactNode } from "react";
-
-/** The control sizes a container can ask of the controls placed in it. */
-export type ContainedControlSize = "xs" | "sm";
+import type { ControlSize } from "@/components/ui/control-geometry";
 
 // A row decides how big its controls are, so a button or field placed in it needs no size of
 // its own. A size passed to the control still wins.
-const ControlSizeContext = createContext<ContainedControlSize | null>(null);
+const ControlSizeContext = createContext<ControlSize | null>(null);
 
 export function ControlSizeProvider({
   size,
   children,
 }: {
-  size: ContainedControlSize;
+  size: ControlSize;
   children: ReactNode;
 }) {
   return <ControlSizeContext.Provider value={size}>{children}</ControlSizeContext.Provider>;
 }
 
 /** The size the surrounding container asks for, or null outside one. */
-export function useContainedControlSize(): ContainedControlSize | null {
+export function useContainedControlSize(): ControlSize | null {
   return useContext(ControlSizeContext);
 }
diff --git a/packages/app/src/components/ui/control-sizing.ts b/packages/app/src/components/ui/control-sizing.ts
new file mode 100644
index 0000000000..6dc371af76
--- /dev/null
+++ b/packages/app/src/components/ui/control-sizing.ts
@@ -0,0 +1,68 @@
+import { hasTouchScreen } from "@/hooks/pointer-capabilities";
+
+// The sizing gate, apart from the control sizes so that low-level modules such as
+// `constants/layout` can size by it without loading the theme. Import it through
+// `@/components/ui/control-geometry`, which re-exports it.
+
+/**
+ * Every size comes in a touch value and a pointer value. Touch values follow Apple's Human
+ * Interface Guidelines for iOS and iPadOS: a 44pt default control and hit region, nothing
+ * smaller than its 28pt minimum. Pointer values sit one step down the same button ladder.
+ */
+export type ControlSizing = "touch" | "pointer";
+
+export interface ControlSizingFacts {
+  /** The layout is below the `md` breakpoint. */
+  compactLayout: boolean;
+  /** The device has a touch screen; see `hasTouchScreen`. */
+  touchScreen: boolean;
+}
+
+/**
+ * The one sizing gate: touch-sized in the compact layout or on any device with a touch screen,
+ * pointer-sized otherwise. A touch screen keeps touch sizing when a mouse or keyboard is attached.
+ */
+export function resolveControlSizing({
+  compactLayout,
+  touchScreen,
+}: ControlSizingFacts): ControlSizing {
+  if (compactLayout || touchScreen) return "touch";
+  return "pointer";
+}
+
+// Read once, so attaching a mouse or keyboard later never flips the sizing.
+const DEVICE_HAS_TOUCH_SCREEN = hasTouchScreen();
+
+/** The sizing on this device for a layout, for code that sizes outside a stylesheet. */
+export function controlSizingForLayout(compactLayout: boolean): ControlSizing {
+  return resolveControlSizing({ compactLayout, touchScreen: DEVICE_HAS_TOUCH_SCREEN });
+}
+
+/** A Unistyles breakpoint value: one number in the compact layout, another from `md` up. */
+// A mapped type, not an interface: Unistyles checks breakpoint objects against an index
+// signature, which interfaces never satisfy.
+export type LayoutValue = Record<"xs" | "md", number>;
+
+export type SizingValue = Record<ControlSizing, number>;
+
+/**
+ * A size as a Unistyles breakpoint value. The compact layout always takes the touch value; from
+ * `md` up the device decides.
+ */
+export function bySizing(
+  sizes: SizingValue,
+  touchScreen: boolean = DEVICE_HAS_TOUCH_SCREEN,
+): LayoutValue {
+  return {
+    xs: sizes[resolveControlSizing({ compactLayout: true, touchScreen })],
+    md: sizes[resolveControlSizing({ compactLayout: false, touchScreen })],
+  };
+}
+
+/** Derives a breakpoint value from another, such as a row as tall as its control plus padding. */
+export function mapLayout(value: LayoutValue, map: (height: number) => number): LayoutValue {
+  return { xs: map(value.xs), md: map(value.md) };
+}
+
+/** The smallest touch target, and the size of every touch-sized icon button, row, and bar. */
+export const TOUCH_TARGET = 44;
diff --git a/packages/app/src/components/ui/dropdown-trigger.tsx b/packages/app/src/components/ui/dropdown-trigger.tsx
index a276e40652..7504bbece4 100644
--- a/packages/app/src/components/ui/dropdown-trigger.tsx
+++ b/packages/app/src/components/ui/dropdown-trigger.tsx
@@ -1,11 +1,11 @@
 import { useCallback, useMemo, type ReactElement, type ReactNode } from "react";
-import { Text, View, type ViewStyle } from "react-native";
+import { Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { ChevronDown } from "lucide-react-native";
 import {
-  buttonIconSize,
+  controlIconSize,
   createControlGeometry,
-  type ButtonControlSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
 import { DropdownMenuTrigger, type DropdownMenuTriggerProps } from "@/components/ui/dropdown-menu";
@@ -22,7 +22,7 @@ interface DropdownTriggerProps extends Omit<DropdownMenuTriggerProps, "children"
   children: string;
   /** Icon or swatch before the label. */
   leading?: ReactNode;
-  size?: ButtonControlSize;
+  size?: ControlSize;
 }
 
 /**
@@ -38,17 +38,8 @@ export function DropdownTrigger({
   ...props
 }: DropdownTriggerProps): ReactElement {
   const containedSize = useContainedControlSize();
-  const size = sizeProp ?? containedSize ?? "sm";
-  let sizeStyle: ViewStyle;
-  if (size === "xs") {
-    sizeStyle = styles.xs;
-  } else if (size === "md") {
-    sizeStyle = styles.md;
-  } else if (size === "lg") {
-    sizeStyle = styles.lg;
-  } else {
-    sizeStyle = styles.sm;
-  }
+  const size = sizeProp ?? containedSize ?? "md";
+  const sizeStyle = size === "sm" ? styles.sm : styles.md;
   const triggerStyle = useCallback(
     ({ pressed }: { pressed: boolean }) => [
       styles.base,
@@ -58,7 +49,7 @@ export function DropdownTrigger({
     ],
     [disabled, sizeStyle],
   );
-  const labelStyle = useMemo(() => [styles.label, size === "xs" && styles.labelXs], [size]);
+  const labelStyle = useMemo(() => [styles.label, size === "sm" && styles.labelSm], [size]);
 
   return (
     <DropdownMenuTrigger {...props} disabled={disabled} style={triggerStyle}>
@@ -67,7 +58,7 @@ export function DropdownTrigger({
         {children}
       </Text>
       <View style={styles.chevron}>
-        <ThemedChevronDown size={buttonIconSize[size]} uniProps={chevronColorMapping} />
+        <ThemedChevronDown size={controlIconSize[size]} uniProps={chevronColorMapping} />
       </View>
     </DropdownMenuTrigger>
   );
@@ -84,10 +75,8 @@ const styles = StyleSheet.create((theme) => {
       borderColor: theme.colors.borderAccent,
       backgroundColor: "transparent",
     },
-    xs: geometry.buttonXs,
     sm: geometry.buttonSm,
     md: geometry.buttonMd,
-    lg: geometry.buttonLg,
     pressed: {
       opacity: 0.85,
     },
@@ -97,9 +86,9 @@ const styles = StyleSheet.create((theme) => {
     label: {
       flexShrink: 1,
       color: theme.colors.foreground,
-      ...geometry.buttonText,
+      ...geometry.buttonTextMd,
     },
-    labelXs: geometry.buttonTextXs,
+    labelSm: geometry.buttonTextSm,
     chevron: {
       transform: [{ translateY: 1 }],
     },
diff --git a/packages/app/src/components/ui/external-link.tsx b/packages/app/src/components/ui/external-link.tsx
index a29018b042..cdf98fc0fc 100644
--- a/packages/app/src/components/ui/external-link.tsx
+++ b/packages/app/src/components/ui/external-link.tsx
@@ -1,5 +1,5 @@
 import { useCallback, type ReactNode } from "react";
-import { Pressable, Text } from "react-native";
+import { Pressable, Text, View, type PressableStateCallbackType } from "react-native";
 import { ArrowUpRight } from "lucide-react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
@@ -41,10 +41,10 @@ export function ExternalLink({
       accessibilityRole="link"
       accessibilityLabel={accessibilityLabel ?? label}
       testID={testID}
-      style={styles.trigger}
     >
-      <Text style={styles.label}>{children ?? label}</Text>
-      <ThemedArrowUpRight size={12} uniProps={iconColor} />
+      {({ hovered }: PressableStateCallbackType & { hovered?: boolean }) => (
+        <ExternalLinkLabel hovered={hovered}>{children ?? label}</ExternalLinkLabel>
+      )}
     </Pressable>
   );
 
@@ -62,7 +62,27 @@ export function ExternalLink({
   );
 }
 
+/**
+ * What an external link looks like: muted text and an outward arrow, both turning foreground on
+ * hover. For a pressable that owns its own hover, such as a settings row that opens a page.
+ */
+export function ExternalLinkLabel({
+  hovered = false,
+  children,
+}: {
+  hovered?: boolean;
+  children?: ReactNode;
+}) {
+  return (
+    <View style={styles.trigger}>
+      {children ? <Text style={[styles.label, hovered && styles.hovered]}>{children}</Text> : null}
+      <ThemedArrowUpRight size={12} uniProps={hovered ? hoveredIconColor : iconColor} />
+    </View>
+  );
+}
+
 const iconColor = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+const hoveredIconColor = (theme: Theme) => ({ color: theme.colors.foreground });
 const ThemedArrowUpRight = withUnistyles(ArrowUpRight);
 
 const styles = StyleSheet.create((theme) => ({
@@ -75,6 +95,9 @@ const styles = StyleSheet.create((theme) => ({
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.sm,
   },
+  hovered: {
+    color: theme.colors.foreground,
+  },
   tooltipText: {
     color: theme.colors.foreground,
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/components/ui/form-field.tsx b/packages/app/src/components/ui/form-field.tsx
index 349d658e4f..a85d9a2712 100644
--- a/packages/app/src/components/ui/form-field.tsx
+++ b/packages/app/src/components/ui/form-field.tsx
@@ -21,18 +21,15 @@ import type { EditingTextInputHandle } from "@/components/ui/text-input";
 import {
   createControlGeometry,
   resolveControlInteractionStyles,
-  type FieldControlSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import { useContainedControlSize } from "@/components/ui/control-size";
 
-const FIELD_CHROME = { xs: "chromeXs", sm: "chromeSm", md: "chromeMd" } as const satisfies Record<
-  FieldControlSize,
-  string
->;
-const FIELD_TEXT = { xs: "inputXs", sm: "inputSm", md: "inputMd" } as const satisfies Record<
-  FieldControlSize,
+const FIELD_CHROME = { sm: "chromeSm", md: "chromeMd" } as const satisfies Record<
+  ControlSize,
   string
 >;
+const FIELD_TEXT = { sm: "inputSm", md: "inputMd" } as const satisfies Record<ControlSize, string>;
 
 interface FieldProps {
   label: string;
@@ -77,7 +74,7 @@ export function Field({ label, children, trailing, hint, error, testID }: FieldP
 }
 
 type FormTextInputProps = AdaptiveTextInputProps & {
-  size?: FieldControlSize;
+  size?: ControlSize;
 };
 
 type FlatFormTextInputStyle = ViewStyle & TextStyle;
@@ -274,9 +271,6 @@ const formInputStyles = StyleSheet.create((theme) => {
     chrome: {
       backgroundColor: theme.colors.surface2,
     },
-    chromeXs: {
-      ...geometry.fieldControlXs,
-    },
     chromeSm: {
       ...geometry.fieldControlSm,
     },
@@ -304,9 +298,6 @@ const formInputStyles = StyleSheet.create((theme) => {
       outlineColor: "transparent",
       outlineWidth: 0,
     },
-    inputXs: {
-      ...geometry.fieldTextXs,
-    },
     inputSm: {
       ...geometry.fieldTextSm,
     },
diff --git a/packages/app/src/components/ui/horizontal-scroll-boundary.tsx b/packages/app/src/components/ui/horizontal-scroll-boundary.tsx
index 046552787b..09c14d3e45 100644
--- a/packages/app/src/components/ui/horizontal-scroll-boundary.tsx
+++ b/packages/app/src/components/ui/horizontal-scroll-boundary.tsx
@@ -74,12 +74,15 @@ export function HorizontalScrollBoundaryShades({
   leftStyle,
   rightStyle,
   testIDPrefix = "horizontal-scroll-boundary",
+  bottomInset = 1,
 }: {
   visible: boolean;
   backdrop: "surface" | "sidebar";
   leftStyle: AnimatedStyle<{ opacity: number }>;
   rightStyle: AnimatedStyle<{ opacity: number }>;
   testIDPrefix?: string;
+  /** Set to 0 when the scrolled content's own border reaches the bottom edge and must fade too. */
+  bottomInset?: number;
 }) {
   if (!visible) return null;
   const colorMapping = backdrop === "sidebar" ? sidebarColorMapping : surfaceColorMapping;
@@ -88,14 +91,14 @@ export function HorizontalScrollBoundaryShades({
       <Animated.View
         pointerEvents="none"
         testID={`${testIDPrefix}-left`}
-        style={[styles.shade, styles.left, leftStyle]}
+        style={[styles.shade(bottomInset), styles.left, leftStyle]}
       >
         <ThemedScrollBoundaryShadeSvg side="left" uniProps={colorMapping} />
       </Animated.View>
       <Animated.View
         pointerEvents="none"
         testID={`${testIDPrefix}-right`}
-        style={[styles.shade, styles.right, rightStyle]}
+        style={[styles.shade(bottomInset), styles.right, rightStyle]}
       >
         <ThemedScrollBoundaryShadeSvg side="right" uniProps={colorMapping} />
       </Animated.View>
@@ -104,12 +107,12 @@ export function HorizontalScrollBoundaryShades({
 }
 
 const styles = StyleSheet.create(() => ({
-  shade: {
+  shade: (bottomInset: number) => ({
     position: "absolute",
     top: 0,
-    bottom: 1,
+    bottom: bottomInset,
     width: SHADE_WIDTH,
-  },
+  }),
   left: { left: 0 },
   right: { right: 0 },
 }));
diff --git a/packages/app/src/components/ui/hover-card.tsx b/packages/app/src/components/ui/hover-card.tsx
index fd81294f80..ecf4c59414 100644
--- a/packages/app/src/components/ui/hover-card.tsx
+++ b/packages/app/src/components/ui/hover-card.tsx
@@ -1,8 +1,10 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import {
   createContext,
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -14,29 +16,19 @@ import { Dimensions, View, type Role, type StyleProp, type ViewStyle } from "rea
 import { FadeIn, FadeOut } from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 import { Portal } from "@gorhom/portal";
-import {
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import { FloatingSurface } from "@/components/ui/floating";
-import {
-  measureFloatingPanelPortalHost,
-  useFloatingPanelPortalHostName,
-} from "@/components/ui/floating-panel-portal";
+import { useFloatingPanelPortalHostName } from "@/components/ui/floating-panel-portal";
 import { isWeb } from "@/constants/platform";
 import { useHoverSafeZone } from "@/hooks/use-hover-safe-zone";
-import {
-  computePosition,
-  measureElement,
-  type Alignment,
-  type Placement,
-  type Rect,
-  type Size,
-} from "./anchor";
+import { computePosition, type Alignment, type Placement, type Rect } from "./anchor";
 
 const CLOSE_GRACE_MS = 100;
 
+// One card per layer: moving onto a sibling trigger replaces the open card instead of stacking
+// a second one beside it for the grace period. Nested cards open on a higher layer.
+const openCardCloseByLayer = new Map<number, () => void>();
+
 interface HoverCardContextValue {
   open: boolean;
   layer: number;
@@ -119,15 +111,29 @@ function WebHoverCard({
     }, CLOSE_GRACE_MS);
   }, [keyboardFocusInside]);
 
+  const closeNow = useCallback(() => {
+    clearGraceTimer();
+    setOpen(false);
+  }, [clearGraceTimer]);
+
   const openNow = useCallback(() => {
     clearGraceTimer();
-    if (!disabled) {
-      setOpen(true);
-    }
-  }, [clearGraceTimer, disabled]);
+    if (disabled) return;
+    const openSibling = openCardCloseByLayer.get(layer);
+    if (openSibling && openSibling !== closeNow) openSibling();
+    openCardCloseByLayer.set(layer, closeNow);
+    setOpen(true);
+  }, [clearGraceTimer, closeNow, disabled, layer]);
+
+  useEffect(() => {
+    if (!open) return;
+    return () => {
+      if (openCardCloseByLayer.get(layer) === closeNow) openCardCloseByLayer.delete(layer);
+    };
+  }, [closeNow, layer, open]);
 
   const keyPressed = useCallback(
-    (event: KeyboardEvent): boolean => {
+    (event: KeyboardInputEvent): boolean => {
       if (!isWeb) return false;
       const trigger = triggerRef.current as unknown as HTMLElement | null;
       if (!trigger) return false;
@@ -139,7 +145,7 @@ function WebHoverCard({
         return true;
       } else if (
         focusInside() &&
-        event.target === trigger &&
+        document.activeElement === trigger &&
         ["ArrowDown", "Enter", " "].includes(event.key)
       ) {
         event.preventDefault();
@@ -158,7 +164,8 @@ function WebHoverCard({
     [clearGraceTimer, focusInside, open, openNow],
   );
 
-  const setOverlayScope = useWebOverlayRegistration({
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
     active: !disabled && open,
     layer,
     onKeyDown: keyPressed,
@@ -210,9 +217,9 @@ function WebHoverCard({
       )
         keyPressed(event);
     };
+    // Only a scroll that moves the trigger detaches the card. A streaming chat beside it does not.
     const scrolled = (event: Event) => {
-      if (!(contentRef.current as unknown as HTMLElement | null)?.contains(event.target as Node))
-        close();
+      if ((event.target as Node).contains(trigger)) close();
     };
     document.addEventListener("focusin", focusEntered);
     document.addEventListener("focusout", focusLeft);
@@ -301,17 +308,40 @@ interface HoverCardContentProps {
 
 export function HoverCardContent(props: HoverCardContentProps): ReactElement | null {
   const ctx = useContext(HoverCardContext);
+  const portalHostName = useFloatingPanelPortalHostName();
   if (!ctx?.open) return null;
   return (
-    <HoverCardSurface
-      {...props}
-      layer={ctx.layer}
-      triggerRef={ctx.triggerRef}
-      contentRef={ctx.contentRef}
-    />
+    <Portal hostName={portalHostName}>
+      <HoverCardSurface
+        {...props}
+        layer={ctx.layer}
+        triggerRef={ctx.triggerRef}
+        contentRef={ctx.contentRef}
+      />
+    </Portal>
   );
 }
 
+// A card above its trigger holds its bottom edge, so content that loads while it is open grows it
+// upward without a correction. Anchored by its top, it would paint over the trigger until placed.
+type CardPosition = { left: number; top: number } | { left: number; bottom: number };
+
+function isSamePosition(current: CardPosition | null, next: CardPosition): boolean {
+  if (!current || current.left !== next.left) return false;
+  return "top" in current
+    ? "top" in next && current.top === next.top
+    : "bottom" in next && current.bottom === next.bottom;
+}
+
+function readDomRect(view: View | null): Rect | null {
+  const element = view as unknown as HTMLElement | null;
+  if (!element) return null;
+  const { x, y, width, height } = element.getBoundingClientRect();
+  return { x, y, width, height };
+}
+
+// Rendered inside the portal so the card is placed in the commit that mounts it: the first
+// painted frame already sits beside the trigger. Web-only, like the rest of the open card.
 function HoverCardSurface({
   layer,
   triggerRef,
@@ -329,78 +359,61 @@ function HoverCardSurface({
   triggerRef: RefObject<View | null>;
   contentRef: RefObject<View | null>;
 }): ReactElement {
-  const portalHostName = useFloatingPanelPortalHostName();
-  const [anchor, setAnchor] = useState<{ triggerRect: Rect; hostRect: Rect } | null>(null);
-  const [contentSize, setContentSize] = useState<Size | null>(null);
-  const [position, setPosition] = useState<{ x: number; y: number } | null>(null);
+  const overlayRef = useRef<View>(null);
+  const [position, setPosition] = useState<CardPosition | null>(null);
 
-  useEffect(() => {
-    if (!triggerRef.current) return;
-    let cancelled = false;
-    void Promise.all([
-      measureElement(triggerRef.current),
-      measureFloatingPanelPortalHost(portalHostName),
-    ]).then(([triggerRect, hostRect]) => {
-      if (!cancelled && hostRect) setAnchor({ triggerRect, hostRect });
-      return undefined;
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [portalHostName, triggerRef]);
-
-  useEffect(() => {
-    if (!anchor || !contentSize) return;
+  const place = useCallback(() => {
+    const triggerRect = readDomRect(triggerRef.current);
+    const overlayRect = readDomRect(overlayRef.current);
+    const content = contentRef.current as unknown as HTMLElement | null;
+    if (!triggerRect || !overlayRect || !content) return;
     const { width, height } = Dimensions.get("window");
-    const { x, y } = computePosition({
-      triggerRect: anchor.triggerRect,
-      contentSize,
+    const { x, y, actualPlacement } = computePosition({
+      triggerRect,
+      contentSize: { width: content.offsetWidth, height: content.offsetHeight },
       displayArea: { x: 0, y: 0, width, height },
       placement,
       flipHorizontal: true,
       alignment,
       offset,
     });
-    setPosition({ x: x - anchor.hostRect.x, y: y - anchor.hostRect.y });
-  }, [alignment, anchor, contentSize, offset, placement]);
+    const left = x - overlayRect.x;
+    const next: CardPosition =
+      actualPlacement === "top"
+        ? { left, bottom: overlayRect.height - (y + content.offsetHeight - overlayRect.y) }
+        : { left, top: y - overlayRect.y };
+    setPosition((current) => (isSamePosition(current, next) ? current : next));
+  }, [alignment, contentRef, offset, placement, triggerRef]);
 
-  const handleLayout = useCallback(
-    (event: { nativeEvent: { layout: { width: number; height: number } } }) => {
-      const { width, height } = event.nativeEvent.layout;
-      setContentSize({ width, height });
-    },
-    [],
-  );
+  useLayoutEffect(place, [place]);
 
   const frameStyle = useMemo(
-    () => ({
-      position: "absolute" as const,
-      top: position?.y ?? -9999,
-      left: position?.x ?? -9999,
-    }),
-    [position?.x, position?.y],
+    () => ({ position: "absolute" as const, ...(position ?? { top: -9999, left: -9999 }) }),
+    [position],
   );
   const surfaceStyle = useMemo(() => [styles.surface, style], [style]);
 
   return (
-    <Portal hostName={portalHostName}>
-      <View pointerEvents="box-none" style={[styles.portalOverlay, { zIndex: layer }]}>
-        <FloatingSurface
-          ref={contentRef}
-          entering={FadeIn.duration(80)}
-          exiting={FadeOut.duration(80)}
-          collapsable={false}
-          onLayout={handleLayout}
-          role={role}
-          accessibilityLabel={accessibilityLabel}
-          testID={testID}
-          style={surfaceStyle}
-          frameStyle={frameStyle}
-        >
-          {children}
-        </FloatingSurface>
-      </View>
-    </Portal>
+    <View
+      ref={overlayRef}
+      pointerEvents="box-none"
+      style={[styles.portalOverlay, { zIndex: layer }]}
+    >
+      <FloatingSurface
+        ref={contentRef}
+        entering={FadeIn.duration(80)}
+        exiting={FadeOut.duration(80)}
+        collapsable={false}
+        onLayout={place}
+        role={role}
+        accessibilityLabel={accessibilityLabel}
+        testID={testID}
+        style={surfaceStyle}
+        frameStyle={frameStyle}
+      >
+        {children}
+      </FloatingSurface>
+    </View>
   );
 }
 
diff --git a/packages/app/src/components/ui/icon-button-chrome.ts b/packages/app/src/components/ui/icon-button-chrome.ts
index 75735ac986..42ba47a80a 100644
--- a/packages/app/src/components/ui/icon-button-chrome.ts
+++ b/packages/app/src/components/ui/icon-button-chrome.ts
@@ -1,17 +1,24 @@
 import { createContext, useCallback, useContext } from "react";
 import type { StyleProp, ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import {
+  bySizing,
+  controlSizingForLayout,
+  ICON_BUTTON_SIZES,
+  TOUCH_ICON_SIZE,
+  type SizingValue,
+} from "@/components/ui/control-geometry";
 import { ICON_SIZE } from "@/styles/theme";
 
 export { extraMutedIconColorMapping, mutedIconColorMapping } from "@/components/ui/icon-color";
 
 export type IconButtonChromeSize = "large" | "small";
 
-const SMALL_ICON_BUTTON_SIZE = 20;
-/** Width and height of a large icon button on compact layouts. */
-export const COMPACT_LARGE_ICON_BUTTON_SIZE = 32;
-const COMPACT_SMALL_ICON_BUTTON_SIZE = 32;
+// Touch-sized, every icon button is one target with one glyph size.
+const GLYPH_SIZES = {
+  large: { touch: TOUCH_ICON_SIZE.md, pointer: ICON_SIZE.md },
+  small: { touch: TOUCH_ICON_SIZE.md, pointer: ICON_SIZE.sm },
+} satisfies Record<IconButtonChromeSize, SizingValue>;
 
 export interface IconButtonChromeState {
   hovered?: boolean;
@@ -22,7 +29,7 @@ export interface IconButtonChromeState {
 
 function resolveIconButtonFrame(size: IconButtonChromeSize, compact: boolean) {
   if (size === "large") return styles.large;
-  return compact ? styles.smallCompact : styles.small;
+  return controlSizingForLayout(compact) === "touch" ? styles.smallTouch : styles.small;
 }
 
 interface IconButtonChromeOptions {
@@ -92,24 +99,17 @@ export function iconButtonChromeFrameStyle(
 }
 
 export function iconButtonChromeGlyphSize(size: IconButtonChromeSize, compact = false): number {
-  if (size === "large") return ICON_SIZE.md;
-  return compact ? 18 : 14;
+  return GLYPH_SIZES[size][controlSizingForLayout(compact)];
 }
 
 export function smallIconButtonChromeFrameSize(compact = false): number {
-  return compact ? COMPACT_SMALL_ICON_BUTTON_SIZE : SMALL_ICON_BUTTON_SIZE;
+  return ICON_BUTTON_SIZES.small[controlSizingForLayout(compact)];
 }
 
 const styles = StyleSheet.create((theme) => ({
   large: {
-    width: {
-      xs: COMPACT_LARGE_ICON_BUTTON_SIZE,
-      md: HEADER_CONTROL_HEIGHT,
-    },
-    height: {
-      xs: COMPACT_LARGE_ICON_BUTTON_SIZE,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: bySizing(ICON_BUTTON_SIZES.large),
+    height: bySizing(ICON_BUTTON_SIZES.large),
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
@@ -119,8 +119,8 @@ const styles = StyleSheet.create((theme) => ({
     outlineColor: "transparent",
   },
   small: {
-    width: SMALL_ICON_BUTTON_SIZE,
-    height: SMALL_ICON_BUTTON_SIZE,
+    width: ICON_BUTTON_SIZES.small.pointer,
+    height: ICON_BUTTON_SIZES.small.pointer,
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
@@ -129,9 +129,9 @@ const styles = StyleSheet.create((theme) => ({
     outlineWidth: 0,
     outlineColor: "transparent",
   },
-  smallCompact: {
-    width: COMPACT_SMALL_ICON_BUTTON_SIZE,
-    height: COMPACT_SMALL_ICON_BUTTON_SIZE,
+  smallTouch: {
+    width: ICON_BUTTON_SIZES.small.touch,
+    height: ICON_BUTTON_SIZES.small.touch,
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
diff --git a/packages/app/src/components/ui/isolated-bottom-sheet-modal/index.tsx b/packages/app/src/components/ui/isolated-bottom-sheet-modal/index.tsx
index 639804bd53..2498ed2a7b 100644
--- a/packages/app/src/components/ui/isolated-bottom-sheet-modal/index.tsx
+++ b/packages/app/src/components/ui/isolated-bottom-sheet-modal/index.tsx
@@ -5,6 +5,7 @@ import {
 } from "@gorhom/bottom-sheet";
 import React from "react";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef } from "react";
+import { useDismissibleOverlay } from "@/components/ui/overlay-dismissal";
 import type { ElementRef, ReactNode } from "react";
 import { systemBackPress } from "./back-press";
 import {
@@ -163,6 +164,7 @@ export function useIsolatedBottomSheetVisibility({
   useEffect(() => {
     tracker.syncDesired({ visible, isEnabled });
   }, [isEnabled, tracker, visible]);
+  useDismissibleOverlay(visible && isEnabled !== false, onClose);
 
   return {
     sheetRef: setSheetRef,
diff --git a/packages/app/src/components/ui/menu/keyboard-navigation.ts b/packages/app/src/components/ui/menu/keyboard-navigation.ts
new file mode 100644
index 0000000000..ca0d854436
--- /dev/null
+++ b/packages/app/src/components/ui/menu/keyboard-navigation.ts
@@ -0,0 +1,4 @@
+import type { KeyboardInputEvent } from "@/keyboard";
+export function navigateMenuKeyboard(_event: KeyboardInputEvent): boolean {
+  return false;
+}
diff --git a/packages/app/src/components/ui/menu/keyboard-navigation.web.ts b/packages/app/src/components/ui/menu/keyboard-navigation.web.ts
new file mode 100644
index 0000000000..ba2dd1f1e5
--- /dev/null
+++ b/packages/app/src/components/ui/menu/keyboard-navigation.web.ts
@@ -0,0 +1,37 @@
+import type { KeyboardInputEvent } from "@/keyboard";
+export function navigateMenuKeyboard(event: KeyboardInputEvent): boolean {
+  const target = document.activeElement;
+  const surface = target?.closest<HTMLElement>('[data-menu-surface="true"]');
+  if (!surface) return false;
+  const items = Array.from(
+    surface.querySelectorAll<HTMLElement>(
+      '[data-menu-item="true"]:not([data-menu-disabled="true"])',
+    ),
+  );
+  if (items.length === 0) return false;
+  const currentIndex = items.findIndex((item) => item === document.activeElement);
+  let nextIndex: number | null = null;
+  if (event.key === "ArrowDown") {
+    if (currentIndex < 0) nextIndex = 0;
+    else nextIndex = (currentIndex + 1) % items.length;
+  }
+  if (event.key === "ArrowUp") {
+    if (currentIndex < 0) nextIndex = items.length - 1;
+    else nextIndex = (currentIndex - 1 + items.length) % items.length;
+  }
+  if (event.key === "Home") nextIndex = 0;
+  if (event.key === "End") nextIndex = items.length - 1;
+  if (nextIndex !== null) {
+    event.preventDefault();
+    event.stopPropagation();
+    items[nextIndex]?.focus();
+    return true;
+  }
+  if ((event.key === "Enter" || event.key === " ") && currentIndex >= 0) {
+    event.preventDefault();
+    event.stopPropagation();
+    items[currentIndex]?.click();
+    return true;
+  }
+  return false;
+}
diff --git a/packages/app/src/components/ui/menu/menu-context.ts b/packages/app/src/components/ui/menu/menu-context.ts
index 502580c308..69c1dfa191 100644
--- a/packages/app/src/components/ui/menu/menu-context.ts
+++ b/packages/app/src/components/ui/menu/menu-context.ts
@@ -11,6 +11,7 @@ import {
   type MenuPath,
 } from "./menu-navigation";
 import type { Rect } from "../anchor";
+import { useDismissibleOverlay } from "../overlay-dismissal";
 
 /**
  * How a menu draws itself once it is open.
@@ -117,6 +118,7 @@ export function useMenuState({
 
   const [isOpen, setIsOpenState] = useControllableOpenState({ open, defaultOpen, onOpenChange });
   useDismissKeyboardOnOpen(isOpen);
+  useDismissibleOverlay(isOpen, () => setOpen(false));
 
   // A menu always reopens on its root page, against a freshly measured anchor. Keeping either
   // would reopen the surface three levels deep, or at the coordinates of the last right click.
diff --git a/packages/app/src/components/ui/menu/menu-geometry.ts b/packages/app/src/components/ui/menu/menu-geometry.ts
index 089f4afa67..b0b53e697e 100644
--- a/packages/app/src/components/ui/menu/menu-geometry.ts
+++ b/packages/app/src/components/ui/menu/menu-geometry.ts
@@ -1,2 +1,5 @@
 /** Shared geometry for menu rows and controls that align with them. */
-export const MENU_ITEM_HEIGHT = { xs: 40, md: 28 } as const;
+import { density } from "@/styles/density";
+
+/** A menu row is a tight row: touch-sized wherever controls are (see `resolveControlSizing`). */
+export const MENU_ITEM_HEIGHT = density.tightRowHeight;
diff --git a/packages/app/src/components/ui/menu/menu-overlay.tsx b/packages/app/src/components/ui/menu/menu-overlay.tsx
index 3979c5b633..0058cacfe5 100644
--- a/packages/app/src/components/ui/menu/menu-overlay.tsx
+++ b/packages/app/src/components/ui/menu/menu-overlay.tsx
@@ -1,3 +1,5 @@
+import { navigateMenuKeyboard } from "./keyboard-navigation";
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
 import { Modal } from "@/components/ui/modal";
 import {
   useCallback,
@@ -24,20 +26,19 @@ import { StyleSheet } from "react-native-unistyles";
 import { FloatingScrollView, FloatingSurface } from "@/components/ui/floating";
 import { isWeb } from "@/constants/platform";
 import type { KeyboardFocusScope } from "@/keyboard/actions";
-import {
-  getOverlayRoot,
-  OverlayLayerProvider,
-  useOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import {
   computePosition,
+  fitSurfaceWidth,
   getTransformOrigin,
+  holdSurfaceEdge,
   measureElement,
+  surfaceFrameStyles,
   type Alignment,
   type Placement,
   type Rect,
   type Size,
+  type SurfacePosition,
 } from "../anchor";
 
 const SCROLL_CONTENT_STYLE = { flexGrow: 1 } as const;
@@ -111,7 +112,7 @@ export function useAnchoredPosition({
 }) {
   const [triggerRect, setTriggerRect] = useState<Rect | null>(null);
   const [contentSize, setContentSize] = useState<Size | null>(null);
-  const [position, setPosition] = useState<{ x: number; y: number } | null>(null);
+  const [position, setPosition] = useState<SurfacePosition | null>(null);
   const [actualPlacement, setActualPlacement] = useState<Placement>(side);
 
   const visibleContentSize = useMemo(() => {
@@ -176,7 +177,7 @@ export function useAnchoredPosition({
       offset,
     });
 
-    setPosition({ x: result.x, y: result.y });
+    setPosition(holdSurfaceEdge(result, visibleContentSize.height));
     setActualPlacement(result.actualPlacement);
   }, [triggerRect, visibleContentSize, side, align, offset]);
 
@@ -282,21 +283,17 @@ export function AnchoredSurface({
     return () => cancelAnimationFrame(frame);
   }, [open, placed, surfaceNativeID]);
 
+  const frame = useMemo(() => surfaceFrameStyles(position), [position]);
   const frameStyle = useMemo<StyleProp<ViewStyle>>(() => {
     const { width: screenWidth } = Dimensions.get("window");
     const resolvedWidthStyle: ViewStyle = fullWidth
       ? { width: screenWidth - horizontalPadding * 2 }
-      : {
-          ...(typeof width === "number" ? { width } : null),
-          ...(typeof minWidth === "number" ? { minWidth } : null),
-          ...(typeof maxWidth === "number" ? { maxWidth } : null),
-        };
+      : fitSurfaceWidth({ width, minWidth, maxWidth }, screenWidth);
     return [
       resolvedWidthStyle,
+      frame.surface,
       {
-        position: "absolute" as const,
-        top: position?.y ?? -9999,
-        left: fullWidth ? horizontalPadding : (position?.x ?? -9999),
+        ...(fullWidth ? { left: horizontalPadding } : null),
         transformOrigin: getTransformOrigin(actualPlacement, align),
       },
     ];
@@ -306,8 +303,7 @@ export function AnchoredSurface({
     width,
     minWidth,
     maxWidth,
-    position?.x,
-    position?.y,
+    frame.surface,
     actualPlacement,
     align,
   ]);
@@ -349,40 +345,42 @@ export function AnchoredSurface({
           testID={testID ? `${testID}-backdrop` : undefined}
         />
       ) : null}
-      <FloatingSurface
-        key={placed ? "placed" : "measuring"}
-        collapsable={false}
-        tabIndex={-1}
-        nativeID={surfaceNativeID}
-        testID={testID}
-        dataSet={surfaceDataSet}
-        style={styles.content}
-        frameStyle={frameStyle}
-        entering={placed ? nativeContentEntering : undefined}
-        exiting={
-          !placed || isWeb || !onExited
-            ? undefined
-            : contentExiting.withCallback((finished) => {
-                "worklet";
-                if (finished) {
-                  runOnJS(onExited)();
-                }
-              })
-        }
-      >
-        {scrollable ? (
-          <FloatingScrollView
-            bounces={false}
-            showsVerticalScrollIndicator
-            style={scrollViewportStyle}
-            contentContainerStyle={SCROLL_CONTENT_STYLE}
-          >
-            {measured}
-          </FloatingScrollView>
-        ) : (
-          measured
-        )}
-      </FloatingSurface>
+      <View pointerEvents="box-none" style={frame.holder}>
+        <FloatingSurface
+          key={placed ? "placed" : "measuring"}
+          collapsable={false}
+          tabIndex={-1}
+          nativeID={surfaceNativeID}
+          testID={testID}
+          dataSet={surfaceDataSet}
+          style={styles.content}
+          frameStyle={frameStyle}
+          entering={placed ? nativeContentEntering : undefined}
+          exiting={
+            !placed || isWeb || !onExited
+              ? undefined
+              : contentExiting.withCallback((finished) => {
+                  "worklet";
+                  if (finished) {
+                    runOnJS(onExited)();
+                  }
+                })
+          }
+        >
+          {scrollable ? (
+            <FloatingScrollView
+              bounces={false}
+              showsVerticalScrollIndicator
+              style={scrollViewportStyle}
+              contentContainerStyle={SCROLL_CONTENT_STYLE}
+            >
+              {measured}
+            </FloatingScrollView>
+          ) : (
+            measured
+          )}
+        </FloatingSurface>
+      </View>
     </>
   );
 }
@@ -405,8 +403,8 @@ export function MenuOverlay({
 }): ReactElement | null {
   const floatingLayer = useOverlayLayer("floating");
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (event.key === "Escape") {
         event.preventDefault();
         event.stopPropagation();
@@ -414,44 +412,15 @@ export function MenuOverlay({
         return true;
       }
 
-      const target = event.target instanceof Element ? event.target : null;
-      const surface = target?.closest<HTMLElement>('[data-menu-surface="true"]');
-      if (!surface) return false;
-      const items = Array.from(
-        surface.querySelectorAll<HTMLElement>(
-          '[data-menu-item="true"]:not([data-menu-disabled="true"])',
-        ),
-      );
-      if (items.length === 0) return false;
-      const currentIndex = items.findIndex((item) => item === document.activeElement);
-      let nextIndex: number | null = null;
-      if (event.key === "ArrowDown")
-        nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % items.length;
-      if (event.key === "ArrowUp")
-        nextIndex =
-          currentIndex < 0 ? items.length - 1 : (currentIndex - 1 + items.length) % items.length;
-      if (event.key === "Home") nextIndex = 0;
-      if (event.key === "End") nextIndex = items.length - 1;
-      if (nextIndex !== null) {
-        event.preventDefault();
-        event.stopPropagation();
-        items[nextIndex]?.focus();
-        return true;
-      }
-      if ((event.key === "Enter" || event.key === " ") && currentIndex >= 0) {
-        event.preventDefault();
-        event.stopPropagation();
-        items[currentIndex]?.click();
-        return true;
-      }
-      return false;
+      return navigateMenuKeyboard(event);
     },
     [onClose],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && visible,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active: visible,
     layer: floatingLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
     restoreFocusRef,
   });
 
@@ -463,7 +432,7 @@ export function MenuOverlay({
         {...{
           onContextMenu: (event: { preventDefault?: () => void }) => event.preventDefault?.(),
         }}
-        ref={setWebOverlayScope}
+        ref={setOverlayScope}
         collapsable={false}
         style={[
           styles.overlay,
diff --git a/packages/app/src/components/ui/modal.tsx b/packages/app/src/components/ui/modal.tsx
index 884377fd8c..68ede2af37 100644
--- a/packages/app/src/components/ui/modal.tsx
+++ b/packages/app/src/components/ui/modal.tsx
@@ -1,13 +1,23 @@
-import { Modal as NativeModal, type ModalProps } from "react-native";
+import { Modal as NativeModal, type ModalProps as NativeModalProps } from "react-native";
+import { useDismissibleOverlay } from "@/components/ui/overlay-dismissal";
 
 // React Native defaults iPhone modals to portrait even when the app supports rotation.
-const orientations: NonNullable<ModalProps["supportedOrientations"]> = [
+const orientations: NonNullable<NativeModalProps["supportedOrientations"]> = [
   "portrait",
   "portrait-upside-down",
   "landscape-left",
   "landscape-right",
 ];
 
+type ModalProps = Omit<NativeModalProps, "onRequestClose"> & {
+  /** Back, Escape, and a composer taking focus all close the modal through this. */
+  onRequestClose?: () => void;
+};
+
+function noClose() {}
+
 export function Modal(props: ModalProps) {
+  const { visible = true, onRequestClose } = props;
+  useDismissibleOverlay(visible && onRequestClose !== undefined, onRequestClose ?? noClose);
   return <NativeModal supportedOrientations={orientations} {...props} />;
 }
diff --git a/packages/app/src/components/ui/overlay-dismissal.tsx b/packages/app/src/components/ui/overlay-dismissal.tsx
new file mode 100644
index 0000000000..44eb239e33
--- /dev/null
+++ b/packages/app/src/components/ui/overlay-dismissal.tsx
@@ -0,0 +1,90 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type PropsWithChildren,
+  type ReactElement,
+} from "react";
+
+interface OverlayDismissal {
+  register(close: () => void): () => void;
+  dismissAll(): Promise<void>;
+}
+
+interface OpenOverlay {
+  close: () => void;
+  /** Set once the overlay is asked to close; every caller waits on the same one. */
+  closing: { gone: Promise<void>; settle: () => void } | null;
+}
+
+function createOverlayDismissal(): OverlayDismissal {
+  const open = new Set<OpenOverlay>();
+
+  function dismiss(overlay: OpenOverlay): Promise<void> {
+    if (!overlay.closing) {
+      let settle = () => {};
+      const gone = new Promise<void>((resolve) => {
+        settle = resolve;
+      });
+      overlay.closing = { gone, settle };
+      overlay.close();
+    }
+    return overlay.closing.gone;
+  }
+
+  return {
+    register(close) {
+      const overlay: OpenOverlay = { close, closing: null };
+      open.add(overlay);
+      return () => {
+        open.delete(overlay);
+        overlay.closing?.settle();
+      };
+    },
+    dismissAll() {
+      // An overlay is gone in the commit that unregisters it. That commit can also move focus, such
+      // as a web modal handing it back to the button that opened it.
+      return Promise.all([...open].map(dismiss)).then(() => undefined);
+    },
+  };
+}
+
+const OverlayDismissalContext = createContext<OverlayDismissal | null>(null);
+
+/**
+ * A region that can close the sheets, menus and popovers opened from inside it. The composer is
+ * one: putting the cursor in it closes whatever it opened over itself. A scope inside another joins
+ * it, so a host widens the region by opening a scope around the composer and its neighbours.
+ */
+export function OverlayDismissalScope({ children }: PropsWithChildren): ReactElement {
+  const enclosing = useContext(OverlayDismissalContext);
+  const [own] = useState(createOverlayDismissal);
+  return (
+    <OverlayDismissalContext.Provider value={enclosing ?? own}>
+      {children}
+    </OverlayDismissalContext.Provider>
+  );
+}
+
+/** While `open`, the enclosing scope, if any, can close this overlay through `close`. */
+export function useDismissibleOverlay(open: boolean, close: () => void): void {
+  const scope = useContext(OverlayDismissalContext);
+  const closeRef = useRef(close);
+  closeRef.current = close;
+  useEffect(() => {
+    if (!scope || !open) return;
+    return scope.register(() => closeRef.current());
+  }, [scope, open]);
+}
+
+/**
+ * Closes every overlay open in the enclosing scope, and resolves once they are gone. Outside a
+ * scope there is nothing to close. A registered `close` must close the overlay.
+ */
+export function useDismissOverlays(): () => Promise<void> {
+  const scope = useContext(OverlayDismissalContext);
+  return useCallback(() => scope?.dismissAll() ?? Promise.resolve(), [scope]);
+}
diff --git a/packages/app/src/components/ui/segmented-control.tsx b/packages/app/src/components/ui/segmented-control.tsx
index d828c26c4d..05d7fedec4 100644
--- a/packages/app/src/components/ui/segmented-control.tsx
+++ b/packages/app/src/components/ui/segmented-control.tsx
@@ -4,8 +4,8 @@ import type { StyleProp, TextStyle, ViewStyle } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import {
   createControlGeometry,
-  segmentedIconSize,
-  type SegmentedControlSize,
+  controlIconSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import { useContainedControlSize } from "@/components/ui/control-size";
 import type { Theme } from "@/styles/theme";
@@ -24,7 +24,7 @@ interface SegmentedControlProps<T extends string> {
   options: SegmentedControlOption<T>[];
   value: T;
   onValueChange: (value: T) => void;
-  size?: SegmentedControlSize;
+  size?: ControlSize;
   hideLabels?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
@@ -57,14 +57,13 @@ export function SegmentedControl<T extends string>({
   const containedSize = useContainedControlSize();
   const size = sizeProp ?? containedSize ?? "md";
   const sizeStyles = {
-    xs: { container: styles.containerXs, segment: styles.segmentXs, label: styles.labelXs },
     sm: { container: styles.containerSm, segment: styles.segmentSm, label: styles.labelSm },
     md: { container: styles.containerMd, segment: styles.segmentMd, label: styles.labelMd },
   }[size];
   const containerSizeStyle = sizeStyles.container;
   const segmentSizeStyle = sizeStyles.segment;
   const labelSizeStyle = sizeStyles.label;
-  const iconSize = segmentedIconSize[size];
+  const iconSize = controlIconSize[size];
 
   const containerStyle = useMemo(
     () => [styles.container, containerSizeStyle, style],
@@ -173,9 +172,6 @@ const styles = StyleSheet.create((theme) => {
       backgroundColor: "transparent",
       gap: theme.spacing[1],
     },
-    containerXs: {
-      ...geometry.segmentedContainerXs,
-    },
     containerSm: {
       ...geometry.segmentedContainerSm,
     },
@@ -189,9 +185,6 @@ const styles = StyleSheet.create((theme) => {
       flexShrink: 0,
       gap: theme.spacing[1],
     },
-    segmentXs: {
-      ...geometry.segmentedSegmentXs,
-    },
     segmentSm: {
       ...geometry.segmentedSegmentSm,
     },
@@ -218,9 +211,6 @@ const styles = StyleSheet.create((theme) => {
       color: theme.colors.foregroundMuted,
       fontWeight: theme.fontWeight.normal,
     },
-    labelXs: {
-      ...geometry.segmentedLabelXs,
-    },
     labelSm: {
       ...geometry.segmentedLabelSm,
     },
diff --git a/packages/app/src/components/ui/select-field.tsx b/packages/app/src/components/ui/select-field.tsx
index a1228cb8e1..42af6786e3 100644
--- a/packages/app/src/components/ui/select-field.tsx
+++ b/packages/app/src/components/ui/select-field.tsx
@@ -13,7 +13,7 @@ import { Combobox, ComboboxItem, type ComboboxOption } from "@/components/ui/com
 import {
   createControlGeometry,
   resolveControlInteractionStyles,
-  type FieldControlSize,
+  type ControlSize,
 } from "@/components/ui/control-geometry";
 import { Field } from "@/components/ui/form-field";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
@@ -55,7 +55,7 @@ export interface SelectFieldProps<TValue> {
   searchable?: boolean;
   searchPlaceholder?: string;
   title?: string;
-  size?: FieldControlSize;
+  size?: ControlSize;
   getValueKey?: (value: TValue) => string;
   renderOption?: (input: SelectFieldRenderOptionInput<TValue>) => ReactElement;
   triggerLeading?: ReactNode;
@@ -75,7 +75,7 @@ export interface SelectFieldTriggerProps {
   disabled?: boolean;
   loading?: boolean;
   leading?: ReactNode;
-  size?: FieldControlSize;
+  size?: ControlSize;
   testID?: string;
 }
 
diff --git a/packages/app/src/components/ui/shortcut.tsx b/packages/app/src/components/ui/shortcut.tsx
index 6be0cf353e..3734902b8d 100644
--- a/packages/app/src/components/ui/shortcut.tsx
+++ b/packages/app/src/components/ui/shortcut.tsx
@@ -1,7 +1,7 @@
 import React, { useMemo, type ReactElement } from "react";
 import { Text, View, type StyleProp, type TextStyle, type ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent } from "@/keyboard";
 import { normalizeDisplayChord } from "@/components/ui/normalize-display-chord";
 import { formatShortcut, type ShortcutKey } from "@/utils/format-shortcut";
 import { getShortcutOs } from "@/utils/shortcut-platform";
@@ -17,7 +17,7 @@ export function Shortcut({
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
 }): ReactElement | null {
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent();
   const displayChord = normalizeDisplayChord(chord, keys);
   const shortcutOs = getShortcutOs();
 
diff --git a/packages/app/src/components/ui/skeleton.tsx b/packages/app/src/components/ui/skeleton.tsx
new file mode 100644
index 0000000000..76b710913d
--- /dev/null
+++ b/packages/app/src/components/ui/skeleton.tsx
@@ -0,0 +1,34 @@
+import { useEffect, useMemo, useRef } from "react";
+import { Animated, type StyleProp, type ViewStyle } from "react-native";
+
+/** One looping value per skeleton, shared by its shapes so they pulse together. */
+export function useSkeletonPulse(): Animated.Value {
+  const pulse = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    const animation = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, { toValue: 1, duration: 1000, useNativeDriver: true }),
+        Animated.timing(pulse, { toValue: 0, duration: 1000, useNativeDriver: true }),
+      ]),
+    );
+    animation.start();
+    return () => animation.stop();
+  }, [pulse]);
+  return pulse;
+}
+
+/** A placeholder shape; `style` sets its size, radius and color. */
+export function SkeletonPulse({
+  pulse,
+  style,
+}: {
+  pulse: Animated.Value;
+  style: StyleProp<ViewStyle>;
+}) {
+  const opacity = pulse.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0.4, 0.8],
+  });
+  const pulseStyle = useMemo(() => [style, { opacity }], [style, opacity]);
+  return <Animated.View style={pulseStyle} />;
+}
diff --git a/packages/app/src/components/ui/switch.test.tsx b/packages/app/src/components/ui/switch.test.tsx
index 1db67418ff..96fb57df79 100644
--- a/packages/app/src/components/ui/switch.test.tsx
+++ b/packages/app/src/components/ui/switch.test.tsx
@@ -86,6 +86,7 @@ vi.mock("react-native-unistyles", () => ({
     ) =>
     (props: Record<string, unknown>) =>
       React.createElement(Component, { ...props, ...mapping?.(theme) }),
+  useUnistyles: () => ({ theme, rt: { breakpoint: "md" } }),
 }));
 
 describe("Switch", () => {
diff --git a/packages/app/src/components/ui/switch.tsx b/packages/app/src/components/ui/switch.tsx
index b4c035eea0..618eae8c11 100644
--- a/packages/app/src/components/ui/switch.tsx
+++ b/packages/app/src/components/ui/switch.tsx
@@ -13,7 +13,9 @@ import Animated, {
   withTiming,
 } from "react-native-reanimated";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { createControlGeometry, switchGeometry } from "@/components/ui/control-geometry";
+import { switchGeometryForLayout, type SwitchGeometry } from "@/components/ui/control-geometry";
+import { useContainedControlSize } from "@/components/ui/control-size";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import type { Theme } from "@/styles/theme";
 
 interface SwitchProps {
@@ -29,6 +31,7 @@ const TIMING = { duration: 180, easing: Easing.inOut(Easing.ease) };
 
 interface SwitchTrackProps {
   value: boolean;
+  geometry: SwitchGeometry;
   trackOffColor: string;
   trackOnColor: string;
   thumbOffColor: string;
@@ -37,6 +40,7 @@ interface SwitchTrackProps {
 
 function SwitchTrack({
   value,
+  geometry,
   trackOffColor,
   trackOnColor,
   thumbOffColor,
@@ -48,15 +52,36 @@ function SwitchTrack({
     backgroundColor: interpolateColor(progress.value, [0, 1], [trackOffColor, trackOnColor]),
   }));
 
+  const { thumbTravel } = geometry;
   const thumbAnimatedStyle = useAnimatedStyle(() => ({
     backgroundColor: interpolateColor(progress.value, [0, 1], [thumbOffColor, thumbOnColor]),
-    transform: [{ translateX: progress.value * switchGeometry.thumbTravel }],
+    transform: [{ translateX: progress.value * thumbTravel }],
   }));
 
-  const trackStyle = useMemo(() => [styles.switchTrack, trackAnimatedStyle], [trackAnimatedStyle]);
+  const trackSize = useMemo(
+    () => ({
+      width: geometry.trackWidth,
+      height: geometry.trackHeight,
+      borderRadius: geometry.trackHeight / 2,
+      padding: (geometry.trackHeight - geometry.thumbSize) / 2,
+    }),
+    [geometry],
+  );
+  const thumbSize = useMemo(
+    () => ({
+      width: geometry.thumbSize,
+      height: geometry.thumbSize,
+      borderRadius: geometry.thumbSize / 2,
+    }),
+    [geometry],
+  );
+  const trackStyle = useMemo(
+    () => [styles.switchTrack, trackSize, trackAnimatedStyle],
+    [trackSize, trackAnimatedStyle],
+  );
   const thumbStyle = useMemo(
-    () => [styles.switchThumb, styles.thumb, thumbAnimatedStyle],
-    [thumbAnimatedStyle],
+    () => [thumbSize, styles.thumb, thumbAnimatedStyle],
+    [thumbSize, thumbAnimatedStyle],
   );
 
   return (
@@ -90,10 +115,19 @@ export function Switch({
     [disabled, onValueChange, value],
   );
 
+  const size = useContainedControlSize() ?? "md";
+  const isCompact = useIsCompactFormFactor();
+  const geometry = useMemo(() => switchGeometryForLayout(size, isCompact), [size, isCompact]);
+
   const accessibilityState = useMemo(() => ({ checked: value, disabled }), [value, disabled]);
   const pressableStyle = useMemo(
-    () => [styles.switchControl, disabled ? styles.disabled : null, style],
-    [disabled, style],
+    () => [
+      styles.switchControl,
+      { minHeight: geometry.reservedHeight },
+      disabled ? styles.disabled : null,
+      style,
+    ],
+    [disabled, geometry.reservedHeight, style],
   );
 
   return (
@@ -108,29 +142,18 @@ export function Switch({
       testID={testID}
       style={pressableStyle}
     >
-      <ThemedSwitchTrack value={value} />
+      <ThemedSwitchTrack value={value} geometry={geometry} />
     </Pressable>
   );
 }
 
 const styles = StyleSheet.create((theme) => {
-  const geometry = createControlGeometry(theme);
-
   return {
     switchControl: {
-      ...geometry.switchControl,
-    },
-    switchTrack: {
-      width: switchGeometry.trackWidth,
-      height: switchGeometry.trackHeight,
-      borderRadius: switchGeometry.trackHeight / 2,
-      padding: (switchGeometry.trackHeight - switchGeometry.thumbSize) / 2,
       justifyContent: "center",
     },
-    switchThumb: {
-      width: switchGeometry.thumbSize,
-      height: switchGeometry.thumbSize,
-      borderRadius: switchGeometry.thumbSize / 2,
+    switchTrack: {
+      justifyContent: "center",
     },
     thumb: {
       shadowColor: "rgba(0, 0, 0, 0.25)",
diff --git a/packages/app/src/components/ui/tail-ellipsis-text/index.browser.test.tsx b/packages/app/src/components/ui/tail-ellipsis-text/index.browser.test.tsx
new file mode 100644
index 0000000000..fd0706d4fd
--- /dev/null
+++ b/packages/app/src/components/ui/tail-ellipsis-text/index.browser.test.tsx
@@ -0,0 +1,61 @@
+import React, { act, useMemo } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { View } from "react-native";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { TailEllipsisText } from "./index";
+
+// App sources compile against the classic JSX runtime, which expects React on the global.
+beforeEach(() => vi.stubGlobal("React", React));
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+const TEXT_STYLE = { fontSize: 16, fontFamily: "monospace" } as const;
+
+function LabelRow({ text, width }: { text: string; width: number }) {
+  const rowStyle = useMemo(() => ({ width, flexDirection: "row" as const }), [width]);
+  return (
+    <View style={rowStyle}>
+      <TailEllipsisText text={text} style={TEXT_STYLE} testID="label" />
+    </View>
+  );
+}
+
+function renderLabel(text: string, width: number): void {
+  act(() => root.render(<LabelRow text={text} width={width} />));
+}
+
+function shownLabel(): { text: string; visible: boolean } {
+  const label = host.querySelector<HTMLElement>('[data-testid="label"]');
+  if (!label) throw new Error("label did not render");
+  return { text: label.textContent ?? "", visible: getComputedStyle(label).opacity !== "0" };
+}
+
+it("shows a replacement label that shares its shortened prefixes with the previous one", async () => {
+  // Wide enough for "Ten second…" in monospace, too narrow for either full label.
+  const width = 12 * 10;
+  renderLabel("Ten second stream", width);
+  await vi.waitFor(() => expect(shownLabel()).toEqual({ text: "Ten second…", visible: true }));
+
+  renderLabel("Ten second thread", width);
+  await vi.waitFor(() => expect(shownLabel()).toEqual({ text: "Ten second…", visible: true }));
+});
+
+it("shows a replacement label as wide as the previous one", async () => {
+  renderLabel("Opus 4.7", 400);
+  await vi.waitFor(() => expect(shownLabel()).toEqual({ text: "Opus 4.7", visible: true }));
+
+  renderLabel("Opus 4.8", 400);
+  await vi.waitFor(() => expect(shownLabel()).toEqual({ text: "Opus 4.8", visible: true }));
+});
diff --git a/packages/app/src/components/ui/tail-ellipsis-text/index.tsx b/packages/app/src/components/ui/tail-ellipsis-text/index.tsx
new file mode 100644
index 0000000000..d8d477def1
--- /dev/null
+++ b/packages/app/src/components/ui/tail-ellipsis-text/index.tsx
@@ -0,0 +1,145 @@
+import { useCallback, useMemo, useState } from "react";
+import { Text, View, type LayoutChangeEvent, type StyleProp, type TextStyle } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { readMeasuredWidth } from "@/hooks/use-container-width";
+import { resolveTailEllipsis, tailEllipsisCandidates } from "./resolve";
+
+interface MeasuredWidths {
+  text: string;
+  full?: number;
+  candidates: (number | undefined)[];
+}
+
+/**
+ * One line of text that shrinks with its row and, when it does not fit, ends on a whole word
+ * and an ellipsis ("Ten second…"), never on a space. It measures itself, so it stays invisible
+ * for the frame before its widths are known.
+ */
+export function TailEllipsisText({
+  text,
+  style,
+  testID,
+}: {
+  text: string;
+  /** Text styles; the component owns its layout. */
+  style: StyleProp<TextStyle>;
+  testID?: string;
+}) {
+  const candidates = useMemo(() => tailEllipsisCandidates(text), [text]);
+  const [boxWidth, setBoxWidth] = useState<number | undefined>(undefined);
+  const [widths, setWidths] = useState<MeasuredWidths>({ text, candidates: [] });
+  const current = widths.text === text ? widths : { text, candidates: [] };
+
+  const onBoxLayout = useCallback((event: LayoutChangeEvent) => {
+    const width = readMeasuredWidth(event);
+    if (width !== null) setBoxWidth(width);
+  }, []);
+  const measure = useCallback(
+    (slot: "full" | number) => (event: LayoutChangeEvent) => {
+      const width = readMeasuredWidth(event);
+      if (width === null) return;
+      setWidths((previous) => {
+        const base = previous.text === text ? previous : { text, candidates: [] };
+        if (slot === "full") return { ...base, full: width };
+        const next = [...base.candidates];
+        next[slot] = width;
+        return { ...base, candidates: next };
+      });
+    },
+    [text],
+  );
+
+  const decision = resolveTailEllipsis({
+    candidates,
+    measurements: { boxWidth, fullWidth: current.full, candidateWidths: current.candidates },
+  });
+  const shownText = decision.kind === "truncated" ? decision.text : text;
+
+  return (
+    <View style={styles.box} onLayout={onBoxLayout}>
+      {/* Sizes the box: as wide as the text, or as the row allows. */}
+      <Text
+        style={[style, styles.sizer]}
+        numberOfLines={1}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
+        {text}
+      </Text>
+      <View style={styles.shown} pointerEvents="none">
+        <Text
+          style={[style, styles.shownText, decision.kind === "measuring" && styles.measuring]}
+          numberOfLines={1}
+          ellipsizeMode="tail"
+          testID={testID}
+        >
+          {shownText}
+        </Text>
+      </View>
+      {/* Keyed by the text, so new text remounts the measurer and every width is measured again.
+          A retained node whose size does not change emits no new layout event. */}
+      <View
+        key={text}
+        style={styles.measurer}
+        pointerEvents="none"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
+        <Text style={[style, styles.measured]} numberOfLines={1} onLayout={measure("full")}>
+          {text}
+        </Text>
+        {candidates.map((candidate, index) => (
+          <Text
+            key={candidate}
+            style={[style, styles.measured]}
+            numberOfLines={1}
+            onLayout={measure(index)}
+          >
+            {candidate}
+          </Text>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // A row, so the absolute measurer below lays its text out at full width on native too.
+  box: {
+    minWidth: 0,
+    flexShrink: 1,
+    flexDirection: "row",
+  },
+  sizer: {
+    minWidth: 0,
+    flexShrink: 1,
+    opacity: 0,
+  },
+  shown: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  shownText: {
+    minWidth: 0,
+    flexShrink: 1,
+  },
+  measuring: {
+    opacity: 0,
+  },
+  measurer: {
+    position: "absolute",
+    left: 0,
+    top: 0,
+    flexDirection: "row",
+    alignItems: "flex-start",
+    opacity: 0,
+  },
+  measured: {
+    flexShrink: 0,
+  },
+});
diff --git a/packages/app/src/components/ui/tail-ellipsis-text/resolve.test.ts b/packages/app/src/components/ui/tail-ellipsis-text/resolve.test.ts
new file mode 100644
index 0000000000..e65ae7e4a2
--- /dev/null
+++ b/packages/app/src/components/ui/tail-ellipsis-text/resolve.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { resolveTailEllipsis, tailEllipsisCandidates } from "./resolve";
+
+const candidates = tailEllipsisCandidates("Ten second stream");
+const candidateWidths = [34, 80];
+
+describe("tail ellipsis", () => {
+  it("cuts at word boundaries, so no whitespace sits before the ellipsis", () => {
+    expect(candidates).toEqual(["Ten…", "Ten second…"]);
+    expect(tailEllipsisCandidates("  GPT-5.1   Codex  ")).toEqual(["GPT-5.1…"]);
+    expect(tailEllipsisCandidates("claude-opus-4-5")).toEqual([]);
+  });
+
+  it("shows the full text while it fits", () => {
+    expect(
+      resolveTailEllipsis({
+        candidates,
+        measurements: { boxWidth: 132, fullWidth: 132.3, candidateWidths },
+      }),
+    ).toEqual({ kind: "full" });
+  });
+
+  it("keeps the most words that fit with the ellipsis", () => {
+    expect(
+      resolveTailEllipsis({
+        candidates,
+        measurements: { boxWidth: 98, fullWidth: 132, candidateWidths },
+      }),
+    ).toEqual({ kind: "truncated", text: "Ten second…" });
+    expect(
+      resolveTailEllipsis({
+        candidates,
+        measurements: { boxWidth: 60, fullWidth: 132, candidateWidths },
+      }),
+    ).toEqual({ kind: "truncated", text: "Ten…" });
+  });
+
+  it("lets the platform cut inside a first word too long for the box", () => {
+    expect(
+      resolveTailEllipsis({
+        candidates,
+        measurements: { boxWidth: 20, fullWidth: 132, candidateWidths },
+      }),
+    ).toEqual({ kind: "clipped" });
+    expect(
+      resolveTailEllipsis({
+        candidates: [],
+        measurements: { boxWidth: 60, fullWidth: 132, candidateWidths: [] },
+      }),
+    ).toEqual({ kind: "clipped" });
+  });
+
+  it("decides nothing until the widths it needs are measured", () => {
+    expect(resolveTailEllipsis({ candidates, measurements: { candidateWidths } })).toEqual({
+      kind: "measuring",
+    });
+    expect(
+      resolveTailEllipsis({
+        candidates,
+        measurements: { boxWidth: 98, fullWidth: 132, candidateWidths: [34] },
+      }),
+    ).toEqual({ kind: "measuring" });
+  });
+});
diff --git a/packages/app/src/components/ui/tail-ellipsis-text/resolve.ts b/packages/app/src/components/ui/tail-ellipsis-text/resolve.ts
new file mode 100644
index 0000000000..1e7bb61d1c
--- /dev/null
+++ b/packages/app/src/components/ui/tail-ellipsis-text/resolve.ts
@@ -0,0 +1,47 @@
+const ELLIPSIS = "…";
+
+/**
+ * The word-boundary truncations of `text`, shortest first: "Ten second stream" gives "Ten…" and
+ * "Ten second…". Cutting at a word keeps whitespace out from before the ellipsis.
+ */
+export function tailEllipsisCandidates(text: string): string[] {
+  const words = text.trim().split(/\s+/);
+  return words.slice(1).map((_, index) => `${words.slice(0, index + 1).join(" ")}${ELLIPSIS}`);
+}
+
+export type TailEllipsis =
+  | { kind: "measuring" }
+  | { kind: "full" }
+  | { kind: "truncated"; text: string }
+  /** Not even the first word fits: the platform ellipsis cuts inside it, where no space can sit. */
+  | { kind: "clipped" };
+
+/** Widths in points, measured from the rendered text. */
+export interface TailEllipsisMeasurements {
+  /** The space the text may take, up to its full width. */
+  boxWidth?: number;
+  fullWidth?: number;
+  /** One per `tailEllipsisCandidates` entry, in the same order. */
+  candidateWidths: readonly (number | undefined)[];
+}
+
+/** Sub-point slack for widths the layout rounds differently from the text it measures. */
+const ROUNDING_SLACK = 0.5;
+
+export function resolveTailEllipsis(input: {
+  candidates: readonly string[];
+  measurements: TailEllipsisMeasurements;
+}): TailEllipsis {
+  const { boxWidth, fullWidth, candidateWidths } = input.measurements;
+  if (boxWidth === undefined || fullWidth === undefined) return { kind: "measuring" };
+  if (fullWidth <= boxWidth + ROUNDING_SLACK) return { kind: "full" };
+  if (input.candidates.some((_, index) => candidateWidths[index] === undefined)) {
+    return { kind: "measuring" };
+  }
+  for (let index = input.candidates.length - 1; index >= 0; index -= 1) {
+    if ((candidateWidths[index] ?? Infinity) <= boxWidth) {
+      return { kind: "truncated", text: input.candidates[index] };
+    }
+  }
+  return { kind: "clipped" };
+}
diff --git a/packages/app/src/components/ui/tooltip.tsx b/packages/app/src/components/ui/tooltip.tsx
index 99f446001f..71ac53d8ac 100644
--- a/packages/app/src/components/ui/tooltip.tsx
+++ b/packages/app/src/components/ui/tooltip.tsx
@@ -30,6 +30,7 @@ import { FloatingSurface } from "@/components/ui/floating";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { isNative, isWeb } from "@/constants/platform";
 import { getOverlayRoot, OVERLAY_Z } from "@/lib/overlay-root";
+import { holdSurfaceEdge, surfaceFrameStyles, type SurfacePosition } from "./anchor";
 
 type Side = "top" | "bottom" | "left" | "right";
 type Align = "start" | "center" | "end";
@@ -475,7 +476,7 @@ export function TooltipContent({
   const ctx = useTooltipContext("TooltipContent");
   const [triggerRect, setTriggerRect] = useState<Rect | null>(null);
   const [contentSize, setContentSize] = useState<{ width: number; height: number } | null>(null);
-  const [position, setPosition] = useState<{ x: number; y: number } | null>(null);
+  const [position, setPosition] = useState<SurfacePosition | null>(null);
 
   useEffect(() => {
     if (!ctx.open || !ctx.enabled || !ctx.triggerRef.current) {
@@ -509,7 +510,12 @@ export function TooltipContent({
       align,
       offset,
     });
-    setPosition({ x: result.x, y: result.y });
+    setPosition(
+      holdSurfaceEdge(
+        { x: result.x, y: result.y, actualPlacement: result.actualSide },
+        contentSize.height,
+      ),
+    );
   }, [triggerRect, contentSize, side, align, offset]);
 
   const handleLayout = useCallback(
@@ -520,17 +526,8 @@ export function TooltipContent({
     [],
   );
 
-  const frameStyle = useMemo(
-    () => [
-      {
-        position: "absolute" as const,
-        top: position?.y ?? -9999,
-        left: position?.x ?? -9999,
-        maxWidth,
-      },
-    ],
-    [maxWidth, position?.x, position?.y],
-  );
+  const frame = useMemo(() => surfaceFrameStyles(position), [position]);
+  const frameStyle = useMemo(() => [frame.surface, { maxWidth }], [frame.surface, maxWidth]);
   const contentStyle = useMemo(() => [styles.content, style], [style]);
 
   const handleDismiss = useCallback(() => ctx.setOpen(false), [ctx]);
@@ -543,19 +540,21 @@ export function TooltipContent({
   if (isWeb) {
     return createPortal(
       <View pointerEvents="none" style={styles.portalOverlay}>
-        <FloatingSurface
-          pointerEvents="none"
-          entering={FadeIn.duration(80)}
-          exiting={FadeOut.duration(80)}
-          collapsable={false}
-          role="tooltip"
-          testID={testID}
-          onLayout={handleLayout}
-          style={contentStyle}
-          frameStyle={frameStyle}
-        >
-          {children}
-        </FloatingSurface>
+        <View pointerEvents="box-none" style={frame.holder}>
+          <FloatingSurface
+            pointerEvents="none"
+            entering={FadeIn.duration(80)}
+            exiting={FadeOut.duration(80)}
+            collapsable={false}
+            role="tooltip"
+            testID={testID}
+            onLayout={handleLayout}
+            style={contentStyle}
+            frameStyle={frameStyle}
+          >
+            {children}
+          </FloatingSurface>
+        </View>
       </View>,
       getOverlayRoot(),
     );
@@ -570,19 +569,21 @@ export function TooltipContent({
       onRequestClose={handleDismiss}
     >
       <Pressable testID="tooltip-dismiss" style={styles.overlay} onPress={handleDismiss}>
-        <FloatingSurface
-          pointerEvents="none"
-          entering={FadeIn.duration(80)}
-          exiting={FadeOut.duration(80)}
-          collapsable={false}
-          role="tooltip"
-          testID={testID}
-          onLayout={handleLayout}
-          style={contentStyle}
-          frameStyle={frameStyle}
-        >
-          {children}
-        </FloatingSurface>
+        <View pointerEvents="box-none" style={frame.holder}>
+          <FloatingSurface
+            pointerEvents="none"
+            entering={FadeIn.duration(80)}
+            exiting={FadeOut.duration(80)}
+            collapsable={false}
+            role="tooltip"
+            testID={testID}
+            onLayout={handleLayout}
+            style={contentStyle}
+            frameStyle={frameStyle}
+          >
+            {children}
+          </FloatingSurface>
+        </View>
       </Pressable>
     </Modal>
   );
diff --git a/packages/app/src/components/ui/trailing-action-scrim.tsx b/packages/app/src/components/ui/trailing-action-scrim.tsx
index e106bf3ec5..0b43136bd1 100644
--- a/packages/app/src/components/ui/trailing-action-scrim.tsx
+++ b/packages/app/src/components/ui/trailing-action-scrim.tsx
@@ -6,9 +6,18 @@ import type { SurfaceBackdrop } from "@/styles/surface-backdrop";
 import type { Theme } from "@/styles/theme";
 
 export const SCRIM_WIDTH = 48;
-const SCRIM_SOLID_OFFSET = "55%";
+// The fade is a fixed length so a wider scrim only adds solid surface under its actions.
+const SCRIM_FADE_WIDTH = SCRIM_WIDTH * 0.55;
 
-function TrailingActionScrimSvg({ gradientId, color }: { gradientId: string; color: string }) {
+function TrailingActionScrimSvg({
+  gradientId,
+  color,
+  solidOffset,
+}: {
+  gradientId: string;
+  color: string;
+  solidOffset: string;
+}) {
   return (
     <Svg width="100%" height="100%" preserveAspectRatio="none">
       <Defs>
@@ -16,7 +25,7 @@ function TrailingActionScrimSvg({ gradientId, color }: { gradientId: string; col
           {/* Vary opacity rather than interpolating toward `transparent`, which crosses black in
               some engines and leaves a grey fringe. */}
           <Stop offset="0%" stopColor={color} stopOpacity={0} />
-          <Stop offset={SCRIM_SOLID_OFFSET} stopColor={color} stopOpacity={1} />
+          <Stop offset={solidOffset} stopColor={color} stopOpacity={1} />
           <Stop offset="100%" stopColor={color} stopOpacity={1} />
         </SvgLinearGradient>
       </Defs>
@@ -39,17 +48,22 @@ const backdropColorMappings: Record<SurfaceBackdrop, (theme: Theme) => { color:
 /** Fades trailing content into the surface beneath an absolutely overlaid action. */
 export function TrailingActionScrim({
   backdrop,
+  width = SCRIM_WIDTH,
   testID,
 }: {
   backdrop: SurfaceBackdrop;
+  /** Covers more than one trailing action; the fade keeps its length. */
+  width?: number;
   testID?: string;
 }) {
   // React-generated ids contain characters that are invalid inside SVG fragment references.
   const gradientId = `trailing-action-scrim-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+  const solidOffset = `${Math.round((SCRIM_FADE_WIDTH / width) * 100)}%`;
   return (
-    <View style={styles.scrim} pointerEvents="none" testID={testID}>
+    <View style={styles.scrim(width)} pointerEvents="none" testID={testID}>
       <ThemedTrailingActionScrimSvg
         gradientId={gradientId}
+        solidOffset={solidOffset}
         uniProps={backdropColorMappings[backdrop]}
       />
     </View>
@@ -57,11 +71,11 @@ export function TrailingActionScrim({
 }
 
 const styles = StyleSheet.create({
-  scrim: {
+  scrim: (width: number) => ({
     position: "absolute",
     top: 0,
     bottom: 0,
     right: 0,
-    width: SCRIM_WIDTH,
-  },
+    width,
+  }),
 });
diff --git a/packages/app/src/components/user-message/index.tsx b/packages/app/src/components/user-message/index.tsx
index e7bef2d177..dc73c517ca 100644
--- a/packages/app/src/components/user-message/index.tsx
+++ b/packages/app/src/components/user-message/index.tsx
@@ -9,8 +9,11 @@ import { useProviderIcon } from "@/components/provider-icons";
 import { useSessionStore } from "@/stores/session-store";
 import { navigateToAgent } from "@/utils/navigate-to-agent";
 import { isNative } from "@/constants/platform";
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 
 const PREVIEW_HEIGHT = 240;
+// Show more and show less sit under the text they open and close.
+const TRIGGER_BELOW_CONTENT = { triggerEdge: "bottom" } as const;
 // Native View still clips with "scroll", but Yoga measures its children without
 // the height cap. "hidden" caps the measured body too, hiding the expand control.
 const previewStyle: ViewStyle = {
@@ -26,7 +29,11 @@ export function MessagePreview({ children }: { children: ReactNode }) {
     (event: LayoutChangeEvent) => setOverflowing(event.nativeEvent.layout.height > PREVIEW_HEIGHT),
     [],
   );
-  const toggle = useCallback(() => setExpanded((value) => !value), []);
+  const hold = useDisclosureHold();
+  const toggle = useCallback(
+    () => hold(() => setExpanded((value) => !value), TRIGGER_BELOW_CONTENT),
+    [hold],
+  );
   const accessibilityState = useMemo(() => ({ expanded }), [expanded]);
   return (
     <>
diff --git a/packages/app/src/components/welcome-screen.tsx b/packages/app/src/components/welcome-screen.tsx
index 1b3cdbe237..6dd1a1426c 100644
--- a/packages/app/src/components/welcome-screen.tsx
+++ b/packages/app/src/components/welcome-screen.tsx
@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useAddHost } from "@/hosts/add-host";
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { Pressable, Text, View, ScrollView } from "react-native";
 import { useRouter } from "expo-router";
@@ -12,11 +13,7 @@ import {
   Terminal,
 } from "lucide-react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import type { HostProfile } from "@/types/host-connection";
 import { getHostRuntimeStore, isHostRuntimeConnected, useHosts } from "@/runtime/host-runtime";
-import { AddHostModal } from "./add-host-modal";
-import { AddRemoteSshHostModal } from "./add-remote-ssh-host-modal";
-import { PairLinkModal } from "./pair-link-modal";
 import { Button } from "@/components/ui/button";
 import { resolveAppVersion } from "@/utils/app-version";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -162,20 +159,13 @@ function useAnyHostOnline(serverIds: string[]): string | null {
   );
 }
 
-export interface WelcomeScreenProps {
-  onHostAdded?: (profile: HostProfile) => void;
-}
-
-export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
+export function WelcomeScreen() {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
   const router = useRouter();
   const appVersion = resolveAppVersion();
   const appVersionText = formatVersionWithPrefix(appVersion);
-  const [isDirectOpen, setIsDirectOpen] = useState(false);
-  const [isRemoteSshOpen, setIsRemoteSshOpen] = useState(false);
-  const [isPasteLinkOpen, setIsPasteLinkOpen] = useState(false);
   const hosts = useHosts();
   const anyOnlineServerId = useAnyHostOnline(hosts.map((h) => h.serverId));
 
@@ -196,23 +186,10 @@ export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
     router.push("/settings");
   }, [router]);
 
-  const handleOpenDirect = useCallback(() => setIsDirectOpen(true), []);
-  const handleCloseDirect = useCallback(() => setIsDirectOpen(false), []);
-  const handleOpenRemoteSsh = useCallback(() => setIsRemoteSshOpen(true), []);
-  const handleCloseRemoteSsh = useCallback(() => setIsRemoteSshOpen(false), []);
-  const handleOpenPasteLink = useCallback(() => setIsPasteLinkOpen(true), []);
-  const handleClosePasteLink = useCallback(() => setIsPasteLinkOpen(false), []);
-  const handleScanQr = useCallback(() => {
-    router.push("/pair-scan?source=onboarding");
-  }, [router]);
-
-  const handleHostSaved = useCallback(
-    ({ profile }: { profile: HostProfile; serverId: string }) => {
-      onHostAdded?.(profile);
-      finishOnboarding();
-    },
-    [onHostAdded, finishOnboarding],
-  );
+  const handleOpenDirect = useAddHost({ method: "direct", onAdded: finishOnboarding });
+  const handleOpenRemoteSsh = useAddHost({ method: "ssh", onAdded: finishOnboarding });
+  const handleOpenPasteLink = useAddHost({ method: "link", onAdded: finishOnboarding });
+  const handleScanQr = useAddHost({ method: "scan", onAdded: finishOnboarding });
 
   const actions: WelcomeAction[] =
     isWeb || isFdroidBuild
@@ -306,7 +283,6 @@ export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
 
           <Button
             variant="ghost"
-            size="sm"
             leftIcon={Settings}
             onPress={handleOpenSettings}
             style={styles.settingsButton}
@@ -316,24 +292,6 @@ export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
           </Button>
         </View>
         <Text style={styles.versionLabel}>{appVersionText}</Text>
-
-        <AddHostModal
-          visible={isDirectOpen}
-          onClose={handleCloseDirect}
-          onSaved={handleHostSaved}
-        />
-
-        <AddRemoteSshHostModal
-          visible={isRemoteSshOpen}
-          onClose={handleCloseRemoteSsh}
-          onSaved={handleHostSaved}
-        />
-
-        <PairLinkModal
-          visible={isPasteLinkOpen}
-          onClose={handleClosePasteLink}
-          onSaved={handleHostSaved}
-        />
       </ScrollView>
     </View>
   );
diff --git a/packages/app/src/components/workspace-setup-dialog.tsx b/packages/app/src/components/workspace-setup-dialog.tsx
index 3a326aed3d..299bd9f27b 100644
--- a/packages/app/src/components/workspace-setup-dialog.tsx
+++ b/packages/app/src/components/workspace-setup-dialog.tsx
@@ -436,7 +436,7 @@ export function WorkspaceSetupDialog() {
       desktopMaxWidth={640}
     >
       <FileDropZone style={styles.section}>
-        <KeyboardTranslateView>
+        <KeyboardTranslateView style={styles.composerSlot}>
           <Composer
             agentId={`workspace-setup:${serverId}:${sourceDirectory}`}
             serverId={serverId}
@@ -487,6 +487,9 @@ const styles = StyleSheet.create((theme) => ({
     color: theme.colors.destructive,
     lineHeight: 20,
   },
+  composerSlot: {
+    paddingBottom: theme.spacing[4],
+  },
   composerInputWrapper: {
     backgroundColor: theme.colors.surface2,
   },
diff --git a/packages/app/src/components/workspace-shortcut-targets-subscriber.test.tsx b/packages/app/src/components/workspace-shortcut-targets-subscriber.test.tsx
index 84e9141b6a..9f72789430 100644
--- a/packages/app/src/components/workspace-shortcut-targets-subscriber.test.tsx
+++ b/packages/app/src/components/workspace-shortcut-targets-subscriber.test.tsx
@@ -125,6 +125,20 @@ describe("WorkspaceShortcutTargetsSubscriber", () => {
     });
   });
 
+  it("keeps keyboard navigation populated when the sidebar starts hidden", async () => {
+    await act(async () => {
+      root?.render(
+        <SidebarModelProvider active={false} keyboardNavigationActive>
+          <WorkspaceShortcutTargetsSubscriber enabled />
+        </SidebarModelProvider>,
+      );
+    });
+    expect(useKeyboardShortcutsStore.getState().sidebarShortcutWorkspaceTargets).toEqual([
+      { serverId: "srv", workspaceId: "ws-1" },
+      { serverId: "srv", workspaceId: "ws-2" },
+    ]);
+  });
+
   it("publishes workspace shortcut targets without rendering the sidebar", async () => {
     await act(async () => {
       root?.render(
diff --git a/packages/app/src/composer/agent-composer/index.test.ts b/packages/app/src/composer/agent-composer/index.test.ts
new file mode 100644
index 0000000000..b16b583455
--- /dev/null
+++ b/packages/app/src/composer/agent-composer/index.test.ts
@@ -0,0 +1,592 @@
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
+import { resolveAgentModelSelection } from "@/composer/agent-controls/utils";
+import { filterSelectableModels } from "@/provider-selection/model-catalog";
+import { buildDraftStoreKey } from "@/stores/draft-keys";
+import { useDraftStore } from "@/stores/draft-store";
+import { useSessionStore, type Agent } from "@/stores/session-store";
+import { providersSnapshotQueryRoot } from "@/data/providers-snapshot";
+import { agentComposer, createAgentComposer } from "./index";
+
+const serverId = "host-1";
+const agentId = "agent-1";
+const draftKey = buildDraftStoreKey({ serverId, agentId });
+
+const entries: ProviderSnapshotEntry[] = [
+  {
+    provider: "claude",
+    status: "ready",
+    enabled: true,
+    models: [
+      {
+        provider: "claude",
+        id: "opus",
+        label: "Opus",
+        isDefault: true,
+        defaultThinkingOptionId: "high",
+        thinkingOptions: [
+          { id: "low", label: "Low" },
+          { id: "high", label: "High" },
+        ],
+      },
+      {
+        provider: "claude",
+        id: "claude-sonnet-4",
+        label: "Sonnet 4",
+        aliases: ["sonnet"],
+        thinkingOptions: [{ id: "low", label: "Low" }],
+      },
+    ],
+  },
+];
+
+function agent(overrides: Partial<Agent> = {}): Agent {
+  return {
+    serverId,
+    id: agentId,
+    provider: "claude",
+    status: "idle",
+    turn: { phase: "idle", cancellationRequestId: null },
+    createdAt: new Date("2026-11-04T10:00:00.000Z"),
+    updatedAt: new Date("2026-11-04T10:00:00.000Z"),
+    lastUserMessageAt: null,
+    lastActivityAt: new Date("2026-11-04T10:00:00.000Z"),
+    capabilities: {
+      supportsStreaming: true,
+      supportsSessionPersistence: true,
+      supportsDynamicModes: true,
+      supportsMcpServers: true,
+      supportsReasoningStream: true,
+      supportsToolInvocations: true,
+    },
+    currentModeId: "default",
+    availableModes: [],
+    pendingPermissions: [],
+    persistence: null,
+    title: null,
+    cwd: "/repo",
+    workspaceId: "workspace-1",
+    model: null,
+    parentAgentId: null,
+    labels: {},
+    ...overrides,
+  };
+}
+
+function fakeClient() {
+  const calls: string[] = [];
+  const client = {
+    async getProvidersSnapshot() {
+      if (hostCatalog.failing) throw new Error("The host is busy.");
+      return {
+        entries: hostCatalog.entries,
+        generatedAt: "2026-11-04T10:00:00.000Z",
+        requestId: "snapshot",
+      };
+    },
+    async setAgentModel(id: string, model: string | null) {
+      calls.push(`model:${id}:${model}`);
+      if (model === "nope") throw new Error("The provider refused model 'nope'");
+    },
+    async setAgentMetadata(id: string, patch: unknown) {
+      calls.push(`metadata:${id}:${JSON.stringify(patch)}`);
+    },
+    async setAgentOptions(id: string, patch: unknown) {
+      calls.push(`options:${id}:${JSON.stringify(patch)}`);
+    },
+    async setAgentMode(id: string, mode: string) {
+      calls.push(`mode:${id}:${mode}`);
+      return null;
+    },
+    async setAgentThinkingOption(id: string, thinking: string) {
+      calls.push(`thinking:${id}:${thinking}`);
+      return null;
+    },
+  };
+  return { client: client as unknown as DaemonClient, calls };
+}
+
+/** What the host answers the next catalog request with. */
+const hostCatalog: { entries: ProviderSnapshotEntry[]; failing: boolean } = {
+  entries,
+  failing: false,
+};
+
+function openSession(running: Agent) {
+  const { client, calls } = fakeClient();
+  const store = useSessionStore.getState();
+  store.initializeSession(serverId, client);
+  store.updateSessionServerInfo(serverId, {
+    serverId,
+    hostname: null,
+    version: null,
+    features: { providersSnapshot: true },
+  } as never);
+  store.setAgents(serverId, new Map([[running.id, running]]));
+  return calls;
+}
+
+async function until(read: () => unknown, expected: unknown) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (Object.is(read(), expected)) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  expect(read()).toBe(expected);
+}
+
+let queryClient: QueryClient;
+
+function runtimeModel(model: string): Agent["runtimeInfo"] {
+  return { provider: "claude", sessionId: null, model };
+}
+
+function composer(deps: { reveal?: () => void } = {}) {
+  return createAgentComposer(serverId, agentId, { queryClient, reveal: () => {}, ...deps });
+}
+
+/** A mounted input that records the focus it takes. */
+function mountedInput(on: { revealed: boolean }) {
+  const focused: unknown[] = [];
+  return {
+    focused,
+    input: {
+      isLive: () => on.revealed,
+      setText() {},
+      insertText() {},
+      isRevealed: () => on.revealed,
+      focus: async (options?: unknown) => {
+        focused.push(options);
+      },
+    },
+  };
+}
+
+beforeEach(() => {
+  queryClient = new QueryClient();
+  hostCatalog.entries = entries;
+  hostCatalog.failing = false;
+  useDraftStore.setState({ drafts: {}, textReplacementRequestByDraftKey: {} });
+});
+
+afterEach(() => {
+  useSessionStore.getState().clearSession(serverId);
+});
+
+describe("agent composer focus", () => {
+  it("only focuses an input that is already on screen", async () => {
+    openSession(agent());
+    let reveals = 0;
+    const model = composer({ reveal: () => (reveals += 1) });
+    const { input, focused } = mountedInput({ revealed: true });
+    model.attachInput(input);
+
+    await model.focus({ selection: { start: 1, end: 3 } });
+
+    expect(focused).toEqual([{ selection: { start: 1, end: 3 } }]);
+    expect(reveals).toBe(0);
+  });
+
+  it("reveals an agent with no mounted composer and focuses the input that arrives", async () => {
+    openSession(agent());
+    let reveals = 0;
+    const model = composer({ reveal: () => (reveals += 1) });
+
+    const focusing = model.focus();
+    expect(reveals).toBe(1);
+
+    const { input, focused } = mountedInput({ revealed: true });
+    model.attachInput(input);
+    await focusing;
+    expect(focused).toEqual([undefined]);
+  });
+
+  it("focuses after the commit that revealed the input has applied a pending prompt", async () => {
+    openSession(agent());
+    const model = composer({ reveal() {} });
+    const focusing = model.focus({ selection: { start: 0, end: 5 } });
+    let text = "";
+    const textWhenFocused: string[] = [];
+    model.attachInput({
+      ...mountedInput({ revealed: true }).input,
+      focus: async () => {
+        textWhenFocused.push(text);
+      },
+    });
+    text = "HELLO";
+
+    await focusing;
+
+    expect(textWhenFocused).toEqual(["HELLO"]);
+  });
+
+  it("waits for a retained input to come on screen before focusing it", async () => {
+    openSession(agent());
+    let reveals = 0;
+    const model = composer({ reveal: () => (reveals += 1) });
+    const on = { revealed: false };
+    const { input, focused } = mountedInput(on);
+    const detach = model.attachInput(input);
+
+    const focusing = model.focus();
+    expect(reveals).toBe(1);
+    expect(focused).toEqual([]);
+
+    // The mounted composer re-attaches when it comes on screen.
+    on.revealed = true;
+    detach();
+    model.attachInput(input);
+    await focusing;
+    expect(focused).toEqual([undefined]);
+  });
+
+  it("applies only the latest of two focus requests", async () => {
+    openSession(agent());
+    const model = composer();
+    const first = model.focus({ selection: { start: 0, end: 0 } });
+    const second = model.focus({ selection: { start: 2, end: 2 } });
+    const { input, focused } = mountedInput({ revealed: true });
+    model.attachInput(input);
+    await Promise.all([first, second]);
+    expect(focused).toEqual([{ selection: { start: 2, end: 2 } }]);
+  });
+
+  it("lets a call made while an arriving input is being focused decide the selection", async () => {
+    openSession(agent());
+    const model = composer();
+    const first = model.focus({ selection: { start: 0, end: 1 } });
+    const { input, focused } = mountedInput({ revealed: true });
+    model.attachInput(input);
+    const second = model.focus({ selection: { start: 2, end: 4 } });
+    await Promise.all([first, second]);
+    expect(focused.at(-1)).toEqual({ selection: { start: 2, end: 4 } });
+  });
+
+  it("settles a replaced focus request with the request that replaced it", async () => {
+    vi.useFakeTimers();
+    try {
+      openSession(agent());
+      const model = composer();
+      const settled: string[] = [];
+      const record = (name: string, request: Promise<void>) =>
+        request.then(
+          () => settled.push(`${name} focused`),
+          () => settled.push(`${name} failed`),
+        );
+      const first = record("first", model.focus());
+      const second = record("second", model.focus());
+      await vi.advanceTimersByTimeAsync(60_000);
+      await Promise.all([first, second]);
+      expect(settled).toEqual(["second failed", "first failed"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("rejects when the composer never comes on screen, and a later mount does not take focus", async () => {
+    vi.useFakeTimers();
+    try {
+      openSession(agent());
+      const model = composer();
+      const focusing = model.focus();
+      const failed = expect(focusing).rejects.toThrow("did not come on screen");
+      await vi.advanceTimersByTimeAsync(60_000);
+      await failed;
+
+      const { input, focused } = mountedInput({ revealed: true });
+      model.attachInput(input);
+      expect(focused).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("rejects for an archived agent without navigating to it", async () => {
+    openSession(agent({ archivedAt: new Date() }));
+    let reveals = 0;
+    const model = composer({ reveal: () => (reveals += 1) });
+    await expect(model.focus()).rejects.toThrow("archived");
+    expect(reveals).toBe(0);
+  });
+});
+
+describe("agent composer", () => {
+  it("reads without notifying anyone, so a read during a render updates no other component", () => {
+    const running = agent();
+    const other = agent({ id: "agent-2", cwd: "/other-repo" });
+    openSession(running);
+    useSessionStore.getState().setAgents(
+      serverId,
+      new Map([
+        [running.id, running],
+        [other.id, other],
+      ]),
+    );
+    const watched = createAgentComposer(serverId, running.id, { queryClient, reveal: () => {} });
+    const reader = createAgentComposer(serverId, other.id, { queryClient, reveal: () => {} });
+    let notifications = 0;
+    const stop = watched.subscribe(() => {
+      notifications += 1;
+    });
+    const before = notifications;
+    // The first read of another catalog creates its query in the shared cache.
+    reader.getState();
+    expect(notifications).toBe(before);
+    stop();
+  });
+
+  it("keeps the prompt in the stored draft while no composer is mounted", () => {
+    openSession(agent());
+    const model = composer();
+    model.insertText("Review ");
+    model.insertText("this diff.\n");
+    expect(model.getState().prompt).toBe("Review this diff.\n");
+    expect(useDraftStore.getState().getDraftInput(draftKey)?.text).toBe("Review this diff.\n");
+    model.setPrompt("Start over");
+    expect(model.getState().prompt).toBe("Start over");
+  });
+
+  it("sends prompt commands through the mounted composer while it is mounted", () => {
+    openSession(agent());
+    const model = composer();
+    const mounted: string[] = [];
+    const detach = model.attachInput({
+      isLive: () => true,
+      setText: (text) => mounted.push(`set:${text}`),
+      insertText: (text) => mounted.push(`insert:${text}`),
+      isRevealed: () => false,
+      focus: async () => {},
+    });
+    model.insertText("at the cursor");
+    model.setPrompt("replaced");
+    expect(mounted).toEqual(["insert:at the cursor", "set:replaced"]);
+    expect(useDraftStore.getState().getDraftInput(draftKey)).toBeUndefined();
+    detach();
+    model.insertText("stored");
+    expect(model.getState().prompt).toBe("stored");
+  });
+
+  it("stores the prompt and asks the draft's input to show it while the composer is mounted off screen", () => {
+    openSession(agent());
+    const model = composer();
+    const mounted: string[] = [];
+    model.attachInput({
+      isLive: () => false,
+      setText: (text) => mounted.push(`set:${text}`),
+      insertText: (text) => mounted.push(`insert:${text}`),
+      isRevealed: () => false,
+      focus: async () => {},
+    });
+    model.insertText("while away");
+    expect(mounted).toEqual([]);
+    expect(model.getState().prompt).toBe("while away");
+    expect(useDraftStore.getState().textReplacementRequestByDraftKey[draftKey]).toBe(1);
+    model.setPrompt("replaced");
+    expect(model.getState().prompt).toBe("replaced");
+    expect(useDraftStore.getState().textReplacementRequestByDraftKey[draftKey]).toBe(2);
+  });
+
+  it("notifies subscribers of a stored prompt and returns the same state until something changes", () => {
+    openSession(agent());
+    const model = composer();
+    let notified = 0;
+    const stop = model.subscribe(() => {
+      notified += 1;
+    });
+    const before = model.getState();
+    expect(model.getState()).toBe(before);
+    model.insertText("x");
+    expect(notified).toBeGreaterThan(0);
+    expect(model.getState()).not.toBe(before);
+    stop();
+  });
+
+  it("adds and removes attachments in the stored draft", () => {
+    openSession(agent());
+    const model = composer();
+    const attachment = {
+      kind: "plugin_resource" as const,
+      pluginId: "review",
+      sourceId: "issues",
+      sourceTitle: "Issues",
+      sourceIcon: "CircleDot",
+      item: {
+        id: "1",
+        identifier: "ENG-1",
+        title: "Title",
+        subtitle: "Open",
+        url: "https://example.com/1",
+        text: "Issue ENG-1: Title",
+        resourceType: "issue",
+      },
+    };
+    model.changeAttachments((current) => [...current, attachment]);
+    expect(model.getState().attachments).toHaveLength(1);
+    model.changeAttachments(() => []);
+    expect(model.getState().attachments).toHaveLength(0);
+  });
+
+  it("reads mode, options and metadata from the agent, and sends commands to the daemon", async () => {
+    const calls = openSession(
+      agent({ currentModeId: "plan", options: { effort: "high" }, metadata: { flag: true } }),
+    );
+    const model = composer();
+    expect(model.getState()).toMatchObject({
+      context: "agent",
+      provider: "claude",
+      mode: "plan",
+      options: { effort: "high" },
+      metadata: { flag: true },
+    });
+    await model.setMetadata({ flag: null });
+    await model.setOptions({ effort: "low" });
+    await model.setMode("default");
+    expect(calls).toEqual([
+      'metadata:agent-1:{"flag":null}',
+      'options:agent-1:{"effort":"low"}',
+      "mode:agent-1:default",
+    ]);
+    await expect(model.setProvider("codex")).rejects.toThrow(
+      "A running agent cannot change provider.",
+    );
+  });
+
+  it("rejects a model the provider refuses with the provider's message", async () => {
+    openSession(agent());
+    await expect(composer().setModel("nope")).rejects.toThrow("The provider refused model 'nope'");
+  });
+
+  it("takes the catalog the host changed while the picker was not open, once the host reconnects", async () => {
+    openSession(agent({ runtimeInfo: runtimeModel("opus") }));
+    const model = composer();
+    const stop = model.subscribe(() => {});
+    await until(() => model.getState().thinking, "high");
+
+    // The host changes the catalog while the client is away. Reconnecting invalidates the provider
+    // catalogs, which refetches the ones something is watching.
+    hostCatalog.entries = [
+      {
+        ...entries[0],
+        models: [{ ...entries[0].models![0], defaultThinkingOptionId: "low" }],
+      },
+    ] as ProviderSnapshotEntry[];
+    await queryClient.invalidateQueries({ queryKey: providersSnapshotQueryRoot(serverId) });
+
+    await until(() => model.getState().thinking, "low");
+    stop();
+  });
+
+  it("asks for the catalog again after a failed load once the host reconnects", async () => {
+    hostCatalog.failing = true;
+    openSession(agent({ runtimeInfo: runtimeModel("opus") }));
+    const model = composer();
+    const stop = model.subscribe(() => {});
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(model.getState().thinking).toBeNull();
+
+    hostCatalog.failing = false;
+    await queryClient.invalidateQueries({ queryKey: providersSnapshotQueryRoot(serverId) });
+
+    await until(() => model.getState().thinking, "high");
+    stop();
+  });
+
+  it("watches the stores once however many components watch the composer, and only for its own draft", () => {
+    openSession(agent());
+    const model = composer();
+    const calls = [0, 0, 0];
+    const stops: Array<() => void> = [];
+    for (const index of calls.keys()) {
+      stops.push(model.subscribe(() => void (calls[index] += 1)));
+    }
+    const before = [...calls];
+    model.insertText("typed");
+    expect(calls.map((count, index) => count - before[index])).toEqual([1, 1, 1]);
+
+    const unrelated = [...calls];
+    useDraftStore.getState().replaceDraftText({
+      draftKey: buildDraftStoreKey({ serverId, agentId: "agent-2" }),
+      text: "elsewhere",
+    });
+    expect(calls).toEqual(unrelated);
+    for (const stop of stops) stop();
+  });
+
+  function pickerShows(running: Agent, catalog: ProviderSnapshotEntry[] | null) {
+    const picker = resolveAgentModelSelection({
+      models: filterSelectableModels(catalog?.[0]?.models ?? null),
+      runtimeModelId: running.runtimeInfo?.model ?? null,
+      configuredModelId: running.model,
+      runtimeThinkingOptionId: running.runtimeInfo?.thinkingOptionId ?? null,
+      explicitThinkingOptionId: running.thinkingOptionId,
+    });
+    return { model: picker.activeModelId, thinking: picker.selectedThinkingId };
+  }
+
+  it.each([
+    [
+      "an alias of a listed model",
+      { runtimeInfo: { model: "sonnet" } },
+      "sonnet",
+      "claude-sonnet-4",
+      "low",
+    ],
+    ["no reported model", { model: null }, null, "opus", "high"],
+    ["the configured model", { model: "opus", thinkingOptionId: "low" }, "opus", "opus", "low"],
+  ] as const)(
+    "shows what the picker shows for %s, before the catalog and after it loads",
+    async (_name, overrides, modelBefore, modelAfter, thinkingAfter) => {
+      const running = agent(overrides as unknown as Partial<Agent>);
+      openSession(running);
+      const model = composer();
+      // No catalog yet: the picker resolves with no models.
+      expect(model.getState()).toMatchObject(pickerShows(running, null));
+      expect(model.getState().model).toBe(modelBefore);
+      const stop = model.subscribe(() => {});
+      await until(() => model.getState().model, modelAfter);
+      expect(model.getState()).toMatchObject(pickerShows(running, entries));
+      expect(model.getState().thinking).toBe(thinkingAfter);
+      stop();
+    },
+  );
+
+  it("is shared while its agent is in the session, across closing and reopening its tab", () => {
+    openSession(agent());
+    const shared = agentComposer(serverId, agentId);
+    const detach = shared.attachInput(mountedInput({ revealed: true }).input);
+    detach();
+    expect(agentComposer(serverId, agentId)).toBe(shared);
+    const stop = shared.subscribe(() => {});
+    stop();
+    expect(agentComposer(serverId, agentId)).toBe(shared);
+  });
+
+  it("is released when the last holder lets go of a composer whose agent was removed meanwhile", () => {
+    openSession(agent());
+    const mounted = agentComposer(serverId, agentId);
+    const detach = mounted.attachInput(mountedInput({ revealed: true }).input);
+    useSessionStore.getState().setAgents(serverId, new Map());
+    // Held, so the session change did not release it, and nothing changes in the session after.
+    expect(agentComposer(serverId, agentId)).toBe(mounted);
+    detach();
+    expect(agentComposer(serverId, agentId)).not.toBe(mounted);
+
+    useSessionStore.getState().setAgents(serverId, new Map([[agentId, agent()]]));
+    const watched = agentComposer(serverId, agentId);
+    const stop = watched.subscribe(() => {});
+    useSessionStore.getState().clearSession(serverId);
+    expect(agentComposer(serverId, agentId)).toBe(watched);
+    stop();
+    expect(agentComposer(serverId, agentId)).not.toBe(watched);
+  });
+
+  it("is released when its agent is archived and nothing holds it", () => {
+    openSession(agent());
+    const idle = agentComposer(serverId, agentId);
+    useSessionStore
+      .getState()
+      .setAgents(serverId, new Map([[agentId, agent({ archivedAt: new Date() })]]));
+    expect(agentComposer(serverId, agentId)).not.toBe(idle);
+  });
+});
diff --git a/packages/app/src/composer/agent-composer/index.ts b/packages/app/src/composer/agent-composer/index.ts
new file mode 100644
index 0000000000..086aa90253
--- /dev/null
+++ b/packages/app/src/composer/agent-composer/index.ts
@@ -0,0 +1,387 @@
+import { QueryObserver, type QueryClient } from "@tanstack/react-query";
+import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
+import { providersSnapshotQuery } from "@/data/providers-snapshot";
+import { replicaQueryOptions } from "@/data/query";
+import { queryClient as singletonQueryClient } from "@/data/query-client";
+import type { ProviderSnapshotCache } from "@/data/provider-snapshot-cache";
+import {
+  resolveAgentModelSelection,
+  resolveProviderSnapshotEntry,
+} from "@/composer/agent-controls/utils";
+import type { ComposerFocusOptions, ComposerModel, ComposerState } from "@/composer/model";
+import { filterSelectableModels } from "@/provider-selection/model-catalog";
+import { buildDraftStoreKey } from "@/stores/draft-keys";
+import { useDraftStore } from "@/stores/draft-store";
+import { toDraftInputIfReady, type DraftRecord } from "@/stores/draft-store/state";
+import { useSessionStore, type Agent } from "@/stores/session-store";
+import type { UserComposerAttachment } from "@/attachments/types";
+import { navigateToAgent } from "@/utils/navigate-to-agent";
+
+/** The mounted composer's input. While attached, prompt commands go through it. */
+export interface MountedComposerInput {
+  /** False while the composer is retained but its input is not on screen. */
+  isLive(): boolean;
+  setText(text: string): void;
+  /** Inserts at the cursor, replacing the selection. */
+  insertText(text: string): void;
+  /** On screen and able to take the keyboard: `focus` needs nothing revealed first. */
+  isRevealed(): boolean;
+  focus(options?: ComposerFocusOptions): Promise<void>;
+}
+
+/**
+ * The composer of a running agent. It exists whether or not the agent's tab is open: the prompt
+ * and attachments are the agent's draft in the draft store, its settings are the session store's
+ * agent, and the model and thinking level resolve through the provider catalog exactly as the
+ * model picker does.
+ */
+export interface AgentComposer extends ComposerModel {
+  /** The mounted composer plugs in cursor-aware prompt commands for as long as it is mounted. */
+  attachInput(input: MountedComposerInput): () => void;
+}
+
+interface AgentComposerDeps {
+  queryClient: QueryClient;
+  cache?: ProviderSnapshotCache;
+  /** The last watcher or mounted composer let go, so the composer may be releasable. */
+  onUnheld?: () => void;
+  /** Brings the agent's composer on screen, wherever the user is. */
+  reveal: () => void;
+}
+
+// Long enough for a cold workspace to load its chat over a relay.
+const REVEAL_TIMEOUT_MS = 15_000;
+
+/** A focus waiting for the revealed input to come on screen. */
+interface PendingFocus {
+  /** Which `focus()` call this is; a later call decides where the cursor goes. */
+  call: number;
+  options: ComposerFocusOptions | undefined;
+  settle: { resolve: () => void; reject: (error: Error) => void };
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+type Catalog = { status: "loading" } | { status: "ready"; entries: ProviderSnapshotEntry[] | null };
+
+const NO_VALUES = Object.freeze({});
+const NO_ATTACHMENTS: readonly UserComposerAttachment[] = Object.freeze([]);
+
+interface ManagedAgentComposer extends AgentComposer {
+  /** The agent is gone or archived, and nothing watches the composer or has one mounted. */
+  isReleasable(): boolean;
+}
+
+export function createAgentComposer(
+  serverId: string,
+  agentId: string,
+  deps: AgentComposerDeps,
+): ManagedAgentComposer {
+  const draftKey = buildDraftStoreKey({ serverId, agentId });
+  const listeners = new Set<() => void>();
+  // While something watches, the catalog has an observer: it fetches the catalog, and it is what
+  // makes the catalog an active query that reconnect repair refetches, a failed one included.
+  let observing: { cwd: string; stop: () => void } | null = null;
+  // One pair of store subscriptions serves every listener, from the first to the last.
+  let stopWatchingStores: (() => void) | null = null;
+  let mounted: MountedComposerInput | null = null;
+  let pendingFocus: PendingFocus | null = null;
+  let focusCalls = 0;
+  let latestFocus: Promise<void> = Promise.resolve();
+  let last: {
+    agent: Agent | null;
+    draft: DraftRecord | undefined;
+    catalog: Catalog;
+    state: ComposerState;
+  } | null = null;
+
+  function readAgent(): Agent | null {
+    const session = useSessionStore.getState().sessions[serverId];
+    return session?.agents.get(agentId) ?? session?.agentDetails.get(agentId) ?? null;
+  }
+
+  function client() {
+    const connected = useSessionStore.getState().sessions[serverId]?.client;
+    if (!connected) throw new Error("The host is not connected.");
+    return connected;
+  }
+
+  function catalogQuery(cwd: string) {
+    return replicaQueryOptions(
+      providersSnapshotQuery({
+        serverId,
+        cwd,
+        client,
+        queryClient: deps.queryClient,
+        cache: deps.cache,
+      }),
+    );
+  }
+
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+
+  function observeCatalog() {
+    const agent = listeners.size > 0 ? readAgent() : null;
+    const session = useSessionStore.getState().sessions[serverId];
+    const cwd =
+      agent && session?.client && session.serverInfo?.features?.providersSnapshot === true
+        ? agent.cwd
+        : null;
+    if ((observing?.cwd ?? null) === cwd) return;
+    observing?.stop();
+    observing = null;
+    if (cwd === null) return;
+    // Watching again after the catalog was invalidated or failed while nothing watched refreshes it.
+    const options = { ...catalogQuery(cwd), refetchOnMount: true };
+    observing = { cwd, stop: new QueryObserver(deps.queryClient, options).subscribe(notify) };
+  }
+
+  function watchStores() {
+    const stops = [
+      useSessionStore.subscribe(() => {
+        observeCatalog();
+        notify();
+      }),
+      useDraftStore.subscribe((state, previous) => {
+        if (state.drafts[draftKey] !== previous.drafts[draftKey]) notify();
+      }),
+    ];
+    return () => {
+      for (const stop of stops) stop();
+    };
+  }
+
+  function readCatalog(agent: Agent): Catalog {
+    const session = useSessionStore.getState().sessions[serverId];
+    // The picker never loads a catalog from a host without it and shows the configured model.
+    if (session?.serverInfo?.features?.providersSnapshot !== true) {
+      return { status: "ready", entries: null };
+    }
+    const query = catalogQuery(agent.cwd);
+    const state = deps.queryClient.getQueryState<{ entries: ProviderSnapshotEntry[] }>(
+      query.queryKey,
+    );
+    // Nothing observes while nothing watches, so a read starts the one deduplicated load or
+    // refresh it needs and shows the cached catalog meanwhile. A read can run in another
+    // component's render and creating the query tells every query-cache subscriber, so it starts
+    // after the render.
+    const loads = state?.isInvalidated === true || (!state?.data && state?.status !== "error");
+    if (loads && !observing && session.client) {
+      queueMicrotask(() => void deps.queryClient.prefetchQuery(query));
+    }
+    if (state?.data) return { status: "ready", entries: state.data.entries };
+    if (state?.status === "error") return { status: "ready", entries: null };
+    return { status: "loading" };
+  }
+
+  function selectModel(agent: Agent, catalog: Catalog) {
+    // Until the catalog lands there are no models, which is what the picker resolves with too.
+    const entries = catalog.status === "ready" ? catalog.entries : null;
+    return resolveAgentModelSelection({
+      models: filterSelectableModels(
+        resolveProviderSnapshotEntry(entries ?? undefined, agent.provider)?.models ?? null,
+      ),
+      runtimeModelId: agent.runtimeInfo?.model ?? null,
+      configuredModelId: agent.model,
+      runtimeThinkingOptionId: agent.runtimeInfo?.thinkingOptionId ?? null,
+      explicitThinkingOptionId: agent.thinkingOptionId,
+    });
+  }
+
+  function buildState(
+    agent: Agent | null,
+    catalog: Catalog,
+    record: DraftRecord | undefined,
+  ): ComposerState {
+    const draft = toDraftInputIfReady(record);
+    const selection = agent ? selectModel(agent, catalog) : null;
+    return {
+      context: "agent",
+      prompt: draft?.text ?? "",
+      attachments: draft?.attachments ?? NO_ATTACHMENTS,
+      provider: agent?.provider ?? null,
+      model: selection?.activeModelId ?? null,
+      mode: agent?.currentModeId ?? null,
+      thinking: selection?.selectedThinkingId ?? null,
+      options: agent?.options ?? NO_VALUES,
+      metadata: agent?.metadata ?? NO_VALUES,
+    };
+  }
+
+  function readDraft(): DraftRecord | undefined {
+    const record = useDraftStore.getState().drafts[draftKey];
+    return record?.lifecycle === "active" ? record : undefined;
+  }
+
+  function getState(): ComposerState {
+    const agent = readAgent();
+    const draft = readDraft();
+    const catalog = agent ? readCatalog(agent) : ({ status: "loading" } as const);
+    if (
+      last &&
+      last.agent === agent &&
+      last.draft === draft &&
+      sameCatalog(last.catalog, catalog)
+    ) {
+      return last.state;
+    }
+    last = { agent, draft, catalog, state: buildState(agent, catalog, draft) };
+    return last.state;
+  }
+
+  function takePendingFocus(): PendingFocus | null {
+    const pending = pendingFocus;
+    pendingFocus = null;
+    if (pending) clearTimeout(pending.timeout);
+    return pending;
+  }
+
+  function focusIfRevealed(input: MountedComposerInput) {
+    if (!pendingFocus || !input.isRevealed()) return;
+    const { call, options, settle } = takePendingFocus()!;
+    // Attaching runs in a commit's effects, and a prompt set alongside this request can be applied
+    // by a later effect in that commit. A selection has to see that text.
+    queueMicrotask(() => {
+      // A call made since then, such as from a mounting item, decides; this one ends with it.
+      const outcome = call === focusCalls ? input.focus(options) : latestFocus;
+      outcome.then(settle.resolve, settle.reject);
+    });
+  }
+
+  function unheld() {
+    if (listeners.size === 0 && mounted === null) deps.onUnheld?.();
+  }
+
+  return {
+    isReleasable() {
+      if (listeners.size > 0 || mounted !== null) return false;
+      const agent = readAgent();
+      return agent === null || agent.archivedAt != null;
+    },
+    getState,
+    subscribe(listener) {
+      listeners.add(listener);
+      stopWatchingStores ??= watchStores();
+      observeCatalog();
+      getState();
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stopWatchingStores?.();
+          stopWatchingStores = null;
+        }
+        observeCatalog();
+        unheld();
+      };
+    },
+    attachInput(input) {
+      mounted = input;
+      focusIfRevealed(input);
+      return () => {
+        if (mounted === input) mounted = null;
+        unheld();
+      };
+    },
+    setPrompt(text) {
+      if (mounted?.isLive()) mounted.setText(text);
+      else useDraftStore.getState().replaceDraftText({ draftKey, text });
+    },
+    insertText(text) {
+      if (mounted?.isLive()) mounted.insertText(text);
+      else {
+        const current = useDraftStore.getState().getDraftInput(draftKey)?.text ?? "";
+        useDraftStore.getState().replaceDraftText({ draftKey, text: current + text });
+      }
+    },
+    focus(options) {
+      const agent = readAgent();
+      if (!agent || agent.archivedAt != null) {
+        return Promise.reject(new Error("The agent is gone or archived."));
+      }
+      const call = ++focusCalls;
+      if (mounted?.isRevealed()) {
+        latestFocus = mounted.focus(options);
+        return latestFocus;
+      }
+      const replaced = takePendingFocus();
+      const request = new Promise<void>((resolve, reject) => {
+        pendingFocus = {
+          call,
+          options,
+          settle: { resolve, reject },
+          timeout: setTimeout(() => {
+            takePendingFocus();
+            reject(new Error("The composer did not come on screen."));
+          }, REVEAL_TIMEOUT_MS),
+        };
+        deps.reveal();
+      });
+      // The latest request decides where the cursor goes, and the one it replaced ends with it.
+      if (replaced) request.then(replaced.settle.resolve, replaced.settle.reject);
+      latestFocus = request;
+      return request;
+    },
+    changeAttachments(updater) {
+      useDraftStore.getState().updateDraftInput({
+        draftKey,
+        update: (current) => ({ ...current, attachments: updater(current.attachments) }),
+      });
+    },
+    async setProvider() {
+      throw new Error("A running agent cannot change provider.");
+    },
+    async setModel(modelId) {
+      await client().setAgentModel(agentId, modelId);
+    },
+    async setMode(modeId) {
+      await client().setAgentMode(agentId, modeId);
+    },
+    async setThinking(thinkingOptionId) {
+      await client().setAgentThinkingOption(agentId, thinkingOptionId);
+    },
+    async setOptions(patch) {
+      await client().setAgentOptions(agentId, patch);
+    },
+    async setMetadata(patch) {
+      await client().setAgentMetadata(agentId, patch);
+    },
+  };
+}
+
+function sameCatalog(left: Catalog, right: Catalog): boolean {
+  return (
+    left.status === right.status &&
+    (left.status === "loading" || left.entries === (right as typeof left).entries)
+  );
+}
+
+const composers = new Map<string, ManagedAgentComposer>();
+let stopReleasing: (() => void) | null = null;
+
+/**
+ * The composer of a running agent; the same one for every caller for as long as the agent is in the
+ * session and not archived, so a command a plugin saved keeps reaching the composer a later tab
+ * mounts. It is released when the agent is gone or archived and nothing holds it, checked when the
+ * session changes and when the last holder lets go.
+ */
+export function agentComposer(serverId: string, agentId: string): AgentComposer {
+  stopReleasing ??= useSessionStore.subscribe(releaseReleasableComposers);
+  const key = `${serverId}:${agentId}`;
+  let composer = composers.get(key);
+  if (!composer) {
+    composer = createAgentComposer(serverId, agentId, {
+      queryClient: singletonQueryClient,
+      onUnheld: releaseReleasableComposers,
+      reveal: () => navigateToAgent({ serverId, agentId, asTab: true }),
+    });
+    composers.set(key, composer);
+  }
+  return composer;
+}
+
+function releaseReleasableComposers() {
+  for (const [key, composer] of composers) {
+    if (composer.isReleasable()) composers.delete(key);
+  }
+}
diff --git a/packages/app/src/composer/agent-controls/composer-control.browser.test.tsx b/packages/app/src/composer/agent-controls/composer-control.browser.test.tsx
new file mode 100644
index 0000000000..b787462ca8
--- /dev/null
+++ b/packages/app/src/composer/agent-controls/composer-control.browser.test.tsx
@@ -0,0 +1,200 @@
+import React from "react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { Scan } from "lucide-react-native";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import type { ToastApi } from "@/components/toast-host";
+import { ToastApiProvider } from "@/contexts/toast-api-context";
+import { ComposerControls, type ComposerControlItem } from "./composer-control";
+import { useAgentControlItems } from "./control-items";
+import { resolveComposerControlPresentation } from "./layout";
+
+beforeEach(() => vi.stubGlobal("React", React));
+afterEach(cleanup);
+
+const base = { id: "x", title: "Context", icon: Scan };
+// The sheet lays its rows out in a column, which is what stretches a row across it.
+const SHEET_COLUMN = { display: "flex", flexDirection: "column", width: 382 } as const;
+
+type RecordingToast = ToastApi & { error: ReturnType<typeof vi.fn> };
+
+function createToast(): RecordingToast {
+  return { error: vi.fn() } as unknown as RecordingToast;
+}
+
+function ignoreOpenChange() {}
+
+function Controls({
+  items,
+  surface,
+  toast,
+}: {
+  items: ComposerControlItem[];
+  surface: "toolbar" | "sheet";
+  toast: ToastApi;
+}) {
+  return (
+    <ToastApiProvider api={toast}>
+      <ComposerControls
+        items={items}
+        surface={surface}
+        openId={null}
+        onOpenIdChange={ignoreOpenChange}
+      />
+    </ToastApiProvider>
+  );
+}
+
+function renderControls(items: ComposerControlItem[], surface: "toolbar" | "sheet" = "toolbar") {
+  const toast = createToast();
+  render(<Controls items={items} surface={surface} toast={toast} />);
+  return toast;
+}
+
+describe("ComposerControls", () => {
+  it("shows a select's chosen label, or only its icon when asked", () => {
+    const select: ComposerControlItem = {
+      ...base,
+      type: "select",
+      value: "large",
+      choices: [
+        { value: "small", label: "Small" },
+        { value: "large", label: "Large" },
+      ],
+      onChange: () => undefined,
+    };
+    renderControls([select]);
+    expect(screen.getByRole("button", { name: "Context" }).textContent).toContain("Large");
+  });
+
+  it("names the choice on an icon-only select, without drawing it", () => {
+    renderControls([
+      {
+        ...base,
+        type: "select",
+        value: "large",
+        iconOnly: true,
+        choices: [{ value: "large", label: "Large" }],
+        onChange: () => undefined,
+      },
+    ]);
+    const trigger = screen.getByRole("button", { name: "Context: Large" });
+    expect(trigger.textContent).not.toContain("Large");
+  });
+
+  it("flips a toggle on press in the toolbar", () => {
+    const onChange = vi.fn();
+    renderControls([{ ...base, type: "toggle", value: true, onChange }]);
+    fireEvent.click(screen.getByRole("button", { name: "Context" }));
+    expect(onChange).toHaveBeenCalledWith(false);
+  });
+
+  it("lists a toggle as On or Off in the sheet", () => {
+    renderControls([{ ...base, type: "toggle", value: true, onChange: () => undefined }], "sheet");
+    expect(screen.getByRole("button", { name: "Context" }).textContent).toContain("On");
+  });
+
+  it("gives a sheet row's value the row's width, so a short value is not truncated", () => {
+    const toast = createToast();
+    render(
+      <div style={SHEET_COLUMN}>
+        <Controls
+          items={[
+            {
+              ...base,
+              type: "select",
+              value: "full",
+              choices: [{ value: "full", label: "Full access" }],
+              onChange: () => undefined,
+            },
+          ]}
+          surface="sheet"
+          toast={toast}
+        />
+      </div>,
+    );
+    const value = screen.getByText("Full access");
+    expect(value.scrollWidth).toBeLessThanOrEqual(value.clientWidth);
+  });
+
+  it("reports a failed command the way a built-in control does, and frees the control", async () => {
+    let reject: (error: Error) => void = () => undefined;
+    const onPress = vi.fn(
+      () =>
+        new Promise<void>((_resolve, rejectPromise) => {
+          reject = rejectPromise;
+        }),
+    );
+    const toast = renderControls([{ ...base, type: "action", onPress }]);
+    const button = screen.getByRole("button", { name: "Context" });
+
+    fireEvent.click(button);
+    // While the command is in flight the control cannot be pressed again.
+    await waitFor(() => expect(button.getAttribute("aria-disabled")).toBe("true"));
+    fireEvent.click(button);
+    expect(onPress).toHaveBeenCalledTimes(1);
+
+    reject(new Error("Unknown or unavailable provider: x"));
+    await waitFor(() =>
+      expect(toast.error).toHaveBeenCalledWith("Unknown or unavailable provider: x"),
+    );
+    await waitFor(() => expect(button.getAttribute("aria-disabled")).not.toBe("true"));
+  });
+
+  it("reports a command that throws before it returns", () => {
+    const toast = renderControls([
+      {
+        ...base,
+        type: "action",
+        onPress: () => {
+          throw new Error("No such control");
+        },
+      },
+    ]);
+    fireEvent.click(screen.getByRole("button", { name: "Context" }));
+    expect(toast.error).toHaveBeenCalledWith("No such control");
+  });
+});
+
+const FAST_ON = { fast_mode: true };
+
+describe("provider option controls", () => {
+  const fastMode: AgentOptionControl = {
+    type: "toggle",
+    key: "fast_mode",
+    label: "Fast",
+    defaultValue: false,
+  };
+  function OptionControls({
+    options,
+    onSetOption,
+  }: {
+    options: Record<string, unknown>;
+    onSetOption: (key: string, value: unknown) => void;
+  }) {
+    const optionControls = React.useMemo(
+      () => ({ controls: [fastMode], options, onSetOption }),
+      [onSetOption, options],
+    );
+    const items = useAgentControlItems({
+      surface: "toolbar",
+      presentation: resolveComposerControlPresentation("full"),
+      thinking: null,
+      optionControls,
+    });
+    return <Controls items={items.features} surface="toolbar" toast={TOAST} />;
+  }
+  const TOAST = createToast();
+
+  function recordWrites(writes: Array<[string, unknown]>) {
+    return (key: string, value: unknown) => void writes.push([key, value]);
+  }
+
+  it("write the toggled option from the agent's current options", () => {
+    const writes: Array<[string, unknown]> = [];
+    const onSetOption = recordWrites(writes);
+    render(<OptionControls options={FAST_ON} onSetOption={onSetOption} />);
+    fireEvent.click(screen.getByTestId("agent-feature-fast_mode"));
+    expect(writes).toEqual([["fast_mode", false]]);
+  });
+});
diff --git a/packages/app/src/composer/agent-controls/composer-control.tsx b/packages/app/src/composer/agent-controls/composer-control.tsx
new file mode 100644
index 0000000000..f98be7261f
--- /dev/null
+++ b/packages/app/src/composer/agent-controls/composer-control.tsx
@@ -0,0 +1,403 @@
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+} from "react";
+import type { TFunction } from "i18next";
+import { useTranslation } from "react-i18next";
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import type { AgentControlIcon } from "@/agent-controls/icons";
+import type { SheetHeader } from "@/components/adaptive-modal-sheet";
+import { Combobox, type ComboboxOption } from "@/components/ui/combobox";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { FieldTrigger } from "@/screens/new-workspace/form/field-trigger";
+import { ICON_SIZE } from "@/styles/theme";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { AgentControlTrigger } from "@/composer/agent-controls/control";
+import { useToast } from "@/contexts/toast-api-context";
+import { toErrorMessage } from "@/utils/error-messages";
+
+interface ComposerControlBase {
+  id: string;
+  title: string;
+  icon: AgentControlIcon;
+  /** Tints the icon; muted when absent. */
+  highlight?: "blue" | "green" | "yellow";
+  /** Defaults to the title, or to "title: choice" on an icon-only select. */
+  tooltip?: string;
+  /** Defaults to the tooltip. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+export interface ComposerControlChoice {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+/**
+ * One control, drawn from data. Provider option controls, thinking and plugin controls all come
+ * through here, so each is an icon in the composer toolbar, a row in its sheet, or, in a New
+ * workspace item, a field. The name stays from when the composer was the only place it drew.
+ */
+export type ComposerControlItem =
+  | (ComposerControlBase & {
+      type: "toggle";
+      value: boolean;
+      onChange: (value: boolean) => void | Promise<void>;
+    })
+  | (ComposerControlBase & {
+      type: "select";
+      value: string | null;
+      choices: readonly ComposerControlChoice[];
+      /** Names a value the choices do not list, such as a pick that a search no longer returns. */
+      valueLabel?: string;
+      onChange: (value: string) => void | Promise<void>;
+      /** The toolbar trigger shows only the icon. */
+      iconOnly?: boolean;
+      showCaret?: boolean;
+      searchable?: boolean;
+      /** The list answers `onSearchQueryChange` itself, so it is not filtered again. */
+      remoteSearch?: boolean;
+      onSearchQueryChange?: (query: string) => void;
+      emptyText?: string;
+      desktopMinWidth?: number;
+      renderOption?: (args: {
+        option: ComboboxOption;
+        selected: boolean;
+        active: boolean;
+        onPress: () => void;
+      }) => ReactElement;
+    })
+  | (ComposerControlBase & {
+      type: "action";
+      onPress: () => void | Promise<void>;
+    });
+
+/** `field`: a New workspace setup field, a badge on desktop and a full-width field when compact. */
+export type ComposerControlSurface = "toolbar" | "sheet" | "field";
+
+const ComposerControlSurfaceContext = createContext<ComposerControlSurface>("toolbar");
+export const ComposerControlSurfaceProvider = ComposerControlSurfaceContext.Provider;
+
+const ComposerControlLockContext = createContext(false);
+/** Disables every control below it, for a surface that is not a composer and has its own lock. */
+export const ComposerControlLockProvider = ComposerControlLockContext.Provider;
+
+export function useComposerControlLocked(): boolean {
+  return useContext(ComposerControlLockContext);
+}
+
+/** Where the control being drawn sits: the toolbar, a row in the overflow sheet, or a field. */
+export function useComposerControlSurface(): ComposerControlSurface {
+  return useContext(ComposerControlSurfaceContext);
+}
+
+interface ComposerControlProps {
+  item: ComposerControlItem;
+  surface: ComposerControlSurface;
+  disabled?: boolean;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Runs after a toolbar toggle or action, so the composer can take focus back. */
+  onActionComplete?: () => void;
+}
+
+interface ControlView {
+  options: ComboboxOption[];
+  /** The list's selected id. */
+  selectedId: string;
+  /** What the trigger shows beside the icon. */
+  value: string;
+  iconOnly: boolean;
+  tooltip: string;
+  /** Whether pressing the trigger opens a list instead of acting. */
+  opensList: boolean;
+}
+
+function describeControl(
+  item: ComposerControlItem,
+  surface: ComposerControlSurface,
+  t: TFunction,
+): ControlView {
+  const isSheet = surface === "sheet";
+  if (item.type === "action") {
+    return {
+      options: [],
+      selectedId: "",
+      value: "",
+      iconOnly: true,
+      tooltip: item.tooltip ?? item.title,
+      opensList: false,
+    };
+  }
+  if (item.type === "toggle") {
+    const label = item.value ? t("agentControls.features.on") : t("agentControls.features.off");
+    return {
+      options: [
+        { id: "true", label: t("agentControls.features.on") },
+        { id: "false", label: t("agentControls.features.off") },
+      ],
+      selectedId: String(item.value),
+      value: label,
+      iconOnly: true,
+      tooltip: item.tooltip ?? item.title,
+      opensList: isSheet,
+    };
+  }
+  const choiceLabel =
+    item.choices.find((choice) => choice.value === item.value)?.label ??
+    item.valueLabel ??
+    item.title;
+  const iconOnly = item.iconOnly === true;
+  return {
+    options: item.choices.map((choice) => ({
+      id: choice.value,
+      label: choice.label,
+      description: choice.description,
+    })),
+    selectedId: String(item.value ?? ""),
+    value: choiceLabel,
+    iconOnly,
+    // An icon-only trigger names its value; a sheet row shows the value, so it names the action.
+    tooltip: iconOnly && !isSheet ? `${item.title}: ${choiceLabel}` : (item.tooltip ?? item.title),
+    opensList: true,
+  };
+}
+
+type SelectItem = Extract<ComposerControlItem, { type: "select" }>;
+
+/** The list options only a select carries; a toggle's two-choice list has none of them. */
+function listProps(select: SelectItem | null) {
+  if (!select) return { searchable: false };
+  return {
+    desktopMinWidth: select.desktopMinWidth,
+    searchable: select.searchable,
+    remoteSearch: select.remoteSearch,
+    onSearchQueryChange: select.onSearchQueryChange,
+    emptyText: select.emptyText,
+    renderOption: select.renderOption,
+  };
+}
+
+// A command that returns a promise keeps the control pending until it settles, and a failure
+// reaches the user the way a built-in live control's does.
+function usePendingRun() {
+  const toast = useToast();
+  const [pending, setPending] = useState(false);
+  const run = useCallback(
+    (invoke: () => void | Promise<void>) => {
+      try {
+        const result = invoke();
+        if (!result) return;
+        setPending(true);
+        result
+          .catch((error: unknown) => toast.error(toErrorMessage(error)))
+          .finally(() => setPending(false));
+      } catch (error) {
+        toast.error(toErrorMessage(error));
+      }
+    },
+    [toast],
+  );
+  return { pending, run };
+}
+
+export function ComposerControl({
+  item,
+  surface,
+  disabled = false,
+  open,
+  onOpenChange,
+  onActionComplete,
+}: ComposerControlProps) {
+  const { t } = useTranslation();
+  const anchorRef = useRef<View>(null);
+  const isSheet = surface === "sheet";
+  const isField = surface === "field";
+  const sheetHeader = useMemo<SheetHeader>(() => ({ title: item.title }), [item.title]);
+  const view = useMemo(() => describeControl(item, surface, t), [item, surface, t]);
+
+  const { pending, run } = usePendingRun();
+  const handlePress = useCallback(() => {
+    if (item.type === "toggle") run(() => item.onChange(!item.value));
+    else if (item.type === "action") run(item.onPress);
+    onActionComplete?.();
+  }, [item, onActionComplete, run]);
+  const handleOpenPress = useCallback(() => onOpenChange(!open), [onOpenChange, open]);
+  const handleSelect = useCallback(
+    (value: string) => {
+      if (item.type === "select") run(() => item.onChange(value));
+      else if (item.type === "toggle") run(() => item.onChange(value === "true"));
+    },
+    [item, run],
+  );
+
+  const select = item.type === "select" ? item : null;
+  const accessibilityLabel = item.accessibilityLabel ?? view.tooltip;
+  const trigger = isField ? (
+    <FieldControlTrigger
+      ref={anchorRef}
+      item={item}
+      view={view}
+      accessibilityLabel={accessibilityLabel}
+      disabled={disabled || pending}
+      onPress={view.opensList ? handleOpenPress : handlePress}
+    />
+  ) : (
+    <AgentControlTrigger
+      ref={anchorRef}
+      icon={item.icon}
+      iconColor={item.highlight ? styles[item.highlight].color : undefined}
+      surface={surface}
+      label={item.title}
+      value={view.value}
+      showToolbarLabel={!view.iconOnly}
+      showCaret={select?.showCaret === true && !isSheet}
+      open={view.opensList && open}
+      disabled={disabled || pending}
+      onPress={view.opensList ? handleOpenPress : handlePress}
+      accessibilityLabel={accessibilityLabel}
+      testID={item.testID}
+    />
+  );
+
+  return (
+    <>
+      {isSheet || isField ? (
+        trigger
+      ) : (
+        <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
+          <TooltipTrigger asChild triggerRefProp="ref">
+            {trigger}
+          </TooltipTrigger>
+          <TooltipContent side="top" align="center" offset={8}>
+            <Text style={styles.tooltipText}>{view.tooltip}</Text>
+          </TooltipContent>
+        </Tooltip>
+      )}
+      {view.opensList ? (
+        <Combobox
+          options={view.options}
+          value={view.selectedId}
+          onSelect={handleSelect}
+          open={open}
+          onOpenChange={onOpenChange}
+          anchorRef={anchorRef}
+          presentation={isSheet ? "push" : undefined}
+          desktopPlacement={DESKTOP_PLACEMENT[surface]}
+          {...listProps(select)}
+          header={isSheet ? sheetHeader : undefined}
+        />
+      ) : null}
+    </>
+  );
+}
+
+/** Where a list opens on desktop; the sheet has its own presentation. */
+const DESKTOP_PLACEMENT = {
+  toolbar: "top-start",
+  sheet: undefined,
+  field: "bottom-start",
+} as const;
+
+/** What a field shows: a badge has no label, so a toggle names itself beside its state. */
+function fieldValue(item: ComposerControlItem, view: ControlView, compact: boolean): string {
+  if (item.type === "action") return item.title;
+  if (item.type === "toggle" && !compact) return `${item.title}: ${view.value}`;
+  return view.value;
+}
+
+const FieldControlTrigger = forwardRef<
+  View,
+  {
+    item: ComposerControlItem;
+    view: ControlView;
+    accessibilityLabel: string;
+    disabled: boolean;
+    onPress: () => void;
+  }
+>(function FieldControlTrigger({ item, view, accessibilityLabel, disabled, onPress }, ref) {
+  const compact = useIsCompactFormFactor();
+  const Icon = item.icon;
+  const iconColor = item.highlight ? styles[item.highlight].color : styles.fieldIcon.color;
+  const icon = useMemo(() => <Icon size={ICON_SIZE.sm} color={iconColor} />, [Icon, iconColor]);
+  return (
+    <FieldTrigger
+      ref={ref}
+      variant={compact ? "field" : "badge"}
+      label={item.title}
+      icon={icon}
+      value={fieldValue(item, view, compact)}
+      tooltip={view.tooltip}
+      accessibilityLabel={accessibilityLabel}
+      disabled={disabled}
+      onPress={onPress}
+      testID={item.testID}
+    />
+  );
+});
+
+interface ComposerControlsProps {
+  items: readonly ComposerControlItem[];
+  surface: ComposerControlSurface;
+  disabled?: boolean;
+  /** The id of the item whose list is open. */
+  openId: string | null;
+  onOpenIdChange: (id: string | null) => void;
+  onActionComplete?: () => void;
+}
+
+/** A row of Paseo-owned controls that share one open list at a time. */
+export function ComposerControls({
+  items,
+  onOpenIdChange,
+  openId,
+  ...rest
+}: ComposerControlsProps) {
+  return (
+    <>
+      {items.map((item) => (
+        <ComposerControlSlot
+          key={item.id}
+          item={item}
+          open={openId === item.id}
+          onOpenIdChange={onOpenIdChange}
+          {...rest}
+        />
+      ))}
+    </>
+  );
+}
+
+function ComposerControlSlot({
+  item,
+  open,
+  onOpenIdChange,
+  ...rest
+}: Omit<ComposerControlsProps, "items" | "openId"> & { item: ComposerControlItem; open: boolean }) {
+  const handleOpenChange = useCallback(
+    (next: boolean) => onOpenIdChange(next ? item.id : null),
+    [item.id, onOpenIdChange],
+  );
+  return <ComposerControl item={item} open={open} onOpenChange={handleOpenChange} {...rest} />;
+}
+
+const styles = StyleSheet.create((theme) => ({
+  fieldIcon: { color: theme.colors.foregroundMuted },
+  blue: { color: theme.colors.palette.blue[400] },
+  green: { color: theme.colors.palette.green[400] },
+  yellow: { color: theme.colors.palette.yellow[400] },
+  tooltipText: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.base,
+    lineHeight: theme.fontSize.base * 1.4,
+  },
+}));
diff --git a/packages/app/src/composer/agent-controls/control-items.tsx b/packages/app/src/composer/agent-controls/control-items.tsx
new file mode 100644
index 0000000000..590f60dfd3
--- /dev/null
+++ b/packages/app/src/composer/agent-controls/control-items.tsx
@@ -0,0 +1,161 @@
+import { useMemo } from "react";
+import type { TFunction } from "i18next";
+import { useTranslation } from "react-i18next";
+import { DensityIcon } from "@/components/ui/density-icon";
+import type { AgentOptionControl, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { getAgentFeatureIcon, ThinkingIcon } from "@/agent-controls/icons";
+import {
+  getControlTooltip,
+  isControlActive,
+  readSelectOption,
+  readToggleOption,
+  type ComposerOptionControls,
+} from "@/agent-controls/option-controls";
+import { ComboboxItem, type ComboboxOption } from "@/components/ui/combobox";
+import {
+  type ComposerControlItem,
+  type ComposerControlSurface,
+} from "@/composer/agent-controls/composer-control";
+import type { ComposerControlPresentation } from "@/composer/agent-controls/layout";
+import { getAgentControlHintKey, getFeatureHighlightColor } from "@/composer/agent-controls/utils";
+
+const SEARCH_THRESHOLD = 6;
+
+function getFeatureHighlight(
+  control: AgentOptionControl,
+  options: ProviderOptions,
+): ComposerControlItem["highlight"] {
+  if (!isControlActive(control, options)) return undefined;
+  const color = getFeatureHighlightColor(control.key);
+  return color === "default" ? undefined : color;
+}
+
+function toFeatureItem(
+  control: AgentOptionControl,
+  optionControls: ComposerOptionControls,
+): ComposerControlItem {
+  const { options, onSetOption } = optionControls;
+  const base = {
+    id: `feature-${control.key}`,
+    title: control.label,
+    icon: getAgentFeatureIcon(control.icon),
+    highlight: getFeatureHighlight(control, options),
+    testID: `agent-feature-${control.key}`,
+  };
+  if (control.type === "toggle") {
+    return {
+      ...base,
+      type: "toggle",
+      tooltip: getControlTooltip(control),
+      value: readToggleOption(control, options),
+      onChange: (value) => onSetOption(control.key, value),
+    };
+  }
+  const iconOnly = control.desktopTrigger === "icon";
+  return {
+    ...base,
+    type: "select",
+    tooltip: getControlTooltip(control),
+    value: readSelectOption(control, options),
+    choices: control.choices,
+    iconOnly,
+    onChange: (value) => onSetOption(control.key, value),
+  };
+}
+
+interface ThinkingControl {
+  options: readonly { id: string; label: string }[];
+  selectedId: string | undefined;
+  onSelect: (id: string) => void;
+  /** The select's displayed label, falling back like the compact model sheet. */
+  displayLabel: string;
+}
+
+/** The thinking select and the option controls, as the data `ComposerControl` draws. */
+export function useAgentControlItems({
+  surface,
+  presentation,
+  thinking,
+  optionControls,
+}: {
+  surface: ComposerControlSurface;
+  presentation: ComposerControlPresentation;
+  thinking: ThinkingControl | null;
+  optionControls: ComposerOptionControls | undefined;
+}): { thinking: ComposerControlItem[]; features: ComposerControlItem[] } {
+  const { t } = useTranslation();
+
+  const thinkingItem = useMemo(
+    () => (thinking ? [toThinkingItem({ thinking, surface, presentation, t })] : []),
+    [presentation, surface, t, thinking],
+  );
+  const features = useMemo(
+    () =>
+      optionControls
+        ? optionControls.controls.map((control) => toFeatureItem(control, optionControls))
+        : [],
+    [optionControls],
+  );
+  return { thinking: thinkingItem, features };
+}
+
+function toThinkingItem({
+  thinking,
+  surface,
+  presentation,
+  t,
+}: {
+  thinking: ThinkingControl;
+  surface: ComposerControlSurface;
+  presentation: ComposerControlPresentation;
+  t: TFunction;
+}): ComposerControlItem {
+  const isSheet = surface === "sheet";
+  return {
+    id: "thinking",
+    type: "select",
+    title: t("agentControls.thinking.title"),
+    icon: ThinkingIcon,
+    tooltip: t(getAgentControlHintKey("thinking")),
+    accessibilityLabel: t("agentControls.thinking.selectWithValue", {
+      value: thinking.displayLabel,
+    }),
+    testID: isSheet ? "agent-controls-thinking" : "agent-thinking-selector",
+    value: thinking.options.some((option) => option.id === thinking.selectedId)
+      ? (thinking.selectedId ?? null)
+      : (thinking.options[0]?.id ?? null),
+    choices: thinking.options.map((option) => ({ value: option.id, label: option.label })),
+    onChange: thinking.onSelect,
+    iconOnly: !presentation.showThinkingLabel,
+    showCaret: presentation.showCarets,
+    searchable: !isSheet && thinking.options.length > SEARCH_THRESHOLD,
+    desktopMinWidth: 200,
+    renderOption: (args) => <ThinkingOption {...args} />,
+  };
+}
+
+function ThinkingOption({
+  option,
+  selected,
+  active,
+  onPress,
+}: {
+  option: ComboboxOption;
+  selected: boolean;
+  active: boolean;
+  onPress: () => void;
+}) {
+  const leadingSlot = useMemo(
+    () => <DensityIcon icon={ThinkingIcon} size="md" color="foreground" />,
+    [],
+  );
+  return (
+    <ComboboxItem
+      label={option.label}
+      selected={selected}
+      active={active}
+      onPress={onPress}
+      leadingSlot={leadingSlot}
+    />
+  );
+}
diff --git a/packages/app/src/composer/agent-controls/control.tsx b/packages/app/src/composer/agent-controls/control.tsx
index 64b8b39100..189d381e9b 100644
--- a/packages/app/src/composer/agent-controls/control.tsx
+++ b/packages/app/src/composer/agent-controls/control.tsx
@@ -2,6 +2,7 @@ import { forwardRef, useCallback, type ComponentProps } from "react";
 import { Text, View, type PressableStateCallbackType } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { ComboboxTrigger } from "@/components/ui/combobox-trigger";
+import { toolbarContentSlot, toolbarSlot } from "@/components/ui/control-geometry";
 import { useComposerControlLayout } from "@/composer/agent-controls/layout-context";
 import { ComposerToolbarGlyph } from "@/composer/agent-controls/glyph";
 import type { AgentControlIcon } from "@/agent-controls/icons";
@@ -41,10 +42,13 @@ export const AgentControlTrigger = forwardRef<View, AgentControlTriggerProps>(
     },
     ref,
   ) {
-    const { glyphSize } = useComposerControlLayout();
+    const { glyphs } = useComposerControlLayout();
+    const glyphRole = showToolbarLabel ? "label" : "icon";
+    const glyph = glyphs[glyphRole];
     const isSheet = surface === "sheet";
-    const resolvedGlyphSize = isSheet ? 16 : glyphSize;
-    const resolvedIconColor = iconColor ?? styles.iconColor.color;
+    const toolbarIconColor =
+      glyph.tone === "foreground" ? styles.iconColorForeground.color : styles.iconColor.color;
+    const resolvedIconColor = iconColor ?? (isSheet ? styles.iconColor.color : toolbarIconColor);
     const showValue = isSheet || showToolbarLabel;
     const triggerStyle = useCallback(
       ({ pressed, hovered }: PressableStateCallbackType) => [
@@ -69,14 +73,15 @@ export const AgentControlTrigger = forwardRef<View, AgentControlTriggerProps>(
         accessibilityLabel={accessibilityLabel}
         testID={testID}
         chevron={showCaret ? undefined : null}
+        block={isSheet}
       >
         {isSheet ? (
           <View style={styles.sheetGlyph}>
-            <Icon size={resolvedGlyphSize} color={resolvedIconColor} />
+            <Icon size={16} color={resolvedIconColor} />
           </View>
         ) : (
-          <ComposerToolbarGlyph size={resolvedGlyphSize}>
-            <Icon size={resolvedGlyphSize} color={resolvedIconColor} />
+          <ComposerToolbarGlyph role={glyphRole}>
+            <Icon size={glyph.size} strokeWidth={glyph.strokeWidth} color={resolvedIconColor} />
           </ComposerToolbarGlyph>
         )}
         {isSheet ? (
@@ -96,18 +101,17 @@ export const AgentControlTrigger = forwardRef<View, AgentControlTriggerProps>(
 
 const styles = StyleSheet.create((theme) => ({
   toolbarControl: {
-    height: 28,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
     alignItems: "center",
     gap: theme.spacing[1],
-    paddingHorizontal: theme.spacing[2],
-    borderRadius: theme.borderRadius["2xl"],
+    ...toolbarContentSlot(),
+    borderRadius: theme.borderRadius.full,
     backgroundColor: "transparent",
   },
   toolbarIconOnly: {
-    width: 28,
+    ...toolbarSlot(),
     flexShrink: 0,
     paddingHorizontal: 0,
     justifyContent: "center",
@@ -159,7 +163,7 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: theme.colors.surface2,
   },
   pressed: {
-    backgroundColor: theme.colors.surface0,
+    backgroundColor: theme.colors.surface2,
   },
   disabled: {
     opacity: 0.5,
@@ -167,4 +171,7 @@ const styles = StyleSheet.create((theme) => ({
   iconColor: {
     color: theme.colors.foregroundMuted,
   },
+  iconColorForeground: {
+    color: theme.colors.foreground,
+  },
 }));
diff --git a/packages/app/src/composer/agent-controls/glyph.tsx b/packages/app/src/composer/agent-controls/glyph.tsx
index 73b2a220c1..7763d1c2b5 100644
--- a/packages/app/src/composer/agent-controls/glyph.tsx
+++ b/packages/app/src/composer/agent-controls/glyph.tsx
@@ -1,10 +1,22 @@
 import type { ReactNode } from "react";
-import { StyleSheet, View } from "react-native";
+import { View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { TOOLBAR_GLYPH_SIZES, type ToolbarGlyphs } from "@/components/ui/control-geometry";
 
-export function ComposerToolbarGlyph({ children, size }: { children: ReactNode; size: number }) {
+/**
+ * The slot a composer toolbar control's glyph sits in; see `toolbarGlyphsFor`. `label` when the
+ * glyph sits beside a label, `icon` when the glyph is the whole control.
+ */
+export function ComposerToolbarGlyph({
+  role,
+  children,
+}: {
+  role: keyof ToolbarGlyphs;
+  children: ReactNode;
+}) {
   return (
     <View
-      style={size >= 20 ? styles.native : styles.web}
+      style={role === "label" ? styles.labelSlot : styles.iconSlot}
       accessibilityElementsHidden
       importantForAccessibility="no-hide-descendants"
       pointerEvents="none"
@@ -14,19 +26,9 @@ export function ComposerToolbarGlyph({ children, size }: { children: ReactNode;
   );
 }
 
+const slot = { flexShrink: 0, alignItems: "center", justifyContent: "center" } as const;
+
 const styles = StyleSheet.create({
-  web: {
-    width: 16,
-    height: 16,
-    flexShrink: 0,
-    alignItems: "center",
-    justifyContent: "center",
-  },
-  native: {
-    width: 20,
-    height: 20,
-    flexShrink: 0,
-    alignItems: "center",
-    justifyContent: "center",
-  },
+  iconSlot: { ...slot, width: TOOLBAR_GLYPH_SIZES.icon, height: TOOLBAR_GLYPH_SIZES.icon },
+  labelSlot: { ...slot, width: TOOLBAR_GLYPH_SIZES.label, height: TOOLBAR_GLYPH_SIZES.label },
 });
diff --git a/packages/app/src/composer/agent-controls/index.tsx b/packages/app/src/composer/agent-controls/index.tsx
index 72795289cf..6a1549aa62 100644
--- a/packages/app/src/composer/agent-controls/index.tsx
+++ b/packages/app/src/composer/agent-controls/index.tsx
@@ -1,13 +1,4 @@
-import {
-  memo,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ReactElement,
-  type RefObject,
-} from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { router } from "expo-router";
 import {
@@ -17,16 +8,12 @@ import {
   Keyboard,
   useWindowDimensions,
   type LayoutChangeEvent,
-  type PressableStateCallbackType,
-  type StyleProp,
-  type ViewStyle,
 } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useShallow } from "zustand/shallow";
 import { Settings2 } from "lucide-react-native";
-import { getAgentFeatureIcon, ThinkingIcon } from "@/agent-controls/icons";
+import { readSelectOption, type ComposerOptionControls } from "@/agent-controls/option-controls";
 import { formatThinkingOptionLabel } from "@/agent-controls/labels";
-import { ComboboxTrigger } from "@/components/ui/combobox-trigger";
 import { CombinedModelSelector } from "@/components/combined-model-selector";
 import {
   buildProviderSelectorProviders,
@@ -38,7 +25,6 @@ import { useSessionStore } from "@/stores/session-store";
 import { useProvidersSnapshot } from "@/hooks/use-providers-snapshot";
 import { resolveProviderDefinition } from "@/utils/provider-definitions";
 import { mergeProviderPreferences, useFormPreferences } from "@/hooks/use-form-preferences";
-import { Combobox, ComboboxItem, type ComboboxOption } from "@/components/ui/combobox";
 import {
   AgentModeControl,
   useLiveAgentModeControl,
@@ -47,20 +33,27 @@ import {
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import type {
-  AgentFeature,
+  AgentOptionControl,
+  JsonValue,
+  ProviderOptions,
   AgentMode,
   AgentModelDefinition,
   AgentProvider,
 } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import {
-  getFeatureHighlightColor,
-  isFeatureActive,
-  getFeatureTooltip,
   getAgentControlHintKey,
   resolveAgentModelSelection,
+  resolveProviderSnapshotEntry,
 } from "@/composer/agent-controls/utils";
 import { useIsCompactFormFactor } from "@/constants/layout";
+import {
+  controlSizingForLayout,
+  TOOLBAR_CONTROL_GAP,
+  toolbarGlyphColor,
+  type ToolbarGlyphs,
+  toolbarSlot,
+} from "@/components/ui/control-geometry";
 import { readMeasuredWidth } from "@/hooks/use-container-width";
 import { useToast } from "@/contexts/toast-context";
 import { toErrorMessage } from "@/utils/error-messages";
@@ -70,18 +63,32 @@ import {
   type AgentControlCommandCenterSource,
 } from "@/command-center/agent-control-registration";
 import { useComposerKeyboardScope } from "@/composer/keyboard-scope";
-import { isNative } from "@/constants/platform";
 import {
+  composerToolbarGeometry,
   resolveComposerControlDensity,
   resolveComposerControlPresentation,
-  resolveComposerToolbarGlyphSize,
   type ComposerControlDensity,
   type ComposerControlPresentation,
 } from "@/composer/agent-controls/layout";
 import { ComposerControlLayoutProvider } from "@/composer/agent-controls/layout-context";
 import { ComposerToolbarGlyph } from "@/composer/agent-controls/glyph";
-import { AgentControlTrigger } from "@/composer/agent-controls/control";
+import {
+  ComposerControls,
+  type ComposerControlItem,
+} from "@/composer/agent-controls/composer-control";
+import { useAgentControlItems } from "@/composer/agent-controls/control-items";
 import { CompactModelSheet } from "@/composer/agent-controls/model-sheet";
+import { useComposerSheetBridge } from "@/composer/agent-controls/sheet-bridge";
+import { draftComposerAgent } from "@/composer/draft/composer-agent";
+import { agentComposer } from "@/composer/agent-composer";
+import { composerModelFromHalves } from "@/composer/halves-model";
+import { ComposerModelProvider } from "@/composer/model";
+import { ComposerAgentProvider, useComposerInput } from "@/composer/session";
+import { PluginComposerItems, usePluginComposerItemCount } from "@/plugins/composer-items";
+import {
+  PluginToolbarSlot,
+  usePluginToolbarWidth,
+} from "@/composer/agent-controls/plugin-toolbar-slot";
 import {
   useAgentProfileEditor,
   useAgentProfilePicker,
@@ -98,15 +105,11 @@ interface AgentControlOption {
   label: string;
 }
 
-type AgentControlSelector = "provider" | "mode" | "model" | "thinking" | `feature-${string}`;
-
 const EMPTY_AGENT_PROVIDER_DEFINITIONS: AgentProviderDefinition[] = [];
+const EMPTY_OPTIONS: ProviderOptions = {};
 
 interface ControlledAgentControlsProps {
   provider: string;
-  providerOptions?: AgentControlOption[];
-  selectedProviderId?: string;
-  onSelectProvider?: (providerId: string) => void;
   modelOptions?: AgentControlOption[];
   selectedModelId?: string;
   onSelectModel?: (modelId: string) => void;
@@ -122,8 +125,7 @@ interface ControlledAgentControlsProps {
   onEditAgentProfiles?: () => void;
   onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
   onEditAgentProfile?: (profileId: string) => void;
-  features?: AgentFeature[];
-  onSetFeature?: (featureId: string, value: unknown) => void;
+  optionControls?: ComposerOptionControls;
   onDropdownClose?: () => void;
   onModelSelectorOpen?: () => void;
   onRetryModelProvider?: (provider: AgentProvider) => void;
@@ -145,13 +147,17 @@ export interface DraftAgentControlsProps {
   isModelLoading: boolean;
   modelSelectorProviders: ProviderSelectorProvider[];
   isAllModelsLoading: boolean;
-  onSelectProviderAndModel: (provider: AgentProvider, modelId: string) => void;
+  /** `false` when the provider is unknown or not ready. */
+  onSelectProviderAndModel: (provider: AgentProvider, modelId: string) => boolean;
   thinkingOptions: NonNullable<AgentModelDefinition["thinkingOptions"]>;
   selectedThinkingOptionId: string;
   onSelectThinkingOption: (thinkingOptionId: string) => void;
   onApplyAgentProfile: DraftAgentProfileControls["applyProfile"];
-  features?: AgentFeature[];
-  onSetFeature?: (featureId: string, value: unknown) => void;
+  /** The controls the daemon described for the draft; absent until it answers. */
+  optionControls?: ComposerOptionControls;
+  /** What the draft will create with, edits included, whether or not the daemon has answered. */
+  options: ProviderOptions;
+  onSetOption: (key: string, value: unknown) => void;
   onDropdownClose?: () => void;
   onModelSelectorOpen?: () => void;
   onRetryModelProvider?: (provider: AgentProvider) => void;
@@ -159,6 +165,11 @@ export interface DraftAgentControlsProps {
   disabled?: boolean;
   modelSelectorServerId?: string | null;
   isCompactLayout?: boolean;
+  /** Which composer a plugin's `useComposer()` reports. */
+  context?: "draft" | "new-workspace";
+  /** What plugins set on the agent this draft creates. */
+  metadata: Record<string, JsonValue>;
+  onSetMetadata: (patch: Record<string, JsonValue>) => void;
 }
 
 interface AgentControlsProps {
@@ -211,59 +222,30 @@ function getModeProviderDefinitions(modeControl: AgentModeControlValue | null) {
   return modeControl?.providerDefinitions ?? EMPTY_AGENT_PROVIDER_DEFINITIONS;
 }
 
-function getFeatureIconColor(
-  feature: AgentFeature,
-  palette: {
-    blue: { 400: string };
-    green: { 400: string };
-    yellow: { 400: string };
-  },
-  foregroundMuted: string,
-): string {
-  if (!isFeatureActive(feature)) {
-    return foregroundMuted;
-  }
-
-  switch (getFeatureHighlightColor(feature.id)) {
-    case "blue":
-      return palette.blue[400];
-    case "green":
-      return palette.green[400];
-    case "yellow":
-      return palette.yellow[400];
-    default:
-      return foregroundMuted;
-  }
-}
-
-type ActiveSheet = "thinking" | "features" | null;
+type ActiveSheet = "features" | null;
 
 function resolveHasAnyControl({
-  providerOptions,
   canSelectModel,
   thinkingOptions,
-  features,
+  controls,
   hasMode,
+  pluginItemCount,
 }: {
-  providerOptions: AgentControlOption[] | undefined;
   canSelectModel: boolean;
   thinkingOptions: AgentControlOption[] | undefined;
-  features: AgentFeature[] | undefined;
+  controls: readonly AgentOptionControl[] | undefined;
   hasMode: boolean;
+  pluginItemCount: number;
 }) {
   return (
-    Boolean(providerOptions?.length) ||
     canSelectModel ||
     Boolean(thinkingOptions?.length) ||
-    Boolean(features?.length) ||
-    hasMode
+    Boolean(controls?.length) ||
+    hasMode ||
+    pluginItemCount > 0
   );
 }
 
-function toComboboxOptions(options: AgentControlOption[] | undefined): ComboboxOption[] {
-  return (options ?? []).map((o) => ({ id: o.id, label: o.label }));
-}
-
 function toThinkingControlOptions(options: AgentControlOption[] | undefined): AgentControlOption[] {
   return (options ?? []).map((option) => ({
     id: option.id,
@@ -327,42 +309,21 @@ function buildFallbackModelSelectorProviders(
   ];
 }
 
-function makeBadgePressableStyle(
-  baseStyle: StyleProp<ViewStyle>,
-  disabledStyle: StyleProp<ViewStyle>,
-  disabled: boolean,
-  isOpen: boolean,
-) {
-  return ({ pressed, hovered }: PressableStateCallbackType) => [
-    baseStyle,
-    hovered && styles.modeBadgeHovered,
-    (pressed || isOpen) && styles.modeBadgePressed,
-    disabled && disabledStyle,
-  ];
-}
-
 function pickSheetModel({
   nextProviderId,
   modelId,
-  currentProvider,
   onSelectProviderAndModel,
-  onSelectProvider,
   onSelectModel,
 }: {
   nextProviderId: string;
   modelId: string;
-  currentProvider: string;
   onSelectProviderAndModel?: (provider: string, modelId: string) => void;
-  onSelectProvider?: (providerId: string) => void;
   onSelectModel?: (modelId: string) => void;
 }) {
   if (onSelectProviderAndModel) {
     onSelectProviderAndModel(nextProviderId, modelId);
     return;
   }
-  if (nextProviderId !== currentProvider) {
-    onSelectProvider?.(nextProviderId);
-  }
   onSelectModel?.(modelId);
 }
 
@@ -393,10 +354,12 @@ type AgentControlsSlice = {
   cwd: string | null;
   runtimeModelId: string | null;
   model: string | null | undefined;
-  features: AgentFeature[] | undefined;
+  options: ProviderOptions | undefined;
+  controls: AgentOptionControl[] | undefined;
   runtimeThinkingOptionId: string | null;
   thinkingOptionId: string | null | undefined;
   lastUsage: unknown;
+  metadata: Record<string, JsonValue> | undefined;
 } | null;
 
 function selectAgentControlsSlice(
@@ -413,25 +376,17 @@ function selectAgentControlsSlice(
     cwd: currentAgent.cwd,
     runtimeModelId: currentAgent.runtimeInfo?.model ?? null,
     model: currentAgent.model,
-    features: currentAgent.features,
+    options: currentAgent.options,
+    controls: currentAgent.controls,
     runtimeThinkingOptionId: currentAgent.runtimeInfo?.thinkingOptionId ?? null,
     thinkingOptionId: currentAgent.thinkingOptionId,
     lastUsage: currentAgent.lastUsage,
+    metadata: currentAgent.metadata,
   };
 }
 
-function resolveSnapshotSelectedEntry(
-  snapshotEntries: ReturnType<typeof useProvidersSnapshot>["entries"],
-  agentProvider: string | undefined,
-) {
-  if (!snapshotEntries || !agentProvider) {
-    return null;
-  }
-  return snapshotEntries.find((e) => e.provider === agentProvider) ?? null;
-}
-
 function resolveSnapshotModeIds(
-  entry: ReturnType<typeof resolveSnapshotSelectedEntry>,
+  entry: ReturnType<typeof resolveProviderSnapshotEntry>,
 ): string[] | null {
   if (entry?.status !== "ready" || !entry.modes) {
     return null;
@@ -460,24 +415,12 @@ function buildAgentProviderModels(
   return map;
 }
 
-function buildOpenChangeHandler(
-  selector: AgentControlSelector,
-  setOpenSelector: (next: AgentControlSelector | null) => void,
-  onDropdownClose?: () => void,
-) {
-  return (nextOpen: boolean) => {
-    setOpenSelector(nextOpen ? selector : null);
-    if (!nextOpen) {
-      onDropdownClose?.();
-    }
-  };
+function densityFolds(density: ComposerControlDensity): boolean {
+  return resolveComposerControlPresentation(density).foldControls;
 }
 
 function ControlledAgentControls({
   provider,
-  providerOptions,
-  selectedProviderId,
-  onSelectProvider,
   modelOptions,
   selectedModelId,
   onSelectModel,
@@ -493,8 +436,7 @@ function ControlledAgentControls({
   onEditAgentProfiles,
   onCreateAgentProfile,
   onEditAgentProfile,
-  features,
-  onSetFeature,
+  optionControls,
   onDropdownClose,
   onModelSelectorOpen,
   onRetryModelProvider,
@@ -503,35 +445,31 @@ function ControlledAgentControls({
   modelSelectorServerId = null,
   isCompactLayout,
 }: ControlledAgentControlsProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const isCompactFormFactor = useIsCompactFormFactor();
   const isCompact = isCompactLayout ?? isCompactFormFactor;
+  // Control sizes follow the window layout, as the toolbar's stylesheet does. A narrow pane in a
+  // wide window (`isCompactLayout`) changes which labels show, never how large a control is.
+  const toolbarSizing = controlSizingForLayout(isCompactFormFactor);
+  const toolbarGeometry = useMemo(() => composerToolbarGeometry(toolbarSizing), [toolbarSizing]);
   const { fontScale } = useWindowDimensions();
   const [activeSheet, setActiveSheet] = useState<ActiveSheet>(null);
-  const [openSelector, setOpenSelector] = useState<AgentControlSelector | null>(null);
-  const initialDensity: ComposerControlDensity = isCompact ? "tight" : "full";
+  const [openSelector, setOpenSelector] = useState<string | null>(null);
+  // A compact composer always folds its controls into the model sheet; the width budget only
+  // decides whether the model keeps its label.
+  const minimumDensity: ComposerControlDensity = isCompact ? "compact" : "full";
+  const initialDensity = minimumDensity;
   const [density, setDensity] = useState<ComposerControlDensity>(initialDensity);
   const densityRef = useRef<ComposerControlDensity>(initialDensity);
   const availableWidthRef = useRef(0);
 
-  const providerAnchorRef = useRef<View>(null);
-  const _modelAnchorRef = useRef<View>(null);
-  const thinkingAnchorRef = useRef<View>(null);
-
-  const canSelectProvider = Boolean(
-    onSelectProvider && providerOptions && providerOptions.length > 0,
-  );
   const canSelectModel = Boolean(onSelectModel);
   const canSelectThinking = Boolean(
     onSelectThinkingOption && thinkingOptions && thinkingOptions.length > 0,
   );
+  const pluginItemCount = usePluginComposerItemCount(modelSelectorServerId);
+  const { width: pluginItemsWidth, onLayout: handlePluginItemsLayout } = usePluginToolbarWidth();
 
-  const displayProvider = findOptionLabel(
-    providerOptions,
-    selectedProviderId,
-    t("agentControls.provider.fallback"),
-  );
   const formattedThinkingOptions = useMemo(
     () => toThinkingControlOptions(thinkingOptions),
     [thinkingOptions],
@@ -543,23 +481,25 @@ function ControlledAgentControls({
   );
 
   const hasAnyControl = resolveHasAnyControl({
-    providerOptions,
     canSelectModel,
     thinkingOptions,
-    features,
+    controls: optionControls?.controls,
     hasMode: modeControl !== null && modeControl !== undefined,
+    pluginItemCount,
   });
   const featureControls = useMemo(
     () =>
-      (features ?? []).map((feature) => {
-        if (feature.type === "toggle") return { type: "toggle" as const };
-        const selectedOption = feature.options.find((option) => option.id === feature.value);
+      (optionControls?.controls ?? []).map((control) => {
+        if (control.type === "toggle") return { type: "toggle" as const };
+        if (control.desktopTrigger === "icon") return { type: "select" as const, label: null };
+        const selected = readSelectOption(control, optionControls?.options ?? {});
+        const choice = control.choices.find((candidate) => candidate.value === selected);
         return {
           type: "select" as const,
-          label: selectedOption?.label ?? feature.label,
+          label: choice?.label ?? control.label,
         };
       }),
-    [features],
+    [optionControls],
   );
   const controlPresence = useMemo(
     () => ({
@@ -567,17 +507,18 @@ function ControlledAgentControls({
       hasThinking: canSelectThinking,
       hasMode: modeControl !== null && modeControl !== undefined,
       features: featureControls,
+      pluginItemsWidth,
       fontScale,
     }),
-    [canSelectModel, canSelectThinking, featureControls, fontScale, modeControl],
+    [canSelectModel, canSelectThinking, featureControls, fontScale, modeControl, pluginItemsWidth],
   );
   const presentation = useMemo(() => resolveComposerControlPresentation(density), [density]);
   const layoutContextValue = useMemo(
     () => ({
-      glyphSize: resolveComposerToolbarGlyphSize(isNative ? "native" : "web"),
+      glyphs: toolbarGeometry.glyphs,
       presentation,
     }),
-    [presentation],
+    [presentation, toolbarGeometry],
   );
 
   const updateDensityForWidth = useCallback(
@@ -586,12 +527,20 @@ function ControlledAgentControls({
         availableWidth,
         currentDensity: densityRef.current,
         controls: controlPresence,
+        geometry: toolbarGeometry,
+        minimumDensity,
       });
       if (nextDensity === densityRef.current) return;
+      // Folding swaps the toolbar controls for the model sheet and back, so whatever menu or
+      // sheet was open belonged to controls that are gone.
+      if (densityFolds(nextDensity) !== densityFolds(densityRef.current)) {
+        setOpenSelector(null);
+        setActiveSheet(null);
+      }
       densityRef.current = nextDensity;
       setDensity(nextDensity);
     },
-    [controlPresence],
+    [controlPresence, minimumDensity, toolbarGeometry],
   );
 
   const handleLayout = useCallback(
@@ -610,65 +559,43 @@ function ControlledAgentControls({
     }
   }, [updateDensityForWidth]);
 
-  const modelDisabled = disabled;
-
-  const comboboxProviderOptions = useMemo<ComboboxOption[]>(
-    () => toComboboxOptions(providerOptions),
-    [providerOptions],
-  );
   const fallbackModelSelectorProviders = useMemo(
     () => buildFallbackModelSelectorProviders(provider, modelOptions),
     [modelOptions, provider],
   );
   const effectiveModelSelectorProviders = modelSelectorProviders ?? fallbackModelSelectorProviders;
-  const comboboxThinkingOptions = useMemo<ComboboxOption[]>(
-    () => toComboboxOptions(formattedThinkingOptions),
-    [formattedThinkingOptions],
-  );
 
-  const renderThinkingOption = useCallback(
-    (args: { option: ComboboxOption; selected: boolean; active: boolean; onPress: () => void }) => (
-      <ThinkingComboboxOption
-        option={args.option}
-        selected={args.selected}
-        active={args.active}
-        onPress={args.onPress}
-        iconColor={theme.colors.foreground}
-      />
-    ),
-    [theme.colors.foreground],
+  const thinking = useMemo(
+    () =>
+      canSelectThinking && onSelectThinkingOption
+        ? {
+            options: formattedThinkingOptions,
+            selectedId: selectedThinkingOptionId,
+            onSelect: onSelectThinkingOption,
+            displayLabel: displayThinking,
+          }
+        : null,
+    [
+      canSelectThinking,
+      displayThinking,
+      formattedThinkingOptions,
+      onSelectThinkingOption,
+      selectedThinkingOptionId,
+    ],
   );
+  const items = useAgentControlItems({
+    surface: presentation.foldControls ? "sheet" : "toolbar",
+    presentation,
+    thinking,
+    optionControls,
+  });
 
-  const handleOpenChange = useCallback(
-    (selector: AgentControlSelector) =>
-      buildOpenChangeHandler(selector, setOpenSelector, onDropdownClose),
-    [onDropdownClose],
-  );
-  const handleSheetOpenChange = useCallback(
-    (selector: AgentControlSelector) => (nextOpen: boolean) => {
-      setOpenSelector(nextOpen ? selector : null);
+  const handleToolbarOpenChange = useCallback(
+    (id: string | null) => {
+      setOpenSelector(id);
+      if (id === null) onDropdownClose?.();
     },
-    [],
-  );
-
-  const handleProviderPress = useCallback(() => {
-    handleOpenChange("provider")(openSelector !== "provider");
-  }, [handleOpenChange, openSelector]);
-
-  const handleThinkingPress = useCallback(() => {
-    handleOpenChange("thinking")(openSelector !== "thinking");
-  }, [handleOpenChange, openSelector]);
-
-  const handleProviderOpenChange = useMemo(() => handleOpenChange("provider"), [handleOpenChange]);
-  const handleThinkingOpenChange = useMemo(() => handleOpenChange("thinking"), [handleOpenChange]);
-
-  const handleProviderSelect = useCallback(
-    (id: string) => onSelectProvider?.(id),
-    [onSelectProvider],
-  );
-  const handleThinkingSelect = useCallback(
-    (id: string) => onSelectThinkingOption?.(id),
-    [onSelectThinkingOption],
+    [onDropdownClose],
   );
 
   const handleDesktopModelSelect = useCallback(
@@ -684,17 +611,6 @@ function ControlledAgentControls({
     [onSelectModel, onSelectProviderAndModel, provider],
   );
 
-  const providerPressableStyle = useMemo(
-    () =>
-      makeBadgePressableStyle(
-        styles.modeBadge,
-        styles.disabledBadge,
-        disabled || !canSelectProvider,
-        openSelector === "provider",
-      ),
-    [canSelectProvider, disabled, openSelector],
-  );
-
   const handleOpenSheet = useCallback((sheet: Exclude<ActiveSheet, null>) => {
     Keyboard.dismiss();
     setActiveSheet(sheet);
@@ -702,29 +618,19 @@ function ControlledAgentControls({
 
   const handleCloseSheet = useCallback(() => {
     setActiveSheet(null);
-    if (!isCompact) onDropdownClose?.();
-  }, [isCompact, onDropdownClose]);
-
-  const handleSelectThinkingAndClose = useCallback(
-    (thinkingOptionId: string) => {
-      onSelectThinkingOption?.(thinkingOptionId);
-      setActiveSheet(null);
-    },
-    [onSelectThinkingOption],
-  );
+    if (!presentation.foldControls) onDropdownClose?.();
+  }, [onDropdownClose, presentation.foldControls]);
 
   const handleSheetModelSelect = useCallback(
     (nextProviderId: string, modelId: string) => {
       pickSheetModel({
         nextProviderId,
         modelId,
-        currentProvider: provider,
         onSelectProviderAndModel,
-        onSelectProvider,
         onSelectModel,
       });
     },
-    [onSelectModel, onSelectProvider, onSelectProviderAndModel, provider],
+    [onSelectModel, onSelectProviderAndModel],
   );
 
   if (!hasAnyControl) {
@@ -733,18 +639,13 @@ function ControlledAgentControls({
 
   return (
     <ComposerControlLayoutProvider value={layoutContextValue}>
-      <View style={styles.container} onLayout={handleLayout}>
-        {!isCompact ? (
+      <View style={styles.container} onLayout={handleLayout} testID="agent-controls-toolbar">
+        {!presentation.foldControls ? (
           <DesktopAgentControlsContent
             provider={provider}
-            providerOptions={providerOptions}
-            selectedProviderId={selectedProviderId}
-            modelOptions={modelOptions}
             selectedModelId={selectedModelId}
-            thinkingOptions={formattedThinkingOptions}
-            selectedThinkingOptionId={selectedThinkingOptionId}
-            features={features}
-            onSetFeature={onSetFeature}
+            thinkingItems={items.thinking}
+            featureItems={items.features}
             onApplyAgentProfile={onApplyAgentProfile}
             onEditAgentProfiles={onEditAgentProfiles}
             onCreateAgentProfile={onCreateAgentProfile}
@@ -756,32 +657,16 @@ function ControlledAgentControls({
             agentProfiles={agentProfiles}
             disabled={disabled}
             isModelLoading={isModelLoading}
-            canSelectProvider={canSelectProvider}
             canSelectModel={canSelectModel}
-            canSelectThinking={canSelectThinking}
             modelSelectorProviders={effectiveModelSelectorProviders}
-            modelDisabled={modelDisabled}
-            comboboxProviderOptions={comboboxProviderOptions}
-            comboboxThinkingOptions={comboboxThinkingOptions}
-            displayProvider={displayProvider}
-            displayThinking={displayThinking}
             openSelector={openSelector}
-            providerAnchorRef={providerAnchorRef}
-            thinkingAnchorRef={thinkingAnchorRef}
-            providerPressableStyle={providerPressableStyle}
-            handleProviderPress={handleProviderPress}
-            handleThinkingPress={handleThinkingPress}
-            handleProviderSelect={handleProviderSelect}
-            handleThinkingSelect={handleThinkingSelect}
             handleDesktopModelSelect={handleDesktopModelSelect}
-            handleProviderOpenChange={handleProviderOpenChange}
-            handleThinkingOpenChange={handleThinkingOpenChange}
-            handleOpenChange={handleOpenChange}
-            handleNestedOpenChange={handleSheetOpenChange}
-            renderThinkingOption={renderThinkingOption}
+            handleToolbarOpenChange={handleToolbarOpenChange}
+            handleSheetOpenChange={setOpenSelector}
             modeControl={modeControl}
             presentation={presentation}
-            glyphSize={layoutContextValue.glyphSize}
+            hasPluginItems={pluginItemsWidth > 0}
+            glyphs={layoutContextValue.glyphs}
             activeSheet={activeSheet}
             handleOpenSheet={handleOpenSheet}
             handleCloseSheet={handleCloseSheet}
@@ -791,9 +676,8 @@ function ControlledAgentControls({
           <SheetAgentControlsContent
             provider={provider}
             selectedModelId={selectedModelId}
-            selectedThinkingOptionId={selectedThinkingOptionId}
-            features={features}
-            onSetFeature={onSetFeature}
+            thinkingItems={items.thinking}
+            featureItems={items.features}
             onApplyAgentProfile={onApplyAgentProfile}
             onEditAgentProfiles={onEditAgentProfiles}
             onCreateAgentProfile={onCreateAgentProfile}
@@ -806,40 +690,36 @@ function ControlledAgentControls({
             disabled={disabled}
             isModelLoading={isModelLoading}
             canSelectModel={canSelectModel}
-            canSelectThinking={canSelectThinking}
             modelSelectorProviders={effectiveModelSelectorProviders}
-            modelDisabled={modelDisabled}
-            comboboxThinkingOptions={comboboxThinkingOptions}
             openSelector={openSelector}
-            displayThinking={displayThinking}
-            activeSheet={activeSheet}
-            handleOpenSheet={handleOpenSheet}
-            handleCloseSheet={handleCloseSheet}
+            displayThinking={thinking ? displayThinking : null}
             handleSheetModelSelect={handleSheetModelSelect}
-            handleSelectThinkingAndClose={handleSelectThinkingAndClose}
-            handleOpenChange={handleSheetOpenChange}
-            renderThinkingOption={renderThinkingOption}
+            handleSheetOpenChange={setOpenSelector}
             modeControl={modeControl}
-            glyphSize={layoutContextValue.glyphSize}
+            glyphs={layoutContextValue.glyphs}
+            showLabels={presentation.showModelLabel}
             modelSelectorServerId={modelSelectorServerId}
             canSwitchProvider={Boolean(onSelectProviderAndModel)}
           />
         )}
+        {!isCompact ? (
+          <PluginToolbarSlot
+            serverId={modelSelectorServerId}
+            width={pluginItemsWidth}
+            fits={!presentation.aggregateFeatures}
+            onLayout={handlePluginItemsLayout}
+          />
+        ) : null}
       </View>
     </ComposerControlLayoutProvider>
   );
 }
 
-interface DesktopAgentControlsContentProps {
+interface AgentControlsContentProps {
   provider: string;
-  providerOptions?: AgentControlOption[];
-  selectedProviderId?: string;
-  modelOptions?: AgentControlOption[];
   selectedModelId?: string;
-  thinkingOptions?: AgentControlOption[];
-  selectedThinkingOptionId?: string;
-  features?: AgentFeature[];
-  onSetFeature?: (featureId: string, value: unknown) => void;
+  thinkingItems: ComposerControlItem[];
+  featureItems: ComposerControlItem[];
   onApplyAgentProfile?: (profileId: string) => void;
   onEditAgentProfiles?: () => void;
   onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
@@ -851,57 +731,34 @@ interface DesktopAgentControlsContentProps {
   agentProfiles: AgentProfilePicker | null;
   disabled: boolean;
   isModelLoading: boolean;
-  canSelectProvider: boolean;
   canSelectModel: boolean;
-  canSelectThinking: boolean;
   modelSelectorProviders: ProviderSelectorProvider[];
-  modelDisabled: boolean;
-  comboboxProviderOptions: ComboboxOption[];
-  comboboxThinkingOptions: ComboboxOption[];
-  displayProvider: string;
-  displayThinking: string;
-  openSelector: AgentControlSelector | null;
-  providerAnchorRef: RefObject<View | null>;
-  thinkingAnchorRef: RefObject<View | null>;
-  providerPressableStyle: (state: PressableStateCallbackType) => StyleProp<ViewStyle>;
-  handleProviderPress: () => void;
-  handleThinkingPress: () => void;
-  handleProviderSelect: (id: string) => void;
-  handleThinkingSelect: (id: string) => void;
-  handleDesktopModelSelect: (providerId: string, modelId: string) => void;
-  handleProviderOpenChange: (open: boolean) => void;
-  handleThinkingOpenChange: (open: boolean) => void;
-  handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  handleNestedOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  renderThinkingOption: (args: {
-    option: ComboboxOption;
-    selected: boolean;
-    active: boolean;
-    onPress: () => void;
-  }) => ReactElement;
+  openSelector: string | null;
+  handleSheetOpenChange: (id: string | null) => void;
   modeControl?: AgentModeControlValue | null;
-  presentation: ComposerControlPresentation;
-  glyphSize: number;
-  activeSheet: ActiveSheet;
-  handleOpenSheet: (sheet: Exclude<ActiveSheet, null>) => void;
-  handleCloseSheet: () => void;
+  glyphs: ToolbarGlyphs;
   modelSelectorServerId: string | null;
 }
 
-const DESKTOP_SEARCH_THRESHOLD = 6;
+interface DesktopAgentControlsContentProps extends AgentControlsContentProps {
+  handleDesktopModelSelect: (providerId: string, modelId: string) => void;
+  handleToolbarOpenChange: (id: string | null) => void;
+  presentation: ComposerControlPresentation;
+  hasPluginItems: boolean;
+  activeSheet: ActiveSheet;
+  handleOpenSheet: (sheet: Exclude<ActiveSheet, null>) => void;
+  handleCloseSheet: () => void;
+}
 
 function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
+  const sheetBridge = useComposerSheetBridge();
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const {
     provider,
-    providerOptions,
-    selectedProviderId,
     selectedModelId,
-    thinkingOptions,
-    selectedThinkingOptionId,
-    features,
-    onSetFeature,
+    thinkingItems,
+    featureItems,
     onApplyAgentProfile,
     onEditAgentProfiles,
     onCreateAgentProfile,
@@ -913,75 +770,33 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
     agentProfiles,
     disabled,
     isModelLoading,
-    canSelectProvider,
     canSelectModel,
-    canSelectThinking,
     modelSelectorProviders,
-    modelDisabled,
-    comboboxProviderOptions,
-    comboboxThinkingOptions,
-    displayProvider,
-    displayThinking,
     openSelector,
-    providerAnchorRef,
-    thinkingAnchorRef,
-    providerPressableStyle,
-    handleProviderPress,
-    handleThinkingPress,
-    handleProviderSelect,
-    handleThinkingSelect,
     handleDesktopModelSelect,
-    handleProviderOpenChange,
-    handleThinkingOpenChange,
-    handleOpenChange,
-    handleNestedOpenChange,
-    renderThinkingOption,
+    handleToolbarOpenChange,
+    handleSheetOpenChange,
     modeControl,
     presentation,
-    glyphSize,
+    hasPluginItems,
+    glyphs,
     activeSheet,
     handleOpenSheet,
     handleCloseSheet,
     modelSelectorServerId,
   } = props;
   const modelToolbar = useMemo(
-    () => ({ glyphSize, showCaret: presentation.showCarets }),
-    [glyphSize, presentation.showCarets],
+    () => ({ glyph: glyphs.label, showCaret: presentation.showCarets }),
+    [glyphs, presentation.showCarets],
   );
   const featuresSheetHeader = useMemo<SheetHeader>(
     () => ({ title: t("agentControls.features.title") }),
     [t],
   );
   const handleOpenFeatures = useCallback(() => handleOpenSheet("features"), [handleOpenSheet]);
+  const hasFeatures = featureItems.length > 0 || hasPluginItems;
   return (
     <>
-      {providerOptions && providerOptions.length > 0 ? (
-        <>
-          <ComboboxTrigger
-            ref={providerAnchorRef}
-            collapsable={false}
-            disabled={disabled || !canSelectProvider}
-            onPress={handleProviderPress}
-            style={providerPressableStyle}
-            accessibilityRole="button"
-            accessibilityLabel={t("agentControls.provider.select")}
-            testID="agent-provider-selector"
-          >
-            <Text style={styles.modeBadgeText}>{displayProvider}</Text>
-          </ComboboxTrigger>
-          <Combobox
-            options={comboboxProviderOptions}
-            value={selectedProviderId ?? ""}
-            onSelect={handleProviderSelect}
-            searchable={comboboxProviderOptions.length > DESKTOP_SEARCH_THRESHOLD}
-            open={openSelector === "provider"}
-            onOpenChange={handleProviderOpenChange}
-            anchorRef={providerAnchorRef}
-            desktopPlacement="top-start"
-          />
-        </>
-      ) : null}
-
       {canSelectModel ? (
         <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
           <TooltipTrigger asChild triggerRefProp="ref">
@@ -997,7 +812,7 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
                 onCreateProfile={onCreateAgentProfile}
                 onEditProfile={onEditAgentProfile}
                 isLoading={isModelLoading}
-                disabled={modelDisabled}
+                disabled={disabled}
                 onOpen={onModelSelectorOpen}
                 onClose={onDropdownClose}
                 onRetryProvider={onRetryModelProvider}
@@ -1015,49 +830,17 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
         </Tooltip>
       ) : null}
 
-      {thinkingOptions && thinkingOptions.length > 0 ? (
-        <>
-          <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
-            <TooltipTrigger asChild triggerRefProp="ref">
-              <AgentControlTrigger
-                ref={thinkingAnchorRef}
-                icon={ThinkingIcon}
-                surface="toolbar"
-                label={t("agentControls.thinking.title")}
-                value={displayThinking}
-                showToolbarLabel={presentation.showThinkingLabel}
-                showCaret={presentation.showCarets}
-                open={openSelector === "thinking"}
-                disabled={disabled || !canSelectThinking}
-                onPress={handleThinkingPress}
-                accessibilityLabel={t("agentControls.thinking.selectWithValue", {
-                  value: displayThinking,
-                })}
-                testID="agent-thinking-selector"
-              />
-            </TooltipTrigger>
-            <TooltipContent side="top" align="center" offset={8}>
-              <Text style={styles.tooltipText}>{t(getAgentControlHintKey("thinking"))}</Text>
-            </TooltipContent>
-          </Tooltip>
-          <Combobox
-            options={comboboxThinkingOptions}
-            value={selectedThinkingOptionId ?? ""}
-            onSelect={handleThinkingSelect}
-            searchable={comboboxThinkingOptions.length > DESKTOP_SEARCH_THRESHOLD}
-            open={openSelector === "thinking"}
-            onOpenChange={handleThinkingOpenChange}
-            anchorRef={thinkingAnchorRef}
-            desktopPlacement="top-start"
-            desktopMinWidth={200}
-            renderOption={renderThinkingOption}
-          />
-        </>
-      ) : null}
+      <ComposerControls
+        items={thinkingItems}
+        surface="toolbar"
+        disabled={disabled}
+        openId={openSelector}
+        onOpenIdChange={handleToolbarOpenChange}
+      />
 
       {modeControl ? <AgentModeControl {...modeControl} onClose={onDropdownClose} /> : null}
 
-      {presentation.aggregateFeatures && features?.length ? (
+      {presentation.aggregateFeatures && hasFeatures ? (
         <>
           <Pressable
             onPress={handleOpenFeatures}
@@ -1067,95 +850,59 @@ function DesktopAgentControlsContent(props: DesktopAgentControlsContentProps) {
             accessibilityLabel={t("agentControls.features.open")}
             testID="agent-controls-features"
           >
-            <ComposerToolbarGlyph size={glyphSize}>
-              <Settings2 size={glyphSize} color={theme.colors.foregroundMuted} />
+            <ComposerToolbarGlyph role="icon">
+              <Settings2
+                size={glyphs.icon.size}
+                strokeWidth={glyphs.icon.strokeWidth}
+                color={toolbarGlyphColor(theme, glyphs.icon.tone)}
+              />
             </ComposerToolbarGlyph>
           </Pressable>
           <AdaptiveModalSheet
             header={featuresSheetHeader}
             visible={activeSheet === "features"}
             onClose={handleCloseSheet}
+            contextBridge={sheetBridge}
             testID="agent-features-sheet"
           >
-            {features.map((feature) => (
-              <SheetFeatureItem
-                key={`feature-${feature.id}`}
-                feature={feature}
-                disabled={disabled}
-                openSelector={openSelector}
-                handleOpenChange={handleNestedOpenChange}
-                onSetFeature={onSetFeature}
-              />
-            ))}
+            <ComposerControls
+              items={featureItems}
+              surface="sheet"
+              disabled={disabled}
+              openId={openSelector}
+              onOpenIdChange={handleSheetOpenChange}
+            />
+            <PluginComposerItems serverId={modelSelectorServerId} surface="sheet" />
           </AdaptiveModalSheet>
         </>
       ) : (
-        features?.map((feature) => (
-          <DesktopFeatureItem
-            key={`feature-${feature.id}`}
-            feature={feature}
-            disabled={disabled}
-            openSelector={openSelector}
-            handleOpenChange={handleOpenChange}
-            onSetFeature={onSetFeature}
-            onActionComplete={onDropdownClose}
-          />
-        ))
+        <ComposerControls
+          items={featureItems}
+          surface="toolbar"
+          disabled={disabled}
+          openId={openSelector}
+          onOpenIdChange={handleToolbarOpenChange}
+          onActionComplete={onDropdownClose}
+        />
       )}
     </>
   );
 }
 
-interface SheetAgentControlsContentProps {
-  provider: string;
-  selectedModelId?: string;
-  selectedThinkingOptionId?: string;
-  features?: AgentFeature[];
-  onSetFeature?: (featureId: string, value: unknown) => void;
-  onApplyAgentProfile?: (profileId: string) => void;
-  onEditAgentProfiles?: () => void;
-  onCreateAgentProfile?: (seed: AgentProfileSeed) => void;
-  onEditAgentProfile?: (profileId: string) => void;
-  onDropdownClose?: () => void;
-  onModelSelectorOpen?: () => void;
-  onRetryModelProvider?: (provider: AgentProvider) => void;
-  isRetryingModelProvider: boolean;
-  agentProfiles: AgentProfilePicker | null;
-  disabled: boolean;
-  isModelLoading: boolean;
-  canSelectModel: boolean;
-  canSelectThinking: boolean;
-  modelSelectorProviders: ProviderSelectorProvider[];
-  modelDisabled: boolean;
-  comboboxThinkingOptions: ComboboxOption[];
-  openSelector: AgentControlSelector | null;
-  displayThinking: string;
-  activeSheet: ActiveSheet;
-  handleOpenSheet: (sheet: Exclude<ActiveSheet, null>) => void;
-  handleCloseSheet: () => void;
+interface SheetAgentControlsContentProps extends AgentControlsContentProps {
+  showLabels: boolean;
+  displayThinking: string | null;
   handleSheetModelSelect: (providerId: string, modelId: string) => void;
-  handleSelectThinkingAndClose: (thinkingOptionId: string) => void;
-  handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  renderThinkingOption: (args: {
-    option: ComboboxOption;
-    selected: boolean;
-    active: boolean;
-    onPress: () => void;
-  }) => ReactElement;
-  modeControl?: AgentModeControlValue | null;
-  glyphSize: number;
-  modelSelectorServerId: string | null;
   canSwitchProvider: boolean;
 }
 
 function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
-  const { t } = useTranslation();
+  const sheetBridge = useComposerSheetBridge();
   const {
     provider,
     selectedModelId,
-    selectedThinkingOptionId,
-    features,
-    onSetFeature,
+    thinkingItems,
+    featureItems,
     onApplyAgentProfile,
     onEditAgentProfiles,
     onCreateAgentProfile,
@@ -1168,86 +915,38 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
     disabled,
     isModelLoading,
     canSelectModel,
-    canSelectThinking,
     modelSelectorProviders,
-    modelDisabled,
-    comboboxThinkingOptions,
     openSelector,
     displayThinking,
-    activeSheet,
-    handleOpenSheet,
-    handleCloseSheet,
     handleSheetModelSelect,
-    handleSelectThinkingAndClose,
-    handleOpenChange,
-    renderThinkingOption,
+    handleSheetOpenChange,
     modeControl,
-    glyphSize,
+    glyphs,
+    showLabels,
     modelSelectorServerId,
     canSwitchProvider,
   } = props;
 
-  const thinkingAnchorRef = useRef<View | null>(null);
-
-  const hasThinking = comboboxThinkingOptions.length > 0;
-
-  const handleOpenThinking = useCallback(() => handleOpenSheet("thinking"), [handleOpenSheet]);
-  const handleThinkingSheetOpenChange = useCallback(
-    (nextOpen: boolean) => {
-      if (nextOpen) {
-        handleOpenSheet("thinking");
-      } else {
-        handleCloseSheet();
-      }
-    },
-    [handleCloseSheet, handleOpenSheet],
-  );
-
   const sheetControls = (
     <View style={styles.combinedSheetControls} testID="agent-controls-combined-sheet-controls">
-      {hasThinking ? (
-        <>
-          <AgentControlTrigger
-            ref={thinkingAnchorRef}
-            icon={ThinkingIcon}
-            surface="sheet"
-            label={t("agentControls.thinking.title")}
-            value={displayThinking}
-            open={activeSheet === "thinking"}
-            onPress={handleOpenThinking}
-            disabled={disabled || !canSelectThinking}
-            accessibilityLabel={t("agentControls.thinking.selectWithValue", {
-              value: displayThinking,
-            })}
-            testID="agent-controls-thinking"
-          />
-          <Combobox
-            options={comboboxThinkingOptions}
-            value={selectedThinkingOptionId ?? ""}
-            onSelect={handleSelectThinkingAndClose}
-            searchable={false}
-            title={t("agentControls.thinking.title")}
-            open={activeSheet === "thinking"}
-            onOpenChange={handleThinkingSheetOpenChange}
-            anchorRef={thinkingAnchorRef}
-            renderOption={renderThinkingOption}
-            presentation="push"
-          />
-        </>
-      ) : null}
+      <ComposerControls
+        items={thinkingItems}
+        surface="sheet"
+        disabled={disabled}
+        openId={openSelector}
+        onOpenIdChange={handleSheetOpenChange}
+      />
 
       {modeControl ? <AgentModeControl {...modeControl} surface="sheet" /> : null}
 
-      {(features ?? []).map((feature) => (
-        <SheetFeatureItem
-          key={`feature-${feature.id}`}
-          feature={feature}
-          disabled={disabled}
-          openSelector={openSelector}
-          handleOpenChange={handleOpenChange}
-          onSetFeature={onSetFeature}
-        />
-      ))}
+      <ComposerControls
+        items={featureItems}
+        surface="sheet"
+        disabled={disabled}
+        openId={openSelector}
+        onOpenIdChange={handleSheetOpenChange}
+      />
+      <PluginComposerItems serverId={modelSelectorServerId} surface="sheet" />
     </View>
   );
 
@@ -1256,21 +955,23 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
       providers={modelSelectorProviders}
       selectedProvider={provider}
       selectedModel={selectedModelId ?? ""}
-      thinkingLabel={hasThinking ? displayThinking : null}
+      thinkingLabel={displayThinking}
       onSelect={handleSheetModelSelect}
       profiles={agentProfiles}
       onApplyProfile={onApplyAgentProfile}
       onEditProfiles={onEditAgentProfiles}
       onCreateProfile={onCreateAgentProfile}
       onEditProfile={onEditAgentProfile}
+      contextBridge={sheetBridge}
       isLoading={isModelLoading}
-      disabled={modelDisabled}
+      disabled={disabled}
       onOpen={onModelSelectorOpen}
       onClose={onDropdownClose}
       onRetryProvider={onRetryModelProvider}
       isRetryingProvider={isRetryingModelProvider}
       serverId={modelSelectorServerId}
-      glyphSize={glyphSize}
+      glyphs={glyphs}
+      showLabels={showLabels}
       canSwitchProvider={canSwitchProvider}
     >
       {sheetControls}
@@ -1278,274 +979,15 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
   ) : null;
 }
 
-function DesktopFeatureItem({
-  feature,
-  disabled,
-  openSelector,
-  handleOpenChange,
-  onSetFeature,
-  onActionComplete,
-}: {
-  feature: AgentFeature;
-  disabled: boolean;
-  openSelector: AgentControlSelector | null;
-  handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  onSetFeature?: (featureId: string, value: unknown) => void;
-  onActionComplete?: () => void;
-}) {
-  const { theme } = useUnistyles();
-  const featureSelector: AgentControlSelector = `feature-${feature.id}`;
-  const featureAnchorRef = useRef<View>(null);
-
-  const handleFeatureOpenChange = useMemo(
-    () => handleOpenChange(featureSelector),
-    [handleOpenChange, featureSelector],
-  );
-  const handleSelectPress = useCallback(
-    () => handleFeatureOpenChange(openSelector !== featureSelector),
-    [featureSelector, handleFeatureOpenChange, openSelector],
-  );
-
-  const handleTogglePress = useCallback(() => {
-    if (feature.type === "toggle") {
-      onSetFeature?.(feature.id, !feature.value);
-      onActionComplete?.();
-    }
-  }, [feature, onActionComplete, onSetFeature]);
-
-  const handleSelectOption = useCallback(
-    (optionId: string) => {
-      onSetFeature?.(feature.id, optionId);
-    },
-    [feature.id, onSetFeature],
-  );
-  const comboboxOptions = useMemo<ComboboxOption[]>(
-    () =>
-      feature.type === "select"
-        ? feature.options.map((option) => ({ id: option.id, label: option.label }))
-        : [],
-    [feature],
-  );
-
-  if (feature.type === "toggle") {
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
-    return (
-      <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
-        <TooltipTrigger asChild triggerRefProp="ref">
-          <AgentControlTrigger
-            icon={FeatureIcon}
-            iconColor={getFeatureIconColor(
-              feature,
-              theme.colors.palette,
-              theme.colors.foregroundMuted,
-            )}
-            surface="toolbar"
-            label={feature.label}
-            showToolbarLabel={false}
-            disabled={disabled}
-            onPress={handleTogglePress}
-            accessibilityLabel={getFeatureTooltip(feature)}
-            testID={`agent-feature-${feature.id}`}
-          />
-        </TooltipTrigger>
-        <TooltipContent side="top" align="center" offset={8}>
-          <Text style={styles.tooltipText}>{getFeatureTooltip(feature)}</Text>
-        </TooltipContent>
-      </Tooltip>
-    );
-  }
-
-  if (feature.type === "select") {
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
-    const selectedOption = feature.options.find((o) => o.id === feature.value);
-    const iconOnly = feature.desktopTrigger === "icon";
-    const tooltip = iconOnly
-      ? `${feature.label}: ${selectedOption?.label ?? feature.label}`
-      : getFeatureTooltip(feature);
-    return (
-      <>
-        <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
-          <TooltipTrigger asChild triggerRefProp="ref">
-            <AgentControlTrigger
-              ref={featureAnchorRef}
-              icon={FeatureIcon}
-              iconColor={getFeatureIconColor(
-                feature,
-                theme.colors.palette,
-                theme.colors.foregroundMuted,
-              )}
-              surface="toolbar"
-              label={feature.label}
-              value={selectedOption?.label ?? feature.label}
-              showToolbarLabel={!iconOnly}
-              open={openSelector === featureSelector}
-              disabled={disabled}
-              onPress={handleSelectPress}
-              accessibilityLabel={tooltip}
-              testID={`agent-feature-${feature.id}`}
-            />
-          </TooltipTrigger>
-          <TooltipContent side="top" align="center" offset={8}>
-            <Text style={styles.tooltipText}>{tooltip}</Text>
-          </TooltipContent>
-        </Tooltip>
-        <Combobox
-          options={comboboxOptions}
-          value={String(feature.value)}
-          onSelect={handleSelectOption}
-          open={openSelector === featureSelector}
-          onOpenChange={handleFeatureOpenChange}
-          anchorRef={featureAnchorRef}
-          desktopPlacement="top-start"
-        />
-      </>
-    );
-  }
-
-  return null;
-}
-
-function SheetFeatureItem({
-  feature,
-  disabled,
-  openSelector,
-  handleOpenChange,
-  onSetFeature,
-}: {
-  feature: AgentFeature;
-  disabled: boolean;
-  openSelector: AgentControlSelector | null;
-  handleOpenChange: (selector: AgentControlSelector) => (nextOpen: boolean) => void;
-  onSetFeature?: (featureId: string, value: unknown) => void;
-}) {
-  const { theme } = useUnistyles();
-  const { t } = useTranslation();
-  const featureSelector: AgentControlSelector = `feature-${feature.id}`;
-  const featureAnchorRef = useRef<View>(null);
-
-  const handleFeatureOpenChange = useMemo(
-    () => handleOpenChange(featureSelector),
-    [handleOpenChange, featureSelector],
-  );
-  const handleSelectPress = useCallback(
-    () => handleFeatureOpenChange(openSelector !== featureSelector),
-    [featureSelector, handleFeatureOpenChange, openSelector],
-  );
-  const sheetHeader = useMemo<SheetHeader>(() => ({ title: feature.label }), [feature.label]);
-
-  const handleSelectOption = useCallback(
-    (optionId: string) => {
-      onSetFeature?.(feature.id, feature.type === "toggle" ? optionId === "true" : optionId);
-    },
-    [feature.id, feature.type, onSetFeature],
-  );
-  const comboboxOptions = useMemo<ComboboxOption[]>(() => {
-    if (feature.type === "select") {
-      return feature.options.map((option) => ({ id: option.id, label: option.label }));
-    }
-    return [
-      { id: "true", label: t("agentControls.features.on") },
-      { id: "false", label: t("agentControls.features.off") },
-    ];
-  }, [feature, t]);
-
-  if (feature.type === "toggle") {
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
-    return (
-      <>
-        <AgentControlTrigger
-          ref={featureAnchorRef}
-          icon={FeatureIcon}
-          iconColor={getFeatureIconColor(
-            feature,
-            theme.colors.palette,
-            theme.colors.foregroundMuted,
-          )}
-          surface="sheet"
-          label={feature.label}
-          value={feature.value ? t("agentControls.features.on") : t("agentControls.features.off")}
-          open={openSelector === featureSelector}
-          disabled={disabled}
-          onPress={handleSelectPress}
-          accessibilityLabel={getFeatureTooltip(feature)}
-          testID={`agent-feature-${feature.id}`}
-        />
-        <Combobox
-          options={comboboxOptions}
-          value={String(feature.value)}
-          onSelect={handleSelectOption}
-          open={openSelector === featureSelector}
-          onOpenChange={handleFeatureOpenChange}
-          anchorRef={featureAnchorRef}
-          presentation="push"
-          searchable={false}
-          header={sheetHeader}
-        />
-      </>
-    );
-  }
-
-  if (feature.type === "select") {
-    const FeatureIcon = getAgentFeatureIcon(feature.icon);
-    const selectedOption = feature.options.find((o) => o.id === feature.value);
-    return (
-      <>
-        <AgentControlTrigger
-          ref={featureAnchorRef}
-          icon={FeatureIcon}
-          iconColor={getFeatureIconColor(
-            feature,
-            theme.colors.palette,
-            theme.colors.foregroundMuted,
-          )}
-          surface="sheet"
-          label={feature.label}
-          value={selectedOption?.label ?? feature.label}
-          open={openSelector === featureSelector}
-          disabled={disabled}
-          onPress={handleSelectPress}
-          accessibilityLabel={getFeatureTooltip(feature)}
-          testID={`agent-feature-${feature.id}`}
-        />
-        <Combobox
-          options={comboboxOptions}
-          value={String(feature.value)}
-          onSelect={handleSelectOption}
-          open={openSelector === featureSelector}
-          onOpenChange={handleFeatureOpenChange}
-          anchorRef={featureAnchorRef}
-          presentation="push"
-          header={sheetHeader}
-        />
-      </>
-    );
-  }
-
-  return null;
-}
-
-function ThinkingComboboxOption({
-  option,
-  selected,
-  active,
-  onPress,
-  iconColor,
-}: {
-  option: ComboboxOption;
-  selected: boolean;
-  active: boolean;
-  onPress: () => void;
-  iconColor: string;
-}) {
-  const leadingSlot = useMemo(() => <ThinkingIcon size={16} color={iconColor} />, [iconColor]);
-  return (
-    <ComboboxItem
-      label={option.label}
-      selected={selected}
-      active={active}
-      onPress={onPress}
-      leadingSlot={leadingSlot}
-    />
+function useAgentOptionControls(
+  agent: { controls?: AgentOptionControl[]; options?: ProviderOptions } | null | undefined,
+  onSetOption: ComposerOptionControls["onSetOption"],
+): ComposerOptionControls {
+  const controls = agent?.controls;
+  const options = agent?.options;
+  return useMemo(
+    () => ({ controls: controls ?? [], options: options ?? EMPTY_OPTIONS, onSetOption }),
+    [controls, onSetOption, options],
   );
 }
 
@@ -1574,7 +1016,7 @@ export const AgentControls = memo(function AgentControls({
   } = useProvidersSnapshot(serverId, { cwd: agent?.cwd });
 
   const snapshotSelectedEntry = useMemo(
-    () => resolveSnapshotSelectedEntry(snapshotEntries, agent?.provider),
+    () => resolveProviderSnapshotEntry(snapshotEntries, agent?.provider),
     [snapshotEntries, agent?.provider],
   );
 
@@ -1700,8 +1142,8 @@ export const AgentControls = memo(function AgentControls({
     [activeModelId, agentId, agentProvider, client, toast, updatePreferences],
   );
 
-  const handleSetFeature = useCallback(
-    (featureId: string, value: unknown) => {
+  const handleSetOption = useCallback(
+    (key: string, value: unknown) => {
       if (!client || !agentProvider) {
         return;
       }
@@ -1710,22 +1152,42 @@ export const AgentControls = memo(function AgentControls({
           preferences: current,
           provider: agentProvider,
           updates: {
-            featureValues: {
-              [featureId]: value,
+            options: {
+              [key]: value,
             },
           },
         }),
       ).catch((error) => {
-        console.warn("[AgentControls] persist feature preference failed", error);
+        console.warn("[AgentControls] persist option preference failed", error);
       });
-      void client.setAgentFeature(agentId, featureId, value).catch((error) => {
-        console.warn("[AgentControls] setAgentFeature failed", error);
+      void client.setAgentOptions(agentId, { [key]: value }).catch((error) => {
+        console.warn("[AgentControls] setAgentOptions failed", error);
         toast.error(toErrorMessage(error));
       });
     },
     [agentId, agentProvider, client, toast, updatePreferences],
   );
 
+  const agentOptionControls = useAgentOptionControls(agent, handleSetOption);
+
+  // The agent's composer exists apart from this component; while this is mounted, prompt
+  // commands go through the input the user is typing in.
+  const composer = useMemo(() => agentComposer(serverId, agentId), [agentId, serverId]);
+  const composerInput = useComposerInput();
+  useEffect(
+    () =>
+      composerInput
+        ? composer.attachInput({
+            isLive: composerInput.isLive,
+            setText: composerInput.setText,
+            insertText: composerInput.insertText,
+            isRevealed: composerInput.isRevealed,
+            focus: composerInput.focus,
+          })
+        : undefined,
+    [composer, composerInput],
+  );
+
   const commandCenterControls = useMemo<AgentControlCommandCenterSource>(
     () => ({
       serverId,
@@ -1744,21 +1206,18 @@ export const AgentControls = memo(function AgentControls({
         select: handleSelectThinkingOption,
       },
       modes: commandCenterModes,
-      features: {
-        list: agent?.features,
-        set: handleSetFeature,
-      },
+      optionControls: client ? agentOptionControls : null,
     }),
     [
       activeModelId,
-      agent?.features,
+      agentOptionControls,
+      client,
       agentId,
       agentModelSelectorProviders,
       agentProvider,
       commandCenterModes,
       handleSelectCommandCenterModel,
       handleSelectThinkingOption,
-      handleSetFeature,
       modeProviderDefinitions,
       modelSelection.selectedThinkingId,
       modelSelection.thinkingOptions,
@@ -1790,7 +1249,7 @@ export const AgentControls = memo(function AgentControls({
   }
 
   return (
-    <>
+    <ComposerModelProvider value={composer}>
       {commandCenterRegistration}
       {profileEditor.element}
       <ControlledAgentControls
@@ -1807,8 +1266,7 @@ export const AgentControls = memo(function AgentControls({
         thinkingOptions={thinkingOptions.length > 0 ? thinkingOptions : undefined}
         selectedThinkingOptionId={modelSelection.selectedThinkingId ?? undefined}
         onSelectThinkingOption={handleSelectThinkingOption}
-        features={agent.features}
-        onSetFeature={handleSetFeature}
+        optionControls={agentOptionControls}
         isModelLoading={snapshotIsLoading || selectedProviderIsLoading}
         onModelSelectorOpen={handleModelSelectorOpen}
         onRetryModelProvider={handleRetryModelProvider}
@@ -1819,7 +1277,7 @@ export const AgentControls = memo(function AgentControls({
         modelSelectorServerId={serverId}
         isCompactLayout={isCompactLayout}
       />
-    </>
+    </ComposerModelProvider>
   );
 });
 
@@ -1840,8 +1298,9 @@ export function DraftAgentControls({
   selectedThinkingOptionId,
   onSelectThinkingOption,
   onApplyAgentProfile,
-  features,
-  onSetFeature,
+  optionControls,
+  options,
+  onSetOption,
   onDropdownClose,
   onModelSelectorOpen,
   onRetryModelProvider,
@@ -1849,6 +1308,9 @@ export function DraftAgentControls({
   disabled = false,
   modelSelectorServerId = null,
   isCompactLayout,
+  context = "draft",
+  metadata,
+  onSetMetadata,
 }: DraftAgentControlsProps) {
   const mappedThinkingOptions = useMemo<AgentControlOption[]>(() => {
     return toThinkingControlOptions(thinkingOptions);
@@ -1908,37 +1370,88 @@ export function DraftAgentControls({
     [selectedProvider, providerDefinitions, modeOptions, selectedMode, onSelectMode, disabled],
   );
 
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
+  const isLocked = useCallback(() => disabledRef.current, []);
+  const composerAgent = useMemo(
+    () =>
+      draftComposerAgent({
+        context,
+        disabled,
+        isLocked,
+        selectedProvider,
+        selectedModel,
+        selectedMode,
+        thinking: effectiveSelectedThinkingOption ?? null,
+        options,
+        metadata,
+        onSelectProviderAndModel,
+        onSelectModel,
+        onSelectMode,
+        onSelectThinkingOption,
+        onSetOption,
+        onSetMetadata,
+      }),
+    [
+      context,
+      disabled,
+      isLocked,
+      effectiveSelectedThinkingOption,
+      metadata,
+      onSelectMode,
+      onSelectModel,
+      onSelectProviderAndModel,
+      onSelectThinkingOption,
+      onSetMetadata,
+      onSetOption,
+      options,
+      selectedMode,
+      selectedModel,
+      selectedProvider,
+    ],
+  );
+
+  const composerInput = useComposerInput();
+  const composerModel = useMemo(
+    () =>
+      composerInput
+        ? composerModelFromHalves({ agent: composerAgent, input: composerInput })
+        : null,
+    [composerAgent, composerInput],
+  );
+
   return (
-    <>
-      {profileEditor.element}
-      <ControlledAgentControls
-        provider={selectedProvider ?? ""}
-        modelSelectorProviders={modelSelectorProviders}
-        modelOptions={modelOptions}
-        selectedModelId={selectedModel}
-        onSelectModel={onSelectModel}
-        onSelectProviderAndModel={onSelectProviderAndModel}
-        isModelLoading={isAllModelsLoading}
-        agentProfiles={agentProfiles}
-        onApplyAgentProfile={agentProfiles?.applyProfile}
-        onEditAgentProfiles={handleEditAgentProfiles}
-        onCreateAgentProfile={profileActions.create}
-        onEditAgentProfile={profileActions.edit}
-        thinkingOptions={mappedThinkingOptions.length > 0 ? mappedThinkingOptions : undefined}
-        selectedThinkingOptionId={effectiveSelectedThinkingOption}
-        onSelectThinkingOption={onSelectThinkingOption}
-        features={features}
-        onSetFeature={onSetFeature}
-        onDropdownClose={onDropdownClose}
-        onModelSelectorOpen={onModelSelectorOpen}
-        onRetryModelProvider={onRetryModelProvider}
-        isRetryingModelProvider={isRetryingModelProvider}
-        disabled={disabled}
-        modeControl={modeControl}
-        modelSelectorServerId={modelSelectorServerId}
-        isCompactLayout={isCompactLayout}
-      />
-    </>
+    <ComposerAgentProvider value={composerAgent}>
+      <ComposerModelProvider value={composerModel}>
+        {profileEditor.element}
+        <ControlledAgentControls
+          provider={selectedProvider ?? ""}
+          modelSelectorProviders={modelSelectorProviders}
+          modelOptions={modelOptions}
+          selectedModelId={selectedModel}
+          onSelectModel={onSelectModel}
+          onSelectProviderAndModel={onSelectProviderAndModel}
+          isModelLoading={isAllModelsLoading}
+          agentProfiles={agentProfiles}
+          onApplyAgentProfile={agentProfiles?.applyProfile}
+          onEditAgentProfiles={handleEditAgentProfiles}
+          onCreateAgentProfile={profileActions.create}
+          onEditAgentProfile={profileActions.edit}
+          thinkingOptions={mappedThinkingOptions.length > 0 ? mappedThinkingOptions : undefined}
+          selectedThinkingOptionId={effectiveSelectedThinkingOption}
+          onSelectThinkingOption={onSelectThinkingOption}
+          optionControls={optionControls}
+          onDropdownClose={onDropdownClose}
+          onModelSelectorOpen={onModelSelectorOpen}
+          onRetryModelProvider={onRetryModelProvider}
+          isRetryingModelProvider={isRetryingModelProvider}
+          disabled={disabled}
+          modeControl={modeControl}
+          modelSelectorServerId={modelSelectorServerId}
+          isCompactLayout={isCompactLayout}
+        />
+      </ComposerModelProvider>
+    </ComposerAgentProvider>
   );
 }
 
@@ -1949,30 +1462,16 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 1,
     flexDirection: "row",
     alignItems: "center",
-    gap: theme.spacing[1],
+    gap: TOOLBAR_CONTROL_GAP,
+    // Clips pickers that run out of room.
     overflow: "hidden",
   },
-  modeBadge: {
-    height: 28,
-    flexDirection: "row",
-    alignItems: "center",
-    backgroundColor: "transparent",
-    gap: theme.spacing[1],
-    paddingHorizontal: theme.spacing[2],
-    borderRadius: theme.borderRadius["2xl"],
-  },
   modelControl: {
     minWidth: 0,
     flexShrink: 1,
   },
-  toolbarCaret: {
-    width: 14,
-    height: 14,
-    flexShrink: 0,
-  },
   modeIconBadge: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(),
     alignItems: "center",
     justifyContent: "center",
     paddingHorizontal: 0,
@@ -1980,22 +1479,6 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: "transparent",
     borderRadius: theme.borderRadius.full,
   },
-  modeBadgeHovered: {
-    backgroundColor: theme.colors.surface2,
-  },
-  modeBadgePressed: {
-    backgroundColor: theme.colors.surface0,
-  },
-  disabledBadge: {
-    opacity: 0.5,
-  },
-  modeBadgeText: {
-    minWidth: 0,
-    flexShrink: 1,
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.base,
-    fontWeight: theme.fontWeight.normal,
-  },
   tooltipText: {
     color: theme.colors.foreground,
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/composer/agent-controls/layout-context.tsx b/packages/app/src/composer/agent-controls/layout-context.tsx
index edf8fec7aa..86a9b8cbfe 100644
--- a/packages/app/src/composer/agent-controls/layout-context.tsx
+++ b/packages/app/src/composer/agent-controls/layout-context.tsx
@@ -1,19 +1,18 @@
 import { createContext, useContext, type ReactNode } from "react";
-import type { ComposerControlPresentation } from "@/composer/agent-controls/layout";
+import { toolbarGlyphsFor, type ToolbarGlyphs } from "@/components/ui/control-geometry";
+import {
+  resolveComposerControlPresentation,
+  type ComposerControlPresentation,
+} from "@/composer/agent-controls/layout";
 
 interface ComposerControlLayoutValue {
-  glyphSize: number;
+  glyphs: ToolbarGlyphs;
   presentation: ComposerControlPresentation;
 }
 
 const DEFAULT_LAYOUT: ComposerControlLayoutValue = {
-  glyphSize: 16,
-  presentation: {
-    showCarets: true,
-    showThinkingLabel: true,
-    showModeLabel: true,
-    aggregateFeatures: false,
-  },
+  glyphs: toolbarGlyphsFor("pointer"),
+  presentation: resolveComposerControlPresentation("full"),
 };
 
 const ComposerControlLayoutContext = createContext(DEFAULT_LAYOUT);
diff --git a/packages/app/src/composer/agent-controls/layout.test.ts b/packages/app/src/composer/agent-controls/layout.test.ts
index 2e52972b1c..75dc07451d 100644
--- a/packages/app/src/composer/agent-controls/layout.test.ts
+++ b/packages/app/src/composer/agent-controls/layout.test.ts
@@ -1,30 +1,43 @@
 import { describe, expect, it } from "vitest";
 import {
-  COMPOSER_TOOLBAR_GEOMETRY,
+  composerToolbarGeometry,
   resolveComposerControlDensity,
   resolveComposerControlPresentation,
-  resolveComposerToolbarGlyphSize,
+  resolveModelTriggerLabels,
 } from "./layout";
 
+const POINTER = composerToolbarGeometry("pointer");
+const TOUCH = composerToolbarGeometry("touch");
+
 describe("composer control layout", () => {
-  it("removes labels in priority order as the toolbar narrows", () => {
+  it("removes labels, then folds controls, then drops the model label as the toolbar narrows", () => {
     expect(resolveComposerControlPresentation("full")).toEqual({
       showCarets: true,
       showThinkingLabel: true,
       showModeLabel: true,
       aggregateFeatures: false,
+      foldControls: false,
+      showModelLabel: true,
     });
-    expect(resolveComposerControlPresentation("condensed")).toEqual({
+    expect(resolveComposerControlPresentation("condensed")).toMatchObject({
       showCarets: false,
       showThinkingLabel: false,
       showModeLabel: true,
       aggregateFeatures: true,
+      foldControls: false,
     });
-    expect(resolveComposerControlPresentation("tight")).toEqual({
-      showCarets: false,
-      showThinkingLabel: false,
+    expect(resolveComposerControlPresentation("tight")).toMatchObject({
       showModeLabel: false,
-      aggregateFeatures: true,
+      foldControls: false,
+      showModelLabel: true,
+    });
+    expect(resolveComposerControlPresentation("compact")).toMatchObject({
+      foldControls: true,
+      showModelLabel: true,
+    });
+    expect(resolveComposerControlPresentation("iconOnly")).toMatchObject({
+      foldControls: true,
+      showModelLabel: false,
     });
   });
 
@@ -34,6 +47,7 @@ describe("composer control layout", () => {
       hasThinking: true,
       hasMode: true,
       features: [{ type: "toggle" as const }],
+      pluginItemsWidth: 0,
       fontScale: 1,
     };
 
@@ -41,6 +55,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 420,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("full");
@@ -48,6 +63,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 380,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -55,6 +71,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 290,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -62,6 +79,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 280,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -69,6 +87,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 300,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -76,6 +95,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 312,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -85,6 +105,7 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "condensed" as const,
+      geometry: POINTER,
     };
 
     expect(
@@ -95,6 +116,7 @@ describe("composer control layout", () => {
           hasThinking: true,
           hasMode: true,
           features: [{ type: "toggle" }],
+          pluginItemsWidth: 0,
           fontScale: 1,
         },
       }),
@@ -107,6 +129,7 @@ describe("composer control layout", () => {
           hasThinking: true,
           hasMode: true,
           features: [{ type: "toggle" }, { type: "select", label: "Tools" }],
+          pluginItemsWidth: 0,
           fontScale: 1,
         },
       }),
@@ -119,6 +142,7 @@ describe("composer control layout", () => {
           hasThinking: true,
           hasMode: true,
           features: [{ type: "toggle" }],
+          pluginItemsWidth: 0,
           fontScale: 1.25,
         },
       }),
@@ -129,10 +153,12 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "full" as const,
+      geometry: POINTER,
       controls: {
         hasModel: true,
         hasThinking: true,
         hasMode: true,
+        pluginItemsWidth: 0,
         fontScale: 1,
       },
     };
@@ -154,15 +180,249 @@ describe("composer control layout", () => {
     ).toBe("condensed");
   });
 
-  it("gives every toolbar control one shell and one platform glyph envelope", () => {
-    expect(COMPOSER_TOOLBAR_GEOMETRY).toEqual({
+  describe("plugin items", () => {
+    const base = {
+      availableWidth: 430,
+      currentDensity: "full" as const,
+      geometry: POINTER,
+    };
+    const controls = {
+      hasModel: true,
+      hasThinking: true,
+      hasMode: true,
+      features: [],
+      fontScale: 1,
+      pluginItemsWidth: 0,
+    };
+
+    it("budgets the width the items measured, so an icon toggle fits where a label would not", () => {
+      expect(
+        resolveComposerControlDensity({
+          ...base,
+          controls: { ...controls, pluginItemsWidth: 28 },
+        }),
+      ).toBe("full");
+      expect(
+        resolveComposerControlDensity({
+          ...base,
+          controls: { ...controls, pluginItemsWidth: 125 },
+        }),
+      ).toBe("condensed");
+    });
+
+    it("reserves no overflow button for items that render nothing", () => {
+      // 264 for the condensed row; an overflow button would take it to 296.
+      const tight = { ...base, availableWidth: 290, currentDensity: "tight" as const };
+      expect(resolveComposerControlDensity({ ...tight, controls })).toBe("condensed");
+      expect(
+        resolveComposerControlDensity({
+          ...tight,
+          controls: { ...controls, pluginItemsWidth: 28 },
+        }),
+      ).toBe("tight");
+    });
+
+    it("holds either density at the full floor while the items' width stays the same", () => {
+      // 412 is the full floor with a 28-wide item, and 12 the hysteresis.
+      const atFloor = { ...base, availableWidth: 412 - 12 };
+      const withItem = { ...controls, pluginItemsWidth: 28 };
+      expect(resolveComposerControlDensity({ ...atFloor, controls: withItem })).toBe("full");
+      expect(
+        resolveComposerControlDensity({
+          ...atFloor,
+          currentDensity: "condensed",
+          controls: withItem,
+        }),
+      ).toBe("condensed");
+    });
+  });
+
+  it("gives every toolbar control one shell and one glyph per role and control sizing", () => {
+    const pointerGlyph = { size: 16, strokeWidth: 1.5, tone: "muted" };
+    expect(POINTER).toEqual({
       controlSize: 28,
+      glyphs: { icon: pointerGlyph, label: pointerGlyph },
       controlGap: 4,
       iconLabelGap: 4,
       labelPadding: 8,
       caretSize: 14,
     });
-    expect(resolveComposerToolbarGlyphSize("web")).toBe(16);
-    expect(resolveComposerToolbarGlyphSize("native")).toBe(20);
+    expect(TOUCH).toMatchObject({
+      controlSize: 36,
+      glyphs: {
+        icon: { size: 20, strokeWidth: 1.5, tone: "foreground" },
+        label: { size: 20, strokeWidth: 1.5, tone: "foreground" },
+      },
+      controlGap: 0,
+      labelPadding: 8,
+    });
+  });
+
+  it("budgets an icon-only select as the icon it draws", () => {
+    // Codex's service tier: a select whose toolbar trigger is an icon. 476 with its icon, 543 with
+    // the label "Priority", against a 502-wide toolbar.
+    const controls = {
+      hasModel: true,
+      hasThinking: true,
+      hasMode: true,
+      features: [{ type: "select" as const, label: null }, { type: "toggle" as const }],
+      fontScale: 1,
+      pluginItemsWidth: 28,
+    };
+
+    expect(
+      resolveComposerControlDensity({
+        availableWidth: 502,
+        currentDensity: "condensed",
+        geometry: POINTER,
+        controls,
+      }),
+    ).toBe("full");
+  });
+
+  it("budgets touch-sized controls, so a touch toolbar condenses at a width a pointer one fits", () => {
+    const input = {
+      availableWidth: 400,
+      currentDensity: "full" as const,
+      controls: {
+        hasModel: true,
+        hasThinking: true,
+        hasMode: true,
+        features: [{ type: "toggle" as const }],
+        fontScale: 1,
+        pluginItemsWidth: 0,
+      },
+    };
+
+    expect(resolveComposerControlDensity({ ...input, geometry: POINTER })).toBe("full");
+    expect(resolveComposerControlDensity({ ...input, geometry: TOUCH })).toBe("condensed");
+  });
+
+  describe("touch toolbar on an iPad in portrait, sidebar docked", () => {
+    // Codex: model, thinking, mode and two toggle features. Touch controls lay out at their
+    // 36pt highlight with no gap, so icon-only thinking, mode and features need 108.
+    const controls = {
+      hasModel: true,
+      hasThinking: true,
+      hasMode: true,
+      features: [{ type: "toggle" as const }, { type: "toggle" as const }],
+      fontScale: 1,
+      pluginItemsWidth: 0,
+    };
+
+    it("keeps the model family label with icon-only controls on an empty draft", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 280,
+          currentDensity: "full",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("tight");
+    });
+
+    it("keeps the icon-only controls once an attachment brings in send", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 240,
+          currentDensity: "tight",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("tight");
+    });
+
+    it("folds thinking, mode and features into the model control below their width", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 180,
+          currentDensity: "tight",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("compact");
+    });
+
+    it("drops the model label only after the controls are folded", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 64,
+          currentDensity: "compact",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("iconOnly");
+    });
+  });
+
+  it("starts a compact composer at the folded toolbar however wide it is", () => {
+    const input = {
+      currentDensity: "compact" as const,
+      geometry: TOUCH,
+      minimumDensity: "compact" as const,
+      controls: {
+        hasModel: true,
+        hasThinking: true,
+        hasMode: true,
+        features: [],
+        fontScale: 1,
+        pluginItemsWidth: 0,
+      },
+    };
+
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 600 })).toBe("compact");
+    // The thinking label is not budgeted: it gives way before the model family label does.
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 96 })).toBe("compact");
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 64 })).toBe("iconOnly");
+  });
+});
+
+describe("folded model control labels", () => {
+  it("shows the thinking label while the model label fits beside it in full", () => {
+    expect(
+      resolveModelTriggerLabels({
+        hasThinking: true,
+        measurements: { availableWidth: 191, fullWidth: 190 },
+      }),
+    ).toBe("modelAndThinking");
+  });
+
+  it("hides the thinking label when rounded widths tie", () => {
+    // On the web, 203.14 of labels and a 203 frame both report 203.
+    expect(
+      resolveModelTriggerLabels({
+        hasThinking: true,
+        measurements: { availableWidth: 203, fullWidth: 203 },
+      }),
+    ).toBe("model");
+  });
+
+  it("hides the thinking label before the model label would truncate", () => {
+    expect(
+      resolveModelTriggerLabels({
+        hasThinking: true,
+        measurements: { availableWidth: 189.5, fullWidth: 190 },
+      }),
+    ).toBe("model");
+    expect(
+      resolveModelTriggerLabels({
+        hasThinking: true,
+        measurements: { availableWidth: 90, fullWidth: 190 },
+      }),
+    ).toBe("model");
+  });
+
+  it("decides nothing until both widths are measured", () => {
+    expect(resolveModelTriggerLabels({ hasThinking: true, measurements: {} })).toBe("measuring");
+    expect(
+      resolveModelTriggerLabels({ hasThinking: true, measurements: { availableWidth: 300 } }),
+    ).toBe("measuring");
+    expect(resolveModelTriggerLabels({ hasThinking: true, measurements: { fullWidth: 120 } })).toBe(
+      "measuring",
+    );
+  });
+
+  it("needs no measurement without a thinking label", () => {
+    expect(resolveModelTriggerLabels({ hasThinking: false, measurements: {} })).toBe("model");
   });
 });
diff --git a/packages/app/src/composer/agent-controls/layout.ts b/packages/app/src/composer/agent-controls/layout.ts
index 6f7c78cc73..063723774e 100644
--- a/packages/app/src/composer/agent-controls/layout.ts
+++ b/packages/app/src/composer/agent-controls/layout.ts
@@ -1,41 +1,88 @@
-export type ComposerControlDensity = "full" | "condensed" | "tight";
+import {
+  TOOLBAR_CONTROL_GAPS,
+  TOOLBAR_DISC_SIZES,
+  TOOLBAR_LABEL_PADDING,
+  toolbarGlyphsFor,
+  type ControlSizing,
+  type ToolbarGlyphs,
+} from "@/components/ui/control-geometry";
+
+/**
+ * How much of the toolbar shows, widest first. Each step drops something before the next:
+ * carets and labels, then the mode label, then the thinking, mode and feature controls fold into
+ * the model control's sheet (`compact`, the phone toolbar), then the model's own label.
+ */
+export type ComposerControlDensity = "full" | "condensed" | "tight" | "compact" | "iconOnly";
+
+const DENSITY_LADDER: readonly ComposerControlDensity[] = [
+  "full",
+  "condensed",
+  "tight",
+  "compact",
+  "iconOnly",
+];
 
 export interface ComposerControlPresence {
   hasModel: boolean;
   hasThinking: boolean;
   hasMode: boolean;
   features: readonly ComposerFeatureControlPresence[];
+  /** The plugin items' measured width in the toolbar row; 0 when none of them renders anything. */
+  pluginItemsWidth: number;
   fontScale: number;
 }
 
-export type ComposerFeatureControlPresence = { type: "toggle" } | { type: "select"; label: string };
+export type ComposerFeatureControlPresence =
+  | { type: "toggle" }
+  /** `label` is what the toolbar trigger draws; null for an icon-only trigger. */
+  | { type: "select"; label: string | null };
 
 export interface ComposerControlPresentation {
   showCarets: boolean;
   showThinkingLabel: boolean;
   showModeLabel: boolean;
   aggregateFeatures: boolean;
+  /** Thinking, mode and features live in the model control's sheet. */
+  foldControls: boolean;
+  showModelLabel: boolean;
 }
 
-export const COMPOSER_TOOLBAR_GEOMETRY = {
-  controlSize: 28,
-  controlGap: 4,
-  iconLabelGap: 4,
-  labelPadding: 8,
-  caretSize: 14,
-} as const;
+/** What each toolbar control takes up in the row, which is what the density budget sums. */
+export interface ComposerToolbarGeometry {
+  /** An icon-only control's width in the row. */
+  controlSize: number;
+  glyphs: ToolbarGlyphs;
+  controlGap: number;
+  iconLabelGap: number;
+  /** A labelled control's padding on each side. */
+  labelPadding: number;
+  caretSize: number;
+}
+
+/** The toolbar's measurements under a control sizing; see `resolveControlSizing`. */
+export function composerToolbarGeometry(sizing: ControlSizing): ComposerToolbarGeometry {
+  return {
+    controlSize: TOOLBAR_DISC_SIZES[sizing],
+    glyphs: toolbarGlyphsFor(sizing),
+    controlGap: TOOLBAR_CONTROL_GAPS[sizing],
+    iconLabelGap: 4,
+    labelPadding: TOOLBAR_LABEL_PADDING,
+    caretSize: 14,
+  };
+}
 
 const DENSITY_HYSTERESIS = 12;
+/** The model label's narrowest useful width: enough for the model family, such as "GPT-6…". */
+const MODEL_FAMILY_LABEL_WIDTH = 56;
 
 function normalizedFontScale(fontScale: number): number {
   return Number.isFinite(fontScale) ? Math.max(1, fontScale) : 1;
 }
 
-function sumControlWidths(widths: number[]): number {
+function sumControlWidths(widths: number[], geometry: ComposerToolbarGeometry): number {
   if (widths.length === 0) return 0;
   return (
-    widths.reduce((total, width) => total + width, 0) +
-    (widths.length - 1) * COMPOSER_TOOLBAR_GEOMETRY.controlGap
+    widths.reduce((total, width) => total + width, 0) + (widths.length - 1) * geometry.controlGap
   );
 }
 
@@ -43,92 +90,208 @@ function estimateLabelWidth(label: string, fontScale: number): number {
   return Array.from(label).length * 7 * fontScale;
 }
 
+/** A labelled control's fixed chrome: its padding, its glyph, and the gap to its label. */
+function labelledChrome(geometry: ComposerToolbarGeometry): number {
+  return geometry.labelPadding * 2 + geometry.glyphs.label.size + geometry.iconLabelGap;
+}
+
 function resolveFeatureControlWidth(
   feature: ComposerFeatureControlPresence,
   fontScale: number,
+  geometry: ComposerToolbarGeometry,
 ): number {
-  if (feature.type === "toggle") return COMPOSER_TOOLBAR_GEOMETRY.controlSize;
+  if (feature.type === "toggle" || feature.label === null) return geometry.controlSize;
   return (
-    COMPOSER_TOOLBAR_GEOMETRY.controlSize +
-    COMPOSER_TOOLBAR_GEOMETRY.iconLabelGap +
-    COMPOSER_TOOLBAR_GEOMETRY.labelPadding * 2 +
+    geometry.controlSize +
+    geometry.iconLabelGap +
+    geometry.labelPadding * 2 +
     estimateLabelWidth(feature.label, fontScale)
   );
 }
 
-function resolveCondensedFloor(controls: ComposerControlPresence): number {
+function resolveCondensedFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
   const fontScale = normalizedFontScale(controls.fontScale);
+  const chrome = labelledChrome(geometry);
   const widths: number[] = [];
-  if (controls.hasModel) widths.push(36 + 60 * fontScale);
-  if (controls.hasThinking) widths.push(COMPOSER_TOOLBAR_GEOMETRY.controlSize);
-  if (controls.hasMode) widths.push(36 + 96 * fontScale);
-  if (controls.features.length > 0) widths.push(COMPOSER_TOOLBAR_GEOMETRY.controlSize);
-  return sumControlWidths(widths);
-}
-
-function resolveFullFloor(controls: ComposerControlPresence): number {
-  const fontScale = normalizedFontScale(controls.fontScale);
-  const widths: number[] = [];
-  if (controls.hasModel) widths.push(50 + 70 * fontScale);
-  if (controls.hasThinking) widths.push(54 + 48 * fontScale);
-  if (controls.hasMode) widths.push(54 + 96 * fontScale);
-  for (const feature of controls.features) {
-    widths.push(resolveFeatureControlWidth(feature, fontScale));
+  if (controls.hasModel) widths.push(chrome + 60 * fontScale);
+  if (controls.hasThinking) widths.push(geometry.controlSize);
+  if (controls.hasMode) widths.push(chrome + 96 * fontScale);
+  if (controls.features.length > 0 || controls.pluginItemsWidth > 0) {
+    widths.push(geometry.controlSize);
   }
-  return sumControlWidths(widths);
+  return sumControlWidths(widths, geometry);
 }
 
+function resolveFullFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  const fontScale = normalizedFontScale(controls.fontScale);
+  const chrome = labelledChrome(geometry);
+  const caret = geometry.caretSize;
+  const widths: number[] = [];
+  if (controls.hasModel) widths.push(chrome + caret + 70 * fontScale);
+  if (controls.hasThinking) widths.push(chrome + geometry.iconLabelGap + caret + 48 * fontScale);
+  if (controls.hasMode) widths.push(chrome + geometry.iconLabelGap + caret + 96 * fontScale);
+  for (const feature of controls.features) {
+    widths.push(resolveFeatureControlWidth(feature, fontScale, geometry));
+  }
+  if (controls.pluginItemsWidth > 0) widths.push(controls.pluginItemsWidth);
+  return sumControlWidths(widths, geometry);
+}
+
+/** Model at its family label, with thinking, mode and features as icon-only squares. */
+function resolveTightFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  const fontScale = normalizedFontScale(controls.fontScale);
+  const widths: number[] = [];
+  if (controls.hasModel) {
+    widths.push(labelledChrome(geometry) + MODEL_FAMILY_LABEL_WIDTH * fontScale);
+  }
+  if (controls.hasThinking) widths.push(geometry.controlSize);
+  if (controls.hasMode) widths.push(geometry.controlSize);
+  if (controls.features.length > 0 || controls.pluginItemsWidth > 0) {
+    widths.push(geometry.controlSize);
+  }
+  return sumControlWidths(widths, geometry);
+}
+
+/**
+ * One model control carrying the model family label. Its thinking label is not budgeted: it is
+ * the first label to go when the control runs out of room; see `resolveModelTriggerLabels`.
+ */
+function resolveCompactFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  const fontScale = normalizedFontScale(controls.fontScale);
+  return labelledChrome(geometry) + MODEL_FAMILY_LABEL_WIDTH * fontScale;
+}
+
+function resolveDensityFloor(
+  density: ComposerControlDensity,
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  switch (density) {
+    case "full":
+      return resolveFullFloor(controls, geometry);
+    case "condensed":
+      return resolveCondensedFloor(controls, geometry);
+    case "tight":
+      return resolveTightFloor(controls, geometry);
+    case "compact":
+      return resolveCompactFloor(controls, geometry);
+    case "iconOnly":
+      return 0;
+  }
+}
+
+/**
+ * The widest density whose floor fits `availableWidth`. Widening past the current density needs
+ * the floor plus the hysteresis and keeping it tolerates the floor minus it, so a width near a
+ * floor does not flip back and forth. `minimumDensity` is the widest density allowed.
+ */
 export function resolveComposerControlDensity(input: {
   availableWidth: number;
   currentDensity: ComposerControlDensity;
   controls: ComposerControlPresence;
+  geometry: ComposerToolbarGeometry;
+  minimumDensity?: ComposerControlDensity;
 }): ComposerControlDensity {
-  const fullFloor = resolveFullFloor(input.controls);
-  const condensedFloor = resolveCondensedFloor(input.controls);
-
-  if (input.currentDensity === "full") {
-    if (input.availableWidth >= fullFloor - DENSITY_HYSTERESIS) return "full";
-    return input.availableWidth >= condensedFloor ? "condensed" : "tight";
+  const current = DENSITY_LADDER.indexOf(input.currentDensity);
+  const first = DENSITY_LADDER.indexOf(input.minimumDensity ?? "full");
+  for (let step = first; step < DENSITY_LADDER.length; step += 1) {
+    const density = DENSITY_LADDER[step];
+    const floor = resolveDensityFloor(density, input.controls, input.geometry);
+    let required = floor;
+    if (step < current) required = floor + DENSITY_HYSTERESIS;
+    if (step === current) required = floor - DENSITY_HYSTERESIS;
+    if (input.availableWidth >= required) return density;
   }
-
-  if (input.currentDensity === "condensed") {
-    if (input.availableWidth >= fullFloor + DENSITY_HYSTERESIS) return "full";
-    if (input.availableWidth < condensedFloor - DENSITY_HYSTERESIS) return "tight";
-    return "condensed";
-  }
-
-  if (input.availableWidth >= fullFloor + DENSITY_HYSTERESIS) return "full";
-  if (input.availableWidth >= condensedFloor + DENSITY_HYSTERESIS) return "condensed";
-  return "tight";
+  return "iconOnly";
 }
 
-export function resolveComposerControlPresentation(
-  density: ComposerControlDensity,
-): ComposerControlPresentation {
-  if (density === "full") {
-    return {
-      showCarets: true,
-      showThinkingLabel: true,
-      showModeLabel: true,
-      aggregateFeatures: false,
-    };
-  }
-  if (density === "condensed") {
-    return {
-      showCarets: false,
-      showThinkingLabel: false,
-      showModeLabel: true,
-      aggregateFeatures: true,
-    };
-  }
-  return {
+const PRESENTATIONS: Record<ComposerControlDensity, ComposerControlPresentation> = {
+  full: {
+    showCarets: true,
+    showThinkingLabel: true,
+    showModeLabel: true,
+    aggregateFeatures: false,
+    foldControls: false,
+    showModelLabel: true,
+  },
+  condensed: {
+    showCarets: false,
+    showThinkingLabel: false,
+    showModeLabel: true,
+    aggregateFeatures: true,
+    foldControls: false,
+    showModelLabel: true,
+  },
+  tight: {
     showCarets: false,
     showThinkingLabel: false,
     showModeLabel: false,
     aggregateFeatures: true,
-  };
+    foldControls: false,
+    showModelLabel: true,
+  },
+  compact: {
+    showCarets: false,
+    showThinkingLabel: true,
+    showModeLabel: false,
+    aggregateFeatures: true,
+    foldControls: true,
+    showModelLabel: true,
+  },
+  iconOnly: {
+    showCarets: false,
+    showThinkingLabel: false,
+    showModeLabel: false,
+    aggregateFeatures: true,
+    foldControls: true,
+    showModelLabel: false,
+  },
+};
+
+export function resolveComposerControlPresentation(
+  density: ComposerControlDensity,
+): ComposerControlPresentation {
+  return PRESENTATIONS[density];
 }
 
-export function resolveComposerToolbarGlyphSize(platform: "web" | "native"): number {
-  return platform === "native" ? 20 : 16;
+/**
+ * Which labels the folded model control shows. `measuring` until every width is known, so the
+ * control never paints a choice made without them.
+ */
+export type ModelTriggerLabels = "measuring" | "modelAndThinking" | "model";
+
+/** Widths measured from the rendered model control, in points. */
+export interface ModelTriggerMeasurements {
+  /** The width the control may take. */
+  availableWidth: number;
+  /** The control with its model and thinking labels side by side, untruncated. */
+  fullWidth: number;
+}
+
+/**
+ * The thinking label goes first: it shows only while the model label fits beside it in full, so
+ * the model label truncates only once the thinking label is gone. The web reports layout widths
+ * rounded to whole pixels, so equal widths can hide a fraction of a pixel of overflow; only a
+ * full width strictly below the available width is known to fit.
+ */
+export function resolveModelTriggerLabels(input: {
+  hasThinking: boolean;
+  measurements: Partial<ModelTriggerMeasurements>;
+}): ModelTriggerLabels {
+  if (!input.hasThinking) return "model";
+  const { availableWidth, fullWidth } = input.measurements;
+  if (availableWidth === undefined || fullWidth === undefined) return "measuring";
+  return fullWidth < availableWidth ? "modelAndThinking" : "model";
 }
diff --git a/packages/app/src/composer/agent-controls/mode-control.tsx b/packages/app/src/composer/agent-controls/mode-control.tsx
index 59fb515ce5..ce6b6d000a 100644
--- a/packages/app/src/composer/agent-controls/mode-control.tsx
+++ b/packages/app/src/composer/agent-controls/mode-control.tsx
@@ -1,7 +1,7 @@
 import { useCallback, useMemo, useRef, useState, type ReactElement } from "react";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet } from "react-native-unistyles";
 import { useShallow } from "zustand/shallow";
 import { useStoreWithEqualityFn } from "zustand/traditional";
 import { type SheetHeader } from "@/components/adaptive-modal-sheet";
@@ -27,6 +27,7 @@ import { showProviderNoticeToast } from "@/utils/provider-notice-toast";
 import type { AgentMode } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import { getAgentModeIcon, getAgentModeOptionIcon } from "@/agent-controls/icons";
+import { DensityIcon } from "@/components/ui/density-icon";
 interface ModeComboboxOptionProps {
   option: ComboboxOption;
   selected: boolean;
@@ -34,7 +35,6 @@ interface ModeComboboxOptionProps {
   onPress: () => void;
   provider: string;
   providerDefinitions: AgentProviderDefinition[];
-  iconColor: string;
 }
 
 function ModeComboboxOption({
@@ -44,12 +44,12 @@ function ModeComboboxOption({
   onPress,
   provider,
   providerDefinitions,
-  iconColor,
 }: ModeComboboxOptionProps) {
   const IconComponent = getAgentModeOptionIcon(provider, option.id, providerDefinitions);
   const leadingSlot = useMemo(
-    () => (IconComponent ? <IconComponent size={16} color={iconColor} /> : null),
-    [IconComponent, iconColor],
+    () =>
+      IconComponent ? <DensityIcon icon={IconComponent} size="md" color="foreground" /> : null,
+    [IconComponent],
   );
   return (
     <ComboboxItem
@@ -85,7 +85,6 @@ export function AgentModeControl({
   surface = "toolbar",
   onClose,
 }: AgentModeControlValue & { surface?: "toolbar" | "sheet"; onClose?: () => void }) {
-  const { theme } = useUnistyles();
   const { presentation } = useComposerControlLayout();
   const { t } = useTranslation();
   const { isActiveComposer } = useComposerKeyboardScope();
@@ -102,7 +101,6 @@ export function AgentModeControl({
   }, [modeOptions, selectedModeId]);
 
   const Icon = getAgentModeIcon(provider, selectedMode?.id ?? "", providerDefinitions);
-  const iconColor = theme.colors.foregroundMuted;
   const selectedModeLabel = selectedMode ? formatAgentModeLabel(selectedMode) : "";
 
   const allOptions = useMemo<ComboboxOption[]>(
@@ -171,10 +169,9 @@ export function AgentModeControl({
         onPress={args.onPress}
         provider={provider}
         providerDefinitions={providerDefinitions}
-        iconColor={theme.colors.foreground}
       />
     ),
-    [provider, providerDefinitions, theme.colors.foreground],
+    [provider, providerDefinitions],
   );
 
   const sheetHeader = useMemo<SheetHeader>(
@@ -198,7 +195,6 @@ export function AgentModeControl({
           <AgentControlTrigger
             ref={anchorRef}
             icon={Icon}
-            iconColor={iconColor}
             surface={surface}
             label={t("agentControls.mode.title")}
             value={selectedModeLabel}
diff --git a/packages/app/src/composer/agent-controls/mode.test.ts b/packages/app/src/composer/agent-controls/mode.test.ts
index 0905e3cd4c..8eca9b9251 100644
--- a/packages/app/src/composer/agent-controls/mode.test.ts
+++ b/packages/app/src/composer/agent-controls/mode.test.ts
@@ -25,15 +25,19 @@ describe("resolveAgentControlsMode", () => {
         onSelectMode: () => undefined,
         models: [],
         selectedModel: "",
-        onSelectModel: () => undefined,
+        onSelectModel: () => true,
         isModelLoading: false,
         modelSelectorProviders: [],
         isAllModelsLoading: false,
-        onSelectProviderAndModel: () => undefined,
+        onSelectProviderAndModel: () => true,
+        options: {},
+        onSetOption: () => undefined,
         thinkingOptions: [],
         selectedThinkingOptionId: "",
         onSelectThinkingOption: () => undefined,
         onApplyAgentProfile: () => undefined,
+        metadata: {},
+        onSetMetadata: () => undefined,
       }),
     ).toBe("draft");
   });
diff --git a/packages/app/src/composer/agent-controls/model-sheet.tsx b/packages/app/src/composer/agent-controls/model-sheet.tsx
index 6929b447ea..c9da7d778e 100644
--- a/packages/app/src/composer/agent-controls/model-sheet.tsx
+++ b/packages/app/src/composer/agent-controls/model-sheet.tsx
@@ -1,20 +1,36 @@
 import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import { Keyboard, ScrollView, Text, View, type PressableStateCallbackType } from "react-native";
+import {
+  Keyboard,
+  ScrollView,
+  Text,
+  View,
+  type LayoutChangeEvent,
+  type PressableStateCallbackType,
+} from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
 import type { AgentProfilePicker, AgentProfileSeed } from "@/agent-profiles";
 import { AdaptiveModalSheet } from "@/components/adaptive-modal-sheet";
+import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
 import { ComboboxTrigger } from "@/components/ui/combobox-trigger";
+import { TailEllipsisText } from "@/components/ui/tail-ellipsis-text";
 import { useProviderIcon } from "@/components/provider-icons";
 import { ModelBrowser, useModelBrowser } from "@/components/model-browser";
 import { resolveModelBrowserScrolling } from "@/components/model-browser-view";
 import { AgentControlTrigger } from "@/composer/agent-controls/control";
 import { ComposerToolbarGlyph } from "@/composer/agent-controls/glyph";
+import { resolveModelTriggerLabels } from "@/composer/agent-controls/layout";
 import { resolveModelSheetOpening } from "@/composer/agent-controls/model-sheet-flow";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
+import { readMeasuredWidth } from "@/hooks/use-container-width";
+import {
+  toolbarContentSlot,
+  toolbarSlot,
+  type ToolbarGlyphs,
+} from "@/components/ui/control-geometry";
 
 const SNAP_POINTS = ["80%", "90%"];
 const MODEL_LIST_TOP_INSET = 4;
@@ -41,8 +57,12 @@ interface CompactModelSheetProps {
   isRetryingProvider?: boolean;
   disabled?: boolean;
   serverId?: string | null;
-  glyphSize: number;
+  glyphs: ToolbarGlyphs;
+  /** False when the toolbar is too narrow for labels: the trigger shows the provider glyph only. */
+  showLabels: boolean;
   canSwitchProvider: boolean;
+  /** Carries the composer's contexts into the sheets, which draw away from it. */
+  contextBridge?: ContextBridge | null;
   children: ReactNode;
 }
 
@@ -75,6 +95,43 @@ function resolveModelSheetProfileActions(
   };
 }
 
+/**
+ * Measures the folded model control and decides which labels it shows; see
+ * `resolveModelTriggerLabels`. The full width is keyed by what was measured, so a new label is
+ * `measuring` until its own width is known instead of reusing the previous label's.
+ */
+function useModelTriggerLabels(input: {
+  modelLabel: string;
+  thinkingLabel: string | null;
+  glyphSize: number;
+}) {
+  const { modelLabel, thinkingLabel, glyphSize } = input;
+  const measuredKey = `${glyphSize}\n${modelLabel}\n${thinkingLabel ?? ""}`;
+  const [availableWidth, setAvailableWidth] = useState<number | undefined>(undefined);
+  const [fullWidth, setFullWidth] = useState<{ key: string; width: number } | null>(null);
+
+  const onFrameLayout = useCallback((event: LayoutChangeEvent) => {
+    const width = readMeasuredWidth(event);
+    if (width !== null) setAvailableWidth(width);
+  }, []);
+  const onFullLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const width = readMeasuredWidth(event);
+      if (width !== null) setFullWidth({ key: measuredKey, width });
+    },
+    [measuredKey],
+  );
+
+  const labels = resolveModelTriggerLabels({
+    hasThinking: thinkingLabel !== null,
+    measurements: {
+      availableWidth,
+      fullWidth: fullWidth?.key === measuredKey ? fullWidth.width : undefined,
+    },
+  });
+  return { labels, measuredKey, onFrameLayout, onFullLayout };
+}
+
 export function CompactModelSheet({
   providers,
   selectedProvider,
@@ -93,8 +150,10 @@ export function CompactModelSheet({
   isRetryingProvider = false,
   disabled = false,
   serverId = null,
-  glyphSize,
+  glyphs,
+  showLabels,
   canSwitchProvider,
+  contextBridge = null,
   children,
 }: CompactModelSheetProps) {
   const { t } = useTranslation();
@@ -229,15 +288,6 @@ export function CompactModelSheet({
     open();
   }, [close, isOpen, open]);
 
-  const triggerStyle = useCallback(
-    ({ hovered, pressed }: PressableStateCallbackType) => [
-      styles.trigger,
-      hovered && styles.triggerHovered,
-      (pressed || isOpen) && styles.triggerPressed,
-      disabled && styles.triggerDisabled,
-    ],
-    [disabled, isOpen],
-  );
   const mobileRootContent = useMemo(
     () => (
       <View style={styles.mobileRootContent} testID="agent-controls-settings-list">
@@ -263,34 +313,19 @@ export function CompactModelSheet({
 
   return (
     <>
-      <ComboboxTrigger
-        collapsable={false}
+      <ModelSheetTrigger
+        ModelIcon={hasSelectedProvider ? ModelIcon : null}
+        modelLabel={shortModelLabel(rootBrowser.triggerLabel)}
+        thinkingLabel={thinkingLabel}
+        glyphs={glyphs}
+        iconOnly={!showLabels && hasSelectedProvider}
+        isOpen={isOpen}
         disabled={disabled}
         onPress={toggle}
-        style={triggerStyle}
-        accessibilityRole="button"
         accessibilityLabel={t("modelSelector.selectedModel", {
           model: rootBrowser.selectedModelLabel,
         })}
-        testID="combined-model-selector"
-        chevron={null}
-      >
-        {hasSelectedProvider ? (
-          <ComposerToolbarGlyph size={glyphSize}>
-            <ModelIcon size={glyphSize} color={styles.providerIcon.color} />
-          </ComposerToolbarGlyph>
-        ) : null}
-        <View style={styles.triggerLabels}>
-          <Text style={styles.triggerText} numberOfLines={1}>
-            {shortModelLabel(rootBrowser.triggerLabel)}
-          </Text>
-          {thinkingLabel ? (
-            <Text style={styles.triggerThinking} numberOfLines={1}>
-              {thinkingLabel}
-            </Text>
-          ) : null}
-        </View>
-      </ComboboxTrigger>
+      />
 
       <AdaptiveModalSheet
         header={rootHeader}
@@ -299,6 +334,7 @@ export function CompactModelSheet({
         snapPoints={SNAP_POINTS}
         scrollable={false}
         contentStyle={styles.sheetBody}
+        contextBridge={contextBridge}
         testID="agent-controls-model-sheet"
       >
         <View
@@ -347,6 +383,7 @@ export function CompactModelSheet({
           scrollable={false}
           presentation="push"
           contentStyle={styles.sheetBody}
+          contextBridge={contextBridge}
           testID="agent-controls-model-browser-sheet"
         >
           <View
@@ -372,23 +409,146 @@ export function CompactModelSheet({
   );
 }
 
+/**
+ * The folded model control in the toolbar: the provider glyph, then the model and thinking
+ * labels for as long as they fit.
+ */
+function ModelSheetTrigger({
+  ModelIcon,
+  modelLabel,
+  thinkingLabel,
+  glyphs,
+  iconOnly,
+  isOpen,
+  disabled,
+  onPress,
+  accessibilityLabel,
+}: {
+  /** The selected provider's glyph, or null before a provider is selected. */
+  ModelIcon: ReturnType<typeof useProviderIcon> | null;
+  modelLabel: string;
+  thinkingLabel: string | null;
+  glyphs: ToolbarGlyphs;
+  iconOnly: boolean;
+  isOpen: boolean;
+  disabled: boolean;
+  onPress: () => void;
+  accessibilityLabel: string;
+}) {
+  const glyphRole = iconOnly ? "icon" : "label";
+  const glyph = glyphs[glyphRole];
+  const triggerLabels = useModelTriggerLabels({
+    modelLabel,
+    thinkingLabel: iconOnly ? null : thinkingLabel,
+    glyphSize: glyph.size,
+  });
+  const providerIconColor =
+    glyph.tone === "foreground" ? styles.providerIconForeground.color : styles.providerIcon.color;
+  const triggerStyle = useCallback(
+    ({ hovered, pressed }: PressableStateCallbackType) => [
+      styles.trigger,
+      iconOnly && styles.triggerIconOnly,
+      hovered && styles.triggerHovered,
+      (pressed || isOpen) && styles.triggerPressed,
+      disabled && styles.triggerDisabled,
+    ],
+    [disabled, iconOnly, isOpen],
+  );
+
+  return (
+    <View style={styles.triggerFrame} onLayout={triggerLabels.onFrameLayout}>
+      <ComboboxTrigger
+        collapsable={false}
+        disabled={disabled}
+        onPress={onPress}
+        style={triggerStyle}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+        testID="combined-model-selector"
+        chevron={null}
+      >
+        {ModelIcon ? (
+          <ComposerToolbarGlyph role={glyphRole}>
+            <ModelIcon
+              size={glyph.size}
+              strokeWidth={glyph.strokeWidth}
+              color={providerIconColor}
+            />
+          </ComposerToolbarGlyph>
+        ) : null}
+        {!iconOnly ? (
+          <View
+            style={[
+              styles.triggerLabels,
+              triggerLabels.labels === "measuring" && styles.triggerLabelsMeasuring,
+            ]}
+          >
+            <TailEllipsisText
+              text={modelLabel}
+              style={styles.triggerText}
+              testID="combined-model-selector-model-label"
+            />
+            {thinkingLabel && triggerLabels.labels !== "model" ? (
+              <Text
+                style={styles.triggerThinking}
+                numberOfLines={1}
+                testID="combined-model-selector-thinking-label"
+              >
+                {thinkingLabel}
+              </Text>
+            ) : null}
+          </View>
+        ) : null}
+      </ComboboxTrigger>
+      {!iconOnly && thinkingLabel ? (
+        <View
+          // Keyed by what it measures: a retained node whose size does not change emits no new
+          // layout event, so new labels would never be measured.
+          key={triggerLabels.measuredKey}
+          style={[styles.trigger, styles.triggerMeasurer]}
+          onLayout={triggerLabels.onFullLayout}
+          pointerEvents="none"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+          aria-hidden
+        >
+          {ModelIcon ? <ComposerToolbarGlyph role={glyphRole}>{null}</ComposerToolbarGlyph> : null}
+          <View style={styles.triggerLabels}>
+            <Text style={[styles.triggerText, styles.triggerMeasuredText]} numberOfLines={1}>
+              {modelLabel}
+            </Text>
+            <Text style={styles.triggerThinking} numberOfLines={1}>
+              {thinkingLabel}
+            </Text>
+          </View>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
 const styles = StyleSheet.create((theme) => ({
   trigger: {
-    height: 28,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
     alignItems: "center",
     gap: theme.spacing[1],
-    paddingHorizontal: theme.spacing[2],
-    borderRadius: theme.borderRadius["2xl"],
+    ...toolbarContentSlot(),
+    borderRadius: theme.borderRadius.full,
     backgroundColor: "transparent",
   },
+  triggerIconOnly: {
+    ...toolbarSlot(),
+    flexShrink: 0,
+    paddingHorizontal: 0,
+    justifyContent: "center",
+  },
   triggerHovered: {
     backgroundColor: theme.colors.surface2,
   },
   triggerPressed: {
-    backgroundColor: theme.colors.surface0,
+    backgroundColor: theme.colors.surface2,
   },
   triggerDisabled: {
     opacity: 0.5,
@@ -407,6 +567,28 @@ const styles = StyleSheet.create((theme) => ({
     alignItems: "center",
     gap: theme.spacing[1],
   },
+  triggerLabelsMeasuring: {
+    opacity: 0,
+  },
+  /** The space the trigger may take; the trigger itself stays as wide as its content. */
+  triggerFrame: {
+    minWidth: 0,
+    flexGrow: 1,
+    flexShrink: 1,
+    flexDirection: "row",
+    alignItems: "center",
+  },
+  /** An invisible copy of the trigger with both labels untruncated. */
+  triggerMeasurer: {
+    position: "absolute",
+    left: 0,
+    top: 0,
+    flexShrink: 0,
+    opacity: 0,
+  },
+  triggerMeasuredText: {
+    flexShrink: 0,
+  },
   triggerThinking: {
     flexShrink: 0,
     color: theme.colors.foregroundExtraMuted,
@@ -416,6 +598,9 @@ const styles = StyleSheet.create((theme) => ({
   providerIcon: {
     color: theme.colors.foregroundMuted,
   },
+  providerIconForeground: {
+    color: theme.colors.foreground,
+  },
   sheetBody: {
     paddingHorizontal: 0,
     paddingTop: 0,
diff --git a/packages/app/src/composer/agent-controls/plugin-toolbar-slot.tsx b/packages/app/src/composer/agent-controls/plugin-toolbar-slot.tsx
new file mode 100644
index 0000000000..f31561b6ac
--- /dev/null
+++ b/packages/app/src/composer/agent-controls/plugin-toolbar-slot.tsx
@@ -0,0 +1,82 @@
+import { useCallback, useState } from "react";
+import { type LayoutChangeEvent, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { RetainedPanelActivity } from "@/components/retained-panel";
+import { TOOLBAR_CONTROL_GAP } from "@/components/ui/control-geometry";
+import { isWeb } from "@/constants/platform";
+import { PluginComposerItems } from "@/plugins/composer-items";
+
+/** A retained tab under `display: none` reports 0 by 0; see `styles.slot` for why 0 wide is real. */
+function readSlotWidth(event: LayoutChangeEvent): number | null {
+  const { width, height } = event.nativeEvent.layout;
+  return height > 0 ? width : null;
+}
+
+/** What the plugin items take up in the toolbar row, in points, as `PluginToolbarSlot` reports it. */
+export function usePluginToolbarWidth(): {
+  width: number;
+  onLayout: (event: LayoutChangeEvent) => void;
+} {
+  const [width, setWidth] = useState(0);
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const next = readSlotWidth(event);
+    if (next !== null) setWidth(next);
+  }, []);
+  return { width, onLayout };
+}
+
+/**
+ * The plugin items in their toolbar form, measured whether or not the toolbar shows them. An item
+ * is an arbitrary component, so its width is known only from rendering it, and it is always the
+ * toolbar form that is measured: the width never depends on the density it decides, so moving the
+ * items to the overflow sheet cannot change the answer. Out of the row, the same node stays
+ * mounted and measured, unseen and out of reach, and inactive so an open picker closes with it.
+ */
+export function PluginToolbarSlot({
+  serverId,
+  width,
+  fits,
+  onLayout,
+}: {
+  serverId: string | null;
+  width: number;
+  /** Whether the toolbar has room for the items at the width they measured. */
+  fits: boolean;
+  onLayout: (event: LayoutChangeEvent) => void;
+}) {
+  // An empty slot stays out of the row, or the row's gap would reserve room for nothing.
+  const inline = fits && width > 0;
+  return (
+    <View
+      style={[styles.slot, !inline && styles.measuring]}
+      onLayout={onLayout}
+      testID="plugin-toolbar-items"
+      accessibilityElementsHidden={!inline}
+      importantForAccessibility={inline ? "auto" : "no-hide-descendants"}
+      aria-hidden={!inline}
+    >
+      <RetainedPanelActivity active={inline}>
+        <PluginComposerItems serverId={serverId} surface="toolbar" />
+      </RetainedPanelActivity>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  slot: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexShrink: 0,
+    gap: TOOLBAR_CONTROL_GAP,
+    // Keeps a slot whose items render nothing distinguishable from one that is not rendered.
+    minHeight: 1,
+  },
+  measuring: {
+    position: "absolute",
+    left: 0,
+    top: 0,
+    opacity: 0,
+    pointerEvents: "none",
+    ...(isWeb ? ({ visibility: "hidden" } as const) : null),
+  },
+});
diff --git a/packages/app/src/composer/agent-controls/sheet-bridge.tsx b/packages/app/src/composer/agent-controls/sheet-bridge.tsx
new file mode 100644
index 0000000000..a46fdaec4e
--- /dev/null
+++ b/packages/app/src/composer/agent-controls/sheet-bridge.tsx
@@ -0,0 +1,47 @@
+import { useCallback } from "react";
+import { QueryClientProvider, useQueryClient } from "@tanstack/react-query";
+import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
+import { ComposerControlLayoutProvider, useComposerControlLayout } from "./layout-context";
+import {
+  ComposerAgentProvider,
+  ComposerInputProvider,
+  useComposerAgent,
+  useComposerInput,
+} from "@/composer/session";
+import { ComposerModelProvider, useComposerModel } from "@/composer/model";
+import { ToastApiProvider, useToast } from "@/contexts/toast-api-context";
+
+/**
+ * A phone's overflow draws in a sheet whose content lands at the app root, away from the
+ * composer. This carries across what a control in it reads from the composer: the agent, model and input
+ * a plugin's `useComposer()` sits on, the layout, and the toast and query client the controls use.
+ * Call it from inside the composer, outside any sheet.
+ */
+export function useComposerSheetBridge(): ContextBridge {
+  const layout = useComposerControlLayout();
+  const agent = useComposerAgent();
+  const input = useComposerInput();
+  const model = useComposerModel();
+  const toast = useToast();
+  const queryClient = useQueryClient();
+  return useCallback<ContextBridge>(
+    (content) => (
+      <QueryClientProvider client={queryClient}>
+        <ToastApiProvider api={toast}>
+          <ComposerControlLayoutProvider value={layout}>
+            <ComposerAgentProvider value={agent}>
+              <ComposerModelProvider value={model}>
+                {input ? (
+                  <ComposerInputProvider value={input}>{content}</ComposerInputProvider>
+                ) : (
+                  content
+                )}
+              </ComposerModelProvider>
+            </ComposerAgentProvider>
+          </ComposerControlLayoutProvider>
+        </ToastApiProvider>
+      </QueryClientProvider>
+    ),
+    [agent, input, layout, model, queryClient, toast],
+  );
+}
diff --git a/packages/app/src/composer/agent-controls/utils.test.ts b/packages/app/src/composer/agent-controls/utils.test.ts
index dfacec0ec7..ad8f6da983 100644
--- a/packages/app/src/composer/agent-controls/utils.test.ts
+++ b/packages/app/src/composer/agent-controls/utils.test.ts
@@ -1,9 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   getFeatureHighlightColor,
-  getFeatureTooltip,
   getAgentControlHintKey,
-  isFeatureActive,
   normalizeModelId,
   resolveAgentModelSelection,
 } from "./utils";
@@ -17,51 +15,12 @@ describe("getAgentControlHintKey", () => {
 });
 
 describe("feature metadata helpers", () => {
-  it("prefers explicit feature tooltip copy", () => {
-    expect(
-      getFeatureTooltip({
-        label: "Plan",
-        tooltip: "Toggle plan mode",
-      }),
-    ).toBe("Toggle plan mode");
-  });
-
-  it("falls back to the feature label when no tooltip is provided", () => {
-    expect(
-      getFeatureTooltip({
-        label: "Custom",
-      }),
-    ).toBe("Custom");
-  });
-
   it("maps feature highlight colors by feature id", () => {
     expect(getFeatureHighlightColor("fast_mode")).toBe("yellow");
     expect(getFeatureHighlightColor("service_tier")).toBe("yellow");
     expect(getFeatureHighlightColor("plan_mode")).toBe("blue");
     expect(getFeatureHighlightColor("other")).toBe("default");
   });
-
-  it("treats a select feature as active when a non-default option is selected", () => {
-    const speed = {
-      type: "select" as const,
-      id: "service_tier",
-      label: "Speed",
-      options: [
-        { id: "default", label: "Normal", isDefault: true },
-        { id: "fast", label: "Fast" },
-      ],
-    };
-    expect(isFeatureActive({ ...speed, value: "default" })).toBe(false);
-    expect(isFeatureActive({ ...speed, value: "fast" })).toBe(true);
-    expect(
-      isFeatureActive({
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast",
-        value: true,
-      }),
-    ).toBe(true);
-  });
 });
 
 describe("normalizeModelId", () => {
diff --git a/packages/app/src/composer/agent-controls/utils.ts b/packages/app/src/composer/agent-controls/utils.ts
index c0b1da7c47..26a5cabe5b 100644
--- a/packages/app/src/composer/agent-controls/utils.ts
+++ b/packages/app/src/composer/agent-controls/utils.ts
@@ -1,4 +1,4 @@
-import type { AgentFeature, AgentModelDefinition } from "@getpaseo/protocol/agent-types";
+import type { AgentModelDefinition, ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
 import { i18n } from "@/i18n/i18next";
 import { formatThinkingOptionLabel } from "@/agent-controls/labels";
 import {
@@ -35,16 +35,6 @@ export function normalizeModelId(modelId: string | null | undefined): string | n
   return normalized;
 }
 
-export function getFeatureTooltip(feature: Pick<AgentFeature, "label" | "tooltip">): string {
-  return feature.tooltip ?? feature.label;
-}
-
-export function isFeatureActive(feature: AgentFeature): boolean {
-  if (feature.type === "toggle") return feature.value;
-  const selectedOption = feature.options.find((option) => option.id === feature.value);
-  return selectedOption !== undefined && !selectedOption.isDefault;
-}
-
 export function getFeatureHighlightColor(featureId: string): FeatureHighlightColor {
   switch (featureId) {
     case FAST_MODE_FEATURE_ID:
@@ -59,6 +49,14 @@ export function getFeatureHighlightColor(featureId: string): FeatureHighlightCol
   }
 }
 
+export function resolveProviderSnapshotEntry(
+  entries: readonly ProviderSnapshotEntry[] | null | undefined,
+  provider: string | null | undefined,
+): ProviderSnapshotEntry | null {
+  if (!entries || !provider) return null;
+  return entries.find((entry) => entry.provider === provider) ?? null;
+}
+
 function findModelById(
   models: AgentModelDefinition[] | null,
   modelId: string | null,
diff --git a/packages/app/src/composer/dock/index.native.tsx b/packages/app/src/composer/dock/index.native.tsx
index 4b6407c872..ab26fe5612 100644
--- a/packages/app/src/composer/dock/index.native.tsx
+++ b/packages/app/src/composer/dock/index.native.tsx
@@ -19,15 +19,18 @@ import Animated, {
 import { useKeyboardShift } from "@/keyboard/shift";
 import {
   resolveCenteredClearance,
+  resolveComposerBottomPlacement,
   resolveComposerSlotCapacity,
   updateComposerCapacity,
   type ComposerCapacity,
 } from "./internal/capacity";
+import { SPACING } from "@/styles/theme";
 
 const ViewportSizing = createContext<SharedValue<ComposerCapacity | undefined> | null>(null);
 
 interface ComposerViewportProps extends ViewProps {
   bottomInset?: number;
+  keyboardGap?: number;
   centered?: boolean;
 }
 
@@ -36,6 +39,7 @@ function ComposerViewport({
   children,
   onLayout,
   bottomInset = 0,
+  keyboardGap = 0,
   centered = false,
   ...props
 }: ComposerViewportProps) {
@@ -48,6 +52,7 @@ function ComposerViewport({
       bottomInset,
       safeAreaBottom: safeAreaBottom.value,
       keyboardShift: layoutShift.value,
+      keyboardGap,
       centered,
     }),
     (geometry) => {
@@ -129,6 +134,10 @@ export function ComposerDock({
   const insets = useSafeAreaInsets();
   const contentMaxWidth = resolveContentMaxWidth(useAppSettings().settings);
   const centeredClearance = useCenteredClearance(insets.bottom);
+  const placement = resolveComposerBottomPlacement({
+    safeAreaBottom: insets.bottom,
+    contentSpacing: SPACING[4],
+  });
   // Preserve the existing centered form's visual balance on tablets.
   const bottomInset = centered && !fullscreen ? HEADER_INNER_HEIGHT + 24 : 0;
   const fullscreenSurface = [
@@ -176,17 +185,23 @@ export function ComposerDock({
               style={fullscreen ? dockStyles.surface : dockStyles.centeredComposer}
               fullscreen={fullscreen}
             >
-              <View style={fullscreen ? fullscreenSurface : dockStyles.composer}>{composer}</View>
+              <View style={fullscreen ? fullscreenSurface : dockStyles.centeredComposerSurface}>
+                {composer}
+              </View>
             </ComposerViewportContent>
           </ComposerViewportContent>
-          {overlay}
         </KeyboardTranslateView>
+        {overlay}
       </ComposerViewport>
     );
   }
   return (
-    <ComposerViewport style={dockStyles.viewport}>
-      <KeyboardTranslateView style={dockStyles.surface} enabled={!fullscreen}>
+    <ComposerViewport style={dockStyles.viewport} keyboardGap={placement.keyboardGap}>
+      <KeyboardTranslateView
+        style={dockStyles.surface}
+        enabled={!fullscreen}
+        keyboardGap={placement.keyboardGap}
+      >
         <View
           testID="composer-dock-content"
           collapsable={false}
@@ -208,14 +223,14 @@ export function ComposerDock({
             style={
               fullscreen
                 ? fullscreenSurface
-                : [dockStyles.composer, { paddingBottom: insets.bottom }]
+                : [dockStyles.composer, { paddingBottom: placement.restingPadding }]
             }
           >
             {composer}
           </View>
         </ComposerViewportContent>
-        {overlay}
       </KeyboardTranslateView>
+      {overlay}
     </ComposerViewport>
   );
 }
@@ -232,6 +247,7 @@ const dockStyles = StyleSheet.create({
   centered: { flexShrink: 1, width: "100%" },
   // Reserve the composer's own capped height before the setup scroll view shrinks.
   centeredComposer: { width: "100%", flexShrink: 0 },
+  centeredComposerSurface: { width: "100%", flexShrink: 1 },
   setup: { flexGrow: 0, flexShrink: 1, minHeight: 0 },
   hiddenSetup: { display: "none" },
 });
diff --git a/packages/app/src/composer/dock/index.tsx b/packages/app/src/composer/dock/index.tsx
index 421002352e..0456cd6280 100644
--- a/packages/app/src/composer/dock/index.tsx
+++ b/packages/app/src/composer/dock/index.tsx
@@ -72,7 +72,7 @@ export function ComposerDock({
 const styles = StyleSheet.create((theme) => ({
   surface: { flex: 1, overflow: "hidden" },
   content: { flex: 1, justifyContent: "flex-end" },
-  composer: { width: "100%", flexShrink: 1 },
+  composer: { width: "100%", flexShrink: 1, paddingBottom: theme.spacing[4] },
   // Fixed, not absolute: a touch pan that starts inside an overflow-hidden ancestor
   // never reaches the zoomed visual viewport, while a fixed box chains to the viewport
   // directly. React Native Web renders `fixed`; React Native's style type omits it.
diff --git a/packages/app/src/composer/dock/internal/capacity.test.ts b/packages/app/src/composer/dock/internal/capacity.test.ts
index 44e79e6ef9..973c7f2406 100644
--- a/packages/app/src/composer/dock/internal/capacity.test.ts
+++ b/packages/app/src/composer/dock/internal/capacity.test.ts
@@ -1,18 +1,66 @@
 import { describe, expect, it } from "vitest";
 import {
   resolveCenteredClearance,
+  resolveComposerBottomPlacement,
   resolveComposerSlotCapacity,
   resolveInlineComposerCapacity,
   resolveComposerCapacity,
   updateComposerCapacity,
 } from "./capacity";
 
+describe("composer bottom placement", () => {
+  const keyboardHeight = 264;
+  /** Keyboard top minus composer bottom, both measured up from the window bottom. */
+  function keyboardGapAbove(safeAreaBottom: number): number {
+    const placement = resolveComposerBottomPlacement({ safeAreaBottom, contentSpacing: 16 });
+    const shift = keyboardHeight - safeAreaBottom;
+    const lift = shift + Math.min(placement.keyboardGap, shift);
+    return placement.restingPadding + lift - keyboardHeight;
+  }
+
+  it("rests at the bottom clearance without stacking a second gutter", () => {
+    expect(resolveComposerBottomPlacement({ safeAreaBottom: 34, contentSpacing: 16 })).toEqual({
+      restingPadding: 34,
+      keyboardGap: 16,
+    });
+    expect(
+      resolveComposerBottomPlacement({ safeAreaBottom: 24, contentSpacing: 16 }).restingPadding,
+    ).toBe(24);
+  });
+
+  it.each([0, 20, 34])("never rests closer to the edge than the content spacing (%s)", (inset) => {
+    expect(
+      resolveComposerBottomPlacement({ safeAreaBottom: inset, contentSpacing: 16 }).restingPadding,
+    ).toBe(Math.max(inset, 16));
+  });
+
+  it("keeps a measured zero clearance at the content spacing", () => {
+    expect(resolveComposerBottomPlacement({ safeAreaBottom: 0, contentSpacing: 16 })).toEqual({
+      restingPadding: 16,
+      keyboardGap: 0,
+    });
+  });
+
+  it.each([0, 20, 24, 34])("keeps the content spacing above the keyboard (%s)", (inset) => {
+    expect(keyboardGapAbove(inset)).toBe(16);
+  });
+
+  it("reserves the gap's extra rise out of the docked composer's capacity", () => {
+    const viewport = { height: 582, bottomInset: 0, safeAreaBottom: 34, centered: false };
+    const closed = resolveComposerCapacity({ ...viewport, keyboardShift: 0, keyboardGap: 16 });
+    const open = resolveComposerCapacity({ ...viewport, keyboardShift: 230, keyboardGap: 16 });
+    expect(closed).toBe(577);
+    expect(open).toBe(331);
+  });
+});
+
 describe("composer viewport", () => {
   it("caps the complete compact composer at sixty percent of keyboard-reserved space", () => {
     const open = updateComposerCapacity(undefined, {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -25,6 +73,7 @@ describe("composer viewport", () => {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -35,7 +84,13 @@ describe("composer viewport", () => {
     );
   });
   it("preserves the editing capacity when the keyboard closes", () => {
-    const viewport = { height: 582, bottomInset: 24, safeAreaBottom: 0, centered: false };
+    const viewport = {
+      height: 582,
+      bottomInset: 24,
+      safeAreaBottom: 0,
+      keyboardGap: 0,
+      centered: false,
+    };
     const open = updateComposerCapacity(undefined, { ...viewport, keyboardShift: 308 });
     const closed = updateComposerCapacity(open, { ...viewport, keyboardShift: 0 });
     expect(open.capacity).toBe(245);
@@ -48,6 +103,7 @@ describe("composer viewport", () => {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -56,6 +112,7 @@ describe("composer viewport", () => {
         height: 650,
         bottomInset: 24,
         safeAreaBottom: 0,
+        keyboardGap: 0,
         centered: false,
         keyboardShift: 0,
       }).capacity,
@@ -65,6 +122,7 @@ describe("composer viewport", () => {
         height: 0,
         bottomInset: 24,
         safeAreaBottom: 0,
+        keyboardGap: 0,
         centered: false,
         keyboardShift: 0,
       }),
@@ -76,6 +134,7 @@ describe("composer viewport", () => {
       bottomInset: 24,
       safeAreaBottom: 0,
       keyboardShift: 308,
+      keyboardGap: 0,
       centered: false,
     });
     expect(height).toBe(245);
@@ -91,6 +150,7 @@ describe("composer viewport", () => {
       bottomInset,
       safeAreaBottom: 0,
       keyboardShift,
+      keyboardGap: 0,
       centered: true,
     });
     expect(height).toBe(695);
@@ -110,6 +170,7 @@ describe("composer viewport", () => {
         bottomInset: 72,
         safeAreaBottom: 0,
         keyboardShift: 313,
+        keyboardGap: 0,
         centered: true,
       }),
     ).toBe(407);
@@ -122,6 +183,7 @@ describe("composer viewport", () => {
       bottomInset: 60,
       safeAreaBottom: 32,
       keyboardShift: 288,
+      keyboardGap: 0,
       centered: true,
     };
     const height = resolveComposerCapacity(geometry);
@@ -145,6 +207,7 @@ describe("composer viewport", () => {
         bottomInset: 24,
         safeAreaBottom: 0,
         keyboardShift: 0,
+        keyboardGap: 0,
         centered: false,
       }),
     ).toBe(553);
@@ -154,6 +217,7 @@ describe("composer viewport", () => {
         bottomInset: 0,
         safeAreaBottom: 0,
         keyboardShift: 200,
+        keyboardGap: 0,
         centered: false,
       }),
     ).toBe(95);
diff --git a/packages/app/src/composer/dock/internal/capacity.ts b/packages/app/src/composer/dock/internal/capacity.ts
index 9c460e1729..d9be8b9255 100644
--- a/packages/app/src/composer/dock/internal/capacity.ts
+++ b/packages/app/src/composer/dock/internal/capacity.ts
@@ -4,6 +4,8 @@ interface ComposerGeometry {
   /** The keyboard also covers this space below its shift. */
   safeAreaBottom: number;
   keyboardShift: number;
+  /** A docked composer rises this much beyond the keyboard shift; see the placement. */
+  keyboardGap: number;
   centered: boolean;
 }
 
@@ -24,10 +26,36 @@ export function resolveComposerCapacity(input: ComposerGeometry): number {
         input.height - input.bottomInset,
         input.height - input.safeAreaBottom - input.keyboardShift,
       )
-    : input.height - input.bottomInset - input.keyboardShift;
+    : input.height -
+      input.bottomInset -
+      input.keyboardShift -
+      Math.min(input.keyboardGap, input.keyboardShift);
   return Math.max(0, available - 5);
 }
 
+export interface ComposerBottomPlacement {
+  /** The composer's distance from the window bottom with the keyboard closed. */
+  restingPadding: number;
+  /** How much further than the keyboard's safe-area overlap the composer rises. */
+  keyboardGap: number;
+}
+
+/**
+ * One bottom distance for the docked composer: the safe-area bottom, never closer to
+ * the edge than the content spacing. With the keyboard open it keeps the content
+ * spacing above the keyboard.
+ */
+export function resolveComposerBottomPlacement(input: {
+  safeAreaBottom: number;
+  contentSpacing: number;
+}): ComposerBottomPlacement {
+  const restingPadding = Math.max(input.safeAreaBottom, input.contentSpacing);
+  return {
+    restingPadding,
+    keyboardGap: input.safeAreaBottom + input.contentSpacing - restingPadding,
+  };
+}
+
 /** Space below a centered form that the keyboard fills before the form moves. */
 export function resolveCenteredClearance(input: {
   viewportHeight: number;
diff --git a/packages/app/src/composer/dock/overlay-placement.test.ts b/packages/app/src/composer/dock/overlay-placement.test.ts
new file mode 100644
index 0000000000..da4262af12
--- /dev/null
+++ b/packages/app/src/composer/dock/overlay-placement.test.ts
@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+import { expect, it } from "vitest";
+
+it("keeps dock overlays outside keyboard translation in every native layout", () => {
+  const source = ts.createSourceFile(
+    "dock.tsx",
+    readFileSync(new URL("./index.native.tsx", import.meta.url), "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let surfaces = 0;
+  function visit(node: ts.Node) {
+    if (
+      ts.isJsxElement(node) &&
+      node.openingElement.tagName.getText(source) === "KeyboardTranslateView"
+    ) {
+      surfaces++;
+      function assertStationary(child: ts.Node) {
+        if (ts.isJsxExpression(child))
+          expect(child.expression?.getText(source)).not.toBe("overlay");
+        ts.forEachChild(child, assertStationary);
+      }
+      ts.forEachChild(node, assertStationary);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  expect(surfaces).toBe(2);
+});
diff --git a/packages/app/src/composer/draft/composer-agent.test.ts b/packages/app/src/composer/draft/composer-agent.test.ts
new file mode 100644
index 0000000000..35256eba4c
--- /dev/null
+++ b/packages/app/src/composer/draft/composer-agent.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it } from "vitest";
+import type { AgentModelDefinition } from "@getpaseo/protocol/agent-types";
+import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
+import {
+  draftControlsRequest,
+  openDraftOptions,
+  shownDraftOptions,
+} from "@/agent-controls/draft-options-model";
+import { openAgentForm, type AgentFormCatalog } from "@/provider-selection/agent-form-store";
+import { draftComposerAgent } from "./composer-agent";
+
+function definition(id: string, modeId: string): AgentProviderDefinition {
+  return {
+    id,
+    label: id,
+    description: id,
+    defaultModeId: modeId,
+    modes: [{ id: modeId, label: modeId, icon: "ShieldCheck", colorTier: "safe" }],
+  };
+}
+
+function model(provider: string, id: string, isDefault = false): AgentModelDefinition {
+  return { provider, id, label: id, isDefault };
+}
+
+/** The host: two providers with catalogs, and one that is ready but lists no models. */
+const catalog: AgentFormCatalog = {
+  selectableProviders: new Map([
+    ["claude", definition("claude", "default")],
+    ["codex", definition("codex", "auto")],
+    ["opencode", definition("opencode", "build")],
+  ]),
+  models: new Map([
+    ["claude", [model("claude", "sonnet", true)]],
+    ["codex", [model("codex", "gpt-5.4", true), model("codex", "gpt-5.5")]],
+    ["opencode", []],
+  ]),
+  providerPreferences: () => undefined,
+};
+
+/** A draft composer on the real form and options models. */
+function openDraft(context: "draft" | "new-workspace") {
+  const form = openAgentForm(() => catalog);
+  const options = openDraftOptions({
+    provider: null,
+    currentProvider: () => form.getState().form.provider,
+  });
+  // The screen hands the options the provider the form reaches.
+  form.subscribe(() => options.observeProvider(form.getState().form.provider));
+  form.setProviderAndModel("claude", "");
+
+  function agent() {
+    const { form: current } = form.getState();
+    return draftComposerAgent({
+      context,
+      selectedProvider: current.provider,
+      selectedModel: current.model,
+      selectedMode: current.modeId,
+      thinking: current.thinkingOptionId || null,
+      isLocked: () => false,
+      options: shownDraftOptions(options.getState(), {
+        provider: current.provider,
+        requestKey: "",
+      }),
+      metadata: {},
+      onSelectProviderAndModel: form.setProviderAndModel,
+      onSelectModel: form.setModel,
+      onSelectMode: () => undefined,
+      onSelectThinkingOption: () => undefined,
+      onSetOption: options.setOption,
+      onSetMetadata: () => undefined,
+    });
+  }
+
+  /** What the daemon is asked to resolve for the agent this draft would create. */
+  function request() {
+    const { form: current } = form.getState();
+    return draftControlsRequest(options.getState(), {
+      provider: current.provider,
+      cwd: "/repo",
+      modeId: current.modeId,
+      modelId: current.model,
+    });
+  }
+
+  return { form, agent, request };
+}
+
+describe("a draft's options", () => {
+  it("belong to the provider the form has now, before the screen has rendered the change", () => {
+    const form = openAgentForm(() => catalog);
+    const options = openDraftOptions({
+      provider: null,
+      currentProvider: () => form.getState().form.provider,
+    });
+    // No subscription: the screen observes the provider in an effect, after the command ran.
+    form.setProviderAndModel("claude", "");
+    options.observeProvider("claude");
+    options.setOption("context", "1m");
+
+    form.setProviderAndModel("codex", "");
+    options.setOption("effort", "high");
+
+    expect(options.getState()).toMatchObject({ provider: "codex", edits: { effort: "high" } });
+  });
+});
+
+describe.each(["draft", "new-workspace"] as const)("the %s composer's agent", (context) => {
+  it("applies each awaited command before the next one runs", async () => {
+    const draft = openDraft(context);
+    // A plugin keeps the object it was handed across its awaits.
+    const retained = draft.agent();
+
+    await retained.setProvider("codex");
+    await retained.setModel("gpt-5.5");
+    await retained.setOptions({ context: "1m" });
+
+    const agent = draft.agent();
+    expect(agent).toMatchObject({
+      context,
+      provider: "codex",
+      model: "gpt-5.5",
+      options: { context: "1m" },
+    });
+    expect(draft.request()).toMatchObject({
+      provider: "codex",
+      model: "gpt-5.5",
+      providerOptions: { context: "1m" },
+    });
+  });
+
+  it("starts the options over when the provider is chosen by hand", async () => {
+    const draft = openDraft(context);
+    const retained = draft.agent();
+
+    await retained.setOptions({ context: "1m" });
+    expect(draft.agent().options).toEqual({ context: "1m" });
+    await retained.setProvider("codex");
+
+    expect(draft.agent().options).toEqual({});
+  });
+
+  it("creates with the provider's default again once a plugin resets an option", async () => {
+    const draft = openDraft(context);
+    const retained = draft.agent();
+
+    await retained.setOptions({ context: "1m", effort: "high" });
+    await retained.setOptions({ context: null });
+
+    expect(draft.agent().options).toEqual({ effort: "high" });
+    expect(draft.request()?.providerOptions).toEqual({ effort: "high" });
+
+    await retained.setOptions({ effort: null });
+
+    expect(draft.agent().options).toEqual({});
+    expect(draft.request()?.providerOptions).toBeUndefined();
+  });
+
+  it("rejects a provider the host cannot run", async () => {
+    const draft = openDraft(context);
+    const retained = draft.agent();
+
+    await expect(retained.setProvider("nope")).rejects.toThrow(
+      "Unknown or unavailable provider: nope",
+    );
+    expect(draft.agent().provider).toBe("claude");
+  });
+
+  it("accepts a model id the catalog does not list; the form resolves it as the model picker does", async () => {
+    const draft = openDraft(context);
+    const retained = draft.agent();
+
+    await retained.setProvider("codex");
+    await expect(retained.setModel("missing")).resolves.toBeUndefined();
+
+    // The form keeps a listed model when the one asked for is not in the catalog.
+    expect(draft.agent()).toMatchObject({ provider: "codex", model: "gpt-5.4" });
+  });
+
+  it("keeps a model id as given when the provider lists no catalog", async () => {
+    const draft = openDraft(context);
+    const retained = draft.agent();
+
+    await retained.setProvider("opencode");
+    await retained.setModel("anthropic/claude-x");
+
+    expect(draft.agent().model).toBe("anthropic/claude-x");
+  });
+});
diff --git a/packages/app/src/composer/draft/composer-agent.ts b/packages/app/src/composer/draft/composer-agent.ts
new file mode 100644
index 0000000000..426f2edf4e
--- /dev/null
+++ b/packages/app/src/composer/draft/composer-agent.ts
@@ -0,0 +1,50 @@
+import type { ComposerAgent } from "@/composer/session";
+import type { DraftAgentControlsProps } from "@/composer/agent-controls";
+
+/**
+ * The agent a draft composer creates, as a plugin sees it. Its commands go to the form and the
+ * options model, which apply them as they run, so a plugin can `await` one and issue the next.
+ */
+export function draftComposerAgent(
+  props: Pick<
+    DraftAgentControlsProps,
+    | "context"
+    | "disabled"
+    | "selectedProvider"
+    | "selectedModel"
+    | "selectedMode"
+    | "options"
+    | "metadata"
+    | "onSelectProviderAndModel"
+    | "onSelectModel"
+    | "onSelectMode"
+    | "onSelectThinkingOption"
+    | "onSetOption"
+    | "onSetMetadata"
+  > & { thinking: string | null; isLocked: () => boolean },
+): ComposerAgent {
+  return {
+    context: props.context ?? "draft",
+    locked: props.disabled ?? false,
+    isLocked: props.isLocked,
+    provider: props.selectedProvider,
+    model: props.selectedModel || null,
+    mode: props.selectedMode || null,
+    thinking: props.thinking,
+    options: props.options,
+    metadata: props.metadata,
+    // An empty model id picks the provider's default model.
+    setProvider: async (provider) => {
+      if (!props.onSelectProviderAndModel(provider, "")) {
+        throw new Error(`Unknown or unavailable provider: ${provider}`);
+      }
+    },
+    setModel: async (modelId) => props.onSelectModel(modelId),
+    setMode: async (modeId) => props.onSelectMode(modeId),
+    setThinking: async (thinkingOptionId) => props.onSelectThinkingOption(thinkingOptionId),
+    setOptions: async (patch) => {
+      for (const [key, value] of Object.entries(patch)) props.onSetOption(key, value);
+    },
+    setMetadata: async (patch) => props.onSetMetadata(patch),
+  };
+}
diff --git a/packages/app/src/composer/draft/create-flow.test.ts b/packages/app/src/composer/draft/create-flow.test.ts
index 8587fa3db6..fd8c8abb3c 100644
--- a/packages/app/src/composer/draft/create-flow.test.ts
+++ b/packages/app/src/composer/draft/create-flow.test.ts
@@ -60,17 +60,6 @@ describe("useDraftAgentCreateFlow", () => {
 
     expect(result.current.isSubmitting).toBe(true);
     expect(result.current.draftAgent).toEqual({ currentAttempt: attempt });
-    expect(result.current.submittedStreamItems).toEqual([
-      {
-        kind: "user_message",
-        id: "msg-prepared",
-        clientMessageId: "msg-prepared",
-        text: "build this",
-        timestamp: attempt.timestamp,
-        images: [image],
-        attachments: [attachment],
-      },
-    ]);
     expect(createRequest).not.toHaveBeenCalled();
 
     await act(async () => {
diff --git a/packages/app/src/composer/draft/create-flow.ts b/packages/app/src/composer/draft/create-flow.ts
index bd4d0fe95c..28ab74d145 100644
--- a/packages/app/src/composer/draft/create-flow.ts
+++ b/packages/app/src/composer/draft/create-flow.ts
@@ -8,15 +8,8 @@ import {
 import { isActiveCreateFlowForDraft, useCreateFlowStore } from "@/stores/create-flow-store";
 import { handoffCreatedAgentMessageSubmission } from "@/composer/submission/writer";
 import { useSessionStore } from "@/stores/session-store";
-import {
-  createUserMessage,
-  type StreamItem,
-  type UserMessageImageAttachment,
-} from "@/types/stream";
+import { createUserMessage, type UserMessageImageAttachment } from "@/types/stream";
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
-import type { PendingMessageSubmission } from "@/composer/submission/model";
-
-const EMPTY_STREAM_ITEMS: StreamItem[] = [];
 
 interface CreateAttempt {
   clientMessageId: string;
@@ -153,38 +146,6 @@ export function useDraftAgentCreateFlow<TDraftAgent, TCreateResult>({
   const formErrorMessage = machine.tag === "draft" ? machine.errorMessage : "";
   const isSubmitting = machine.tag === "creating";
 
-  const submittedStreamItems = useMemo<StreamItem[]>(() => {
-    if (machine.tag !== "creating") {
-      return EMPTY_STREAM_ITEMS;
-    }
-
-    if (
-      !machine.attempt.text &&
-      (!machine.attempt.images || machine.attempt.images.length === 0) &&
-      (!machine.attempt.attachments || machine.attempt.attachments.length === 0)
-    ) {
-      return EMPTY_STREAM_ITEMS;
-    }
-
-    return [
-      createUserMessage({
-        clientMessageId: machine.attempt.clientMessageId,
-        text: machine.attempt.text,
-        timestamp: machine.attempt.timestamp,
-        images: machine.attempt.images,
-        attachments: machine.attempt.attachments,
-      }),
-    ];
-  }, [machine]);
-  const pendingMessageSubmissions = useMemo<readonly PendingMessageSubmission[]>(() => {
-    if (machine.tag !== "creating") return [];
-    return [
-      {
-        clientMessageId: machine.attempt.clientMessageId,
-      },
-    ];
-  }, [machine]);
-
   const draftAgent = machine.tag === "creating" ? machine.draftAgent : null;
   const startCreateAttempt = useCallback(
     (attempt: CreateAttempt) => {
@@ -365,8 +326,6 @@ export function useDraftAgentCreateFlow<TDraftAgent, TCreateResult>({
     machine,
     formErrorMessage,
     isSubmitting,
-    submittedStreamItems,
-    pendingMessageSubmissions,
     draftAgent,
     handleCreateFromInput,
     continueCreateFromAttempt,
diff --git a/packages/app/src/composer/draft/input-draft-core.ts b/packages/app/src/composer/draft/input-draft-core.ts
index 162869855b..6458126e7f 100644
--- a/packages/app/src/composer/draft/input-draft-core.ts
+++ b/packages/app/src/composer/draft/input-draft-core.ts
@@ -1,3 +1,4 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { UserComposerAttachment } from "@/attachments/types";
 import type { DraftAgentControlsProps } from "@/composer/agent-controls";
 import type { UseAgentFormStateResult } from "@/hooks/use-agent-form-state";
@@ -20,12 +21,26 @@ export function resolveDraftKey(input: {
 
 export function buildDraftAgentControls(input: {
   formState: UseAgentFormStateResult;
-  features?: DraftAgentControlsProps["features"];
-  onSetFeature?: DraftAgentControlsProps["onSetFeature"];
+  optionControls?: DraftAgentControlsProps["optionControls"];
+  options: DraftAgentControlsProps["options"];
+  onSetOption: DraftAgentControlsProps["onSetOption"];
   onApplyAgentProfile: DraftAgentControlsProps["onApplyAgentProfile"];
   onDropdownClose?: DraftAgentControlsProps["onDropdownClose"];
+  context: NonNullable<DraftAgentControlsProps["context"]>;
+  metadata: Record<string, JsonValue>;
+  onSetMetadata: (patch: Record<string, JsonValue>) => void;
 }): DraftAgentControlsProps {
-  const { formState, features, onSetFeature, onApplyAgentProfile, onDropdownClose } = input;
+  const {
+    formState,
+    optionControls,
+    options,
+    onSetOption,
+    onApplyAgentProfile,
+    onDropdownClose,
+    context,
+    metadata,
+    onSetMetadata,
+  } = input;
   return {
     providerDefinitions: formState.providerDefinitions,
     selectedProvider: formState.selectedProvider,
@@ -43,13 +58,17 @@ export function buildDraftAgentControls(input: {
     selectedThinkingOptionId: formState.selectedThinkingOptionId,
     onSelectThinkingOption: formState.setThinkingOptionFromUser,
     onApplyAgentProfile,
-    features,
-    onSetFeature,
+    optionControls,
+    options,
+    onSetOption,
     onDropdownClose,
     onModelSelectorOpen: formState.refetchProviderModelsIfStale,
     onRetryModelProvider: formState.refreshProviderModels,
     isRetryingModelProvider: formState.isProviderModelsRefreshing,
     modelSelectorServerId: formState.selectedServerId,
+    context,
+    metadata,
+    onSetMetadata,
   };
 }
 
diff --git a/packages/app/src/composer/draft/input-draft.live.test.tsx b/packages/app/src/composer/draft/input-draft.live.test.tsx
index 8bc31bb176..871650f270 100644
--- a/packages/app/src/composer/draft/input-draft.live.test.tsx
+++ b/packages/app/src/composer/draft/input-draft.live.test.tsx
@@ -2,7 +2,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useDraftStore } from "@/stores/draft-store";
 import type { AttachmentMetadata, ComposerAttachment } from "@/attachments/types";
 import { createWorkspaceFileAttachment } from "@/attachments/workspace-file";
@@ -126,17 +126,13 @@ afterEach(async () => {
   });
 });
 
-let useAgentInputDraft: typeof import("./input-draft").useAgentInputDraft;
 type DraftRecordForTest = ReturnType<typeof useDraftStore.getState>["drafts"][string];
 
-beforeAll(async () => {
-  Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
-    value: true,
-    configurable: true,
-  });
-
-  ({ useAgentInputDraft } = await import("./input-draft"));
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  value: true,
+  configurable: true,
 });
+const { useAgentInputDraft } = await import("./input-draft");
 
 describe("useAgentInputDraft live contract", () => {
   beforeEach(() => {
@@ -148,6 +144,7 @@ describe("useAgentInputDraft live contract", () => {
       drafts: {},
       createModalDraft: null,
       attachmentFocusRequestByDraftKey: {},
+      textReplacementRequestByDraftKey: {},
     });
   });
 
@@ -490,6 +487,37 @@ describe("useAgentInputDraft live contract", () => {
     });
   });
 
+  it("shows text another module put in the draft while the input is retained off screen", async () => {
+    let latest: ReturnType<typeof useAgentInputDraft> | null = null;
+    function getLatest(): ReturnType<typeof useAgentInputDraft> {
+      if (!latest) throw new Error("Expected hook result");
+      return latest;
+    }
+    function Probe() {
+      latest = useAgentInputDraft({ draftKey: "draft:replaced" });
+      return null;
+    }
+    const container = document.getElementById("root");
+    if (!container) throw new Error("Missing root container");
+    const root = createTestRoot(container);
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={new QueryClient()}>
+          <Probe />
+        </QueryClientProvider>,
+      );
+    });
+    const before = getLatest().textReplacement.key;
+
+    await act(async () => {
+      useDraftStore.getState().replaceDraftText({ draftKey: "draft:replaced", text: "from away" });
+    });
+
+    expect(getLatest().textReplacement).toMatchObject({ kind: "replace", text: "from away" });
+    expect(getLatest().textReplacement.key).not.toBe(before);
+    expect(getLatest().textSource.getSnapshot()).toBe("from away");
+  });
+
   it("clear resets text and attachments", async () => {
     let latest: ReturnType<typeof useAgentInputDraft> | null = null;
     const image: AttachmentMetadata = {
diff --git a/packages/app/src/composer/draft/input-draft.ts b/packages/app/src/composer/draft/input-draft.ts
index c14db9a119..3a445df10c 100644
--- a/packages/app/src/composer/draft/input-draft.ts
+++ b/packages/app/src/composer/draft/input-draft.ts
@@ -1,17 +1,17 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { UserComposerAttachment } from "@/attachments/types";
 import type { TextReplacement } from "@/composer/types";
 import type { DraftAgentControlsProps } from "@/composer/agent-controls";
-import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/agent-commands";
 import {
   useAgentFormState,
   type CreateAgentInitialValues,
   type UseAgentFormStateResult,
 } from "@/hooks/use-agent-form-state";
-import { useDraftAgentFeatures } from "@/hooks/use-draft-agent-features";
+import { useDraftProviderOptions } from "@/hooks/use-draft-provider-options";
 import {
   buildDraftAgentControls,
-  hasDraftContent,
   resolveDraftKey,
   type DraftKeyInput,
 } from "@/composer/draft/input-draft-core";
@@ -22,12 +22,14 @@ import {
   resolveEffectiveComposerThinkingOptionId,
   type ProviderSelectionState,
 } from "@/provider-selection/provider-selection";
-import { useDraftStore } from "@/stores/draft-store";
+import { useDraftStore, type DraftInput } from "@/stores/draft-store";
 import { AfterPaintPublication } from "@/composer/after-paint-publication";
 import { useShallow } from "zustand/shallow";
 import type { ComposerTextSource } from "@/composer/text-source";
 import { isWeb } from "@/constants/platform";
 
+const NO_METADATA: Record<string, JsonValue> = {};
+
 type AttachmentUpdater =
   | UserComposerAttachment[]
   | ((prev: UserComposerAttachment[]) => UserComposerAttachment[]);
@@ -35,7 +37,9 @@ type AttachmentUpdater =
 interface AgentInputDraftComposerOptions {
   initialServerId: string | null;
   initialValues?: CreateAgentInitialValues;
-  initialFeatureValues?: Record<string, unknown>;
+  initialProviderOptions?: Record<string, unknown>;
+  /** Which composer a plugin's `useComposer()` reports. */
+  context?: "draft" | "new-workspace";
   isVisible?: boolean;
   lockedWorkingDir?: string;
 }
@@ -50,7 +54,9 @@ type DraftComposerState = UseAgentFormStateResult & {
   effectiveModeId: string;
   effectiveModelId: string;
   effectiveThinkingOptionId: string;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: Record<string, unknown> | undefined;
+  /** What plugins set on the agent this draft creates. */
+  metadata: Record<string, JsonValue>;
   agentControls: DraftAgentControlsProps;
   commandDraft: DraftCommandTarget;
 };
@@ -135,21 +141,8 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
   );
 
   const saveDraft = useCallback(
-    (
-      update: (draft: { text: string; attachments: UserComposerAttachment[] }) => {
-        text: string;
-        attachments: UserComposerAttachment[];
-      },
-    ) => {
-      const store = useDraftStore.getState();
-      const current = store.getDraftInput(draftKey) ?? { text: "", attachments: [] };
-      const next = update(current);
-      if (!hasDraftContent(next)) {
-        store.clearDraftInput({ draftKey, lifecycle: "abandoned" });
-        return;
-      }
-      store.saveDraftInput({ draftKey, draft: next });
-    },
+    (update: (draft: DraftInput) => DraftInput) =>
+      useDraftStore.getState().updateDraftInput({ draftKey, update }),
     [draftKey],
   );
 
@@ -161,6 +154,20 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
     [draftKey],
   );
 
+  // Text another module put in the draft (a plugin writing to a composer that is not on screen)
+  // reaches the input the way a rewind restore does.
+  const replacementRequest = useDraftStore(
+    (state) => state.textReplacementRequestByDraftKey[draftKey] ?? 0,
+  );
+  const shownReplacementRequestRef = useRef({ draftKey, request: replacementRequest });
+  useEffect(() => {
+    const shown = shownReplacementRequestRef.current;
+    if (shown.draftKey === draftKey && shown.request === replacementRequest) return;
+    shownReplacementRequestRef.current = { draftKey, request: replacementRequest };
+    textPublication.cancel();
+    publishTextReplacement("replace", textSource.getSnapshot());
+  }, [draftKey, publishTextReplacement, replacementRequest, textPublication, textSource]);
+
   const editText = useCallback(
     (nextText: string) => {
       if (isWeb) {
@@ -191,10 +198,18 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
     [saveDraft],
   );
 
+  const metadata = useDraftStore((state) => state.metadataByDraftKey[draftKey] ?? NO_METADATA);
+  const setMetadata = useCallback(
+    (patch: Record<string, JsonValue>) =>
+      useDraftStore.getState().patchDraftMetadata({ draftKey, patch }),
+    [draftKey],
+  );
+
   const clear = useCallback(
     (lifecycle: "sent" | "abandoned") => {
       textPublication.cancel();
       useDraftStore.getState().clearDraftInput({ draftKey, lifecycle });
+      if (lifecycle === "sent") useDraftStore.getState().clearDraftMetadata({ draftKey });
     },
     [draftKey, textPublication],
   );
@@ -274,26 +289,28 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
   );
 
   const {
-    features: draftFeatures,
-    featureValues: draftFeatureValues,
-    setFeatureValue: setDraftFeatureValue,
-    applyProfileFeatureValues,
-  } = useDraftAgentFeatures({
+    optionControls: draftOptionControls,
+    options: draftOptions,
+    shownOptions: draftShownOptions,
+    setOption: setDraftOption,
+    applyProfile: applyProfileOptions,
+  } = useDraftProviderOptions({
     serverId: formState.selectedServerId,
     provider: formState.selectedProvider,
+    getProvider: formState.getSelectedProvider,
     cwd: workingDir,
     modeId: formState.selectedMode,
     modelId: effectiveModelId,
     thinkingOptionId: effectiveThinkingOptionId,
-    initialFeatureValues: composerOptions?.initialFeatureValues,
+    initialOptions: composerOptions?.initialProviderOptions,
   });
 
   const applyDraftAgentProfile = useCallback(
     (profile: Parameters<typeof formState.applyProfileFromUser>[0]) => {
       formState.applyProfileFromUser(profile);
-      applyProfileFeatureValues(profile.featureValues);
+      applyProfileOptions({ provider: profile.provider, options: profile.options });
     },
-    [applyProfileFeatureValues, formState],
+    [applyProfileOptions, formState],
   );
 
   const commandDraft = useMemo(
@@ -303,15 +320,9 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
         cwd: workingDir,
         effectiveModelId,
         effectiveThinkingOptionId,
-        featureValues: draftFeatureValues,
+        providerOptions: draftOptions,
       }),
-    [
-      effectiveModelId,
-      effectiveThinkingOptionId,
-      draftFeatureValues,
-      providerSelection,
-      workingDir,
-    ],
+    [effectiveModelId, effectiveThinkingOptionId, draftOptions, providerSelection, workingDir],
   );
 
   const composerState = useMemo<DraftComposerState | null>(() => {
@@ -325,12 +336,17 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
       effectiveModeId,
       effectiveModelId,
       effectiveThinkingOptionId,
-      featureValues: draftFeatureValues,
+      providerOptions: draftOptions,
+      metadata,
       agentControls: buildDraftAgentControls({
         formState,
-        features: draftFeatures,
-        onSetFeature: setDraftFeatureValue,
+        optionControls: draftOptionControls,
+        options: draftShownOptions,
+        onSetOption: setDraftOption,
         onApplyAgentProfile: applyDraftAgentProfile,
+        context: composerOptions.context ?? "draft",
+        metadata,
+        onSetMetadata: setMetadata,
       }),
       commandDraft,
     };
@@ -340,11 +356,14 @@ export function useAgentInputDraft(input: UseAgentInputDraftInput): AgentInputDr
     effectiveModeId,
     effectiveModelId,
     effectiveThinkingOptionId,
-    draftFeatures,
-    draftFeatureValues,
+    draftOptionControls,
+    draftOptions,
+    draftShownOptions,
+    setDraftOption,
     applyDraftAgentProfile,
     formState,
-    setDraftFeatureValue,
+    metadata,
+    setMetadata,
     workingDir,
   ]);
 
diff --git a/packages/app/src/composer/draft/metadata.test.ts b/packages/app/src/composer/draft/metadata.test.ts
new file mode 100644
index 0000000000..c1a0e28213
--- /dev/null
+++ b/packages/app/src/composer/draft/metadata.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { applyMetadataPatch } from "./metadata";
+
+describe("applyMetadataPatch", () => {
+  it("replaces top-level keys and removes keys patched to null", () => {
+    expect(
+      applyMetadataPatch(
+        { "linear.issue": { id: "ENG-1" }, review: true },
+        { "linear.issue": { id: "ENG-2" }, review: null, extra: [1] },
+      ),
+    ).toEqual({ "linear.issue": { id: "ENG-2" }, extra: [1] });
+  });
+
+  it("leaves the current record untouched", () => {
+    const current = { review: true };
+    applyMetadataPatch(current, { review: null });
+    expect(current).toEqual({ review: true });
+  });
+});
diff --git a/packages/app/src/composer/draft/metadata.ts b/packages/app/src/composer/draft/metadata.ts
new file mode 100644
index 0000000000..481abd24c2
--- /dev/null
+++ b/packages/app/src/composer/draft/metadata.ts
@@ -0,0 +1,14 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+
+/** Top-level keys replace; `null` removes the key. The daemon applies the same rule to an agent. */
+export function applyMetadataPatch(
+  current: Readonly<Record<string, JsonValue>>,
+  patch: Readonly<Record<string, JsonValue>>,
+): Record<string, JsonValue> {
+  const next = { ...current };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
diff --git a/packages/app/src/composer/draft/timeline.test.ts b/packages/app/src/composer/draft/timeline.test.ts
new file mode 100644
index 0000000000..a1344f8830
--- /dev/null
+++ b/packages/app/src/composer/draft/timeline.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import type { AgentAttachment } from "@getpaseo/protocol/messages";
+import type { PendingCreateAttempt } from "@/stores/create-flow-store";
+import type { UserMessageImageAttachment } from "@/types/stream";
+import { DRAFT_CAPABILITIES, resolveDraftTimeline } from "./timeline";
+
+const image: UserMessageImageAttachment = {
+  id: "image-1",
+  mimeType: "image/png",
+  storageType: "web-indexeddb",
+  storageKey: "image-key",
+  createdAt: 123,
+};
+const attachment = {
+  type: "review",
+  cwd: "/repo",
+  summary: "Review",
+} as unknown as AgentAttachment;
+
+function pendingAttempt(overrides: Partial<PendingCreateAttempt> = {}): PendingCreateAttempt {
+  return {
+    draftId: "draft-1",
+    serverId: "server-1",
+    agentId: null,
+    clientMessageId: "draft-1:initial-message",
+    text: "build this",
+    timestamp: Date.parse("2026-05-25T00:00:00.000Z"),
+    lifecycle: "active",
+    images: [image],
+    attachments: [attachment],
+    ...overrides,
+  };
+}
+
+describe("resolveDraftTimeline", () => {
+  it("shows the sent prompt pending with the turn working", () => {
+    const timeline = resolveDraftTimeline({
+      pending: pendingAttempt(),
+      serverId: "server-1",
+      tabId: "tab-1",
+      cwd: "/repo",
+    });
+
+    expect(timeline?.agent).toEqual({
+      serverId: "server-1",
+      id: "tab-1",
+      status: "running",
+      cwd: "/repo",
+      capabilities: DRAFT_CAPABILITIES,
+    });
+    expect(timeline?.streamItems).toEqual([
+      {
+        kind: "user_message",
+        id: "draft-1:initial-message",
+        clientMessageId: "draft-1:initial-message",
+        text: "build this",
+        timestamp: new Date("2026-05-25T00:00:00.000Z"),
+        images: [image],
+        attachments: [attachment],
+      },
+    ]);
+    expect(timeline?.pendingMessageSubmissions).toEqual([
+      { clientMessageId: "draft-1:initial-message" },
+    ]);
+    expect(timeline?.turnPresentation.isActive).toBe(true);
+  });
+
+  it("keeps the prompt once the agent is created, until the tab retargets", () => {
+    const timeline = resolveDraftTimeline({
+      pending: pendingAttempt({ lifecycle: "sent", agentId: "agent-1" }),
+      serverId: "server-1",
+      tabId: "tab-1",
+      cwd: "/repo",
+    });
+
+    expect(timeline?.streamItems).toHaveLength(1);
+  });
+
+  it("shows only the working turn for a prompt without content", () => {
+    const timeline = resolveDraftTimeline({
+      pending: pendingAttempt({ text: "", images: undefined, attachments: undefined }),
+      serverId: "server-1",
+      tabId: "tab-1",
+      cwd: "/repo",
+    });
+
+    expect(timeline?.streamItems).toEqual([]);
+    expect(timeline?.turnPresentation.isActive).toBe(true);
+  });
+
+  it("shows no timeline before a prompt is sent, after it fails, or on another host", () => {
+    const base = { serverId: "server-1", tabId: "tab-1", cwd: "/repo" };
+
+    expect(resolveDraftTimeline({ ...base, pending: undefined })).toBeNull();
+    expect(
+      resolveDraftTimeline({ ...base, pending: pendingAttempt({ lifecycle: "abandoned" }) }),
+    ).toBeNull();
+    expect(
+      resolveDraftTimeline({ ...base, pending: pendingAttempt({ serverId: "server-2" }) }),
+    ).toBeNull();
+    expect(resolveDraftTimeline({ ...base, cwd: null, pending: pendingAttempt() })).toBeNull();
+  });
+});
diff --git a/packages/app/src/composer/draft/timeline.ts b/packages/app/src/composer/draft/timeline.ts
new file mode 100644
index 0000000000..bbc0aecbce
--- /dev/null
+++ b/packages/app/src/composer/draft/timeline.ts
@@ -0,0 +1,102 @@
+import { useMemo } from "react";
+import type { AgentCapabilityFlags } from "@getpaseo/protocol/agent-types";
+import type { PendingMessageSubmission } from "@/composer/submission/model";
+import type { AgentScreenAgent } from "@/hooks/use-agent-screen-state-machine";
+import { type PendingCreateAttempt, useCreateFlowStore } from "@/stores/create-flow-store";
+import { useWorkspaceFields } from "@/stores/session-store-hooks";
+import {
+  resolveTurnPresentation,
+  TURN_LIVENESS_IDLE,
+  type TurnPresentation,
+} from "@/timeline/turn-liveness";
+import { createUserMessage, type StreamItem } from "@/types/stream";
+import type { WorkspaceDraftTabSetup } from "@/workspace-tabs/model";
+import { resolveDraftWorkingDirectory } from "@/composer/draft/workspace-tab-core";
+
+export const DRAFT_CAPABILITIES: AgentCapabilityFlags = {
+  supportsStreaming: true,
+  supportsSessionPersistence: false,
+  supportsDynamicModes: false,
+  supportsMcpServers: false,
+  supportsReasoningStream: false,
+  supportsToolInvocations: false,
+};
+
+export interface DraftConversation {
+  tabId: string;
+  workspaceId: string;
+  draftId: string;
+  setup?: WorkspaceDraftTabSetup;
+}
+
+/** The timeline a draft shows while its first prompt creates the agent. */
+export interface DraftTimeline {
+  agent: AgentScreenAgent;
+  streamItems: StreamItem[];
+  pendingMessageSubmissions: readonly PendingMessageSubmission[];
+  turnPresentation: TurnPresentation;
+}
+
+const EMPTY_STREAM_ITEMS: StreamItem[] = [];
+
+/**
+ * The sent prompt, pending, with the turn working. The created agent's timeline carries the same
+ * row (same client message id), so the handoff only changes who owns it.
+ */
+export function resolveDraftTimeline(input: {
+  pending: PendingCreateAttempt | undefined;
+  serverId: string;
+  tabId: string;
+  cwd: string | null;
+}): DraftTimeline | null {
+  const { pending, serverId, tabId, cwd } = input;
+  if (!pending || pending.serverId !== serverId || pending.lifecycle === "abandoned" || !cwd) {
+    return null;
+  }
+  const hasContent =
+    pending.text.length > 0 ||
+    (pending.images?.length ?? 0) > 0 ||
+    (pending.attachments?.length ?? 0) > 0;
+  return {
+    agent: { serverId, id: tabId, status: "running", cwd, capabilities: DRAFT_CAPABILITIES },
+    streamItems: hasContent
+      ? [
+          createUserMessage({
+            clientMessageId: pending.clientMessageId,
+            text: pending.text,
+            timestamp: new Date(pending.timestamp),
+            images: pending.images,
+            attachments: pending.attachments,
+          }),
+        ]
+      : EMPTY_STREAM_ITEMS,
+    pendingMessageSubmissions: [{ clientMessageId: pending.clientMessageId }],
+    turnPresentation: resolveTurnPresentation(TURN_LIVENESS_IDLE, true),
+  };
+}
+
+export function useDraftTimeline(input: {
+  serverId: string;
+  draft: DraftConversation | null;
+}): DraftTimeline | null {
+  const { serverId, draft } = input;
+  const pending = useCreateFlowStore((state) =>
+    draft ? state.pendingByDraftId[draft.draftId] : undefined,
+  );
+  const workspaceDirectory = useWorkspaceFields(
+    serverId,
+    draft?.workspaceId ?? null,
+    (workspace) => workspace.workspaceDirectory,
+  );
+  const cwd = draft
+    ? resolveDraftWorkingDirectory({
+        workspaceDirectory: workspaceDirectory || null,
+        initialSetup: draft.setup ?? null,
+      })
+    : null;
+  const tabId = draft?.tabId ?? "";
+  return useMemo(
+    () => resolveDraftTimeline({ pending, serverId, tabId, cwd }),
+    [cwd, pending, serverId, tabId],
+  );
+}
diff --git a/packages/app/src/composer/draft/workspace-tab-core.ts b/packages/app/src/composer/draft/workspace-tab-core.ts
index 26bf548064..89211571a2 100644
--- a/packages/app/src/composer/draft/workspace-tab-core.ts
+++ b/packages/app/src/composer/draft/workspace-tab-core.ts
@@ -1,4 +1,5 @@
 import { resolveSubmissionReadiness } from "@/provider-selection/provider-selection";
+import type { WorkspaceDraftTabSetup } from "@/workspace-tabs/model";
 
 export interface WorkspaceDraftAutoSubmitConfig {
   provider: string;
@@ -50,3 +51,13 @@ export function validateDraftSubmission(input: {
   });
   return readiness.ok ? null : (readiness.reason ?? null);
 }
+
+export function resolveDraftWorkingDirectory(input: {
+  workspaceDirectory: string | null;
+  initialSetup: WorkspaceDraftTabSetup | null;
+}): string | null {
+  if (input.initialSetup) {
+    return input.initialSetup.cwd;
+  }
+  return input.workspaceDirectory;
+}
diff --git a/packages/app/src/composer/draft/workspace-tab.tsx b/packages/app/src/composer/draft/workspace-tab.tsx
index c4ef45cb3f..0815603e55 100644
--- a/packages/app/src/composer/draft/workspace-tab.tsx
+++ b/packages/app/src/composer/draft/workspace-tab.tsx
@@ -1,21 +1,19 @@
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { Keyboard, ScrollView, StyleSheet as RNStyleSheet, Text, View } from "react-native";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import { Keyboard, StyleSheet as RNStyleSheet, Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
-import { ComposerDock } from "@/composer/dock";
 import { useContainerWidthBelow } from "@/hooks/use-container-width";
 import invariant from "tiny-invariant";
 import { Composer } from "@/composer";
-import { useComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
-import { FileDropZone } from "@/components/file-drop/file-drop-zone";
+import { type ComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
 import { ComposerImportPill } from "@/composer/draft/import-pill";
 import { COMPOSER_PILL_CLEARANCE } from "@/composer/pill-styles";
-import { AgentStreamView } from "@/agent-stream/view";
 import { composerWorkspaceAttachment } from "@/composer/attachments/workspace";
 import { useAgentInputDraft } from "@/composer/draft/input-draft";
 import type { CreateAgentInitialValues } from "@/hooks/use-agent-form-state";
 import { useDraftAgentCreateFlow, type DraftCreateAttempt } from "@/composer/draft/create-flow";
-import { resolveTurnPresentation, TURN_LIVENESS_IDLE } from "@/timeline/turn-liveness";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import { buildWorkspaceDraftAgentConfig } from "@/screens/workspace/workspace-draft-agent-config";
 import { buildDraftStoreKey } from "@/stores/draft-keys";
@@ -25,13 +23,13 @@ import { useWorkspaceFields } from "@/stores/session-store-hooks";
 import { useWorkspaceDraftSubmissionStore } from "@/stores/workspace-draft-submission-store";
 import { useAgentControlCommandCenterActions } from "@/command-center/agent-control-registration";
 import { encodeImages } from "@/utils/encode-images";
-import type { WorkspaceFileOpenRequest } from "@/workspace/file-open";
 import { shouldAutoFocusWorkspaceDraftComposer } from "@/screens/workspace/workspace-draft-pane-focus";
 import {
+  resolveDraftWorkingDirectory,
   shouldAllowEmptyDraftText,
   validateDraftSubmission,
 } from "@/composer/draft/workspace-tab-core";
-import type { AgentCapabilityFlags } from "@getpaseo/protocol/agent-types";
+import { DRAFT_CAPABILITIES } from "@/composer/draft/timeline";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import type { WorkspaceComposerAttachment } from "@/attachments/types";
@@ -50,22 +48,12 @@ import {
 import { openWorkspaceChanges } from "@/workspace-tabs/open-supporting-view";
 import { useSettings } from "@/hooks/use-settings";
 
-const EMPTY_PENDING_PERMISSIONS = new Map();
-const DRAFT_CAPABILITIES: AgentCapabilityFlags = {
-  supportsStreaming: true,
-  supportsSessionPersistence: false,
-  supportsDynamicModes: false,
-  supportsMcpServers: false,
-  supportsReasoningStream: false,
-  supportsToolInvocations: false,
-};
-
 interface AutoSubmitConfig {
   provider: string;
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown>;
+  providerOptions: Record<string, unknown>;
 }
 
 function resolveAutoSubmitConfig(
@@ -74,7 +62,7 @@ function resolveAutoSubmitConfig(
     modeId?: string | null;
     model?: string | null;
     thinkingOptionId?: string | null;
-    featureValues?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
   } | null,
 ): AutoSubmitConfig | null {
   if (!pending) return null;
@@ -83,7 +71,7 @@ function resolveAutoSubmitConfig(
     modeId: pending.modeId ?? null,
     model: pending.model ?? null,
     thinkingOptionId: pending.thinkingOptionId ?? null,
-    featureValues: pending.featureValues ?? {},
+    providerOptions: pending.providerOptions ?? {},
   };
 }
 
@@ -131,7 +119,8 @@ async function submitDraftCreateRequest(input: {
     effectiveModeId: string;
     effectiveModelId: string | null;
     effectiveThinkingOptionId: string | null;
-    featureValues: Record<string, unknown> | undefined;
+    providerOptions: Record<string, unknown> | undefined;
+    metadata: Record<string, JsonValue>;
   };
   hostDisconnectedMessage: string;
   selectModelMessage: string;
@@ -170,7 +159,7 @@ async function submitDraftCreateRequest(input: {
     model: autoSubmitConfig?.model ?? (composerState.effectiveModelId || undefined),
     thinkingOptionId:
       autoSubmitConfig?.thinkingOptionId ?? (composerState.effectiveThinkingOptionId || undefined),
-    featureValues: autoSubmitConfig?.featureValues ?? composerState.featureValues,
+    providerOptions: autoSubmitConfig?.providerOptions ?? composerState.providerOptions,
   });
 
   const attachmentsArray = Array.isArray(attachments) ? attachments : undefined;
@@ -181,6 +170,7 @@ async function submitDraftCreateRequest(input: {
     workspaceId,
     initialPrompt: text,
     clientMessageId: attempt.clientMessageId,
+    ...(Object.keys(composerState.metadata).length > 0 ? { metadata: composerState.metadata } : {}),
     ...(imagesData && imagesData.length > 0 ? { images: imagesData } : {}),
     ...(attachmentsArray && attachmentsArray.length > 0 ? { attachments: attachmentsArray } : {}),
   };
@@ -204,7 +194,7 @@ function buildDraftAgentSnapshot(input: {
     effectiveThinkingOptionId: string | null;
     effectiveModeId: string;
     selectedProvider: string | null;
-    agentControls: { features?: Agent["features"] };
+    agentControls: { optionControls?: ComposerOptionControls };
   };
   selectModelMessage: string;
 }): Agent {
@@ -241,7 +231,8 @@ function buildDraftAgentSnapshot(input: {
     title: "Agent",
     cwd: workspaceDirectory,
     model,
-    features: composerState.agentControls.features,
+    options: composerState.agentControls.optionControls?.options,
+    controls: composerState.agentControls.optionControls?.controls,
     thinkingOptionId,
     parentAgentId: null,
     labels: {},
@@ -260,25 +251,15 @@ function buildDraftInitialValues(input: {
   };
 }
 
-function resolveDraftWorkingDirectory(input: {
-  workspaceDirectory: string | null;
-  initialSetup: WorkspaceDraftTabSetup | null;
-}): string | null {
-  if (input.initialSetup) {
-    return input.initialSetup.cwd;
-  }
-  return input.workspaceDirectory;
-}
-
-interface WorkspaceDraftAgentTabProps {
+interface WorkspaceDraftComposerProps {
   serverId: string;
   workspaceId: string;
   tabId: string;
   draftId: string;
   initialSetup?: WorkspaceDraftTabSetup;
   isPaneFocused: boolean;
+  editingSession: ComposerEditingSession;
   onCreated: (snapshot: AgentSnapshotPayload) => void;
-  onOpenWorkspaceFile: (request: WorkspaceFileOpenRequest) => void;
   onOpenImportSheet?: () => void;
 }
 
@@ -292,17 +273,21 @@ function resolveImportPillPress(
   return onOpenImportSheet ?? null;
 }
 
-export function WorkspaceDraftAgentTab({
+/**
+ * Creates the agent from the draft's first prompt. The conversation panel shows that prompt in
+ * the timeline from the create-flow store while the agent is created.
+ */
+export function WorkspaceDraftComposer({
   serverId,
   workspaceId,
   tabId,
   draftId,
   initialSetup = undefined,
   isPaneFocused,
+  editingSession,
   onCreated,
-  onOpenWorkspaceFile,
   onOpenImportSheet,
-}: WorkspaceDraftAgentTabProps) {
+}: WorkspaceDraftComposerProps) {
   const { t } = useTranslation();
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
@@ -333,7 +318,7 @@ export function WorkspaceDraftAgentTab({
     composer: {
       initialServerId: serverId,
       initialValues: draftInitialValues,
-      initialFeatureValues: draftSetup?.featureValues,
+      initialProviderOptions: draftSetup?.providerOptions,
       isVisible: true,
       lockedWorkingDir: draftWorkingDirectory ?? undefined,
     },
@@ -351,8 +336,7 @@ export function WorkspaceDraftAgentTab({
   const draftModeOptions = composerState.modeOptions;
   const draftSelectedMode = composerState.selectedMode;
   const draftSetMode = composerState.setModeFromUser;
-  const draftFeatures = composerState.agentControls.features;
-  const draftOnSetFeature = composerState.agentControls.onSetFeature;
+  const draftOptionControls = composerState.agentControls.optionControls;
 
   const clearDraftInput = draftInput.clear;
   const replaceDraftText = draftInput.replaceText;
@@ -387,7 +371,6 @@ export function WorkspaceDraftAgentTab({
   }, [pendingCreateAttempt]);
   const allowsEmptyAutoSubmit = pendingAutoSubmit?.allowEmptyText === true;
   const isCompactFormFactor = useIsCompactFormFactor();
-  const editingSession = useComposerEditingSession("chat");
   const isComposerFullscreen = useComposerFullscreen(editingSession);
   const { onLayout: onInputAreaLayout, isBelow: isCompactComposerLayout } = useContainerWidthBelow(
     COMPACT_CONTENT_WIDTH,
@@ -421,82 +404,71 @@ export function WorkspaceDraftAgentTab({
     [isCompactFormFactor, openInSidePane, serverId, workspaceId],
   );
 
-  const {
-    formErrorMessage,
-    isSubmitting,
-    submittedStreamItems,
-    pendingMessageSubmissions,
-    draftAgent,
-    handleCreateFromInput,
-    continueCreateFromAttempt,
-  } = useDraftAgentCreateFlow<Agent, AgentSnapshotPayload>({
-    draftId,
-    getPendingServerId: () => serverId,
-    initialAttempt: initialCreateAttempt,
-    allowEmptyText: allowsEmptyAutoSubmit,
-    validateBeforeSubmit: ({ text, attachments }) => {
-      const allowsEmptyDraftText = shouldAllowEmptyDraftText({
-        allowsEmptyAutoSubmit,
-        attachments,
-      });
-      return validateDraftSubmission({
-        text,
-        allowsEmptyAutoSubmit: allowsEmptyDraftText,
-        composerState,
-        autoSubmitConfig,
-        workspaceDirectory: draftWorkingDirectory,
-        isConnected,
-      });
-    },
-    onBeforeSubmit: async () => {
-      await composerState.persistFormPreferences();
-      if (isWeb) {
-        (document.activeElement as HTMLElement | null)?.blur?.();
-      }
-      Keyboard.dismiss();
-    },
-    buildDraftAgent: (attempt) =>
-      buildDraftAgentSnapshot({
-        attempt,
-        serverId,
-        tabId,
-        workspaceDirectory: draftWorkingDirectory,
-        autoSubmitConfig,
-        composerState,
-        selectModelMessage: t("workspaceSetup.errors.selectModel"),
-      }),
-    createRequest: async ({ attempt, text, images, attachments, cwd }) => {
-      if (pendingAutoSubmit?.agentCreation) {
-        const result = await pendingAutoSubmit.agentCreation.result;
-        return { agentId: result.id, result };
-      }
-      return submitDraftCreateRequest({
-        draftId,
-        attempt,
-        text,
-        images,
-        attachments,
-        cwd,
-        client,
-        workspaceDirectory: draftWorkingDirectory,
-        workspaceId: workspaceFields?.id ?? null,
-        autoSubmitConfig,
-        composerState,
-        hostDisconnectedMessage: t("workspace.terminal.hostDisconnected"),
-        selectModelMessage: t("workspaceSetup.errors.selectModel"),
-      });
-    },
-    onCreateSuccess: ({ result }) => {
-      clearDraftInput("sent");
-      clearWorkspaceAttachments({ scopeKey: draftAttachmentScopeKey });
-      useWorkspaceDraftSubmissionStore.getState().clearDraftSetup({ draftId });
-      onCreated(result);
-    },
-  });
-  const turnPresentation = useMemo(
-    () => resolveTurnPresentation(TURN_LIVENESS_IDLE, pendingMessageSubmissions.length > 0),
-    [pendingMessageSubmissions],
-  );
+  const { formErrorMessage, isSubmitting, handleCreateFromInput, continueCreateFromAttempt } =
+    useDraftAgentCreateFlow<Agent, AgentSnapshotPayload>({
+      draftId,
+      getPendingServerId: () => serverId,
+      initialAttempt: initialCreateAttempt,
+      allowEmptyText: allowsEmptyAutoSubmit,
+      validateBeforeSubmit: ({ text, attachments }) => {
+        const allowsEmptyDraftText = shouldAllowEmptyDraftText({
+          allowsEmptyAutoSubmit,
+          attachments,
+        });
+        return validateDraftSubmission({
+          text,
+          allowsEmptyAutoSubmit: allowsEmptyDraftText,
+          composerState,
+          autoSubmitConfig,
+          workspaceDirectory: draftWorkingDirectory,
+          isConnected,
+        });
+      },
+      onBeforeSubmit: async () => {
+        await composerState.persistFormPreferences();
+        if (isWeb) {
+          (document.activeElement as HTMLElement | null)?.blur?.();
+        }
+        Keyboard.dismiss();
+      },
+      buildDraftAgent: (attempt) =>
+        buildDraftAgentSnapshot({
+          attempt,
+          serverId,
+          tabId,
+          workspaceDirectory: draftWorkingDirectory,
+          autoSubmitConfig,
+          composerState,
+          selectModelMessage: t("workspaceSetup.errors.selectModel"),
+        }),
+      createRequest: async ({ attempt, text, images, attachments, cwd }) => {
+        if (pendingAutoSubmit?.agentCreation) {
+          const result = await pendingAutoSubmit.agentCreation.result;
+          return { agentId: result.id, result };
+        }
+        return submitDraftCreateRequest({
+          draftId,
+          attempt,
+          text,
+          images,
+          attachments,
+          cwd,
+          client,
+          workspaceDirectory: draftWorkingDirectory,
+          workspaceId: workspaceFields?.id ?? null,
+          autoSubmitConfig,
+          composerState,
+          hostDisconnectedMessage: t("workspace.terminal.hostDisconnected"),
+          selectModelMessage: t("workspaceSetup.errors.selectModel"),
+        });
+      },
+      onCreateSuccess: ({ result }) => {
+        clearDraftInput("sent");
+        clearWorkspaceAttachments({ scopeKey: draftAttachmentScopeKey });
+        useWorkspaceDraftSubmissionStore.getState().clearDraftSetup({ draftId });
+        onCreated(result);
+      },
+    });
   useAgentControlCommandCenterActions({
     sourceId: `draft:${serverId}:${tabId}`,
     enabled: isPaneFocused && !isSubmitting,
@@ -509,7 +481,9 @@ export function WorkspaceDraftAgentTab({
         providers: composerState.modelSelectorProviders,
         selectedProvider: draftProvider,
         selectedModelId: composerState.effectiveModelId,
-        select: composerState.setProviderAndModelFromUser,
+        select: (provider, modelId) => {
+          composerState.setProviderAndModelFromUser(provider, modelId);
+        },
       },
       thinking: {
         options: draftThinkingOptions,
@@ -521,10 +495,7 @@ export function WorkspaceDraftAgentTab({
         selectedId: draftSelectedMode,
         select: draftSetMode,
       },
-      features: {
-        list: draftFeatures,
-        set: draftOnSetFeature,
-      },
+      optionControls: draftOptionControls ?? null,
     },
   });
   const isReadyForPendingAutoSubmit = Boolean(
@@ -600,75 +571,48 @@ export function WorkspaceDraftAgentTab({
     }),
     [composerState.agentControls, handleDropdownCloseFocus, isSubmitting],
   );
-  const dockContent = (
-    <View style={styles.contentContainer}>
-      {isSubmitting && draftAgent ? (
-        <View style={styles.streamContainer}>
-          <AgentStreamView
-            agentId={tabId}
-            serverId={serverId}
-            context={draftAgent}
-            streamItems={submittedStreamItems}
-            pendingMessageSubmissions={pendingMessageSubmissions}
-            turnPresentation={turnPresentation}
-            pendingPermissions={EMPTY_PENDING_PERMISSIONS}
-            onOpenWorkspaceFile={onOpenWorkspaceFile}
-          />
-        </View>
-      ) : (
-        <ScrollView style={styles.scrollView} contentContainerStyle={styles.configScrollContent}>
-          <View style={styles.configSection}>
-            {formErrorMessage ? (
-              <View style={styles.errorContainer}>
-                <Text style={styles.errorText}>{formErrorMessage}</Text>
-              </View>
-            ) : null}
-          </View>
-        </ScrollView>
-      )}
-    </View>
-  );
-
   return (
-    <FileDropZone style={styles.container}>
-      <ComposerDock fullscreen={isComposerFullscreen}>
-        {dockContent}
-        <View style={animatedStaticStyles.inputAreaWrapper} onLayout={onInputAreaLayout}>
-          {importPillPress && !isComposerFullscreen ? (
-            <View style={styles.importPillRow}>
-              <View style={styles.importPillContent}>
-                <ComposerImportPill onPress={importPillPress} />
-              </View>
-            </View>
-          ) : null}
-          <Composer
-            agentId={tabId}
-            serverId={serverId}
-            workspaceId={workspaceId}
-            isPaneFocused={isPaneFocused}
-            onSubmitMessage={handleCreateFromInput}
-            isSubmitLoading={isSubmitting}
-            blurOnSubmit={true}
-            textSource={draftInput.textSource}
-            onChangeText={draftInput.editText}
-            textReplacement={draftInput.textReplacement}
-            attachments={draftInput.attachments}
-            attachmentScopeKeys={attachmentScopeKeys}
-            onOpenWorkspaceAttachment={handleOpenWorkspaceAttachment}
-            onChangeAttachments={draftInput.setAttachments}
-            cwd={composerState.workingDir}
-            clearDraft={draftInput.clear}
-            editingSession={editingSession}
-            autoFocus={shouldAutoFocusWorkspaceDraftComposer({ isPaneFocused, isSubmitting })}
-            autoFocusKey={String(draftInput.attachmentFocusRequestId)}
-            onFocusInput={handleFocusInputCallback}
-            commandDraft={composerState.commandDraft}
-            agentControls={composerAgentControls}
-            isCompactLayout={isCompactComposerLayout}
-          />
+    <View style={animatedStaticStyles.inputAreaWrapper} onLayout={onInputAreaLayout}>
+      {formErrorMessage ? (
+        <View style={styles.formErrorRow}>
+          <View style={styles.formError}>
+            <Text style={styles.errorText}>{formErrorMessage}</Text>
+          </View>
         </View>
-      </ComposerDock>
-    </FileDropZone>
+      ) : null}
+      {importPillPress && !isComposerFullscreen ? (
+        <View style={styles.importPillRow}>
+          <View style={styles.importPillContent}>
+            <ComposerImportPill onPress={importPillPress} />
+          </View>
+        </View>
+      ) : null}
+      <Composer
+        agentId={tabId}
+        serverId={serverId}
+        workspaceId={workspaceId}
+        isPaneFocused={isPaneFocused}
+        onSubmitMessage={handleCreateFromInput}
+        isSubmitLoading={isSubmitting}
+        blurOnSubmit={true}
+        textSource={draftInput.textSource}
+        onChangeText={draftInput.editText}
+        textReplacement={draftInput.textReplacement}
+        attachments={draftInput.attachments}
+        attachmentScopeKeys={attachmentScopeKeys}
+        onOpenWorkspaceAttachment={handleOpenWorkspaceAttachment}
+        onChangeAttachments={draftInput.setAttachments}
+        cwd={composerState.workingDir}
+        clearDraft={draftInput.clear}
+        editingSession={editingSession}
+        autoFocus={shouldAutoFocusWorkspaceDraftComposer({ isPaneFocused, isSubmitting })}
+        autoFocusKey={String(draftInput.attachmentFocusRequestId)}
+        onFocusInput={handleFocusInputCallback}
+        commandDraft={composerState.commandDraft}
+        agentControls={composerAgentControls}
+        isCompactLayout={isCompactComposerLayout}
+      />
+    </View>
   );
 }
 
@@ -682,27 +626,10 @@ const animatedStaticStyles = RNStyleSheet.create({
 });
 
 const styles = StyleSheet.create((theme) => ({
-  container: {
-    flex: 1,
+  formErrorRow: {
     width: "100%",
-    backgroundColor: theme.colors.surface0,
-  },
-  contentContainer: {
-    flex: 1,
-  },
-  streamContainer: {
-    flex: 1,
-  },
-  scrollView: {
-    flex: 1,
-  },
-  configScrollContent: {
     paddingHorizontal: theme.spacing[4],
-    paddingTop: theme.spacing[4],
-    paddingBottom: theme.spacing[6],
-  },
-  configSection: {
-    gap: theme.spacing[3],
+    alignItems: "center",
   },
   importPillRow: {
     width: "100%",
@@ -722,8 +649,10 @@ const styles = StyleSheet.create((theme) => ({
     maxWidth: theme.contentMaxWidth,
     flexDirection: "row",
   },
-  errorContainer: {
-    marginTop: theme.spacing[2],
+  formError: {
+    width: "100%",
+    maxWidth: theme.contentMaxWidth,
+    marginBottom: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
     borderRadius: theme.borderRadius.md,
diff --git a/packages/app/src/composer/editing-session/index.test.ts b/packages/app/src/composer/editing-session/index.test.ts
index 31c3765426..7dfcb0d438 100644
--- a/packages/app/src/composer/editing-session/index.test.ts
+++ b/packages/app/src/composer/editing-session/index.test.ts
@@ -2,6 +2,31 @@ import { describe, expect, it } from "vitest";
 import { ComposerEditingSession, ComposerEditingSessions } from "./index";
 
 describe("composer editing session", () => {
+  it("appends commands to the current editor buffer and focuses it", () => {
+    const session = new ComposerEditingSession();
+    let text = "draft typed since publication";
+    let focuses = 0;
+    let selection = { start: 0, end: 0 };
+    const detach = session.attachEditor({
+      getText: () => text,
+      replaceText: (next, nextSelection) => {
+        text = next;
+        selection = nextSelection;
+      },
+      focus: () => {
+        focuses += 1;
+      },
+    });
+    session.insertCommand("/review");
+    expect(selection).toEqual({ start: text.length, end: text.length });
+    session.insertCommand("/test");
+    expect(text).toBe("draft typed since publication /review /test ");
+    expect(focuses).toBe(2);
+    expect(selection).toEqual({ start: text.length, end: text.length });
+    detach();
+    session.insertCommand("/ignored");
+    expect(text).toBe("draft typed since publication /review /test ");
+  });
   it("publishes fullscreen changes once per transition", () => {
     const session = new ComposerEditingSession();
     const changes: boolean[] = [];
diff --git a/packages/app/src/composer/editing-session/index.tsx b/packages/app/src/composer/editing-session/index.tsx
index 4776b5af3d..237b15251a 100644
--- a/packages/app/src/composer/editing-session/index.tsx
+++ b/packages/app/src/composer/editing-session/index.tsx
@@ -30,10 +30,29 @@ export interface ComposerRetainedEditor {
  */
 export class ComposerEditingSession {
   private fullscreen = false;
+  private editor: {
+    getText(): string;
+    replaceText(text: string, selection: ComposerSelection): void;
+    focus(): void;
+  } | null = null;
   private retained: ComposerRetainedEditor | null = null;
   private listeners = new Set<() => void>();
   constructor(private readonly onChange?: () => void) {}
   getFullscreen = () => this.fullscreen;
+  attachEditor(editor: NonNullable<ComposerEditingSession["editor"]>) {
+    this.editor = editor;
+    return () => {
+      if (this.editor === editor) this.editor = null;
+    };
+  }
+  insertCommand(command: string) {
+    const editor = this.editor;
+    if (!editor) return;
+    const text = editor.getText();
+    const nextText = `${text}${text && !/\s$/.test(text) ? " " : ""}${command} `;
+    editor.replaceText(nextText, { start: nextText.length, end: nextText.length });
+    editor.focus();
+  }
   /** Called by the unmounting editor; the next mount of this session takes it. */
   retainEditor(retained: ComposerRetainedEditor) {
     this.retained = retained;
diff --git a/packages/app/src/composer/halves-model.ts b/packages/app/src/composer/halves-model.ts
new file mode 100644
index 0000000000..729e78e501
--- /dev/null
+++ b/packages/app/src/composer/halves-model.ts
@@ -0,0 +1,70 @@
+import type { ComposerAgent, ComposerInput } from "@/composer/session";
+import type { ComposerModel, ComposerState } from "@/composer/model";
+
+const LOCKED_MESSAGE = "The composer is locked while the agent is being created.";
+
+function assertUnlocked(isLocked: () => boolean): void {
+  if (isLocked()) throw new Error(LOCKED_MESSAGE);
+}
+
+async function whenUnlocked(agent: ComposerAgent, command: () => Promise<void>): Promise<void> {
+  assertUnlocked(agent.isLocked);
+  await command();
+}
+
+/**
+ * The model of a draft or New workspace composer, built from the two halves its mounted
+ * composer provides. Its state belongs to the render that built it, so a change is a new model;
+ * only the prompt changes underneath it.
+ */
+export function composerModelFromHalves(input: {
+  agent: ComposerAgent;
+  input: ComposerInput;
+}): ComposerModel {
+  const { agent, input: composerInput } = input;
+  let last: ComposerState | null = null;
+  return {
+    getState() {
+      const prompt = composerInput.textSource.getSnapshot();
+      if (last && last.prompt === prompt) return last;
+      last = {
+        context: agent.context,
+        prompt,
+        attachments: composerInput.attachments,
+        provider: agent.provider,
+        model: agent.model,
+        mode: agent.mode,
+        thinking: agent.thinking,
+        options: agent.options,
+        metadata: agent.metadata,
+      };
+      return last;
+    },
+    subscribe: composerInput.textSource.subscribe,
+    setPrompt(text) {
+      assertUnlocked(composerInput.isLocked);
+      composerInput.setText(text);
+    },
+    insertText(text) {
+      assertUnlocked(composerInput.isLocked);
+      composerInput.insertText(text);
+    },
+    // Only an item inside this composer can hold it, so the user was here when they asked. Paseo
+    // has no way to name a draft from outside it and does not pull the user back to one.
+    async focus(options) {
+      if (!composerInput.isRevealed()) throw new Error("The composer is not on screen.");
+      await composerInput.focus(options);
+    },
+    changeAttachments(updater) {
+      assertUnlocked(composerInput.isLocked);
+      composerInput.changeAttachments(updater);
+    },
+    setProvider: (provider) => whenUnlocked(agent, () => agent.setProvider(provider)),
+    setModel: (modelId) => whenUnlocked(agent, () => agent.setModel(modelId)),
+    setMode: (modeId) => whenUnlocked(agent, () => agent.setMode(modeId)),
+    setThinking: (thinkingOptionId) =>
+      whenUnlocked(agent, () => agent.setThinking(thinkingOptionId)),
+    setOptions: (patch) => whenUnlocked(agent, () => agent.setOptions(patch)),
+    setMetadata: (patch) => whenUnlocked(agent, () => agent.setMetadata(patch)),
+  };
+}
diff --git a/packages/app/src/composer/index.tsx b/packages/app/src/composer/index.tsx
index b7088ddeef..4b31c4e0c6 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -31,8 +31,19 @@ import {
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import { usePanelStore } from "@/stores/panel-store";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import {
+  controlSizingForLayout,
+  TOOLBAR_CONTROL_GAP,
+  TOOLBAR_DISC_GLYPH_SIZES,
+  TOOLBAR_DISC_SIZE,
+  TOOLBAR_RINGS,
+  toolbarGlyphsFor,
+  toolbarGlyphTone,
+  type ToolbarGlyph,
+  toolbarSlot,
+} from "@/components/ui/control-geometry";
+import { usePanelStore, type MobilePanelView } from "@/stores/panel-store";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import { useShallow } from "zustand/shallow";
 import {
   ArrowUp,
@@ -71,7 +82,7 @@ import {
 } from "./input/input";
 import type { ImageAttachment, MessagePayload, TextReplacement } from "./types";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
-import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/agent-commands";
 import { encodeImages } from "@/utils/encode-images";
 import { focusWithRetries } from "@/utils/web-focus";
 import {
@@ -117,6 +128,7 @@ import {
 } from "@/attachments/service";
 import { resolveAgentControlsMode } from "@/composer/agent-controls/mode";
 import { resolveComposerInputMode, type ComposerInputMode } from "@/composer/input-mode";
+import { useIsInputLive } from "./input/use-input-live";
 import { resolveActiveSendBehavior } from "./input/state";
 import { useKeyboardActionHandler } from "@/hooks/use-keyboard-action-handler";
 import type { KeyboardActionDefinition } from "@/keyboard/keyboard-action-dispatcher";
@@ -125,6 +137,9 @@ import { submitAgentInput } from "@/composer/submit";
 import { ComposerRecall } from "@/composer/recall";
 import { createMessageSubmissionWriter } from "@/composer/submission/writer";
 import { ComposerKeyboardScopeProvider, useComposerKeyboardScope } from "@/composer/keyboard-scope";
+import { usePaneHost } from "@/panels/pane-context";
+import { OverlayDismissalScope, useDismissOverlays } from "@/components/ui/overlay-dismissal";
+import type { PaneHost } from "@/panels/panel-manifest";
 import { useAppSettings } from "@/hooks/use-settings";
 import { RenderProfile } from "@/utils/render-profiler";
 import { AfterPaintPublication } from "@/composer/after-paint-publication";
@@ -139,6 +154,10 @@ import type {
 } from "@/attachments/types";
 import type { SelectedFile } from "@/attachments/selected-file";
 import { resolveComposerAttachmentSubmitFormat } from "@/composer/attachments/submit";
+import { ComposerInputProvider, type ComposerInput } from "@/composer/session";
+import type { ComposerFocusOptions } from "@/composer/model";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+import { insertAtSelection } from "@/composer/insert-text";
 import { composerWorkspaceAttachment } from "@/composer/attachments/workspace";
 import { useWorkspaceAttachmentsForScopes } from "@/attachments/workspace-attachments-store";
 import { droppedItemsToSelectedFiles } from "@/composer/attachments/drop";
@@ -193,10 +212,6 @@ const EMPTY_ATTACHMENT_SCOPE_KEYS: readonly string[] = [];
 function noop() {}
 const noopCallback = () => {};
 
-function resolveComposerButtonIconSize(): number {
-  return isWeb ? ICON_SIZE.md : ICON_SIZE.lg;
-}
-
 function resolveIsComposerLocked(
   submitBehavior: "clear" | "preserve-and-lock",
   isSubmitLoading: boolean,
@@ -258,20 +273,22 @@ function resolveCheckoutRemoteUrl(
   return checkoutStatus?.remoteUrl ?? null;
 }
 
-function buildCancelButtonStyle(isConnected: boolean, isCancellingAgent: boolean): object[] {
+function buildCancelButtonStyle(
+  pressed: boolean,
+  isConnected: boolean,
+  isCancellingAgent: boolean,
+): object[] {
+  const pressedStyle = pressed ? styles.discPressed : undefined;
   const disabled = !isConnected || isCancellingAgent ? styles.buttonDisabled : undefined;
-  return [styles.cancelButton, disabled].filter((value): value is object => Boolean(value));
+  return [styles.cancelButton, pressedStyle, disabled].filter((value): value is object =>
+    Boolean(value),
+  );
 }
 
-function buildRealtimeVoiceButtonStyle(
-  hovered: boolean | undefined,
-  voiceButtonDisabled: boolean,
-  reserveLeadingSpace: boolean,
-): object[] {
-  const hoveredStyle = hovered ? styles.iconButtonHovered : undefined;
+function buildRealtimeVoiceButtonStyle(pressed: boolean, voiceButtonDisabled: boolean): object[] {
+  const pressedStyle = pressed ? styles.discPressed : undefined;
   const disabledStyle = voiceButtonDisabled ? styles.buttonDisabled : undefined;
-  const reserveStyle = reserveLeadingSpace ? styles.realtimeVoiceButtonCompactReserve : undefined;
-  return [styles.realtimeVoiceButton, reserveStyle, hoveredStyle, disabledStyle].filter(
+  return [styles.realtimeVoiceButton, pressedStyle, disabledStyle].filter(
     (value): value is object => Boolean(value),
   );
 }
@@ -1048,10 +1065,7 @@ function ComposerAutocompleteBinding({
       options={autocomplete.options}
       selectedIndex={autocomplete.selectedIndex}
       onSelect={onSelect}
-      isLoading={autocomplete.isLoading}
-      errorMessage={autocomplete.errorMessage}
-      loadingText={autocomplete.loadingText}
-      emptyText={autocomplete.emptyText}
+      status={autocomplete.status}
     >
       {children}
     </ComposerAutocomplete>
@@ -1080,8 +1094,8 @@ function ComposerForgeBinding({
 }
 
 interface ComposerCancelButtonProps {
-  buttonIconSize: number;
-  cancelButtonStyle: (object | undefined)[];
+  discGlyphSize: number;
+  cancelButtonStyle: (state: PressableStateCallbackType) => object[];
   handleCancelAgent: () => void;
   isConnected: boolean;
   isCancellingAgent: boolean;
@@ -1090,7 +1104,7 @@ interface ComposerCancelButtonProps {
 }
 
 function ComposerCancelButton({
-  buttonIconSize,
+  discGlyphSize,
   cancelButtonStyle,
   handleCancelAgent,
   isConnected,
@@ -1104,7 +1118,7 @@ function ComposerCancelButton({
   const icon = isCancellingAgent ? (
     <LoadingSpinner size="small" color="white" />
   ) : (
-    <Square size={buttonIconSize} color="white" fill="white" />
+    <Square size={discGlyphSize} color="white" fill="white" />
   );
   const shortcutNode = agentInterruptKeys ? <Shortcut chord={agentInterruptKeys} /> : null;
   return (
@@ -1116,7 +1130,7 @@ function ComposerCancelButton({
         accessibilityRole="button"
         style={cancelButtonStyle}
       >
-        {icon}
+        <View style={styles.cancelButtonDisc}>{icon}</View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <View style={styles.tooltipRow}>
@@ -1129,7 +1143,7 @@ function ComposerCancelButton({
 }
 
 interface ComposerVoiceModeButtonProps {
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
   handleToggleRealtimeVoice: () => void;
   isConnected: boolean;
   isVoiceSwitching: boolean;
@@ -1140,37 +1154,18 @@ interface ComposerVoiceModeButtonProps {
   t: TFunction;
 }
 
-interface ComposerRightControlsSlotProps extends ComposerVoiceModeButtonProps {
+/** Whether voice mode can take the trailing disc; MessageInput decides when it does. */
+function offersVoiceMode(input: {
   isVoiceModeForAgent: boolean;
   hasAgent: boolean;
   isAgentRunning: boolean;
-  hasSendableContent: boolean;
-  isCompact: boolean;
   showVoice: boolean;
-}
-
-function ComposerRightControlsSlot({
-  isVoiceModeForAgent,
-  hasAgent,
-  isAgentRunning,
-  hasSendableContent,
-  isCompact,
-  showVoice,
-  ...voiceProps
-}: ComposerRightControlsSlotProps) {
-  const hideVoiceForCompactInput = isCompact && hasSendableContent;
-  const showVoiceModeButton =
-    showVoice && !isVoiceModeForAgent && hasAgent && !isAgentRunning && !hideVoiceForCompactInput;
-  if (!showVoiceModeButton) return null;
-  return (
-    <View style={styles.rightControls}>
-      <ComposerVoiceModeButton {...voiceProps} />
-    </View>
-  );
+}): boolean {
+  return input.showVoice && !input.isVoiceModeForAgent && input.hasAgent && !input.isAgentRunning;
 }
 
 function ComposerVoiceModeButton({
-  buttonIconSize,
+  glyph,
   handleToggleRealtimeVoice,
   isConnected,
   isVoiceSwitching,
@@ -1181,13 +1176,25 @@ function ComposerVoiceModeButton({
   const shortcutNode = voiceToggleKeys ? <Shortcut chord={voiceToggleKeys} /> : null;
   const renderTriggerContent = useCallback(
     ({ hovered }: PressableStateCallbackType & { hovered?: boolean }) => {
-      if (isVoiceSwitching) {
-        return <LoadingSpinner size="small" color="white" />;
-      }
-      const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
-      return <ThemedAudioLines size={buttonIconSize} uniProps={colorMapping} />;
+      const colorMapping =
+        toolbarGlyphTone(glyph, Boolean(hovered)) === "foreground"
+          ? iconForegroundMapping
+          : iconForegroundMutedMapping;
+      return (
+        <View style={styles.voiceModeDisc}>
+          {isVoiceSwitching ? (
+            <LoadingSpinner size="small" color="white" />
+          ) : (
+            <ThemedAudioLines
+              size={glyph.size}
+              strokeWidth={glyph.strokeWidth}
+              uniProps={colorMapping}
+            />
+          )}
+        </View>
+      );
     },
-    [buttonIconSize, isVoiceSwitching],
+    [glyph, isVoiceSwitching],
   );
   return (
     <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
@@ -1210,6 +1217,24 @@ function ComposerVoiceModeButton({
   );
 }
 
+// A plugin modal can refuse to close; the request then tries the cursor anyway and settles.
+const OVERLAY_CLOSE_TIMEOUT_MS = 1_000;
+
+function closedWithin(closed: Promise<void>, timeoutMs: number): Promise<void> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<void>((resolve) => {
+    timeout = setTimeout(resolve, timeoutMs);
+  });
+  return Promise.race([closed, expired]).finally(() => clearTimeout(timeout));
+}
+
+/** Only the agent list can cover a screen outside a workspace: the Explorer lives in the workspace. */
+function isMobilePanelCoveringHost(target: MobilePanelView, host: PaneHost | null): boolean {
+  if (target === "agent-list") return true;
+  if (host === null) return false;
+  return target !== (host === "explorer" ? "file-explorer" : "agent");
+}
+
 export function Composer({ isPaneFocused, ...props }: ComposerProps) {
   // A compact overlay panel (agent list, explorer) covers the pane without taking its
   // focus. The composer gives up input from the moment the user asks for the panel,
@@ -1217,16 +1242,21 @@ export function Composer({ isPaneFocused, ...props }: ComposerProps) {
   // Pane focus stays put, so the keyboard the panel dismisses is a blur in the
   // user's own pane: closing the panel does not bring focus back.
   const isCompact = useIsCompactFormFactor();
-  const overlayPanelRequested = usePanelStore((state) => state.mobilePanel.target !== "agent");
+  const paneHost = usePaneHost();
+  const overlayPanelRequested = usePanelStore((state) =>
+    isMobilePanelCoveringHost(state.mobilePanel.target, paneHost),
+  );
   const coveredByOverlayPanel = isCompact && overlayPanelRequested;
   return (
     <ComposerKeyboardScopeProvider
       isPaneFocused={isPaneFocused}
       isActiveComposer={isPaneFocused && !coveredByOverlayPanel}
     >
-      <RenderProfile id="ComposerContent">
-        <ComposerContent {...props} />
-      </RenderProfile>
+      <OverlayDismissalScope>
+        <RenderProfile id="ComposerContent">
+          <ComposerContent {...props} />
+        </RenderProfile>
+      </OverlayDismissalScope>
     </ComposerKeyboardScopeProvider>
   );
 }
@@ -1281,7 +1311,6 @@ function ComposerContentImpl({
 }: ComposerContentProps) {
   const mode = resolveComposerInputMode(inputMode);
   const { t } = useTranslation();
-  const buttonIconSize = resolveComposerButtonIconSize();
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
   const agentDirectoryStatus = useHostRuntimeAgentDirectoryStatus(serverId);
@@ -1310,15 +1339,13 @@ function ComposerContentImpl({
 
   const isCompactFormFactor = useIsCompactFormFactor();
   const isCompactLayout = resolveCompactLayout(isCompactLayoutOverride, isCompactFormFactor);
+  const controlSizing = controlSizingForLayout(isCompactFormFactor);
+  const toolbarGlyph = toolbarGlyphsFor(controlSizing).icon;
+  const discGlyphSize = TOOLBAR_DISC_GLYPH_SIZES[controlSizing];
   const isDesktopWebBreakpoint = resolveIsDesktopWebBreakpoint(isCompactFormFactor);
-  const hasFinePointer = useHasFinePointer();
+  const { finePointer: hasFinePointer } = usePointerCapabilities();
   const isDesktopLayout = resolveIsDesktopWebBreakpoint(isCompactLayout);
   const messagePlaceholder = resolveMessagePlaceholder(inputMode, isDesktopLayout, t, placeholder);
-  const hasText = useSyncExternalStore(
-    textSource.subscribe,
-    () => textSource.getSnapshot().trim().length > 0,
-    () => textSource.getSnapshot().trim().length > 0,
-  );
   const setUserInput = onChangeText;
   const workspaceAttachments = useWorkspaceAttachmentsForScopes(attachmentScopeKeys);
   const {
@@ -1419,6 +1446,95 @@ function ComposerContentImpl({
     [onChangeText],
   );
 
+  const insertUserInput = useCallback(
+    (text: string) => {
+      const input = messageInputRef.current;
+      if (!input) {
+        onChangeText(textSource.getSnapshot() + text);
+        return;
+      }
+      const inserted = insertAtSelection(input.getInputSnapshot(), text);
+      input.replaceText(inserted.text, inserted.selection);
+    },
+    [onChangeText, textSource],
+  );
+  const isInputLive = useIsInputLive(messageInputRef);
+  const isPanelActive = useRetainedPanelActive();
+  const { isActiveComposer } = useComposerKeyboardScope();
+  const inputRevealed = isPanelActive && isActiveComposer;
+  const isActiveComposerRef = useRef(isActiveComposer);
+  isActiveComposerRef.current = isActiveComposer;
+  const isInputRevealed = useCallback(
+    () => isInputLive() && isActiveComposerRef.current,
+    [isInputLive],
+  );
+  const dismissOverlays = useDismissOverlays();
+  const latestFocusRef = useRef<Promise<void> | null>(null);
+  const takeInputFocus = useCallback(
+    (options?: ComposerFocusOptions) => {
+      const isFocused = () => messageInputRef.current?.isFocused() ?? false;
+      const place = () => {
+        messageInputRef.current?.focus();
+        if (options?.selection) messageInputRef.current?.setSelection(options.selection);
+      };
+      // The sheets, menus and modals this composer opened would otherwise cover the cursor, or take
+      // focus back as they close.
+      const request: Promise<void> = closedWithin(dismissOverlays(), OVERLAY_CLOSE_TIMEOUT_MS).then(
+        () => {
+          // A newer request decides where the cursor goes, and this one ends with it.
+          const latest = latestFocusRef.current;
+          if (latest && latest !== request) return latest;
+          if (isNative) {
+            place();
+            // A native input refuses focus without saying so, such as while dictation holds it.
+            if (!isFocused()) throw new Error("The composer input could not take focus.");
+            return;
+          }
+          return new Promise<void>((resolve, reject) => {
+            focusWithRetries({
+              focus: place,
+              isFocused,
+              onSuccess: resolve,
+              onTimeout: () => reject(new Error("The composer input could not take focus.")),
+            });
+          });
+        },
+      );
+      latestFocusRef.current = request;
+      return request;
+    },
+    [dismissOverlays],
+  );
+  const isComposerLockedRef = useRef(isComposerLocked);
+  isComposerLockedRef.current = isComposerLocked;
+  const composerInput = useMemo<ComposerInput>(
+    () => ({
+      locked: isComposerLocked,
+      isLocked: () => isComposerLockedRef.current,
+      isLive: isInputLive,
+      revealed: inputRevealed,
+      isRevealed: isInputRevealed,
+      focus: takeInputFocus,
+      textSource,
+      setText: replaceUserInput,
+      insertText: insertUserInput,
+      attachments,
+      changeAttachments: setSelectedAttachments,
+    }),
+    [
+      attachments,
+      inputRevealed,
+      insertUserInput,
+      isComposerLocked,
+      isInputLive,
+      isInputRevealed,
+      replaceUserInput,
+      setSelectedAttachments,
+      takeInputFocus,
+      textSource,
+    ],
+  );
+
   const runClientSlashCommand = useCallback(
     (command: ClientSlashCommand): boolean => {
       if (command.execution !== "immediate" || !onClientSlashCommand) {
@@ -1993,8 +2109,6 @@ function ComposerContentImpl({
     ],
   );
 
-  const hasSendableContent = hasText || selectedAttachments.length > 0;
-
   // An open autocomplete owns the arrows; otherwise they may recall sent messages.
   const handleCommandKeyPress = useCallback(
     (event: ComposerKeyPressEvent) => {
@@ -2010,8 +2124,9 @@ function ComposerContentImpl({
     [agentId, recall, replaceUserInput, serverId],
   );
 
-  const cancelButtonStyle = useMemo(
-    () => buildCancelButtonStyle(isConnected, isCancellingAgent),
+  const cancelButtonStyle = useCallback(
+    (state: PressableStateCallbackType) =>
+      buildCancelButtonStyle(state.pressed, isConnected, isCancellingAgent),
     [isConnected, isCancellingAgent],
   );
 
@@ -2019,14 +2134,14 @@ function ComposerContentImpl({
   const voiceButtonDisabled = !isConnected || isVoiceSwitching;
   const realtimeVoiceButtonStyle = useCallback(
     (state: PressableStateCallbackType & { hovered?: boolean }) =>
-      buildRealtimeVoiceButtonStyle(state.hovered, voiceButtonDisabled, isCompactLayout),
-    [isCompactLayout, voiceButtonDisabled],
+      buildRealtimeVoiceButtonStyle(state.pressed, voiceButtonDisabled),
+    [voiceButtonDisabled],
   );
 
   const activeActionContent = useMemo(
     () => (
       <ComposerCancelButton
-        buttonIconSize={buttonIconSize}
+        discGlyphSize={discGlyphSize}
         cancelButtonStyle={cancelButtonStyle}
         handleCancelAgent={handleCancelAgent}
         isConnected={isConnected}
@@ -2037,7 +2152,7 @@ function ComposerContentImpl({
     ),
     [
       agentInterruptKeys,
-      buttonIconSize,
+      discGlyphSize,
       cancelButtonStyle,
       handleCancelAgent,
       isCancellingAgent,
@@ -2046,32 +2161,32 @@ function ComposerContentImpl({
     ],
   );
 
-  const rightContent = useMemo(
-    () => (
-      <ComposerRightControlsSlot
-        isVoiceModeForAgent={isVoiceModeForAgent}
-        hasAgent={hasAgent}
-        isAgentRunning={isAgentRunning}
-        hasSendableContent={hasSendableContent}
-        isCompact={isCompactLayout}
-        showVoice={mode.showVoice}
-        buttonIconSize={buttonIconSize}
-        handleToggleRealtimeVoice={handleToggleRealtimeVoice}
-        isConnected={isConnected}
-        isVoiceSwitching={isVoiceSwitching}
-        realtimeVoiceButtonStyle={realtimeVoiceButtonStyle}
-        voiceToggleKeys={voiceToggleKeys}
-        t={t}
-      />
-    ),
+  const voiceModeContent = useMemo(
+    () =>
+      offersVoiceMode({
+        isVoiceModeForAgent,
+        hasAgent,
+        isAgentRunning,
+        showVoice: mode.showVoice,
+      }) ? (
+        <View style={styles.rightControls}>
+          <ComposerVoiceModeButton
+            glyph={toolbarGlyph}
+            handleToggleRealtimeVoice={handleToggleRealtimeVoice}
+            isConnected={isConnected}
+            isVoiceSwitching={isVoiceSwitching}
+            realtimeVoiceButtonStyle={realtimeVoiceButtonStyle}
+            voiceToggleKeys={voiceToggleKeys}
+            t={t}
+          />
+        </View>
+      ) : null,
     [
-      buttonIconSize,
+      toolbarGlyph,
       handleToggleRealtimeVoice,
       hasAgent,
-      hasSendableContent,
       isAgentRunning,
       isConnected,
-      isCompactLayout,
       isVoiceModeForAgent,
       isVoiceSwitching,
       mode.showVoice,
@@ -2081,7 +2196,6 @@ function ComposerContentImpl({
     ],
   );
 
-  const contextWindowMeterGlyphSize = isCompactLayout ? ICON_SIZE.md : buttonIconSize;
   const beforeVoiceContent = useMemo(
     () =>
       hasAgent ? (
@@ -2092,7 +2206,7 @@ function ComposerContentImpl({
             maxTokens={agentState.contextWindowMaxTokens}
             usedTokens={agentState.contextWindowUsedTokens}
             totalCostUsd={agentState.totalCostUsd}
-            glyphSize={contextWindowMeterGlyphSize}
+            toolbarRing={TOOLBAR_RINGS[controlSizing]}
           />
         </View>
       ) : null,
@@ -2103,7 +2217,7 @@ function ComposerContentImpl({
       agentState.contextWindowMaxTokens,
       agentState.contextWindowUsedTokens,
       agentState.totalCostUsd,
-      contextWindowMeterGlyphSize,
+      controlSizing,
     ],
   );
 
@@ -2223,18 +2337,27 @@ function ComposerContentImpl({
     [attachments, setSelectedAttachments, setGithubSearchQuery, setIsGithubPickerOpen],
   );
 
-  const leftContent = useMemo(
-    () =>
-      renderLeftContent({
-        agentControls,
-        agentId,
-        serverId,
-        focusInput,
-        isCompactLayout,
-        showAgentControls: mode.showAgentControls,
-      }),
-    [agentControls, agentId, focusInput, isCompactLayout, mode.showAgentControls, serverId],
-  );
+  const leftContent = useMemo(() => {
+    const controls = renderLeftContent({
+      agentControls,
+      agentId,
+      serverId,
+      focusInput,
+      isCompactLayout,
+      showAgentControls: mode.showAgentControls,
+    });
+    return controls ? (
+      <ComposerInputProvider value={composerInput}>{controls}</ComposerInputProvider>
+    ) : null;
+  }, [
+    agentControls,
+    agentId,
+    composerInput,
+    focusInput,
+    isCompactLayout,
+    mode.showAgentControls,
+    serverId,
+  ]);
 
   const handleAttachButtonRef = useCallback((node: View | null) => {
     attachButtonRef.current = node;
@@ -2489,7 +2612,7 @@ function ComposerContentImpl({
                   disabled={isSubmitLoading}
                   leftContent={leftContent}
                   beforeVoiceContent={beforeVoiceContent}
-                  rightContent={rightContent}
+                  voiceModeContent={voiceModeContent}
                   activeActionContent={activeActionContent}
                   voiceServerId={serverId}
                   voiceAgentId={agentId}
@@ -2568,7 +2691,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     width: "100%",
     overflow: "visible",
     paddingHorizontal: theme.spacing[4],
-    paddingBottom: theme.spacing[4],
   },
   inputAreaLocked: {
     opacity: 0.6,
@@ -2578,7 +2700,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     minHeight: 0,
     alignItems: "stretch",
     paddingHorizontal: 0,
-    paddingBottom: 0,
   },
   fullscreenFill: {
     flex: 1,
@@ -2598,42 +2719,49 @@ const styles = StyleSheet.create((theme: Theme) => ({
     gap: theme.spacing[3],
   },
   cancelButton: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(),
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  cancelButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.palette.red[600],
     alignItems: "center",
     justifyContent: "center",
-    marginLeft: theme.spacing[1],
   },
   rightControls: {
     flexDirection: "row",
     alignItems: "center",
-    gap: theme.spacing[1],
+    gap: TOOLBAR_CONTROL_GAP,
   },
   contextWindowMeterSlot: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(),
     flexShrink: 0,
     alignItems: "center",
     justifyContent: "center",
   },
-  realtimeVoiceButton: {
-    width: 28,
-    height: 28,
+  voiceModeDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.surface3,
     alignItems: "center",
     justifyContent: "center",
   },
-  realtimeVoiceButtonCompactReserve: {
-    marginLeft: theme.spacing[1],
+  realtimeVoiceButton: {
+    ...toolbarSlot(),
+    borderRadius: theme.borderRadius.full,
+    alignItems: "center",
+    justifyContent: "center",
   },
   realtimeVoiceButtonActive: {
     backgroundColor: theme.colors.palette.green[600],
     borderColor: theme.colors.palette.green[800],
   },
-  iconButtonHovered: {
-    backgroundColor: theme.colors.surface2,
+  discPressed: {
+    opacity: 0.7,
   },
   attachmentTray: {
     flexDirection: "row",
diff --git a/packages/app/src/composer/input/fullscreen-exit.browser.test.tsx b/packages/app/src/composer/input/fullscreen-exit.browser.test.tsx
new file mode 100644
index 0000000000..c9c62d85be
--- /dev/null
+++ b/packages/app/src/composer/input/fullscreen-exit.browser.test.tsx
@@ -0,0 +1,28 @@
+import React from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { dispatchTopOverlayKeyDown } from "@/keyboard";
+import { useComposerFullscreenExit } from "./fullscreen-exit";
+
+it("the native entry claims Escape until fullscreen closes", () => {
+  let exits = 0;
+  function Harness({ active }: { active: boolean }) {
+    useComposerFullscreenExit(active, () => exits++);
+    return null;
+  }
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    flushSync(() => root.render(<Harness active />));
+    expect(dispatchTopOverlayKeyDown(new KeyboardEvent("keydown", { key: "Escape" }))).toBe(true);
+    expect(exits).toBe(1);
+    flushSync(() => root.render(<Harness active={false} />));
+    expect(dispatchTopOverlayKeyDown(new KeyboardEvent("keydown", { key: "Escape" }))).toBe(false);
+    expect(exits).toBe(1);
+  } finally {
+    root.unmount();
+    container.remove();
+  }
+});
diff --git a/packages/app/src/composer/input/fullscreen-exit.ts b/packages/app/src/composer/input/fullscreen-exit.ts
index b76eeed5fc..b0fbe9e2a5 100644
--- a/packages/app/src/composer/input/fullscreen-exit.ts
+++ b/packages/app/src/composer/input/fullscreen-exit.ts
@@ -1,4 +1,6 @@
-import { useOverlayLayer, useWebOverlayRegistration } from "@/lib/overlay-root";
+import { useComposerHardwareBackExit } from "./hardware-back-exit";
+import { useOverlayRegistration } from "@/keyboard";
+import { useOverlayLayer } from "@/lib/overlay-root";
 
 /**
  * Escape leaves fullscreen before app shortcuts see it. The registration only claims
@@ -8,8 +10,10 @@ export function useComposerFullscreenExit(
   active: boolean,
   onExit: () => void,
 ): ((node: unknown) => void) | undefined {
+  useComposerHardwareBackExit(active, onExit);
   const layer = useOverlayLayer("modal");
-  return useWebOverlayRegistration({
+  return useOverlayRegistration({
+    keys: ["Escape"],
     active,
     layer,
     manageFocus: false,
diff --git a/packages/app/src/composer/input/fullscreen-exit.native.ts b/packages/app/src/composer/input/hardware-back-exit.android.ts
similarity index 72%
rename from packages/app/src/composer/input/fullscreen-exit.native.ts
rename to packages/app/src/composer/input/hardware-back-exit.android.ts
index c2344d50b0..96eec89bd6 100644
--- a/packages/app/src/composer/input/fullscreen-exit.native.ts
+++ b/packages/app/src/composer/input/hardware-back-exit.android.ts
@@ -2,10 +2,7 @@ import { useEffect } from "react";
 import { BackHandler } from "react-native";
 
 /** The hardware back button leaves fullscreen instead of the screen. */
-export function useComposerFullscreenExit(
-  active: boolean,
-  onExit: () => void,
-): ((node: unknown) => void) | undefined {
+export function useComposerHardwareBackExit(active: boolean, onExit: () => void): void {
   useEffect(() => {
     if (!active) return;
     const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
@@ -14,5 +11,4 @@ export function useComposerFullscreenExit(
     });
     return () => subscription.remove();
   }, [active, onExit]);
-  return undefined;
 }
diff --git a/packages/app/src/composer/input/hardware-back-exit.ts b/packages/app/src/composer/input/hardware-back-exit.ts
new file mode 100644
index 0000000000..0fefbbad72
--- /dev/null
+++ b/packages/app/src/composer/input/hardware-back-exit.ts
@@ -0,0 +1 @@
+export function useComposerHardwareBackExit(_active: boolean, _onExit: () => void): void {}
diff --git a/packages/app/src/composer/input/input.tsx b/packages/app/src/composer/input/input.tsx
index 16acede7e5..a3ae8652ae 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -1,3 +1,4 @@
+import { useKeyboardFocusSurface } from "@/keyboard";
 import type { SendShortcut } from "@/hooks/use-settings";
 import {
   useComposerEditingSession,
@@ -7,6 +8,7 @@ import {
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import {
   View,
+  Platform,
   Text,
   useWindowDimensions,
   NativeSyntheticEvent,
@@ -26,11 +28,31 @@ import {
 } from "react";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
+import type { Theme } from "@/styles/theme";
+import {
+  controlSizingForLayout,
+  TOOLBAR_CONTROL_GAP,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_DISC_GLYPH_SIZES,
+  TOOLBAR_DISC_SIZE,
+  toolbarGlyphsFor,
+  toolbarGlyphTone,
+  type ToolbarGlyph,
+  toolbarSlot,
+} from "@/components/ui/control-geometry";
+import { bySizing } from "@/components/ui/control-sizing";
+import {
+  COMPOSER_PADDING_BOTTOM,
+  COMPOSER_PADDING_HORIZONTAL,
+  COMPOSER_CORNER_RADIUS,
+  COMPOSER_PADDING_TOP,
+  composerToolbarOverhang,
+  resolveComposerLeadingEdge,
+} from "@/composer/input/toolbar-rails";
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
 import { useDictation } from "@/hooks/use-dictation";
-import { hasFinePointer } from "@/hooks/use-fine-pointer";
+import { hasFinePointer } from "@/hooks/pointer-capabilities";
 import { DictationOverlay } from "@/components/dictation-controls";
 import { RealtimeVoiceOverlay } from "@/components/realtime-voice-overlay";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -66,6 +88,7 @@ import { RenderProfile } from "@/utils/render-profiler";
 import { useComposerHeight } from "./height";
 import { ComposerInputPresentation } from "./presentation";
 import { resolveComposerInputMode, type ComposerInputMode } from "@/composer/input-mode";
+import { pasteLinkedClipboardText } from "@/composer/pasted-text";
 import type { NativePastedFile } from "@/composer/native-pasted-image";
 import {
   EditingTextInput,
@@ -162,8 +185,8 @@ export interface MessageInputProps {
   leftContent?: React.ReactNode;
   /** Content to render on the right side before the voice button (e.g., context window meter) */
   beforeVoiceContent?: React.ReactNode;
-  /** Auxiliary content to render on the right side after the voice button. */
-  rightContent?: React.ReactNode;
+  /** The realtime voice mode button, which takes the trailing disc while there is nothing to send. */
+  voiceModeContent?: React.ReactNode;
   /** Primary action to render when the agent is active and the composer has no sendable content. */
   activeActionContent?: React.ReactNode;
   voiceServerId?: string;
@@ -202,9 +225,12 @@ export interface MessageInputProps {
 export interface MessageInputRef {
   focus: () => void;
   blur: () => void;
+  isFocused: () => boolean;
   getText: () => string;
   getInputSnapshot: () => ComposerInputSnapshot;
   replaceText: (text: string, selection?: { start: number; end: number }) => void;
+  /** Clamped to the text the input holds. */
+  setSelection: (selection: { start: number; end: number }) => void;
   runKeyboardAction: (action: MessageInputKeyboardActionKind) => boolean;
   /**
    * Web-only: return the underlying DOM element for focus assertions/retries.
@@ -244,19 +270,28 @@ interface TextAreaHandle {
   };
 }
 
+function glyphColorMapping(glyph: ToolbarGlyph, hovered: boolean) {
+  return toolbarGlyphTone(glyph, hovered) === "foreground"
+    ? iconForegroundMapping
+    : iconForegroundMutedMapping;
+}
+
 function AttachButtonIcon({
   hovered,
   onAttachButtonRef,
-  buttonIconSize,
+  glyph,
 }: {
   hovered: boolean;
   onAttachButtonRef: ((node: View | null) => void) | undefined;
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
 }) {
-  const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
   return (
     <View ref={onAttachButtonRef} collapsable={false} style={styles.attachButtonAnchor}>
-      <ThemedPlus size={buttonIconSize} uniProps={colorMapping} />
+      <ThemedPlus
+        size={glyph.size}
+        strokeWidth={glyph.strokeWidth}
+        uniProps={glyphColorMapping(glyph, hovered)}
+      />
     </View>
   );
 }
@@ -334,21 +369,25 @@ function VoiceButtonIcon({
   hovered,
   isDictating,
   isMutedRealtime,
-  buttonIconSize,
+  glyph,
+  discGlyphSize,
 }: {
   hovered: boolean;
   isDictating: boolean;
   isMutedRealtime: boolean;
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
+  discGlyphSize: number;
 }) {
   if (isDictating) {
-    return <Square size={buttonIconSize} color="white" fill="white" />;
+    return (
+      <View style={styles.voiceButtonRecordingDisc}>
+        <Square size={discGlyphSize} color="white" fill="white" />
+      </View>
+    );
   }
-  const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
-  if (isMutedRealtime) {
-    return <ThemedMicOff size={buttonIconSize} uniProps={colorMapping} />;
-  }
-  return <ThemedMic size={buttonIconSize} uniProps={colorMapping} />;
+  const colorMapping = glyphColorMapping(glyph, hovered);
+  const Icon = isMutedRealtime ? ThemedMicOff : ThemedMic;
+  return <Icon size={glyph.size} strokeWidth={glyph.strokeWidth} uniProps={colorMapping} />;
 }
 
 type ShortcutChord = NonNullable<React.ComponentProps<typeof Shortcut>["chord"]>;
@@ -387,12 +426,12 @@ function SendButtonContent({
   isSubmitLoading,
   submitIcon,
   submitLabel,
-  buttonIconSize,
+  glyph,
 }: {
   isSubmitLoading: boolean;
   submitIcon: "arrow" | "return";
   submitLabel: string | undefined;
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
 }) {
   if (isSubmitLoading) {
     return <ThemedLoadingSpinner size="small" uniProps={iconAccentForegroundMapping} />;
@@ -401,9 +440,21 @@ function SendButtonContent({
     return <Text style={styles.sendButtonLabel}>{submitLabel}</Text>;
   }
   if (submitIcon === "return") {
-    return <ThemedCornerDownLeft size={buttonIconSize} uniProps={iconAccentForegroundMapping} />;
+    return (
+      <ThemedCornerDownLeft
+        size={glyph.size}
+        strokeWidth={glyph.strokeWidth}
+        uniProps={iconAccentForegroundMapping}
+      />
+    );
   }
-  return <ThemedArrowUp size={buttonIconSize} uniProps={iconAccentForegroundMapping} />;
+  return (
+    <ThemedArrowUp
+      size={glyph.size}
+      strokeWidth={glyph.strokeWidth}
+      uniProps={iconAccentForegroundMapping}
+    />
+  );
 }
 
 interface DesktopKeyPressContext {
@@ -466,7 +517,7 @@ function getTextInputNativeElement(current: ComposerTextInputHandle | null): HTM
   return native instanceof HTMLElement ? native : null;
 }
 
-interface PasteImagesEffectArgs {
+interface PasteEffectArgs {
   textarea: HTMLElement | null;
   isConnected: boolean;
   disabled: boolean;
@@ -475,7 +526,7 @@ interface PasteImagesEffectArgs {
   onAddImages: ((images: ImageAttachment[]) => void) | undefined;
 }
 
-function usePasteImagesEffect(args: PasteImagesEffectArgs): void {
+function usePasteEffect(args: PasteEffectArgs): void {
   const {
     textarea,
     isConnected,
@@ -486,16 +537,20 @@ function usePasteImagesEffect(args: PasteImagesEffectArgs): void {
   } = args;
 
   useEffect(() => {
-    if (!isWeb || !onAddImages) return;
+    if (!isWeb) return;
 
     if (!textarea) return;
 
     let disposed = false;
     const handlePaste = (event: ClipboardEvent) => {
-      if (!isConnected || disabled || isDictating || isRealtimeVoiceForCurrentAgent) return;
+      if (disabled || isDictating || isRealtimeVoiceForCurrentAgent) return;
 
       const imageFiles = collectImageFilesFromClipboardData(event.clipboardData);
-      if (imageFiles.length === 0) return;
+      if (imageFiles.length === 0) {
+        if (pasteLinkedClipboardText(textarea, event.clipboardData)) event.preventDefault();
+        return;
+      }
+      if (!isConnected || !onAddImages) return;
 
       event.preventDefault();
 
@@ -796,7 +851,7 @@ function SendButtonTooltip({
   submitIcon,
   submitLabel,
   submitButtonTestID,
-  buttonIconSize,
+  glyph,
   sendKeys,
   sendTooltipLabel,
 }: {
@@ -813,7 +868,7 @@ function SendButtonTooltip({
   submitIcon: "arrow" | "return";
   submitLabel: string | undefined;
   submitButtonTestID: string | undefined;
-  buttonIconSize: number;
+  glyph: ToolbarGlyph;
   sendKeys: ShortcutChord | null | undefined;
   sendTooltipLabel: string;
 }) {
@@ -830,12 +885,14 @@ function SendButtonTooltip({
         testID={submitButtonTestID}
         style={sendButtonCombinedStyle}
       >
-        <SendButtonContent
-          isSubmitLoading={isSubmitLoading}
-          submitIcon={submitIcon}
-          submitLabel={submitLabel}
-          buttonIconSize={buttonIconSize}
-        />
+        <View style={submitLabel ? styles.sendButtonDiscLabeled : styles.sendButtonDisc}>
+          <SendButtonContent
+            isSubmitLoading={isSubmitLoading}
+            submitIcon={submitIcon}
+            submitLabel={submitLabel}
+            glyph={glyph}
+          />
+        </View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <SendTooltipBody label={sendTooltipLabel} sendKeys={sendKeys} />
@@ -844,7 +901,7 @@ function SendButtonTooltip({
   );
 }
 
-type PrimaryActionKind = "send" | "active" | "none";
+type PrimaryActionKind = "send" | "active" | "voiceMode" | "none";
 
 function hasSendableComposerContent(input: {
   hasText: boolean;
@@ -859,22 +916,26 @@ function resolvePrimaryActionKind(input: {
   allowEmptySubmit: boolean;
   isAgentRunning: boolean;
   isSubmitLoading: boolean;
+  offersVoiceMode: boolean;
 }): PrimaryActionKind {
   if (input.hasSendableContent || input.allowEmptySubmit) return "send";
   if (input.isAgentRunning) return "active";
   if (input.isSubmitLoading) return "send";
-  return "none";
+  return input.offersVoiceMode ? "voiceMode" : "none";
 }
 
 function PrimaryAction({
   kind,
   activeActionContent,
+  voiceModeContent,
   ...sendButtonProps
 }: {
   kind: PrimaryActionKind;
   activeActionContent: React.ReactNode;
+  voiceModeContent: React.ReactNode;
 } & React.ComponentProps<typeof SendButtonTooltip>) {
   if (kind === "active") return activeActionContent;
+  if (kind === "voiceMode") return voiceModeContent;
   if (kind === "send") return <SendButtonTooltip {...sendButtonProps} />;
   return null;
 }
@@ -1126,7 +1187,7 @@ interface ResolvedMessageInputProps {
   disabled: boolean;
   leftContent: React.ReactNode;
   beforeVoiceContent: React.ReactNode;
-  rightContent: React.ReactNode;
+  voiceModeContent: React.ReactNode;
   activeActionContent: React.ReactNode;
   voiceServerId: string | undefined;
   voiceAgentId: string | undefined;
@@ -1174,7 +1235,7 @@ function resolveMessageInputProps(props: MessageInputProps): ResolvedMessageInpu
     disabled: props.disabled ?? false,
     leftContent: props.leftContent,
     beforeVoiceContent: props.beforeVoiceContent,
-    rightContent: props.rightContent,
+    voiceModeContent: props.voiceModeContent,
     activeActionContent: props.activeActionContent,
     voiceServerId: props.voiceServerId,
     voiceAgentId: props.voiceAgentId,
@@ -1202,8 +1263,12 @@ function extractErrorMessage(error: unknown): string | null {
   return null;
 }
 
+/**
+ * Send that stands in for the trailing disc, in fullscreen or while there is nothing to send, is
+ * disabled until there is content.
+ */
 function resolvePresentationSendDisabled(input: {
-  fullscreen: boolean;
+  standsIn: boolean;
   disabled: boolean;
   hasText: boolean;
   attachments: ComposerAttachment[];
@@ -1211,7 +1276,7 @@ function resolvePresentationSendDisabled(input: {
   allowEmpty: boolean;
 }): boolean {
   return (
-    input.disabled || (input.fullscreen && !input.allowEmpty && !hasSendableComposerContent(input))
+    input.disabled || (input.standsIn && !input.allowEmpty && !hasSendableComposerContent(input))
   );
 }
 
@@ -1252,7 +1317,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       disabled,
       leftContent,
       beforeVoiceContent,
-      rightContent,
+      voiceModeContent,
       activeActionContent,
       voiceServerId,
       voiceAgentId,
@@ -1281,13 +1346,16 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     const isFullscreen = useComposerFullscreen(editingSession);
     const [renderedLines, setRenderedLines] = useState(1);
     const maxInputHeight = resolveMaxInputHeight(windowHeight, isCompact);
-    const buttonIconSize = isWeb ? ICON_SIZE.md : ICON_SIZE.lg;
+    const controlSizing = controlSizingForLayout(isCompact);
+    const toolbarGlyph = toolbarGlyphsFor(controlSizing).icon;
+    const discGlyphSize = TOOLBAR_DISC_GLYPH_SIZES[controlSizing];
     const toast = useToast();
     const voice = useVoiceOptional();
     const voiceMuteToggleKeys = useShortcutKeys("voice-mute-toggle");
     const dictationToggleKeys = useShortcutKeys("dictation-toggle");
     const focusInputKeys = useShortcutKeys("focus-message-input");
     const [isInputFocused, setIsInputFocused] = useState(false);
+    useKeyboardFocusSurface("message-input", isInputFocused && isPaneFocused);
     // Web text is DOM-owned between deferred draft publications. The action button only needs
     // this boundary, so publish empty/non-empty transitions without rerendering for every key.
     const initialHasLiveText = value.trim().length > 0;
@@ -1407,10 +1475,21 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       [onChangeText, updateComposerHeightForText, updateLiveTextPresence],
     );
 
+    useLayoutEffect(
+      () =>
+        editingSession.attachEditor({
+          getText: () => textInputRef.current?.getText() ?? valueRef.current,
+          replaceText,
+          focus: () => textInputRef.current?.focus(),
+        }),
+      [editingSession, replaceText],
+    );
+
     useImperativeHandle(ref, () => ({
       focus: () => {
         textInputRef.current?.focus();
       },
+      isFocused: () => textInputRef.current?.isFocused() ?? false,
       blur: () => {
         textInputRef.current?.blur();
       },
@@ -1418,6 +1497,12 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       getInputSnapshot: () =>
         getComposerInputSnapshot(textInputRef.current, valueRef.current, selectionRef.current),
       replaceText,
+      setSelection: (selection) => {
+        const text = textInputRef.current?.getText() ?? valueRef.current;
+        const clamped = resolveRetainedSelection(selection, text.length);
+        selectionRef.current = clamped;
+        textInputRef.current?.setSelection(clamped);
+      },
       runKeyboardAction: (action) =>
         runMessageInputKeyboardAction(action, {
           focusInput: () => textInputRef.current?.focus(),
@@ -1720,6 +1805,9 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         handleSendMessage,
         handleQueueMessage,
       });
+      if (hasFinePointer()) {
+        textInputRef.current?.focus();
+      }
     }, [defaultSendBehavior, isAgentRunning, onQueue, handleQueueMessage, handleSendMessage]);
 
     const handleAlternateSendAction = useCallback(() => {
@@ -1745,7 +1833,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       handleAlternateSendAction();
     }, [alternateSendAction, handleAlternateSendAction]);
 
-    usePasteImagesEffect({
+    usePasteEffect({
       textarea: webTextArea,
       isConnected,
       disabled,
@@ -1812,6 +1900,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       allowEmptySubmit,
       isAgentRunning,
       isSubmitLoading,
+      offersVoiceMode: voiceModeContent != null,
     });
     const { canPressLoadingButton, isSendButtonDisabled, defaultActionQueues } =
       computeSendButtonState({
@@ -1893,20 +1982,20 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     );
 
     const attachButtonStyle = useCallback(
-      ({ hovered }: { hovered?: boolean }) => [
+      ({ hovered, pressed }: { hovered?: boolean; pressed?: boolean }) => [
         styles.attachButton,
-        Boolean(hovered) && styles.iconButtonHovered,
+        Boolean(hovered || pressed) && styles.iconButtonHovered,
         (!isConnected || disabled) && styles.buttonDisabled,
       ],
       [isConnected, disabled],
     );
 
     const voiceButtonStyle = useCallback(
-      ({ hovered }: { hovered?: boolean }) => [
+      ({ hovered, pressed }: { hovered?: boolean; pressed?: boolean }) => [
         styles.voiceButton,
-        Boolean(hovered) && !isDictating && styles.iconButtonHovered,
+        Boolean(hovered || pressed) && !isDictating && styles.iconButtonHovered,
+        Boolean(pressed) && isDictating && styles.discPressed,
         !isDictationStartEnabled && styles.buttonDisabled,
-        isDictating && styles.voiceButtonRecording,
       ],
       [isDictating, isDictationStartEnabled],
     );
@@ -1918,7 +2007,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     const inputWrapperCombinedStyle = useMemo(
       () => [
         styles.inputWrapper,
-        isCompact && !isFullscreen && styles.inputWrapperCompact,
+        Platform.OS !== "ios" && isCompact && !isFullscreen && styles.inputWrapperCompact,
         readOnly && styles.inputWrapperReadOnly,
         inputWrapperStyle,
         { opacity: surfacePresentation.input.opacity },
@@ -1946,21 +2035,25 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       [mode.isMonospace],
     );
     // Fullscreen always shows Send; without content it is disabled, and looks it.
+    // With nothing to send and no voice mode, a disabled Send holds the trailing disc so the row
+    // does not shift when typing starts.
+    const sendStandsIn = isFullscreen || primaryActionKind === "none";
+    const presentedActionKind: PrimaryActionKind = sendStandsIn ? "send" : primaryActionKind;
     const isPresentedSendDisabled = resolvePresentationSendDisabled({
-      fullscreen: isFullscreen,
+      standsIn: sendStandsIn,
       disabled: isSendButtonDisabled,
       hasText: hasLiveText,
       attachments,
       hasExternalContent,
       allowEmpty: allowEmptySubmit,
     });
-    const sendButtonCombinedStyle = useMemo(
-      () => [
+    const sendButtonCombinedStyle = useCallback(
+      ({ pressed }: { pressed?: boolean }) => [
         styles.sendButton,
-        submitLabel ? styles.sendButtonLabeled : undefined,
+        Boolean(pressed) && styles.discPressed,
         isPresentedSendDisabled && styles.buttonDisabled,
       ],
-      [isPresentedSendDisabled, submitLabel],
+      [isPresentedSendDisabled],
     );
     const overlayContainerStyle = useMemo(
       () => [styles.overlayContainer, { opacity: surfacePresentation.overlay.opacity }],
@@ -1972,10 +2065,10 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         <AttachButtonIcon
           hovered={Boolean(hovered)}
           onAttachButtonRef={onAttachButtonRef}
-          buttonIconSize={buttonIconSize}
+          glyph={toolbarGlyph}
         />
       ),
-      [onAttachButtonRef, buttonIconSize],
+      [onAttachButtonRef, toolbarGlyph],
     );
 
     const renderVoiceButtonIcon = useCallback(
@@ -1984,17 +2077,19 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
           hovered={Boolean(hovered)}
           isDictating={isDictating}
           isMutedRealtime={Boolean(isRealtimeVoiceForCurrentAgent && voice?.isMuted)}
-          buttonIconSize={buttonIconSize}
+          glyph={toolbarGlyph}
+          discGlyphSize={discGlyphSize}
         />
       ),
-      [isDictating, isRealtimeVoiceForCurrentAgent, voice?.isMuted, buttonIconSize],
+      [isDictating, isRealtimeVoiceForCurrentAgent, voice?.isMuted, toolbarGlyph, discGlyphSize],
     );
 
     const sendButton = useMemo(
       () => (
         <PrimaryAction
-          kind={isFullscreen ? "send" : primaryActionKind}
+          kind={presentedActionKind}
           activeActionContent={activeActionContent}
+          voiceModeContent={voiceModeContent}
           shouldShow
           canPressLoadingButton={canPressLoadingButton}
           onSubmitLoadingPress={onSubmitLoadingPress}
@@ -2008,15 +2103,15 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
           submitIcon={submitIcon}
           submitLabel={submitLabel}
           submitButtonTestID={submitButtonTestID}
-          buttonIconSize={buttonIconSize}
+          glyph={toolbarGlyph}
           sendKeys={resolveSendKeys(sendShortcut)}
           sendTooltipLabel={sendTooltipLabel}
         />
       ),
       [
-        isFullscreen,
-        primaryActionKind,
+        presentedActionKind,
         activeActionContent,
+        voiceModeContent,
         canPressLoadingButton,
         onSubmitLoadingPress,
         handleDefaultSendAction,
@@ -2029,7 +2124,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         submitIcon,
         submitLabel,
         submitButtonTestID,
-        buttonIconSize,
+        toolbarGlyph,
         sendShortcut,
         sendTooltipLabel,
       ],
@@ -2067,7 +2162,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
             fullscreen={isFullscreen}
             compact={isCompact}
             onRenderedLinesChange={setRenderedLines}
-            focusHintVisible={!isFullscreen && isWeb && !isInputFocused && !value}
+            focusHintVisible={!isFullscreen && isWeb && !isInputFocused && !hasLiveText}
             focusInputKeys={focusInputKeys}
             focusHintLabel={t("composer.input.focusHint", {
               shortcut: focusInputKeys ? formatShortcut(focusInputKeys[0], getShortcutOs()) : "",
@@ -2099,13 +2194,30 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         isFullscreen,
         isCompact,
         isInputFocused,
+        hasLiveText,
         value,
         focusInputKeys,
       ],
     );
+    const leadingEdge = resolveComposerLeadingEdge({
+      showsAttach: mode.showAttachments,
+      showsAgentControls: leftContent != null,
+    });
+    // The trailing control is always a disc: voice mode, then Send or Stop.
+    const trailingEdge = "disc";
+    const buttonRowStyle = useMemo(
+      () => [
+        styles.buttonRow,
+        {
+          marginLeft: -composerToolbarOverhang(leadingEdge, controlSizing),
+          marginRight: -composerToolbarOverhang(trailingEdge, controlSizing),
+        },
+      ],
+      [controlSizing, leadingEdge, trailingEdge],
+    );
     const toolbar = useMemo(
       () => (
-        <View style={styles.buttonRow}>
+        <View style={buttonRowStyle}>
           {/* Toolbar left: attachment button + agent controls */}
           <View style={styles.leftButtonGroup}>
             <AttachmentDropdown
@@ -2120,7 +2232,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
             {leftContent}
           </View>
 
-          {/* Right: voice button, contextual button (realtime/send/cancel) */}
+          {/* Right: dictation, then the trailing action (voice mode, send or stop) */}
           <View style={styles.rightButtonGroup}>
             {beforeVoiceContent}
             <VoiceButtonTooltip
@@ -2135,12 +2247,12 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
               voiceMuteToggleKeys={voiceMuteToggleKeys}
               dictationToggleKeys={dictationToggleKeys}
             />
-            {rightContent}
-            {sendButton}
+            <View style={styles.trailingDisc}>{sendButton}</View>
           </View>
         </View>
       ),
       [
+        buttonRowStyle,
         mode.showAttachments,
         isConnected,
         disabled,
@@ -2160,7 +2272,6 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         isRealtimeVoiceForCurrentAgent,
         voiceMuteToggleKeys,
         dictationToggleKeys,
-        rightContent,
         sendButton,
       ],
     );
@@ -2212,7 +2323,11 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     return (
       <View
         ref={rootRef}
-        style={isFullscreen ? styles.fullscreenContainer : styles.container}
+        style={
+          isFullscreen
+            ? styles.fullscreenContainer
+            : [styles.container, Platform.OS === "ios" && isCompact && styles.inputWrapperCompact]
+        }
         testID="message-input-root"
         onLayout={handleComposerLayout}
       >
@@ -2223,7 +2338,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         />
         <ComposerInputPresentation
           fullscreen={isFullscreen}
-          sendIconSize={buttonIconSize}
+          controlSizing={controlSizing}
+          sendIconSize={toolbarGlyph.size}
           surface={textSurface}
           toolbar={toolbar}
           send={sendButton}
@@ -2257,26 +2373,17 @@ const styles = StyleSheet.create((theme: Theme) => ({
     position: "relative",
   },
   inputWrapper: {
+    ...(Platform.OS === "ios" ? { overflow: "hidden" as const } : {}),
     flexShrink: 1,
     flexDirection: "column",
     gap: theme.spacing[3],
     backgroundColor: theme.colors.surface1,
     borderWidth: theme.borderWidth[1],
     borderColor: theme.colors.borderAccent,
-    borderRadius: theme.borderRadius["2xl"],
-    paddingTop: {
-      xs: theme.spacing[2],
-      md: theme.spacing[4],
-    },
-    // The button row bleeds 6px horizontally, so match its corner inset at the bottom.
-    paddingBottom: {
-      xs: theme.spacing[2],
-      md: theme.spacing[3],
-    },
-    paddingHorizontal: {
-      xs: theme.spacing[3],
-      md: theme.spacing[4],
-    },
+    borderRadius: COMPOSER_CORNER_RADIUS,
+    paddingTop: COMPOSER_PADDING_TOP,
+    paddingBottom: COMPOSER_PADDING_BOTTOM,
+    paddingHorizontal: COMPOSER_PADDING_HORIZONTAL,
     ...(isWeb
       ? {
           transitionProperty: "border-color",
@@ -2350,64 +2457,84 @@ const styles = StyleSheet.create((theme: Theme) => ({
     minHeight: MIN_INPUT_HEIGHT,
     color: theme.colors.foregroundMuted,
   },
+  // The row keeps a full touch target's height; its disc-sized controls centre in it.
   buttonRow: {
+    minHeight: TOOLBAR_CONTROL_HEIGHT,
     flexShrink: 0,
     flexDirection: "row",
-    alignItems: "flex-end",
+    alignItems: "center",
     justifyContent: "space-between",
-    marginHorizontal: -6,
   },
   leftButtonGroup: {
     minWidth: 0,
     flexShrink: 1,
     flexGrow: 1,
     flexDirection: "row",
-    alignItems: "flex-end",
-    gap: theme.spacing[0],
+    alignItems: "center",
+    gap: TOOLBAR_CONTROL_GAP,
   },
   rightButtonGroup: {
     flexShrink: 0,
     flexDirection: "row",
     alignItems: "center",
-    gap: theme.spacing[1],
+    gap: TOOLBAR_CONTROL_GAP,
   },
+  // Touch-sized the row's highlights touch, but the disc is always painted, so a pressed neighbour
+  // keeps clear of it instead of merging with it.
+  trailingDisc: {
+    marginLeft: bySizing({ touch: theme.spacing[1.5], pointer: 0 }),
+  },
+  // Touch-sized the plus is all thin arms, so beside the picker's glyph the same gap reads wider.
+  // Its highlight can overlap the picker's: only one control is ever pressed.
   attachButton: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(),
+    marginRight: bySizing({ touch: -2, pointer: 0 }),
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
   attachButtonAnchor: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     alignItems: "center",
     justifyContent: "center",
   },
   voiceButton: {
-    width: 28,
-    height: 28,
+    ...toolbarSlot(),
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
-  voiceButtonRecording: {
+  voiceButtonRecordingDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
+    borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.destructive,
+    alignItems: "center",
+    justifyContent: "center",
   },
   sendButton: {
-    width: 28,
-    height: 28,
+    minWidth: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  sendButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.accent,
     alignItems: "center",
     justifyContent: "center",
-    marginLeft: theme.spacing[1],
   },
-  sendButtonLabeled: {
-    width: "auto",
-    minWidth: 28,
+  sendButtonDiscLabeled: {
+    minWidth: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     paddingHorizontal: theme.spacing[3],
     borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
   },
   sendButtonLabel: {
     fontSize: theme.fontSize.base,
@@ -2417,6 +2544,9 @@ const styles = StyleSheet.create((theme: Theme) => ({
   iconButtonHovered: {
     backgroundColor: theme.colors.surface2,
   },
+  discPressed: {
+    opacity: 0.7,
+  },
   tooltipRow: {
     flexDirection: "row",
     alignItems: "center",
diff --git a/packages/app/src/composer/input/presentation.tsx b/packages/app/src/composer/input/presentation.tsx
index 64697999f5..956dc22597 100644
--- a/packages/app/src/composer/input/presentation.tsx
+++ b/packages/app/src/composer/input/presentation.tsx
@@ -6,14 +6,16 @@ import { Button } from "@/components/ui/button";
 import { ComposerFullscreenBody, ComposerFullscreenFooter } from "@/composer/dock";
 import { useComposerKeyboardScope } from "@/composer/keyboard-scope";
 import { isWeb } from "@/constants/platform";
-import { ICON_SIZE } from "@/styles/theme";
+import {
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_CONTROL_SIZES,
+  type ControlSizing,
+} from "@/components/ui/control-geometry";
 import { StyleSheet } from "react-native-unistyles";
 import { useComposerFullscreenExit } from "./fullscreen-exit";
 import { resolveGlyphRailOffset } from "./state";
 
-const CONTROL_SIZE = 28;
-const FULLSCREEN_GLYPH_SIZE = ICON_SIZE.md;
-
 function keepEditorFocused(event: import("react-native").PointerEvent) {
   if (isWeb) event.preventDefault();
 }
@@ -27,6 +29,7 @@ function keepEditorFocused(event: import("react-native").PointerEvent) {
  */
 export function ComposerInputPresentation({
   fullscreen,
+  controlSizing,
   sendIconSize,
   surface,
   toolbar,
@@ -42,6 +45,8 @@ export function ComposerInputPresentation({
   overlay,
 }: {
   fullscreen: boolean;
+  /** The sizing the toolbar's stylesheet resolves to; see `resolveControlSizing`. */
+  controlSizing: ControlSizing;
   sendIconSize: number;
   surface: ReactNode;
   toolbar: ReactNode;
@@ -61,18 +66,19 @@ export function ComposerInputPresentation({
   // action (Escape, hardware back) belongs only to the pane the user is in.
   const { isActiveComposer } = useComposerKeyboardScope();
   const exitScopeRef = useComposerFullscreenExit(fullscreen && isActiveComposer, onExit);
+  const glyphSize = iconSizeFor("md")[controlSizing];
   const railOffset = resolveGlyphRailOffset({
-    controlSize: CONTROL_SIZE,
+    controlSize: TOOLBAR_CONTROL_SIZES[controlSizing],
     sendIconSize,
-    glyphIconSize: FULLSCREEN_GLYPH_SIZE,
+    glyphIconSize: glyphSize,
   });
   const maximizeIcon = useCallback(
-    (color: string) => <Maximize2 color={color} size={FULLSCREEN_GLYPH_SIZE} />,
-    [],
+    (color: string) => <Maximize2 color={color} size={glyphSize} />,
+    [glyphSize],
   );
   const minimizeIcon = useCallback(
-    (color: string) => <Minimize2 color={color} size={FULLSCREEN_GLYPH_SIZE} />,
-    [],
+    (color: string) => <Minimize2 color={color} size={glyphSize} />,
+    [glyphSize],
   );
   // The toolbar row bleeds 6px past the input padding; the inline glyph sits on that edge.
   const enterStyle = useMemo(() => [styles.enterButton, { right: -6 + railOffset }], [railOffset]);
@@ -87,7 +93,7 @@ export function ComposerInputPresentation({
         <View style={styles.exitRow}>
           <Button
             variant="ghost"
-            size="xs"
+            size="sm"
             accessibilityLabel={t("composer.input.exitFullscreen")}
             onPointerDown={keepEditorFocused}
             onPress={onExit}
@@ -111,7 +117,7 @@ export function ComposerInputPresentation({
             {showFullscreenButton && !fullscreen ? (
               <Button
                 variant="ghost"
-                size="xs"
+                size="sm"
                 accessibilityLabel={t("composer.input.fullscreen")}
                 leftIcon={maximizeIcon}
                 onPointerDown={keepEditorFocused}
@@ -141,8 +147,8 @@ const styles = StyleSheet.create((theme) => ({
   inline: { flexShrink: 1, position: "relative" },
   inlineTextSurface: { flexShrink: 1, position: "relative" },
   iconButton: {
-    width: CONTROL_SIZE,
-    height: CONTROL_SIZE,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     padding: 0,
     borderWidth: 0,
     borderRadius: theme.borderRadius.full,
@@ -150,8 +156,8 @@ const styles = StyleSheet.create((theme) => ({
   enterButton: {
     position: "absolute",
     top: 0,
-    width: CONTROL_SIZE,
-    height: CONTROL_SIZE,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     padding: 0,
     borderWidth: 0,
     borderRadius: theme.borderRadius.full,
diff --git a/packages/app/src/composer/input/toolbar-rails.test.ts b/packages/app/src/composer/input/toolbar-rails.test.ts
new file mode 100644
index 0000000000..002de77071
--- /dev/null
+++ b/packages/app/src/composer/input/toolbar-rails.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { composerToolbarOverhang, resolveComposerLeadingEdge } from "./toolbar-rails";
+
+describe("composer toolbar rails", () => {
+  it("hangs each end highlight far enough to put its ink on the text rail and nests a trailing disc into the corner", () => {
+    // The 36pt highlight around the plus's ink (14/24 of a 20pt glyph, plus its 1.5 stroke).
+    expect(composerToolbarOverhang("attach", "touch")).toBeCloseTo((36 - (14 * 20) / 24 - 1.5) / 2);
+    expect(composerToolbarOverhang("label", "touch")).toBe(8);
+    expect(composerToolbarOverhang("none", "touch")).toBe(0);
+    // A 36pt disc centred in the 44pt row sits 8 from the bottom edge, so it sits 8 from the side.
+    expect(composerToolbarOverhang("disc", "touch")).toBe(8);
+  });
+
+  it("keeps the pointer row's flat overhang", () => {
+    for (const edge of ["attach", "disc", "label", "none"] as const) {
+      expect(composerToolbarOverhang(edge, "pointer")).toBe(6);
+    }
+  });
+
+  it("starts the row on attach, else on the agent controls", () => {
+    expect(resolveComposerLeadingEdge({ showsAttach: true, showsAgentControls: true })).toBe(
+      "attach",
+    );
+    expect(resolveComposerLeadingEdge({ showsAttach: false, showsAgentControls: true })).toBe(
+      "label",
+    );
+    expect(resolveComposerLeadingEdge({ showsAttach: false, showsAgentControls: false })).toBe(
+      "none",
+    );
+  });
+});
diff --git a/packages/app/src/composer/input/toolbar-rails.ts b/packages/app/src/composer/input/toolbar-rails.ts
new file mode 100644
index 0000000000..9ae9765a48
--- /dev/null
+++ b/packages/app/src/composer/input/toolbar-rails.ts
@@ -0,0 +1,84 @@
+import {
+  TOOLBAR_CONTROL_SIZES,
+  TOOLBAR_DISC_SIZES,
+  TOOLBAR_LABEL_PADDING,
+  toolbarGlyphsFor,
+  type ControlSizing,
+} from "@/components/ui/control-geometry";
+import { bySizing } from "@/components/ui/control-sizing";
+
+/** The control at one end of the composer toolbar, which decides how far the row hangs out. */
+export type ComposerToolbarEdge = "attach" | "label" | "disc" | "none";
+
+/**
+ * The composer's padding. Its sides are the rails: the text column and the toolbar's outer
+ * controls both start there.
+ */
+const COMPOSER_PADDING = {
+  touch: { top: 12, horizontal: 16, bottom: 4 },
+  pointer: { top: 16, horizontal: 16, bottom: 12 },
+} as const;
+
+export const COMPOSER_PADDING_TOP = bySizing({
+  touch: COMPOSER_PADDING.touch.top,
+  pointer: COMPOSER_PADDING.pointer.top,
+});
+export const COMPOSER_PADDING_HORIZONTAL = bySizing({
+  touch: COMPOSER_PADDING.touch.horizontal,
+  pointer: COMPOSER_PADDING.pointer.horizontal,
+});
+export const COMPOSER_PADDING_BOTTOM = bySizing({
+  touch: COMPOSER_PADDING.touch.bottom,
+  pointer: COMPOSER_PADDING.pointer.bottom,
+});
+
+/** The plus glyph's ink: 14 of Lucide's 24 units, plus its stroke. */
+function attachGlyphInkWidth(): number {
+  const glyph = toolbarGlyphsFor("touch").icon;
+  return (14 * glyph.size) / 24 + glyph.strokeWidth;
+}
+
+/** Pointer-sized the row hangs a flat 6px into the padding, which puts each 16pt glyph box on the rail. */
+const POINTER_OVERHANG = 6;
+
+/** How far a touch-sized disc sits from the composer's bottom edge, centred in the toolbar row. */
+const DISC_EDGE_INSET =
+  COMPOSER_PADDING.touch.bottom + (TOOLBAR_CONTROL_SIZES.touch - TOOLBAR_DISC_SIZES.touch) / 2;
+
+/**
+ * A trailing disc nests into the composer's corner: it reaches past the rail until it sits as far
+ * from the right edge as from the bottom edge.
+ */
+const DISC_CORNER_NEST = COMPOSER_PADDING.touch.horizontal - DISC_EDGE_INSET;
+
+/** Touch-sized the composer's corner is concentric with the disc nested in it. */
+export const COMPOSER_CORNER_RADIUS = bySizing({
+  touch: TOOLBAR_DISC_SIZES.touch / 2 + DISC_EDGE_INSET,
+  pointer: 16,
+});
+
+/**
+ * Touch-sized each end control's highlight hangs past the rail far enough to put what it paints on
+ * the rail. The trailing disc paints its whole highlight, so it nests into the corner instead.
+ */
+const TOUCH_OVERHANGS: Record<ComposerToolbarEdge, number> = {
+  attach: (TOOLBAR_DISC_SIZES.touch - attachGlyphInkWidth()) / 2,
+  label: TOOLBAR_LABEL_PADDING,
+  disc: DISC_CORNER_NEST,
+  none: 0,
+};
+
+/** How far the composer toolbar hangs past the text column at one end. */
+export function composerToolbarOverhang(edge: ComposerToolbarEdge, sizing: ControlSizing): number {
+  return sizing === "pointer" ? POINTER_OVERHANG : TOUCH_OVERHANGS[edge];
+}
+
+/** The control that starts the toolbar on the left. */
+export function resolveComposerLeadingEdge(input: {
+  showsAttach: boolean;
+  showsAgentControls: boolean;
+}): ComposerToolbarEdge {
+  if (input.showsAttach) return "attach";
+  if (input.showsAgentControls) return "label";
+  return "none";
+}
diff --git a/packages/app/src/composer/input/use-input-live.browser.test.tsx b/packages/app/src/composer/input/use-input-live.browser.test.tsx
new file mode 100644
index 0000000000..d9e20029ca
--- /dev/null
+++ b/packages/app/src/composer/input/use-input-live.browser.test.tsx
@@ -0,0 +1,47 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, expect, it, vi } from "vitest";
+import { RetainedPanelActivity } from "@/components/retained-panel";
+import { useIsInputLive } from "./use-input-live";
+
+// App sources compile against the classic JSX runtime, which expects React on the global, as the
+// other browser tests here arrange.
+beforeEach(() => vi.stubGlobal("React", React));
+
+interface InputRef {
+  current: object | null;
+}
+
+function render(active: boolean, input: InputRef, publish: (isLive: () => boolean) => void) {
+  function Probe() {
+    publish(useIsInputLive(input));
+    return null;
+  }
+  return (
+    <RetainedPanelActivity active={active}>
+      <Probe />
+    </RetainedPanelActivity>
+  );
+}
+
+it("an input kept mounted in a panel that is not showing is not live", () => {
+  const input: InputRef = { current: {} };
+  let isLive: () => boolean = () => false;
+  const publish = (read: () => boolean) => {
+    isLive = read;
+  };
+  const root = createRoot(document.createElement("div"));
+
+  act(() => root.render(render(true, input, publish)));
+  expect(isLive()).toBe(true);
+
+  act(() => root.render(render(false, input, publish)));
+  expect(isLive()).toBe(false);
+
+  act(() => root.render(render(true, input, publish)));
+  expect(isLive()).toBe(true);
+
+  input.current = null;
+  expect(isLive()).toBe(false);
+  act(() => root.unmount());
+});
diff --git a/packages/app/src/composer/input/use-input-live.ts b/packages/app/src/composer/input/use-input-live.ts
new file mode 100644
index 0000000000..cf83ea6735
--- /dev/null
+++ b/packages/app/src/composer/input/use-input-live.ts
@@ -0,0 +1,14 @@
+import { useCallback, useRef } from "react";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+
+/**
+ * Whether the composer's input is on screen, as a read a saved plugin command can make later. A
+ * retained composer keeps its input mounted and hidden, and its cursor and selection are then
+ * stale, so only an input in a panel that is showing counts.
+ */
+export function useIsInputLive(input: { readonly current: unknown }): () => boolean {
+  const panelActive = useRetainedPanelActive();
+  const panelActiveRef = useRef(panelActive);
+  panelActiveRef.current = panelActive;
+  return useCallback(() => input.current !== null && panelActiveRef.current, [input]);
+}
diff --git a/packages/app/src/composer/insert-text.test.ts b/packages/app/src/composer/insert-text.test.ts
new file mode 100644
index 0000000000..b48c1a1248
--- /dev/null
+++ b/packages/app/src/composer/insert-text.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { insertAtSelection } from "./insert-text";
+
+describe("insertAtSelection", () => {
+  it("inserts at the caret and moves the caret after the insertion", () => {
+    expect(insertAtSelection({ text: "ab", selection: { start: 1, end: 1 } }, "XY")).toEqual({
+      text: "aXYb",
+      selection: { start: 3, end: 3 },
+    });
+  });
+
+  it("replaces the selection, however it was dragged", () => {
+    expect(insertAtSelection({ text: "abcd", selection: { start: 3, end: 1 } }, "-")).toEqual({
+      text: "a-d",
+      selection: { start: 2, end: 2 },
+    });
+  });
+});
diff --git a/packages/app/src/composer/insert-text.ts b/packages/app/src/composer/insert-text.ts
new file mode 100644
index 0000000000..78127e744a
--- /dev/null
+++ b/packages/app/src/composer/insert-text.ts
@@ -0,0 +1,15 @@
+import type { ComposerInputSnapshot } from "@/composer/input/input";
+
+/** The text with `inserted` in place of the selection, and the caret after it. */
+export function insertAtSelection(
+  { text, selection }: ComposerInputSnapshot,
+  inserted: string,
+): ComposerInputSnapshot {
+  const start = Math.min(selection.start, selection.end);
+  const end = Math.max(selection.start, selection.end);
+  const caret = start + inserted.length;
+  return {
+    text: text.slice(0, start) + inserted + text.slice(end),
+    selection: { start: caret, end: caret },
+  };
+}
diff --git a/packages/app/src/composer/model.ts b/packages/app/src/composer/model.ts
new file mode 100644
index 0000000000..888e5caed0
--- /dev/null
+++ b/packages/app/src/composer/model.ts
@@ -0,0 +1,58 @@
+import { createContext, useContext } from "react";
+import type { JsonValue, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import type { UserComposerAttachment } from "@/attachments/types";
+
+/** Everything a plugin can read of a composer. A new object whenever any of it changes. */
+export interface ComposerState {
+  /** `"agent"`: a running agent. `"draft"`: a new agent in a workspace. `"new-workspace"`: the New workspace screen. */
+  context: "agent" | "draft" | "new-workspace";
+  prompt: string;
+  attachments: readonly UserComposerAttachment[];
+  provider: string | null;
+  model: string | null;
+  mode: string | null;
+  thinking: string | null;
+  /** The options the agent runs with, defaults included. */
+  options: ProviderOptions;
+  metadata: Record<string, JsonValue>;
+}
+
+/** Where the cursor goes when a composer takes focus. */
+export interface ComposerFocusOptions {
+  /** Offsets into the prompt, clamped to its length. Omit to keep the cursor where it is. */
+  selection?: { start: number; end: number };
+}
+
+/**
+ * A composer as plugins use it: its state, a way to hear about changes, and the commands that
+ * change it. The commands enforce the rules the built-in controls follow (a draft being created
+ * is locked, a running agent keeps its provider). A running agent's model lives in the stores and
+ * exists whether or not its tab is open; a draft's is built from its mounted composer.
+ */
+export interface ComposerModel {
+  getState(): ComposerState;
+  subscribe(listener: () => void): () => void;
+  setPrompt(text: string): void;
+  /** Inserts at the cursor, replacing the selection. */
+  insertText(text: string): void;
+  /** Puts the cursor in the input. Resolves once it is there; rejects when it cannot get there. */
+  focus(options?: ComposerFocusOptions): Promise<void>;
+  changeAttachments(updater: (current: UserComposerAttachment[]) => UserComposerAttachment[]): void;
+  setProvider(provider: string): Promise<void>;
+  setModel(modelId: string): Promise<void>;
+  setMode(modeId: string): Promise<void>;
+  setThinking(thinkingOptionId: string): Promise<void>;
+  /** Top-level keys replace; `null` removes the agent's own value. */
+  setOptions(patch: ProviderOptions): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+const ComposerModelContext = createContext<ComposerModel | null>(null);
+
+export const ComposerModelProvider = ComposerModelContext.Provider;
+
+/** The model of the composer this control sits in. */
+export function useComposerModel(): ComposerModel | null {
+  return useContext(ComposerModelContext);
+}
diff --git a/packages/app/src/composer/pasted-text.browser.test.ts b/packages/app/src/composer/pasted-text.browser.test.ts
new file mode 100644
index 0000000000..e492cd237b
--- /dev/null
+++ b/packages/app/src/composer/pasted-text.browser.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createMarkdownClipboardContent } from "@/utils/rich-clipboard";
+import { pasteLinkedClipboardText } from "./pasted-text.web";
+
+const inputs: HTMLTextAreaElement[] = [];
+function editor(): HTMLTextAreaElement {
+  const input = document.createElement("textarea");
+  document.body.append(input);
+  inputs.push(input);
+  return input;
+}
+afterEach(() => {
+  for (const input of inputs.splice(0)) input.remove();
+});
+
+function clipboard(html: string, text: string): DataTransfer {
+  const data = new DataTransfer();
+  data.setData("text/html", html);
+  data.setData("text/plain", text);
+  return data;
+}
+
+describe("pasted prompt links", () => {
+  it.each([
+    "https://example.com/1",
+    "https://example.com/日本語",
+    "<https://example.com/a b>",
+    "https://例え.テスト/issue",
+  ])("keeps complete Markdown from Copy with destination %s", (destination) => {
+    const source = `| Resource | Status |\n| --- | --- |\n| [issue](${destination}) | ~~closed~~ |`;
+    const content = createMarkdownClipboardContent(source);
+    const input = editor();
+    expect(pasteLinkedClipboardText(input, clipboard(content.html, content.plainText))).toBe(false);
+    expect(input.value).toBe("");
+  });
+  it("converts external links when plain text names the resource but omits a destination", () => {
+    const input = editor();
+    expect(
+      pasteLinkedClipboardText(
+        input,
+        clipboard(
+          '<a href="https://example.com/%E6%97%A5%E6%9C%AC%E8%AA%9E">日本語</a> and <a href="https://example.com/missing">another</a>',
+          "[日本語](https://example.com/日本語) and another",
+        ),
+      ),
+    ).toBe(true);
+    expect(input.value).toBe(
+      "[日本語](https://example.com/%E6%97%A5%E6%9C%AC%E8%AA%9E) and [another](https://example.com/missing)",
+    );
+  });
+  it("preserves a labeled resource URL as Markdown", () => {
+    const data = clipboard(
+      'Hey can you take a look at <a href="https://example.com/issues/39150">this FR</a> and...',
+      "Hey can you take a look at this FR and...",
+    );
+    const input = editor();
+    expect(pasteLinkedClipboardText(input, data)).toBe(true);
+    expect(input.value).toBe(
+      "Hey can you take a look at [this FR](https://example.com/issues/39150) and...",
+    );
+  });
+
+  it("preserves external linked table rows and columns", () => {
+    const input = editor();
+    expect(
+      pasteLinkedClipboardText(
+        input,
+        clipboard(
+          '<table><thead><tr><th>Resource</th><th>Status</th></tr></thead><tbody><tr><td><a href="https://example.com/issue">Issue</a></td><td>closed</td></tr></tbody></table>',
+          "Resource\tStatus\nIssue\tclosed",
+        ),
+      ),
+    ).toBe(true);
+    expect(input.value).toBe(
+      "| Resource | Status |\n| --- | --- |\n| [Issue](https://example.com/issue) | closed |",
+    );
+  });
+
+  it("keeps table cell separators and line breaks inside their cells", () => {
+    const input = editor();
+    expect(
+      pasteLinkedClipboardText(
+        input,
+        clipboard(
+          '<table><tr><th>Resource</th><th>Status</th></tr><tr><td><a href="https://example.com/issue">Issue | tracker</a></td><td>closed<br>today</td></tr></table>',
+          "Resource\tStatus\nIssue | tracker\tclosed today",
+        ),
+      ),
+    ).toBe(true);
+    expect(input.value).toBe(
+      "| Resource | Status |\n| --- | --- |\n| [Issue \\| tracker](https://example.com/issue) | closed<br>today |",
+    );
+  });
+
+  it("retains headerless tables as HTML without inventing a heading", () => {
+    const html =
+      '<table><tbody><tr><td><a href="https://example.com/issue">Issue</a></td><td>closed</td></tr><tr><td>Other</td><td>open</td></tr></tbody></table>';
+    const input = editor();
+    expect(pasteLinkedClipboardText(input, clipboard(html, "Issue\tclosed\nOther\topen"))).toBe(
+      true,
+    );
+    expect(input.value).toBe(html);
+  });
+
+  it.each([
+    ["<table></table>", ""],
+    ["<table><caption>Context</caption></table>", "\n\nContext"],
+  ])("keeps surrounding links when a table has no rows: %s", (table, caption) => {
+    const input = editor();
+    expect(
+      pasteLinkedClipboardText(
+        input,
+        clipboard(`<a href="https://example.com/">Issue</a>${table}`, "Issue"),
+      ),
+    ).toBe(true);
+    expect(input.value).toBe(`[Issue](https://example.com/)${caption}`);
+  });
+
+  it("leaves plain text and rich text without links to native paste", () => {
+    const input = editor();
+    expect(pasteLinkedClipboardText(input, clipboard("", "[link](https://example.com)"))).toBe(
+      false,
+    );
+    expect(pasteLinkedClipboardText(input, clipboard("<b>hello</b>", "hello"))).toBe(false);
+    expect(pasteLinkedClipboardText(input, null)).toBe(false);
+    expect(input.value).toBe("");
+  });
+
+  it("keeps paragraphs and multiple links", () => {
+    const input = editor();
+    expect(
+      pasteLinkedClipboardText(
+        input,
+        clipboard(
+          '<p>See <a href="https://example.com/a">one</a></p><p>and <a href="https://example.com/b">two</a></p>',
+          "See one\n\nand two",
+        ),
+      ),
+    ).toBe(true);
+    expect(input.value).toBe(
+      "See [one](https://example.com/a)\n\nand [two](https://example.com/b)",
+    );
+  });
+});
diff --git a/packages/app/src/composer/pasted-text.ts b/packages/app/src/composer/pasted-text.ts
new file mode 100644
index 0000000000..99e7b2cfb5
--- /dev/null
+++ b/packages/app/src/composer/pasted-text.ts
@@ -0,0 +1,7 @@
+/** Native inputs retain their platform clipboard handling. */
+export function pasteLinkedClipboardText(
+  _input: HTMLElement,
+  _clipboard: Pick<DataTransfer, "getData"> | null,
+): boolean {
+  return false;
+}
diff --git a/packages/app/src/composer/pasted-text.web.ts b/packages/app/src/composer/pasted-text.web.ts
new file mode 100644
index 0000000000..b9b89d215e
--- /dev/null
+++ b/packages/app/src/composer/pasted-text.web.ts
@@ -0,0 +1,59 @@
+import TurndownService from "turndown";
+import { tables } from "turndown-plugin-gfm";
+import { createAssistantMarkdownParser } from "@/utils/assistant-markdown-parser";
+
+const markdown = new TurndownService({
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-",
+});
+// Heading tables become Markdown; headerless tables retain their HTML structure.
+markdown.use(tables);
+markdown.addRule("rowlessTable", {
+  filter: (node) => node.nodeName === "TABLE" && (node as HTMLTableElement).rows.length === 0,
+  replacement: (content) => (content ? `\n\n${content}\n\n` : ""),
+});
+markdown.addRule("tableCell", {
+  filter: ["th", "td"],
+  replacement: (content, node) => {
+    const prefix = node.previousElementSibling ? " " : "| ";
+    const cell = content.trim().replace(/\|/g, "\\|").replace(/ *\n/g, "<br>");
+    return `${prefix}${cell} |`;
+  },
+});
+const copiedMarkdown = createAssistantMarkdownParser();
+
+function linkDestinations(fragment: Document): string[] {
+  return Array.from(fragment.querySelectorAll("a[href]"), (link) => link.getAttribute("href")!);
+}
+
+function containsDestinations(plainText: string, destinations: string[]): boolean {
+  if (destinations.every((url) => plainText.includes(url))) return true;
+
+  // Copy normalizes Markdown URLs in HTML (percent encoding, internationalized
+  // domains). Compare parsed destinations using that same parser, not URL spelling.
+  const rendered = new DOMParser().parseFromString(copiedMarkdown.render(plainText), "text/html");
+  const links = new Set(linkDestinations(rendered));
+  return destinations.every((url) => plainText.includes(url) || links.has(url));
+}
+
+/** Paste linked HTML as Markdown through the browser's undoable editing command. */
+export function pasteLinkedClipboardText(
+  input: HTMLElement,
+  clipboard: Pick<DataTransfer, "getData"> | null,
+): boolean {
+  const html = clipboard?.getData("text/html");
+  if (!html) return false;
+
+  // Parse in a detached document. Clipboard markup is never mounted in the app.
+  const fragment = new DOMParser().parseFromString(html, "text/html");
+  const destinations = linkDestinations(fragment);
+  const plainText = clipboard!.getData("text/plain");
+  // Copy actions already put complete Markdown on the clipboard. Keep that
+  // representation, including tables and formatting, whenever it carries the URLs.
+  if (containsDestinations(plainText, destinations)) return false;
+  const text = markdown.turndown(fragment.body);
+  input.focus();
+  // Direct value assignment drops the textarea's undo history. This also emits
+  // the normal input event so the editor publishes its new draft as for typing.
+  return input.ownerDocument.execCommand("insertText", false, text);
+}
diff --git a/packages/app/src/composer/session.tsx b/packages/app/src/composer/session.tsx
new file mode 100644
index 0000000000..cb46f2b3dd
--- /dev/null
+++ b/packages/app/src/composer/session.tsx
@@ -0,0 +1,103 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { JsonValue, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import type { UserComposerAttachment } from "@/attachments/types";
+import type { ComposerFocusOptions } from "@/composer/model";
+import type { ComposerTextSource } from "@/composer/text-source";
+
+/**
+ * The text and attachments of the composer a control sits in. `Composer` provides it, so a
+ * control reaches the prompt without knowing which screen mounted the composer.
+ */
+export interface ComposerInput {
+  /** The prompt is held while the composer submits; the built-in input is read-only meanwhile. */
+  locked: boolean;
+  /** `locked` as it is now. A command a plugin kept from an earlier render asks this. */
+  isLocked: () => boolean;
+  /**
+   * The input is on screen. A retained composer in a workspace that is not shown has none, so it
+   * cannot take the cursor-aware commands below.
+   */
+  isLive: () => boolean;
+  /**
+   * The input is showing and nothing stands between it and the keyboard: its pane is focused and
+   * no compact overlay panel covers it. A new value of `revealed` is a new `ComposerInput`, which
+   * is how a request waiting for the input to come on screen hears about it.
+   */
+  revealed: boolean;
+  isRevealed: () => boolean;
+  focus: (options?: ComposerFocusOptions) => Promise<void>;
+  textSource: ComposerTextSource;
+  setText: (text: string) => void;
+  /** Inserts at the cursor, replacing the selection. */
+  insertText: (text: string) => void;
+  attachments: readonly UserComposerAttachment[];
+  changeAttachments: (
+    updater: (current: UserComposerAttachment[]) => UserComposerAttachment[],
+  ) => void;
+}
+
+/**
+ * The agent a composer configures, as one set of reads and commands. A running agent sends each
+ * command to the daemon; a draft keeps it locally until the agent is created. Controls call the
+ * same command either way.
+ */
+export interface ComposerAgent {
+  context: "agent" | "draft" | "new-workspace";
+  /** The agent is being created; the built-in controls are disabled meanwhile. */
+  locked: boolean;
+  /** `locked` as it is now. A command a plugin kept from an earlier render asks this. */
+  isLocked: () => boolean;
+  provider: string | null;
+  model: string | null;
+  mode: string | null;
+  thinking: string | null;
+  /** The options the agent runs with, defaults included. */
+  options: ProviderOptions;
+  metadata: Record<string, JsonValue>;
+  setProvider: (provider: string) => Promise<void>;
+  setModel: (modelId: string) => Promise<void>;
+  setMode: (modeId: string) => Promise<void>;
+  setThinking: (thinkingOptionId: string) => Promise<void>;
+  /** Top-level keys replace; `null` removes the agent's own value. */
+  setOptions: (patch: ProviderOptions) => Promise<void>;
+  /** Top-level keys replace; `null` removes the key. */
+  setMetadata: (patch: Record<string, JsonValue>) => Promise<void>;
+}
+
+const ComposerInputContext = createContext<ComposerInput | null>(null);
+const ComposerAgentContext = createContext<ComposerAgent | null>(null);
+
+export function ComposerInputProvider({
+  value,
+  children,
+}: {
+  value: ComposerInput;
+  children: ReactNode;
+}) {
+  return <ComposerInputContext.Provider value={value}>{children}</ComposerInputContext.Provider>;
+}
+
+export function ComposerAgentProvider({
+  value,
+  children,
+}: {
+  value: ComposerAgent | null;
+  children: ReactNode;
+}) {
+  return <ComposerAgentContext.Provider value={value}>{children}</ComposerAgentContext.Provider>;
+}
+
+export function useComposerInput(): ComposerInput | null {
+  return useContext(ComposerInputContext);
+}
+
+export function useComposerAgent(): ComposerAgent | null {
+  return useContext(ComposerAgentContext);
+}
+
+/** True while the composer holds its prompt or its agent's settings for a submit in flight. */
+export function useComposerLocked(): boolean {
+  const input = useComposerInput();
+  const agent = useComposerAgent();
+  return Boolean(input?.locked || agent?.locked);
+}
diff --git a/packages/app/src/composer/tracks-panel.browser.test.tsx b/packages/app/src/composer/tracks-panel.browser.test.tsx
index b02a1e5e28..8c523454bb 100644
--- a/packages/app/src/composer/tracks-panel.browser.test.tsx
+++ b/packages/app/src/composer/tracks-panel.browser.test.tsx
@@ -1,9 +1,15 @@
 import React, { act, useCallback, useState, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { Pressable, Text } from "react-native";
+import { Pressable, Text, View } from "react-native";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { RetainedPanelActivity } from "@/components/retained-panel";
-import { ComposerTrackPill, ComposerTrackRow, type ComposerTrackPillSegment } from "./tracks";
+import { MobilePanelsProvider } from "@/mobile-panels/provider";
+import {
+  ComposerTrackBar,
+  ComposerTrackPill,
+  ComposerTrackRow,
+  type ComposerTrackPillSegment,
+} from "./tracks";
 
 const SUBAGENT_SEGMENTS: ComposerTrackPillSegment[] = [{ bucket: null, text: "3 subagents" }];
 
@@ -192,6 +198,87 @@ describe("composer track panel", () => {
   });
 });
 
+const BAR_PILL_STYLE = { width: 120, height: 32 };
+const TRANSCRIPT_STYLE = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 } as const;
+const NARROW_HOST = { position: "relative", width: 300, height: 120 } as const;
+const WIDE_HOST = { position: "relative", width: 400, height: 120 } as const;
+
+function mountTrackBar({
+  host,
+  pills,
+}: {
+  host: typeof NARROW_HOST | typeof WIDE_HOST;
+  pills: number;
+}): void {
+  mount(
+    <MobilePanelsProvider>
+      <View style={host}>
+        <View testID="transcript" style={TRANSCRIPT_STYLE} />
+        <ComposerTrackBar>
+          {Array.from({ length: pills }, (_, index) => (
+            <View key={index} testID={`bar-pill-${index}`} style={BAR_PILL_STYLE} />
+          ))}
+        </ComposerTrackBar>
+      </View>
+    </MobilePanelsProvider>,
+  );
+}
+
+function byTestID(testID: string): HTMLElement {
+  const element = document.querySelector(`[data-testid="${testID}"]`);
+  if (!(element instanceof HTMLElement)) {
+    throw new Error(`${testID} did not render`);
+  }
+  return element;
+}
+
+/** The element that receives a touch landing at this point of the page. */
+function hitTest(x: number, y: number): Element | null {
+  return document.elementFromPoint(x, y);
+}
+
+describe("composer track bar", () => {
+  // Android's horizontal ScrollView ignores the drag unless the scroller itself can be touched.
+  // Browsers scroll either way, so this is the only part of that bug a browser can see.
+  it("keeps the scroller touchable, so Android can drag the row", () => {
+    mountTrackBar({ host: NARROW_HOST, pills: 4 });
+
+    expect(getComputedStyle(byTestID("composer-track-scroll")).pointerEvents).toBe("auto");
+  });
+
+  it("stays inside the bar when the pills overflow it", () => {
+    mountTrackBar({ host: NARROW_HOST, pills: 4 });
+
+    const scroller = byTestID("composer-track-scroll");
+    expect(scroller.getBoundingClientRect().right).toBeLessThanOrEqual(
+      byTestID("transcript").getBoundingClientRect().right,
+    );
+    expect(scroller.scrollWidth).toBeGreaterThan(scroller.clientWidth);
+  });
+
+  it("leaves the empty part of the row to the transcript", () => {
+    mountTrackBar({ host: WIDE_HOST, pills: 1 });
+
+    const pillRect = byTestID("bar-pill-0").getBoundingClientRect();
+    const transcript = byTestID("transcript");
+    const emptyX = transcript.getBoundingClientRect().right - 40;
+    expect(emptyX).toBeGreaterThan(pillRect.right);
+
+    expect(hitTest(emptyX, pillRect.top + pillRect.height / 2)).toBe(transcript);
+  });
+
+  it("fades the full height of the row without taking its touches", () => {
+    mountTrackBar({ host: NARROW_HOST, pills: 4 });
+
+    const scroller = byTestID("composer-track-scroll").getBoundingClientRect();
+    const shade = byTestID("composer-track-scroll-shade-right").getBoundingClientRect();
+    expect(shade.bottom).toBe(scroller.bottom);
+
+    const underShade = hitTest(shade.left + shade.width / 2, shade.top + shade.height / 2);
+    expect(byTestID("composer-track-scroll").contains(underShade)).toBe(true);
+  });
+});
+
 describe("composer track pill status mark", () => {
   /** The mark is the glyph itself: the dot for a still state, the ring's carrier for running. */
   function mountMark(bucket: "running" | "failed"): { mark: HTMLElement; body: HTMLElement } {
diff --git a/packages/app/src/composer/tracks.tsx b/packages/app/src/composer/tracks.tsx
index 341e7dc8e0..44906333d8 100644
--- a/packages/app/src/composer/tracks.tsx
+++ b/packages/app/src/composer/tracks.tsx
@@ -1,5 +1,7 @@
 import { useCallback, useMemo, useState, type ReactElement, type ReactNode } from "react";
 import { Pressable, Text, View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import Animated from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 import {
   MENU_ITEM_HEIGHT,
@@ -13,8 +15,14 @@ import {
   type MenuTriggerState,
 } from "@/components/ui/menu";
 import { StatusRing } from "@/components/status-ring";
+import { bySizing } from "@/components/ui/control-geometry";
+import {
+  HorizontalScrollBoundaryShades,
+  useHorizontalScrollBoundary,
+} from "@/components/ui/horizontal-scroll-boundary";
 import { STATUS_RING_HALO_INSET } from "@/components/status-ring/geometry";
 import { isWeb } from "@/constants/platform";
+import { usePanelAwareHorizontalScrollGesture } from "@/mobile-panels/gestures";
 import { getStatusDotColor } from "@/utils/status-dot-color";
 import { STATUS_INDICATOR_FILLED_DOT_SIZE } from "@/utils/status-indicator-geometry";
 import type { SidebarStateBucket } from "@/utils/sidebar-agent-state";
@@ -29,14 +37,41 @@ import { COMPOSER_PILL_CLEARANCE, composerPillStyles } from "./pill-styles";
  * on every platform.
  *
  * The bar floats over the transcript with no background, so content remains visible underneath.
- * Its host gives the scroll viewport a small bottom inset only when the bar exists; that keeps
- * the final footer clear without turning the overlay into a layout band.
+ * Its host gives the scroll viewport a small bottom inset for as long as the bar is mounted, with
+ * or without pills: that keeps the final footer clear, and pills that come and go every turn do not
+ * move the transcript.
  */
 export function ComposerTrackBar({ children }: { children: ReactNode }): ReactElement {
+  const scrollGesture = usePanelAwareHorizontalScrollGesture();
+  const scrollBoundary = useHorizontalScrollBoundary();
   return (
     <View style={styles.bar} pointerEvents="box-none">
-      <View style={styles.track} pointerEvents="box-none">
-        {children}
+      <View style={styles.trackViewport} pointerEvents="box-none">
+        <GestureDetector gesture={scrollGesture}>
+          <Animated.ScrollView
+            testID="composer-track-scroll"
+            style={styles.trackScroller}
+            horizontal
+            keyboardShouldPersistTaps="handled"
+            showsHorizontalScrollIndicator={false}
+            onLayout={scrollBoundary.onLayout}
+            onContentSizeChange={scrollBoundary.onContentSizeChange}
+            onScroll={scrollBoundary.onScroll}
+            scrollEventThrottle={16}
+          >
+            <View style={styles.track} pointerEvents="box-none">
+              {children}
+            </View>
+          </Animated.ScrollView>
+        </GestureDetector>
+        <HorizontalScrollBoundaryShades
+          visible
+          backdrop="surface"
+          testIDPrefix="composer-track-scroll-shade"
+          bottomInset={0}
+          leftStyle={scrollBoundary.leftShadeStyle}
+          rightStyle={scrollBoundary.rightShadeStyle}
+        />
       </View>
     </View>
   );
@@ -342,16 +377,17 @@ const styles = StyleSheet.create((theme) => {
   // The rail every panel row sits on: inset from the panel edge so the fill is a rounded block
   // inside it, and tall enough that revealing an action button cannot resize the row.
   //
-  // Compact and desktop differ here and only here. A finger needs the taller row a menu row gets
-  // on compact; a pointer does not, and the popover keeps its density.
+  // Touch and pointer sizing differ here and only here. A finger needs the row a menu row gets
+  // on touch (`MENU_ITEM_HEIGHT` is always its touch value at `xs`); a pointer does not, and the
+  // popover keeps its density.
   const trackRow = {
     flexDirection: "row",
     alignItems: "center",
     gap: theme.spacing[2],
-    minHeight: { xs: MENU_ITEM_HEIGHT.xs, md: 32 },
+    minHeight: bySizing({ touch: MENU_ITEM_HEIGHT.xs, pointer: 32 }),
     marginHorizontal: theme.spacing[1],
     paddingHorizontal: theme.spacing[2],
-    paddingVertical: { xs: theme.spacing[2], md: theme.spacing[1] },
+    paddingVertical: bySizing({ touch: theme.spacing[2], pointer: theme.spacing[1] }),
     borderRadius: theme.borderRadius.md,
   } as const;
 
@@ -368,9 +404,21 @@ const styles = StyleSheet.create((theme) => {
         md: COMPOSER_PILL_CLEARANCE.wide,
       },
     },
-    track: {
+    trackViewport: {
       width: "100%",
       maxWidth: theme.contentMaxWidth,
+      minWidth: 0,
+      flexGrow: 0,
+      flexShrink: 1,
+    },
+    // Only as wide as its pills, so the rest of the row passes touches to the transcript. The
+    // scroller can't use box-none for that: Android's horizontal ScrollView won't scroll with it.
+    trackScroller: {
+      alignSelf: "flex-start",
+      // Web sizes a flex-start scroller to its content, so without a cap it overflows the bar.
+      maxWidth: "100%",
+    },
+    track: {
       flexDirection: "row",
       alignItems: "center",
       gap: theme.spacing[1],
diff --git a/packages/app/src/constants/layout.ts b/packages/app/src/constants/layout.ts
index 739be45ee9..ee30a611ff 100644
--- a/packages/app/src/constants/layout.ts
+++ b/packages/app/src/constants/layout.ts
@@ -1,14 +1,19 @@
 import { useUnistyles } from "react-native-unistyles";
+import { bySizing, TOUCH_TARGET } from "@/components/ui/control-sizing";
 import { isWeb } from "@/constants/platform";
 
 export const FOOTER_HEIGHT = 75;
 
-// Shared header inner height (excluding safe area insets and border)
+// A bar of icon buttons: touch-sized it is one touch target tall, like an iOS navigation bar.
+const BAR_HEIGHT = { touch: TOUCH_TARGET, pointer: 36 };
+
+// Shared header inner height from `md` up (excluding safe area insets and border).
 // Used by both agent header (ScreenHeader) and explorer sidebar header
 // This ensures both headers have the same visual height
-export const HEADER_INNER_HEIGHT = 36;
+export const HEADER_INNER_HEIGHT = bySizing(BAR_HEIGHT).md;
 export const HEADER_INNER_HEIGHT_MOBILE = 56;
-export const WORKSPACE_SECONDARY_HEADER_HEIGHT = 36;
+/** The tab rail and pane toolbars under the header. A breakpoint value for stylesheets. */
+export const WORKSPACE_SECONDARY_HEADER_HEIGHT = bySizing(BAR_HEIGHT);
 export const HEADER_TOP_PADDING_MOBILE = 8;
 
 // Measured composer width; independent of the window's compact/wide breakpoint.
diff --git a/packages/app/src/contexts/session-context.tsx b/packages/app/src/contexts/session-context.tsx
index 1307407647..324f500586 100644
--- a/packages/app/src/contexts/session-context.tsx
+++ b/packages/app/src/contexts/session-context.tsx
@@ -12,7 +12,6 @@ import {
   refreshAgentInitializationTimeout,
 } from "@/hooks/use-agent-initialization";
 import type { StreamItem } from "@/types/stream";
-import { deriveAgentStreamTurnLiveness } from "@/timeline/session-stream-reducers";
 import { planTimelineTailFetch } from "@/timeline/timeline-sync-plan";
 import { requestTimelineReplacement } from "@/timeline/timeline-replacement";
 import { type ViewedTimelineOwner } from "@/timeline/viewed-timeline-sync";
@@ -360,8 +359,6 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
     const onStream = (message: SessionOutboundMessage) => {
       if (message.type !== "agent_stream") return;
       const { agentId, event, timestamp, seq, epoch } = message.payload;
-      const parsedTimestamp = new Date(timestamp);
-      const streamEvent = event;
       if (
         event.type === "turn_started" ||
         event.type === "turn_completed" ||
@@ -370,18 +367,7 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
       ) {
         voiceRuntime?.onTurnEvent(serverId, agentId, event.type);
       }
-      const turnLiveness = deriveAgentStreamTurnLiveness([
-        { event: streamEvent, seq, epoch, timestamp: parsedTimestamp },
-      ]);
-      if (turnLiveness.length > 0) {
-        getHostRuntimeStore().applyAgentTurnLiveness(serverId, agentId, turnLiveness);
-      }
-      sync.enqueueStreamEvent(agentId, {
-        event: streamEvent,
-        seq,
-        epoch,
-        timestamp: parsedTimestamp,
-      });
+      sync.applyStreamEvent(agentId, { event, seq, epoch, timestamp: new Date(timestamp) });
 
       // NOTE: We don't update lastActivityAt on every stream event to prevent
       // cascading rerenders. The agent_update handler updates agent.lastActivityAt
@@ -402,7 +388,7 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
     const onRewind = (message: SessionOutboundMessage) => {
       if (message.type !== "agent.timeline.rewind") return;
       const { agentId, epoch, seq, retireFromSeq } = message.payload;
-      sync.enqueueStreamEvent(agentId, {
+      sync.applyStreamEvent(agentId, {
         event: { type: "rewind", retireFromSeq },
         seq,
         epoch,
@@ -410,8 +396,10 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
       });
     };
     const sync = getHostRuntimeStore().createViewedTimelineOwner(serverId, {
-      observe: (agentIds) => {
-        const observation = client.observeTimeline(agentIds);
+      canCheckFreshness: () =>
+        client.getLastServerInfoMessage()?.features?.timelineFreshnessCheck === true,
+      observe: (agentIds, cursors) => {
+        const observation = client.observeTimeline(agentIds, { cursors });
         observation.subscribe({
           snapshot: () => {},
           update: (message) => {
diff --git a/packages/app/src/contexts/session-workspace-upserts.test.ts b/packages/app/src/contexts/session-workspace-upserts.test.ts
index c0c3bea91f..7e942f234b 100644
--- a/packages/app/src/contexts/session-workspace-upserts.test.ts
+++ b/packages/app/src/contexts/session-workspace-upserts.test.ts
@@ -4,7 +4,10 @@ import {
   clearWorkspaceArchivePending,
   isWorkspaceArchivePending,
   markWorkspaceArchivePending,
+  markWorkspaceArchiveUndoPending,
   shouldSuppressWorkspaceForLocalArchive,
+  settleWorkspaceArchiveIntent,
+  shouldSuppressWorkspaceRemovalForLocalUndo,
 } from "@/contexts/session-workspace-upserts";
 
 const baseWorkspace: WorkspaceDescriptor = {
@@ -116,3 +119,41 @@ describe("workspace archive pending suppression", () => {
     clearWorkspaceArchivePending({ serverId: "server-1", workspaceId: "/repo/worktree" });
   });
 });
+
+describe("workspace archive undo intent", () => {
+  const target = { serverId: "server-1", workspaceId: "/repo/worktree" };
+
+  it("lets host upserts through and holds host removes while an undo is pending", () => {
+    markWorkspaceArchivePending(target);
+    const undo = markWorkspaceArchiveUndoPending(target);
+
+    expect({
+      upsertSuppressed: shouldSuppressWorkspaceForLocalArchive({
+        serverId: target.serverId,
+        workspace: workspace({ archivingAt: null }),
+      }),
+      removeSuppressed: shouldSuppressWorkspaceRemovalForLocalUndo(target),
+    }).toEqual({ upsertSuppressed: false, removeSuppressed: true });
+
+    settleWorkspaceArchiveIntent(undo);
+    expect(shouldSuppressWorkspaceRemovalForLocalUndo(target)).toBe(false);
+  });
+
+  it("keeps a newer intent when the request behind an older one settles late", () => {
+    const firstArchive = markWorkspaceArchivePending(target);
+    const firstUndo = markWorkspaceArchiveUndoPending(target);
+    settleWorkspaceArchiveIntent(firstArchive);
+    clearWorkspaceArchivePending(target);
+    expect(shouldSuppressWorkspaceRemovalForLocalUndo(target)).toBe(true);
+
+    markWorkspaceArchivePending(target);
+    settleWorkspaceArchiveIntent(firstUndo);
+    expect(isWorkspaceArchivePending(target)).toBe(true);
+
+    const secondUndo = markWorkspaceArchiveUndoPending(target);
+    settleWorkspaceArchiveIntent(firstUndo);
+    expect(shouldSuppressWorkspaceRemovalForLocalUndo(target)).toBe(true);
+
+    settleWorkspaceArchiveIntent(secondUndo);
+  });
+});
diff --git a/packages/app/src/contexts/session-workspace-upserts.ts b/packages/app/src/contexts/session-workspace-upserts.ts
index 1b4279631f..2957a90b0d 100644
--- a/packages/app/src/contexts/session-workspace-upserts.ts
+++ b/packages/app/src/contexts/session-workspace-upserts.ts
@@ -1,77 +1,142 @@
 import type { WorkspaceDescriptor } from "@/stores/session-store";
 import { normalizeWorkspaceOpaqueId } from "@/utils/workspace-identity";
 
-interface PendingWorkspaceArchive {
-  workspaceId: string;
+/**
+ * What this client last asked the host to do with a workspace, while the host catches up.
+ *
+ * - `archive`: the row is hidden; host upserts for it are dropped until its remove arrives.
+ * - `undo`: the row is back; host removes for it are dropped until the undo response arrives.
+ *
+ * Each request gets its own intent. A request settles or checks only the intent it set, so a
+ * late response for an earlier request never touches the intent of a newer one.
+ */
+export interface WorkspaceArchiveIntent {
+  readonly kind: "archive" | "undo";
 }
 
-const pendingWorkspaceArchivesByServer = new Map<string, Map<string, PendingWorkspaceArchive>>();
+const intentsByServer = new Map<string, Map<string, WorkspaceArchiveIntent>>();
+const intentListeners = new Set<() => void>();
+const targetByIntent = new WeakMap<
+  WorkspaceArchiveIntent,
+  { serverId: string; workspaceId: string }
+>();
 
-function pendingArchiveKey(input: { serverId: string; workspaceId: string }): string {
-  return `${input.serverId.trim()}::${input.workspaceId.trim()}`;
+interface WorkspaceIntentTarget {
+  serverId: string;
+  workspaceId?: string | null;
+}
+
+function resolveTarget(
+  input: WorkspaceIntentTarget,
+): { serverId: string; workspaceId: string } | null {
+  const serverId = input.serverId.trim();
+  const workspaceId = normalizeWorkspaceOpaqueId(input.workspaceId);
+  if (!serverId || !workspaceId) return null;
+  return { serverId, workspaceId };
+}
+
+function readIntent(input: WorkspaceIntentTarget): WorkspaceArchiveIntent | null {
+  const target = resolveTarget(input);
+  if (!target) return null;
+  return intentsByServer.get(target.serverId)?.get(target.workspaceId) ?? null;
+}
+
+function setIntent(
+  input: WorkspaceIntentTarget,
+  kind: WorkspaceArchiveIntent["kind"],
+): WorkspaceArchiveIntent {
+  const intent: WorkspaceArchiveIntent = { kind };
+  const target = resolveTarget(input);
+  if (!target) return intent;
+  targetByIntent.set(intent, target);
+  const intents = intentsByServer.get(target.serverId) ?? new Map();
+  intents.set(target.workspaceId, intent);
+  intentsByServer.set(target.serverId, intents);
+  notifyIntentListeners();
+  return intent;
+}
+
+function deleteIntent(target: { serverId: string; workspaceId: string }): void {
+  const intents = intentsByServer.get(target.serverId);
+  if (!intents) return;
+  intents.delete(target.workspaceId);
+  if (intents.size === 0) intentsByServer.delete(target.serverId);
+  notifyIntentListeners();
+}
+
+function notifyIntentListeners(): void {
+  for (const listener of intentListeners) listener();
+}
+
+/** Calls `listener` whenever any workspace's archive intent changes. */
+export function subscribeWorkspaceArchiveIntents(listener: () => void): () => void {
+  intentListeners.add(listener);
+  return () => {
+    intentListeners.delete(listener);
+  };
+}
+
+function clearIntentOfKind(
+  input: WorkspaceIntentTarget,
+  kind: WorkspaceArchiveIntent["kind"],
+): void {
+  const target = resolveTarget(input);
+  if (!target || readIntent(target)?.kind !== kind) return;
+  deleteIntent(target);
+}
+
+/** True while `intent` is still the latest thing this client asked for its workspace. */
+export function isWorkspaceArchiveIntentCurrent(intent: WorkspaceArchiveIntent): boolean {
+  const target = targetByIntent.get(intent);
+  return target !== undefined && readIntent(target) === intent;
+}
+
+/** The request behind `intent` settled. A newer request's intent stays in place. */
+export function settleWorkspaceArchiveIntent(intent: WorkspaceArchiveIntent): void {
+  const target = targetByIntent.get(intent);
+  if (target && readIntent(target) === intent) deleteIntent(target);
 }
 
 export function markWorkspaceArchivePending(input: {
   serverId: string;
   workspaceId: string;
-}): void {
-  const serverId = input.serverId.trim();
-  const workspaceId = normalizeWorkspaceOpaqueId(input.workspaceId);
-  if (!serverId || !workspaceId) {
-    return;
-  }
-
-  const archives = pendingWorkspaceArchivesByServer.get(serverId) ?? new Map();
-  archives.set(pendingArchiveKey({ serverId, workspaceId }), {
-    workspaceId,
-  });
-  pendingWorkspaceArchivesByServer.set(serverId, archives);
+}): WorkspaceArchiveIntent {
+  return setIntent(input, "archive");
 }
 
+/** The host removed the workspace, which settles whichever archive this client has pending. */
 export function clearWorkspaceArchivePending(input: {
   serverId: string;
   workspaceId: string;
 }): void {
-  const serverId = input.serverId.trim();
-  const workspaceId = normalizeWorkspaceOpaqueId(input.workspaceId);
-  if (!serverId || !workspaceId) {
-    return;
-  }
-
-  const archives = pendingWorkspaceArchivesByServer.get(serverId);
-  if (!archives) {
-    return;
-  }
-  archives.delete(pendingArchiveKey({ serverId, workspaceId }));
-  if (archives.size === 0) {
-    pendingWorkspaceArchivesByServer.delete(serverId);
-  }
+  clearIntentOfKind(input, "archive");
 }
 
-export function isWorkspaceArchivePending(input: {
+export function isWorkspaceArchivePending(input: WorkspaceIntentTarget): boolean {
+  return readIntent(input)?.kind === "archive";
+}
+
+export function markWorkspaceArchiveUndoPending(input: {
   serverId: string;
-  workspaceId?: string | null;
-}): boolean {
-  const serverId = input.serverId.trim();
-  if (!serverId) {
-    return false;
-  }
+  workspaceId: string;
+}): WorkspaceArchiveIntent {
+  return setIntent(input, "undo");
+}
 
-  const archives = pendingWorkspaceArchivesByServer.get(serverId);
-  if (!archives) {
-    return false;
-  }
-
-  const workspaceId = normalizeWorkspaceOpaqueId(input.workspaceId);
-  return Boolean(workspaceId && archives.has(pendingArchiveKey({ serverId, workspaceId })));
+export function isWorkspaceArchiveUndoPending(input: WorkspaceIntentTarget): boolean {
+  return readIntent(input)?.kind === "undo";
 }
 
 export function shouldSuppressWorkspaceForLocalArchive(input: {
   serverId: string;
   workspace: WorkspaceDescriptor;
 }): boolean {
-  return isWorkspaceArchivePending({
-    serverId: input.serverId,
-    workspaceId: input.workspace.id,
-  });
+  return isWorkspaceArchivePending({ serverId: input.serverId, workspaceId: input.workspace.id });
+}
+
+export function shouldSuppressWorkspaceRemovalForLocalUndo(input: {
+  serverId: string;
+  workspaceId: string;
+}): boolean {
+  return isWorkspaceArchiveUndoPending(input);
 }
diff --git a/packages/app/src/create-agent-preferences/preferences.test.ts b/packages/app/src/create-agent-preferences/preferences.test.ts
index b30b2a66ca..543b49bb1c 100644
--- a/packages/app/src/create-agent-preferences/preferences.test.ts
+++ b/packages/app/src/create-agent-preferences/preferences.test.ts
@@ -80,7 +80,7 @@ describe("create agent preferences", () => {
         modelId: "gpt-5.5",
         modeId: "full-access",
         thinkingOptionId: "high",
-        featureValues: { fast_mode: true },
+        options: { service_tier: "fast" },
       }),
     );
 
@@ -95,7 +95,7 @@ describe("create agent preferences", () => {
           model: "gpt-5.5",
           mode: "full-access",
           thinkingByModel: { "gpt-5.5": "high" },
-          featureValues: { fast_mode: true },
+          options: { service_tier: "fast" },
         },
       },
     });
@@ -119,7 +119,7 @@ describe("create agent preferences", () => {
           model: "gpt-5.6",
           mode: undefined,
           thinkingByModel: undefined,
-          featureValues: undefined,
+          options: undefined,
         },
       }),
     ).toEqual({
@@ -167,13 +167,13 @@ describe("create agent preferences", () => {
         modelId: "one-minute-stream",
         modeId: "approval-test",
         thinkingOptionId: "",
-        featureValues: {},
+        options: {},
       }),
     ).toEqual({
       provider: "mock",
       providerPreferences: {
         pi: { model: "anthropic/sonnet" },
-        mock: { model: "one-minute-stream", mode: "approval-test", featureValues: {} },
+        mock: { model: "one-minute-stream", mode: "approval-test", options: {} },
       },
     });
   });
@@ -208,6 +208,60 @@ describe("create agent preferences", () => {
     });
   });
 
+  it("reads preferences saved as featureValues as options", () => {
+    expect(
+      parseFormPreferences({
+        provider: "codex",
+        providerPreferences: { codex: { featureValues: { service_tier: "priority" } } },
+      }),
+    ).toEqual({
+      provider: "codex",
+      providerPreferences: { codex: { options: { service_tier: "priority" } } },
+    });
+  });
+
+  it("reads a remembered Codex fast_mode as the service tier it meant, so the draft shows Fast", () => {
+    expect(
+      parseFormPreferences({
+        provider: "codex",
+        providerPreferences: {
+          codex: { options: { fast_mode: true, sandbox_mode: "read-only" } },
+          claude: { options: { fast_mode: true } },
+        },
+      }),
+    ).toEqual({
+      provider: "codex",
+      providerPreferences: {
+        codex: { options: { service_tier: "fast", sandbox_mode: "read-only" } },
+        claude: { options: { fast_mode: true } },
+      },
+    });
+
+    expect(
+      parseFormPreferences({
+        providerPreferences: { codex: { featureValues: { fast_mode: false } } },
+      }),
+    ).toEqual({ providerPreferences: { codex: { options: { service_tier: "default" } } } });
+
+    // A tier already remembered wins over the key it replaced.
+    expect(
+      parseFormPreferences({
+        providerPreferences: { codex: { options: { fast_mode: true, service_tier: "default" } } },
+      }),
+    ).toEqual({ providerPreferences: { codex: { options: { service_tier: "default" } } } });
+  });
+
+  it("keeps options that are not booleans or strings, such as a profile's sandbox settings", () => {
+    const options = {
+      sandbox_workspace_write: { network_access: true, writable_roots: ["/tmp"] },
+      max_turns: 3,
+    };
+
+    expect(
+      parseFormPreferences({ provider: "codex", providerPreferences: { codex: { options } } }),
+    ).toEqual({ provider: "codex", providerPreferences: { codex: { options } } });
+  });
+
   it("rejects unknown persisted fields outside the explicit legacy shape", () => {
     expect(parseFormPreferences({ provider: "codex", surprise: true })).toEqual({});
   });
diff --git a/packages/app/src/create-agent-preferences/preferences.ts b/packages/app/src/create-agent-preferences/preferences.ts
index bdade894e8..cd9d012fe7 100644
--- a/packages/app/src/create-agent-preferences/preferences.ts
+++ b/packages/app/src/create-agent-preferences/preferences.ts
@@ -1,13 +1,14 @@
 import { z } from "zod";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
 
-const featureValuesSchema = z.record(z.string(), z.union([z.boolean(), z.string(), z.null()]));
+const optionsSchema = z.record(z.string(), z.json());
 
 export interface ProviderPreferences {
   model?: string;
   mode?: string;
   thinkingByModel?: Record<string, string>;
-  featureValues?: Record<string, unknown>;
+  /** Last-used values of the provider's option controls, by option key. */
+  options?: Record<string, unknown>;
 }
 
 export type LaunchTarget = { kind: "chat" } | { kind: "terminal"; profileId: string };
@@ -20,12 +21,41 @@ export interface FormPreferences {
   launchTarget?: LaunchTarget;
 }
 
-const providerPreferencesSchema: z.ZodType<ProviderPreferences> = z.strictObject({
-  model: z.string().optional(),
-  mode: z.string().optional(),
-  thinkingByModel: z.record(z.string(), z.string()).optional(),
-  featureValues: featureValuesSchema.optional(),
-});
+// COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01. Preferences written
+// before the rename stored the same record as `featureValues`.
+function renameLegacyFeatureValues(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || !("featureValues" in value)) return value;
+  const { featureValues, ...rest } = value as { featureValues: unknown } & Record<string, unknown>;
+  return "options" in rest ? rest : { ...rest, options: featureValues };
+}
+
+const providerPreferencesSchema: z.ZodType<ProviderPreferences> = z.preprocess(
+  renameLegacyFeatureValues,
+  z.strictObject({
+    model: z.string().optional(),
+    mode: z.string().optional(),
+    thinkingByModel: z.record(z.string(), z.string()).optional(),
+    options: optionsSchema.optional(),
+  }),
+);
+
+// COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Codex took `fast_mode`
+// before `service_tier`; the daemon converts the option on every agent and profile it touches,
+// and this is the one place the app reads a remembered value without the daemon in between. Keyed
+// on the built-in provider id: a custom provider extending Codex keeps the old key and the daemon
+// still converts it on create.
+function convertLegacyCodexOptions(
+  preferences: Record<string, ProviderPreferences>,
+): Record<string, ProviderPreferences> {
+  const codex = preferences.codex;
+  if (!codex?.options || !("fast_mode" in codex.options)) return preferences;
+  const { fast_mode: legacy, ...rest } = codex.options;
+  const options =
+    "service_tier" in rest || typeof legacy !== "boolean"
+      ? rest
+      : { ...rest, service_tier: legacy ? "fast" : "default" };
+  return { ...preferences, codex: { ...codex, options } };
+}
 
 const launchTargetSchema: z.ZodType<LaunchTarget> = z.discriminatedUnion("kind", [
   z.strictObject({ kind: z.literal("chat") }),
@@ -34,7 +64,10 @@ const launchTargetSchema: z.ZodType<LaunchTarget> = z.discriminatedUnion("kind",
 
 export const FormPreferencesSchema = z.strictObject({
   provider: z.string().optional(),
-  providerPreferences: z.record(z.string(), providerPreferencesSchema).optional(),
+  providerPreferences: z
+    .record(z.string(), providerPreferencesSchema)
+    .transform(convertLegacyCodexOptions)
+    .optional(),
   // COMPAT(agentProfileFavoriteMigration): favourites were removed in v0.3.2.
   // Keep the legacy payload alive until every capable host has had a chance to
   // import it; ordinary preference writes must not erase it first.
@@ -116,7 +149,7 @@ function applyProviderPreferenceUpdates(
 ): ProviderPreferences {
   const next: ProviderPreferences = { ...existing };
   const nextThinkingByModel = mergeDefinedRecord(existing.thinkingByModel, updates.thinkingByModel);
-  const nextFeatureValues = mergeDefinedRecord(existing.featureValues, updates.featureValues);
+  const nextOptions = mergeDefinedRecord(existing.options, updates.options);
 
   if (updates.model !== undefined) {
     next.model = updates.model;
@@ -129,8 +162,8 @@ function applyProviderPreferenceUpdates(
   if (nextThinkingByModel !== undefined) {
     next.thinkingByModel = nextThinkingByModel;
   }
-  if (nextFeatureValues !== undefined) {
-    next.featureValues = nextFeatureValues;
+  if (nextOptions !== undefined) {
+    next.options = nextOptions;
   }
 
   return next;
@@ -161,7 +194,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
   modelId?: string | null;
   modeId?: string | null;
   thinkingOptionId?: string | null;
-  featureValues?: Record<string, unknown>;
+  options?: Record<string, unknown>;
 }): FormPreferences {
   if (!args.provider) {
     return args.preferences;
@@ -170,7 +203,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
   const modelId = args.modelId?.trim() ?? "";
   const modeId = args.modeId?.trim() ?? "";
   const thinkingOptionId = args.thinkingOptionId?.trim() ?? "";
-  const featureValues = featureValuesSchema.safeParse(args.featureValues);
+  const options = optionsSchema.safeParse(args.options);
 
   return mergeProviderPreferences({
     preferences: args.preferences,
@@ -179,7 +212,7 @@ export function mergeCreateAgentSelectionPreferences(args: {
       model: modelId || undefined,
       mode: args.modeId === undefined ? undefined : modeId || null,
       ...(modelId && thinkingOptionId ? { thinkingByModel: { [modelId]: thinkingOptionId } } : {}),
-      ...(featureValues.success ? { featureValues: featureValues.data } : {}),
+      ...(options.success ? { options: options.data } : {}),
     },
   });
 }
@@ -192,7 +225,7 @@ export function applyAgentProfilePreferences(args: {
   modelId: string;
   modeId: string;
   thinkingOptionId: string;
-  featureValues: Record<string, unknown>;
+  options: Record<string, unknown>;
 }): FormPreferences {
   let next = args.preferences;
   if (args.previousProvider) {
@@ -215,7 +248,7 @@ export function applyAgentProfilePreferences(args: {
       ...(args.modelId && args.thinkingOptionId
         ? { thinkingByModel: { [args.modelId]: args.thinkingOptionId } }
         : {}),
-      featureValues: args.featureValues,
+      options: args.options,
     },
   });
 }
diff --git a/packages/app/src/data/acp-provider-catalog.ts b/packages/app/src/data/acp-provider-catalog.ts
index 46b7d81a2d..bfa7ffe3cf 100644
--- a/packages/app/src/data/acp-provider-catalog.ts
+++ b/packages/app/src/data/acp-provider-catalog.ts
@@ -1,4 +1,5 @@
 import { ACP_PROVIDER_ICON_SVGS } from "@/assets/acp-provider-icons";
+import type { HostFeatureName } from "@/runtime/host-features";
 
 export interface AcpProviderCatalogEntry {
   id: string;
@@ -8,7 +9,7 @@ export interface AcpProviderCatalogEntry {
   iconSvg: string | null;
   installLink: string;
   command: readonly [string, ...string[]];
-  bundledProvider?: boolean;
+  bundledProvider?: { readonly hostFeature: HostFeatureName };
   env?: Readonly<Record<string, string>>;
   params?: Readonly<Record<string, unknown>>;
 }
@@ -179,6 +180,16 @@ const CATALOG_DATA = [
     installLink: "https://fast-agent.ai/acp/",
     command: ["uvx", "--from", "fast-agent-acp==0.10.47", "fast-agent-acp", "-x"],
   },
+  {
+    id: "fx",
+    bundledProvider: { hostFeature: "fxProvider" },
+    title: "fx",
+    description: "Vercel Labs' tiny, open, native coding agent",
+    version: "manual",
+    iconId: "fx",
+    installLink: "https://fx.sh/docs/getting-started/installation",
+    command: ["fx", "acp"],
+  },
   {
     id: "gemini",
     title: "Gemini CLI",
@@ -241,7 +252,7 @@ const CATALOG_DATA = [
   },
   {
     id: "hoplite",
-    bundledProvider: true,
+    bundledProvider: { hostFeature: "hopliteProvider" },
     title: "Hoplite",
     description: "Cloud coding agent through the local hoplite acp bridge",
     version: "manual",
diff --git a/packages/app/src/data/providers-snapshot.ts b/packages/app/src/data/providers-snapshot.ts
index 68b389fe15..b2fe4bed11 100644
--- a/packages/app/src/data/providers-snapshot.ts
+++ b/packages/app/src/data/providers-snapshot.ts
@@ -8,7 +8,7 @@ import {
 } from "./provider-snapshot-cache";
 import { queryClient as singletonQueryClient } from "./query-client";
 import { replaceProviderSnapshotIcons } from "@/data/provider-icons";
-import { agentCommandsQueryRoot } from "@/hooks/agent-commands-query";
+import { agentCommandsQueryRoot } from "@/agent-commands/cache";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
 import { normalizeWorkspacePath } from "@/utils/workspace-identity";
 
@@ -119,6 +119,36 @@ export async function fetchProvidersSnapshot(input: {
   return snapshot;
 }
 
+/**
+ * The providers snapshot as a replica query: its key and its fetch together, so the model picker
+ * and anything else that needs the catalog read the same cache entry. `client` is asked when the
+ * fetch runs.
+ */
+export function providersSnapshotQuery(input: {
+  serverId: string;
+  cwd?: string | null;
+  client: () => SnapshotClient;
+  queryClient?: QueryClient;
+  cache?: ProviderSnapshotCache;
+}) {
+  const cwd = normalizeProvidersSnapshotCwd(input.cwd);
+  return {
+    queryKey: providersSnapshotQueryKey(input.serverId, cwd),
+    // The content-hash cache already owns catalog and model identity.
+    structuralSharing: false as const,
+    pushEvent: "providers_snapshot_update",
+    queryFn: ({ signal }: { signal: AbortSignal }) =>
+      fetchProvidersSnapshot({
+        client: input.client(),
+        serverId: input.serverId,
+        cwd,
+        queryClient: input.queryClient,
+        cache: input.cache,
+        signal,
+      }),
+  };
+}
+
 export async function refreshAndApplyProvidersSnapshot(input: {
   client: SnapshotClient & Pick<DaemonClient, "refreshProvidersSnapshot">;
   queryClient: QueryClient;
diff --git a/packages/app/src/data/push-router.test.ts b/packages/app/src/data/push-router.test.ts
index 6599c28467..cf5a4d5af6 100644
--- a/packages/app/src/data/push-router.test.ts
+++ b/packages/app/src/data/push-router.test.ts
@@ -1,7 +1,9 @@
-import type { OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
+import type { DiffState, OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
 import { QueryClient, QueryObserver, skipToken } from "@tanstack/react-query";
 import { describe, expect, it } from "vitest";
 import type { MutableDaemonConfig, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { deriveCheckoutDiffResult, type CheckoutDiffSnapshot } from "@/git/diff-snapshot";
+import { shareCheckoutDiff } from "@/git/diff-sharing";
 import { checkoutDiffQueryKey } from "@/git/query-keys";
 import { buildTerminalsQueryKey } from "@/screens/workspace/terminals/state";
 import { daemonConfigQueryKey } from "@/data/daemon-config";
@@ -34,6 +36,7 @@ type RouterMessage =
 type RouterMessageType = RouterMessage["type"];
 type RouterHandler = (message: RouterMessage) => void;
 type RouterClient = Parameters<typeof mountServerDataPushRouter>[0]["client"];
+type DiffFile = SubscribeCheckoutDiffResponseMessage["payload"]["files"][number];
 
 const daemonConfig: MutableDaemonConfig = {
   relay: { enabled: false },
@@ -55,8 +58,8 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
     subscriptionId: string;
   }>;
   unsubscribeCheckoutDiffCalls: string[];
-  subscribeTerminalCalls: Array<{ cwd: string; workspaceId?: string }>;
-  unsubscribeTerminalCalls: Array<{ cwd: string; workspaceId?: string }>;
+  subscribeTerminalCalls: Array<{ cwd?: string; workspaceId?: string }>;
+  unsubscribeTerminalCalls: Array<{ cwd?: string; workspaceId?: string }>;
 } {
   const handlers: Record<RouterMessageType, RouterHandler[]> = {
     providers_snapshot_update: [],
@@ -71,8 +74,8 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
     subscriptionId: string;
   }> = [];
   const unsubscribeCheckoutDiffCalls: string[] = [];
-  const subscribeTerminalCalls: Array<{ cwd: string; workspaceId?: string }> = [];
-  const unsubscribeTerminalCalls: Array<{ cwd: string; workspaceId?: string }> = [];
+  const subscribeTerminalCalls: Array<{ cwd?: string; workspaceId?: string }> = [];
+  const unsubscribeTerminalCalls: Array<{ cwd?: string; workspaceId?: string }> = [];
 
   function on<K extends RouterMessageType>(
     type: K,
@@ -144,10 +147,21 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
           ["status", "providers_snapshot_update"],
           () => {},
         ),
-      observeCheckoutDiff(cwd, compare) {
+      observeDiff(input) {
+        const cwd = input.cwd;
+        let mode: "uncommitted" | "base" | "all" = "uncommitted";
+        if (input.head.kind === "rev") mode = "base";
+        else if (input.mergeBase) mode = "all";
+        const compare = {
+          mode,
+          ...(input.base.kind === "rev" && input.base.rev !== "HEAD"
+            ? { baseRef: input.base.rev }
+            : {}),
+          ignoreWhitespace: input.ignoreWhitespace,
+        };
         const subscriptionId = `server-diff-${subscribeCheckoutDiffCalls.length + 1}`;
         subscribeCheckoutDiffCalls.push({ cwd, compare, subscriptionId });
-        const handle = observe(
+        const handle = observe<SubscribeCheckoutDiffResponseMessage["payload"]>(
           { subscriptionId, cwd, files: [], error: null, requestId: "subscribe-checkout-diff" },
           ["checkout_diff_update", "subscribe_checkout_diff_response"],
           () => unsubscribeCheckoutDiffCalls.push(subscriptionId),
@@ -155,9 +169,43 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
             "subscriptionId" in message.payload &&
             message.payload.subscriptionId === subscriptionId,
         );
-        if (!config.rejectCheckoutDiffSubscribe) return handle;
-        return {
+        const modern: OwnedSubscription<DiffState> = {
           ...handle,
+          ready: Promise.resolve({
+            phase: "ready",
+            revision: 1,
+            resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+            files: [],
+            diffTooLarge: false,
+            subscriptionId,
+          }),
+          subscribe: (observer) =>
+            handle.subscribe({
+              snapshot: (payload) =>
+                observer.snapshot({
+                  phase: "ready",
+                  revision: 1,
+                  resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                  files: payload.files,
+                  diffTooLarge: payload.diffTooLarge === true,
+                  subscriptionId,
+                }),
+              update: (message) => {
+                if (message.type === "checkout_diff_update")
+                  observer.snapshot({
+                    phase: "ready",
+                    revision: 2,
+                    resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                    files: message.payload.files,
+                    diffTooLarge: message.payload.diffTooLarge === true,
+                    subscriptionId,
+                  });
+              },
+            }),
+        };
+        if (!config.rejectCheckoutDiffSubscribe) return modern;
+        return {
+          ...modern,
           subscribe: (observer) => {
             queueMicrotask(() => observer.error?.(new Error("subscribe failed")));
             return () => {};
@@ -188,6 +236,49 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
   };
 }
 
+/** Matches the real diff observation: nothing is delivered until the stream publishes. */
+type SubscribedDiffState = DiffState & { subscriptionId: string };
+
+function createDiffStreamClient() {
+  const subscriptions: Array<{ publish(state: DiffState): void }> = [];
+  const noSubscription = {
+    subscriptionId: "none",
+    ready: Promise.resolve(undefined as never),
+    subscribe: () => () => {},
+    release: async () => {},
+  };
+  const client: RouterClient = {
+    async getProvidersSnapshot() {
+      throw new Error("Unexpected snapshot pull");
+    },
+    observeEvents: () => noSubscription,
+    observeTerminals: () => noSubscription,
+    observeDiff() {
+      const observers = new Set<SubscriptionObserver<SubscribedDiffState>>();
+      let released = false;
+      const subscriptionId = `diff-${subscriptions.length + 1}`;
+      subscriptions.push({
+        publish: (state) => {
+          if (released) return;
+          for (const observer of observers) observer.snapshot({ ...state, subscriptionId });
+        },
+      });
+      return {
+        subscriptionId,
+        ready: new Promise<never>(() => {}),
+        subscribe: (observer: SubscriptionObserver<SubscribedDiffState>) => {
+          observers.add(observer);
+          return () => observers.delete(observer);
+        },
+        release: async () => {
+          released = true;
+        },
+      };
+    },
+  };
+  return { client, subscriptions, latest: () => subscriptions[subscriptions.length - 1]! };
+}
+
 function providerUpdate(generatedAt: string): ProvidersSnapshotUpdateMessage {
   return {
     type: "providers_snapshot_update",
@@ -328,7 +419,7 @@ describe("server data push router", () => {
       const first = publish(files, "first");
       const same = publish(structuredClone(files), "reopen");
       expect(same.files).toBe(first.files);
-      expect(same.requestId).toBe("reopen");
+      expect(same.requestId).toBe("diff:1:ready");
       const changed = structuredClone(files);
       changed[0]!.hunks[0]!.lines[0]!.tokens![0]!.style = "variable";
       const next = publish(changed, "edit");
@@ -343,6 +434,160 @@ describe("server data push router", () => {
     }
   });
 
+  describe("a diff reopened from a retained panel", () => {
+    const serverId = "server-1";
+    const cwd = "/repo";
+    const queryKey = checkoutDiffQueryKey(serverId, cwd, "uncommitted", undefined, false);
+
+    function diffFile(content: string): DiffFile {
+      return {
+        path: "README.md",
+        isNew: false,
+        isDeleted: false,
+        additions: 1,
+        deletions: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldCount: 1,
+            newStart: 1,
+            newCount: 1,
+            lines: [{ type: "add", content, tokens: [{ text: content, style: null }] }],
+          },
+        ],
+      };
+    }
+
+    function loadingState(revision: number): DiffState {
+      return {
+        phase: "loading",
+        revision,
+        entries: [
+          {
+            path: "README.md",
+            oldPath: null,
+            change: "modified",
+            content: "text",
+            additions: 1,
+            deletions: 0,
+          },
+        ],
+      };
+    }
+
+    function readyState(revision: number, files: DiffFile[]): DiffState {
+      return {
+        phase: "ready",
+        revision,
+        resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+        files,
+        diffTooLarge: false,
+      };
+    }
+
+    function mountChangesPanel(fake: ReturnType<typeof createDiffStreamClient>) {
+      const queryClient = new QueryClient();
+      const route = (enabled: boolean) => ({
+        queryKey,
+        queryFn: skipToken as typeof skipToken,
+        gcTime: Infinity,
+        structuralSharing: shareCheckoutDiff,
+        meta: checkoutDiffPushRoute({
+          enabled,
+          serverId,
+          cwd,
+          subscriptionId: `checkoutDiff:${JSON.stringify(queryKey)}`,
+          compare: { mode: "uncommitted", ignoreWhitespace: false },
+        }),
+      });
+      const observer = new QueryObserver(queryClient, route(true));
+      const unsubscribeObserver = observer.subscribe(() => {});
+      const unmountRouter = mountServerDataPushRouter({
+        queryClient,
+        client: fake.client,
+        serverId,
+      });
+      return {
+        hide: () => observer.setOptions(route(false)),
+        show: () => observer.setOptions(route(true)),
+        // What the Changes pane renders from.
+        diff: () =>
+          deriveCheckoutDiffResult(
+            queryClient.getQueryData<CheckoutDiffSnapshot>(queryKey) ?? null,
+          ),
+        unmount: () => {
+          unsubscribeObserver();
+          unmountRouter();
+          queryClient.clear();
+        },
+      };
+    }
+
+    it("keeps the painted diff through the reload when the daemon returns the same content", () => {
+      const fake = createDiffStreamClient();
+      const panel = mountChangesPanel(fake);
+      try {
+        fake.latest().publish(readyState(1, [diffFile("same")]));
+        const painted = panel.diff().files;
+        expect(fake.subscriptions).toHaveLength(1);
+
+        panel.hide();
+        panel.show();
+        expect(fake.subscriptions).toHaveLength(2);
+
+        fake.latest().publish(loadingState(1));
+        expect(panel.diff()).toMatchObject({ isLoading: false, entries: null });
+        expect(panel.diff().files).toBe(painted);
+
+        fake.latest().publish(readyState(1, [diffFile("same")]));
+        expect(panel.diff().isLoading).toBe(false);
+        expect(panel.diff().files).toBe(painted);
+      } finally {
+        panel.unmount();
+      }
+    });
+
+    it("replaces the painted diff in one step when the daemon returns changed content", () => {
+      const fake = createDiffStreamClient();
+      const panel = mountChangesPanel(fake);
+      try {
+        fake.latest().publish(readyState(1, [diffFile("before")]));
+        const painted = panel.diff().files;
+
+        panel.hide();
+        panel.show();
+        fake.latest().publish(loadingState(1));
+        expect(panel.diff().isLoading).toBe(false);
+        expect(panel.diff().files).toBe(painted);
+
+        const changed = [diffFile("after")];
+        fake.latest().publish(readyState(1, changed));
+        expect(panel.diff().isLoading).toBe(false);
+        expect(panel.diff().files).toEqual(changed);
+      } finally {
+        panel.unmount();
+      }
+    });
+
+    it("reports loading with the announced entries when no content has been painted", () => {
+      const fake = createDiffStreamClient();
+      const panel = mountChangesPanel(fake);
+      try {
+        expect(panel.diff().isLoading).toBe(true);
+
+        fake.latest().publish(loadingState(1));
+        expect(panel.diff()).toMatchObject({ isLoading: true, files: [] });
+        expect(panel.diff().entries).toHaveLength(1);
+
+        fake.latest().publish(readyState(1, [diffFile("first")]));
+        expect(panel.diff()).toMatchObject({ isLoading: false, entries: null });
+        expect(panel.diff().files).toHaveLength(1);
+      } finally {
+        panel.unmount();
+      }
+    });
+  });
+
   it("routes provider snapshot and daemon config payloads until detached", async () => {
     const queryClient = new QueryClient();
     const fake = createFakeClient();
@@ -430,7 +675,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: "diff-1",
+      requestId: "diff:1:ready",
     });
 
     fake.emit({
@@ -449,7 +694,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: `subscription:${serverSubscriptionId}`,
+      requestId: "diff:2:ready",
     });
 
     unsubscribeObserver();
diff --git a/packages/app/src/data/push-router.ts b/packages/app/src/data/push-router.ts
index 75ac313169..5e51ded0d4 100644
--- a/packages/app/src/data/push-router.ts
+++ b/packages/app/src/data/push-router.ts
@@ -1,11 +1,14 @@
+import { checkoutDiffSnapshot, type CheckoutDiffSnapshot } from "@/git/diff-snapshot";
+import type { DiffState } from "@getpaseo/client";
 import type { OwnedSubscription } from "@getpaseo/client";
+import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
 import type { Query, QueryCacheNotifyEvent, QueryClient, QueryKey } from "@tanstack/react-query";
 import type {
   ListTerminalsResponse,
   MutableDaemonConfig,
   SessionOutboundMessage,
 } from "@getpaseo/protocol/messages";
-import { agentCommandsQueryRoot } from "@/hooks/agent-commands-query";
+import { invalidateCommandsForProviderChange } from "@/agent-commands/cache";
 import { shareCheckoutDiff } from "@/git/diff-sharing";
 import { orderCheckoutDiffFiles } from "@/git/diff-order";
 import { daemonConfigQueryKey } from "@/data/daemon-config";
@@ -22,14 +25,9 @@ type ProvidersSnapshotUpdateMessage = Extract<
   SessionOutboundMessage,
   { type: "providers_snapshot_update" }
 >;
-type SubscribeCheckoutDiffResponseMessage = Extract<
-  SessionOutboundMessage,
-  { type: "subscribe_checkout_diff_response" }
->;
 type StatusMessage = Extract<SessionOutboundMessage, { type: "status" }>;
 type TerminalsChangedMessage = Extract<SessionOutboundMessage, { type: "terminals_changed" }>;
-type CheckoutDiffResponsePayload = SubscribeCheckoutDiffResponseMessage["payload"];
-type CheckoutDiffCachePayload = Omit<CheckoutDiffResponsePayload, "subscriptionId">;
+type CheckoutDiffCachePayload = CheckoutDiffSnapshot;
 type ListTerminalsPayload = ListTerminalsResponse["payload"];
 
 interface CheckoutDiffCompare {
@@ -48,7 +46,7 @@ interface CheckoutDiffRoute {
 }
 
 interface CheckoutDiffRegistration extends CheckoutDiffRoute {
-  subscription: OwnedSubscription<CheckoutDiffResponsePayload>;
+  subscription: OwnedSubscription<DiffState>;
 }
 
 interface WorkspaceTerminalsRoute {
@@ -74,7 +72,7 @@ export type ProvidersSnapshotUpdate = ProvidersSnapshotUpdateMessage;
 interface ServerDataPushClient {
   getProvidersSnapshot: import("@getpaseo/client/internal/daemon-client").DaemonClient["getProvidersSnapshot"];
   observeEvents: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeEvents"];
-  observeCheckoutDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeCheckoutDiff"];
+  observeDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeDiff"];
   observeTerminals: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeTerminals"];
 }
 
@@ -186,10 +184,10 @@ export async function applyProvidersSnapshotUpdate(input: {
   const snapshot = { ...input.message.payload, requestId: "providers_snapshot_update" };
   const cwd = normalizeProvidersSnapshotCwd(snapshot.cwd);
   const queryKey = providersSnapshotQueryKey(input.serverId, cwd);
-  const previous = input.queryClient.getQueryData<{ snapshotHash?: string }>(queryKey);
+  const previous = input.queryClient.getQueryData<{ entries: ProviderSnapshotEntry[] }>(queryKey);
   let announcement: typeof snapshot | undefined = snapshot;
   void input.queryClient.cancelQueries({ queryKey, exact: true });
-  await input.queryClient.fetchQuery({
+  const current = await input.queryClient.fetchQuery({
     queryKey,
     staleTime: 0,
     structuralSharing: false,
@@ -205,12 +203,13 @@ export async function applyProvidersSnapshotUpdate(input: {
       });
     },
   });
-  if (!snapshot.snapshotHash || previous?.snapshotHash !== snapshot.snapshotHash) {
-    void input.queryClient.invalidateQueries({
-      queryKey: agentCommandsQueryRoot(input.serverId),
-      exact: false,
-    });
-  }
+  void invalidateCommandsForProviderChange({
+    queryClient: input.queryClient,
+    serverId: input.serverId,
+    cwd,
+    previous: previous?.entries,
+    current: current.entries,
+  });
 }
 
 export function mountServerDataPushRouter(input: PushRouterInput): () => void {
@@ -337,34 +336,34 @@ function reconcileCheckoutDiffSubscriptions(input: {
   }
   for (const [key, desired] of input.desired) {
     if (input.active.has(key)) continue;
-    const subscription = input.client.observeCheckoutDiff(desired.cwd, desired.compare);
+    const { mode, baseRef, ignoreWhitespace } = desired.compare;
+    const revision = mode === "uncommitted" ? "HEAD" : baseRef;
+    if (!revision) continue;
+    const subscription = input.client.observeDiff({
+      cwd: desired.cwd,
+      base: { kind: "rev", rev: revision },
+      head: mode === "base" ? { kind: "rev", rev: "HEAD" } : { kind: "worktree" },
+      mergeBase: mode !== "uncommitted",
+      ignoreWhitespace,
+    });
     const registration = { ...desired, subscription };
     input.active.set(key, registration);
-    const apply = (
-      payload: Omit<CheckoutDiffResponsePayload, "requestId"> & { requestId?: string },
-    ) => {
-      if (input.active.get(key) !== registration) return;
-      const { subscriptionId, ...snapshot } = payload;
-      setCheckoutDiffPayload({
-        activeCheckoutDiffSubscriptions: input.active,
-        queryClient: input.queryClient,
-        serverId: input.serverId,
-        subscriptionId: key,
-        payload: {
-          ...snapshot,
-          files: orderCheckoutDiffFiles(payload.files),
-          requestId: payload.requestId ?? `subscription:${subscriptionId}`,
-        },
-      });
-    };
     subscription.subscribe({
-      snapshot: apply,
-      update: (message) => {
-        if (message.type === "checkout_diff_update") apply(message.payload);
+      snapshot: (state) => {
+        if (input.active.get(key) !== registration) return;
+        const snapshot = checkoutDiffSnapshot(desired.cwd, state);
+        setCheckoutDiffPayload({
+          activeCheckoutDiffSubscriptions: input.active,
+          queryClient: input.queryClient,
+          serverId: input.serverId,
+          subscriptionId: key,
+          payload: { ...snapshot, files: orderCheckoutDiffFiles(snapshot.files) },
+        });
       },
+      update: () => {},
       error: (error) => {
         if (input.active.get(key) === registration) input.active.delete(key);
-        console.error("[server-data] observeCheckoutDiff failed", {
+        console.error("[server-data] observeDiff failed", {
           serverId: input.serverId,
           cwd: desired.cwd,
           error,
diff --git a/packages/app/src/data/query.ts b/packages/app/src/data/query.ts
index 2a645f8666..07f7a622ee 100644
--- a/packages/app/src/data/query.ts
+++ b/packages/app/src/data/query.ts
@@ -27,7 +27,7 @@ type ReplicaQueryInput<TQueryFnData, TError, TData, TQueryKey extends QueryKey>
 
 type FetchQueryInput<TQueryFnData, TError, TData, TQueryKey extends QueryKey> = Omit<
   UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
-  "initialData" | "placeholderData" | "queryFn" | "refetchOnMount" | "staleTime"
+  "initialData" | "placeholderData" | "queryFn" | "staleTime"
 > & {
   dataShape: "list" | "value";
   queryFn: QueryFnOption<TQueryFnData, TError, TData, TQueryKey>;
@@ -41,8 +41,11 @@ export function useReplicaQuery<
   TError = Error,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
->(input: ReplicaQueryInput<TQueryFnData, TError, TData, TQueryKey>): UseQueryResult<TData, TError> {
-  return useQuery(replicaQueryOptions(input));
+>(
+  input: ReplicaQueryInput<TQueryFnData, TError, TData, TQueryKey>,
+  queryClient?: QueryClient,
+): UseQueryResult<TData, TError> {
+  return useQuery(replicaQueryOptions(input), queryClient);
 }
 
 export function useFetchQuery<
@@ -63,7 +66,7 @@ export function useFetchQueries<TData>(
   return useQueries({ queries: inputs.map((input) => fetchQueryOptions(input)) });
 }
 
-function replicaQueryOptions<
+export function replicaQueryOptions<
   TQueryFnData,
   TError = Error,
   TData = TQueryFnData,
@@ -113,7 +116,7 @@ export function fetchQueryOptions<
         dataShape,
       },
     },
-    refetchOnMount: immutableWhen ? true : "always",
+    refetchOnMount: options.refetchOnMount ?? (immutableWhen ? true : "always"),
     staleTime: immutableWhen
       ? (query) =>
           query.state.data !== undefined && immutableWhen(query.state.data) ? Infinity : 0
diff --git a/packages/app/src/desktop/browser/pane/index.electron.tsx b/packages/app/src/desktop/browser/pane/index.electron.tsx
index 674cf419ef..c728c5cd1d 100644
--- a/packages/app/src/desktop/browser/pane/index.electron.tsx
+++ b/packages/app/src/desktop/browser/pane/index.electron.tsx
@@ -1635,10 +1635,10 @@ function BrowserElementAnnotationCard({
           initialValue={comment}
         />
         <View style={styles.annotationActions}>
-          <Button variant="ghost" size="sm" onPress={onCancel}>
+          <Button variant="ghost" onPress={onCancel}>
             {t("workspace.browser.annotate.cancel")}
           </Button>
-          <Button variant="default" size="sm" onPress={handleSubmit}>
+          <Button variant="default" onPress={handleSubmit}>
             {t("workspace.browser.annotate.submit")}
           </Button>
         </View>
diff --git a/packages/app/src/desktop/browser/settings/browser-data-section.tsx b/packages/app/src/desktop/browser/settings/browser-data-section.tsx
index ad4140d683..6424750d86 100644
--- a/packages/app/src/desktop/browser/settings/browser-data-section.tsx
+++ b/packages/app/src/desktop/browser/settings/browser-data-section.tsx
@@ -66,7 +66,6 @@ export function BrowserDataSection() {
           </View>
           <Button
             variant="outline"
-            size="sm"
             loading={isClearing}
             disabled={isClearing}
             onPress={handleClear}
diff --git a/packages/app/src/desktop/components/desktop-notifications-section.tsx b/packages/app/src/desktop/components/desktop-notifications-section.tsx
index 60b8bb3b67..4fba4880da 100644
--- a/packages/app/src/desktop/components/desktop-notifications-section.tsx
+++ b/packages/app/src/desktop/components/desktop-notifications-section.tsx
@@ -59,7 +59,6 @@ export function DesktopNotificationsSection() {
     () => (
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={refreshIcon}
         onPress={handleRefreshPress}
         disabled={isPermissionBusy}
@@ -119,7 +118,6 @@ export function DesktopNotificationsSection() {
           </View>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleSendTestNotification}
             disabled={!notificationsGranted || isPermissionBusy || isSendingTestNotification}
           >
diff --git a/packages/app/src/desktop/components/desktop-permission-row.tsx b/packages/app/src/desktop/components/desktop-permission-row.tsx
index a03a3a63d0..5c3360f32b 100644
--- a/packages/app/src/desktop/components/desktop-permission-row.tsx
+++ b/packages/app/src/desktop/components/desktop-permission-row.tsx
@@ -58,7 +58,7 @@ export function DesktopPermissionRow({
             <Text style={styles.permissionStatusText}>{labels.granted}</Text>
           </View>
         ) : (
-          <Button variant="outline" size="sm" onPress={onRequest} disabled={isRequesting}>
+          <Button variant="outline" onPress={onRequest} disabled={isRequesting}>
             {isRequesting ? labels.requesting : labels.request}
           </Button>
         )}
diff --git a/packages/app/src/desktop/components/desktop-permissions-section.tsx b/packages/app/src/desktop/components/desktop-permissions-section.tsx
index 74cc71dc4a..b2c261543b 100644
--- a/packages/app/src/desktop/components/desktop-permissions-section.tsx
+++ b/packages/app/src/desktop/components/desktop-permissions-section.tsx
@@ -41,7 +41,6 @@ export function DesktopPermissionsSection() {
     () => (
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={refreshIcon}
         onPress={handleRefreshPress}
         disabled={isBusy}
diff --git a/packages/app/src/desktop/components/desktop-updates-section.tsx b/packages/app/src/desktop/components/desktop-updates-section.tsx
index bb5c1536a6..4592fa9cae 100644
--- a/packages/app/src/desktop/components/desktop-updates-section.tsx
+++ b/packages/app/src/desktop/components/desktop-updates-section.tsx
@@ -6,11 +6,10 @@ import { useTranslation } from "react-i18next";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { settingsStyles } from "@/styles/settings";
 import { SettingsSection } from "@/components/settings/headings/settings-section";
-import { ArrowUpRight, Copy, FileText, Activity } from "lucide-react-native";
+import { Copy, FileText, Activity } from "lucide-react-native";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
 import { Switch } from "@/components/ui/switch";
-import { openExternalUrl } from "@/utils/open-external-url";
 import { isVersionMismatch } from "@/desktop/updates/desktop-updates";
 import {
   getCliDaemonStatus,
@@ -187,12 +186,10 @@ function DaemonCliStatusModal({
           {cliStatusOutput ?? ""}
         </Text>
         <View style={styles.modalActions}>
-          <Button variant="outline" size="sm" onPress={onClose}>
+          <Button variant="outline" onPress={onClose}>
             {t("common.actions.close")}
           </Button>
-          <Button size="sm" onPress={onCopy}>
-            {t("common.actions.copy")}
-          </Button>
+          <Button onPress={onCopy}>{t("common.actions.copy")}</Button>
         </View>
       </View>
     </AdaptiveModalSheet>
@@ -284,13 +281,12 @@ function DaemonInfoCard(props: DaemonInfoCardProps) {
         </View>
         <View style={styles.actionGroup}>
           {daemonLogs?.logPath ? (
-            <Button variant="outline" size="sm" leftIcon={copyIcon} onPress={handleCopyLogPath}>
+            <Button variant="outline" leftIcon={copyIcon} onPress={handleCopyLogPath}>
               {t("desktop.daemon.logs.copyPath")}
             </Button>
           ) : null}
           <Button
             variant="outline"
-            size="sm"
             leftIcon={fileTextIcon}
             onPress={handleOpenLogs}
             disabled={!daemonLogs}
@@ -306,7 +302,6 @@ function DaemonInfoCard(props: DaemonInfoCardProps) {
         </View>
         <Button
           variant="outline"
-          size="sm"
           leftIcon={activityIcon}
           onPress={handleRunCliStatus}
           disabled={isLoadingCliStatus}
@@ -386,15 +381,6 @@ export function LocalDaemonSection() {
     void handleOpenCliStatus();
   }, [handleOpenCliStatus]);
 
-  const handleOpenAdvancedSettings = useCallback(
-    () => void openExternalUrl(ADVANCED_DAEMON_SETTINGS_URL),
-    [],
-  );
-
-  const advancedSettingsIcon = useMemo(
-    () => <ArrowUpRight size={theme.iconSize.sm} color={theme.colors.foregroundMuted} />,
-    [theme.iconSize.sm, theme.colors.foregroundMuted],
-  );
   const copyIcon = useMemo(
     () => <Copy size={theme.iconSize.sm} color={theme.colors.foreground} />,
     [theme.iconSize.sm, theme.colors.foreground],
@@ -408,21 +394,13 @@ export function LocalDaemonSection() {
     [theme.iconSize.sm, theme.colors.foreground],
   );
 
-  const advancedSettingsButton = useMemo(
-    () => (
-      <Button
-        variant="ghost"
-        size="sm"
-        leftIcon={advancedSettingsIcon}
-        textStyle={settingsStyles.sectionHeaderLinkText}
-        style={settingsStyles.sectionHeaderLink}
-        onPress={handleOpenAdvancedSettings}
-        accessibilityLabel={t("desktop.daemon.openAdvancedSettings")}
-      >
-        {t("desktop.daemon.advancedSettings")}
-      </Button>
-    ),
-    [advancedSettingsIcon, handleOpenAdvancedSettings, t],
+  const advancedSettingsLink = useMemo(
+    () => ({
+      href: ADVANCED_DAEMON_SETTINGS_URL,
+      label: t("desktop.daemon.advancedSettings"),
+      accessibilityLabel: t("desktop.daemon.openAdvancedSettings"),
+    }),
+    [t],
   );
 
   if (!showSection) {
@@ -432,7 +410,7 @@ export function LocalDaemonSection() {
   return (
     <SettingsSection
       title={t("desktop.daemon.title")}
-      trailing={advancedSettingsButton}
+      link={advancedSettingsLink}
       testID="host-page-daemon-lifecycle-card"
     >
       {isLoading || isLoadingSettings ? (
@@ -471,7 +449,7 @@ export function LocalDaemonSection() {
                   </Text>
                   <Text style={settingsStyles.rowHint}>{daemonStatus.home}</Text>
                 </View>
-                <Button variant="outline" size="sm" onPress={handleStop} disabled={isStopping}>
+                <Button variant="outline" onPress={handleStop} disabled={isStopping}>
                   {isStopping
                     ? t("desktop.daemon.lifecycle.stopping")
                     : t("desktop.daemon.lifecycle.stop")}
diff --git a/packages/app/src/desktop/components/integrations-section.tsx b/packages/app/src/desktop/components/integrations-section.tsx
index b5422b71bc..9d97c64022 100644
--- a/packages/app/src/desktop/components/integrations-section.tsx
+++ b/packages/app/src/desktop/components/integrations-section.tsx
@@ -1,88 +1,72 @@
 import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { Text, View } from "react-native";
 import { useFocusEffect } from "expo-router/react-navigation";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
-import { ArrowUpRight, Check, Terminal } from "lucide-react-native";
-import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
 import { useCliInstall } from "@/desktop/hooks/use-install-status";
-import { SettingsSection } from "@/components/settings/headings/settings-section";
-import { settingsStyles } from "@/styles/settings";
-import { openExternalUrl } from "@/utils/open-external-url";
-import { shouldUseDesktopDaemon } from "@/desktop/daemon/desktop-daemon";
+import { SettingsCard, SettingsRow, SettingsSection } from "@/components/settings";
 
 const CLI_DOCS_URL = "https://paseo.sh/docs/cli";
 
 export function IntegrationsSection() {
   const { t } = useTranslation();
-  const { theme } = useUnistyles();
-  const showSection = shouldUseDesktopDaemon();
-  const { status, isInstalling, install, refresh } = useCliInstall();
+  const cli = useCliInstall();
+  const { available, refresh, setInstalled } = cli;
   useFocusEffect(
     useCallback(() => {
-      if (showSection) refresh();
+      if (available) refresh();
       return undefined;
-    }, [refresh, showSection]),
+    }, [refresh, available]),
   );
-  const docsIcon = useMemo(
-    () => <ArrowUpRight size={theme.iconSize.sm} color={theme.colors.foregroundMuted} />,
-    [theme.iconSize.sm, theme.colors.foregroundMuted],
+  const handleValueChange = useCallback(
+    (next: boolean) => {
+      void setInstalled(next);
+    },
+    [setInstalled],
   );
-  const handleOpenDocs = useCallback(() => {
-    void openExternalUrl(CLI_DOCS_URL);
-  }, []);
-  const trailing = useMemo(
-    () => (
-      <Button
-        variant="ghost"
-        size="sm"
-        leftIcon={docsIcon}
-        textStyle={settingsStyles.sectionHeaderLinkText}
-        style={settingsStyles.sectionHeaderLink}
-        onPress={handleOpenDocs}
-        accessibilityLabel={t("settings.integrations.docs.openCli")}
-      >
-        {t("settings.integrations.docs.cli")}
-      </Button>
-    ),
-    [docsIcon, handleOpenDocs, t],
+  const docsLink = useMemo(
+    () => ({
+      href: CLI_DOCS_URL,
+      label: t("settings.integrations.docs.cli"),
+      accessibilityLabel: t("settings.integrations.docs.openCli"),
+    }),
+    [t],
   );
-  if (!showSection) return null;
+  if (!available) return null;
   return (
-    <SettingsSection title={t("settings.integrations.title")} trailing={trailing}>
-      <View style={settingsStyles.card}>
-        <View style={settingsStyles.row}>
-          <View style={settingsStyles.rowContent}>
-            <View style={styles.rowTitleRow}>
-              <Terminal size={theme.iconSize.md} color={theme.colors.foreground} />
-              <Text style={settingsStyles.rowTitle}>
-                {t("settings.integrations.commandLine.title")}
-              </Text>
-            </View>
-            <Text style={settingsStyles.rowHint}>
-              {t("settings.integrations.commandLine.description")}
-            </Text>
-          </View>
-          {status?.installed ? (
-            <View style={styles.installedLabel}>
-              <Check size={14} color={theme.colors.foregroundMuted} />
-              <Text style={styles.mutedText}>{t("settings.integrations.actions.installed")}</Text>
-            </View>
-          ) : (
-            <Button variant="outline" size="sm" onPress={install} disabled={isInstalling}>
-              {isInstalling
-                ? t("settings.integrations.actions.installing")
-                : t("settings.integrations.actions.install")}
-            </Button>
-          )}
-        </View>
-      </View>
+    <SettingsSection title={t("settings.integrations.title")} link={docsLink}>
+      <SettingsCard>
+        <CommandLineRow
+          value={cli.status?.installed ?? false}
+          onValueChange={handleValueChange}
+          disabled={cli.status === null || cli.isWorking}
+        />
+      </SettingsCard>
     </SettingsSection>
   );
 }
 
-const styles = StyleSheet.create((theme) => ({
-  rowTitleRow: { flexDirection: "row", alignItems: "center", gap: theme.spacing[2] },
-  installedLabel: { flexDirection: "row", alignItems: "center", gap: 4 },
-  mutedText: { color: theme.colors.foregroundMuted, fontSize: theme.fontSize.base },
-}));
+/** The `paseo` CLI row: on means installed on this computer. */
+export function CommandLineRow({
+  value,
+  onValueChange,
+  disabled,
+}: {
+  value: boolean;
+  onValueChange: (next: boolean) => void;
+  disabled?: boolean;
+}) {
+  const { t } = useTranslation();
+  return (
+    <SettingsRow
+      label={t("settings.integrations.commandLine.title")}
+      hint={t("settings.integrations.commandLine.description")}
+    >
+      <Switch
+        value={value}
+        onValueChange={onValueChange}
+        disabled={disabled}
+        accessibilityLabel={t("settings.integrations.commandLine.accessibilityLabel")}
+      />
+    </SettingsRow>
+  );
+}
diff --git a/packages/app/src/desktop/components/pair-device-section.tsx b/packages/app/src/desktop/components/pair-device-section.tsx
index 982469008a..bb5c853aca 100644
--- a/packages/app/src/desktop/components/pair-device-section.tsx
+++ b/packages/app/src/desktop/components/pair-device-section.tsx
@@ -22,6 +22,8 @@ import {
 } from "@/components/ui/text-input";
 
 const RELAY_DOCS_URL = "https://paseo.sh/docs/security";
+export const CONNECTIVITY_DOCS_URL = "https://paseo.sh/docs/connectivity";
+export const TAILSCALE_DOCS_URL = `${CONNECTIVITY_DOCS_URL}#tailscale`;
 const FLEX_ONE_STYLE = { flex: 1 } as const;
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedShieldCheck = withUnistyles(ShieldCheck);
@@ -169,7 +171,7 @@ function OfferLoadError({ message, onRetry }: { message: string; onRetry: () =>
   const { t } = useTranslation();
   return (
     <Alert size="sm" variant="error" description={message}>
-      <Button variant="outline" size="sm" leftIcon={RotateCw} onPress={onRetry}>
+      <Button variant="outline" leftIcon={RotateCw} onPress={onRetry}>
         {t("pairing.device.retry")}
       </Button>
     </Alert>
@@ -219,7 +221,14 @@ function RelayConsent(props: PairDeviceBodyProps) {
       </View>
       <View style={styles.directRow}>
         <ThemedNetwork size={14} style={styles.directIcon} />
-        <Text style={styles.directHint}>{t("pairing.device.directConnectionHint")}</Text>
+        <View style={styles.directContent}>
+          <Text style={styles.directHint}>{t("pairing.device.directConnectionHint")}</Text>
+          <ExternalLink
+            href={TAILSCALE_DOCS_URL}
+            label={t("pairing.device.tailscaleDocs")}
+            accessibilityLabel={t("pairing.device.tailscaleDocsAccessibility")}
+          />
+        </View>
       </View>
     </View>
   );
@@ -254,12 +263,7 @@ function PairingOffer(props: PairDeviceBodyProps & { offer: { url: string } }) {
             accessibilityLabel={t("pairing.link.label")}
           />
         </View>
-        <Button
-          variant="outline"
-          size="sm"
-          leftIcon={props.copied ? Check : Copy}
-          onPress={props.onCopy}
-        >
+        <Button variant="outline" leftIcon={props.copied ? Check : Copy} onPress={props.onCopy}>
           {props.copied ? t("pairing.device.copied") : t("pairing.device.copy")}
         </Button>
       </View>
@@ -338,8 +342,12 @@ const styles = StyleSheet.create((theme) => ({
     color: theme.colors.foregroundMuted,
     marginTop: 1, // optical: seats the glyph on the hint's first text line
   },
-  directHint: {
+  directContent: {
     flex: 1,
+    alignItems: "flex-start",
+    gap: theme.spacing[2],
+  },
+  directHint: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.sm,
     lineHeight: theme.fontSize.sm * 1.5,
diff --git a/packages/app/src/desktop/daemon/desktop-daemon.ts b/packages/app/src/desktop/daemon/desktop-daemon.ts
index 87cc058a0c..ac1427363e 100644
--- a/packages/app/src/desktop/daemon/desktop-daemon.ts
+++ b/packages/app/src/desktop/daemon/desktop-daemon.ts
@@ -326,6 +326,10 @@ export async function installCli(): Promise<InstallStatus> {
   return parseInstallStatus(await invokeDesktopCommand("install_cli"));
 }
 
+export async function uninstallCli(): Promise<InstallStatus> {
+  return parseInstallStatus(await invokeDesktopCommand("uninstall_cli"));
+}
+
 // COMPAT(desktopSkillSelectionMigration): added in v0.4.0; remove after 2027-02-16.
 export function readLegacySkillSelection(): Promise<AgentSkillSelection | null> {
   return invokeDesktopCommand("read_legacy_skill_selection") as Promise<AgentSkillSelection | null>;
diff --git a/packages/app/src/desktop/hooks/use-install-status.ts b/packages/app/src/desktop/hooks/use-install-status.ts
index 98bc3da804..5a688da449 100644
--- a/packages/app/src/desktop/hooks/use-install-status.ts
+++ b/packages/app/src/desktop/hooks/use-install-status.ts
@@ -1,10 +1,12 @@
 import { useCallback } from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
+import { useToast } from "@/contexts/toast-context";
 import {
   getCliInstallStatus,
   installCli,
   shouldUseDesktopDaemon,
+  uninstallCli,
   type InstallStatus,
 } from "@/desktop/daemon/desktop-daemon";
 import {
@@ -14,60 +16,85 @@ import {
 
 const CLI_INSTALL_STATUS_QUERY_KEY = ["desktop", "integrations", "cli-install-status"] as const;
 
-interface DesktopInstallHookResult {
+interface CliInstall {
+  /** False outside the desktop app: the CLI installs on the machine running the app. */
+  available: boolean;
   status: InstallStatus | null;
   isLoading: boolean;
-  isInstalling: boolean;
-  error: Error | null;
-  install: () => void;
+  isWorking: boolean;
+  /**
+   * Installs or removes the CLI; resolves to whether it worked. Failures are reported. Removing
+   * keeps a paseo command this app did not install, says so, and resolves true.
+   */
+  setInstalled: (installed: boolean) => Promise<boolean>;
   refresh: () => void;
 }
 
-export function useCliInstall(): DesktopInstallHookResult {
+export function useCliInstall(): CliInstall {
   const { t } = useTranslation();
   const queryClient = useQueryClient();
   const reportError = useDesktopIpcErrorReporter();
-  const enabled = shouldUseDesktopDaemon();
+  const toast = useToast();
+  const available = shouldUseDesktopDaemon();
 
   const statusQuery = useQuery<InstallStatus, Error>({
     queryKey: CLI_INSTALL_STATUS_QUERY_KEY,
     queryFn: getCliInstallStatus,
-    enabled,
+    enabled: available,
     retry: false,
   });
-  const { data: installStatus, error: statusError, isLoading, refetch } = statusQuery;
+  const { data: installStatus, isLoading, refetch } = statusQuery;
   useDesktopIpcQueryErrorToast({
     error: statusQuery.error,
     message: t("desktop.integrations.cli.statusFailed"),
     logLabel: "[Integrations] Failed to load CLI status",
   });
 
-  const installMutation = useMutation<InstallStatus, Error>({
-    mutationFn: installCli,
-    onError: (error) => {
+  const mutation = useMutation<InstallStatus, Error, boolean>({
+    mutationFn: (installed) => (installed ? installCli() : uninstallCli()),
+    onError: (error, installed) => {
       reportError({
         error,
-        message: t("desktop.integrations.cli.installFailed"),
-        logLabel: "[Integrations] Failed to install CLI",
+        message: installed
+          ? t("desktop.integrations.cli.installFailed")
+          : t("desktop.integrations.cli.uninstallFailed"),
+        logLabel: installed
+          ? "[Integrations] Failed to install CLI"
+          : "[Integrations] Failed to uninstall CLI",
       });
     },
     onSuccess: (nextStatus) => {
       queryClient.setQueryData<InstallStatus>(CLI_INSTALL_STATUS_QUERY_KEY, nextStatus);
-      void queryClient.invalidateQueries({ queryKey: CLI_INSTALL_STATUS_QUERY_KEY });
     },
   });
-  const { error: installError, isPending: isInstalling, mutate: install } = installMutation;
+  const { mutateAsync, isPending } = mutation;
 
+  // Removing only ever deletes the CLI this app installed. A paseo command put there some other way
+  // stays, and that still counts as done: the user is told rather than left with a switch that
+  // silently won't turn off.
+  const setInstalled = useCallback(
+    (installed: boolean) =>
+      mutateAsync(installed).then(
+        (status) => {
+          if (status.installed === installed) return true;
+          if (installed) return false;
+          toast.show(t("desktop.integrations.cli.keptForeign"));
+          return true;
+        },
+        () => false,
+      ),
+    [mutateAsync, t, toast],
+  );
   const refresh = useCallback(() => {
     void refetch();
   }, [refetch]);
 
   return {
+    available,
     status: installStatus ?? null,
     isLoading,
-    isInstalling,
-    error: statusError ?? installError ?? null,
-    install,
+    isWorking: isPending,
+    setInstalled,
     refresh,
   };
 }
diff --git a/packages/app/src/desktop/host.ts b/packages/app/src/desktop/host.ts
index 080da9c37a..2541da9f79 100644
--- a/packages/app/src/desktop/host.ts
+++ b/packages/app/src/desktop/host.ts
@@ -1,6 +1,6 @@
 import { Platform } from "react-native";
 import { getElectronHost } from "@/desktop/electron/host";
-import type { BrowserKeyboardPolicy } from "@/desktop/browser/shortcuts";
+import type { BrowserKeyboardPolicy } from "@/keyboard";
 import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
 
 type BrowserAutomationExecuteRequest = Extract<
diff --git a/packages/app/src/diagnostics/app-diagnostic-report.test.ts b/packages/app/src/diagnostics/app-diagnostic-report.test.ts
index df10b01fed..b330d56745 100644
--- a/packages/app/src/diagnostics/app-diagnostic-report.test.ts
+++ b/packages/app/src/diagnostics/app-diagnostic-report.test.ts
@@ -46,6 +46,31 @@ function makeHost(): HostProfile {
   };
 }
 
+function makeSnapshot(host: HostProfile): HostRuntimeSnapshot {
+  return {
+    serverId: host.serverId,
+    activeConnectionId: "relay:relay.secret.test:443",
+    activeConnection: {
+      type: "relay",
+      endpoint: "relay.secret.test:443",
+      display: "relay",
+    },
+    connectionStatus: "online",
+    client: null,
+    lastError: null,
+    lastOnlineAt: "2026-06-25T00:00:00.000Z",
+    agentDirectoryStatus: "ready",
+    agentDirectoryError: null,
+    hasEverLoadedAgentDirectory: true,
+    probeByConnectionId: new Map([
+      ["direct:secret.example.test:6767", { status: "available", latencyMs: 42 }],
+      ["relay:relay.secret.test:443", { status: "available", latencyMs: 8 }],
+    ]),
+    clientGeneration: 1,
+    connectionEpoch: 1,
+  };
+}
+
 describe("app diagnostics report", () => {
   test("reports whether the connected daemon is managed by Paseo Desktop", () => {
     const report = formatServerInfoSection({
@@ -61,31 +86,11 @@ describe("app diagnostics report", () => {
 
   test("formats connection rows without raw connection details", () => {
     const host = makeHost();
-    const snapshot: HostRuntimeSnapshot = {
-      serverId: host.serverId,
-      activeConnectionId: "relay:relay.secret.test:443",
-      activeConnection: {
-        type: "relay",
-        endpoint: "relay.secret.test:443",
-        display: "relay",
-      },
-      connectionStatus: "online",
-      client: null,
-      lastError: null,
-      lastOnlineAt: "2026-06-25T00:00:00.000Z",
-      agentDirectoryStatus: "ready",
-      agentDirectoryError: null,
-      hasEverLoadedAgentDirectory: true,
-      probeByConnectionId: new Map([
-        ["direct:secret.example.test:6767", { status: "available", latencyMs: 42 }],
-        ["relay:relay.secret.test:443", { status: "available", latencyMs: 8 }],
-      ]),
-      clientGeneration: 1,
-      connectionEpoch: 1,
-    };
+    const snapshot = makeSnapshot(host);
 
     const report = formatHostRuntimeSection({ host, snapshot });
 
+    expect(report).toContain("Last online: 2026-06-25T00:00:00.000Z");
     expect(report).toContain("direct TCP");
     expect(report).toContain("relay");
     expect(report).toContain("local socket");
@@ -97,6 +102,58 @@ describe("app diagnostics report", () => {
     expect(report).not.toContain("tcp-password");
   });
 
+  test.each(["connecting", "offline", "error"] as const)(
+    "does not claim a previously connected host was never online while %s",
+    (connectionStatus) => {
+      const host = makeHost();
+      const snapshot = makeSnapshot(host);
+      const report = formatHostRuntimeSection({
+        host,
+        snapshot: { ...snapshot, connectionStatus, lastOnlineAt: null },
+      });
+
+      expect(report).toContain("Last online: unknown");
+      expect(report).not.toContain("Last online: never");
+    },
+  );
+
+  test("does not infer connection history when the runtime has not started", () => {
+    const report = formatHostRuntimeSection({ host: makeHost(), snapshot: null });
+
+    expect(report).toContain("Last online: unknown");
+  });
+
+  test.each(["online", "error"] as const)(
+    "identifies a routed connection while %s",
+    (connectionStatus) => {
+      const host = makeHost();
+      host.connections.push({ id: "routed-origin", type: "routed", originServerId: "srv-origin" });
+      const snapshot: HostRuntimeSnapshot = {
+        serverId: host.serverId,
+        activeConnectionId: "routed-origin",
+        activeConnection: { type: "routed", endpoint: "srv-origin", display: "via srv-origin" },
+        connectionStatus,
+        client: null,
+        lastError: connectionStatus === "error" ? "Host disconnected" : null,
+        lastOnlineAt: null,
+        agentDirectoryStatus: "ready",
+        agentDirectoryError: null,
+        hasEverLoadedAgentDirectory: true,
+        probeByConnectionId: new Map(),
+        clientGeneration: 1,
+        connectionEpoch: 1,
+      };
+
+      const report = formatHostRuntimeSection({ host, snapshot });
+
+      expect(report).toContain("Active connection: routed");
+      expect(report).toContain("Connection 5: routed, active, probe=unknown");
+      expect(report).toContain(`Status: ${connectionStatus}`);
+      expect(report).toContain(`Last error: ${snapshot.lastError ?? "none"}`);
+      expect(report).not.toContain("srv-origin");
+    },
+  );
+
   test("redacts saved connection secrets from collected daemon and desktop text", () => {
     const host = makeHost();
     const redacted = redactAppDiagnosticReport(
diff --git a/packages/app/src/diagnostics/app-diagnostic-report.ts b/packages/app/src/diagnostics/app-diagnostic-report.ts
index afb38e7aad..3ba48fc1f0 100644
--- a/packages/app/src/diagnostics/app-diagnostic-report.ts
+++ b/packages/app/src/diagnostics/app-diagnostic-report.ts
@@ -45,7 +45,7 @@ export function formatHostRuntimeSection(input: {
         ? describeConnectionKind(snapshot.activeConnection.type)
         : "none",
     },
-    { label: "Last online", value: snapshot?.lastOnlineAt ?? "never" },
+    { label: "Last online", value: snapshot?.lastOnlineAt ?? "unknown" },
     { label: "Last error", value: snapshot?.lastError ?? "none" },
     {
       label: "Agent directory",
@@ -100,6 +100,8 @@ export function describeConnectionKind(type: HostConnection["type"] | string): s
       return "local pipe";
     case "relay":
       return "relay";
+    case "routed":
+      return "routed";
     default:
       return "unknown";
   }
diff --git a/packages/app/src/file-explorer/directory-listings.test.ts b/packages/app/src/file-explorer/directory-listings.test.ts
new file mode 100644
index 0000000000..8e56b39b2b
--- /dev/null
+++ b/packages/app/src/file-explorer/directory-listings.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import type { AgentFileExplorerState, ExplorerDirectory } from "@/stores/session-store";
+import {
+  refreshExplorerDirectories,
+  restoreExpandedDirectories,
+  showHiddenFilesAndRestoreExpandedDirectories,
+  reconcileRestoredExpandedPaths,
+} from "./tree";
+import {
+  DIRECTORY_LISTING_INVALIDATED,
+  invalidateExplorerDirectoryListings,
+  loadExplorerDirectory,
+} from "./directory-listings";
+
+function directory(path: string, names: string[]): ExplorerDirectory {
+  return {
+    path,
+    entries: names.map((name) => ({
+      path: `${path}/${name}`,
+      name,
+      kind: "file",
+      size: 0,
+      modifiedAt: "2026-01-01T00:00:00.000Z",
+    })),
+  };
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: Error) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+function explorer() {
+  let state: AgentFileExplorerState = {
+    listingGeneration: 0,
+    directories: new Map([[".", directory(".", ["docs"])]]),
+    isLoading: false,
+    lastError: null,
+    pendingRequest: null,
+    currentPath: ".",
+    history: ["."],
+    lastVisitedPath: ".",
+    selectedEntryPath: null,
+  };
+  const updateState = (update: (state: AgentFileExplorerState) => AgentFileExplorerState) => {
+    state = update(state);
+    return state;
+  };
+  return {
+    state: () => state,
+    load: (path: string, result: Promise<ExplorerDirectory>) =>
+      loadExplorerDirectory({
+        path,
+        updateState,
+        listDirectory: () => result,
+        fallbackError: "Directory listing failed",
+        options: { recordHistory: false, setCurrentPath: false },
+      }),
+    refresh: (retained: readonly string[]) =>
+      invalidateExplorerDirectoryListings(updateState, retained),
+  };
+}
+
+describe("directory listings across Refresh", () => {
+  it("ignores an earlier reply for a collapsed folder while the fresh root is loading", async () => {
+    const model = explorer();
+    const old = deferred<ExplorerDirectory>();
+    const oldLoad = model.load("docs", old.promise);
+    model.refresh(["."]);
+    const fresh = deferred<ExplorerDirectory>();
+    const freshLoad = model.load(".", fresh.promise);
+    old.resolve(directory("docs", ["OLD.md"]));
+
+    await expect(oldLoad).resolves.toBe(DIRECTORY_LISTING_INVALIDATED);
+    expect(model.state().directories.has("docs")).toBe(false);
+    expect(model.state().isLoading).toBe(true);
+    expect(model.state().pendingRequest?.path).toBe(".");
+
+    const root = directory(".", ["docs", "NEW.md"]);
+    fresh.resolve(root);
+    await expect(freshLoad).resolves.toEqual(root);
+    expect(model.state().directories.get(".")).toEqual(root);
+    expect(model.state().isLoading).toBe(false);
+  });
+
+  it("does not let a pre-refresh reply replace a newer listing of the same folder", async () => {
+    const model = explorer();
+    const old = deferred<ExplorerDirectory>();
+    const oldLoad = model.load("docs", old.promise);
+    model.refresh([".", "docs"]);
+    const fresh = directory("docs", ["NEW.md"]);
+    await model.load("docs", Promise.resolve(fresh));
+    old.resolve(directory("docs", ["OLD.md"]));
+
+    await expect(oldLoad).resolves.toBe(DIRECTORY_LISTING_INVALIDATED);
+    expect(model.state().directories.get("docs")).toEqual(fresh);
+  });
+
+  it("ignores errors from requests invalidated by Refresh", async () => {
+    const model = explorer();
+    const old = deferred<ExplorerDirectory>();
+    const oldLoad = model.load("docs", old.promise);
+    model.refresh(["."]);
+    const fresh = deferred<ExplorerDirectory>();
+    const freshLoad = model.load(".", fresh.promise);
+    old.reject(new Error("Old request failed"));
+
+    await expect(oldLoad).resolves.toBe(DIRECTORY_LISTING_INVALIDATED);
+    expect(model.state().lastError).toBeNull();
+    expect(model.state().isLoading).toBe(true);
+    fresh.resolve(directory(".", ["docs"]));
+    await freshLoad;
+  });
+
+  it("keeps expanded listings visible and discards collapsed listings on Refresh", async () => {
+    const model = explorer();
+    const docs = directory("docs", ["guide.md"]);
+    await model.load("docs", Promise.resolve(docs));
+    await model.load("assets", Promise.resolve(directory("assets", ["logo.png"])));
+    model.refresh([".", "docs"]);
+
+    expect(model.state().directories.get("docs")).toEqual(docs);
+    expect(model.state().directories.has("assets")).toBe(false);
+    expect(model.state().currentPath).toBe(".");
+    expect(model.state().history).toEqual(["."]);
+  });
+});
+
+it.each([false, true])(
+  "preserves saved expansion when Refresh invalidates restoration (hidden: %s)",
+  async (hidden) => {
+    const model = explorer();
+    const folder = hidden ? ".hidden" : "docs";
+    const root: ExplorerDirectory = {
+      path: ".",
+      entries: [
+        {
+          name: folder,
+          path: folder,
+          kind: "directory",
+          size: 0,
+          modifiedAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+    };
+    const saved = new Set([".", folder]);
+    const pending = deferred<ExplorerDirectory>();
+    const input = {
+      rootDirectory: root,
+      persistedExpandedPaths: saved,
+      requestDirectoryListing: (path: string) => model.load(path, pending.promise),
+    };
+    const restoration = hidden
+      ? showHiddenFilesAndRestoreExpandedDirectories({ ...input, showHiddenFiles: () => {} })
+      : restoreExpandedDirectories({ ...input, showHiddenFiles: false });
+    const fresh = directory(folder, ["NEW.md"]);
+    await refreshExplorerDirectories({
+      hasWorkspaceScope: true,
+      expandedPaths: saved,
+      showHiddenFiles: hidden,
+      invalidateDirectoryListings: model.refresh,
+      requestDirectoryListing: (path) =>
+        model.load(path, Promise.resolve(path === "." ? root : fresh)),
+    });
+    pending.resolve(directory(folder, ["OLD.md"]));
+    const restored = await restoration;
+    const expanded = reconcileRestoredExpandedPaths({
+      persistedExpandedPaths: saved,
+      currentExpandedPaths: saved,
+      restoredExpandedPaths: restored,
+    });
+    expect(model.state().directories.get(folder)).toEqual(fresh);
+    expect(expanded).toEqual([".", folder]);
+  },
+);
diff --git a/packages/app/src/file-explorer/directory-listings.ts b/packages/app/src/file-explorer/directory-listings.ts
new file mode 100644
index 0000000000..4d52aaf782
--- /dev/null
+++ b/packages/app/src/file-explorer/directory-listings.ts
@@ -0,0 +1,91 @@
+import type { AgentFileExplorerState, ExplorerDirectory } from "@/stores/session-store";
+
+export const DIRECTORY_LISTING_INVALIDATED = Symbol("directory-listing-invalidated");
+export type DirectoryListingResult =
+  | ExplorerDirectory
+  | null
+  | typeof DIRECTORY_LISTING_INVALIDATED;
+
+type UpdateExplorerState = (
+  update: (state: AgentFileExplorerState) => AgentFileExplorerState,
+) => AgentFileExplorerState | null;
+
+function pushHistory(history: string[], path: string): string[] {
+  const normalizedHistory = history.length === 0 ? ["."] : history;
+  return normalizedHistory.at(-1) === path ? normalizedHistory : [...normalizedHistory, path];
+}
+
+export async function loadExplorerDirectory({
+  path,
+  options,
+  updateState,
+  listDirectory,
+  fallbackError,
+}: {
+  path: string;
+  options?: { recordHistory?: boolean; setCurrentPath?: boolean };
+  updateState: UpdateExplorerState;
+  listDirectory: () => Promise<ExplorerDirectory>;
+  fallbackError: string;
+}): Promise<DirectoryListingResult> {
+  const shouldSetCurrentPath = options?.setCurrentPath ?? true;
+  const shouldRecordHistory = options?.recordHistory ?? shouldSetCurrentPath;
+  const initial = updateState((state) => ({
+    ...state,
+    isLoading: true,
+    lastError: null,
+    pendingRequest: { path, mode: "list" },
+    ...(shouldSetCurrentPath
+      ? {
+          currentPath: path,
+          history: shouldRecordHistory ? pushHistory(state.history, path) : state.history,
+          lastVisitedPath: path,
+        }
+      : {}),
+  }));
+  if (!initial) return null;
+  const generation = initial.listingGeneration;
+  try {
+    const directory = await listDirectory();
+    let accepted = false;
+    updateState((state) => {
+      if (state.listingGeneration !== generation) return state;
+      accepted = true;
+      const directories = new Map(state.directories);
+      directories.set(directory.path, directory);
+      return { ...state, directories, isLoading: false, lastError: null, pendingRequest: null };
+    });
+    return accepted ? directory : DIRECTORY_LISTING_INVALIDATED;
+  } catch (error) {
+    let invalidated = false;
+    updateState((state) => {
+      if (state.listingGeneration !== generation) {
+        invalidated = true;
+        return state;
+      }
+      return {
+        ...state,
+        isLoading: false,
+        lastError: error instanceof Error ? error.message : fallbackError,
+        pendingRequest: null,
+      };
+    });
+    return invalidated ? DIRECTORY_LISTING_INVALIDATED : null;
+  }
+}
+
+/** Refresh invalidates earlier replies as well as listings of collapsed folders. */
+export function invalidateExplorerDirectoryListings(
+  updateState: UpdateExplorerState,
+  retainedPaths: readonly string[],
+): void {
+  const retained = new Set(retainedPaths);
+  updateState((state) => ({
+    ...state,
+    listingGeneration: state.listingGeneration + 1,
+    directories: new Map([...state.directories].filter(([path]) => retained.has(path))),
+    isLoading: false,
+    pendingRequest: null,
+    lastError: null,
+  }));
+}
diff --git a/packages/app/src/file-explorer/tree.test.ts b/packages/app/src/file-explorer/tree.test.ts
index e3df026c0d..82d4bcc61a 100644
--- a/packages/app/src/file-explorer/tree.test.ts
+++ b/packages/app/src/file-explorer/tree.test.ts
@@ -1,9 +1,10 @@
 import { describe, expect, it } from "vitest";
-import type { ExplorerEntry } from "@/stores/session-store";
+import type { ExplorerDirectory, ExplorerEntry } from "@/stores/session-store";
 import {
   MAX_AUTO_EXPANDED_DIRECTORY_DEPTH,
   flattenExplorerTree,
   reconcileRestoredExpandedPaths,
+  refreshExplorerDirectories,
   restoreExpandedDirectories,
   setExpandedDirectoryPath,
   showHiddenFilesAndRestoreExpandedDirectories,
@@ -195,3 +196,76 @@ describe("file explorer tree", () => {
     await expect(restoration).resolves.toEqual([".", ".hidden"]);
   });
 });
+
+describe("refreshExplorerDirectories", () => {
+  function makeListing(path: string, names: string[]): ExplorerDirectory {
+    return {
+      path,
+      entries: names.map((name) => ({
+        name,
+        path: path === "." ? name : `${path}/${name}`,
+        kind: "file" as const,
+        size: 0,
+        modifiedAt: "2026-01-01T00:00:00.000Z",
+      })),
+    };
+  }
+
+  function createExplorer(disk: Record<string, string[]>, cached: Record<string, string[]>) {
+    const directories = new Map(
+      Object.entries(cached).map(([path, names]) => [path, makeListing(path, names)]),
+    );
+    return {
+      directories,
+      requestDirectoryListing: async (path: string) => {
+        const listing = makeListing(path, disk[path] ?? []);
+        directories.set(path, listing);
+        return listing;
+      },
+      invalidateDirectoryListings: (retainedPaths: readonly string[]) => {
+        const retained = new Set(retainedPaths);
+        for (const path of directories.keys()) if (!retained.has(path)) directories.delete(path);
+      },
+    };
+  }
+
+  it("does not keep a stale listing for a collapsed folder", async () => {
+    // docs/ was expanded and collapsed earlier, then NEW.md was created in it.
+    const explorer = createExplorer(
+      { ".": ["docs"], docs: ["README.md", "NEW.md"] },
+      { ".": ["docs"], docs: ["README.md"] },
+    );
+
+    await refreshExplorerDirectories({
+      hasWorkspaceScope: true,
+      expandedPaths: new Set(["."]),
+      showHiddenFiles: false,
+      requestDirectoryListing: explorer.requestDirectoryListing,
+      invalidateDirectoryListings: explorer.invalidateDirectoryListings,
+    });
+
+    // Expanding docs/ only fetches when it has no cached listing.
+    expect(explorer.directories.has("docs")).toBe(false);
+    expect(explorer.directories.get(".")?.entries.map((entry) => entry.name)).toEqual(["docs"]);
+  });
+
+  it("refreshes expanded folders and keeps their listings", async () => {
+    const explorer = createExplorer(
+      { ".": ["src"], src: ["a.ts", "b.ts"] },
+      { ".": ["src"], src: ["a.ts"] },
+    );
+
+    await refreshExplorerDirectories({
+      hasWorkspaceScope: true,
+      expandedPaths: new Set([".", "src"]),
+      showHiddenFiles: false,
+      requestDirectoryListing: explorer.requestDirectoryListing,
+      invalidateDirectoryListings: explorer.invalidateDirectoryListings,
+    });
+
+    expect(explorer.directories.get("src")?.entries.map((entry) => entry.name)).toEqual([
+      "a.ts",
+      "b.ts",
+    ]);
+  });
+});
diff --git a/packages/app/src/file-explorer/tree.ts b/packages/app/src/file-explorer/tree.ts
index 8b75ae7b25..4402cd82bc 100644
--- a/packages/app/src/file-explorer/tree.ts
+++ b/packages/app/src/file-explorer/tree.ts
@@ -1,5 +1,6 @@
 import type { ExplorerDirectory, ExplorerEntry } from "@/stores/session-store";
 import type { SortOption } from "@/stores/panel-store/state";
+import { DIRECTORY_LISTING_INVALIDATED, type DirectoryListingResult } from "./directory-listings";
 import { filterVisibleExplorerEntries, isHiddenExplorerPath } from "./visibility";
 
 export const MAX_AUTO_EXPANDED_DIRECTORY_DEPTH = 5;
@@ -16,11 +17,13 @@ interface FlattenExplorerTreeInput {
   showHiddenFiles: boolean;
 }
 
+type RestoredExpandedPaths = string[] | typeof DIRECTORY_LISTING_INVALIDATED;
+
 interface RestoreExpandedDirectoriesInput {
   rootDirectory: ExplorerDirectory;
   persistedExpandedPaths: ReadonlySet<string>;
   showHiddenFiles: boolean;
-  requestDirectoryListing: (path: string) => Promise<ExplorerDirectory | null>;
+  requestDirectoryListing: (path: string) => Promise<DirectoryListingResult>;
 }
 
 interface ShowHiddenFilesAndRestoreExpandedDirectoriesInput extends Omit<
@@ -33,7 +36,7 @@ interface ShowHiddenFilesAndRestoreExpandedDirectoriesInput extends Omit<
 interface ReconcileRestoredExpandedPathsInput {
   persistedExpandedPaths: ReadonlySet<string>;
   currentExpandedPaths: ReadonlySet<string>;
-  restoredExpandedPaths: string[];
+  restoredExpandedPaths: RestoredExpandedPaths;
 }
 
 interface SetExpandedDirectoryPathInput {
@@ -85,7 +88,7 @@ export async function restoreExpandedDirectories({
   persistedExpandedPaths,
   showHiddenFiles,
   requestDirectoryListing,
-}: RestoreExpandedDirectoriesInput): Promise<string[]> {
+}: RestoreExpandedDirectoriesInput): Promise<RestoredExpandedPaths> {
   const restoredPaths = ["."];
   const restoredPathSet = new Set(restoredPaths);
   let parentDirectories = [rootDirectory];
@@ -110,9 +113,11 @@ export async function restoreExpandedDirectories({
     const requestedDirectories = await Promise.all(
       pathsToRequest.map((path) => requestDirectoryListing(path)),
     );
+    if (requestedDirectories.includes(DIRECTORY_LISTING_INVALIDATED))
+      return DIRECTORY_LISTING_INVALIDATED;
     parentDirectories = [];
     for (const directory of requestedDirectories) {
-      if (!directory) {
+      if (!directory || directory === DIRECTORY_LISTING_INVALIDATED) {
         continue;
       }
       restoredPaths.push(directory.path);
@@ -128,7 +133,7 @@ export function showHiddenFilesAndRestoreExpandedDirectories({
   persistedExpandedPaths,
   showHiddenFiles,
   requestDirectoryListing,
-}: ShowHiddenFilesAndRestoreExpandedDirectoriesInput): Promise<string[]> {
+}: ShowHiddenFilesAndRestoreExpandedDirectoriesInput): Promise<RestoredExpandedPaths> {
   showHiddenFiles();
   return restoreExpandedDirectories({
     rootDirectory,
@@ -143,6 +148,8 @@ export function reconcileRestoredExpandedPaths({
   currentExpandedPaths,
   restoredExpandedPaths,
 }: ReconcileRestoredExpandedPathsInput): string[] {
+  if (restoredExpandedPaths === DIRECTORY_LISTING_INVALIDATED)
+    return Array.from(currentExpandedPaths);
   const reconciledPaths = new Set(restoredExpandedPaths);
 
   for (const path of persistedExpandedPaths) {
@@ -205,7 +212,7 @@ function sortExplorerEntries(entries: ExplorerEntry[], sortOption: SortOption):
 /** Load and expand the path to a directory selected outside the tree. */
 export async function revealExplorerDirectory(input: {
   directoryPath: string;
-  requestDirectoryListing: (path: string) => Promise<ExplorerDirectory | null>;
+  requestDirectoryListing: (path: string) => Promise<DirectoryListingResult>;
   expandPaths: (paths: string[]) => void;
   showHiddenFiles: () => void;
 }): Promise<void> {
@@ -218,7 +225,51 @@ export async function revealExplorerDirectory(input: {
     }
   }
   for (const path of paths) {
-    if (!(await input.requestDirectoryListing(path))) return;
+    const directory = await input.requestDirectoryListing(path);
+    if (!directory || directory === DIRECTORY_LISTING_INVALIDATED) return;
   }
   input.expandPaths(paths);
 }
+
+/**
+ * Files Refresh: re-lists the expanded directories (and the root), and drops the cached
+ * listing of every other directory. Expanding a directory only fetches when it has no
+ * cached listing, so keeping a collapsed directory's old listing would show it as it was
+ * before the refresh.
+ */
+export async function refreshExplorerDirectories({
+  hasWorkspaceScope,
+  expandedPaths,
+  showHiddenFiles,
+  requestDirectoryListing,
+  invalidateDirectoryListings,
+}: {
+  hasWorkspaceScope: boolean;
+  expandedPaths: Set<string>;
+  showHiddenFiles: boolean;
+  requestDirectoryListing: (
+    path: string,
+    opts?: { recordHistory?: boolean; setCurrentPath?: boolean },
+  ) => Promise<DirectoryListingResult>;
+  invalidateDirectoryListings: (retainedPaths: readonly string[]) => void;
+}): Promise<null> {
+  if (!hasWorkspaceScope) {
+    return null;
+  }
+  const directoryPaths = Array.from(expandedPaths).filter(
+    (path) => showHiddenFiles || !isHiddenExplorerPath(path),
+  );
+  if (!directoryPaths.includes(".")) {
+    directoryPaths.unshift(".");
+  }
+  invalidateDirectoryListings(directoryPaths);
+  await Promise.all(
+    directoryPaths.map((path) =>
+      requestDirectoryListing(path, {
+        recordHistory: false,
+        setCurrentPath: false,
+      }),
+    ),
+  );
+  return null;
+}
diff --git a/packages/app/src/file-pane/pane.tsx b/packages/app/src/file-pane/pane.tsx
index 5f70030819..3674ed7a50 100644
--- a/packages/app/src/file-pane/pane.tsx
+++ b/packages/app/src/file-pane/pane.tsx
@@ -90,7 +90,7 @@ export function FilePane({
         <Text style={styles.errorText}>
           {snapshot.status === "error" ? snapshot.error : t("panels.file.notFound")}
         </Text>
-        <Button variant="outline" size="sm" onPress={handle.retry}>
+        <Button variant="outline" onPress={handle.retry}>
           {t("common.actions.retry")}
         </Button>
       </>
diff --git a/packages/app/src/file-panels/html-preview.web.tsx b/packages/app/src/file-panels/html-preview.web.tsx
index 471362d8ca..eac275bfe8 100644
--- a/packages/app/src/file-panels/html-preview.web.tsx
+++ b/packages/app/src/file-panels/html-preview.web.tsx
@@ -25,12 +25,17 @@ const iframeStyle = {
 
 export function FileHtmlPreview({ html, testID }: { html: string; testID?: string }) {
   const { t } = useTranslation();
-  const document = useMemo(() => withPreviewCsp(html), [html]);
+  // A document URL lets the browser resolve fragment links within the preview.
+  // srcDoc would inherit the app URL and navigate the frame back into Paseo.
+  const source = useMemo(
+    () => `data:text/html;charset=utf-8,${encodeURIComponent(withPreviewCsp(html))}`,
+    [html],
+  );
   return (
     <iframe
       data-testid={testID}
       title={t("panels.file.filePanels.builtin.html")}
-      srcDoc={document}
+      src={source}
       sandbox={SANDBOX}
       referrerPolicy="no-referrer"
       style={iframeStyle}
diff --git a/packages/app/src/file-panels/source/conflict-alert.tsx b/packages/app/src/file-panels/source/conflict-alert.tsx
index 94a76f517d..7d3a27990c 100644
--- a/packages/app/src/file-panels/source/conflict-alert.tsx
+++ b/packages/app/src/file-panels/source/conflict-alert.tsx
@@ -30,11 +30,11 @@ export function FileConflictAlert({ state }: { state: FileConflictAlertState })
       {state.kind === "changed" ? (
         <View style={styles.actions}>
           {state.canOverwrite ? (
-            <Button variant="outline" size="sm" onPress={state.onOverwrite}>
+            <Button variant="outline" onPress={state.onOverwrite}>
               {t("panels.file.editor.overwrite")}
             </Button>
           ) : null}
-          <Button variant="outline" size="sm" onPress={state.onReload}>
+          <Button variant="outline" onPress={state.onReload}>
             {t("panels.file.editor.reload")}
           </Button>
         </View>
diff --git a/packages/app/src/file-panels/source/find/index.web.tsx b/packages/app/src/file-panels/source/find/index.web.tsx
index dedf58389f..2642bb5365 100644
--- a/packages/app/src/file-panels/source/find/index.web.tsx
+++ b/packages/app/src/file-panels/source/find/index.web.tsx
@@ -12,7 +12,7 @@ import { StyleSheet } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
 import { PaneFind, findShortcutPlatform, isFindShortcut, type PaneFindHandle } from "@/pane-find";
 import { usePaneFocus } from "@/panels/pane-context";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
+import { hasActiveOverlay } from "@/keyboard";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
 import { FileFindModel } from "./model.web";
@@ -39,7 +39,7 @@ export function FileFind({
   useEffect(() => {
     if (!isInteractive || !active) return;
     function onKeyDown(event: KeyboardEvent) {
-      if (event.defaultPrevented || hasActiveWebOverlay() || isImeComposingKeyboardEvent(event))
+      if (event.defaultPrevented || hasActiveOverlay() || isImeComposingKeyboardEvent(event))
         return;
       if (isFindShortcut(event, findShortcutPlatform())) {
         event.preventDefault();
diff --git a/packages/app/src/file-panels/source/panel.tsx b/packages/app/src/file-panels/source/panel.tsx
index 23ea42f875..906719bce6 100644
--- a/packages/app/src/file-panels/source/panel.tsx
+++ b/packages/app/src/file-panels/source/panel.tsx
@@ -206,7 +206,7 @@ function EditableTextFile({
     return (
       <View style={styles.centerState}>
         <Text style={styles.errorText}>{snapshot.error ?? t("panels.file.failedToLoad")}</Text>
-        <Button variant="outline" size="sm" onPress={handleRetry}>
+        <Button variant="outline" onPress={handleRetry}>
           {t("common.actions.retry")}
         </Button>
       </View>
diff --git a/packages/app/src/file-panels/source/toolbar.tsx b/packages/app/src/file-panels/source/toolbar.tsx
index 43cb6f7291..4cf391b5d6 100644
--- a/packages/app/src/file-panels/source/toolbar.tsx
+++ b/packages/app/src/file-panels/source/toolbar.tsx
@@ -108,7 +108,7 @@ export function TextFileToolbar({
           </View>
           {view && onViewChange ? (
             <SegmentedControl
-              size="xs"
+              size="sm"
               value={view}
               onValueChange={onViewChange}
               testID="file-preview-mode"
diff --git a/packages/app/src/git/actions-split-button.tsx b/packages/app/src/git/actions-split-button.tsx
index 64a550f144..eb52e5ca53 100644
--- a/packages/app/src/git/actions-split-button.tsx
+++ b/packages/app/src/git/actions-split-button.tsx
@@ -17,7 +17,7 @@ import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { actionsWithoutPrimary, type GitAction, type GitActions } from "@/git/policy";
 import { useGitActionRunner } from "@/git/use-actions";
-import { buttonControlHeight, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 
 interface GitActionsSplitButtonProps {
   gitActions: GitActions;
@@ -272,10 +272,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
@@ -296,10 +293,7 @@ const styles = StyleSheet.create((theme) => ({
       xs: 48,
       md: 42,
     },
-    height: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
@@ -330,24 +324,15 @@ const styles = StyleSheet.create((theme) => ({
     transform: [{ scale: 0.8 }],
   },
   splitButtonCaret: {
-    width: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderLeftWidth: theme.borderWidth[1],
     borderLeftColor: theme.colors.borderAccent,
   },
   iconButton: {
-    width: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
-    height: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
+    height: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderRadius: theme.borderRadius.md,
diff --git a/packages/app/src/git/changed-files-tree.tsx b/packages/app/src/git/changed-files-tree.tsx
index 0b88d33e96..f020cfa101 100644
--- a/packages/app/src/git/changed-files-tree.tsx
+++ b/packages/app/src/git/changed-files-tree.tsx
@@ -13,10 +13,10 @@ import {
   type DiffTreeRow,
 } from "@/git/diff-tree";
 import { FileHeader } from "@/git/file-header";
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 
 export interface ChangedFilesTreeProps {
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   collapsedFolderPaths: string[];
diff --git a/packages/app/src/git/checkout-status-cache.test.ts b/packages/app/src/git/checkout-status-cache.test.ts
index 026ec9d43a..bbfeb6d758 100644
--- a/packages/app/src/git/checkout-status-cache.test.ts
+++ b/packages/app/src/git/checkout-status-cache.test.ts
@@ -16,7 +16,7 @@ import {
   resolveWorkingDiffComparison,
   selectWorkingDiffComparison,
 } from "@/git/working-diff-comparison";
-import { draftAgentCommandsQueryKey } from "@/hooks/agent-commands-query";
+import { draftAgentCommandsQueryKey } from "@/agent-commands/cache";
 import {
   applyCheckoutStatusUpdateFromEvent,
   ensureCheckoutStatus,
diff --git a/packages/app/src/git/checkout-status-cache.ts b/packages/app/src/git/checkout-status-cache.ts
index ca5cbb3a7a..7a20e98fa2 100644
--- a/packages/app/src/git/checkout-status-cache.ts
+++ b/packages/app/src/git/checkout-status-cache.ts
@@ -8,7 +8,7 @@ import {
   invalidatePrPaneTimelineForCheckout,
 } from "@/git/query-keys";
 import { type CheckoutPrStatusPayload, normalizeCheckoutPrStatusPayload } from "@/git/pr-status";
-import { resetDraftAgentCommandsForCheckout } from "@/hooks/agent-commands-query";
+import { resetDraftAgentCommandsForCheckout } from "@/agent-commands/cache";
 
 export type CheckoutStatusPayload = CheckoutStatusResponse["payload"];
 export type { CheckoutPrStatusPayload } from "@/git/pr-status";
@@ -25,7 +25,7 @@ export async function fetchCheckoutStatus({
   serverId: string;
   cwd: string;
 }): Promise<CheckoutStatusPayload> {
-  const payload = await client.getCheckoutStatus(cwd);
+  const payload = normalizeCheckoutBaseRef(await client.getCheckoutStatus(cwd));
   return payload;
 }
 
@@ -56,7 +56,7 @@ export function applyCheckoutStatusUpdateFromEvent({
   serverId: string;
   message: CheckoutStatusUpdate;
 }): void {
-  const { payload } = message;
+  const payload = normalizeCheckoutBaseRef(message.payload);
   const prStatus = payload.prStatus
     ? normalizeCheckoutPrStatusPayload(payload.prStatus)
     : undefined;
@@ -88,6 +88,13 @@ export function applyCheckoutStatusUpdateFromEvent({
   }
 }
 
+function normalizeCheckoutBaseRef<T extends CheckoutStatusPayload>(payload: T): T {
+  // COMPAT(workspaceBaseBranch): hosts <= v0.11.2 only send the display ref; remove after 2027-10-14.
+  return !payload.isGit || payload.baseRefExact === undefined
+    ? payload
+    : { ...payload, baseRef: payload.baseRefExact };
+}
+
 // requestId changes on every emission and carries no PR state.
 function prStatusWithoutVolatileFields(
   prStatus: CheckoutPrStatusPayload,
diff --git a/packages/app/src/git/client-forge-module.ts b/packages/app/src/git/client-forge-module.ts
index d8293fc26f..f36fb18fb3 100644
--- a/packages/app/src/git/client-forge-module.ts
+++ b/packages/app/src/git/client-forge-module.ts
@@ -41,8 +41,15 @@ export interface ForgeReferencePath {
   kind: "change_request" | "issue";
   /** Path between the repository path and the numeric local id. */
   infix: string;
+  /**
+   * Shorthand marker the forge links in prose, e.g. GitHub `#12`, GitLab `!12`.
+   * Absent when the forge has no shorthand for this kind.
+   */
+  sigil?: ForgeReferenceSigil;
 }
 
+export type ForgeReferenceSigil = "#" | "!";
+
 /** Line/range anchor shared by every GitHub-family forge (github, gitea, forgejo, codeberg). */
 export function GITHUB_LINE_ANCHOR(start: number, end?: number): string {
   return end && end > start ? `#L${start}-L${end}` : `#L${start}`;
@@ -54,8 +61,8 @@ export const GITEA_FAMILY_URL_GRAMMAR: ForgeUrlGrammar = {
   blobInfix: "/src/branch/",
   lineAnchor: GITHUB_LINE_ANCHOR,
   referencePaths: [
-    { kind: "change_request", infix: "/pulls/" },
-    { kind: "issue", infix: "/issues/" },
+    { kind: "change_request", infix: "/pulls/", sigil: "!" },
+    { kind: "issue", infix: "/issues/", sigil: "#" },
   ],
 };
 
diff --git a/packages/app/src/git/diff-order.ts b/packages/app/src/git/diff-order.ts
index d57bb0ef29..0ad572866f 100644
--- a/packages/app/src/git/diff-order.ts
+++ b/packages/app/src/git/diff-order.ts
@@ -13,6 +13,6 @@ export function orderCheckoutDiffFiles(files: ParsedDiffFile[]): ParsedDiffFile[
   // chains, so it is skipped; the collapsed set is empty because the flat list
   // always carries every file, whatever the rail has collapsed.
   return flattenDiffTree(buildDiffTree(files), new Set()).flatMap((row) =>
-    row.kind === "file" ? [row.file] : [],
+    row.kind === "file" ? [files[row.fileIndex]] : [],
   );
 }
diff --git a/packages/app/src/git/diff-pane.tsx b/packages/app/src/git/diff-pane.tsx
index 3dd84f256a..3581166980 100644
--- a/packages/app/src/git/diff-pane.tsx
+++ b/packages/app/src/git/diff-pane.tsx
@@ -1,3 +1,4 @@
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { floatingActionsClearance } from "@/components/ui/floating-action-button";
 import { useState, useCallback, useMemo, type ReactElement, type ReactNode } from "react";
@@ -19,6 +20,7 @@ import type { Theme } from "@/styles/theme";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import {
   AlignJustify,
+  ArrowRight,
   ChevronDown,
   Columns2,
   ExternalLink,
@@ -61,6 +63,7 @@ import { GitActionsSplitButton } from "@/git/actions-split-button";
 import type { GitActions } from "@/git/policy";
 import { BranchSwitcher } from "@/components/branch-switcher";
 import { useGitActions } from "@/git/use-actions";
+import { WorkspaceBaseBranchPicker } from "@/git/workspace-base-branch-picker";
 import { GIT_ACTION_ICONS } from "@/git/action-icons";
 import { buildForgeSignInCommand, getForgePresentation, type Forge } from "@/git/forge";
 import { parseGitRemoteLocation } from "@getpaseo/protocol/git-remote";
@@ -201,6 +204,7 @@ const foregroundMutedIconColorMapping = (theme: Theme) => ({ color: theme.colors
 
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedAlignJustify = withUnistyles(AlignJustify);
+const ThemedArrowRight = withUnistyles(ArrowRight);
 const ThemedColumns2 = withUnistyles(Columns2);
 const ThemedPilcrow = withUnistyles(Pilcrow);
 const ThemedWrapText = withUnistyles(WrapText);
@@ -470,6 +474,8 @@ interface ChangesPullRequestLinkModel extends Pick<PrHint, "forge" | "number" |
 }
 
 interface ChangesRepositoryToolbarModel {
+  baseRef: string | null;
+  isWorktree: boolean;
   branchName: string | null;
   cwd: string;
   gitActions: GitActions | null;
@@ -496,6 +502,8 @@ interface ChangesHeaderProps {
 }
 
 interface BuildChangesHeaderModelInput {
+  baseRef: string | null;
+  isWorktree: boolean;
   branchName: string | null;
   committedDescription?: string;
   compact: boolean;
@@ -519,6 +527,8 @@ function buildChangesHeaderModel(input: BuildChangesHeaderModelInput): {
 } {
   return {
     repository: {
+      baseRef: input.baseRef,
+      isWorktree: input.isWorktree,
       branchName: input.branchName,
       cwd: input.cwd,
       gitActions: input.compact ? input.gitActions : null,
@@ -629,6 +639,10 @@ function ChangesToolbarTrailing({ children }: { children: ReactNode }) {
   return <ToolbarControls style={styles.changesToolbarControls}>{children}</ToolbarControls>;
 }
 
+function isManagedWorktree(status: { isPaseoOwnedWorktree?: boolean } | null | undefined): boolean {
+  return status?.isPaseoOwnedWorktree === true;
+}
+
 function ChangesRepositoryToolbar({
   compact,
   model,
@@ -654,6 +668,17 @@ function ChangesRepositoryToolbar({
           isGitCheckout
           testID="changes-branch-switcher"
         />
+        {model.baseRef && model.isWorktree ? (
+          <>
+            <ThemedArrowRight size={14} uniProps={extraMutedIconColorMapping} />
+            <WorkspaceBaseBranchPicker
+              serverId={model.serverId}
+              workspaceId={model.workspaceId}
+              cwd={model.cwd}
+              baseRef={model.baseRef}
+            />
+          </>
+        ) : null}
       </ChangesToolbarLeading>
       <ChangesToolbarTrailing>
         {model.pullRequest ? (
@@ -1070,6 +1095,7 @@ interface DiffBodyContentProps {
   emptyMessage: string;
   emptyAction: ChangesEmptyAction | null;
   children: ReactElement;
+  loadingLabel: string;
   checkingRepositoryLabel: string;
   notRepositoryLabel: string;
 }
@@ -1086,11 +1112,16 @@ function DiffBodyContent({
   emptyAction,
   children,
   checkingRepositoryLabel,
+  loadingLabel,
   notRepositoryLabel,
 }: DiffBodyContentProps) {
   if (isStatusLoading) {
     return (
-      <View style={styles.loadingContainer}>
+      <View
+        style={styles.loadingContainer}
+        accessibilityRole="progressbar"
+        accessibilityLabel={loadingLabel}
+      >
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
         <Text style={styles.loadingText}>{checkingRepositoryLabel}</Text>
       </View>
@@ -1112,12 +1143,16 @@ function DiffBodyContent({
   }
   if (isDiffLoading) {
     return (
-      <View style={styles.loadingContainer}>
+      <View
+        style={styles.loadingContainer}
+        accessibilityRole="progressbar"
+        accessibilityLabel={loadingLabel}
+      >
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
       </View>
     );
   }
-  if (diffTooLarge) {
+  if (diffTooLarge && !hasChanges) {
     return <DiffTooLargeState />;
   }
   if (diffErrorMessage) {
@@ -1134,7 +1169,7 @@ function DiffBodyContent({
         {emptyAction ? (
           <Button
             variant="ghost"
-            size="xs"
+            size="sm"
             testID="changes-empty-switch-mode"
             onPress={emptyAction.onPress}
           >
@@ -1296,7 +1331,7 @@ function ChangesTreeRail({
 }: {
   shown: boolean;
   children: ReactElement;
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1336,7 +1371,7 @@ function ChangesBody({
   children: ReactElement;
   desktopTreeVisible: boolean;
   isMobile: boolean;
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1561,6 +1596,7 @@ export function ChangesSurface({
     selectBase: handleSelectBase,
     selectAll: handleSelectAll,
     files,
+    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,
@@ -1810,6 +1846,7 @@ export function ChangesSurface({
         hasChanges={hasChanges}
         emptyMessage={emptyMessage}
         emptyAction={emptyAction}
+        loadingLabel={t("common.loading")}
         checkingRepositoryLabel={t("workspace.git.diff.checkingRepository")}
         notRepositoryLabel={t("workspace.git.diff.notRepository")}
       >
@@ -1840,7 +1877,7 @@ export function ChangesSurface({
       presentation={presentation}
       desktopTreeVisible={desktopTreeVisible}
       isMobile={isMobile}
-      files={files}
+      files={treeFiles}
       mode={workingMode}
       onSelectFile={handleSelectTreeFile}
       treeWidth={instanceState.treeWidth}
@@ -1904,6 +1941,8 @@ export function ChangesSurface({
   const changesHeaderModel = useMemo(
     () =>
       buildChangesHeaderModel({
+        baseRef: baseRef ?? null,
+        isWorktree: isManagedWorktree(status),
         branchName: currentBranchName,
         committedDescription: committedDiffDescription,
         compact: isMobile,
@@ -1921,6 +1960,8 @@ export function ChangesSurface({
         workspaceId,
       }),
     [
+      baseRef,
+      status,
       committedDiffDescription,
       currentBranchName,
       cwd,
diff --git a/packages/app/src/git/diff-sharing.ts b/packages/app/src/git/diff-sharing.ts
index 6bdac10ddf..8571de6630 100644
--- a/packages/app/src/git/diff-sharing.ts
+++ b/packages/app/src/git/diff-sharing.ts
@@ -1,7 +1,8 @@
 import { replaceEqualDeep } from "@tanstack/react-query";
-import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
+import type { CheckoutDiffSnapshot } from "./diff-snapshot";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
 
-type DiffPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
+type DiffPayload = CheckoutDiffSnapshot;
 
 /** File identity owns text-model reuse. Never reconstruct the hunk/token graph. */
 export function retainDiffFiles(
@@ -24,17 +25,26 @@ export function shareCheckoutDiff(previous: unknown, incoming: unknown): DiffPay
   const next = incoming as DiffPayload;
   const old = previous as DiffPayload | undefined;
   if (!old || old === next) return next;
+  // A new subscription announces its entries before the bodies arrive. That is
+  // progress on the first load only: once a diff has settled it stays on screen
+  // until the next revision commits, so an unchanged diff never repaints.
+  if (isLoadingSnapshot(next) && !isLoadingSnapshot(old)) return old;
   const files = retainDiffFiles(old.files, next.files);
   const error = replaceEqualDeep(old.error, next.error);
   return files === old.files &&
     error === old.error &&
     old.cwd === next.cwd &&
     old.requestId === next.requestId &&
+    old.entries === next.entries &&
     old.diffTooLarge === next.diffTooLarge
     ? old
     : { ...next, files, error };
 }
 
+function isLoadingSnapshot(payload: DiffPayload): boolean {
+  return payload.entries !== undefined;
+}
+
 export function shareCommitFileDiff(
   previous: unknown,
   incoming: unknown,
diff --git a/packages/app/src/git/diff-snapshot.ts b/packages/app/src/git/diff-snapshot.ts
new file mode 100644
index 0000000000..84f650b588
--- /dev/null
+++ b/packages/app/src/git/diff-snapshot.ts
@@ -0,0 +1,74 @@
+import type { DiffState, DiffEntry } from "@getpaseo/client";
+import type {
+  DiffError,
+  ParsedDiffFile,
+  SubscribeCheckoutDiffRequest,
+} from "@getpaseo/protocol/messages";
+export type DiffFileHeader = Omit<ParsedDiffFile, "hunks">;
+export interface CheckoutDiffSnapshot {
+  requestId: string;
+  cwd: string;
+  files: ParsedDiffFile[];
+  entries?: DiffEntry[];
+  error: DiffError | null;
+  diffTooLarge?: boolean;
+}
+export function checkoutDiffSnapshot(cwd: string, state: DiffState): CheckoutDiffSnapshot {
+  const common = { cwd, requestId: `diff:${state.revision}:${state.phase}` };
+  if (state.phase === "loading")
+    return { ...common, files: [], entries: state.entries, error: null };
+  if (state.phase === "error") return { ...common, files: [], error: state.error };
+  return { ...common, files: state.files, error: null, diffTooLarge: state.diffTooLarge };
+}
+export function diffEntryHeaders(entries: DiffEntry[]): DiffFileHeader[] {
+  return entries.map((entry) => ({
+    path: entry.path,
+    ...(entry.oldPath === null ? {} : { oldPath: entry.oldPath }),
+    isNew: entry.change === "added",
+    isDeleted: entry.change === "deleted",
+    additions: entry.additions,
+    deletions: entry.deletions,
+    status: entry.content === "binary" ? "binary" : "ok",
+  }));
+}
+export interface CheckoutDiffResult {
+  files: ParsedDiffFile[];
+  entries: DiffEntry[] | null;
+  payloadError: CheckoutDiffSnapshot["error"];
+  diffTooLarge: boolean;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+  error: null;
+}
+
+/**
+ * The result derives from the payload alone. Until a payload arrives there is no
+ * diff to describe, so the boundary reports loading rather than an empty diff —
+ * whether the query is idle (an inactive retained panel), in flight, or the host
+ * is disconnected. Reporting `files: []` as settled made callers render "+0 -0"
+ * and "No changes" for a diff nobody has fetched yet.
+ */
+export function deriveCheckoutDiffResult(payload: CheckoutDiffSnapshot | null): CheckoutDiffResult {
+  const payloadError = payload?.error ?? null;
+  return {
+    files: payload?.files ?? [],
+    entries: payload?.entries ?? null,
+    payloadError,
+    diffTooLarge: payload?.diffTooLarge === true,
+    isLoading: payload === null || payload.entries !== undefined,
+    isFetching: false,
+    isError: Boolean(payloadError),
+    error: null,
+  };
+}
+
+export function checkoutDiffComparisonError(
+  compare: Pick<SubscribeCheckoutDiffRequest["compare"], "mode" | "baseRef">,
+): DiffError | null {
+  if (compare.mode === "uncommitted" || compare.baseRef?.trim()) return null;
+  return {
+    code: "INVALID_COMPARE",
+    message: "Comparison base is unavailable. Select Uncommitted to view pending changes.",
+  };
+}
diff --git a/packages/app/src/git/diff-tree.ts b/packages/app/src/git/diff-tree.ts
index 49709cd5e2..c3130b1cae 100644
--- a/packages/app/src/git/diff-tree.ts
+++ b/packages/app/src/git/diff-tree.ts
@@ -1,6 +1,6 @@
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 
-// Builds a directory hierarchy from the `ParsedDiffFile[]` the Changes view
+// Builds a directory hierarchy from the `DiffFileHeader[]` the Changes view
 // renders. The tree renders on every form factor, consistent with the Files
 // explorer.
 //
@@ -17,7 +17,7 @@ import type { ParsedDiffFile } from "@/git/use-diff-query";
 
 export interface DiffTreeFileNode {
   kind: "file";
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   fileIndex: number;
   /** basename, e.g. "diff-pane.tsx" */
   name: string;
@@ -47,7 +47,7 @@ export interface DiffTreeFolderRow {
 
 export interface DiffTreeFileRow {
   kind: "file";
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   fileIndex: number;
   depth: number;
 }
@@ -73,7 +73,7 @@ function sortTree(node: DiffTreeDirNode): void {
 }
 
 /** Build the (uncompressed) directory tree. Returns the virtual root (dirPath ""). */
-export function buildDiffTree(files: ParsedDiffFile[]): DiffTreeDirNode {
+export function buildDiffTree(files: DiffFileHeader[]): DiffTreeDirNode {
   const root: DiffTreeDirNode = { kind: "dir", dirPath: "", name: "", children: [] };
   const dirByPath = new Map<string, DiffTreeDirNode>([["", root]]);
 
diff --git a/packages/app/src/git/file-header.tsx b/packages/app/src/git/file-header.tsx
index d19d58cbf2..39427a612b 100644
--- a/packages/app/src/git/file-header.tsx
+++ b/packages/app/src/git/file-header.tsx
@@ -28,11 +28,11 @@ import {
   fileNameForPath,
   formatDiffCount,
 } from "@/git/file-header-presentation";
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
 
 export interface FileHeaderProps {
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   workspaceFileDragScope?: { serverId: string; workspaceId: string };
   bodyVisible: boolean;
   showsBodyState?: boolean;
@@ -73,7 +73,7 @@ function expandedAriaValue(showsBodyState: boolean, bodyVisible: boolean): boole
   return showsBodyState ? bodyVisible : undefined;
 }
 
-function fileHeaderAccessibilityLabel(canvasRendered: boolean, file: ParsedDiffFile) {
+function fileHeaderAccessibilityLabel(canvasRendered: boolean, file: DiffFileHeader) {
   if (!canvasRendered) return undefined;
   return `${file.path}, +${formatDiffCount(file.additions)}, -${formatDiffCount(file.deletions)}`;
 }
@@ -130,7 +130,7 @@ function fileHeaderNameStyle(showsBodyState: boolean, isHovered: boolean) {
   ];
 }
 
-function fileChange(file: ParsedDiffFile): "added" | "deleted" | "modified" {
+function fileChange(file: DiffFileHeader): "added" | "deleted" | "modified" {
   return diffFileChangeKind(file);
 }
 
diff --git a/packages/app/src/git/forge-shorthand/index.tsx b/packages/app/src/git/forge-shorthand/index.tsx
new file mode 100644
index 0000000000..5e40874c0a
--- /dev/null
+++ b/packages/app/src/git/forge-shorthand/index.tsx
@@ -0,0 +1,35 @@
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { createForgeShorthand, type ForgeShorthand } from "./shorthand";
+
+export { createForgeShorthand, type ForgeShorthand } from "./shorthand";
+
+const ForgeShorthandContext = createContext<ForgeShorthand | null>(null);
+
+/** Makes `#12`-style references in descendant Markdown open on the workspace forge. */
+export function ForgeShorthandProvider({
+  forge,
+  remoteUrl,
+  children,
+}: {
+  forge: string | null | undefined;
+  remoteUrl: string | null | undefined;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => createForgeShorthand({ forge, remoteUrl }), [forge, remoteUrl]);
+  return <ForgeShorthandContext.Provider value={value}>{children}</ForgeShorthandContext.Provider>;
+}
+
+export function useForgeShorthand(): ForgeShorthand | null {
+  return useContext(ForgeShorthandContext);
+}
+
+/** Carries the shorthand environment across a portal. */
+export function useForgeShorthandBridge() {
+  const value = useContext(ForgeShorthandContext);
+  return useCallback(
+    (children: ReactNode) => (
+      <ForgeShorthandContext.Provider value={value}>{children}</ForgeShorthandContext.Provider>
+    ),
+    [value],
+  );
+}
diff --git a/packages/app/src/git/forge-shorthand/shorthand.test.ts b/packages/app/src/git/forge-shorthand/shorthand.test.ts
new file mode 100644
index 0000000000..7da4ea1014
--- /dev/null
+++ b/packages/app/src/git/forge-shorthand/shorthand.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createForgeShorthand } from "./shorthand";
+
+function matches(shorthand: { pattern: string }, text: string): string[] {
+  return [...text.matchAll(new RegExp(shorthand.pattern, "g"))].map((match) => match[0]);
+}
+
+describe("createForgeShorthand", () => {
+  const github = createForgeShorthand({
+    forge: "github",
+    remoteUrl: "git@github.com:getpaseo/paseo.git",
+  })!;
+  const gitlab = createForgeShorthand({
+    forge: "gitlab",
+    remoteUrl: "https://gitlab.com/g/p.git",
+  })!;
+
+  it("resolves same-repo and cross-repo references on the remote's host", () => {
+    expect(github.resolve("#8613")).toBe("https://github.com/getpaseo/paseo/issues/8613");
+    expect(github.resolve("acme/tools#4")).toBe("https://github.com/acme/tools/issues/4");
+    expect(gitlab.resolve("!7")).toBe("https://gitlab.com/g/p/-/merge_requests/7");
+    expect(gitlab.resolve("g/sub/q#3")).toBe("https://gitlab.com/g/sub/q/-/issues/3");
+  });
+
+  it("only recognizes the sigils the forge declares", () => {
+    expect(matches(github, "see #1 and !2")).toEqual(["#1"]);
+    expect(github.resolve("!2")).toBeNull();
+    expect(matches(gitlab, "see #1 and !2")).toEqual(["#1", "!2"]);
+  });
+
+  it("recognizes references only at word boundaries", () => {
+    expect(
+      matches(
+        github,
+        "(#1), #2. acme/tools#3, foo#4 #5abc &#6; https://x/#7 #0 #08 wow!9 user@host#10",
+      ),
+    ).toEqual(["#1", "#2", "acme/tools#3"]);
+  });
+
+  it("falls back to the cloud host forge when the daemon reports none", () => {
+    expect(
+      createForgeShorthand({ forge: undefined, remoteUrl: "git@github.com:a/b.git" })?.resolve(
+        "#1",
+      ),
+    ).toBe("https://github.com/a/b/issues/1");
+  });
+
+  it("is absent without a remote or a known forge", () => {
+    expect(createForgeShorthand({ forge: "github", remoteUrl: null })).toBeNull();
+    expect(
+      createForgeShorthand({ forge: undefined, remoteUrl: "git@git.corp:a/b.git" }),
+    ).toBeNull();
+  });
+});
diff --git a/packages/app/src/git/forge-shorthand/shorthand.ts b/packages/app/src/git/forge-shorthand/shorthand.ts
new file mode 100644
index 0000000000..84a97bfb29
--- /dev/null
+++ b/packages/app/src/git/forge-shorthand/shorthand.ts
@@ -0,0 +1,55 @@
+import type { ForgeReferenceSigil } from "@/git/client-forge-module";
+import { forgeFromRemoteUrl } from "@/git/forge";
+import { getClientForgeLogicModule } from "@/git/forges";
+import { buildForgeReferenceUrl } from "@/git/forge-url";
+
+/**
+ * Shorthand references in prose, such as `#12`, `!12` or `owner/repo#12`,
+ * resolved against one workspace remote.
+ */
+export interface ForgeShorthand {
+  /** Regex source for recognizing references in Markdown text. */
+  pattern: string;
+  /** Web URL for a recognized reference, or null. */
+  resolve(text: string): string | null;
+}
+
+// Keep these in the syntax shared by JavaScript, ICU and java.util.regex: the
+// pattern runs in the native Markdown engines too.
+const REPO = String.raw`[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)+`;
+const NUMBER = String.raw`[1-9][0-9]{0,8}`;
+// A reference never continues a word, path, URL fragment or entity.
+const BEFORE = String.raw`(?<![A-Za-z0-9_./@#!&-])`;
+const AFTER = String.raw`(?![A-Za-z0-9_])`;
+const REFERENCE = new RegExp(String.raw`^(?:(${REPO}))?([#!])(${NUMBER})$`);
+
+export function createForgeShorthand(input: {
+  forge: string | null | undefined;
+  remoteUrl: string | null | undefined;
+}): ForgeShorthand | null {
+  const remoteUrl = input.remoteUrl;
+  const forge = input.forge || forgeFromRemoteUrl(remoteUrl);
+  if (!forge || !remoteUrl) return null;
+  const sigils = forgeSigils(forge).filter(
+    (sigil) => buildForgeReferenceUrl(forge, { remoteUrl, sigil, number: 1 }) !== null,
+  );
+  if (sigils.length === 0) return null;
+  return {
+    pattern: `${BEFORE}(?:${REPO})?[${sigils.join("")}]${NUMBER}${AFTER}`,
+    resolve(text) {
+      const match = REFERENCE.exec(text);
+      if (!match) return null;
+      return buildForgeReferenceUrl(forge, {
+        remoteUrl,
+        repo: match[1] ?? null,
+        sigil: match[2] as ForgeReferenceSigil,
+        number: Number(match[3]),
+      });
+    },
+  };
+}
+
+function forgeSigils(forge: string): ForgeReferenceSigil[] {
+  const paths = getClientForgeLogicModule(forge)?.urlGrammar?.referencePaths ?? [];
+  return paths.flatMap((path) => (path.sigil ? [path.sigil] : []));
+}
diff --git a/packages/app/src/git/forge-url.test.ts b/packages/app/src/git/forge-url.test.ts
index c7a250f9a4..e0deca00ff 100644
--- a/packages/app/src/git/forge-url.test.ts
+++ b/packages/app/src/git/forge-url.test.ts
@@ -3,9 +3,77 @@ import {
   buildForgeBlobUrl,
   buildForgeBranchTreeUrl,
   buildForgeChecksUrl,
+  buildForgeReferenceUrl,
   hasForgeWebUrls,
 } from "./forge-url";
 
+describe("buildForgeReferenceUrl", () => {
+  it.each([
+    ["github", "git@github.com:acme/repo.git", "#", null, "https://github.com/acme/repo/issues/12"],
+    ["github", "git@github.com:acme/repo.git", "!", null, null],
+    [
+      "github",
+      "https://github.com/acme/repo",
+      "#",
+      "other/tools",
+      "https://github.com/other/tools/issues/12",
+    ],
+    ["gitlab", "git@gitlab.com:g/sub/p.git", "#", null, "https://gitlab.com/g/sub/p/-/issues/12"],
+    [
+      "gitlab",
+      "git@gitlab.com:g/sub/p.git",
+      "!",
+      null,
+      "https://gitlab.com/g/sub/p/-/merge_requests/12",
+    ],
+    [
+      "gitlab",
+      "https://gitlab.corp:8443/g/p.git",
+      "!",
+      "g/q",
+      "https://gitlab.corp:8443/g/q/-/merge_requests/12",
+    ],
+    [
+      "codeberg",
+      "https://codeberg.org/acme/repo.git",
+      "!",
+      null,
+      "https://codeberg.org/acme/repo/pulls/12",
+    ],
+    [
+      "gitea",
+      "http://forge.test:3000/team/repo.git",
+      "#",
+      null,
+      "http://forge.test:3000/team/repo/issues/12",
+    ],
+    [
+      "github",
+      "http://github.com/acme/repo.git",
+      "#",
+      null,
+      "https://github.com/acme/repo/issues/12",
+    ],
+    [
+      "forgejo",
+      "git@forge.example:acme/repo.git",
+      "#",
+      null,
+      "https://forge.example/acme/repo/issues/12",
+    ],
+    ["bitbucket", "git@bitbucket.org:acme/repo.git", "#", null, null],
+    ["github", null, "#", null, null],
+    ["github", "git@github.com:acme/repo.git", "#", "../escape", null],
+  ] as const)("builds %s %s %s in %s", (forge, remoteUrl, sigil, repo, expected) => {
+    expect(buildForgeReferenceUrl(forge, { remoteUrl, repo, sigil, number: 12 })).toBe(expected);
+  });
+
+  it("rejects non-positive numbers", () => {
+    const remoteUrl = "git@github.com:acme/repo.git";
+    expect(buildForgeReferenceUrl("github", { remoteUrl, sigil: "#", number: 0 })).toBeNull();
+  });
+});
+
 describe("buildForgeChecksUrl", () => {
   it.each([
     [
diff --git a/packages/app/src/git/forge-url.ts b/packages/app/src/git/forge-url.ts
index 61bf6bdb8d..4fd86950e9 100644
--- a/packages/app/src/git/forge-url.ts
+++ b/packages/app/src/git/forge-url.ts
@@ -12,6 +12,7 @@
  */
 import { getForgeDefinition } from "@getpaseo/protocol/forge-manifest";
 import { normalizeHost, parseGitRemoteLocation } from "@getpaseo/protocol/git-remote";
+import type { ForgeReferenceSigil } from "@/git/client-forge-module";
 import { getClientForgeLogicModule } from "@/git/forges";
 
 export interface ForgeBlobUrlInput {
@@ -27,6 +28,14 @@ export interface ForgeBranchTreeUrlInput {
   branch: string | null | undefined;
 }
 
+export interface ForgeReferenceUrlInput {
+  remoteUrl: string | null | undefined;
+  /** Repository path of a cross-repository reference; the remote's repository when absent. */
+  repo?: string | null;
+  sigil: ForgeReferenceSigil;
+  number: number;
+}
+
 export function buildForgeChecksUrl(forge: string, changeRequestUrl: string): string | null {
   const suffix = getClientForgeLogicModule(forge)?.urlGrammar?.changeRequestChecksSuffix;
   if (!suffix) {
@@ -45,6 +54,8 @@ export function buildForgeChecksUrl(forge: string, changeRequestUrl: string): st
 }
 
 interface ForgeWebLocation {
+  /** "http" only for a self-hosted http:// remote; every other remote browses over https. */
+  scheme: "http" | "https";
   host: string;
   /** Non-default port for a self-hosted http(s) origin, or undefined. */
   port?: string;
@@ -87,16 +98,18 @@ function resolveForgeWebLocation(
     !isCloudHost && (location.transport === "http" || location.transport === "https")
       ? location.port
       : undefined;
-  return { host: webHost, port, repo: location.path };
+  const scheme = !isCloudHost && location.transport === "http" ? "http" : "https";
+  return { scheme, host: webHost, port, repo: location.path };
 }
 
 function encodeBranch(branch: string): string {
   return branch.split("/").map(encodeURIComponent).join("/");
 }
 
-/** Host, plus `:port` when the remote pins a non-default port. */
-function forgeAuthority(location: ForgeWebLocation): string {
-  return location.port ? `${location.host}:${location.port}` : location.host;
+/** Scheme and host, plus `:port` when the remote pins a non-default port. */
+function forgeOrigin(location: ForgeWebLocation): string {
+  const authority = location.port ? `${location.host}:${location.port}` : location.host;
+  return `${location.scheme}://${authority}`;
 }
 
 function normalizeBlobPath(path: string | null | undefined): string | null {
@@ -131,7 +144,7 @@ export function buildForgeBranchTreeUrl(
   if (!grammar || !location || !branch || branch === "HEAD") {
     return null;
   }
-  return `https://${forgeAuthority(location)}/${location.repo}${grammar.treeInfix}${encodeBranch(branch)}`;
+  return `${forgeOrigin(location)}/${location.repo}${grammar.treeInfix}${encodeBranch(branch)}`;
 }
 
 export function buildForgeBlobUrl(forge: string, input: ForgeBlobUrlInput): string | null {
@@ -143,13 +156,40 @@ export function buildForgeBlobUrl(forge: string, input: ForgeBlobUrlInput): stri
     return null;
   }
   const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
-  let url = `https://${forgeAuthority(location)}/${location.repo}${grammar.blobInfix}${encodeBranch(branch)}/${encodedPath}`;
+  let url = `${forgeOrigin(location)}/${location.repo}${grammar.blobInfix}${encodeBranch(branch)}/${encodedPath}`;
   if (input.lineStart && input.lineStart > 0) {
     url += grammar.lineAnchor(input.lineStart, input.lineEnd);
   }
   return url;
 }
 
+/**
+ * Web URL of a shorthand reference such as `#12` or `group/project!12`. A
+ * cross-repository reference stays on the remote's host. Null when the forge
+ * has no shorthand for the sigil.
+ */
+export function buildForgeReferenceUrl(
+  forge: string,
+  input: ForgeReferenceUrlInput,
+): string | null {
+  const referencePath = getClientForgeLogicModule(forge)?.urlGrammar?.referencePaths?.find(
+    (path) => path.sigil === input.sigil,
+  );
+  const location = resolveForgeWebLocation(forge, input.remoteUrl);
+  const repo = input.repo ?? location?.repo;
+  if (
+    !referencePath ||
+    !location ||
+    !repo ||
+    !isValidRepoPath(repo) ||
+    !Number.isSafeInteger(input.number) ||
+    input.number <= 0
+  ) {
+    return null;
+  }
+  return `${forgeOrigin(location)}/${repo}${referencePath.infix}${input.number}`;
+}
+
 /** Whether the forge has web URL builders (i.e. a known URL grammar). */
 export function hasForgeWebUrls(forge: string): boolean {
   return getClientForgeLogicModule(forge)?.urlGrammar !== undefined;
diff --git a/packages/app/src/git/forges/github.ts b/packages/app/src/git/forges/github.ts
index 10290a2849..146fec827d 100644
--- a/packages/app/src/git/forges/github.ts
+++ b/packages/app/src/git/forges/github.ts
@@ -89,7 +89,8 @@ export const githubForgeLogic = {
     changeRequestChecksSuffix: "/checks",
     referencePaths: [
       { kind: "change_request", infix: "/pull/" },
-      { kind: "issue", infix: "/issues/" },
+      // GitHub redirects /issues/N to /pull/N, so `#N` covers both kinds.
+      { kind: "issue", infix: "/issues/", sigil: "#" },
     ],
   },
   facts: defineForgeFacts({
diff --git a/packages/app/src/git/forges/gitlab.ts b/packages/app/src/git/forges/gitlab.ts
index 15a67aeedf..5a98478b79 100644
--- a/packages/app/src/git/forges/gitlab.ts
+++ b/packages/app/src/git/forges/gitlab.ts
@@ -166,8 +166,8 @@ export const gitlabForgeLogic = {
     lineAnchor: gitlabLineAnchor,
     changeRequestChecksSuffix: "/pipelines",
     referencePaths: [
-      { kind: "change_request", infix: "/-/merge_requests/" },
-      { kind: "issue", infix: "/-/issues/" },
+      { kind: "change_request", infix: "/-/merge_requests/", sigil: "!" },
+      { kind: "issue", infix: "/-/issues/", sigil: "#" },
     ],
   },
   facts: defineForgeFacts({
diff --git a/packages/app/src/git/policy.test.ts b/packages/app/src/git/policy.test.ts
index efbd61efa6..34f6e93d1d 100644
--- a/packages/app/src/git/policy.test.ts
+++ b/packages/app/src/git/policy.test.ts
@@ -2,7 +2,13 @@ import { afterEach, describe, expect, it } from "vitest";
 import { CheckoutPrStatusSchema } from "@getpaseo/protocol/messages";
 import { i18n } from "@/i18n/i18next";
 
-import { actionsWithoutPrimary, buildGitActions, type BuildGitActionsInput } from "./policy";
+import {
+  actionsWithoutPrimary,
+  buildGitActions,
+  isCurrentBranchBase,
+  canMergeIntoLocalBase,
+  type BuildGitActionsInput,
+} from "./policy";
 import { deriveMergeCapability, type ForgeSpecificStatusFacts } from "./merge-capability";
 
 type GithubMergeFactsFixture = ForgeSpecificStatusFacts & {
@@ -72,6 +78,7 @@ function createInput(
     hasRemote: false,
     isPaseoOwnedWorktree: false,
     isOnBaseBranch: true,
+    canMergeLocally: true,
     hasUncommittedChanges: false,
     baseRefAvailable: true,
     baseRefLabel: "main",
@@ -208,6 +215,81 @@ describe("git-actions-policy", () => {
     ]);
   });
 
+  it("distinguishes exact local and remote base refs and retains legacy names", () => {
+    expect(isCurrentBranchBase("release", "refs/heads/release")).toBe(true);
+    expect(isCurrentBranchBase("release", "refs/remotes/origin/release")).toBe(false);
+    expect(isCurrentBranchBase("release", "release")).toBe(true);
+    expect(isCurrentBranchBase("release", "origin/release")).toBe(true);
+    expect(isCurrentBranchBase(null, "refs/heads/release")).toBe(false);
+    expect(canMergeIntoLocalBase("release", "refs/heads/release")).toBe(false);
+    expect(canMergeIntoLocalBase("feature", "refs/remotes/origin/release")).toBe(true);
+    expect(canMergeIntoLocalBase("release", "refs/remotes/upstream/release")).toBe(false);
+  });
+
+  it("offers local merge when the selected local base starts with origin slash", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: isCurrentBranchBase("release", "refs/heads/origin/release"),
+        canMergeLocally: canMergeIntoLocalBase("release", "refs/heads/origin/release"),
+        baseRefLabel: "origin/release",
+        aheadCount: 1,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-branch");
+  });
+
+  it("offers update but not local merge for a non-origin remote base", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: false,
+        canMergeLocally: canMergeIntoLocalBase("feature", "refs/remotes/upstream/release"),
+        baseRefLabel: "upstream/release",
+        aheadCount: 1,
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+    expect(actionsWithoutPrimary(actions).map((action) => action.id)).not.toContain("merge-branch");
+  });
+
+  it("does not offer merging into the current local branch when the remote base shares its name", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: false,
+        canMergeLocally: canMergeIntoLocalBase("release", "refs/remotes/origin/release"),
+        baseRefLabel: "release",
+        aheadCount: 1,
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+    expect(actionsWithoutPrimary(actions).map((action) => action.id)).not.toContain("merge-branch");
+  });
+
+  it("offers update from the same-named remote base when it is ahead", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: isCurrentBranchBase("release", "refs/remotes/origin/release"),
+        baseRefLabel: "release",
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+  });
+
   it("drops a promoted merge action from the remaining menu actions", () => {
     const actions = buildGitActions(
       createInput({
diff --git a/packages/app/src/git/policy.ts b/packages/app/src/git/policy.ts
index 71d63eae37..9f18e65755 100644
--- a/packages/app/src/git/policy.ts
+++ b/packages/app/src/git/policy.ts
@@ -50,6 +50,29 @@ interface GitActionRuntimeState {
   handler: () => void;
 }
 
+export function isCurrentBranchBase(
+  currentBranch: string | null | undefined,
+  baseRef: string | null | undefined,
+): boolean {
+  if (!currentBranch || !baseRef) return false;
+  if (baseRef.startsWith("refs/heads/")) return baseRef === `refs/heads/${currentBranch}`;
+  if (baseRef.startsWith("refs/")) return false;
+  // Older hosts send a display name, which cannot distinguish a local ref from its remote.
+  return currentBranch === baseRef.replace(/^origin\//, "");
+}
+
+export function canMergeIntoLocalBase(
+  currentBranch: string | null | undefined,
+  baseRef: string | null | undefined,
+): boolean {
+  if (!currentBranch || !baseRef) return false;
+  if (baseRef.startsWith("refs/remotes/") && !baseRef.startsWith("refs/remotes/origin/")) {
+    return false;
+  }
+  const localTarget = baseRef.replace(/^(?:refs\/heads\/|refs\/remotes\/origin\/|origin\/)/, "");
+  return currentBranch !== localTarget;
+}
+
 export interface BuildGitActionsInput {
   isGit: boolean;
   githubFeaturesEnabled: boolean;
@@ -68,6 +91,7 @@ export interface BuildGitActionsInput {
   hasRemote: boolean;
   isPaseoOwnedWorktree: boolean;
   isOnBaseBranch: boolean;
+  canMergeLocally: boolean;
   hasUncommittedChanges: boolean;
   baseRefAvailable: boolean;
   baseRefLabel: string;
@@ -349,7 +373,7 @@ function getPrimaryActionId(input: BuildGitActionsInput): GitActionId | null {
   if (input.shipDefault === "pr" && canUsePullRequestActionAsShipDefault(input)) {
     return "pr";
   }
-  if (!input.isOnBaseBranch && input.aheadCount > 0) {
+  if (!input.isOnBaseBranch && input.canMergeLocally && input.aheadCount > 0) {
     return "merge-branch";
   }
   if (!input.isOnBaseBranch && canMergeFromBase(input)) {
@@ -380,7 +404,7 @@ function getPullRequestActionIds(filter: {
 function getFeatureActionIds(input: BuildGitActionsInput): GitActionId[] {
   return [
     "merge-from-base",
-    "merge-branch",
+    ...(input.canMergeLocally ? (["merge-branch"] as const) : []),
     ...getPullRequestActionIds({ roles: ["status", "direct", "auto"], input }),
   ];
 }
diff --git a/packages/app/src/git/pull-request-panel/activity-skeleton.tsx b/packages/app/src/git/pull-request-panel/activity-skeleton.tsx
index 72c315f3b6..473d6e6e02 100644
--- a/packages/app/src/git/pull-request-panel/activity-skeleton.tsx
+++ b/packages/app/src/git/pull-request-panel/activity-skeleton.tsx
@@ -1,39 +1,9 @@
-import { useEffect, useMemo, useRef } from "react";
-import { Animated, View, type StyleProp, type ViewStyle } from "react-native";
+import { View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { SkeletonPulse, useSkeletonPulse } from "@/components/ui/skeleton";
 
 const ROW_KEYS = [0, 1, 2].map((i) => `pr-activity-skeleton-row-${i}`);
 
-export function useSkeletonPulse(): Animated.Value {
-  const pulse = useRef(new Animated.Value(0)).current;
-  useEffect(() => {
-    const animation = Animated.loop(
-      Animated.sequence([
-        Animated.timing(pulse, { toValue: 1, duration: 1000, useNativeDriver: true }),
-        Animated.timing(pulse, { toValue: 0, duration: 1000, useNativeDriver: true }),
-      ]),
-    );
-    animation.start();
-    return () => animation.stop();
-  }, [pulse]);
-  return pulse;
-}
-
-export function SkeletonPulse({
-  pulse,
-  style,
-}: {
-  pulse: Animated.Value;
-  style: StyleProp<ViewStyle>;
-}) {
-  const opacity = pulse.interpolate({
-    inputRange: [0, 1],
-    outputRange: [0.4, 0.8],
-  });
-  const pulseStyle = useMemo(() => [style, { opacity }], [style, opacity]);
-  return <Animated.View style={pulseStyle} />;
-}
-
 export function PrActivitySkeleton() {
   const pulse = useSkeletonPulse();
 
diff --git a/packages/app/src/git/pull-request-panel/checks-section.tsx b/packages/app/src/git/pull-request-panel/checks-section.tsx
index ac1ba078c5..ad542c8695 100644
--- a/packages/app/src/git/pull-request-panel/checks-section.tsx
+++ b/packages/app/src/git/pull-request-panel/checks-section.tsx
@@ -215,7 +215,7 @@ function CheckRow({
         {attachEnabled && canAddPullRequestCheckLogsToChat(check) ? (
           <Button
             variant="ghost"
-            size="xs"
+            size="sm"
             leftIcon={MessageSquarePlus}
             loading={isAddingLogsToChat}
             onPress={handleAddLogsToChat}
diff --git a/packages/app/src/git/pull-request-panel/pane-error.tsx b/packages/app/src/git/pull-request-panel/pane-error.tsx
index 51eb7bbfd3..c593eb0c4c 100644
--- a/packages/app/src/git/pull-request-panel/pane-error.tsx
+++ b/packages/app/src/git/pull-request-panel/pane-error.tsx
@@ -15,7 +15,7 @@ export function PullRequestPaneError({
   return (
     <View style={styles.root} testID="pr-pane-error">
       <Text style={styles.message}>{message ?? t("workspace.git.diff.failedRefresh")}</Text>
-      <Button variant="ghost" size="xs" leftIcon={RotateCw} onPress={onRetry}>
+      <Button variant="ghost" size="sm" leftIcon={RotateCw} onPress={onRetry}>
         {t("common.actions.retry")}
       </Button>
     </View>
diff --git a/packages/app/src/git/pull-request-panel/pane-skeleton.tsx b/packages/app/src/git/pull-request-panel/pane-skeleton.tsx
index 9ddeeadf2c..d7ab363e49 100644
--- a/packages/app/src/git/pull-request-panel/pane-skeleton.tsx
+++ b/packages/app/src/git/pull-request-panel/pane-skeleton.tsx
@@ -2,7 +2,8 @@ import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
 import { PaneContentToolbar } from "@/components/ui/pane-content-toolbar";
-import { PrActivitySkeleton, SkeletonPulse, useSkeletonPulse } from "./activity-skeleton";
+import { SkeletonPulse, useSkeletonPulse } from "@/components/ui/skeleton";
+import { PrActivitySkeleton } from "./activity-skeleton";
 
 const CHECK_ROW_KEYS = [0, 1, 2].map((i) => `pr-pane-skeleton-check-${i}`);
 
diff --git a/packages/app/src/git/pull-request-panel/pane.tsx b/packages/app/src/git/pull-request-panel/pane.tsx
index 429dd2be0e..1f36a8749e 100644
--- a/packages/app/src/git/pull-request-panel/pane.tsx
+++ b/packages/app/src/git/pull-request-panel/pane.tsx
@@ -484,7 +484,7 @@ export function PullRequestPane({
           <View style={styles.toolbarActions}>
             <Button
               variant="ghost"
-              size="xs"
+              size="sm"
               leftIcon={ExternalLink}
               onPress={handleOpenPrUrl}
               style={styles.viewButton}
@@ -587,7 +587,7 @@ export function PullRequestPane({
             <View style={styles.activityToolbar}>
               <Button
                 variant="ghost"
-                size="xs"
+                size="sm"
                 leftIcon={MessageSquarePlus}
                 onPress={handleAddAllToChat}
                 disabled={activityLoading}
@@ -882,7 +882,7 @@ function SingleActivityCard({
             <View style={styles.cardFooter}>
               <Button
                 variant="ghost"
-                size="xs"
+                size="sm"
                 leftIcon={MessageSquarePlus}
                 onPress={handleAddToChat}
               >
@@ -959,7 +959,7 @@ function ReviewCard({
           {collapsed && attachEnabled && canAddPullRequestActivityToChat(review) ? (
             <Button
               variant="ghost"
-              size="xs"
+              size="sm"
               leftIcon={MessageSquarePlus}
               onPress={handleAddToChat}
               style={styles.checkAddButton}
@@ -994,7 +994,7 @@ function ReviewCard({
             <View style={styles.cardFooter}>
               <Button
                 variant="ghost"
-                size="xs"
+                size="sm"
                 leftIcon={MessageSquarePlus}
                 onPress={handleAddToChat}
               >
@@ -1127,7 +1127,7 @@ function ThreadBlock({
             <View style={styles.cardFooter}>
               <Button
                 variant="ghost"
-                size="xs"
+                size="sm"
                 leftIcon={MessageSquarePlus}
                 onPress={handleAddThreadToChat}
               >
diff --git a/packages/app/src/git/pull-request-panel/section-kit.tsx b/packages/app/src/git/pull-request-panel/section-kit.tsx
index ab7b07ee9f..b4a9d00a3a 100644
--- a/packages/app/src/git/pull-request-panel/section-kit.tsx
+++ b/packages/app/src/git/pull-request-panel/section-kit.tsx
@@ -2,7 +2,7 @@ import React, { type ReactNode } from "react";
 import { Pressable, Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import type { CountedCheckPresentation } from "@/git/check-presentation";
-import { CONTROL_HEIGHTS } from "@/components/ui/control-geometry";
+import { CONTROL_HEIGHTS, mapLayout } from "@/components/ui/control-geometry";
 import {
   CheckPresentationIcon,
   getCheckPresentationTone,
@@ -163,11 +163,11 @@ export const sectionKitStyles = StyleSheet.create((theme) => ({
     alignItems: "center",
     gap: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
-    // Fixed, not minHeight plus padding. A row's trailing slot holds an xs Button
-    // (28pt), which stacked on the vertical padding and made rows with an
+    // Fixed, not minHeight plus padding. A row's trailing slot holds an sm Button
+    // , which stacked on the vertical padding and made rows with an
     // "Add to chat" button taller than rows without one. The row is single-line by
     // construction, so it declares a height the button fits inside instead.
-    height: CONTROL_HEIGHTS.compact,
+    height: mapLayout(CONTROL_HEIGHTS.sm, (height) => height + theme.spacing[1]),
   },
   checkName: {
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/git/use-actions.tsx b/packages/app/src/git/use-actions.tsx
index 05e65a21a5..13f7587623 100644
--- a/packages/app/src/git/use-actions.tsx
+++ b/packages/app/src/git/use-actions.tsx
@@ -12,6 +12,8 @@ import { type CheckoutStatusPayload, useCheckoutStatusQuery } from "@/git/use-st
 import { type CheckoutPrStatusPayload, useCheckoutPrStatusQuery } from "@/git/use-pr-status-query";
 import {
   buildGitActions,
+  isCurrentBranchBase,
+  canMergeIntoLocalBase,
   narrowPullRequestState,
   type BuildGitActionsInput,
   type GitAction,
@@ -116,7 +118,7 @@ interface DeriveGitActionsStateArgs {
   hasUncommittedChanges: boolean;
   postShipArchiveSuggested: boolean;
   isStatusLoading: boolean;
-  baseRefLabel: string;
+  baseRef: string | undefined;
 }
 
 interface DerivedGitActionsState {
@@ -129,6 +131,7 @@ interface DerivedGitActionsState {
   hasRemote: boolean;
   isPaseoOwnedWorktree: boolean;
   isOnBaseBranch: boolean;
+  canMergeLocally: boolean;
   shouldPromoteArchive: boolean;
 }
 
@@ -167,7 +170,7 @@ function deriveGitActionsState(args: DeriveGitActionsStateArgs): DerivedGitActio
     hasUncommittedChanges,
     postShipArchiveSuggested,
     isStatusLoading,
-    baseRefLabel,
+    baseRef,
   } = args;
   const actionsDisabled = !isGit || Boolean(status?.error) || isStatusLoading;
   const isPaseoOwnedWorktree = gitStatus?.isPaseoOwnedWorktree ?? false;
@@ -178,7 +181,8 @@ function deriveGitActionsState(args: DeriveGitActionsStateArgs): DerivedGitActio
     hasPullRequest: Boolean(prStatus?.url),
     hasRemote: gitStatus?.hasRemote ?? false,
     isPaseoOwnedWorktree,
-    isOnBaseBranch: gitStatus?.currentBranch === baseRefLabel,
+    isOnBaseBranch: isCurrentBranchBase(gitStatus?.currentBranch, baseRef),
+    canMergeLocally: canMergeIntoLocalBase(gitStatus?.currentBranch, baseRef),
     shouldPromoteArchive: computeShouldPromoteArchive({
       hasUncommittedChanges,
       postShipArchiveSuggested,
@@ -653,7 +657,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     hasUncommittedChanges,
     postShipArchiveSuggested,
     isStatusLoading,
-    baseRefLabel,
+    baseRef,
   });
   const {
     actionsDisabled,
@@ -665,6 +669,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     hasRemote,
     isPaseoOwnedWorktree,
     isOnBaseBranch,
+    canMergeLocally,
     shouldPromoteArchive,
   } = derived;
 
@@ -695,6 +700,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
       hasRemote,
       isPaseoOwnedWorktree,
       isOnBaseBranch,
+      canMergeLocally,
       hasUncommittedChanges,
       baseRefAvailable: Boolean(baseRef),
       baseRefLabel,
@@ -812,6 +818,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     behindBaseCount,
     isPaseoOwnedWorktree,
     isOnBaseBranch,
+    canMergeLocally,
     githubFeaturesEnabled,
     forge,
     githubAutoMergeActionsEnabled,
diff --git a/packages/app/src/git/use-diff-query.test.ts b/packages/app/src/git/use-diff-query.test.ts
index 94b18a7d16..809319bca4 100644
--- a/packages/app/src/git/use-diff-query.test.ts
+++ b/packages/app/src/git/use-diff-query.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
-import { deriveCheckoutDiffResult } from "./use-diff-query";
+import { deriveCheckoutDiffResult } from "./diff-snapshot";
 
 function createParsedDiffFile(path: string): ParsedDiffFile {
   return {
@@ -59,6 +59,7 @@ describe("deriveCheckoutDiffResult", () => {
 
     expect(result).toEqual({
       files: [],
+      entries: null,
       payloadError: error,
       diffTooLarge: true,
       isLoading: false,
@@ -68,3 +69,27 @@ describe("deriveCheckoutDiffResult", () => {
     });
   });
 });
+
+it("shows the announced tree while file bodies are still loading", () => {
+  const entries = [
+    {
+      path: "src/app.ts",
+      oldPath: null,
+      change: "modified",
+      content: "text",
+      additions: 3,
+      deletions: 1,
+    },
+  ] as const;
+  const result = deriveCheckoutDiffResult({ ...createPayload([]), entries: [...entries] });
+  expect(result.isLoading).toBe(true);
+  expect(result.entries).toEqual(entries);
+  expect(result.files).toEqual([]);
+});
+
+it("settles a comparison without a base and leaves Uncommitted available", async () => {
+  const { checkoutDiffComparisonError } = await import("./diff-snapshot");
+  expect(checkoutDiffComparisonError({ mode: "all" })).toMatchObject({ code: "INVALID_COMPARE" });
+  expect(checkoutDiffComparisonError({ mode: "base" })).toMatchObject({ code: "INVALID_COMPARE" });
+  expect(checkoutDiffComparisonError({ mode: "uncommitted" })).toBeNull();
+});
diff --git a/packages/app/src/git/use-diff-query.ts b/packages/app/src/git/use-diff-query.ts
index ebfcd4c354..6ba1202bb7 100644
--- a/packages/app/src/git/use-diff-query.ts
+++ b/packages/app/src/git/use-diff-query.ts
@@ -5,7 +5,13 @@ import { useRetainedPanelActive } from "@/components/retained-panel";
 import { useReplicaQuery } from "@/data/query";
 import { checkoutDiffPushRoute } from "@/data/push-router";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
+import {
+  checkoutDiffComparisonError,
+  deriveCheckoutDiffResult,
+  type CheckoutDiffSnapshot,
+} from "./diff-snapshot";
+export { deriveCheckoutDiffResult } from "./diff-snapshot";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
 import { checkoutDiffQueryKey } from "@/git/query-keys";
 
 interface UseCheckoutDiffQueryOptions {
@@ -18,7 +24,7 @@ interface UseCheckoutDiffQueryOptions {
   queryScope?: string;
 }
 
-type CheckoutDiffQueryPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
+type CheckoutDiffQueryPayload = CheckoutDiffSnapshot;
 
 // Re-export the canonical protocol type so all consumers share one definition.
 export type { ParsedDiffFile };
@@ -77,7 +83,11 @@ export function useCheckoutDiffQuery({
     return normalizedScope ? [...comparisonKey, "scope", normalizedScope] : comparisonKey;
   }, [serverId, cwd, compareMode, compareBaseRef, compareIgnoreWhitespace, queryScope]);
   const subscriptionId = useMemo(() => `checkoutDiff:${JSON.stringify(queryKey)}`, [queryKey]);
-  const routeEnabled = Boolean(queryEnabled && isConnected && cwd && !requiresUpdate);
+  const comparisonError =
+    queryEnabled && isConnected ? checkoutDiffComparisonError(normalizedCompare) : null;
+  const routeEnabled = Boolean(
+    queryEnabled && isConnected && cwd && !requiresUpdate && !comparisonError,
+  );
 
   const query = useReplicaQuery<CheckoutDiffQueryPayload>({
     queryKey,
@@ -97,46 +107,13 @@ export function useCheckoutDiffQuery({
     }),
   });
 
-  return deriveCheckoutDiffResult(
+  const boundaryError =
     requiresUpdate && isConnected
-      ? {
-          requestId: "unsupported",
-          cwd,
-          files: [],
-          error: { code: "UNKNOWN", message: "Update the host to view All changes" },
-        }
+      ? { code: "UNKNOWN" as const, message: "Update the host to view All changes" }
+      : comparisonError;
+  return deriveCheckoutDiffResult(
+    boundaryError
+      ? { requestId: "unavailable", cwd, files: [], error: boundaryError }
       : (query.data ?? null),
   );
 }
-
-export interface CheckoutDiffResult {
-  files: ParsedDiffFile[];
-  payloadError: CheckoutDiffQueryPayload["error"];
-  diffTooLarge: boolean;
-  isLoading: boolean;
-  isFetching: boolean;
-  isError: boolean;
-  error: null;
-}
-
-/**
- * The result derives from the payload alone. Until a payload arrives there is no
- * diff to describe, so the boundary reports loading rather than an empty diff —
- * whether the query is idle (an inactive retained panel), in flight, or the host
- * is disconnected. Reporting `files: []` as settled made callers render "+0 -0"
- * and "No changes" for a diff nobody has fetched yet.
- */
-export function deriveCheckoutDiffResult(
-  payload: CheckoutDiffQueryPayload | null,
-): CheckoutDiffResult {
-  const payloadError = payload?.error ?? null;
-  return {
-    files: payload?.files ?? [],
-    payloadError,
-    diffTooLarge: payload?.diffTooLarge === true,
-    isLoading: payload === null,
-    isFetching: false,
-    isError: Boolean(payloadError),
-    error: null,
-  };
-}
diff --git a/packages/app/src/git/use-working-diff.ts b/packages/app/src/git/use-working-diff.ts
index f835d44f53..9f32ce8819 100644
--- a/packages/app/src/git/use-working-diff.ts
+++ b/packages/app/src/git/use-working-diff.ts
@@ -9,6 +9,8 @@ import {
   useReviewAttachmentSnapshot,
   useReviewFeedback,
 } from "@/review";
+import { useSessionStore } from "@/stores/session-store";
+import { diffEntryHeaders } from "./diff-snapshot";
 import { useCheckoutDiffQuery } from "@/git/use-diff-query";
 import { useCheckoutStatusQuery } from "@/git/use-status-query";
 import { useWorkingDiffComparison } from "@/git/working-diff-comparison";
@@ -44,7 +46,11 @@ export function useWorkingDiff({
   const statusErrorMessage =
     status?.error?.message ??
     (isStatusError && statusError instanceof Error ? statusError.message : null);
-  const baseRef = gitStatus?.baseRef ?? undefined;
+  const modernDiff = useSessionStore(
+    (state) => state.sessions[serverId]?.serverInfo?.features?.diffSubscription === true,
+  );
+  // COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+  const baseRef = (modernDiff ? gitStatus?.comparisonBaseRef : gitStatus?.baseRef) ?? undefined;
   const currentBranchName =
     gitStatus?.currentBranch && gitStatus.currentBranch !== "HEAD" ? gitStatus.currentBranch : null;
 
@@ -59,6 +65,7 @@ export function useWorkingDiff({
 
   const {
     files,
+    entries,
     payloadError: diffPayloadError,
     diffTooLarge,
     isLoading: isDiffLoading,
@@ -71,6 +78,7 @@ export function useWorkingDiff({
     enabled: enabled && isGit,
     queryScope,
   });
+  const treeFiles = useMemo(() => (entries ? diffEntryHeaders(entries) : files), [entries, files]);
   const reviewDraftKey = useMemo(
     () =>
       buildReviewDraftKey({
@@ -112,6 +120,7 @@ export function useWorkingDiff({
     selectBase,
     selectAll,
     files,
+    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,
diff --git a/packages/app/src/git/workspace-base-branch-picker.tsx b/packages/app/src/git/workspace-base-branch-picker.tsx
new file mode 100644
index 0000000000..abc4fbee8f
--- /dev/null
+++ b/packages/app/src/git/workspace-base-branch-picker.tsx
@@ -0,0 +1,174 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { Text, View } from "react-native";
+import { GitBranch } from "lucide-react-native";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useFetchQuery } from "@/data/query";
+import { useTranslation } from "react-i18next";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import type { Theme } from "@/styles/theme";
+import { Combobox, ComboboxItem, type ComboboxProps } from "@/components/ui/combobox";
+import { ToolbarLabelSelectTrigger } from "@/components/ui/toolbar-label-trigger";
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
+import { Button } from "@/components/ui/button";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { useSessionStore } from "@/stores/session-store";
+import { useDebouncedValue } from "@/hooks/use-debounced-value";
+import { invalidateCheckoutGitQueriesForClient } from "./query-keys";
+
+interface Props {
+  serverId: string;
+  workspaceId?: string | null;
+  cwd: string;
+  baseRef: string;
+}
+
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const ThemedGitBranch = withUnistyles(GitBranch);
+const mutedColor = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+function refLabel(ref: string): string {
+  return ref.replace(/^refs\/(heads|remotes)\//, "");
+}
+
+export function WorkspaceBaseBranchPicker({ serverId, workspaceId, cwd, baseRef }: Props) {
+  const { t } = useTranslation();
+  const client = useHostRuntimeClient(serverId);
+  const connected = useHostRuntimeIsConnected(serverId);
+  // COMPAT(workspaceBaseBranch): added after v0.11.2, remove gate after 2027-10-14.
+  const supported = useSessionStore(
+    (state) => state.sessions[serverId]?.serverInfo?.features?.workspaceBaseBranch === true,
+  );
+  const queryClient = useQueryClient();
+  const anchorRef = useRef<View>(null);
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const query = useDebouncedValue(search, 200);
+  const branches = useFetchQuery({
+    queryKey: ["workspaceBaseBranches", serverId, cwd, query],
+    queryFn: async () => {
+      if (!client) throw new Error(t("common.errors.daemonClientUnavailable"));
+      const result = await client.getBranchSuggestions({
+        cwd,
+        refMode: "exact",
+        query,
+        limit: 200,
+      });
+      if (result.error) throw new Error(result.error);
+      return result.branches;
+    },
+    enabled: open && supported && connected && Boolean(client),
+    retry: false,
+    dataShape: "value",
+    staleTimeMs: 0,
+  });
+  const mutation = useMutation({
+    mutationFn: async (ref: string) => {
+      if (!client || !workspaceId) throw new Error(t("common.errors.daemonClientUnavailable"));
+      return client.setWorkspaceBaseBranch({ workspaceId, baseRef: ref });
+    },
+    onSuccess: async () => {
+      setOpen(false);
+      await invalidateCheckoutGitQueriesForClient(queryClient, { serverId, cwd });
+    },
+  });
+  const options = useMemo(
+    () => (branches.data ?? []).map((ref) => ({ id: ref, label: refLabel(ref) })),
+    [branches.data],
+  );
+  const error = mutation.error ?? branches.error;
+  const title = t("workspace.git.diff.baseBranch.title");
+  const label = refLabel(baseRef).replace(/^origin\//, "");
+
+  const { reset, mutate, isPending } = mutation;
+  const { refetch, isError } = branches;
+  const handleOpen = useCallback(() => {
+    reset();
+    setSearch("");
+    setOpen(true);
+  }, [reset]);
+  const handleSelect = useCallback(
+    (ref: string) => {
+      if (!isPending) mutate(ref);
+    },
+    [isPending, mutate],
+  );
+  const handleRetry = useCallback(() => {
+    void refetch();
+  }, [refetch]);
+  const branchIcon = useMemo(() => <ThemedGitBranch size={14} uniProps={mutedColor} />, []);
+  const renderOption = useCallback<NonNullable<ComboboxProps["renderOption"]>>(
+    ({ option, selected, active, onPress }) => (
+      <ComboboxItem
+        label={option.label}
+        leadingSlot={branchIcon}
+        selected={selected}
+        active={active}
+        onPress={onPress}
+        disabled={isPending}
+      />
+    ),
+    [isPending, branchIcon],
+  );
+  const footer = useMemo(
+    () => (
+      <View style={styles.footer}>
+        {isPending ? <ThemedLoadingSpinner size="small" uniProps={mutedColor} /> : null}
+        {error ? (
+          <Text accessibilityRole="alert" testID="workspace-base-branch-error" style={styles.error}>
+            {error.message}
+          </Text>
+        ) : null}
+        {isError ? (
+          <Button variant="outline" onPress={handleRetry}>
+            {t("common.actions.retry")}
+          </Button>
+        ) : null}
+      </View>
+    ),
+    [t, isPending, error, isError, handleRetry],
+  );
+
+  if (!supported || !workspaceId) return <Text style={styles.text}>{label}</Text>;
+
+  return (
+    <View ref={anchorRef} collapsable={false} style={styles.anchor}>
+      <ToolbarLabelSelectTrigger
+        testID="workspace-base-branch-trigger"
+        label={label}
+        open={open}
+        disabled={!connected || mutation.isPending}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+        onPress={handleOpen}
+      />
+      <Combobox
+        options={options}
+        value={baseRef}
+        onSelect={handleSelect}
+        keepOpenOnSelect
+        searchable
+        onSearchQueryChange={setSearch}
+        searchPlaceholder={t("branchSwitcher.searchPlaceholder")}
+        emptyText={branches.isFetching ? t("common.states.loading") : t("branchSwitcher.empty")}
+        title={title}
+        open={open}
+        onOpenChange={setOpen}
+        anchorRef={anchorRef}
+        desktopPlacement="bottom-start"
+        desktopPreventInitialFlash
+        desktopMinWidth={300}
+        renderOption={renderOption}
+        footer={error || isPending ? footer : undefined}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  // The branch name truncates first so a short base like "main" stays readable; the cap lets
+  // a long base still truncate instead of overflowing the header.
+  anchor: { flexShrink: 0, minWidth: 0, maxWidth: "40%" },
+  footer: { padding: theme.spacing[3], gap: theme.spacing[2] },
+  text: { color: theme.colors.foregroundMuted, fontSize: theme.fontSize.sm },
+  error: { color: theme.colors.destructive, fontSize: theme.fontSize.sm },
+}));
diff --git a/packages/app/src/hooks/feature-preferences.test.ts b/packages/app/src/hooks/feature-preferences.test.ts
deleted file mode 100644
index 7cfca13a68..0000000000
--- a/packages/app/src/hooks/feature-preferences.test.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { resolveFeatureValues } from "./feature-preferences";
-
-describe("feature-preferences", () => {
-  const features = [
-    {
-      type: "toggle" as const,
-      id: "fast_mode",
-      label: "Fast",
-      value: false,
-    },
-    {
-      type: "toggle" as const,
-      id: "plan_mode",
-      label: "Plan",
-      value: false,
-    },
-  ];
-
-  it("restores persisted values for available features", () => {
-    expect(
-      resolveFeatureValues({
-        features,
-        persistedFeatureValues: {
-          fast_mode: true,
-          unknown_feature: true,
-        },
-        localFeatureValues: {},
-      }),
-    ).toEqual({
-      fast_mode: true,
-    });
-  });
-
-  it("prefers local values over persisted values", () => {
-    expect(
-      resolveFeatureValues({
-        features,
-        persistedFeatureValues: {
-          fast_mode: true,
-          plan_mode: false,
-        },
-        localFeatureValues: {
-          fast_mode: false,
-        },
-      }),
-    ).toEqual({
-      fast_mode: false,
-      plan_mode: false,
-    });
-  });
-});
diff --git a/packages/app/src/hooks/feature-preferences.ts b/packages/app/src/hooks/feature-preferences.ts
deleted file mode 100644
index 4fbd956581..0000000000
--- a/packages/app/src/hooks/feature-preferences.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import type { AgentFeature } from "@getpaseo/protocol/agent-types";
-
-export function pruneFeatureValues(
-  featureValues: Record<string, unknown>,
-  features: AgentFeature[],
-): Record<string, unknown> {
-  const allowedFeatureIds = new Set(features.map((feature) => feature.id));
-  let changed = false;
-  const next: Record<string, unknown> = {};
-
-  for (const [featureId, value] of Object.entries(featureValues)) {
-    if (!allowedFeatureIds.has(featureId)) {
-      changed = true;
-      continue;
-    }
-    next[featureId] = value;
-  }
-
-  return changed ? next : featureValues;
-}
-
-export function applyFeatureValues(
-  features: AgentFeature[],
-  featureValues: Record<string, unknown>,
-): AgentFeature[] {
-  if (Object.keys(featureValues).length === 0) {
-    return features;
-  }
-
-  return features.map((feature) => {
-    if (!Object.prototype.hasOwnProperty.call(featureValues, feature.id)) {
-      return feature;
-    }
-
-    return {
-      ...feature,
-      value: featureValues[feature.id],
-    } as AgentFeature;
-  });
-}
-
-export function resolveFeatureValues(args: {
-  features: AgentFeature[];
-  persistedFeatureValues: Record<string, unknown>;
-  localFeatureValues: Record<string, unknown>;
-}): Record<string, unknown> {
-  const next: Record<string, unknown> = {};
-
-  for (const feature of args.features) {
-    if (Object.prototype.hasOwnProperty.call(args.localFeatureValues, feature.id)) {
-      next[feature.id] = args.localFeatureValues[feature.id];
-      continue;
-    }
-    if (Object.prototype.hasOwnProperty.call(args.persistedFeatureValues, feature.id)) {
-      next[feature.id] = args.persistedFeatureValues[feature.id];
-    }
-  }
-
-  return next;
-}
diff --git a/packages/app/src/hooks/pointer-capabilities.test.ts b/packages/app/src/hooks/pointer-capabilities.test.ts
new file mode 100644
index 0000000000..167db7c553
--- /dev/null
+++ b/packages/app/src/hooks/pointer-capabilities.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { createPointerCapabilitiesSource } from "./pointer-capabilities";
+
+class FakeMediaQueryList {
+  private readonly listeners = new Set<() => void>();
+
+  constructor(
+    readonly media: string,
+    public matches: boolean,
+  ) {}
+
+  addEventListener(_type: "change", listener: () => void) {
+    this.listeners.add(listener);
+  }
+
+  removeEventListener(_type: "change", listener: () => void) {
+    this.listeners.delete(listener);
+  }
+
+  setMatches(matches: boolean) {
+    this.matches = matches;
+    for (const listener of this.listeners) listener();
+  }
+}
+
+function createFakeDisplay(initial: { finePointer: boolean; touchScreen: boolean }) {
+  const queries = {
+    finePointer: new FakeMediaQueryList("(hover: hover) and (pointer: fine)", initial.finePointer),
+    touchScreen: new FakeMediaQueryList("(any-pointer: coarse)", initial.touchScreen),
+  };
+  const matchMedia = (query: string) => {
+    const match = Object.values(queries).find((list) => list.media === query);
+    if (!match) throw new Error(`Unexpected media query ${query}`);
+    return match as unknown as MediaQueryList;
+  };
+  return { queries, matchMedia };
+}
+
+describe("pointer capabilities", () => {
+  it("reports a hybrid touch laptop as both a fine pointer and a touch screen", () => {
+    const display = createFakeDisplay({ finePointer: true, touchScreen: true });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+
+    expect(source.getSnapshot()).toEqual({ finePointer: true, touchScreen: true });
+  });
+
+  it("notifies and updates the touch answer when a touch screen appears or goes away", () => {
+    const display = createFakeDisplay({ finePointer: true, touchScreen: false });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+    const seen: boolean[] = [];
+    const unsubscribe = source.subscribe(() => seen.push(source.getSnapshot().touchScreen));
+
+    display.queries.touchScreen.setMatches(true);
+    display.queries.touchScreen.setMatches(false);
+    unsubscribe();
+    display.queries.touchScreen.setMatches(true);
+
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("keeps one snapshot until an answer changes", () => {
+    const display = createFakeDisplay({ finePointer: false, touchScreen: true });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+    const first = source.getSnapshot();
+
+    expect(source.getSnapshot()).toBe(first);
+    display.queries.finePointer.setMatches(true);
+    expect(source.getSnapshot()).toEqual({ finePointer: true, touchScreen: true });
+  });
+
+  it("reports neither capability without media queries", () => {
+    expect(createPointerCapabilitiesSource(null).getSnapshot()).toEqual({
+      finePointer: false,
+      touchScreen: false,
+    });
+  });
+});
diff --git a/packages/app/src/hooks/pointer-capabilities.ts b/packages/app/src/hooks/pointer-capabilities.ts
new file mode 100644
index 0000000000..360ff88c24
--- /dev/null
+++ b/packages/app/src/hooks/pointer-capabilities.ts
@@ -0,0 +1,88 @@
+import { useSyncExternalStore } from "react";
+import { isWeb } from "@/constants/platform";
+
+// A touch tablet running the desktop layout is still `isWeb === false || true`
+// depending on the build, so neither platform gate answers "can this user
+// hover and point precisely" or "can this user touch the screen". Only the
+// media queries do, and the same queries notify when the answer changes
+// (detachable keyboards, tablet mode, devtools touch emulation).
+const FINE_POINTER_QUERY = "(hover: hover) and (pointer: fine)";
+const TOUCH_SCREEN_QUERY = "(any-pointer: coarse)";
+
+export interface PointerCapabilities {
+  /** A mouse-like pointer drives the UI. */
+  finePointer: boolean;
+  /** A touch screen is available, possibly next to a mouse on hybrid devices. */
+  touchScreen: boolean;
+}
+
+type MatchMedia = (query: string) => MediaQueryList;
+
+export interface PointerCapabilitiesSource {
+  getSnapshot: () => PointerCapabilities;
+  subscribe: (onChange: () => void) => () => void;
+}
+
+export function createPointerCapabilitiesSource(
+  matchMedia: MatchMedia | null,
+): PointerCapabilitiesSource {
+  const finePointerQuery = matchMedia?.(FINE_POINTER_QUERY) ?? null;
+  const touchScreenQuery = matchMedia?.(TOUCH_SCREEN_QUERY) ?? null;
+  let snapshot: PointerCapabilities = { finePointer: false, touchScreen: false };
+
+  return {
+    getSnapshot() {
+      const finePointer = finePointerQuery?.matches ?? false;
+      const touchScreen = touchScreenQuery?.matches ?? false;
+      if (snapshot.finePointer !== finePointer || snapshot.touchScreen !== touchScreen) {
+        snapshot = { finePointer, touchScreen };
+      }
+      return snapshot;
+    },
+    subscribe(onChange) {
+      finePointerQuery?.addEventListener("change", onChange);
+      touchScreenQuery?.addEventListener("change", onChange);
+      return () => {
+        finePointerQuery?.removeEventListener("change", onChange);
+        touchScreenQuery?.removeEventListener("change", onChange);
+      };
+    },
+  };
+}
+
+function browserMatchMedia(): MatchMedia | null {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
+  return (query) => window.matchMedia(query);
+}
+
+// Native builds run on iOS and Android touch screens. A paired mouse or pen is
+// filtered per gesture event by its pointer type, not by this capability.
+const NATIVE_POINTER_CAPABILITIES: PointerCapabilities = { finePointer: false, touchScreen: true };
+const nativeSource: PointerCapabilitiesSource = {
+  getSnapshot: () => NATIVE_POINTER_CAPABILITIES,
+  subscribe: () => () => {},
+};
+
+const source = isWeb ? createPointerCapabilitiesSource(browserMatchMedia()) : nativeSource;
+const SERVER_SNAPSHOT: PointerCapabilities = { finePointer: false, touchScreen: false };
+
+function getServerSnapshot(): PointerCapabilities {
+  return SERVER_SNAPSHOT;
+}
+
+export function usePointerCapabilities(): PointerCapabilities {
+  return useSyncExternalStore(source.subscribe, source.getSnapshot, getServerSnapshot);
+}
+
+/** True when a mouse-like pointer drives the UI, read at call time. */
+export function hasFinePointer(): boolean {
+  return source.getSnapshot().finePointer;
+}
+
+/** Touch sizing remains enabled on hybrid browsers that report touch points. */
+export function hasTouchScreen(): boolean {
+  return (
+    source.getSnapshot().touchScreen ||
+    (isWeb && typeof window !== "undefined" && window.navigator.maxTouchPoints > 0)
+  );
+}
diff --git a/packages/app/src/hooks/use-acp-provider-catalog.test.ts b/packages/app/src/hooks/use-acp-provider-catalog.test.ts
index 41806de307..f160630508 100644
--- a/packages/app/src/hooks/use-acp-provider-catalog.test.ts
+++ b/packages/app/src/hooks/use-acp-provider-catalog.test.ts
@@ -52,6 +52,7 @@ describe("ACP provider catalog", () => {
     expect(findProvider("devin").command).toEqual(["devin", "acp"]);
     expect(findProvider("goose").command).toEqual(["goose", "acp"]);
     expect(findProvider("hoplite").command).toEqual(["hoplite", "acp"]);
+    expect(findProvider("fx").command).toEqual(["fx", "acp"]);
     expect(findProvider("junie").command).toEqual(["junie", "--acp", "true"]);
     expect(findProvider("kiro").command).toEqual(["kiro-cli", "acp"]);
     expect(findProvider("poolside").command).toEqual(["pool", "acp"]);
@@ -75,7 +76,7 @@ describe("ACP provider catalog", () => {
       command: ["hoplite", "acp"],
       installLink: "https://hoplite.sh/docs/cli#install",
     });
-    expect(buildAcpProviderConfigPatch(findProvider("hoplite"), true)).toEqual({
+    expect(buildAcpProviderConfigPatch(findProvider("hoplite"), () => true)).toEqual({
       providers: {
         hoplite: { enabled: true },
       },
@@ -86,14 +87,31 @@ describe("ACP provider catalog", () => {
     expect(findProvider("hoplite").iconSvg).toContain('fill="currentColor"');
   });
 
-  it.each([undefined, false])(
-    "rejects unsupported bundled Hoplite before producing a patch (%s)",
-    (supported) => {
-      expect(() => buildAcpProviderConfigPatch(findProvider("hoplite"), supported)).toThrow(
-        "Update the host to add Hoplite.",
-      );
-    },
-  );
+  it("offers fx as a bundled provider gated on its own host feature", () => {
+    expect(findProvider("fx")).toMatchObject({
+      title: "fx",
+      installLink: "https://fx.sh/docs/getting-started/installation",
+    });
+    expect(findProvider("fx").iconSvg).toContain('fill="currentColor"');
+    const supported: string[] = [];
+    expect(
+      buildAcpProviderConfigPatch(findProvider("fx"), (feature) => {
+        supported.push(feature);
+        return true;
+      }),
+    ).toEqual({ providers: { fx: { enabled: true } } });
+    expect(supported).toEqual(["fxProvider"]);
+  });
+
+  it.each([
+    ["hoplite", "Hoplite"],
+    ["fx", "fx"],
+  ])("rejects unsupported bundled %s before producing a patch", (id, title) => {
+    const unsupported = () => false;
+    expect(() => buildAcpProviderConfigPatch(findProvider(id), unsupported)).toThrow(
+      `Update the host to add ${title}.`,
+    );
+  });
 
   it("maps a catalog entry to the daemon provider config patch", () => {
     expect(buildAcpProviderConfigPatch(findProvider("amp-acp"))).toEqual({
diff --git a/packages/app/src/hooks/use-acp-provider-catalog.ts b/packages/app/src/hooks/use-acp-provider-catalog.ts
index f20c31caf2..9eae51f33e 100644
--- a/packages/app/src/hooks/use-acp-provider-catalog.ts
+++ b/packages/app/src/hooks/use-acp-provider-catalog.ts
@@ -1,6 +1,7 @@
 import { useCallback, useState } from "react";
 import type { MutableDaemonConfigPatch } from "@getpaseo/protocol/messages";
 import { ACP_PROVIDER_CATALOG, type AcpProviderCatalogEntry } from "@/data/acp-provider-catalog";
+import type { HostFeatureName } from "@/runtime/host-features";
 
 export type AcpProviderCatalogItem = AcpProviderCatalogEntry;
 
@@ -10,11 +11,14 @@ export function getAcpProviderCatalog(): AcpProviderCatalogItem[] {
 
 export function buildAcpProviderConfigPatch(
   entry: AcpProviderCatalogItem,
-  supportsHopliteProvider = false,
+  hostSupports: (feature: HostFeatureName) => boolean = () => false,
 ): MutableDaemonConfigPatch {
   if (entry.bundledProvider) {
     // COMPAT(hopliteProvider): added after v0.11.2, remove after 2027-04-15 once host floor includes the bundled adapter.
-    if (!supportsHopliteProvider) throw new Error("Update the host to add Hoplite.");
+    // COMPAT(fxProvider): added after v0.15.3, remove after 2027-05-09 once host floor includes the bundled adapter.
+    if (!hostSupports(entry.bundledProvider.hostFeature)) {
+      throw new Error(`Update the host to add ${entry.title}.`);
+    }
     return { providers: { [entry.id]: { enabled: true } } };
   }
   return {
diff --git a/packages/app/src/hooks/use-agent-attention-clear.ts b/packages/app/src/hooks/use-agent-attention-clear.ts
index e1501e0dc9..16a4d77ddb 100644
--- a/packages/app/src/hooks/use-agent-attention-clear.ts
+++ b/packages/app/src/hooks/use-agent-attention-clear.ts
@@ -1,12 +1,10 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { AppState } from "react-native";
-import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
-import {
-  shouldClearAgentAttention,
-  type AgentAttentionClearTrigger,
-} from "@/utils/agent-attention";
+import { DaemonConnectionError, type DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { createAgentAttentionController } from "@/utils/agent-attention";
 import { getIsAppActivelyVisible } from "@/utils/app-visibility";
 import { isWeb } from "@/constants/platform";
+import { useStableEvent } from "@/hooks/use-stable-event";
 
 type AttentionReason = "finished" | "error" | "permission" | null | undefined;
 
@@ -14,54 +12,48 @@ interface UseAgentAttentionClearParams {
   agentId: string | null | undefined;
   client: DaemonClient | null;
   isConnected: boolean;
-  requiresAttention: boolean | null | undefined;
+  isAgentDataReady: boolean;
+  requiresAttention: boolean;
   attentionReason: AttentionReason;
   isScreenFocused: boolean;
+  focusRequest: object | null;
+  onError: (error: unknown) => void;
 }
 
 interface AgentAttentionClearController {
   clearOnInputFocus: () => void;
   clearOnPromptSend: () => void;
-  clearOnAgentBlur: () => void;
 }
 
 export function useAgentAttentionClear({
   agentId,
   client,
   isConnected,
+  isAgentDataReady,
   requiresAttention,
   attentionReason,
   isScreenFocused,
+  focusRequest,
+  onError,
 }: UseAgentAttentionClearParams): AgentAttentionClearController {
   const [isAppVisible, setIsAppVisible] = useState<boolean>(() => getIsAppActivelyVisible());
-  const deferredFocusEntryClearRef = useRef(false);
-  const prevRequiresAttentionRef = useRef(Boolean(requiresAttention));
-  const prevActivelyViewedRef = useRef(isScreenFocused && getIsAppActivelyVisible());
-  const prevScreenFocusedRef = useRef(false);
-  const prevAppVisibleRef = useRef(getIsAppActivelyVisible());
-
-  const clearAttention = useCallback(
-    (trigger: AgentAttentionClearTrigger) => {
-      const resolvedAgentId = agentId?.trim();
-      if (!client || !resolvedAgentId) {
-        return;
-      }
-      if (
-        !shouldClearAgentAttention({
-          agentId: resolvedAgentId,
-          isConnected,
-          requiresAttention,
-          attentionReason,
-          trigger,
-          hasDeferredFocusEntryClear: deferredFocusEntryClearRef.current,
-        })
-      ) {
-        return;
-      }
-      deferredFocusEntryClearRef.current = false;
-      client.clearAgentAttention(resolvedAgentId).catch(() => {});
-    },
-    [agentId, attentionReason, client, isConnected, requiresAttention],
+  const clearAttention = useStableEvent(async (id: string) => {
+    if (client) await client.clearAgentAttention(id);
+  });
+  const reportError = useStableEvent((error: unknown) => {
+    // The timeline's reconnect status already explains a lost connection.
+    if (error instanceof DaemonConnectionError && error.code === "DAEMON_CONNECTION_LOST") return;
+    onError(error);
+  });
+  const controller = useMemo(
+    () =>
+      createAgentAttentionController({
+        clear: async () => {
+          if (agentId) await clearAttention(agentId);
+        },
+        onError: reportError,
+      }),
+    [agentId, clearAttention, reportError],
   );
 
   useEffect(() => {
@@ -90,46 +82,28 @@ export function useAgentAttentionClear({
   }, []);
 
   useEffect(() => {
-    if (!requiresAttention) {
-      deferredFocusEntryClearRef.current = false;
-    }
-  }, [requiresAttention]);
-
-  useEffect(() => {
-    const isActivelyViewed = isScreenFocused && isAppVisible;
-    if (
-      !prevRequiresAttentionRef.current &&
-      Boolean(requiresAttention) &&
-      prevActivelyViewedRef.current &&
-      isActivelyViewed
-    ) {
-      deferredFocusEntryClearRef.current = true;
-    }
-    prevRequiresAttentionRef.current = Boolean(requiresAttention);
-    prevActivelyViewedRef.current = isActivelyViewed;
-  }, [isAppVisible, isScreenFocused, requiresAttention]);
-
-  useEffect(() => {
-    const enteredScreenFocus = !prevScreenFocusedRef.current && isScreenFocused && isAppVisible;
-    const resumedIntoFocusedAgent = !prevAppVisibleRef.current && isAppVisible && isScreenFocused;
-
-    if (enteredScreenFocus || resumedIntoFocusedAgent) {
-      clearAttention("focus-entry");
-    }
-
-    prevScreenFocusedRef.current = isScreenFocused;
-    prevAppVisibleRef.current = isAppVisible;
-  }, [clearAttention, isAppVisible, isScreenFocused]);
+    controller.update({
+      focused: isScreenFocused && isAppVisible,
+      ready: Boolean(client && agentId && isConnected && isAgentDataReady),
+      requiresAttention,
+      attentionReason,
+      focusRequest,
+    });
+  }, [
+    controller,
+    client,
+    agentId,
+    isConnected,
+    isAgentDataReady,
+    isScreenFocused,
+    isAppVisible,
+    requiresAttention,
+    attentionReason,
+    focusRequest,
+  ]);
 
   return {
-    clearOnInputFocus: useCallback(() => {
-      clearAttention("input-focus");
-    }, [clearAttention]),
-    clearOnPromptSend: useCallback(() => {
-      clearAttention("prompt-send");
-    }, [clearAttention]),
-    clearOnAgentBlur: useCallback(() => {
-      clearAttention("agent-blur");
-    }, [clearAttention]),
+    clearOnInputFocus: controller.focus,
+    clearOnPromptSend: controller.focus,
   };
 }
diff --git a/packages/app/src/hooks/use-agent-autocomplete.ts b/packages/app/src/hooks/use-agent-autocomplete.ts
index fe6f98c3f1..f08a69c32e 100644
--- a/packages/app/src/hooks/use-agent-autocomplete.ts
+++ b/packages/app/src/hooks/use-agent-autocomplete.ts
@@ -2,17 +2,21 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
-import type { AutocompleteOption } from "@/components/ui/autocomplete";
+import type { AutocompleteOption, AutocompleteStatus } from "@/components/ui/autocomplete";
+import { findHighlightRanges } from "@/components/ui/highlighted-text-segments";
 import {
-  useAgentCommandsQuery,
+  useAutocompleteCommands,
   type AgentSlashCommand,
   type DraftCommandConfig,
   type DraftCommandTarget,
-} from "./use-agent-commands-query";
+} from "@/agent-commands";
 import { orderAutocompleteOptions } from "@/components/ui/autocomplete-utils";
 import { useAutocomplete } from "./use-autocomplete";
 import { useSessionStore } from "@/stores/session-store";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { useProvidersSnapshot } from "@/hooks/use-providers-snapshot";
+import { pluginDisplayName, usePluginList } from "@/plugins/plugin-list";
+import { resolveProviderLabel } from "@/utils/provider-definitions";
 import { CLIENT_SLASH_COMMANDS, type ClientSlashCommand } from "@/client-slash-commands";
 import type { PluginClientSlashCommand } from "@/plugins/client-slash-commands";
 import { mergeSlashCommandSources } from "@/plugins/client-slash-commands/model";
@@ -70,10 +74,8 @@ interface AgentAutocompleteResult {
   isVisible: boolean;
   options: AutocompleteOption[];
   selectedIndex: number;
-  isLoading: boolean;
-  errorMessage?: string;
-  loadingText: string;
-  emptyText: string;
+  /** Shown in place of options; set exactly when `options` is empty. */
+  status: AutocompleteStatus | null;
   onSelectOption: (option: AutocompleteOption, input?: AgentAutocompleteInputSnapshot) => void;
   onKeyPress: (event: AgentAutocompleteKeyPressEvent) => boolean;
 }
@@ -128,14 +130,14 @@ function resolveDraftQueryConfig(draft?: DraftCommandTarget): DraftCommandConfig
   const modeId = draftConfig.modeId?.trim() ?? "";
   const model = draftConfig.model?.trim() ?? "";
   const thinkingOptionId = draftConfig.thinkingOptionId?.trim() ?? "";
-  const featureValues = draftConfig.featureValues;
+  const providerOptions = draftConfig.providerOptions;
   return {
     provider: draftConfig.provider,
     cwd,
     ...(modeId ? { modeId } : {}),
     ...(model ? { model } : {}),
     ...(thinkingOptionId ? { thinkingOptionId } : {}),
-    ...(featureValues && Object.keys(featureValues).length > 0 ? { featureValues } : {}),
+    ...(providerOptions && Object.keys(providerOptions).length > 0 ? { providerOptions } : {}),
   };
 }
 
@@ -162,39 +164,69 @@ function mapDirectorySuggestionsToEntries(payload: {
   }));
 }
 
-function mapCommandToOption(entry: AvailableCommand, t: TFunction): AgentAutocompleteOption {
+const CLIENT_COMMAND_ICONS = {
+  "archive-agent": "archive",
+  "replace-agent-with-draft": "new-draft",
+} as const satisfies Record<ClientSlashCommand["kind"], AutocompleteOption["icon"]>;
+
+interface CommandOptionContext {
+  query: string;
+  pluginNames: ReadonlyMap<string, string>;
+  t: TFunction;
+}
+
+function mapCommandToOption(
+  entry: AvailableCommand,
+  context: CommandOptionContext,
+): AgentAutocompleteOption {
   const command = entry.command;
   const base = {
     id: command.name,
     label: `/${command.name}`,
-    detail: command.argumentHint || undefined,
-    description:
-      entry.source === "client" ? t(entry.command.descriptionKey) : entry.command.description,
-    kind: "command" as const,
+    // The label carries a leading slash the query does not.
+    labelMatches: findHighlightRanges(context.query, command.name).map((range) => ({
+      start: range.start + 1,
+      length: range.length,
+    })),
+    argumentHint: command.argumentHint || undefined,
   };
   if (entry.source === "client") {
     return {
       ...base,
       type: "client_command",
       command: entry.command,
+      icon: CLIENT_COMMAND_ICONS[entry.command.kind],
+      description: context.t(entry.command.descriptionKey),
+      tag: "Paseo",
     };
   }
   if (entry.source === "plugin") {
-    return { ...base, type: "plugin_command", command: entry.command };
+    return {
+      ...base,
+      type: "plugin_command",
+      command: entry.command,
+      icon: "plugin",
+      description: entry.command.description,
+      tag: context.pluginNames.get(entry.command.pluginId) ?? entry.command.pluginId,
+    };
   }
+  const isSkill = entry.command.kind === "skill";
   return {
     ...base,
     type: "provider_command",
+    icon: isSkill ? "skill" : "command",
+    description: entry.command.description,
+    tag: isSkill ? context.t("agentAutocomplete.skillTag") : undefined,
   };
 }
 
 type AutocompleteMode = "command" | "file" | null;
 
 interface BuildAutocompleteOptionsInput {
-  isVisible: boolean;
   mode: AutocompleteMode;
   commands: AgentSlashCommand[];
   pluginCommands: readonly PluginClientSlashCommand[];
+  pluginNames: ReadonlyMap<string, string>;
   isDraftContext: boolean;
   commandFilterQuery: string;
   activeSlashCommand: SlashCommandRange | null;
@@ -203,11 +235,7 @@ interface BuildAutocompleteOptionsInput {
   t: TFunction;
 }
 
-function buildCommandAutocompleteOptions(input: BuildAutocompleteOptionsInput) {
-  if (!input.isVisible) {
-    return [];
-  }
-
+function buildAutocompleteOptions(input: BuildAutocompleteOptionsInput): AgentAutocompleteOption[] {
   if (input.mode === "command") {
     const providerCommands = input.commands.map((command) => ({
       source: "provider" as const,
@@ -236,8 +264,12 @@ function buildCommandAutocompleteOptions(input: BuildAutocompleteOptionsInput) {
       availableCommands,
       input.commandFilterQuery,
     );
-    const orderedMatches = orderAutocompleteOptions(matches);
-    return orderedMatches.map((entry) => mapCommandToOption(entry, input.t));
+    const context = {
+      query: input.commandFilterQuery,
+      pluginNames: input.pluginNames,
+      t: input.t,
+    };
+    return orderAutocompleteOptions(matches).map((entry) => mapCommandToOption(entry, context));
   }
 
   const activeFileMention = input.activeFileMention;
@@ -247,7 +279,7 @@ function buildCommandAutocompleteOptions(input: BuildAutocompleteOptionsInput) {
       type: "workspace_entry" as const,
       id: `${entry.kind}:${entry.path}`,
       label: entry.path,
-      kind: entry.kind,
+      icon: entry.kind,
       entryPath: entry.path,
       mention: activeFileMention,
     }));
@@ -295,42 +327,140 @@ function resolveCanLoadCommands(args: {
   return Boolean(args.agentId) || args.isDraftContext;
 }
 
-function resolveAutocompleteIsLoading(args: {
-  mode: AutocompleteMode;
-  isCommandsLoading: boolean;
-  fileSuggestionsIsPending: boolean;
-  fileSuggestionsIsLoading: boolean;
-  optionsLength: number;
-}): boolean {
-  if (args.mode === "command") {
-    return args.isCommandsLoading && args.optionsLength === 0;
-  }
-  if (args.mode === "file") {
-    return (
-      args.fileSuggestionsIsPending || (args.fileSuggestionsIsLoading && args.optionsLength === 0)
-    );
-  }
-  return false;
+type CommandsState = "ready" | "loading" | "error";
+
+function resolveCommandsState(input: {
+  canListCommands: boolean;
+  isLoading: boolean;
+  isError: boolean;
+}): CommandsState {
+  if (!input.canListCommands) return "ready";
+  if (input.isError) return "error";
+  if (input.isLoading) return "loading";
+  return "ready";
 }
 
-function resolveAutocompleteErrorMessage(args: {
-  mode: AutocompleteMode;
-  isCommandError: boolean;
-  commandError: Error | null;
-  fileSuggestionsError: unknown;
+interface AutocompleteMenu {
+  options: AgentAutocompleteOption[];
+  status: AutocompleteStatus | null;
+}
+
+/**
+ * One state for the open menu, so options and a loading or error row cannot both claim it:
+ * while a status row shows there are no options for Enter or Tab to pick.
+ */
+function resolveCommandMenu(input: {
+  commandsState: CommandsState;
+  options: () => AgentAutocompleteOption[];
+  providerLabel: string | null;
+  error: Error | null;
+  onRetry: () => void;
+  emptyText: string;
   t: TFunction;
-}): string | undefined {
-  if (args.mode === "command") {
-    return args.isCommandError
-      ? (args.commandError?.message ?? args.t("agentAutocomplete.failedToLoad"))
-      : undefined;
+}): AutocompleteMenu {
+  const { t } = input;
+  if (input.commandsState === "loading") {
+    const message = input.providerLabel
+      ? t("agentAutocomplete.loadingProviderCommands", { provider: input.providerLabel })
+      : t("agentAutocomplete.loadingCommands");
+    return { options: [], status: { kind: "loading", message } };
   }
-  if (args.mode === "file") {
-    return args.fileSuggestionsError instanceof Error
-      ? args.fileSuggestionsError.message
-      : undefined;
+  if (input.commandsState === "error") {
+    const title = input.providerLabel
+      ? t("agentAutocomplete.providerCommandsFailed", { provider: input.providerLabel })
+      : t("agentAutocomplete.commandsFailed");
+    return {
+      options: [],
+      status: { kind: "error", title, reason: input.error?.message, onRetry: input.onRetry },
+    };
   }
-  return undefined;
+  return withEmptyStatus(input.options(), input.emptyText);
+}
+
+function resolveFileMenu(input: {
+  options: () => AgentAutocompleteOption[];
+  isPending: boolean;
+  isLoading: boolean;
+  error: unknown;
+  t: TFunction;
+}): AutocompleteMenu {
+  const options = input.options();
+  if (input.isPending || (input.isLoading && options.length === 0)) {
+    return {
+      options: [],
+      status: { kind: "loading", message: input.t("agentAutocomplete.searchingWorkspace") },
+    };
+  }
+  if (input.error instanceof Error) {
+    return {
+      options: [],
+      status: {
+        kind: "error",
+        title: input.t("agentAutocomplete.filesFailed"),
+        reason: input.error.message,
+      },
+    };
+  }
+  return withEmptyStatus(options, input.t("agentAutocomplete.noFiles"));
+}
+
+function withEmptyStatus(options: AgentAutocompleteOption[], emptyText: string): AutocompleteMenu {
+  return options.length > 0
+    ? { options, status: null }
+    : { options, status: { kind: "empty", message: emptyText } };
+}
+
+/** How long a command menu waits for commands before it opens on a loading row. */
+const COMMANDS_LOADING_REVEAL_MS = 300;
+
+/**
+ * Whether the open command menu has waited long enough to show a loading row. Commands that
+ * arrive sooner paint the list as the first frame; once the wait is over, loading (a retry)
+ * shows at once so the open menu never closes on itself.
+ */
+function useLoadingRevealed(isMenuOpen: boolean): boolean {
+  const [revealed, setRevealed] = useState(false);
+  useEffect(() => {
+    if (!isMenuOpen) {
+      setRevealed(false);
+      return undefined;
+    }
+    const timer = setTimeout(() => setRevealed(true), COMMANDS_LOADING_REVEAL_MS);
+    return () => clearTimeout(timer);
+  }, [isMenuOpen]);
+  return revealed;
+}
+
+/** The names command rows and status rows show: the provider's label and each plugin's name. */
+function useCommandSourceNames(input: {
+  serverId: string;
+  agentId: string;
+  draftConfig: DraftCommandConfig | undefined;
+  cwd: string;
+  isCommandMenuOpen: boolean;
+  commandsState: CommandsState;
+  pluginCommandCount: number;
+}): { providerLabel: string | null; pluginNames: ReadonlyMap<string, string> } {
+  const agentProvider = useSessionStore(
+    (state) => state.sessions[input.serverId]?.agents?.get(input.agentId)?.provider,
+  );
+  const provider = input.draftConfig?.provider ?? agentProvider;
+  // Only a loading or error row names the provider; only plugin rows need plugin names.
+  const { entries: providerEntries } = useProvidersSnapshot(input.serverId, {
+    cwd: input.cwd,
+    enabled: input.isCommandMenuOpen && input.commandsState !== "ready",
+  });
+  const pluginList = usePluginList(input.serverId, {
+    enabled: input.isCommandMenuOpen && input.pluginCommandCount > 0,
+  });
+  const pluginNames = useMemo(
+    () => new Map((pluginList.data ?? []).map((plugin) => [plugin.id, pluginDisplayName(plugin)])),
+    [pluginList.data],
+  );
+  return {
+    providerLabel: provider ? resolveProviderLabel(provider, providerEntries) : null,
+    pluginNames,
+  };
 }
 
 // A draft's agentId is a draft key the daemon does not know, so a draft lists
@@ -345,14 +475,10 @@ function resolveDraftCommandContext(draft: DraftCommandTarget | undefined) {
   };
 }
 
-function resolveAutocompleteEmptyText(args: {
-  mode: AutocompleteMode;
+function resolveCommandsEmptyText(args: {
   draft: DraftCommandTarget | undefined;
   t: TFunction;
 }): string {
-  if (args.mode === "file") {
-    return args.t("agentAutocomplete.noFiles");
-  }
   if (args.draft?.status === "needs-project") {
     return args.t("agentAutocomplete.chooseProjectForCommands");
   }
@@ -432,16 +558,31 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     autocompleteCwd,
   });
 
-  const commandsQuery = useAgentCommandsQuery({
+  const commandsQuery = useAutocompleteCommands({
     serverId,
     agentId,
     enabled: mode === "command" && canLoadCommands && canListCommands,
     draftConfig: queryDraftConfig,
   });
-  const { commands, isError, error } = commandsQuery;
-  const isCommandsLoading = canListCommands && commandsQuery.isLoading;
-
-  const isVisible = canShowAutocomplete && !(mode === "command" && isCommandsLoading);
+  const commandsState = resolveCommandsState({
+    canListCommands,
+    isLoading: commandsQuery.isLoading,
+    isError: commandsQuery.isError,
+  });
+  const isCommandMenuOpen = mode === "command" && canShowAutocomplete;
+  const isLoadingRevealed = useLoadingRevealed(isCommandMenuOpen);
+  const isVisible =
+    canShowAutocomplete &&
+    !(isCommandMenuOpen && commandsState === "loading" && !isLoadingRevealed);
+  const { providerLabel, pluginNames } = useCommandSourceNames({
+    serverId,
+    agentId,
+    draftConfig: queryDraftConfig,
+    cwd: autocompleteCwd,
+    isCommandMenuOpen,
+    commandsState,
+    pluginCommandCount: pluginClientSlashCommands.length,
+  });
 
   const fileSuggestionsQuery = useQuery({
     queryKey: [
@@ -479,33 +620,67 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
     placeholderData: keepPreviousData,
   });
 
-  const options = useMemo<AgentAutocompleteOption[]>(
-    () =>
-      buildCommandAutocompleteOptions({
+  const commandsEmptyText = resolveCommandsEmptyText({ draft, t });
+  const retryCommandsQuery = commandsQuery.retry;
+  const retryCommands = useCallback(() => {
+    retryCommandsQuery();
+    // Pressing Retry takes focus on web; hand it back so the user keeps typing the command.
+    onAutocompleteApplied?.();
+  }, [onAutocompleteApplied, retryCommandsQuery]);
+  const { options, status } = useMemo<AutocompleteMenu>(() => {
+    if (!isVisible) return { options: [], status: null };
+    const buildOptions = () =>
+      buildAutocompleteOptions({
         activeFileMention,
         commandFilterQuery,
-        commands,
+        commands: commandsQuery.commands,
         pluginCommands: pluginClientSlashCommands,
+        pluginNames,
         activeSlashCommand,
         fileSuggestions: fileSuggestionsQuery.data ?? [],
         isDraftContext,
-        isVisible,
         mode,
         t,
-      }),
-    [
-      activeFileMention,
-      activeSlashCommand,
-      commandFilterQuery,
-      commands,
-      pluginClientSlashCommands,
-      fileSuggestionsQuery.data,
-      isDraftContext,
-      isVisible,
-      mode,
+      });
+    if (mode === "file") {
+      return resolveFileMenu({
+        options: buildOptions,
+        isPending: fileSuggestionsQuery.isPending,
+        isLoading: fileSuggestionsQuery.isLoading,
+        error: fileSuggestionsQuery.error,
+        t,
+      });
+    }
+    return resolveCommandMenu({
+      commandsState,
+      options: buildOptions,
+      providerLabel,
+      error: commandsQuery.error,
+      onRetry: retryCommands,
+      emptyText: commandsEmptyText,
       t,
-    ],
-  );
+    });
+  }, [
+    activeFileMention,
+    activeSlashCommand,
+    commandFilterQuery,
+    commandsEmptyText,
+    commandsQuery.commands,
+    commandsQuery.error,
+    commandsState,
+    fileSuggestionsQuery.data,
+    fileSuggestionsQuery.error,
+    fileSuggestionsQuery.isLoading,
+    fileSuggestionsQuery.isPending,
+    isDraftContext,
+    isVisible,
+    mode,
+    pluginClientSlashCommands,
+    pluginNames,
+    providerLabel,
+    retryCommands,
+    t,
+  ]);
 
   const onSelectOption = useCallback(
     (option: AutocompleteOption, snapshot?: AgentAutocompleteInputSnapshot) => {
@@ -587,35 +762,11 @@ export function useAgentAutocomplete(input: UseAgentAutocompleteInput): AgentAut
         : undefined,
   });
 
-  const isLoading = resolveAutocompleteIsLoading({
-    mode,
-    isCommandsLoading,
-    fileSuggestionsIsPending: fileSuggestionsQuery.isPending,
-    fileSuggestionsIsLoading: fileSuggestionsQuery.isLoading,
-    optionsLength: options.length,
-  });
-  const errorMessage = resolveAutocompleteErrorMessage({
-    mode,
-    isCommandError: isError,
-    commandError: error,
-    fileSuggestionsError: fileSuggestionsQuery.error,
-    t,
-  });
-
-  const loadingText =
-    mode === "file"
-      ? t("agentAutocomplete.searchingWorkspace")
-      : t("agentAutocomplete.loadingCommands");
-  const emptyText = resolveAutocompleteEmptyText({ mode, draft, t });
-
   return {
     isVisible,
     options,
     selectedIndex,
-    isLoading,
-    errorMessage,
-    loadingText,
-    emptyText,
+    status,
     onSelectOption,
     onKeyPress,
   };
diff --git a/packages/app/src/hooks/use-agent-form-state.ts b/packages/app/src/hooks/use-agent-form-state.ts
index 1522ce082e..03de6b6806 100644
--- a/packages/app/src/hooks/use-agent-form-state.ts
+++ b/packages/app/src/hooks/use-agent-form-state.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import type {
   AgentMode,
@@ -28,14 +28,13 @@ import {
   mergeSelectedComposerPreferences,
   buildProviderDefinitionMap,
   buildProviderDefinitionMapForStatuses,
-  INITIAL_AGENT_FORM_RESOLUTION,
-  INITIAL_USER_MODIFIED,
   RESOLVABLE_PROVIDER_STATUSES,
   SELECTABLE_PROVIDER_STATUSES,
   type FormInitialValues,
   type FormState,
   type ProviderModelsByProvider,
 } from "@/provider-selection/resolve-agent-form";
+import { openAgentForm, type AgentFormCatalog } from "@/provider-selection/agent-form-store";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import type { MaterializedAgentProfile } from "@/agent-profiles";
 
@@ -52,6 +51,8 @@ export interface UseAgentFormStateOptions {
 export interface UseAgentFormStateResult {
   selectedServerId: string | null;
   selectedProvider: AgentProvider | null;
+  /** The provider as it is now, which a render may not have reached yet. */
+  getSelectedProvider: () => AgentProvider | null;
   selectedMode: string;
   setModeFromUser: (modeId: string) => void;
   selectedModel: string;
@@ -74,13 +75,20 @@ export interface UseAgentFormStateResult {
   modelError: string | null;
   refreshProviderModels: (provider?: AgentProvider) => void;
   refetchProviderModelsIfStale: () => void;
-  setProviderAndModelFromUser: (provider: AgentProvider, modelId: string) => void;
+  /** `false` when the provider is unknown or not ready. */
+  setProviderAndModelFromUser: (provider: AgentProvider, modelId: string) => boolean;
   applyProfileFromUser: (profile: MaterializedAgentProfile) => void;
   clearProviderSelectionFromUser: () => void;
   workingDirIsEmpty: boolean;
   persistFormPreferences: () => Promise<void>;
 }
 
+const EMPTY_CATALOG: AgentFormCatalog = {
+  selectableProviders: new Map(),
+  models: new Map(),
+  providerPreferences: () => undefined,
+};
+
 function resolveSelectedProviderModes(input: {
   selectedEntry: ProviderSnapshotEntry | null;
   provider: AgentProvider | null;
@@ -172,11 +180,15 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
     [updatePreferences],
   );
 
-  const [{ form: formState, userModified, resolution }, dispatch] = useReducer(resolveAgentForm, {
-    form: { provider: null, modeId: "", model: "", thinkingOptionId: "" },
-    userModified: INITIAL_USER_MODIFIED,
-    resolution: INITIAL_AGENT_FORM_RESOLUTION,
-  });
+  // The store reads what the host offers when a command runs; each render publishes the latest.
+  const catalogRef = useRef<AgentFormCatalog>(EMPTY_CATALOG);
+  const [formStore] = useState(() => openAgentForm(() => catalogRef.current));
+  const { form: formState, resolution } = useSyncExternalStore(
+    formStore.subscribe,
+    formStore.getState,
+    formStore.getState,
+  );
+  const dispatch = formStore.dispatch;
 
   const {
     entries: snapshotEntries,
@@ -246,6 +258,12 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
   const providerDefinitionMap = snapshotProviderDefinitionMap;
   const selectableProviderDefinitionMap = snapshotSelectableProviderDefinitionMap;
   const allProviderModels = snapshotAllProviderModels;
+  catalogRef.current = {
+    selectableProviders: selectableProviderDefinitionMap,
+    models: allProviderModels,
+    providerPreferences: (provider) =>
+      preferenceOverlayRef.current.current().providerPreferences?.[provider],
+  };
   const modelSelectorProviders = snapshotModelSelectorProviders;
   const availableModels = snapshotSelectedProviderModels;
   const modeOptions = snapshotSelectedProviderModes;
@@ -277,27 +295,15 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
     preferences,
     snapshotProviderModelsByProvider,
     snapshotResolvableProviderDefinitionMap,
+    dispatch,
   ]);
 
   const setProviderAndModelFromUser = useCallback(
-    (provider: AgentProvider, modelId: string) => {
-      if (!selectableProviderDefinitionMap.has(provider)) {
-        return;
-      }
-      const providerDef = selectableProviderDefinitionMap.get(provider);
+    (provider: AgentProvider, modelId: string): boolean => {
+      if (!formStore.setProviderAndModel(provider, modelId)) return false;
       const providerModels = allProviderModels.get(provider) ?? null;
-      const providerPrefs = preferenceOverlayRef.current.current().providerPreferences?.[provider];
-      const normalizedModelId = normalizeSelectedModelId(modelId);
-      const nextModelId = normalizedModelId || resolveDefaultModelId(providerModels);
-
-      dispatch({
-        type: "SET_PROVIDER_AND_MODEL_FROM_USER",
-        provider,
-        modelId,
-        providerDef,
-        providerModels,
-        providerPrefs,
-      });
+      const nextModelId =
+        normalizeSelectedModelId(modelId) || resolveDefaultModelId(providerModels);
       void updateCurrentPreferences((current) =>
         mergeSelectedComposerPreferences({
           preferences: current,
@@ -307,13 +313,14 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
           },
         }),
       );
+      return true;
     },
-    [allProviderModels, selectableProviderDefinitionMap, updateCurrentPreferences],
+    [allProviderModels, formStore, updateCurrentPreferences],
   );
 
   const clearProviderSelectionFromUser = useCallback(() => {
     dispatch({ type: "CLEAR_PROVIDER_SELECTION_FROM_USER" });
-  }, []);
+  }, [dispatch]);
 
   const applyProfileFromUser = useCallback(
     (profile: MaterializedAgentProfile) => {
@@ -322,7 +329,8 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
         return;
       }
 
-      const previousProvider = formState.provider;
+      const formBefore = formStore.getState();
+      const previousProvider = formBefore.form.provider;
       const providerDef = selectableProviderDefinitionMap.get(provider);
       const providerModels = allProviderModels.get(provider) ?? null;
       const providerPrefs = preferenceOverlayRef.current.current().providerPreferences?.[provider];
@@ -336,7 +344,7 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
         providerModels,
         providerPrefs,
       };
-      const nextState = resolveAgentForm({ form: formState, userModified, resolution }, action);
+      const nextState = resolveAgentForm(formBefore, action);
       const previousProviderModeIds = previousProvider
         ? (providerDefinitionMap.get(previousProvider)?.modes.map((mode) => mode.id) ?? [])
         : [];
@@ -352,7 +360,7 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
           modelId: model,
           modeId,
           thinkingOptionId,
-          featureValues: profile.featureValues,
+          options: profile.options,
         });
       }).catch((error) => {
         console.warn("[useAgentFormState] persist profile preference failed", error);
@@ -360,19 +368,18 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
     },
     [
       allProviderModels,
-      formState,
+      dispatch,
+      formStore,
       providerDefinitionMap,
-      resolution,
       selectableProviderDefinitionMap,
       updateCurrentPreferences,
-      userModified,
     ],
   );
 
   const setModeFromUser = useCallback(
     (modeId: string) => {
       dispatch({ type: "SET_MODE_FROM_USER", modeId });
-      const provider = formState.provider;
+      const { provider } = formStore.getState().form;
       if (provider) {
         void updateCurrentPreferences((current) =>
           mergeSelectedComposerPreferences({
@@ -385,24 +392,18 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
         );
       }
     },
-    [formState.provider, updateCurrentPreferences],
+    [dispatch, formStore, updateCurrentPreferences],
   );
 
   const setModelFromUser = useCallback(
     (modelId: string) => {
-      const provider = formState.provider;
-      const providerPrefs = provider
-        ? preferenceOverlayRef.current.current().providerPreferences?.[provider]
-        : undefined;
-      dispatch({
-        type: "SET_MODEL_FROM_USER",
-        modelId,
-        availableModels,
-        providerPrefs,
-      });
+      formStore.setModel(modelId);
+      const { provider } = formStore.getState().form;
       if (provider) {
-        const normalizedModelId = normalizeSelectedModelId(modelId);
-        const nextModelId = normalizedModelId || resolveDefaultModelId(availableModels);
+        const listed = allProviderModels.get(provider);
+        const nextModelId =
+          normalizeSelectedModelId(modelId) ||
+          resolveDefaultModelId(listed?.length ? listed : null);
         void updateCurrentPreferences((current) =>
           mergeSelectedComposerPreferences({
             preferences: current,
@@ -414,13 +415,13 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
         );
       }
     },
-    [availableModels, formState.provider, updateCurrentPreferences],
+    [allProviderModels, formStore, updateCurrentPreferences],
   );
 
   const setThinkingOptionFromUser = useCallback(
     (thinkingOptionId: string) => {
       dispatch({ type: "SET_THINKING_OPTION_FROM_USER", thinkingOptionId });
-      const { provider, model: modelId } = formState;
+      const { provider, model: modelId } = formStore.getState().form;
       if (provider && modelId) {
         void updateCurrentPreferences((current) =>
           mergeSelectedComposerPreferences({
@@ -435,9 +436,11 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
         );
       }
     },
-    [formState, updateCurrentPreferences],
+    [dispatch, formStore, updateCurrentPreferences],
   );
 
+  const getSelectedProvider = useCallback(() => formStore.getState().form.provider, [formStore]);
+
   const refreshProviderModels = useCallback(
     (provider?: AgentProvider) => {
       void refreshSnapshot(provider ? [provider] : undefined);
@@ -479,6 +482,7 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
     () => ({
       selectedServerId: serverId,
       selectedProvider: formState.provider,
+      getSelectedProvider,
       selectedMode: formState.modeId,
       setModeFromUser,
       selectedModel: formState.model,
@@ -509,6 +513,7 @@ export function useAgentFormState(options: UseAgentFormStateOptions): UseAgentFo
     }),
     [
       serverId,
+      getSelectedProvider,
       formState.provider,
       formState.modeId,
       formState.model,
diff --git a/packages/app/src/hooks/use-agent-history.test.ts b/packages/app/src/hooks/use-agent-history.test.ts
index d4da1f01bb..9a5d80e07e 100644
--- a/packages/app/src/hooks/use-agent-history.test.ts
+++ b/packages/app/src/hooks/use-agent-history.test.ts
@@ -1,4 +1,4 @@
-import { beforeAll, describe, expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import type {
   DaemonClient,
   FetchAgentHistoryEntry,
@@ -13,18 +13,8 @@ import { allAgentHistoryQueryKey } from "./agent-history-query-key";
   }
 ).__DEV__ = false;
 
-type UseAgentHistoryModule = typeof import("./use-agent-history");
-
-let fetchAgentHistoryBatch: UseAgentHistoryModule["fetchAgentHistoryBatch"];
-let fetchAgentHistoryPage: UseAgentHistoryModule["fetchAgentHistoryPage"];
-let collectAgentHistoryHostErrors: UseAgentHistoryModule["collectAgentHistoryHostErrors"];
-
-beforeAll(async () => {
-  const module = await import("./use-agent-history");
-  fetchAgentHistoryBatch = module.fetchAgentHistoryBatch;
-  fetchAgentHistoryPage = module.fetchAgentHistoryPage;
-  collectAgentHistoryHostErrors = module.collectAgentHistoryHostErrors;
-});
+const { fetchAgentHistoryBatch, fetchAgentHistoryPage, collectAgentHistoryHostErrors } =
+  await import("./use-agent-history");
 
 type FetchAgentHistory = DaemonClient["fetchAgentHistory"];
 type FetchAgentHistoryResult = Awaited<ReturnType<FetchAgentHistory>>;
diff --git a/packages/app/src/hooks/use-agent-history.ts b/packages/app/src/hooks/use-agent-history.ts
index 96b0395e76..efd17c74b3 100644
--- a/packages/app/src/hooks/use-agent-history.ts
+++ b/packages/app/src/hooks/use-agent-history.ts
@@ -4,10 +4,14 @@ import type {
   FetchAgentHistoryPageInfo,
 } from "@getpaseo/client/internal/daemon-client";
 import { useInfiniteQuery } from "@tanstack/react-query";
-import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import type { AggregatedAgent } from "@/hooks/use-aggregated-agents";
-import { getHostRuntimeStore, isHostRuntimeConnected, useHosts } from "@/runtime/host-runtime";
+import {
+  getHostRuntimeStore,
+  useHostRuntimeConnectionStatuses,
+  useHosts,
+} from "@/runtime/host-runtime";
 import { useSessionStore } from "@/stores/session-store";
 import { buildAgentDirectoryState } from "@/utils/agent-directory-sync";
 import { agentHistoryQueryKey, allAgentHistoryQueryKey } from "./agent-history-query-key";
@@ -222,32 +226,29 @@ export function useAgentHistory(options: {
   const { t } = useTranslation();
   const daemons = useHosts();
   const runtime = getHostRuntimeStore();
-  const runtimeVersion = useSyncExternalStore(
-    (onStoreChange) => runtime.subscribeAll(onStoreChange),
-    () => runtime.getVersion(),
-    () => runtime.getVersion(),
-  );
   const serverId = useMemo(() => {
     const value = options.serverId;
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
   }, [options.serverId]);
   const enabled = options.enabled ?? true;
+  const serverIds = useMemo(
+    () => (serverId ? [serverId] : daemons.map((daemon) => daemon.serverId)),
+    [daemons, serverId],
+  );
+  const connectionStatuses = useHostRuntimeConnectionStatuses(serverIds);
   // A host the user asked about splits two ways: one this fetch can reach, and
   // one whose sessions will be missing from the answer. Both come out of here,
   // because dropping the unreachable ones silently is what lets the list — and
   // worse, "No sessions match" — overstate what was actually searched.
   const { targetHosts, unreachableHosts } = useMemo(() => {
-    void runtimeVersion;
     const serverLabelById = new Map(daemons.map((daemon) => [daemon.serverId, daemon.label]));
-    const serverIds = serverId ? [serverId] : daemons.map((daemon) => daemon.serverId);
     const hosts: AgentHistoryHost[] = [];
     const unreachable: AgentHistoryHostError[] = [];
 
     for (const targetServerId of serverIds) {
-      const snapshot = runtime.getSnapshot(targetServerId);
       const client = runtime.getClient(targetServerId);
       const serverName = serverLabelById.get(targetServerId) ?? targetServerId;
-      if (!client || !isHostRuntimeConnected(snapshot)) {
+      if (!client || connectionStatuses.get(targetServerId) !== "online") {
         unreachable.push({ serverId: targetServerId, serverName });
         continue;
       }
@@ -255,7 +256,7 @@ export function useAgentHistory(options: {
     }
 
     return { targetHosts: hosts, unreachableHosts: unreachable };
-  }, [daemons, runtime, runtimeVersion, serverId]);
+  }, [daemons, runtime, connectionStatuses, serverIds]);
   const targetServerIds = useMemo(() => targetHosts.map((host) => host.serverId), [targetHosts]);
   // One gate, checked before the field is offered: a fleet where any host
   // predates search has no search, rather than a list that silently omits that
diff --git a/packages/app/src/hooks/use-agent-screen-state-machine.test.ts b/packages/app/src/hooks/use-agent-screen-state-machine.test.ts
index 68102ed131..1216a6d14e 100644
--- a/packages/app/src/hooks/use-agent-screen-state-machine.test.ts
+++ b/packages/app/src/hooks/use-agent-screen-state-machine.test.ts
@@ -455,6 +455,60 @@ describe("deriveAgentScreenViewState", () => {
     expect(ready.sync).toEqual({ status: "idle" });
   });
 
+  it("stays silent over cached content while the freshness check is unanswered", () => {
+    const input: AgentScreenMachineInput = {
+      ...createBaseInput(),
+      agent: createAgentWithStatus({ id: "agent-1", status: "idle" }),
+      visibilityCatchUpStatus: "checking",
+      hasHydratedHistoryBefore: true,
+    };
+
+    const checking = expectReadyState(
+      deriveAgentScreenViewState({ input, memory: createBaseMemory() }).state,
+    );
+    const behind = expectReadyState(
+      deriveAgentScreenViewState({
+        input: { ...input, visibilityCatchUpStatus: "pending" },
+        memory: createBaseMemory(),
+      }).state,
+    );
+
+    expect(checking.sync).toEqual({ status: "catching_up", ui: "silent" });
+    expect(behind.sync).toEqual({ status: "catching_up", ui: "status" });
+  });
+
+  it("keeps reconnecting until the daemon answers the check made after a reconnect", () => {
+    const ready = expectReadyState(
+      deriveAgentScreenViewState({
+        input: {
+          ...createBaseInput(),
+          agent: createAgentWithStatus({ id: "agent-1", status: "idle" }),
+          isConnected: true,
+          visibilityCatchUpStatus: "reattaching",
+          hasHydratedHistoryBefore: true,
+        },
+        memory: createBaseMemory(),
+      }).state,
+    );
+
+    expect(ready.sync).toEqual({ status: "reconnecting" });
+  });
+
+  it("keeps the blocking overlay while a chat with nothing cached is checked", () => {
+    const input: AgentScreenMachineInput = {
+      ...createBaseInput(),
+      agent: createAgentWithStatus({ id: "agent-1", status: "idle" }),
+      visibilityCatchUpStatus: "checking",
+      hasHydratedHistoryBefore: false,
+    };
+
+    const ready = expectReadyState(
+      deriveAgentScreenViewState({ input, memory: createBaseMemory() }).state,
+    );
+
+    expect(ready.sync).toEqual({ status: "catching_up", ui: "overlay" });
+  });
+
   it("keeps optimistic create non-blocking while timeline and authoritative history catch up", () => {
     const memory = createBaseMemory();
     const input: AgentScreenMachineInput = {
diff --git a/packages/app/src/hooks/use-agent-screen-state-machine.ts b/packages/app/src/hooks/use-agent-screen-state-machine.ts
index e0cc75ee06..4718ec43a1 100644
--- a/packages/app/src/hooks/use-agent-screen-state-machine.ts
+++ b/packages/app/src/hooks/use-agent-screen-state-machine.ts
@@ -1,9 +1,6 @@
 import { useRef } from "react";
-import type {
-  AgentCapabilityFlags,
-  AgentFeature,
-  AgentProvider,
-} from "@getpaseo/protocol/agent-types";
+import type { AgentCapabilityFlags, AgentProvider } from "@getpaseo/protocol/agent-types";
+import type { Agent } from "@/stores/session-store";
 import type { ViewedTimelineStatus } from "@/timeline/viewed-timeline-sync";
 
 export interface AgentScreenAgent {
@@ -22,7 +19,8 @@ export interface AgentScreenAgent {
     modeId?: string | null;
     thinkingOptionId?: string | null;
   } | null;
-  features?: readonly AgentFeature[];
+  options?: Agent["options"];
+  controls?: Agent["controls"];
   lastError?: string | null;
   projectPlacement?: {
     projectKey?: string;
@@ -159,12 +157,13 @@ function resolveAgentScreenSource(args: {
 
 function resolveCatchingUpUi(args: {
   hasOptimisticCreateContinuity: boolean;
+  isFreshnessCheckPending: boolean;
   isVisibilityCatchUpPending: boolean;
   hasHydratedHistoryBefore: boolean;
   hadInitialSyncFailure: boolean;
 }): "overlay" | "status" | "silent" {
   if (args.hasOptimisticCreateContinuity) return "silent";
-  if (args.hasHydratedHistoryBefore) return "status";
+  if (args.hasHydratedHistoryBefore) return args.isFreshnessCheckPending ? "silent" : "status";
   if (args.isVisibilityCatchUpPending) return "overlay";
   if (args.hadInitialSyncFailure) return "silent";
   return "overlay";
@@ -182,7 +181,11 @@ function resolveAgentScreenSync(args: {
   ) {
     return { status: "idle" };
   }
-  if (!input.isConnected && !input.isArchived) {
+  // A reconnected chat is not back until the daemon answers whether it is current.
+  if (
+    (!input.isConnected || input.visibilityCatchUpStatus === "reattaching") &&
+    !input.isArchived
+  ) {
     return { status: "reconnecting" };
   }
   if (input.missingAgentState.kind === "error") {
@@ -191,16 +194,16 @@ function resolveAgentScreenSync(args: {
   if (input.visibilityCatchUpStatus === "error" || input.visibilityCatchUpStatus === "retrying") {
     return { status: "sync_error", isRetrying: input.visibilityCatchUpStatus === "retrying" };
   }
-  if (
-    input.visibilityCatchUpStatus === "pending" ||
-    input.needsAuthoritativeSync ||
-    input.isHistorySyncing
-  ) {
+  const isFreshnessCheckPending = input.visibilityCatchUpStatus === "checking";
+  const isVisibilityCatchUpPending =
+    input.visibilityCatchUpStatus === "pending" || isFreshnessCheckPending;
+  if (isVisibilityCatchUpPending || input.needsAuthoritativeSync || input.isHistorySyncing) {
     return {
       status: "catching_up",
       ui: resolveCatchingUpUi({
         hasOptimisticCreateContinuity: hasOptimisticCreateContinuity(input),
-        isVisibilityCatchUpPending: input.visibilityCatchUpStatus === "pending",
+        isFreshnessCheckPending,
+        isVisibilityCatchUpPending,
         hasHydratedHistoryBefore: input.hasHydratedHistoryBefore,
         hadInitialSyncFailure,
       }),
diff --git a/packages/app/src/hooks/use-aggregated-agents.ts b/packages/app/src/hooks/use-aggregated-agents.ts
index 78cca7fbb3..910caf1d64 100644
--- a/packages/app/src/hooks/use-aggregated-agents.ts
+++ b/packages/app/src/hooks/use-aggregated-agents.ts
@@ -76,7 +76,7 @@ export function useAggregatedAgents(options?: {
       }
       const serverLabel = serverLabelById.get(serverId) ?? serverId;
       for (const agent of agents.values()) {
-        if (!includeArchived && agent.archivedAt) {
+        if (agent.background || (!includeArchived && agent.archivedAt)) {
           continue;
         }
         const nextAgent: AggregatedAgent = {
@@ -85,6 +85,7 @@ export function useAggregatedAgents(options?: {
           serverLabel,
           title: agent.title ?? null,
           status: agent.status,
+          backgroundWork: agent.backgroundWork,
           turn: agent.turn,
           lastActivityAt: agent.lastActivityAt,
           cwd: agent.cwd,
diff --git a/packages/app/src/hooks/use-autocomplete.ts b/packages/app/src/hooks/use-autocomplete.ts
index b461c95551..6392602810 100644
--- a/packages/app/src/hooks/use-autocomplete.ts
+++ b/packages/app/src/hooks/use-autocomplete.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import {
   getAutocompleteFallbackIndex,
   getAutocompleteNextIndex,
@@ -31,38 +31,22 @@ export function useAutocomplete<
   TOption,
   TKeyPressEvent extends AutocompleteKeyPressEvent = AutocompleteKeyPressEvent,
 >(input: UseAutocompleteInput<TOption, TKeyPressEvent>): UseAutocompleteResult<TKeyPressEvent> {
-  const [selectedIndex, setSelectedIndex] = useState(-1);
-  const previousQueryRef = useRef("");
+  // The user's choice, tied to the query it was made for. The shown index is resolved from it
+  // during render, so a list never paints its first frame without a selection: the popover only
+  // measures once a non-empty list has one.
+  const [choice, setChoice] = useState<{ index: number; query: string } | null>(null);
+  const itemCount = input.isVisible ? input.options.length : 0;
+  const selectedIndex = resolveSelectedIndex({
+    choice,
+    query: input.query,
+    itemCount,
+    optionsPosition: input.optionsPosition,
+  });
 
+  // A choice belongs to one search. Until this clears it, the query check above ignores it.
   useEffect(() => {
-    if (!input.isVisible) {
-      previousQueryRef.current = input.query;
-      setSelectedIndex(-1);
-      return;
-    }
-
-    const queryChanged = previousQueryRef.current !== input.query;
-    previousQueryRef.current = input.query;
-
-    setSelectedIndex((current) => {
-      if (input.options.length === 0) {
-        return -1;
-      }
-
-      const fallbackIndex = getAutocompleteFallbackIndex(
-        input.options.length,
-        input.optionsPosition,
-      );
-
-      if (queryChanged) {
-        return fallbackIndex;
-      }
-      if (current < 0 || current >= input.options.length) {
-        return fallbackIndex;
-      }
-      return current;
-    });
-  }, [input.isVisible, input.options.length, input.query, input.optionsPosition]);
+    setChoice(null);
+  }, [input.isVisible, input.query]);
 
   const onKeyPress = useCallback(
     (event: TKeyPressEvent) => {
@@ -70,41 +54,22 @@ export function useAutocomplete<
         return false;
       }
 
-      if (event.key === "ArrowUp") {
+      if (event.key === "ArrowUp" || event.key === "ArrowDown") {
         event.preventDefault();
-        setSelectedIndex((current) =>
-          getAutocompleteNextIndex({
-            currentIndex: current,
+        setChoice({
+          index: getAutocompleteNextIndex({
+            currentIndex: selectedIndex,
             itemCount: input.options.length,
-            key: "ArrowUp",
+            key: event.key,
           }),
-        );
-        return true;
-      }
-
-      if (event.key === "ArrowDown") {
-        event.preventDefault();
-        setSelectedIndex((current) =>
-          getAutocompleteNextIndex({
-            currentIndex: current,
-            itemCount: input.options.length,
-            key: "ArrowDown",
-          }),
-        );
+          query: input.query,
+        });
         return true;
       }
 
       if (event.key === "Tab" || event.key === "Enter") {
         event.preventDefault();
-        const fallbackIndex = getAutocompleteFallbackIndex(
-          input.options.length,
-          input.optionsPosition,
-        );
-        const resolvedIndex =
-          selectedIndex >= 0 && selectedIndex < input.options.length
-            ? selectedIndex
-            : fallbackIndex;
-        const selectedOption = input.options[resolvedIndex];
+        const selectedOption = input.options[selectedIndex];
         if (selectedOption) {
           input.onSelectOption(selectedOption, event);
         }
@@ -127,3 +92,21 @@ export function useAutocomplete<
     onKeyPress,
   };
 }
+
+function resolveSelectedIndex(input: {
+  choice: { index: number; query: string } | null;
+  query: string;
+  itemCount: number;
+  optionsPosition?: AutocompleteOptionsPosition;
+}): number {
+  const { choice } = input;
+  if (
+    choice &&
+    choice.query === input.query &&
+    choice.index >= 0 &&
+    choice.index < input.itemCount
+  ) {
+    return choice.index;
+  }
+  return getAutocompleteFallbackIndex(input.itemCount, input.optionsPosition);
+}
diff --git a/packages/app/src/hooks/use-branch-switcher.ts b/packages/app/src/hooks/use-branch-switcher.ts
index e8e33b7f25..5a47c5117e 100644
--- a/packages/app/src/hooks/use-branch-switcher.ts
+++ b/packages/app/src/hooks/use-branch-switcher.ts
@@ -22,6 +22,9 @@ interface UseBranchSwitcherInput {
 
 interface UseBranchSwitcherResult {
   branchOptions: ComboboxOption[];
+  isLoadingBranches: boolean;
+  isFetchingBranches: boolean;
+  branchError: Error | null;
   isOpen: boolean;
   setIsOpen: (open: boolean) => void;
   handleBranchSelect: (branchId: string) => void;
@@ -185,5 +188,14 @@ export function useBranchSwitcher({
     ],
   );
 
-  return { branchOptions, isOpen, setIsOpen, handleBranchSelect, invalidateStashAndCheckout };
+  return {
+    branchOptions,
+    isLoadingBranches: branchSuggestionsQuery.isPending,
+    isFetchingBranches: branchSuggestionsQuery.isFetching,
+    branchError: branchSuggestionsQuery.error,
+    isOpen,
+    setIsOpen,
+    handleBranchSelect,
+    invalidateStashAndCheckout,
+  };
 }
diff --git a/packages/app/src/hooks/use-draft-agent-features.ts b/packages/app/src/hooks/use-draft-agent-features.ts
deleted file mode 100644
index 9ab23ad6d0..0000000000
--- a/packages/app/src/hooks/use-draft-agent-features.ts
+++ /dev/null
@@ -1,159 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { useTranslation } from "react-i18next";
-import type { AgentProvider, AgentSessionConfig } from "@getpaseo/protocol/agent-types";
-import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import { mergeProviderPreferences, useFormPreferences } from "./use-form-preferences";
-import {
-  applyFeatureValues,
-  pruneFeatureValues,
-  resolveFeatureValues,
-} from "./feature-preferences";
-
-type DraftFeatureConfig = Pick<
-  AgentSessionConfig,
-  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId"
->;
-
-export function useDraftAgentFeatures(input: {
-  serverId: string | null | undefined;
-  provider: AgentProvider | null;
-  cwd: string | null | undefined;
-  modeId: string | null | undefined;
-  modelId: string | null | undefined;
-  thinkingOptionId: string | null | undefined;
-  initialFeatureValues?: Record<string, unknown>;
-}) {
-  const { t } = useTranslation();
-  const { serverId, provider, cwd, modeId, modelId, thinkingOptionId, initialFeatureValues } =
-    input;
-  const [localFeatureValues, setLocalFeatureValues] = useState<Record<string, unknown>>(
-    () => initialFeatureValues ?? {},
-  );
-  const client = useHostRuntimeClient(serverId ?? "");
-  const isConnected = useHostRuntimeIsConnected(serverId ?? "");
-  const { preferences, updatePreferences } = useFormPreferences();
-  const normalizedCwd = cwd?.trim() || "";
-  const normalizedProvider = provider ?? null;
-  const previousProviderRef = useRef<AgentProvider | null>(normalizedProvider);
-  const persistedFeatureValues = useMemo(
-    () => (provider ? (preferences.providerPreferences?.[provider]?.featureValues ?? {}) : {}),
-    [preferences.providerPreferences, provider],
-  );
-
-  const draftConfig = useMemo<DraftFeatureConfig | null>(() => {
-    if (!normalizedProvider || !normalizedCwd) {
-      return null;
-    }
-
-    return {
-      provider: normalizedProvider,
-      cwd: normalizedCwd,
-      ...(modeId ? { modeId } : {}),
-      ...(modelId ? { model: modelId } : {}),
-      ...(thinkingOptionId ? { thinkingOptionId } : {}),
-    };
-  }, [modeId, modelId, normalizedCwd, normalizedProvider, thinkingOptionId]);
-
-  const featuresQuery = useQuery({
-    queryKey: [
-      "providerFeatures",
-      serverId ?? null,
-      normalizedProvider,
-      normalizedCwd || null,
-      modeId ?? null,
-      modelId ?? null,
-      thinkingOptionId ?? null,
-    ],
-    enabled: Boolean(serverId && client && isConnected && draftConfig),
-    staleTime: 5 * 60 * 1000,
-    queryFn: async () => {
-      if (!client || !draftConfig) {
-        throw new Error(t("workspace.terminal.hostDisconnected"));
-      }
-      const payload = await client.listProviderFeatures(draftConfig);
-      if (payload.error) {
-        throw new Error(payload.error);
-      }
-      return payload.features ?? [];
-    },
-  });
-  const availableFeaturesRaw = featuresQuery.data;
-  const availableFeatures = useMemo(() => availableFeaturesRaw ?? [], [availableFeaturesRaw]);
-  const featureValues = useMemo(
-    () =>
-      resolveFeatureValues({
-        features: availableFeatures,
-        persistedFeatureValues,
-        localFeatureValues,
-      }),
-    [availableFeatures, localFeatureValues, persistedFeatureValues],
-  );
-
-  const features = useMemo(() => {
-    return applyFeatureValues(availableFeatures, featureValues);
-  }, [availableFeatures, featureValues]);
-
-  useEffect(() => {
-    const previousProvider = previousProviderRef.current;
-    previousProviderRef.current = normalizedProvider;
-    if (previousProvider === null) {
-      return;
-    }
-    if (previousProvider !== normalizedProvider) {
-      setLocalFeatureValues({});
-    }
-  }, [normalizedProvider]);
-
-  useEffect(() => {
-    if (availableFeaturesRaw === undefined) {
-      return;
-    }
-    const next = pruneFeatureValues(localFeatureValues, availableFeatures);
-    if (next !== localFeatureValues) {
-      setLocalFeatureValues(next);
-    }
-  }, [availableFeatures, availableFeaturesRaw, localFeatureValues]);
-
-  const effectiveFeatureValues = Object.keys(featureValues).length > 0 ? featureValues : undefined;
-  const setFeatureValue = useCallback(
-    (featureId: string, value: unknown) => {
-      setLocalFeatureValues((current) => {
-        if (Object.is(current[featureId], value)) {
-          return current;
-        }
-
-        return { ...current, [featureId]: value };
-      });
-      if (!provider) {
-        return;
-      }
-      void updatePreferences((current) =>
-        mergeProviderPreferences({
-          preferences: current,
-          provider,
-          updates: {
-            featureValues: {
-              [featureId]: value,
-            },
-          },
-        }),
-      ).catch((error) => {
-        console.warn("[useDraftAgentFeatures] persist feature preference failed", error);
-      });
-    },
-    [provider, updatePreferences],
-  );
-
-  const applyProfileFeatureValues = useCallback((values: Record<string, unknown>) => {
-    setLocalFeatureValues(values);
-  }, []);
-
-  return {
-    features,
-    featureValues: effectiveFeatureValues,
-    isLoading: featuresQuery.isLoading,
-    setFeatureValue,
-    applyProfileFeatureValues,
-  };
-}
diff --git a/packages/app/src/hooks/use-draft-provider-options.ts b/packages/app/src/hooks/use-draft-provider-options.ts
new file mode 100644
index 0000000000..52309773c2
--- /dev/null
+++ b/packages/app/src/hooks/use-draft-provider-options.ts
@@ -0,0 +1,134 @@
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useTranslation } from "react-i18next";
+import type { AgentProvider, ProviderOptions } from "@getpaseo/protocol/agent-types";
+import {
+  draftControlsRequest,
+  openDraftOptions,
+  ownDraftOptions,
+  shownDraftOptions,
+  viewDraftOptions,
+} from "@/agent-controls/draft-options-model";
+import type { ComposerOptionControls } from "@/agent-controls/option-controls";
+import { useFetchQuery } from "@/data/query";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { mergeProviderPreferences, useFormPreferences } from "./use-form-preferences";
+
+/**
+ * Adapter between a draft's options model and the screen: it sends the model's complete options
+ * to the daemon, hands the answer back, and persists the user's toggles as last-used values.
+ */
+export function useDraftProviderOptions(input: {
+  serverId: string | null | undefined;
+  provider: AgentProvider | null;
+  /** The form's provider as it is now, which a render may not have reached yet. */
+  getProvider: () => AgentProvider | null;
+  cwd: string | null | undefined;
+  modeId: string | null | undefined;
+  modelId: string | null | undefined;
+  thinkingOptionId: string | null | undefined;
+  initialOptions?: ProviderOptions;
+}) {
+  const { t } = useTranslation();
+  const {
+    serverId,
+    provider,
+    getProvider,
+    cwd,
+    modeId,
+    modelId,
+    thinkingOptionId,
+    initialOptions,
+  } = input;
+  const [model] = useState(() =>
+    openDraftOptions({ provider, seed: initialOptions, currentProvider: getProvider }),
+  );
+  const state = useSyncExternalStore(model.subscribe, model.getState, model.getState);
+  const client = useHostRuntimeClient(serverId ?? "");
+  const isConnected = useHostRuntimeIsConnected(serverId ?? "");
+  const { preferences, updatePreferences } = useFormPreferences();
+  const normalizedCwd = cwd?.trim() || "";
+  const persisted = preferences.providerPreferences?.[provider ?? ""]?.options;
+
+  useEffect(() => model.observeProvider(provider), [model, provider]);
+  useEffect(() => model.setRemembered(persisted ?? {}), [model, persisted]);
+
+  const ownOptions = ownDraftOptions(state);
+  const draftConfig = useMemo(
+    () =>
+      draftControlsRequest(state, {
+        provider,
+        cwd: normalizedCwd,
+        modeId,
+        modelId,
+        thinkingOptionId,
+      }),
+    [modeId, modelId, normalizedCwd, provider, state, thinkingOptionId],
+  );
+  const queryKey = useMemo(
+    () => ["providerControls", serverId ?? null, draftConfig],
+    [draftConfig, serverId],
+  );
+  const requestKey = JSON.stringify(queryKey);
+
+  const { data } = useFetchQuery({
+    queryKey,
+    dataShape: "value",
+    staleTimeMs: 5 * 60 * 1000,
+    enabled: Boolean(serverId && client && isConnected && draftConfig),
+    queryFn: async () => {
+      if (!client || !draftConfig) {
+        throw new Error(t("workspace.terminal.hostDisconnected"));
+      }
+      const payload = await client.listProviderControls(draftConfig);
+      if (payload.error) {
+        throw new Error(payload.error);
+      }
+      return { controls: payload.controls ?? [], options: payload.options ?? {} };
+    },
+  });
+
+  useEffect(() => {
+    if (provider && data) model.applyResolved({ provider, requestKey, ...data });
+  }, [data, model, provider, requestKey]);
+
+  // An edit belongs to the provider the form has now, even before the render that shows it.
+  const setOption = useCallback(
+    (key: string, value: unknown) => {
+      model.setOption(key, value);
+      const current = getProvider();
+      if (!current) return;
+      void updatePreferences((stored) =>
+        mergeProviderPreferences({
+          preferences: stored,
+          provider: current,
+          updates: { options: { [key]: value } },
+        }),
+      ).catch((error) => {
+        console.warn("[useDraftProviderOptions] persist option preference failed", error);
+      });
+    },
+    [getProvider, model, updatePreferences],
+  );
+
+  const view = viewDraftOptions(state, { provider, requestKey });
+  const viewControls = view?.controls;
+  const viewOptions = view?.options;
+  const optionControls = useMemo<ComposerOptionControls | undefined>(
+    () =>
+      viewControls && viewOptions
+        ? { controls: viewControls, options: viewOptions, onSetOption: setOption }
+        : undefined,
+    [setOption, viewControls, viewOptions],
+  );
+
+  // What the draft will create with, the plugin's own edits included, before the daemon answers.
+  const shownOptions = shownDraftOptions(state, { provider, requestKey });
+
+  return {
+    optionControls,
+    options: ownOptions,
+    shownOptions,
+    setOption,
+    applyProfile: model.applyProfile,
+  };
+}
diff --git a/packages/app/src/hooks/use-file-explorer-actions.ts b/packages/app/src/hooks/use-file-explorer-actions.ts
index d54131eb4a..82edab6a13 100644
--- a/packages/app/src/hooks/use-file-explorer-actions.ts
+++ b/packages/app/src/hooks/use-file-explorer-actions.ts
@@ -1,16 +1,18 @@
 import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import {
-  useSessionStore,
-  type AgentFileExplorerState,
-  type ExplorerDirectory,
-} from "@/stores/session-store";
+import { useSessionStore, type AgentFileExplorerState } from "@/stores/session-store";
 import { usePanelStore } from "@/stores/panel-store";
 import { revealExplorerDirectory } from "@/file-explorer/tree";
+import {
+  loadExplorerDirectory,
+  type DirectoryListingResult,
+  invalidateExplorerDirectoryListings,
+} from "@/file-explorer/directory-listings";
 import { parentExplorerPath } from "@/utils/explorer-paths";
 
 function createExplorerState(): AgentFileExplorerState {
   return {
+    listingGeneration: 0,
     directories: new Map(),
     isLoading: false,
     lastError: null,
@@ -22,15 +24,6 @@ function createExplorerState(): AgentFileExplorerState {
   };
 }
 
-function pushHistory(history: string[], path: string): string[] {
-  const normalizedHistory = history.length === 0 ? ["."] : history;
-  const last = normalizedHistory[normalizedHistory.length - 1];
-  if (last === path) {
-    return normalizedHistory;
-  }
-  return [...normalizedHistory, path];
-}
-
 export interface FileExplorerWorkspaceScope {
   workspaceId?: string | null;
   workspaceRoot?: string | null;
@@ -75,16 +68,21 @@ export function useFileExplorerActions(params: { serverId: string } & FileExplor
   );
 
   const updateExplorerState = useCallback(
-    (updater: (prev: AgentFileExplorerState) => AgentFileExplorerState) => {
+    (
+      updater: (prev: AgentFileExplorerState) => AgentFileExplorerState,
+    ): AgentFileExplorerState | null => {
       if (!workspaceStateKey) {
-        return;
+        return null;
       }
+      let updated: AgentFileExplorerState | null = null;
       setFileExplorer(serverId, (prev) => {
         const next = new Map(prev);
         const current = next.get(workspaceStateKey) ?? createExplorerState();
-        next.set(workspaceStateKey, updater(current));
+        updated = updater(current);
+        next.set(workspaceStateKey, updated);
         return next;
       });
+      return updated;
     },
     [serverId, setFileExplorer, workspaceStateKey],
   );
@@ -93,80 +91,23 @@ export function useFileExplorerActions(params: { serverId: string } & FileExplor
     async (
       path: string,
       options?: { recordHistory?: boolean; setCurrentPath?: boolean },
-    ): Promise<ExplorerDirectory | null> => {
+    ): Promise<DirectoryListingResult> => {
       if (!workspaceStateKey) {
         return null;
       }
       const normalizedPath = path && path.length > 0 ? path : ".";
-      const shouldSetCurrentPath = options?.setCurrentPath ?? true;
-      const shouldRecordHistory = options?.recordHistory ?? shouldSetCurrentPath;
-
-      updateExplorerState((state) => ({
-        ...state,
-        isLoading: true,
-        lastError: null,
-        pendingRequest: { path: normalizedPath, mode: "list" },
-        ...(shouldSetCurrentPath
-          ? {
-              currentPath: normalizedPath,
-              history: shouldRecordHistory
-                ? pushHistory(state.history, normalizedPath)
-                : state.history,
-              lastVisitedPath: normalizedPath,
-            }
-          : {}),
-      }));
-
-      if (!normalizedWorkspaceRoot) {
-        updateExplorerState((state) => ({
-          ...state,
-          isLoading: false,
-          lastError: t("workspace.fileExplorer.states.unavailable"),
-          pendingRequest: null,
-        }));
-        return null;
-      }
-
-      if (!client) {
-        updateExplorerState((state) => ({
-          ...state,
-          isLoading: false,
-          lastError: t("workspace.terminal.hostDisconnected"),
-          pendingRequest: null,
-        }));
-        return null;
-      }
-
-      try {
-        const directory = await client.listDirectory(normalizedWorkspaceRoot, normalizedPath);
-        updateExplorerState((state) => {
-          const nextState: AgentFileExplorerState = {
-            ...state,
-            isLoading: false,
-            lastError: null,
-            pendingRequest: null,
-            directories: state.directories,
-          };
-
-          const directories = new Map(state.directories);
-          directories.set(directory.path, directory);
-          nextState.directories = directories;
-
-          return nextState;
-        });
-        return directory;
-      } catch (error) {
-        updateExplorerState((state) => ({
-          ...state,
-          isLoading: false,
-          lastError:
-            error instanceof Error
-              ? error.message
-              : t("workspace.fileExplorer.errors.failedToListDirectory"),
-          pendingRequest: null,
-        }));
-        return null;
-      }
+      return loadExplorerDirectory({
+        path: normalizedPath,
+        options,
+        updateState: updateExplorerState,
+        fallbackError: t("workspace.fileExplorer.errors.failedToListDirectory"),
+        listDirectory: async () => {
+          if (!normalizedWorkspaceRoot)
+            throw new Error(t("workspace.fileExplorer.states.unavailable"));
+          if (!client) throw new Error(t("workspace.terminal.hostDisconnected"));
+          return client.listDirectory(normalizedWorkspaceRoot, normalizedPath);
+        },
+      });
     },
     [client, normalizedWorkspaceRoot, t, updateExplorerState, workspaceStateKey],
   );
@@ -308,10 +249,17 @@ export function useFileExplorerActions(params: { serverId: string } & FileExplor
     [updateExplorerState],
   );
 
+  const invalidateDirectoryListings = useCallback(
+    (retainedPaths: readonly string[]) =>
+      invalidateExplorerDirectoryListings(updateExplorerState, retainedPaths),
+    [updateExplorerState],
+  );
+
   return {
     workspaceStateKey,
     revealDirectory,
     requestDirectoryListing,
+    invalidateDirectoryListings,
     requestFileDownloadToken,
     requestFileBytes,
     createEntry,
diff --git a/packages/app/src/hooks/use-fine-pointer.ts b/packages/app/src/hooks/use-fine-pointer.ts
deleted file mode 100644
index a0bc2489bf..0000000000
--- a/packages/app/src/hooks/use-fine-pointer.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { useEffect, useState } from "react";
-import { isWeb } from "@/constants/platform";
-
-// A touch tablet running the desktop layout is still `isWeb === false || true`
-// depending on the build, so neither platform gate answers "can this user
-// hover and point precisely". Only the media query does.
-const FINE_POINTER_QUERY = "(hover: hover) and (pointer: fine)";
-
-function getFinePointerQueryList(): MediaQueryList | null {
-  if (!isWeb || typeof window === "undefined" || typeof window.matchMedia !== "function") {
-    return null;
-  }
-  return window.matchMedia(FINE_POINTER_QUERY);
-}
-
-/** True when a mouse-like pointer drives the UI. Always false on native. */
-export function hasFinePointer(): boolean {
-  return getFinePointerQueryList()?.matches ?? false;
-}
-
-/**
- * Reactive `hasFinePointer()` — re-renders when the user switches between a
- * mouse and touch (detachable keyboards, tablet mode).
- */
-export function useHasFinePointer(): boolean {
-  const [finePointer, setFinePointer] = useState(hasFinePointer);
-
-  useEffect(() => {
-    const mediaQuery = getFinePointerQueryList();
-    if (!mediaQuery) return;
-    const handleChange = () => setFinePointer(mediaQuery.matches);
-    handleChange();
-    mediaQuery.addEventListener?.("change", handleChange);
-    return () => {
-      mediaQuery.removeEventListener?.("change", handleChange);
-    };
-  }, []);
-
-  return finePointer;
-}
diff --git a/packages/app/src/hooks/use-fork-agent.ts b/packages/app/src/hooks/use-fork-agent.ts
index f2cdf3f911..5ecb08ebe0 100644
--- a/packages/app/src/hooks/use-fork-agent.ts
+++ b/packages/app/src/hooks/use-fork-agent.ts
@@ -36,7 +36,7 @@ export type ForkAgentSource = Pick<
   | "model"
   | "thinkingOptionId"
   | "runtimeInfo"
-  | "features"
+  | "options"
   | "projectPlacement"
 >;
 
@@ -95,18 +95,13 @@ function buildForkDraftSetup(agent: ForkAgentSource): WorkspaceDraftTabSetup | u
     return undefined;
   }
 
-  const featureValues: Record<string, unknown> = {};
-  for (const feature of agent.features ?? []) {
-    featureValues[feature.id] = feature.value;
-  }
-
   return {
     provider: agent.provider,
     cwd: agent.cwd,
     modeId: agent.currentModeId ?? agent.runtimeInfo?.modeId ?? null,
     model: agent.model ?? agent.runtimeInfo?.model ?? null,
     thinkingOptionId: agent.thinkingOptionId ?? agent.runtimeInfo?.thinkingOptionId ?? null,
-    featureValues,
+    providerOptions: { ...agent.options },
   };
 }
 
diff --git a/packages/app/src/hooks/use-form-preferences.test.ts b/packages/app/src/hooks/use-form-preferences.test.ts
index be0653fbc1..9c1dbc7be6 100644
--- a/packages/app/src/hooks/use-form-preferences.test.ts
+++ b/packages/app/src/hooks/use-form-preferences.test.ts
@@ -63,7 +63,7 @@ describe("mergeProviderPreferences", () => {
           providerPreferences: {
             codex: {
               model: "gpt-5.4",
-              featureValues: {
+              options: {
                 fast_mode: true,
               },
             },
@@ -71,7 +71,7 @@ describe("mergeProviderPreferences", () => {
         },
         provider: "codex",
         updates: {
-          featureValues: {
+          options: {
             plan_mode: true,
           },
         },
@@ -81,7 +81,7 @@ describe("mergeProviderPreferences", () => {
       providerPreferences: {
         codex: {
           model: "gpt-5.4",
-          featureValues: {
+          options: {
             fast_mode: true,
             plan_mode: true,
           },
diff --git a/packages/app/src/hooks/use-keyboard-shortcuts.ts b/packages/app/src/hooks/use-keyboard-shortcuts.ts
deleted file mode 100644
index 6f332b0a98..0000000000
--- a/packages/app/src/hooks/use-keyboard-shortcuts.ts
+++ /dev/null
@@ -1,432 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
-import { usePathname, useRouter } from "expo-router";
-import { getIsElectronRuntime } from "@/constants/layout";
-import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
-import { setCommandCenterFocusRestoreElement } from "@/utils/command-center-focus-restore";
-import { getResidentBrowserWebview } from "@/desktop/browser/resident-webviews";
-import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
-import { useKeyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher-context";
-import {
-  type ChordState,
-  type KeyboardShortcutInput,
-  resolveKeyboardShortcut,
-  buildEffectiveBindings,
-  getWorkspaceIndexJumpModifierKey,
-} from "@/keyboard/keyboard-shortcuts";
-import { resolveKeyboardFocusScope } from "@/keyboard/focus-scope";
-import {
-  buildBrowserKeyboardPolicy,
-  parseBrowserShortcutInput,
-  shouldPublishBrowserShortcutPolicy,
-} from "@/desktop/browser/shortcuts";
-import type { KeyboardFocusScope, KeyboardShortcutPayload } from "@/keyboard/actions";
-import {
-  routeKeyboardShortcut,
-  type ShortcutAction,
-  type ShortcutCallbackName,
-} from "@/keyboard/route-shortcut";
-import { getShortcutOs } from "@/utils/shortcut-platform";
-import { useOpenAddProject } from "@/hooks/use-open-add-project";
-import { useStableEvent } from "@/hooks/use-stable-event";
-import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
-import { isNative } from "@/constants/platform";
-import { keyboardShortcutsAvailable } from "@/keyboard/availability";
-import { getDesktopHost, isElectronRuntime } from "@/desktop/host";
-import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
-import { buildOpenProjectRoute } from "@/utils/host-routes";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
-import {
-  type ActiveWorkspaceSelection,
-  navigateToLastWorkspace,
-  useActiveWorkspaceSelection,
-} from "@/stores/navigation-active-workspace-store";
-import { dispatchTopWebOverlayKeyDown, keyBelongsToDomPopover } from "@/lib/overlay-root";
-
-export function useKeyboardShortcuts({
-  enabled,
-  isMobile,
-  isWorkspaceFocusModeEnabled,
-  toggleAgentList,
-  toggleBothSidebars,
-  exitFocusMode,
-  cycleTheme,
-}: {
-  enabled: boolean;
-  isMobile: boolean;
-  isWorkspaceFocusModeEnabled: boolean;
-  toggleAgentList: () => void;
-  toggleBothSidebars?: () => void;
-  exitFocusMode: () => void;
-  cycleTheme?: () => void;
-}) {
-  const keyboardActionDispatcher = useKeyboardActionDispatcher();
-  const pathname = usePathname();
-  const router = useRouter();
-  const resetModifiers = useKeyboardShortcutsStore((s) => s.resetModifiers);
-  const { overrides } = useKeyboardShortcutOverrides();
-  const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
-  const shortcutsAvailable = keyboardShortcutsAvailable({ isNative, isCompact: isMobile });
-  const isDesktopApp = getIsElectronRuntime();
-  const isMac = getShortcutOs() === "mac";
-  const chordStateRef = useRef<ChordState>({
-    candidateIndices: [],
-    step: 0,
-    timeoutId: null,
-  });
-  const openProjectPickerAction = useOpenAddProject();
-  const activeWorkspaceSelection = useActiveWorkspaceSelection();
-  const keyboardWorkspaceSelectionRef = useRef<ActiveWorkspaceSelection | null>(null);
-
-  const publishBrowserShortcutPolicy = useCallback(
-    (chordState?: ChordState) => {
-      const policy =
-        enabled && shortcutsAvailable
-          ? buildBrowserKeyboardPolicy({
-              bindings,
-              chordState,
-              isMac,
-              isDesktop: isDesktopApp,
-            })
-          : { menuPrefixes: [], prefixes: [] };
-      void getDesktopHost()?.browser?.setShortcutPolicy?.(policy);
-    },
-    [bindings, enabled, isDesktopApp, isMac, shortcutsAvailable],
-  );
-
-  useEffect(() => {
-    if (activeWorkspaceSelection) {
-      keyboardWorkspaceSelectionRef.current = activeWorkspaceSelection;
-    }
-  }, [activeWorkspaceSelection]);
-
-  useEffect(() => {
-    if (!isDesktopApp) {
-      return;
-    }
-
-    publishBrowserShortcutPolicy();
-  }, [isDesktopApp, publishBrowserShortcutPolicy]);
-
-  // Only the modifier that actually performs the workspace-index jump on this
-  // runtime should reveal the sidebar number badges (Alt on web, Cmd on
-  // desktop Mac, Ctrl on desktop non-Mac). The store ORs altDown/cmdOrCtrlDown
-  // to drive badge visibility, so we set the flag matching this runtime.
-  // Derived from the effective bindings: `null` when the user unassigned or
-  // rebound the jump shortcut, and no `event.key` ever equals null, so the
-  // badges simply never appear.
-  const badgeModifierKey = getWorkspaceIndexJumpModifierKey(
-    { isMac, isDesktop: isDesktopApp },
-    bindings,
-  );
-
-  // The keyup listener matches the released key against the current modifier,
-  // so a modifier held while the jump binding changes could never be released
-  // and the badges would stay up until a blur. Clear them when it changes.
-  useEffect(() => {
-    resetModifiers();
-  }, [badgeModifierKey, resetModifiers]);
-
-  const setBadgeModifierDown = (down: boolean) => {
-    const state = useKeyboardShortcutsStore.getState();
-    if (isDesktopApp) {
-      state.setCmdOrCtrlDown(down);
-    } else {
-      state.setAltDown(down);
-    }
-  };
-
-  const shouldHandle = () => {
-    if (typeof document === "undefined") return false;
-    if (document.visibilityState !== "visible") return false;
-    return true;
-  };
-
-  const captureCommandCenterFocusRestore = (event: KeyboardEvent) => {
-    const target = event.target instanceof Element ? event.target : null;
-    const targetEl =
-      target?.closest?.("textarea, input, [contenteditable='true']") ??
-      (target instanceof HTMLElement ? target : null);
-    const active = document.activeElement;
-    const activeEl = active instanceof HTMLElement ? active : null;
-    setCommandCenterFocusRestoreElement((targetEl as HTMLElement | null) ?? activeEl ?? null);
-  };
-
-  const callbacksByName: Record<ShortcutCallbackName, (() => void) | undefined> = {
-    "toggle-agent-list": toggleAgentList,
-    "toggle-both-sidebars": toggleBothSidebars,
-    "cycle-theme": cycleTheme,
-  };
-
-  const performShortcutAction = (
-    action: ShortcutAction,
-    event: KeyboardEvent | null,
-    browserFocusRestoreElement: HTMLElement | null = null,
-  ): boolean => {
-    switch (action.kind) {
-      case "none":
-        return false;
-      case "dispatch":
-        return keyboardActionDispatcher.dispatch(action.action);
-      case "navigate-workspace":
-        keyboardWorkspaceSelectionRef.current = {
-          serverId: action.serverId,
-          workspaceId: action.workspaceId,
-        };
-        navigateToWorkspace({ serverId: action.serverId, workspaceId: action.workspaceId });
-        return true;
-      case "navigate-last-workspace":
-        if (navigateToLastWorkspace()) {
-          return true;
-        }
-        router.replace(buildOpenProjectRoute());
-        return true;
-      case "router-replace":
-        router.replace(action.route as Parameters<typeof router.replace>[0]);
-        return true;
-      case "router-back":
-        router.back();
-        return true;
-      case "router-push":
-        router.push(action.route as Parameters<typeof router.push>[0]);
-        return true;
-      case "open-project-picker":
-        void openProjectPickerAction();
-        return true;
-      case "callback":
-        callbacksByName[action.name]?.();
-        return true;
-      case "command-center-toggle": {
-        if (action.nextOpen) {
-          if (event) {
-            captureCommandCenterFocusRestore(event);
-          } else {
-            setCommandCenterFocusRestoreElement(browserFocusRestoreElement);
-          }
-        }
-        useKeyboardShortcutsStore
-          .getState()
-          .setCommandCenterOpen(action.nextOpen, action.scope ?? null);
-        return true;
-      }
-      case "shortcuts-dialog-toggle":
-        useKeyboardShortcutsStore.getState().setShortcutsDialogOpen(action.nextOpen);
-        return true;
-    }
-  };
-
-  const routeAndPerformShortcut = (input: {
-    action: string;
-    payload: KeyboardShortcutPayload;
-    domEvent: KeyboardEvent | null;
-    browserFocusRestoreElement?: HTMLElement | null;
-  }): boolean => {
-    const store = useKeyboardShortcutsStore.getState();
-    const shortcutAction = routeKeyboardShortcut(
-      { action: input.action, payload: input.payload },
-      {
-        pathname,
-        isMobile,
-        sidebarShortcutTargets: store.sidebarShortcutWorkspaceTargets,
-        navigationActiveWorkspace:
-          keyboardWorkspaceSelectionRef.current ?? activeWorkspaceSelection,
-        commandCenterOpen: store.commandCenterOpen,
-        shortcutsDialogOpen: store.shortcutsDialogOpen,
-      },
-    );
-    const handled = performShortcutAction(
-      shortcutAction,
-      input.domEvent,
-      input.browserFocusRestoreElement,
-    );
-    if (handled && isWorkspaceFocusModeEnabled && input.action.startsWith("sidebar.")) {
-      exitFocusMode();
-    }
-    return handled;
-  };
-
-  const resolveAndPerformShortcut = (input: {
-    event: KeyboardShortcutInput;
-    focusScope: KeyboardFocusScope;
-    domEvent: KeyboardEvent | null;
-    browserFocusRestoreElement?: HTMLElement | null;
-  }) => {
-    const store = useKeyboardShortcutsStore.getState();
-    const previousChordState = chordStateRef.current;
-    const result = resolveKeyboardShortcut({
-      event: input.event,
-      context: {
-        isMac,
-        isDesktop: isDesktopApp,
-        focusScope: input.focusScope,
-        commandCenterOpen: store.commandCenterOpen,
-      },
-      chordState: chordStateRef.current,
-      onChordReset: () => {
-        chordStateRef.current = {
-          candidateIndices: [],
-          step: 0,
-          timeoutId: null,
-        };
-        publishBrowserShortcutPolicy();
-      },
-      bindings,
-    });
-    chordStateRef.current = result.nextChordState;
-    if (
-      shouldPublishBrowserShortcutPolicy({
-        isBrowserInput: "browserId" in input.event,
-        previousChordState,
-        nextChordState: result.nextChordState,
-      })
-    ) {
-      publishBrowserShortcutPolicy(result.nextChordState);
-    }
-
-    if (result.preventDefault && input.domEvent) {
-      input.domEvent.preventDefault();
-      input.domEvent.stopPropagation();
-    }
-
-    if (!result.match) {
-      return;
-    }
-
-    const handled = routeAndPerformShortcut({
-      action: result.match.action,
-      payload: result.match.payload,
-      domEvent: input.domEvent,
-      browserFocusRestoreElement: input.browserFocusRestoreElement,
-    });
-    if (!handled || !input.domEvent) {
-      return;
-    }
-
-    if (result.match.preventDefault) {
-      input.domEvent.preventDefault();
-    }
-    if (result.match.stopPropagation) {
-      input.domEvent.stopPropagation();
-    }
-  };
-
-  // The window listeners must outlive ordinary re-renders: removing them resets
-  // any in-progress chord. Stable events let them read the latest render instead
-  // of being re-registered whenever a route, callback, or selection changes.
-  const handleKeyDown = useStableEvent((event: KeyboardEvent) => {
-    if (!shouldHandle()) {
-      return;
-    }
-
-    if (dispatchTopWebOverlayKeyDown(event)) {
-      return;
-    }
-
-    if (keyBelongsToDomPopover(event)) {
-      return;
-    }
-
-    // During IME composition, Enter confirms the candidate selection and must
-    // not route through global shortcuts like message send.
-    if (isImeComposingKeyboardEvent(event)) {
-      return;
-    }
-
-    const store = useKeyboardShortcutsStore.getState();
-    if (store.capturingShortcut) {
-      return;
-    }
-
-    const key = event.key ?? "";
-    if (
-      key === "Escape" &&
-      pathname.startsWith("/settings") &&
-      !isMobile &&
-      hasActiveWebOverlay()
-    ) {
-      return;
-    }
-    if (key === badgeModifierKey && !event.shiftKey) {
-      setBadgeModifierDown(true);
-    }
-    if (key === "Shift") {
-      const state = useKeyboardShortcutsStore.getState();
-      if (state.altDown || state.cmdOrCtrlDown) {
-        state.resetModifiers();
-      }
-    }
-
-    const focusScope = resolveKeyboardFocusScope({
-      target: event.target,
-      commandCenterOpen: store.commandCenterOpen,
-    });
-    resolveAndPerformShortcut({
-      event,
-      focusScope,
-      domEvent: event,
-    });
-  });
-
-  const handleKeyUp = useStableEvent((event: KeyboardEvent) => {
-    const key = event.key ?? "";
-    if (key === badgeModifierKey) {
-      setBadgeModifierDown(false);
-    }
-  });
-
-  const handleBrowserShortcutInput = useStableEvent((payload: unknown) => {
-    const input = parseBrowserShortcutInput(payload);
-    if (!input) {
-      return;
-    }
-    resolveAndPerformShortcut({
-      event: input,
-      focusScope: "browser",
-      domEvent: null,
-      browserFocusRestoreElement: getResidentBrowserWebview(input.browserId),
-    });
-  });
-
-  useEffect(() => {
-    if (!enabled) return;
-    if (!shortcutsAvailable) return;
-
-    const handleBlurOrHide = () => {
-      resetModifiers();
-    };
-
-    window.addEventListener("keydown", handleKeyDown, true);
-    window.addEventListener("keyup", handleKeyUp, true);
-    window.addEventListener("blur", handleBlurOrHide);
-    document.addEventListener("visibilitychange", handleBlurOrHide);
-
-    const browserShortcutSubscription = isElectronRuntime()
-      ? getDesktopHost()?.events?.on?.("browser-shortcut-input", handleBrowserShortcutInput)
-      : null;
-    return () => {
-      if (chordStateRef.current.timeoutId !== null) {
-        clearTimeout(chordStateRef.current.timeoutId);
-        chordStateRef.current = {
-          candidateIndices: [],
-          step: 0,
-          timeoutId: null,
-        };
-      }
-      window.removeEventListener("keydown", handleKeyDown, true);
-      window.removeEventListener("keyup", handleKeyUp, true);
-      window.removeEventListener("blur", handleBlurOrHide);
-      document.removeEventListener("visibilitychange", handleBlurOrHide);
-      if (typeof browserShortcutSubscription === "function") {
-        browserShortcutSubscription();
-      } else {
-        void browserShortcutSubscription?.then((dispose) => dispose());
-      }
-    };
-  }, [
-    enabled,
-    handleBrowserShortcutInput,
-    handleKeyDown,
-    handleKeyUp,
-    resetModifiers,
-    shortcutsAvailable,
-  ]);
-}
diff --git a/packages/app/src/hooks/use-load-older-agent-history.test.ts b/packages/app/src/hooks/use-load-older-agent-history.test.ts
index 3259631992..e3ece6990f 100644
--- a/packages/app/src/hooks/use-load-older-agent-history.test.ts
+++ b/packages/app/src/hooks/use-load-older-agent-history.test.ts
@@ -129,7 +129,7 @@ describe("loadOlderAgentHistory", () => {
 
     expect(client.calls).toEqual([]);
     expect(inFlight.values).toEqual([true]);
-    expect(started).toBe(true);
+    expect(started).toBe(false);
   });
 
   it("requests the page before the current start cursor and clears in-flight on success", async () => {
@@ -153,6 +153,7 @@ describe("loadOlderAgentHistory", () => {
           limit: TIMELINE_FETCH_PAGE_SIZE,
           projection: "projected",
           wholeTurns: true,
+          timeout: 10_000,
         },
       },
     ]);
@@ -169,7 +170,7 @@ describe("loadOlderAgentHistory", () => {
     const toast = createToast();
     const logger = createLogger();
 
-    await loadOlderAgentHistory(agentId, {
+    const applied = await loadOlderAgentHistory(agentId, {
       client,
       cursor: someCursor,
       hasOlder: true,
@@ -179,6 +180,7 @@ describe("loadOlderAgentHistory", () => {
       logger,
     });
 
+    expect(applied).toBe(false);
     expect(client.calls).toHaveLength(1);
     expect(toast.shown).toEqual([
       {
diff --git a/packages/app/src/hooks/use-load-older-agent-history.ts b/packages/app/src/hooks/use-load-older-agent-history.ts
index 2bc3f5c9df..a3887dd7b2 100644
--- a/packages/app/src/hooks/use-load-older-agent-history.ts
+++ b/packages/app/src/hooks/use-load-older-agent-history.ts
@@ -18,6 +18,7 @@ export interface LoadOlderAgentHistoryClient {
       cursor: { epoch: string; seq: number };
       limit: number;
       projection: "projected";
+      timeout: number;
     },
   ) => Promise<unknown>;
 }
@@ -44,7 +45,7 @@ export async function loadOlderAgentHistory(
   const { client, cursor, hasOlder, isLoadingOlder, setInFlight, toast, logger, failedMessage } =
     deps;
   if (isLoadingOlder) {
-    return true;
+    return false;
   }
   if (!client || !cursor || !hasOlder) {
     return false;
@@ -52,16 +53,17 @@ export async function loadOlderAgentHistory(
 
   setInFlight(true);
   try {
-    await client.fetchAgentTimeline(
-      agentId,
-      planTimelineOlderFetch({ epoch: cursor.epoch, seq: cursor.startSeq }),
-    );
+    await client.fetchAgentTimeline(agentId, {
+      ...planTimelineOlderFetch({ epoch: cursor.epoch, seq: cursor.startSeq }),
+      timeout: 10_000,
+    });
   } catch (error) {
     (logger ?? console).warn("[Timeline] failed to load older agent history", agentId, error);
     toast?.show(failedMessage ?? i18n.t("loadOlderHistory.failed"), {
       durationMs: 2200,
       testID: "agent-load-older-history-toast",
     });
+    return false;
   } finally {
     setInFlight(false);
   }
diff --git a/packages/app/src/hooks/use-providers-snapshot.test.ts b/packages/app/src/hooks/use-providers-snapshot.test.ts
index 2f3c90b340..0c730cddbd 100644
--- a/packages/app/src/hooks/use-providers-snapshot.test.ts
+++ b/packages/app/src/hooks/use-providers-snapshot.test.ts
@@ -1,4 +1,4 @@
-import { QueryClient } from "@tanstack/react-query";
+import { QueryClient, QueryObserver } from "@tanstack/react-query";
 import { beforeEach, describe, expect, it } from "vitest";
 
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -8,7 +8,7 @@ import {
   expandProviderSnapshot,
 } from "@getpaseo/protocol/provider-snapshot-codec";
 import type { CachedProviderSnapshot, ProviderSnapshotCache } from "@/data/provider-snapshot-cache";
-import { draftAgentCommandsQueryKey } from "@/hooks/agent-commands-query";
+import { draftAgentCommandsQueryKey, sessionAgentCommandsQueryKey } from "@/agent-commands/cache";
 import { providerSnapshotIcons } from "@/data/provider-icons";
 import { applyProvidersSnapshotUpdate, type ProvidersSnapshotUpdate } from "@/data/push-router";
 import {
@@ -363,6 +363,153 @@ describe("applyProvidersSnapshotUpdate", () => {
     };
   }
 
+  it("refreshes active commands only when their provider changes after discovery", async () => {
+    const key = sessionAgentCommandsQueryKey({ serverId, agentId: "agent-1" });
+    let requests = 0;
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: async () => {
+        requests++;
+        return [{ name: "review" }];
+      },
+      staleTime: Infinity,
+      meta: { agentCommandProvider: "codex", agentCommandCwd: "/repo-a" },
+    });
+    const unsubscribe = observer.subscribe(() => {});
+    await observer.refetch({ cancelRefetch: false });
+    expect(requests).toBe(1);
+    const codex = codexEntry("ready", [readyCodexModel]);
+    const other = { provider: "claude", status: "loading", enabled: true } as ProviderSnapshotEntry;
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage([codexEntry("loading"), other], "/repo-a"),
+    });
+    expect(requests).toBe(1);
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage([codex, other], "/repo-a"),
+    });
+    expect(requests).toBe(1);
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage([codex, { ...other, status: "ready" }], "/repo-a"),
+    });
+    expect(requests).toBe(1);
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage(
+        [
+          { ...codex, fetchedAt: "2026-01-01T00:00:02.000Z" },
+          { ...other, status: "ready" },
+        ],
+        "/repo-a",
+      ),
+    });
+    expect(requests).toBe(1);
+    queryClient.setQueryData(
+      providersSnapshotQueryKey(serverId, "/repo-b"),
+      providersSnapshot([codex]),
+    );
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage(
+        [codexEntry("ready", [{ ...readyCodexModel, label: "Other checkout" }])],
+        "/repo-b",
+      ),
+    });
+    expect(requests).toBe(1);
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage(
+        [
+          codexEntry("ready", [{ ...readyCodexModel, label: "Updated" }]),
+          { ...other, status: "ready" },
+        ],
+        "/repo-a",
+      ),
+    });
+    await observer.refetch({ cancelRefetch: false });
+    expect(requests).toBe(2);
+    unsubscribe();
+    queryClient.clear();
+  });
+
+  it("retries a failed command discovery when its provider first becomes ready", async () => {
+    const key = sessionAgentCommandsQueryKey({ serverId, agentId: "agent-1" });
+    let ready = false;
+    let requests = 0;
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: async () => {
+        requests++;
+        if (!ready) throw new Error("provider unavailable");
+        return [{ name: "review" }];
+      },
+      retry: false,
+      meta: { agentCommandProvider: "codex", agentCommandCwd: "/repo-a" },
+    });
+    const unsubscribe = observer.subscribe(() => {});
+    await observer.refetch({ cancelRefetch: false });
+    expect(observer.getCurrentResult().isError).toBe(true);
+    ready = true;
+    await applyProvidersSnapshotUpdate({
+      client: createClient(),
+      serverId,
+      queryClient,
+      message: updateMessage([codexEntry("ready", [readyCodexModel])], "/repo-a"),
+    });
+    await observer.refetch({ cancelRefetch: false });
+    expect(requests).toBe(2);
+    expect(observer.getCurrentResult().data).toEqual([{ name: "review" }]);
+    unsubscribe();
+    queryClient.clear();
+  });
+
+  it("refreshes again when its provider changes during an active refresh", async () => {
+    const key = sessionAgentCommandsQueryKey({ serverId, agentId: "agent-1" });
+    queryClient.setQueryData(key, [{ name: "old" }]);
+    let requests = 0;
+    const waiting = new Promise<{ name: string }[]>(() => {});
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: async () => (++requests === 1 ? waiting : [{ name: "new" }]),
+      staleTime: Infinity,
+      meta: { agentCommandProvider: "codex", agentCommandCwd: "/repo-a" },
+    });
+    const unsubscribe = observer.subscribe(() => {});
+    queryClient.setQueryData(
+      providersSnapshotQueryKey(serverId, "/repo-a"),
+      providersSnapshot([codexEntry("ready", [readyCodexModel])]),
+    );
+    const send = (label: string) =>
+      applyProvidersSnapshotUpdate({
+        client: createClient(),
+        serverId,
+        queryClient,
+        message: updateMessage([codexEntry("ready", [{ ...readyCodexModel, label }])], "/repo-a"),
+      });
+    await send("First change");
+    expect(requests).toBe(1);
+    await send("Second change");
+    expect(requests).toBe(2);
+    await observer.refetch({ cancelRefetch: false });
+    expect(observer.getCurrentResult().data).toEqual([{ name: "new" }]);
+    unsubscribe();
+    queryClient.clear();
+  });
+
   it("routes updates to the home query cache when the message carries no cwd", async () => {
     await applyProvidersSnapshotUpdate({
       client: createClient(),
@@ -455,6 +602,10 @@ describe("applyProvidersSnapshotUpdate", () => {
       draftConfig: { provider: "codex", cwd: "/repo-a" },
     });
     queryClient.setQueryData(commandsKey, [{ name: "compact", description: "", argumentHint: "" }]);
+    queryClient.setQueryData(
+      providersSnapshotQueryKey(serverId, "/repo-a"),
+      providersSnapshot([codexEntry("ready")]),
+    );
 
     await applyProvidersSnapshotUpdate({
       client: createClient(),
diff --git a/packages/app/src/hooks/use-providers-snapshot.ts b/packages/app/src/hooks/use-providers-snapshot.ts
index dc90c18f06..d823782cbf 100644
--- a/packages/app/src/hooks/use-providers-snapshot.ts
+++ b/packages/app/src/hooks/use-providers-snapshot.ts
@@ -10,6 +10,7 @@ import { useReplicaQuery } from "@/data/query";
 import { queryClient as singletonQueryClient } from "@/data/query-client";
 import {
   normalizeProvidersSnapshotCwd,
+  providersSnapshotQuery,
   providersSnapshotQueryKey,
   providersSnapshotQueryRoot,
   fetchProvidersSnapshot,
@@ -78,17 +79,16 @@ export function useProvidersSnapshot(
   const queryKey = useMemo(() => providersSnapshotQueryKey(serverId, cwd), [cwd, serverId]);
 
   const snapshotQuery = useReplicaQuery({
-    queryKey,
-    // The content-hash cache already owns catalog and model identity.
-    structuralSharing: false,
+    ...providersSnapshotQuery({
+      serverId: serverId ?? "",
+      cwd,
+      client: () => {
+        if (!client || !serverId) throw new Error(t("workspace.terminal.hostDisconnected"));
+        return client;
+      },
+      queryClient,
+    }),
     enabled: Boolean(enabled && supportsSnapshot && serverId && client && isConnected),
-    pushEvent: "providers_snapshot_update",
-    queryFn: async ({ signal }) => {
-      if (!client || !serverId) {
-        throw new Error(t("workspace.terminal.hostDisconnected"));
-      }
-      return fetchProvidersSnapshot({ client, serverId, cwd, queryClient, signal });
-    },
   });
 
   const refreshMutation = useMutation({
diff --git a/packages/app/src/hooks/use-shortcut-keys.ts b/packages/app/src/hooks/use-shortcut-keys.ts
index d0d8c98c8b..d3eabd5fff 100644
--- a/packages/app/src/hooks/use-shortcut-keys.ts
+++ b/packages/app/src/hooks/use-shortcut-keys.ts
@@ -1,21 +1,20 @@
+import { usesDesktopBindings } from "@/keyboard";
 import { useMemo } from "react";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { resolveShortcutKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { getShortcutOs } from "@/utils/shortcut-platform";
-import { getIsElectronRuntime } from "@/constants/layout";
 
 /** `null` action ids are accepted so callers can keep the hook unconditional. */
 export function useShortcutKeys(actionId: string | null): ShortcutKey[][] | null {
   const { overrides } = useKeyboardShortcutOverrides();
   const isMac = getShortcutOs() === "mac";
-  const isDesktopApp = getIsElectronRuntime();
 
   return useMemo(() => {
     if (actionId === null) return null;
     return resolveShortcutKeysForAction(actionId, overrides, {
       isMac,
-      isDesktop: isDesktopApp,
+      usesDesktopBindings,
     });
-  }, [actionId, overrides, isMac, isDesktopApp]);
+  }, [actionId, overrides, isMac]);
 }
diff --git a/packages/app/src/hosts/add-host/index.tsx b/packages/app/src/hosts/add-host/index.tsx
new file mode 100644
index 0000000000..42b37c6d8e
--- /dev/null
+++ b/packages/app/src/hosts/add-host/index.tsx
@@ -0,0 +1,89 @@
+import { createContext, useCallback, useContext, useState, useMemo, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { useStore } from "zustand";
+import { AddHostMethodModal } from "./internal/add-host-method-modal";
+import { AddHostModal } from "./internal/add-host-modal";
+import { AddRemoteSshHostModal } from "./internal/add-remote-ssh-host-modal";
+import { PairLinkModal } from "./internal/pair-link-modal";
+import { AdaptiveModalSheet } from "@/components/adaptive-modal-sheet";
+import { PairScanContent } from "./internal/scan";
+import { createAddHostFlow, type AddHostOptions, type AddHostSession } from "./internal/model";
+
+const Context = createContext<ReturnType<typeof createAddHostFlow> | null>(null);
+
+/** Owns the flow outside screen and appearance lifetimes. Callers own success navigation. */
+export function AddHostProvider({ children }: { children: ReactNode }) {
+  const [flow] = useState(createAddHostFlow);
+  return <Context.Provider value={flow}>{children}</Context.Provider>;
+}
+
+export function AddHostFlowHost() {
+  const flow = useContext(Context);
+  if (!flow) throw new Error("AddHostFlowHost requires AddHostProvider");
+  const session = useStore(flow.store, (state) => state.session);
+  return session ? <AddHostSessionView key={session.id} session={session} /> : null;
+}
+
+export function useAddHost({ method, onAdded }: AddHostOptions = {}) {
+  const flow = useContext(Context);
+  if (!flow) throw new Error("useAddHost requires AddHostProvider");
+  return useCallback(() => flow.open({ method, onAdded }), [flow, method, onAdded]);
+}
+
+function AddHostSessionView({ session }: { session: AddHostSession }) {
+  const { t } = useTranslation();
+  const method = useStore(session.step, (state) => state.method);
+  const back = useCallback(() => session.choose(null), [session]);
+  const direct = useCallback(() => session.choose("direct"), [session]);
+  const ssh = useCallback(() => session.choose("ssh"), [session]);
+  const link = useCallback(() => session.choose("link"), [session]);
+  const scan = useCallback(() => session.choose("scan"), [session]);
+  const scanned = useCallback((serverId: string) => session.complete({ serverId }), [session]);
+  const header = useMemo(
+    () => ({ title: t("pairing.scan.title"), back: { onPress: back } }),
+    [t, back],
+  );
+  return (
+    <>
+      <AddHostMethodModal
+        visible={method === null}
+        onClose={session.close}
+        onDirectConnection={direct}
+        onRemoteSsh={ssh}
+        onPasteLink={link}
+        onScanQr={scan}
+      />
+      <AddHostModal
+        visible={method === "direct"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      <AddRemoteSshHostModal
+        visible={method === "ssh"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      <PairLinkModal
+        visible={method === "link"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      {method === "scan" ? (
+        <AdaptiveModalSheet
+          header={header}
+          visible
+          onClose={session.close}
+          scrollable={false}
+          snapPoints={SCAN_SNAP_POINTS}
+          desktopHeight="85%"
+        >
+          <PairScanContent onConnected={scanned} onClose={back} />
+        </AdaptiveModalSheet>
+      ) : null}
+    </>
+  );
+}
+const SCAN_SNAP_POINTS = ["90%"];
diff --git a/packages/app/src/components/add-host-method-modal.tsx b/packages/app/src/hosts/add-host/internal/add-host-method-modal.tsx
similarity index 92%
rename from packages/app/src/components/add-host-method-modal.tsx
rename to packages/app/src/hosts/add-host/internal/add-host-method-modal.tsx
index b97c529bef..35e61a5d17 100644
--- a/packages/app/src/components/add-host-method-modal.tsx
+++ b/packages/app/src/hosts/add-host/internal/add-host-method-modal.tsx
@@ -1,9 +1,10 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { Pressable, Text, View } from "react-native";
+import { Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { QrCode, Link2, ClipboardPaste, Terminal } from "lucide-react-native";
-import { AdaptiveModalSheet, type SheetHeader } from "./adaptive-modal-sheet";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { isFdroidBuild } from "@/constants/build-profile";
 import { isNative } from "@/constants/platform";
 import { isElectronRuntime } from "@/desktop/host";
@@ -84,7 +85,7 @@ export function AddHostMethodModal({
       onClose={onClose}
       testID="add-host-method-modal"
     >
-      <Pressable
+      <PressHighlight
         style={styles.option}
         onPress={handleDirect}
         accessibilityRole="button"
@@ -98,10 +99,10 @@ export function AddHostMethodModal({
             {t("pairing.connectionMethods.direct.description")}
           </Text>
         </View>
-      </Pressable>
+      </PressHighlight>
 
       {isElectronRuntime() ? (
-        <Pressable
+        <PressHighlight
           style={styles.option}
           onPress={handleRemoteSsh}
           accessibilityRole="button"
@@ -115,11 +116,11 @@ export function AddHostMethodModal({
               {t("pairing.connectionMethods.remoteSsh.description")}
             </Text>
           </View>
-        </Pressable>
+        </PressHighlight>
       ) : null}
 
       {isNative && !isFdroidBuild ? (
-        <Pressable
+        <PressHighlight
           style={styles.option}
           onPress={handleScan}
           accessibilityRole="button"
@@ -132,10 +133,10 @@ export function AddHostMethodModal({
               {t("pairing.connectionMethods.scanQr.description")}
             </Text>
           </View>
-        </Pressable>
+        </PressHighlight>
       ) : null}
 
-      <Pressable
+      <PressHighlight
         style={styles.option}
         onPress={handlePaste}
         accessibilityRole="button"
@@ -149,7 +150,7 @@ export function AddHostMethodModal({
             {t("pairing.connectionMethods.pasteLink.description")}
           </Text>
         </View>
-      </Pressable>
+      </PressHighlight>
     </AdaptiveModalSheet>
   );
 }
diff --git a/packages/app/src/components/add-host-modal.tsx b/packages/app/src/hosts/add-host/internal/add-host-modal.tsx
similarity index 87%
rename from packages/app/src/components/add-host-modal.tsx
rename to packages/app/src/hosts/add-host/internal/add-host-modal.tsx
index 653d69c4f1..5379e5f4bd 100644
--- a/packages/app/src/components/add-host-modal.tsx
+++ b/packages/app/src/hosts/add-host/internal/add-host-modal.tsx
@@ -1,20 +1,22 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo, useReducer, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Alert, Pressable, Text, View } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { Alert, Text, View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { Check, ChevronDown, ChevronRight, Eye, EyeOff, Link2 } from "lucide-react-native";
 import type { HostProfile } from "@/types/host-connection";
 import { useHosts, useHostMutations } from "@/runtime/host-runtime";
+import { parseConnectionUri, serializeConnectionUri } from "@/utils/daemon-endpoints";
+import { buildConnectionFailureCopy } from "@/components/connection-failure-copy";
 import {
-  parseConnectionUri,
-  serializeConnectionUri,
-  serializeConnectionUriForStorage,
-} from "@/utils/daemon-endpoints";
-import { buildConnectionFailureCopy } from "./connection-failure-copy";
-import { AdaptiveModalSheet, AdaptiveTextInput, type SheetHeader } from "./adaptive-modal-sheet";
+  AdaptiveModalSheet,
+  AdaptiveTextInput,
+  type SheetHeader,
+} from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
-import { PairingTargetTracker } from "./pair-link-credentials";
+import { PairingTargetTracker } from "@/components/pair-link-credentials";
+import { buildDirectConnectionUri } from "@/components/direct-connection-host";
 
 const FLEX_ONE_STYLE = { flex: 1 } as const;
 
@@ -139,37 +141,11 @@ const styles = StyleSheet.create((theme) => ({
   },
 }));
 
-function isIpv6Host(host: string): boolean {
-  return host.includes(":") && !host.startsWith("[") && !host.endsWith("]");
-}
-
-function buildConnectionUriFromDraft(
-  draft: DirectConnectionDraft,
-  labels: DirectConnectionLabels,
-): string {
-  const host = draft.host.trim();
-  const port = Number(draft.port.trim());
-  if (!host) {
-    throw new Error(labels.hostRequired);
-  }
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new Error(labels.invalidPort);
-  }
-
-  return serializeConnectionUriForStorage({
-    host,
-    port,
-    isIpv6: isIpv6Host(host),
-    useTls: draft.useTls,
-    ...(draft.password ? { password: draft.password } : {}),
-  });
-}
-
 function prepareDirectConnection(
   draft: DirectConnectionDraft,
   labels: DirectConnectionLabels,
 ): PreparedDirectConnection {
-  const parsed = parseConnectionUri(buildConnectionUriFromDraft(draft, labels));
+  const parsed = parseConnectionUri(buildDirectConnectionUri(draft, labels));
   const endpoint = parsed.isIpv6
     ? `[${parsed.host}]:${parsed.port}`
     : `${parsed.host}:${parsed.port}`;
@@ -217,7 +193,6 @@ export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostMod
 }
 
 function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostModalProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
   const { probeAndUpsertDirectConnection, beginLinkPairing } = useHostMutations();
@@ -236,10 +211,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
   const [inputResetKey, bumpInputResetKey] = useReducer((key: number) => key + 1, 0);
   const advancedTarget = useRef(new PairingTargetTracker("", true));
 
-  const connectIcon = useMemo(
-    () => <Link2 size={16} color={theme.colors.accentForeground} />,
-    [theme.colors.accentForeground],
-  );
+  const connectIcon = useMemo(() => <ThemedLink2 size={16} />, []);
   const hostFieldStyle = useMemo(() => [styles.field, styles.hostField], []);
   const portFieldStyle = useMemo(() => [styles.field, styles.portField], []);
   const checkboxStyle = useMemo(
@@ -420,7 +392,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
       advancedTarget.current = new PairingTargetTracker("", true);
       try {
         setAdvancedUri(
-          buildConnectionUriFromDraft({ host, port, useTls, password }, directConnectionLabels),
+          buildDirectConnectionUri({ host, port, useTls, password }, directConnectionLabels),
         );
       } catch {
         setAdvancedUri("");
@@ -444,8 +416,8 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
     setIsAdvancedOpen(false);
   }, [advancedUri, directConnectionLabels, host, isAdvancedOpen, password, port, useTls]);
 
-  const AdvancedIcon = isAdvancedOpen ? ChevronDown : ChevronRight;
-  const PasswordIcon = isPasswordVisible ? EyeOff : Eye;
+  const AdvancedIcon = isAdvancedOpen ? ThemedChevronDown : ThemedChevronRight;
+  const PasswordIcon = isPasswordVisible ? ThemedEyeOff : ThemedEye;
 
   return (
     <AdaptiveModalSheet
@@ -459,7 +431,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
       <View style={styles.portRow}>
         <View style={hostFieldStyle}>
           <Text style={styles.label}>{t("pairing.direct.fields.host")}</Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-host-input"
             nativeID="direct-host-input"
             accessibilityLabel={t("pairing.direct.fields.host")}
@@ -467,7 +439,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-host-${inputResetKey}`}
             onChangeText={setHost}
             placeholder="localhost"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -478,7 +449,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
         </View>
         <View style={portFieldStyle}>
           <Text style={styles.label}>{t("pairing.direct.fields.port")}</Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-port-input"
             nativeID="direct-port-input"
             accessibilityLabel={t("pairing.direct.fields.port")}
@@ -486,7 +457,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-port-${inputResetKey}`}
             onChangeText={setPort}
             placeholder="6767"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -498,29 +468,30 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
         </View>
       </View>
 
-      <Pressable
+      <PressHighlight
         style={styles.checkboxRow}
         onPress={handleToggleUseTls}
         disabled={isSaving}
         accessibilityRole="checkbox"
         accessibilityLabel={t("pairing.direct.fields.useSsl")}
         accessibilityState={useTlsAccessibilityState}
+        aria-checked={useTls}
         testID="direct-ssl-toggle"
       >
         <View style={checkboxStyle}>
           {useTls ? (
             <View testID="direct-ssl-toggle-checked">
-              <Check size={14} color={theme.colors.accentForeground} />
+              <ThemedCheck size={14} />
             </View>
           ) : null}
         </View>
         <Text style={styles.label}>{t("pairing.direct.fields.useSsl")}</Text>
-      </Pressable>
+      </PressHighlight>
 
       <View style={styles.field}>
         <Text style={styles.label}>{t("pairing.direct.fields.password")}</Text>
         <View style={styles.passwordRow}>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-password-input"
             nativeID="direct-password-input"
             accessibilityLabel={t("pairing.direct.fields.password")}
@@ -528,7 +499,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-password-${inputResetKey}`}
             onChangeText={setPassword}
             placeholder={t("pairing.direct.fields.optional")}
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={passwordInputStyle}
             autoCapitalize="none"
             autoCorrect={false}
@@ -537,7 +507,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             returnKeyType="done"
             onSubmitEditing={handleSubmitEditing}
           />
-          <Pressable
+          <PressHighlight
             style={styles.iconButton}
             onPress={handleTogglePasswordVisibility}
             disabled={isSaving}
@@ -549,13 +519,13 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             }
             testID="direct-password-visibility-toggle"
           >
-            <PasswordIcon size={18} color={theme.colors.foregroundMuted} />
-          </Pressable>
+            <PasswordIcon size={18} />
+          </PressHighlight>
         </View>
       </View>
 
       <View style={styles.field}>
-        <Pressable
+        <PressHighlight
           style={styles.advancedToggle}
           onPress={handleToggleAdvanced}
           disabled={isSaving}
@@ -565,11 +535,11 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
           }
           testID="direct-host-advanced-toggle"
         >
-          <AdvancedIcon size={16} color={theme.colors.foregroundMuted} />
+          <AdvancedIcon size={16} />
           <Text style={styles.advancedText}>{t("pairing.direct.advanced.label")}</Text>
-        </Pressable>
+        </PressHighlight>
         {isAdvancedOpen ? (
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-host-uri-input"
             nativeID="direct-host-uri-input"
             accessibilityLabel={t("pairing.direct.fields.connectionUri")}
@@ -577,7 +547,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-host-uri-${inputResetKey}`}
             onChangeText={handleChangeAdvancedUri}
             placeholder="tcp://localhost:6767?ssl=true"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -613,3 +582,23 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
     </AdaptiveModalSheet>
   );
 }
+
+const ThemedLink2 = withUnistyles(Link2, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedCheck = withUnistyles(Check, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedChevronDown = withUnistyles(ChevronDown, (theme) => ({
+  color: theme.colors.foregroundMuted,
+}));
+
+const ThemedChevronRight = withUnistyles(ChevronRight, (theme) => ({
+  color: theme.colors.foregroundMuted,
+}));
+
+const ThemedEye = withUnistyles(Eye, (theme) => ({ color: theme.colors.foregroundMuted }));
+
+const ThemedEyeOff = withUnistyles(EyeOff, (theme) => ({ color: theme.colors.foregroundMuted }));
+
+const ThemedAdaptiveTextInput = withUnistyles(AdaptiveTextInput, (theme) => ({
+  placeholderTextColor: theme.colors.foregroundMuted,
+}));
diff --git a/packages/app/src/components/add-remote-ssh-host-modal.tsx b/packages/app/src/hosts/add-host/internal/add-remote-ssh-host-modal.tsx
similarity index 91%
rename from packages/app/src/components/add-remote-ssh-host-modal.tsx
rename to packages/app/src/hosts/add-host/internal/add-remote-ssh-host-modal.tsx
index c7e25bce64..f8d1908cf1 100644
--- a/packages/app/src/components/add-remote-ssh-host-modal.tsx
+++ b/packages/app/src/hosts/add-host/internal/add-remote-ssh-host-modal.tsx
@@ -1,7 +1,7 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import {
-  Pressable,
   Text,
   View,
   type PressableStateCallbackType,
@@ -21,9 +21,8 @@ import {
   resolveControlInteractionStyles,
 } from "@/components/ui/control-geometry";
 import type { EditingTextInputHandle } from "@/components/ui/text-input";
-import { useIsCompactFormFactor } from "@/constants/layout";
 import { DaemonConnectionTestError } from "@/utils/test-daemon-connection";
-import { AdaptiveModalSheet, type SheetHeader } from "./adaptive-modal-sheet";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 
 const FLEX_ONE_STYLE = { flex: 1 } as const;
 const ThemedTerminal = withUnistyles(Terminal);
@@ -49,18 +48,10 @@ const styles = StyleSheet.create((theme) => {
       minWidth: 0,
     },
     // Boxed adornment next to the field: same height and radius as the field
-    // chrome of the active form size, and the shared interaction phases.
-    iconButtonSm: {
-      minHeight: CONTROL_HEIGHTS.compact,
-      width: CONTROL_HEIGHTS.compact,
-      alignItems: "center",
-      justifyContent: "center",
-      borderRadius: theme.borderRadius.md,
-      backgroundColor: theme.colors.surface2,
-    },
-    iconButtonMd: {
-      minHeight: CONTROL_HEIGHTS.field,
-      width: CONTROL_HEIGHTS.field,
+    // chrome, and the shared interaction phases.
+    iconButton: {
+      minHeight: CONTROL_HEIGHTS.md,
+      width: CONTROL_HEIGHTS.md,
       alignItems: "center",
       justifyContent: "center",
       borderRadius: theme.borderRadius.lg,
@@ -106,7 +97,6 @@ export function AddRemoteSshHostModal({
 }: AddRemoteSshHostModalProps) {
   const { t } = useTranslation();
   const hosts = useHosts();
-  const isCompact = useIsCompactFormFactor();
   const { probeAndUpsertRemoteSshConnection } = useHostMutations();
   const targetRef = useRef("");
   const passwordRef = useRef("");
@@ -174,11 +164,11 @@ export function AddRemoteSshHostModal({
     }
 
     clear();
-    onClose();
     onSaved?.({
       ...result,
       isNewHost: !hosts.some((profile) => profile.serverId === result.serverId),
     });
+    onClose();
   }, [clear, hosts, isSaving, onClose, onSaved, probeAndUpsertRemoteSshConnection, t]);
   const handleTargetChange = useCallback((value: string) => {
     targetRef.current = value;
@@ -193,7 +183,7 @@ export function AddRemoteSshHostModal({
     (
       state: PressableStateCallbackType & { hovered?: boolean; focused?: boolean },
     ): StyleProp<ViewStyle> => [
-      isCompact ? styles.iconButtonMd : styles.iconButtonSm,
+      styles.iconButton,
       resolveControlInteractionStyles(
         {
           controlRest: styles.controlRest,
@@ -209,7 +199,7 @@ export function AddRemoteSshHostModal({
         },
       ),
     ],
-    [isCompact, isSaving],
+    [isSaving],
   );
   const handleSubmit = useCallback(() => void handleSave(), [handleSave]);
 
@@ -228,7 +218,6 @@ export function AddRemoteSshHostModal({
       >
         <FormTextInput
           ref={inputRef}
-          size={isCompact ? "md" : "sm"}
           testID="remote-ssh-target-input"
           accessibilityLabel={t("pairing.remoteSsh.fields.target")}
           initialValue=""
@@ -246,7 +235,6 @@ export function AddRemoteSshHostModal({
           <View style={styles.passwordInputWrap}>
             <FormTextInput
               ref={passwordInputRef}
-              size={isCompact ? "md" : "sm"}
               testID="remote-ssh-password-input"
               accessibilityLabel={t("pairing.remoteSsh.fields.password")}
               initialValue=""
@@ -260,7 +248,7 @@ export function AddRemoteSshHostModal({
               onSubmitEditing={handleSubmit}
             />
           </View>
-          <Pressable
+          <PressHighlight
             style={iconButtonStyle}
             onPress={handleTogglePasswordVisibility}
             disabled={isSaving}
@@ -273,7 +261,7 @@ export function AddRemoteSshHostModal({
             testID="remote-ssh-password-visibility-toggle"
           >
             {isPasswordVisible ? <ThemedEyeOff size={18} /> : <ThemedEye size={18} />}
-          </Pressable>
+          </PressHighlight>
         </View>
       </Field>
       <View style={styles.actions}>
diff --git a/packages/app/src/hosts/add-host/internal/model.test.ts b/packages/app/src/hosts/add-host/internal/model.test.ts
new file mode 100644
index 0000000000..a878a5b41d
--- /dev/null
+++ b/packages/app/src/hosts/add-host/internal/model.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { createAddHostFlow } from "./model";
+
+describe("add host flow", () => {
+  it("closes before notifying the consumer and ignores duplicate completion", () => {
+    const flow = createAddHostFlow();
+    const added: string[] = [];
+    flow.open({
+      onAdded: (serverId) => {
+        expect(flow.store.getState().session).toBeNull();
+        added.push(serverId);
+      },
+    });
+    const session = flow.store.getState().session!;
+    session.choose("direct");
+    session.complete({ serverId: "new-host" });
+    session.complete({ serverId: "new-host" });
+    expect(added).toEqual(["new-host"]);
+  });
+
+  it("cancels without a success action and accepts a fresh request", () => {
+    const flow = createAddHostFlow();
+    const added: string[] = [];
+    flow.open({ onAdded: (id) => added.push(id) });
+    const cancelled = flow.store.getState().session!;
+    cancelled.choose("scan");
+    cancelled.close();
+    expect(flow.store.getState().session).toBeNull();
+    flow.open({ method: "link" });
+    const current = flow.store.getState().session!;
+    cancelled.complete({ serverId: "late-result" });
+    cancelled.close();
+    expect(flow.store.getState().session).toBe(current);
+    expect(current.step.getState()).toEqual({ method: "link" });
+    expect(added).toEqual([]);
+    current.complete({ serverId: "new-host" });
+    expect(flow.store.getState().session).toBeNull();
+  });
+
+  it("returns to method selection within the same request", () => {
+    const flow = createAddHostFlow();
+    flow.open();
+    const session = flow.store.getState().session!;
+    session.choose("ssh");
+    session.choose(null);
+    expect(flow.store.getState().session).toBe(session);
+    expect(session.step.getState()).toEqual({ method: null });
+  });
+});
diff --git a/packages/app/src/hosts/add-host/internal/model.ts b/packages/app/src/hosts/add-host/internal/model.ts
new file mode 100644
index 0000000000..614d9dddc0
--- /dev/null
+++ b/packages/app/src/hosts/add-host/internal/model.ts
@@ -0,0 +1,47 @@
+import { createStore, type StoreApi } from "zustand/vanilla";
+
+export type AddHostMethod = "direct" | "ssh" | "link" | "scan";
+export interface AddHostOptions {
+  method?: AddHostMethod;
+  onAdded?: (serverId: string) => void;
+}
+
+export interface AddHostSession {
+  id: number;
+  step: StoreApi<{ method: AddHostMethod | null }>;
+  choose(method: AddHostMethod | null): void;
+  close(): void;
+  complete(result: { serverId: string }): void;
+}
+
+export function createAddHostFlow() {
+  const store = createStore<{ session: AddHostSession | null }>(() => ({ session: null }));
+  let nextId = 0;
+  function createSession(options: AddHostOptions) {
+    const step = createStore<{ method: AddHostMethod | null }>(() => ({
+      method: options.method ?? null,
+    }));
+    const session = {
+      id: ++nextId,
+      step,
+      choose(method: AddHostMethod | null) {
+        step.setState({ method });
+      },
+      close() {
+        if (store.getState().session === session) store.setState({ session: null });
+      },
+      complete({ serverId }: { serverId: string }) {
+        if (store.getState().session !== session) return;
+        session.close();
+        options.onAdded?.(serverId);
+      },
+    };
+    return session;
+  }
+  return {
+    store,
+    open(options: AddHostOptions = {}) {
+      store.setState({ session: createSession(options) });
+    },
+  };
+}
diff --git a/packages/app/src/components/pair-link-modal.tsx b/packages/app/src/hosts/add-host/internal/pair-link-modal.tsx
similarity index 92%
rename from packages/app/src/components/pair-link-modal.tsx
rename to packages/app/src/hosts/add-host/internal/pair-link-modal.tsx
index 8ed9cefba9..f817bdc5cf 100644
--- a/packages/app/src/components/pair-link-modal.tsx
+++ b/packages/app/src/hosts/add-host/internal/pair-link-modal.tsx
@@ -1,16 +1,20 @@
 import { useCallback, useMemo, useReducer, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Alert, Text, View } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { Link } from "lucide-react-native";
 import type { HostProfile } from "@/types/host-connection";
 import { useHosts, useHostMutations, type PasswordRequiredPairing } from "@/runtime/host-runtime";
 import { parseRelayConnectionUri } from "@/utils/daemon-endpoints";
 import { parseConnectionOfferFromUrl } from "@getpaseo/protocol/connection-offer";
-import { AdaptiveModalSheet, AdaptiveTextInput, type SheetHeader } from "./adaptive-modal-sheet";
+import {
+  AdaptiveModalSheet,
+  AdaptiveTextInput,
+  type SheetHeader,
+} from "@/components/adaptive-modal-sheet";
 import { getConnectionAuthFailureReason } from "@/utils/test-daemon-connection";
-import { PairingTargetTracker } from "./pair-link-credentials";
+import { PairingTargetTracker } from "@/components/pair-link-credentials";
 import { Button } from "@/components/ui/button";
 import type { EditingTextInputHandle } from "@/components/ui/text-input";
 
@@ -100,7 +104,6 @@ function PairLinkModalContent({
   onCancel,
   onSaved,
 }: PairLinkModalProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
   const { beginLinkPairing } = useHostMutations();
@@ -126,10 +129,7 @@ function PairLinkModalContent({
     resetPasswordInput();
   }, []);
 
-  const pairIcon = useMemo(
-    () => <Link size={16} color={theme.colors.accentForeground} />,
-    [theme.colors.accentForeground],
-  );
+  const pairIcon = useMemo(() => <ThemedLink size={16} />, []);
 
   const handleClose = useCallback(() => {
     if (isSaving) return;
@@ -212,7 +212,7 @@ function PairLinkModalContent({
 
       <View style={styles.field}>
         <Text style={styles.label}>{t("pairing.link.label")}</Text>
-        <AdaptiveTextInput
+        <ThemedAdaptiveTextInput
           ref={inputRef}
           initialValue={initialUrl}
           testID="pair-link-input"
@@ -220,7 +220,6 @@ function PairLinkModalContent({
           accessibilityLabel={t("pairing.link.label")}
           onChangeText={handleChangeOfferUrl}
           placeholder="https://app.paseo.sh/#offer=..."
-          placeholderTextColor={theme.colors.foregroundMuted}
           style={styles.input}
           autoFocus
           autoCapitalize="none"
@@ -235,7 +234,7 @@ function PairLinkModalContent({
           <Text style={styles.label}>
             {t("pairing.hostPassword.title", { host: parsedHostLabel(offerUrlRef.current) })}
           </Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="pair-link-password-input"
             resetKey={`pair-link-password-${passwordResetKey}`}
             accessibilityLabel={t("pairing.hostPassword.label")}
@@ -274,3 +273,9 @@ function PairLinkModalContent({
     </AdaptiveModalSheet>
   );
 }
+
+const ThemedLink = withUnistyles(Link, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedAdaptiveTextInput = withUnistyles(AdaptiveTextInput, (theme) => ({
+  placeholderTextColor: theme.colors.foregroundMuted,
+}));
diff --git a/packages/app/src/hosts/pair-scan-model.test.ts b/packages/app/src/hosts/add-host/internal/pair-scan-model.test.ts
similarity index 100%
rename from packages/app/src/hosts/pair-scan-model.test.ts
rename to packages/app/src/hosts/add-host/internal/pair-scan-model.test.ts
diff --git a/packages/app/src/hosts/pair-scan-model.ts b/packages/app/src/hosts/add-host/internal/pair-scan-model.ts
similarity index 100%
rename from packages/app/src/hosts/pair-scan-model.ts
rename to packages/app/src/hosts/add-host/internal/pair-scan-model.ts
diff --git a/packages/app/src/app/pair-scan.tsx b/packages/app/src/hosts/add-host/internal/scan.tsx
similarity index 71%
rename from packages/app/src/app/pair-scan.tsx
rename to packages/app/src/hosts/add-host/internal/scan.tsx
index 5d352140ee..1d96e326df 100644
--- a/packages/app/src/app/pair-scan.tsx
+++ b/packages/app/src/hosts/add-host/internal/scan.tsx
@@ -1,17 +1,14 @@
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
-import { Pressable, Text, View } from "react-native";
-import { useLocalSearchParams, useRouter, type Href } from "expo-router";
+import { Text, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet } from "react-native-unistyles";
 import { CameraView, useCameraPermissions } from "expo-camera";
 import type { BarcodeScanningResult, BarcodeSettings } from "expo-camera";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
-import { openPairScan } from "@/hosts/pair-scan-model";
-import { buildHostRootRoute, buildSettingsHostRoute } from "@/utils/host-routes";
+import { openPairScan } from "./pair-scan-model";
 import { isWeb } from "@/constants/platform";
-import { BackHeader } from "@/components/headers/back-header";
-import { PairLinkModal } from "@/components/pair-link-modal";
+import { PairLinkModal } from "./pair-link-modal";
 import { Button } from "@/components/ui/button";
 
 const styles = StyleSheet.create((theme) => ({
@@ -113,50 +110,26 @@ const styles = StyleSheet.create((theme) => ({
   },
 }));
 
-export default function PairScanScreen() {
-  const { theme } = useUnistyles();
+export function PairScanContent({
+  onConnected,
+  onClose,
+}: {
+  onConnected: (serverId: string) => void;
+  onClose: () => void;
+}) {
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
-  const router = useRouter();
-  const params = useLocalSearchParams<{
-    source?: string;
-  }>();
-  const source = typeof params.source === "string" ? params.source : "settings";
-
   const [permission, requestPermission] = useCameraPermissions();
 
-  const navigateToPairedHost = useCallback(
-    (serverId: string) => {
-      if (source === "onboarding") {
-        router.replace(buildHostRootRoute(serverId));
-        return;
-      }
-      router.replace(buildSettingsHostRoute(serverId));
-    },
-    [router, source],
-  );
-
   const [scan] = useState(() =>
     openPairScan({
-      importConnectionLink: (link) =>
-        getHostRuntimeStore().importConnectionLink(
-          link,
-          source === "onboarding" ? "hostRoot" : "hostSettings",
-        ),
-      onConnected: navigateToPairedHost,
+      importConnectionLink: (link) => getHostRuntimeStore().importConnectionLink(link, "hostRoot"),
+      onConnected,
     }),
   );
   const scanState = useSyncExternalStore(scan.subscribe, scan.getState, scan.getState);
   useEffect(() => () => scan.close(), [scan]);
 
-  const closeToSource = useCallback(() => {
-    try {
-      router.back();
-    } catch {
-      router.replace("/" as Href);
-    }
-  }, [router]);
-
   useEffect(() => {
     if (isWeb) return;
     if (permission && permission.granted) return;
@@ -169,35 +142,29 @@ export default function PairScanScreen() {
     [scan],
   );
 
-  const handleRouterBack = useCallback(() => router.back(), [router]);
   const savePasswordPairing = useCallback(
-    ({ serverId }: { serverId: string }) => navigateToPairedHost(serverId),
-    [navigateToPairedHost],
+    ({ serverId }: { serverId: string }) => onConnected(serverId),
+    [onConnected],
   );
   const handleRequestPermission = useCallback(() => {
     void requestPermission();
   }, [requestPermission]);
 
   const bodyStyle = useMemo(
-    () => [styles.body, { paddingBottom: insets.bottom + theme.spacing[6] }],
-    [insets.bottom, theme.spacing],
-  );
-  const helperTextStyle = useMemo(
-    () => [styles.helperText, { color: theme.colors.foreground }],
-    [theme.colors.foreground],
+    () => [styles.body, { paddingBottom: insets.bottom + 24 }],
+    [insets.bottom],
   );
 
   if (isWeb) {
     return (
       <View style={styles.container}>
-        <BackHeader title={t("pairing.scan.title")} onBack={handleRouterBack} />
         <View style={bodyStyle}>
           <View style={styles.permissionCard}>
             <Text style={styles.permissionTitle}>{t("pairing.scan.webUnavailableTitle")}</Text>
             <Text style={styles.permissionBody}>{t("pairing.scan.webUnavailableBody")}</Text>
-            <Pressable style={styles.permissionButton} onPress={closeToSource}>
-              <Text style={styles.permissionButtonText}>{t("pairing.scan.backToSettings")}</Text>
-            </Pressable>
+            <Button style={styles.permissionButton} onPress={onClose}>
+              <Text style={styles.permissionButtonText}>{t("common.actions.back")}</Text>
+            </Button>
           </View>
         </View>
       </View>
@@ -208,16 +175,14 @@ export default function PairScanScreen() {
 
   return (
     <View style={styles.container}>
-      <BackHeader title={t("pairing.scan.title")} onBack={closeToSource} />
-
       <View style={bodyStyle}>
         {!granted ? (
           <View style={styles.permissionCard}>
             <Text style={styles.permissionTitle}>{t("pairing.scan.cameraPermissionTitle")}</Text>
             <Text style={styles.permissionBody}>{t("pairing.scan.cameraPermissionBody")}</Text>
-            <Pressable style={styles.permissionButton} onPress={handleRequestPermission}>
+            <Button style={styles.permissionButton} onPress={handleRequestPermission}>
               <Text style={styles.permissionButtonText}>{t("pairing.scan.grantPermission")}</Text>
-            </Pressable>
+            </Button>
           </View>
         ) : (
           <View style={styles.cameraWrap}>
@@ -235,10 +200,10 @@ export default function PairScanScreen() {
                 <View style={[styles.corner, styles.cornerBR]} />
               </View>
               {scanState.status === "pairing" ? (
-                <Text style={helperTextStyle}>{t("pairing.scan.pairing")}</Text>
+                <Text style={styles.helperText}>{t("pairing.scan.pairing")}</Text>
               ) : null}
               {scanState.status === "stopped" && scanState.error ? (
-                <Text style={helperTextStyle}>{scanState.error}</Text>
+                <Text style={styles.helperText}>{scanState.error}</Text>
               ) : null}
               {scanState.status === "stopped" ? (
                 <Button
diff --git a/packages/app/src/hosts/host-chooser.tsx b/packages/app/src/hosts/host-chooser.tsx
index 3d807ba3a1..eb6fdea5a0 100644
--- a/packages/app/src/hosts/host-chooser.tsx
+++ b/packages/app/src/hosts/host-chooser.tsx
@@ -1,26 +1,21 @@
+import { useOverlayRegistration, type KeyboardInputEvent } from "@/keyboard";
+import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
-import { usePanelStore } from "@/stores/panel-store";
 import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Pressable, ScrollView, Text, View, type PressableStateCallbackType } from "react-native";
 import {
   EditingTextInput as TextInput,
   type EditingTextInputHandle,
 } from "@/components/ui/text-input";
-import { router } from "expo-router";
 import { Server } from "lucide-react-native";
 import { create } from "zustand";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { HostStatusDotSlot } from "@/components/hosts/host-picker";
 import { isWeb } from "@/constants/platform";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
-import {
-  OverlayLayerProvider,
-  useGlobalWebOverlayLayer,
-  useWebOverlayRegistration,
-} from "@/lib/overlay-root";
+import { OverlayLayerProvider, useGlobalOverlayLayer } from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import { orderHostsLocalFirst, type HostProfile } from "@/types/host-connection";
-import { buildSettingsAddHostRoute } from "@/utils/host-routes";
 
 type HostFilter = (host: HostProfile) => boolean;
 type HostChoiceHandler = (serverId: string) => void | Promise<void>;
@@ -65,6 +60,7 @@ function matchesHostQuery(host: HostProfile, query: string): boolean {
 }
 
 export function useHostChooser() {
+  const addHost = useAddHost();
   const hosts = useHosts();
   const localServerId = useLocalDaemonServerId();
   const open = useHostChooserStore((state) => state.open);
@@ -76,13 +72,7 @@ export function useHostChooser() {
       );
 
       if (availableHosts.length === 0) {
-        (
-          input.onNoHosts ??
-          (() => {
-            usePanelStore.getState().showMobileAgent();
-            router.push(buildSettingsAddHostRoute(Date.now()));
-          })
-        )();
+        (input.onNoHosts ?? addHost)();
         return false;
       }
 
@@ -98,7 +88,7 @@ export function useHostChooser() {
       });
       return true;
     },
-    [hosts, localServerId, open],
+    [hosts, localServerId, open, addHost],
   );
 }
 
@@ -152,7 +142,7 @@ export function HostChooserModal() {
   const inputRef = useRef<EditingTextInputHandle>(null);
   const [query, setQuery] = useState("");
   const [activeIndex, setActiveIndex] = useState(0);
-  const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && request != null);
+  const modalLayer = useGlobalOverlayLayer("modal", request != null);
 
   const requestHosts = useMemo(() => {
     if (!request) return [];
@@ -193,8 +183,8 @@ export function HostChooserModal() {
     [close, request],
   );
 
-  const handleWebOverlayKeyDown = useCallback(
-    (event: KeyboardEvent) => {
+  const handleOverlayKeyDown = useCallback(
+    (event: KeyboardInputEvent) => {
       if (
         event.key !== "ArrowDown" &&
         event.key !== "ArrowUp" &&
@@ -234,51 +224,56 @@ export function HostChooserModal() {
     },
     [activeOptionIndex, chooseHost, close, options],
   );
-  const setWebOverlayScope = useWebOverlayRegistration({
-    active: isWeb && request != null,
+  const setOverlayScope = useOverlayRegistration({
+    keys: ["Escape", "Enter", "ArrowUp", "ArrowDown"],
+    active: request != null,
     layer: modalLayer,
-    onKeyDown: handleWebOverlayKeyDown,
+    onKeyDown: handleOverlayKeyDown,
   });
 
   if (!request) return null;
 
   const modal = (
     <Modal visible transparent animationType="fade" onRequestClose={close} testID="host-chooser">
-      <View style={styles.overlay}>
-        <Pressable style={styles.backdrop} onPress={close} />
-        <View ref={setWebOverlayScope} style={styles.panel}>
-          <View style={styles.header}>
-            <Text style={styles.title}>{request.title}</Text>
-            <TextInput
-              ref={inputRef}
-              initialValue={query}
-              onChangeText={handleQueryChange}
-              placeholder="Search hosts..."
-              placeholderTextColor={theme.colors.foregroundMuted}
-              style={styles.input}
-              autoCapitalize="none"
-              autoCorrect={false}
-              testID="host-chooser-search"
-            />
-          </View>
-          <ScrollView
-            style={styles.results}
-            contentContainerStyle={styles.resultsContent}
-            keyboardShouldPersistTaps="always"
-            showsVerticalScrollIndicator={false}
-          >
-            {options.length === 0 ? <Text style={styles.emptyText}>No matching hosts</Text> : null}
-            {options.map((host, index) => (
-              <HostChooserRow
-                key={host.serverId}
-                host={host}
-                active={index === activeOptionIndex}
-                onChooseHost={chooseHost}
+      <OverlayLayerProvider layer={modalLayer}>
+        <View style={styles.overlay}>
+          <Pressable style={styles.backdrop} onPress={close} />
+          <View ref={setOverlayScope} style={styles.panel}>
+            <View style={styles.header}>
+              <Text style={styles.title}>{request.title}</Text>
+              <TextInput
+                ref={inputRef}
+                initialValue={query}
+                onChangeText={handleQueryChange}
+                placeholder="Search hosts..."
+                placeholderTextColor={theme.colors.foregroundMuted}
+                style={styles.input}
+                autoCapitalize="none"
+                autoCorrect={false}
+                testID="host-chooser-search"
               />
-            ))}
-          </ScrollView>
+            </View>
+            <ScrollView
+              style={styles.results}
+              contentContainerStyle={styles.resultsContent}
+              keyboardShouldPersistTaps="always"
+              showsVerticalScrollIndicator={false}
+            >
+              {options.length === 0 ? (
+                <Text style={styles.emptyText}>No matching hosts</Text>
+              ) : null}
+              {options.map((host, index) => (
+                <HostChooserRow
+                  key={host.serverId}
+                  host={host}
+                  active={index === activeOptionIndex}
+                  onChooseHost={chooseHost}
+                />
+              ))}
+            </ScrollView>
+          </View>
         </View>
-      </View>
+      </OverlayLayerProvider>
     </Modal>
   );
 
diff --git a/packages/app/src/hosts/host-confirmation-sheet.tsx b/packages/app/src/hosts/host-confirmation-sheet.tsx
index c83be51a30..e59971e392 100644
--- a/packages/app/src/hosts/host-confirmation-sheet.tsx
+++ b/packages/app/src/hosts/host-confirmation-sheet.tsx
@@ -47,7 +47,6 @@ export function HostConfirmationSheet() {
       <View style={styles.confirmActions}>
         <Button
           variant="secondary"
-          size="sm"
           style={FLEX_1_STYLE}
           onPress={cancel}
           testID="host-confirmation-cancel"
@@ -56,7 +55,6 @@ export function HostConfirmationSheet() {
         </Button>
         <Button
           variant="default"
-          size="sm"
           style={FLEX_1_STYLE}
           onPress={connect}
           testID="host-confirmation-connect"
diff --git a/packages/app/src/i18n/resources.test.ts b/packages/app/src/i18n/resources.test.ts
index b73b2c4fec..af4c059fb2 100644
--- a/packages/app/src/i18n/resources.test.ts
+++ b/packages/app/src/i18n/resources.test.ts
@@ -820,7 +820,7 @@ describe("translation resources", () => {
     expect(en.branchSwitcher.stashRestored).toBe("Stashed changes restored");
     expect(en.agentAutocomplete.searchingWorkspace).toBe("Searching workspace...");
     expect(en.agentAutocomplete.noCommands).toBe("No commands found");
-    expect(en.agentAutocomplete.failedToLoad).toBe("Failed to load");
+    expect(en.agentAutocomplete.commandsFailed).toBe("Couldn't load commands");
     expect(en.loadOlderHistory.failed).toBe("Couldn't load older history");
     expect(en.agentControls.thinking.extraHigh).toBe("Extra high");
     expect(en.agentControls.model.unknown).toBe("Unknown model");
diff --git a/packages/app/src/i18n/resources/ar.ts b/packages/app/src/i18n/resources/ar.ts
index 36803d4df7..ccf9f6ecb0 100644
--- a/packages/app/src/i18n/resources/ar.ts
+++ b/packages/app/src/i18n/resources/ar.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const ar: TranslationResources = {
+  pluginCombobox: {
+    searching: "جارٍ البحث…",
+    empty: "لا توجد نتائج",
+    failed: "فشل البحث: {{message}}",
+  },
   paneFind: {
     connectionFailure: "تعذر البحث في هذه المحادثة. تحقق من الاتصال بالمضيف وأعد المحاولة.",
     historyChangedFailure: "تغيّرت المحادثة أثناء البحث. أعد البحث.",
@@ -379,6 +384,24 @@ export const ar: TranslationResources = {
       answerPlaceholder: "اكتب إجابتك...",
       otherPlaceholder: "آخر...",
     },
+    backgroundWork: {
+      pillOne: "مهمة واحدة في الخلفية",
+      pillMany: "{{count}} مهمة في الخلفية",
+      notRunning: "لم يعد قيد التشغيل",
+      dismiss: "إغلاق",
+      stop: "إيقاف",
+      stopping: "جارٍ الإيقاف…",
+      stopError: "تعذر تأكيد الإيقاف.",
+      label: "في الخلفية",
+      title: "عمل الخلفية",
+      waiting: "بانتظار تفاصيل عمل الخلفية",
+      error: "تعذر تحميل عمل الخلفية",
+      retry: "إعادة المحاولة",
+      running: "عمل الخلفية قيد التشغيل",
+      shell: "الصدفة",
+      monitor: "المراقبة",
+      other: "عمل آخر",
+    },
     todo: {
       title: "المهام",
       empty: "لا توجد مهام حتى الآن.",
@@ -932,6 +955,9 @@ export const ar: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "الفرع الأساسي",
+        },
         openChangesTab: "فتح علامة تبويب التغييرات",
         openDiffTab: "فتح علامة تبويب الفرق",
         closeChangesTab: "إغلاق علامة تبويب التغييرات",
@@ -1153,6 +1179,8 @@ export const ar: TranslationResources = {
     title: "ما الجديد",
     installed: "مثبّت",
     showMore: "عرض المزيد",
+    showAllChanges: "عرض كل التغييرات",
+    hideAllChanges: "إخفاء كل التغييرات",
     openWebsite: "سجل التغييرات الكامل",
     error: {
       title: "تعذّر تحميل سجل التغييرات",
@@ -1160,6 +1188,14 @@ export const ar: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "تعذر تحميل عرض الشريط الجانبي.",
+      useDefault: "استخدام العرض الافتراضي",
+      readFailed: "تعذر تحميل تفضيل عرض الشريط الجانبي.",
+      agentUnavailable: "لم يعد الوكيل متاحًا",
+      terminalUnavailable: "لم تعد الطرفية متاحة",
+      projectUnavailable: "لم يعد المشروع متاحًا",
+    },
     statusGroupAccessibility: "مجموعة {{label}}",
     statusBucket: {
       needsInput: "تحتاج إدخالاً",
@@ -1235,6 +1271,7 @@ export const ar: TranslationResources = {
       hosts: "المضيفون",
       settings: "إعدادات",
       closeSidebar: "إغلاق الشريط الجانبي",
+      moreActions: "المزيد من الإجراءات",
     },
     footer: {
       usage: "الاستخدام",
@@ -1339,6 +1376,9 @@ export const ar: TranslationResources = {
         hostDisconnected: "Host غير متصل",
         hideFailed: "فشل في إخفاء مساحة العمل",
         archiveFailed: "فشل في أرشفة مساحة العمل",
+        archived: "تمت أرشفة مساحة العمل",
+        undoArchive: "تراجع",
+        undoArchiveFailed: "تعذّر التراجع عن الأرشفة",
       },
     },
   },
@@ -1543,6 +1583,8 @@ export const ar: TranslationResources = {
       cli: {
         statusFailed: "غير قادر على التحقق من حالة تثبيت CLI.",
         installFailed: "غير قادر على تثبيت PaseoCLI.",
+        uninstallFailed: "تعذر إلغاء تثبيت Paseo CLI.",
+        keptForeign: "تم الإبقاء على أمر paseo لم يثبته Paseo. احذفه بنفسك لإلغاء تثبيته.",
       },
     },
   },
@@ -1594,6 +1636,7 @@ export const ar: TranslationResources = {
     openPath: "فتح المسار",
   },
   branchSwitcher: {
+    failedToLoad: "تعذّر تحميل الفروع. أعد فتح قائمة الفروع للمحاولة مرة أخرى.",
     triggerTooltip: "تبديل فرع مساحة العمل",
     currentBranch: "الفرع الحالي:{{branchName}}. اضغط لتبديل الفرع.",
     placeholder: "تبديل الفرع...",
@@ -1616,7 +1659,11 @@ export const ar: TranslationResources = {
     loadingCommands: "جارٍ تحميل الأوامر...",
     noFiles: "لم يتم العثور على ملفات أو أدلة",
     noCommands: "لم يتم العثور على أي أوامر",
-    failedToLoad: "فشل التحميل",
+    loadingProviderCommands: "جارٍ تحميل أوامر {{provider}}...",
+    commandsFailed: "تعذر تحميل الأوامر",
+    providerCommandsFailed: "تعذر تحميل أوامر {{provider}}",
+    filesFailed: "تعذر البحث في الملفات",
+    skillTag: "مهارة",
     chooseProjectForCommands: "اختر مشروعًا لعرض الأوامر",
     chooseModelForCommands: "اختر نموذجًا لعرض الأوامر",
   },
@@ -1643,6 +1690,60 @@ export const ar: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "الخطوة {{current}} من {{total}}",
+      skip: "تخطي الإعداد",
+      continue: "متابعة",
+      finish: "إنهاء",
+      steps: {
+        appearance: {
+          label: "المظهر",
+          title: "مرحبًا بك في Paseo",
+          description: "لنبدأ باختيار المظهر",
+        },
+        providers: {
+          label: "المزوّدون",
+          title: "وكلاؤك",
+          description: "يشغّل Paseo أدوات CLI للوكلاء المثبتة على هذا الكمبيوتر",
+        },
+        projects: {
+          label: "المشاريع",
+          title: "أضف مشاريعك",
+          description: "أين تريد أن يعمل وكلاؤك",
+          addProject: "إضافة مشروع",
+          added: "تمت الإضافة",
+          suggestions: {
+            loading: "جارٍ البحث عن المجلدات التي عملت فيها",
+            empty: "لم يتم العثور على مشاريع حديثة",
+            lastUsed: "آخر استخدام {{time}}",
+            addSelected_one: "إضافة مشروع واحد ({{count}})",
+            addSelected_other: "إضافة {{count}} مشاريع",
+            adding: "جارٍ الإضافة…",
+            addFailed: "تعذّرت إضافة هذا المجلد",
+          },
+        },
+        orchestration: {
+          label: "التنسيق",
+          title: "اسمح للوكلاء باستخدام Paseo",
+          description: "اسمح لوكلائك بإنشاء مساحات عمل والتحدث مع وكلاء آخرين",
+        },
+        phone: {
+          label: "الجوال",
+          title: "خذ وكلاءك معك",
+          description:
+            "يتيح لك تطبيق الجوال الأصلي كامل الميزات التحكم في أي كمبيوتر يعمل عليه Paseo من هاتفك",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "اختر طريقة الاتصال",
+          connectDocs: "الوثائق",
+          openConnectDocs: "افتح وثائق الاتصال",
+          recommended: "موصى به",
+          relay: { title: "التتابع", hint: "مشفّر من طرف إلى طرف، امسح رمز QR" },
+          tailscale: { title: "Tailscale", hint: "يتطلب بعض الإعداد" },
+        },
+      },
+    },
     title: "مرحبا بكم في Paseo",
     subtitle: "قم بتوصيل جهاز الكمبيوتر الخاص بك للبدء",
     actions: {
@@ -1861,6 +1962,8 @@ export const ar: TranslationResources = {
       notNow: "ليس الآن",
       directConnectionHint:
         "بدون التتابع، اتصل مباشرة عبر TCP أو Tailscale أو شبكة VPN أخرى. لن يتم إنشاء رمز QR.",
+      tailscaleDocs: "إعداد Tailscale",
+      tailscaleDocsAccessibility: "اقرأ كيفية الاتصال عبر Tailscale",
       updateRequired: "حدّث المضيف لتمكين التتابع من Paseo Desktop.",
       unavailable: "عرض الاقتران غير متاح.",
       hint: "قم بمسح رمز QR هذا باستخدام Paseo على هاتفك، أو انسخ الرابط أدناه.",
@@ -2360,6 +2463,11 @@ export const ar: TranslationResources = {
     general: {
       title: "عام",
       sending: "الإرسال",
+      setup: {
+        label: "الإعداد الأولي",
+        description: "أعد المرور على المظهر والمزوّدين والمشاريع وإقران الهاتف",
+        action: "إظهار الإعداد مجددًا",
+      },
       browserData: {
         title: "بيانات المتصفح",
         siteData: "ملفات تعريف الارتباط وبيانات المواقع",
@@ -2516,6 +2624,12 @@ export const ar: TranslationResources = {
         description: "عرض مخطط للتنقل بين المطالبات",
       },
       sidebar: {
+        view: {
+          title: "عرض الشريط الجانبي",
+          label: "العرض",
+          default: "العرض الافتراضي",
+          unavailable: "العرض المحدد غير متاح أو معطل. يتم عرض العرض الافتراضي.",
+        },
         header: {
           title: "الرأس",
           description: "اختر العناصر التي تظهر أعلى الشريط الجانبي وترتيبها",
@@ -2647,11 +2761,7 @@ export const ar: TranslationResources = {
       commandLine: {
         title: "سطر الأوامر",
         description: "وكلاء التحكم والبرنامج النصي من المحطة الطرفية الخاصة بك",
-      },
-      actions: {
-        install: "ثَبَّتَ",
-        installing: "جارٍ التثبيت...",
-        installed: "تم التثبيت",
+        accessibilityLabel: "تثبيت Paseo CLI",
       },
     },
     permissions: {
@@ -2729,10 +2839,9 @@ export const ar: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "مهارات التنسيق",
         title: "مهارات التنسيق",
-        description: "قم بتعليم عملائك كيفية التنسيق من خلال CLI",
+        description: "علّم وكلاءك كيفية استخدام أدوات Paseo",
         updateAvailable: "التحديث متاح",
         updateTitle: "تحديث مهارات Paseo ؟",
-        updateFallback: "مزامنة المهارات المجمعة لجهازك.",
         uninstallTitle: "إلغاء تثبيت مهارات Paseo ؟",
         uninstallMessage: "يزيل جميع مهارات تنسيق Paseo من ~/.agents ، ~/.claude ، ~/.codex.",
         choose: "اختيار المهارات",
@@ -2749,9 +2858,6 @@ export const ar: TranslationResources = {
         uninstallFailed: "غير قادر على إلغاء تثبيت مهارات التنسيق.",
         saveSelectionFailed: "غير قادر على حفظ اختيار مهارات التنسيق.",
         actions: {
-          install: "ثَبَّتَ",
-          installing: "جارٍ التثبيت...",
-          installed: "تم التثبيت",
           update: "تحديث",
           working: "عمل...",
           remove: "إزالة",
@@ -2773,6 +2879,7 @@ export const ar: TranslationResources = {
           title: "تمكين أدوات Paseo",
           hint: "سيتمكن الوكلاء من إدارة أشجار العمل والوكلاء والجداول الزمنية",
           accessibilityLabel: "حقن أدوات Paseo",
+          updateFailed: "تعذر تحديث أدوات Paseo.",
         },
         systemPrompt: {
           title: "موجه النظام",
diff --git a/packages/app/src/i18n/resources/en.ts b/packages/app/src/i18n/resources/en.ts
index d3ca03acbf..37c230e100 100644
--- a/packages/app/src/i18n/resources/en.ts
+++ b/packages/app/src/i18n/resources/en.ts
@@ -1,4 +1,9 @@
 export const en = {
+  pluginCombobox: {
+    searching: "Searching…",
+    empty: "No results",
+    failed: "Search failed: {{message}}",
+  },
   paneFind: {
     connectionFailure: "Could not search this chat. Check the host connection and retry.",
     historyChangedFailure: "The chat changed while searching. Search again.",
@@ -376,6 +381,24 @@ export const en = {
       answerPlaceholder: "Type your answer...",
       otherPlaceholder: "Other...",
     },
+    backgroundWork: {
+      pillOne: "1 background task",
+      pillMany: "{{count}} background tasks",
+      notRunning: "No longer running",
+      dismiss: "Dismiss",
+      stop: "Stop",
+      stopping: "Stopping…",
+      stopError: "Could not confirm stop.",
+      label: "Background",
+      title: "Background work",
+      waiting: "Waiting for background work details",
+      error: "Could not load background work",
+      retry: "Retry",
+      running: "Background work running",
+      shell: "Shell",
+      monitor: "Monitor",
+      other: "Other work",
+    },
     todo: {
       title: "Tasks",
       empty: "No tasks yet.",
@@ -940,6 +963,9 @@ export const en = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Change base",
+        },
         openChangesTab: "Open Changes tab",
         openDiffTab: "Open Diff tab",
         closeChangesTab: "Close Changes tab",
@@ -1161,6 +1187,8 @@ export const en = {
     title: "What's new",
     installed: "Installed",
     showMore: "Show more",
+    showAllChanges: "Show all changes",
+    hideAllChanges: "Hide all changes",
     openWebsite: "Full changelog",
     error: {
       title: "Unable to load the changelog",
@@ -1168,6 +1196,14 @@ export const en = {
     },
   },
   sidebar: {
+    view: {
+      failed: "Sidebar view failed to load.",
+      useDefault: "Use default view",
+      readFailed: "Could not load your sidebar view preference.",
+      agentUnavailable: "Agent is no longer available",
+      terminalUnavailable: "Terminal is no longer available",
+      projectUnavailable: "Project is no longer available",
+    },
     statusGroupAccessibility: "{{label}} group",
     statusBucket: {
       needsInput: "Needs input",
@@ -1243,6 +1279,7 @@ export const en = {
       hosts: "Hosts",
       settings: "Settings",
       closeSidebar: "Close sidebar",
+      moreActions: "More actions",
     },
     footer: {
       usage: "Usage",
@@ -1347,6 +1384,9 @@ export const en = {
         hostDisconnected: "Host is not connected",
         hideFailed: "Failed to hide workspace",
         archiveFailed: "Failed to archive workspace",
+        archived: "Workspace archived",
+        undoArchive: "Undo",
+        undoArchiveFailed: "Couldn't undo the archive",
       },
     },
   },
@@ -1567,6 +1607,9 @@ export const en = {
       cli: {
         statusFailed: "Unable to check CLI install status.",
         installFailed: "Unable to install the Paseo CLI.",
+        uninstallFailed: "Unable to uninstall the Paseo CLI.",
+        keptForeign:
+          "Kept a paseo command that Paseo didn't install. Remove it yourself to uninstall it.",
       },
     },
   },
@@ -1623,6 +1666,7 @@ export const en = {
     placeholder: "Switch branch...",
     searchPlaceholder: "Filter branches...",
     empty: "No branches found.",
+    failedToLoad: "Could not load branches. Reopen the picker to try again.",
     title: "Switch branch",
     uncommittedTitle: "Uncommitted changes",
     uncommittedMessage: "You have uncommitted changes. Stash them before switching branches?",
@@ -1641,7 +1685,11 @@ export const en = {
     loadingCommands: "Loading commands...",
     noFiles: "No files or directories found",
     noCommands: "No commands found",
-    failedToLoad: "Failed to load",
+    loadingProviderCommands: "Loading {{provider}} commands...",
+    commandsFailed: "Couldn't load commands",
+    providerCommandsFailed: "Couldn't load {{provider}} commands",
+    filesFailed: "Couldn't search files",
+    skillTag: "Skill",
     chooseProjectForCommands: "Choose a project to see commands",
     chooseModelForCommands: "Select a model to see commands",
   },
@@ -1668,6 +1716,60 @@ export const en = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "Step {{current}} of {{total}}",
+      skip: "Skip setup",
+      continue: "Continue",
+      finish: "Finish",
+      steps: {
+        appearance: {
+          label: "Appearance",
+          title: "Welcome to Paseo",
+          description: "Let's start by picking a look",
+        },
+        providers: {
+          label: "Providers",
+          title: "Your agents",
+          description: "Paseo runs the agent CLIs already on this computer",
+        },
+        projects: {
+          label: "Projects",
+          title: "Add your projects",
+          description: "Where do you want your agents to work on",
+          addProject: "Add project",
+          added: "Added",
+          suggestions: {
+            loading: "Looking for folders you've worked in",
+            empty: "No recent projects found",
+            lastUsed: "Last used {{time}}",
+            addSelected_one: "Add {{count}} project",
+            addSelected_other: "Add {{count}} projects",
+            adding: "Adding…",
+            addFailed: "Couldn't add this folder",
+          },
+        },
+        orchestration: {
+          label: "Orchestration",
+          title: "Let agents use Paseo",
+          description: "Let your agents create workspaces and talk to other agents",
+        },
+        phone: {
+          label: "Mobile",
+          title: "Take your agents with you",
+          description:
+            "The fully featured native mobile app allows you to control any Paseo computer from your phone",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "Choose how to connect",
+          connectDocs: "Docs",
+          openConnectDocs: "Open connectivity documentation",
+          recommended: "Recommended",
+          relay: { title: "Relay", hint: "End-to-end encrypted, scan a QR code" },
+          tailscale: { title: "Tailscale", hint: "Requires some setup" },
+        },
+      },
+    },
     title: "Welcome to Paseo",
     subtitle: "Connect your computer to get started",
     actions: {
@@ -1886,6 +1988,8 @@ export const en = {
       notNow: "Not now",
       directConnectionHint:
         "Without relay, connect directly over TCP, Tailscale, or another VPN. No QR code is created.",
+      tailscaleDocs: "Set up Tailscale",
+      tailscaleDocsAccessibility: "Read how to connect over Tailscale",
       updateRequired: "Update the host to enable relay from Paseo Desktop.",
       unavailable: "Pairing offer unavailable.",
       hint: "Scan this QR code with Paseo on your phone, or copy the link below.",
@@ -2327,7 +2431,7 @@ export const en = {
       installing: "Installing…",
       logs: {
         action: "Logs",
-        title: "Logs: {{id}}",
+        title: "Logs: {{name}}",
         loading: "Loading logs…",
         refresh: "Refresh",
         refreshing: "Refreshing…",
@@ -2336,7 +2440,8 @@ export const en = {
       },
       status: { running: "running", disabled: "disabled", failed: "failed" },
       actions: {
-        menu: "Actions for {{id}}",
+        menu: "Actions for {{name}}",
+        settings: "Settings",
         reload: "Reload",
         reloading: "Reloading…",
         enable: "Enable",
@@ -2347,16 +2452,16 @@ export const en = {
         removing: "Removing…",
       },
       feedback: {
-        installed: "Installed {{id}}",
-        reload: "Reloaded {{id}}",
-        enable: "Enabled {{id}}",
-        disable: "Disabled {{id}}",
-        remove: "Removed {{id}}",
-        kept: "Kept {{id}}",
+        installed: "Installed {{name}}",
+        reload: "Reloaded {{name}}",
+        enable: "Enabled {{name}}",
+        disable: "Disabled {{name}}",
+        remove: "Removed {{name}}",
+        kept: "Kept {{name}}",
         globalEnabled: "Plugins enabled",
         globalDisabled: "Plugins disabled",
       },
-      removeConfirmTitle: "Remove {{id}}?",
+      removeConfirmTitle: "Remove {{name}}?",
       removeConfirmMessage: "This removes the configuration. The source directory is not deleted.",
       states: {
         offlineTitle: "Plugin host is offline",
@@ -2449,6 +2554,11 @@ export const en = {
     general: {
       title: "General",
       sending: "Sending",
+      setup: {
+        label: "First-run setup",
+        description: "Walk through appearance, providers, projects and phone pairing again",
+        action: "Show setup again",
+      },
       browserData: {
         title: "Browser data",
         siteData: "Cookies and site data",
@@ -2605,6 +2715,12 @@ export const en = {
         description: "Show an outline for jumping between prompts",
       },
       sidebar: {
+        view: {
+          title: "Sidebar view",
+          label: "View",
+          default: "Default view",
+          unavailable: "The selected view is unavailable or disabled. Showing Default view.",
+        },
         header: {
           title: "Header",
           description: "Choose which items appear at the top of the sidebar and in what order",
@@ -2735,11 +2851,7 @@ export const en = {
       commandLine: {
         title: "Command line",
         description: "Control and script agents from your terminal",
-      },
-      actions: {
-        install: "Install",
-        installing: "Installing...",
-        installed: "Installed",
+        accessibilityLabel: "Install the Paseo CLI",
       },
     },
     permissions: {
@@ -2816,7 +2928,7 @@ export const en = {
       skills: {
         sectionTitle: "Orchestration skills",
         title: "Orchestration skills",
-        description: "Teach your agents to orchestrate through the CLI",
+        description: "Teach your agents how to use Paseo tools",
         docs: "Skills",
         openDocs: "Open skills documentation",
         unavailable: "Connect to this host to manage orchestration skills",
@@ -2827,7 +2939,6 @@ export const en = {
         saveSelectionFailed: "Unable to save the orchestration skills selection.",
         updateAvailable: "Update available",
         updateTitle: "Update Paseo skills?",
-        updateFallback: "Sync bundled skills to this host.",
         uninstallTitle: "Uninstall Paseo skills?",
         uninstallMessage:
           "Removes all Paseo orchestration skills from ~/.agents, ~/.claude, ~/.codex on this host.",
@@ -2841,9 +2952,6 @@ export const en = {
           "{{skills}} will be deleted from ~/.agents, ~/.claude, and ~/.codex on this host. Anything you added inside those skill folders is deleted too.",
         saveFailed: "Could not save your skill selection.",
         actions: {
-          install: "Install",
-          installing: "Installing...",
-          installed: "Installed",
           update: "Update",
           working: "Working...",
           remove: "Remove",
@@ -2865,6 +2973,7 @@ export const en = {
           title: "Enable Paseo tools",
           hint: "Agents will be able to manage worktrees, agents and schedules",
           accessibilityLabel: "Inject Paseo tools",
+          updateFailed: "Unable to update Paseo tools.",
         },
         systemPrompt: {
           title: "System prompt",
diff --git a/packages/app/src/i18n/resources/es.ts b/packages/app/src/i18n/resources/es.ts
index fa7291b298..3828d466b1 100644
--- a/packages/app/src/i18n/resources/es.ts
+++ b/packages/app/src/i18n/resources/es.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const es: TranslationResources = {
+  pluginCombobox: {
+    searching: "Buscando…",
+    empty: "Sin resultados",
+    failed: "La búsqueda falló: {{message}}",
+  },
   paneFind: {
     connectionFailure:
       "No se pudo buscar en este chat. Comprueba la conexión con el host y vuelve a intentarlo.",
@@ -384,6 +389,24 @@ export const es: TranslationResources = {
       answerPlaceholder: "Escribe tu respuesta...",
       otherPlaceholder: "Otro...",
     },
+    backgroundWork: {
+      pillOne: "1 tarea en segundo plano",
+      pillMany: "{{count}} tareas en segundo plano",
+      notRunning: "Ya no está en ejecución",
+      dismiss: "Cerrar",
+      stop: "Detener",
+      stopping: "Deteniendo…",
+      stopError: "No se pudo confirmar la detención.",
+      label: "Segundo plano",
+      title: "Trabajo en segundo plano",
+      waiting: "Esperando los detalles",
+      error: "No se pudo cargar el trabajo en segundo plano",
+      retry: "Reintentar",
+      running: "Trabajo en segundo plano en curso",
+      shell: "Consola",
+      monitor: "Monitor",
+      other: "Otro trabajo",
+    },
     todo: {
       title: "Tareas",
       empty: "Aún no hay tareas.",
@@ -965,6 +988,9 @@ export const es: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Rama base",
+        },
         openChangesTab: "Abrir la pestaña Cambios",
         openDiffTab: "Abrir la pestaña Diferencia",
         closeChangesTab: "Cerrar la pestaña Cambios",
@@ -1189,6 +1215,8 @@ export const es: TranslationResources = {
     title: "Novedades",
     installed: "Instalada",
     showMore: "Mostrar más",
+    showAllChanges: "Mostrar todos los cambios",
+    hideAllChanges: "Ocultar todos los cambios",
     openWebsite: "Registro de cambios completo",
     error: {
       title: "No se pudo cargar el registro de cambios",
@@ -1196,6 +1224,14 @@ export const es: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "No se pudo cargar la vista de la barra lateral.",
+      useDefault: "Usar vista predeterminada",
+      readFailed: "No se pudo cargar tu preferencia de vista de la barra lateral.",
+      agentUnavailable: "El agente ya no está disponible",
+      terminalUnavailable: "La terminal ya no está disponible",
+      projectUnavailable: "El proyecto ya no está disponible",
+    },
     statusGroupAccessibility: "Grupo {{label}}",
     statusBucket: {
       needsInput: "Necesita datos",
@@ -1271,6 +1307,7 @@ export const es: TranslationResources = {
       hosts: "Hosts",
       settings: "Ajustes",
       closeSidebar: "Cerrar barra lateral",
+      moreActions: "Más acciones",
     },
     footer: {
       usage: "Uso",
@@ -1375,6 +1412,9 @@ export const es: TranslationResources = {
         hostDisconnected: "Hostno está conectado",
         hideFailed: "No se pudo ocultar el espacio de trabajo",
         archiveFailed: "No se pudo archivar el espacio de trabajo",
+        archived: "Espacio de trabajo archivado",
+        undoArchive: "Deshacer",
+        undoArchiveFailed: "No se pudo deshacer el archivado",
       },
     },
   },
@@ -1588,6 +1628,9 @@ export const es: TranslationResources = {
       cli: {
         statusFailed: "No se puede verificar el estado de instalación deCLI.",
         installFailed: "No se puede instalar elPaseoCLI.",
+        uninstallFailed: "No se pudo desinstalar la CLI de Paseo.",
+        keptForeign:
+          "Se conservó un comando paseo que Paseo no instaló. Elimínalo tú mismo para desinstalarlo.",
       },
     },
   },
@@ -1639,6 +1682,7 @@ export const es: TranslationResources = {
     openPath: "Abrir ruta",
   },
   branchSwitcher: {
+    failedToLoad: "No se pudieron cargar las ramas. Vuelve a abrir el selector para reintentarlo.",
     triggerTooltip: "Cambiar rama del espacio de trabajo",
     currentBranch: "Sucursal actual:{{branchName}}. Presione para cambiar de rama.",
     placeholder: "Cambiar de rama...",
@@ -1662,7 +1706,11 @@ export const es: TranslationResources = {
     loadingCommands: "Cargando comandos...",
     noFiles: "No se encontraron archivos ni directorios",
     noCommands: "No se encontraron comandos",
-    failedToLoad: "No se pudo cargar",
+    loadingProviderCommands: "Cargando comandos de {{provider}}...",
+    commandsFailed: "No se pudieron cargar los comandos",
+    providerCommandsFailed: "No se pudieron cargar los comandos de {{provider}}",
+    filesFailed: "No se pudieron buscar archivos",
+    skillTag: "Skill",
     chooseProjectForCommands: "Elige un proyecto para ver los comandos",
     chooseModelForCommands: "Selecciona un modelo para ver los comandos",
   },
@@ -1689,6 +1737,60 @@ export const es: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "Paso {{current}} de {{total}}",
+      skip: "Omitir configuración",
+      continue: "Continuar",
+      finish: "Finalizar",
+      steps: {
+        appearance: {
+          label: "Apariencia",
+          title: "Te damos la bienvenida a Paseo",
+          description: "Empecemos por elegir una apariencia",
+        },
+        providers: {
+          label: "Proveedores",
+          title: "Tus agentes",
+          description: "Paseo usa las CLI de agentes que ya están en este ordenador",
+        },
+        projects: {
+          label: "Proyectos",
+          title: "Añade tus proyectos",
+          description: "Dónde quieres que trabajen tus agentes",
+          addProject: "Añadir proyecto",
+          added: "Añadido",
+          suggestions: {
+            loading: "Buscando carpetas en las que has trabajado",
+            empty: "No se encontraron proyectos recientes",
+            lastUsed: "Último uso {{time}}",
+            addSelected_one: "Añadir {{count}} proyecto",
+            addSelected_other: "Añadir {{count}} proyectos",
+            adding: "Añadiendo…",
+            addFailed: "No se pudo añadir esta carpeta",
+          },
+        },
+        orchestration: {
+          label: "Orquestación",
+          title: "Deja que los agentes usen Paseo",
+          description: "Deja que tus agentes creen espacios de trabajo y hablen con otros agentes",
+        },
+        phone: {
+          label: "Móvil",
+          title: "Lleva tus agentes contigo",
+          description:
+            "La app móvil nativa completa te permite controlar cualquier ordenador con Paseo desde tu teléfono",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "Elige cómo conectarte",
+          connectDocs: "Docs",
+          openConnectDocs: "Abrir la documentación de conectividad",
+          recommended: "Recomendado",
+          relay: { title: "Relé", hint: "Cifrado de extremo a extremo, escanea un código QR" },
+          tailscale: { title: "Tailscale", hint: "Requiere algo de configuración" },
+        },
+      },
+    },
     title: "Bienvenido aPaseo",
     subtitle: "Conecte su computadora para comenzar",
     actions: {
@@ -1909,6 +2011,8 @@ export const es: TranslationResources = {
       notNow: "Ahora no",
       directConnectionHint:
         "Sin relé, conéctese directamente por TCP, Tailscale u otra VPN. No se crea ningún código QR.",
+      tailscaleDocs: "Configurar Tailscale",
+      tailscaleDocsAccessibility: "Leer cómo conectarse con Tailscale",
       updateRequired: "Actualice el host para habilitar el relé desde Paseo Desktop.",
       unavailable: "Oferta de maridaje no disponible.",
       hint: "Escanee este códigoQRconPaseoen su teléfono o copie el enlace a continuación.",
@@ -2372,6 +2476,12 @@ export const es: TranslationResources = {
     general: {
       title: "General",
       sending: "Envío",
+      setup: {
+        label: "Configuración inicial",
+        description:
+          "Vuelve a recorrer apariencia, proveedores, proyectos y emparejamiento del teléfono",
+        action: "Mostrar configuración de nuevo",
+      },
       browserData: {
         title: "Datos del navegador",
         siteData: "Cookies y datos de sitios",
@@ -2534,6 +2644,13 @@ export const es: TranslationResources = {
         description: "Muestra un esquema para saltar entre instrucciones",
       },
       sidebar: {
+        view: {
+          title: "Vista de la barra lateral",
+          label: "Vista",
+          default: "Vista predeterminada",
+          unavailable:
+            "La vista seleccionada no está disponible o está desactivada. Se muestra la vista predeterminada.",
+        },
         header: {
           title: "Encabezado",
           description:
@@ -2667,11 +2784,7 @@ export const es: TranslationResources = {
       commandLine: {
         title: "línea de comando",
         description: "Agentes de control y script desde tu terminal",
-      },
-      actions: {
-        install: "Instalar",
-        installing: "Instalando...",
-        installed: "Instalado",
+        accessibilityLabel: "Instalar la CLI de Paseo",
       },
     },
     permissions: {
@@ -2749,10 +2862,9 @@ export const es: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "Habilidades de orquestación",
         title: "Habilidades de orquestación",
-        description: "Enseñe a sus agentes a orquestar a través delCLI",
+        description: "Enseña a tus agentes a usar las herramientas de Paseo",
         updateAvailable: "Actualización disponible",
         updateTitle: "¿Actualizar las habilidades dePaseo?",
-        updateFallback: "Sincronice las habilidades incluidas con su máquina.",
         uninstallTitle: "¿Desinstalar las habilidadesPaseo?",
         uninstallMessage:
           "Elimina todas las habilidades de orquestaciónPaseode ~/.agents, ~/.claude, ~/.codex.",
@@ -2771,9 +2883,6 @@ export const es: TranslationResources = {
         uninstallFailed: "No se pueden desinstalar las habilidades de orquestación.",
         saveSelectionFailed: "No se puede guardar la selección de habilidades de orquestación.",
         actions: {
-          install: "Instalar",
-          installing: "Instalando...",
-          installed: "Instalado",
           update: "Actualizar",
           working: "Laboral...",
           remove: "Eliminar",
@@ -2795,6 +2904,7 @@ export const es: TranslationResources = {
           title: "Habilitar herramientasPaseo",
           hint: "Los agentes podrán gestionar árboles de trabajo, agentes y horarios.",
           accessibilityLabel: "Inyectar herramientasPaseo",
+          updateFailed: "No se pudieron actualizar las herramientas de Paseo.",
         },
         systemPrompt: {
           title: "Aviso del sistema",
diff --git a/packages/app/src/i18n/resources/fr.ts b/packages/app/src/i18n/resources/fr.ts
index 46f3d40117..e3cb79f473 100644
--- a/packages/app/src/i18n/resources/fr.ts
+++ b/packages/app/src/i18n/resources/fr.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const fr: TranslationResources = {
+  pluginCombobox: {
+    searching: "Recherche…",
+    empty: "Aucun résultat",
+    failed: "Échec de la recherche : {{message}}",
+  },
   paneFind: {
     connectionFailure:
       "Impossible de rechercher dans cette conversation. Vérifiez la connexion à l’hôte et réessayez.",
@@ -384,6 +389,24 @@ export const fr: TranslationResources = {
       answerPlaceholder: "Saisissez votre réponse…",
       otherPlaceholder: "Autre…",
     },
+    backgroundWork: {
+      pillOne: "1 tâche en arrière-plan",
+      pillMany: "{{count}} tâches en arrière-plan",
+      notRunning: "N’est plus en cours",
+      dismiss: "Fermer",
+      stop: "Arrêter",
+      stopping: "Arrêt…",
+      stopError: "Impossible de confirmer l’arrêt.",
+      label: "Arrière-plan",
+      title: "Travail en arrière-plan",
+      waiting: "En attente des détails",
+      error: "Impossible de charger le travail en arrière-plan",
+      retry: "Réessayer",
+      running: "Travail en arrière-plan en cours",
+      shell: "Shell",
+      monitor: "Surveillance",
+      other: "Autre travail",
+    },
     todo: {
       title: "Tâches",
       empty: "Aucune tâche pour l’instant.",
@@ -958,6 +981,9 @@ export const fr: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Branche de base",
+        },
         openChangesTab: "Ouvrir l’onglet Modifications",
         openDiffTab: "Ouvrir l’onglet Diff",
         closeChangesTab: "Fermer l’onglet Modifications",
@@ -1182,6 +1208,8 @@ export const fr: TranslationResources = {
     title: "Nouveautés",
     installed: "Installée",
     showMore: "Afficher plus",
+    showAllChanges: "Afficher toutes les modifications",
+    hideAllChanges: "Masquer toutes les modifications",
     openWebsite: "Journal des modifications complet",
     error: {
       title: "Impossible de charger le journal des modifications",
@@ -1189,6 +1217,14 @@ export const fr: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "Impossible de charger la vue de la barre latérale.",
+      useDefault: "Utiliser la vue par défaut",
+      readFailed: "Impossible de charger votre préférence de vue de la barre latérale.",
+      agentUnavailable: "Cet agent n’est plus disponible",
+      terminalUnavailable: "Ce terminal n’est plus disponible",
+      projectUnavailable: "Ce projet n’est plus disponible",
+    },
     statusGroupAccessibility: "Groupe {{label}}",
     statusBucket: {
       needsInput: "Attend une réponse",
@@ -1265,6 +1301,7 @@ export const fr: TranslationResources = {
       hosts: "Hôtes",
       settings: "Paramètres",
       closeSidebar: "Fermer la barre latérale",
+      moreActions: "Plus d’actions",
     },
     footer: {
       usage: "Utilisation",
@@ -1369,6 +1406,9 @@ export const fr: TranslationResources = {
         hostDisconnected: "L’hôte n’est pas connecté",
         hideFailed: "Impossible de masquer l’espace de travail",
         archiveFailed: "Impossible d’archiver l’espace de travail",
+        archived: "Espace de travail archivé",
+        undoArchive: "Annuler",
+        undoArchiveFailed: "Impossible d’annuler l’archivage",
       },
     },
   },
@@ -1584,6 +1624,9 @@ export const fr: TranslationResources = {
       cli: {
         statusFailed: "Impossible de vérifier l’installation de la CLI.",
         installFailed: "Impossible d’installer la CLI Paseo.",
+        uninstallFailed: "Impossible de désinstaller la CLI Paseo.",
+        keptForeign:
+          "Une commande paseo qui n’a pas été installée par Paseo a été conservée. Supprimez-la vous-même pour la désinstaller.",
       },
     },
   },
@@ -1635,6 +1678,7 @@ export const fr: TranslationResources = {
     openPath: "Ouvrir le chemin",
   },
   branchSwitcher: {
+    failedToLoad: "Impossible de charger les branches. Rouvrez le sélecteur pour réessayer.",
     triggerTooltip: "Changer la branche de l’espace de travail",
     currentBranch: "Branche actuelle : {{branchName}}. Appuyez pour changer de branche.",
     placeholder: "Changer de branche…",
@@ -1659,7 +1703,11 @@ export const fr: TranslationResources = {
     loadingCommands: "Chargement des commandes…",
     noFiles: "Aucun fichier ou répertoire trouvé",
     noCommands: "Aucune commande trouvée",
-    failedToLoad: "Échec du chargement",
+    loadingProviderCommands: "Chargement des commandes {{provider}}…",
+    commandsFailed: "Impossible de charger les commandes",
+    providerCommandsFailed: "Impossible de charger les commandes {{provider}}",
+    filesFailed: "Impossible de rechercher les fichiers",
+    skillTag: "Skill",
     chooseProjectForCommands: "Choisissez un projet pour afficher les commandes",
     chooseModelForCommands: "Sélectionnez un modèle pour afficher les commandes",
   },
@@ -1687,6 +1735,61 @@ export const fr: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "Étape {{current}} sur {{total}}",
+      skip: "Passer la configuration",
+      continue: "Continuer",
+      finish: "Terminer",
+      steps: {
+        appearance: {
+          label: "Apparence",
+          title: "Bienvenue dans Paseo",
+          description: "Commençons par choisir une apparence",
+        },
+        providers: {
+          label: "Fournisseurs",
+          title: "Vos agents",
+          description: "Paseo utilise les CLI d'agents déjà installées sur cet ordinateur",
+        },
+        projects: {
+          label: "Projets",
+          title: "Ajoutez vos projets",
+          description: "Où voulez-vous que vos agents travaillent",
+          addProject: "Ajouter un projet",
+          added: "Ajouté",
+          suggestions: {
+            loading: "Recherche des dossiers dans lesquels vous avez travaillé",
+            empty: "Aucun projet récent trouvé",
+            lastUsed: "Dernière utilisation {{time}}",
+            addSelected_one: "Ajouter {{count}} projet",
+            addSelected_other: "Ajouter {{count}} projets",
+            adding: "Ajout…",
+            addFailed: "Impossible d'ajouter ce dossier",
+          },
+        },
+        orchestration: {
+          label: "Orchestration",
+          title: "Laissez les agents utiliser Paseo",
+          description:
+            "Laissez vos agents créer des espaces de travail et parler à d'autres agents",
+        },
+        phone: {
+          label: "Mobile",
+          title: "Emportez vos agents partout",
+          description:
+            "L'application mobile native complète vous permet de contrôler n'importe quel ordinateur Paseo depuis votre téléphone",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "Choisissez comment vous connecter",
+          connectDocs: "Docs",
+          openConnectDocs: "Ouvrir la documentation sur la connectivité",
+          recommended: "Recommandé",
+          relay: { title: "Relais", hint: "Chiffré de bout en bout, scannez un QR code" },
+          tailscale: { title: "Tailscale", hint: "Demande un peu de configuration" },
+        },
+      },
+    },
     title: "Bienvenue dans Paseo",
     subtitle: "Connectez votre ordinateur pour commencer",
     actions: {
@@ -1907,6 +2010,8 @@ export const fr: TranslationResources = {
       notNow: "Pas maintenant",
       directConnectionHint:
         "Sans relais, connectez-vous directement via TCP, Tailscale ou un autre VPN. Aucun code QR n’est créé.",
+      tailscaleDocs: "Configurer Tailscale",
+      tailscaleDocsAccessibility: "Lire comment se connecter via Tailscale",
       updateRequired: "Mettez à jour l’hôte pour activer le relais depuis Paseo Desktop.",
       unavailable: "Offre d’association indisponible.",
       hint: "Scannez ce code QR avec Paseo sur votre téléphone, ou copiez le lien ci-dessous.",
@@ -2372,6 +2477,12 @@ export const fr: TranslationResources = {
     general: {
       title: "Général",
       sending: "Envoi",
+      setup: {
+        label: "Configuration initiale",
+        description:
+          "Reprendre l'apparence, les fournisseurs, les projets et l'appairage du téléphone",
+        action: "Afficher la configuration",
+      },
       browserData: {
         title: "Données du navigateur",
         siteData: "Cookies et données des sites",
@@ -2534,6 +2645,13 @@ export const fr: TranslationResources = {
         description: "Afficher un plan pour naviguer entre les prompts",
       },
       sidebar: {
+        view: {
+          title: "Vue de la barre latérale",
+          label: "Vue",
+          default: "Vue par défaut",
+          unavailable:
+            "La vue sélectionnée est indisponible ou désactivée. La vue par défaut est affichée.",
+        },
         header: {
           title: "En-tête",
           description:
@@ -2669,11 +2787,7 @@ export const fr: TranslationResources = {
       commandLine: {
         title: "Ligne de commande",
         description: "Pilotez et scriptez vos agents depuis votre terminal",
-      },
-      actions: {
-        install: "Installer",
-        installing: "Installation…",
-        installed: "Installé",
+        accessibilityLabel: "Installer la CLI Paseo",
       },
     },
     permissions: {
@@ -2752,10 +2866,9 @@ export const fr: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "Skills d’orchestration",
         title: "Skills d’orchestration",
-        description: "Apprenez à vos agents à orchestrer via la CLI",
+        description: "Apprenez à vos agents à utiliser les outils Paseo",
         updateAvailable: "Mise à jour disponible",
         updateTitle: "Mettre à jour les skills Paseo ?",
-        updateFallback: "Synchronisez les skills fournis sur cet hôte.",
         uninstallTitle: "Désinstaller les skills Paseo ?",
         uninstallMessage:
           "Supprime tous les skills d’orchestration Paseo de ~/.agents, ~/.claude et ~/.codex sur cet hôte.",
@@ -2774,9 +2887,6 @@ export const fr: TranslationResources = {
         uninstallFailed: "Impossible de désinstaller les skills d’orchestration.",
         saveSelectionFailed: "Impossible d’enregistrer la sélection des skills d’orchestration.",
         actions: {
-          install: "Installer",
-          installing: "Installation…",
-          installed: "Installé",
           update: "Mettre à jour",
           working: "En cours…",
           remove: "Supprimer",
@@ -2798,6 +2908,7 @@ export const fr: TranslationResources = {
           title: "Activer les outils Paseo",
           hint: "Les agents pourront gérer les worktrees, les agents et les planifications",
           accessibilityLabel: "Injecter les outils Paseo",
+          updateFailed: "Impossible de mettre à jour les outils Paseo.",
         },
         systemPrompt: {
           title: "Prompt système",
diff --git a/packages/app/src/i18n/resources/ja.ts b/packages/app/src/i18n/resources/ja.ts
index 7d6d4fe337..ca9cae4be8 100644
--- a/packages/app/src/i18n/resources/ja.ts
+++ b/packages/app/src/i18n/resources/ja.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const ja: TranslationResources = {
+  pluginCombobox: {
+    searching: "検索中…",
+    empty: "結果がありません",
+    failed: "検索に失敗しました: {{message}}",
+  },
   paneFind: {
     connectionFailure:
       "このチャットを検索できませんでした。ホストへの接続を確認して再試行してください。",
@@ -384,6 +389,24 @@ export const ja: TranslationResources = {
       answerPlaceholder: "回答を入力...",
       otherPlaceholder: "その他...",
     },
+    backgroundWork: {
+      pillOne: "バックグラウンドタスク1件",
+      pillMany: "バックグラウンドタスク{{count}}件",
+      notRunning: "実行は終了しました",
+      dismiss: "閉じる",
+      stop: "停止",
+      stopping: "停止中…",
+      stopError: "停止を確認できませんでした。",
+      label: "バックグラウンド",
+      title: "バックグラウンド作業",
+      waiting: "作業の詳細を待っています",
+      error: "バックグラウンド作業を読み込めませんでした",
+      retry: "再試行",
+      running: "バックグラウンド作業を実行中",
+      shell: "シェル",
+      monitor: "監視",
+      other: "その他の作業",
+    },
     todo: {
       title: "タスク",
       empty: "タスクがまだありません。",
@@ -945,6 +968,9 @@ export const ja: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "ベースブランチ",
+        },
         openChangesTab: "変更タブを開く",
         openDiffTab: "差分タブを開く",
         closeChangesTab: "変更タブを閉じる",
@@ -1166,6 +1192,8 @@ export const ja: TranslationResources = {
     title: "新着情報",
     installed: "インストール済み",
     showMore: "もっと見る",
+    showAllChanges: "すべての変更を表示",
+    hideAllChanges: "すべての変更を非表示",
     openWebsite: "変更履歴をすべて表示",
     error: {
       title: "変更履歴を読み込めません",
@@ -1173,6 +1201,14 @@ export const ja: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "サイドバーのビューを読み込めませんでした。",
+      useDefault: "デフォルトのビューを使用",
+      readFailed: "サイドバーのビュー設定を読み込めませんでした。",
+      agentUnavailable: "このエージェントは利用できなくなりました",
+      terminalUnavailable: "このターミナルは利用できなくなりました",
+      projectUnavailable: "このプロジェクトは利用できなくなりました",
+    },
     statusGroupAccessibility: "{{label}} グループ",
     statusBucket: {
       needsInput: "入力待ち",
@@ -1249,6 +1285,7 @@ export const ja: TranslationResources = {
       hosts: "ホスト",
       settings: "設定",
       closeSidebar: "サイドバーを閉じる",
+      moreActions: "その他のアクション",
     },
     footer: {
       usage: "使用状況",
@@ -1353,6 +1390,9 @@ export const ja: TranslationResources = {
         hostDisconnected: "ホストが接続されていません",
         hideFailed: "ワークスペースの非表示に失敗しました",
         archiveFailed: "ワークスペースのアーカイブに失敗しました",
+        archived: "ワークスペースをアーカイブしました",
+        undoArchive: "元に戻す",
+        undoArchiveFailed: "アーカイブを元に戻せませんでした",
       },
     },
   },
@@ -1559,6 +1599,9 @@ export const ja: TranslationResources = {
       cli: {
         statusFailed: "CLIのインストール状態を確認できません。",
         installFailed: "Paseo CLIをインストールできません。",
+        uninstallFailed: "Paseo CLI をアンインストールできません。",
+        keptForeign:
+          "Paseoがインストールしていないpaseoコマンドは残しました。アンインストールするには手動で削除してください。",
       },
     },
   },
@@ -1610,6 +1653,7 @@ export const ja: TranslationResources = {
     openPath: "パスを開く",
   },
   branchSwitcher: {
+    failedToLoad: "ブランチを読み込めませんでした。選択画面を開き直してお試しください。",
     triggerTooltip: "ワークスペースのブランチを切り替え",
     currentBranch: "現在のブランチ: {{branchName}}。押してブランチを切り替えてください。",
     placeholder: "ブランチを切り替え...",
@@ -1633,7 +1677,11 @@ export const ja: TranslationResources = {
     loadingCommands: "コマンドを読み込み中...",
     noFiles: "ファイルまたはディレクトリが見つかりません",
     noCommands: "コマンドが見つかりません",
-    failedToLoad: "読み込みに失敗しました",
+    loadingProviderCommands: "{{provider}} のコマンドを読み込み中...",
+    commandsFailed: "コマンドを読み込めませんでした",
+    providerCommandsFailed: "{{provider}} のコマンドを読み込めませんでした",
+    filesFailed: "ファイルを検索できませんでした",
+    skillTag: "スキル",
     chooseProjectForCommands: "コマンドを表示するにはプロジェクトを選択してください",
     chooseModelForCommands: "コマンドを表示するにはモデルを選択してください",
   },
@@ -1660,6 +1708,61 @@ export const ja: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "ステップ {{current}}/{{total}}",
+      skip: "セットアップをスキップ",
+      continue: "続ける",
+      finish: "完了",
+      steps: {
+        appearance: {
+          label: "外観",
+          title: "Paseo へようこそ",
+          description: "まずは外観を選びましょう",
+        },
+        providers: {
+          label: "プロバイダー",
+          title: "エージェント",
+          description: "Paseo はこのコンピューターにインストール済みのエージェント CLI を使います",
+        },
+        projects: {
+          label: "プロジェクト",
+          title: "プロジェクトを追加",
+          description: "エージェントにどこで作業させますか",
+          addProject: "プロジェクトを追加",
+          added: "追加済み",
+          suggestions: {
+            loading: "作業したフォルダーを探しています",
+            empty: "最近のプロジェクトは見つかりませんでした",
+            lastUsed: "最終使用 {{time}}",
+            addSelected_one: "{{count}} 件のプロジェクトを追加",
+            addSelected_other: "{{count}} 件のプロジェクトを追加",
+            adding: "追加しています…",
+            addFailed: "このフォルダーを追加できませんでした",
+          },
+        },
+        orchestration: {
+          label: "オーケストレーション",
+          title: "エージェントに Paseo を使わせる",
+          description:
+            "エージェントがワークスペースを作成し、ほかのエージェントとやり取りできるようにします",
+        },
+        phone: {
+          label: "モバイル",
+          title: "エージェントを持ち歩く",
+          description:
+            "フル機能のネイティブモバイルアプリで、スマートフォンからどの Paseo コンピューターでも操作できます",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "接続方法を選択",
+          connectDocs: "ドキュメント",
+          openConnectDocs: "接続のドキュメントを開く",
+          recommended: "おすすめ",
+          relay: { title: "リレー", hint: "エンドツーエンド暗号化、QR コードをスキャン" },
+          tailscale: { title: "Tailscale", hint: "少し設定が必要です" },
+        },
+      },
+    },
     title: "Paseoへようこそ",
     subtitle: "始めるにはコンピューターに接続してください",
     actions: {
@@ -1880,6 +1983,8 @@ export const ja: TranslationResources = {
       notNow: "今はしない",
       directConnectionHint:
         "リレーを使わない場合は、TCP、Tailscale、または別の VPN で直接接続してください。QR コードは作成されません。",
+      tailscaleDocs: "Tailscale を設定",
+      tailscaleDocsAccessibility: "Tailscale で接続する方法を読む",
       updateRequired: "Paseo Desktop からリレーを有効にするにはホストを更新してください。",
       unavailable: "ペアリングオファーが利用できません。",
       hint: "スマートフォンのPaseoでこのQRコードをスキャンするか、以下のリンクをコピーしてください。",
@@ -2345,6 +2450,12 @@ export const ja: TranslationResources = {
     general: {
       title: "一般",
       sending: "送信",
+      setup: {
+        label: "初回セットアップ",
+        description:
+          "外観、プロバイダー、プロジェクト、スマートフォンのペアリングをもう一度設定します",
+        action: "セットアップを再表示",
+      },
       browserData: {
         title: "ブラウザーデータ",
         siteData: "Cookie とサイトデータ",
@@ -2500,6 +2611,13 @@ export const ja: TranslationResources = {
         description: "プロンプト間を移動するためのアウトラインを表示します",
       },
       sidebar: {
+        view: {
+          title: "サイドバーのビュー",
+          label: "ビュー",
+          default: "デフォルトのビュー",
+          unavailable:
+            "選択したビューは利用できないか無効です。デフォルトのビューを表示しています。",
+        },
         header: {
           title: "ヘッダー",
           description: "サイドバー上部に表示する項目とその順序を選択します",
@@ -2633,11 +2751,7 @@ export const ja: TranslationResources = {
       commandLine: {
         title: "コマンドライン",
         description: "ターミナルからエージェントを制御し、スクリプトで操作",
-      },
-      actions: {
-        install: "インストール",
-        installing: "インストール中...",
-        installed: "インストール済み",
+        accessibilityLabel: "Paseo CLI をインストール",
       },
     },
     permissions: {
@@ -2716,10 +2830,9 @@ export const ja: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "オーケストレーションスキル",
         title: "オーケストレーションスキル",
-        description: "エージェントがCLI経由でオーケストレーションできるようにします。",
+        description: "エージェントに Paseo ツールの使い方を教えます",
         updateAvailable: "更新が利用可能",
         updateTitle: "Paseoスキルを更新しますか？",
-        updateFallback: "バンドルされたスキルをマシンに同期します。",
         uninstallTitle: "Paseoスキルをアンインストールしますか？",
         uninstallMessage:
           "~/.agents、~/.claude、~/.codexからすべてのPaseoオーケストレーションスキルを削除します。",
@@ -2738,9 +2851,6 @@ export const ja: TranslationResources = {
         uninstallFailed: "オーケストレーションスキルをアンインストールできません。",
         saveSelectionFailed: "オーケストレーションスキルの選択を保存できません。",
         actions: {
-          install: "インストール",
-          installing: "インストール中...",
-          installed: "インストール済み",
           update: "更新",
           working: "処理中...",
           remove: "削除",
@@ -2762,6 +2872,7 @@ export const ja: TranslationResources = {
           title: "Paseoツールを有効にする",
           hint: "エージェントがワークツリー、エージェント、スケジュールを管理できるようになります",
           accessibilityLabel: "Paseoツールを有効にする",
+          updateFailed: "Paseoツールを更新できませんでした。",
         },
         systemPrompt: {
           title: "システムプロンプト",
diff --git a/packages/app/src/i18n/resources/ko.ts b/packages/app/src/i18n/resources/ko.ts
index 128484861a..6521470e64 100644
--- a/packages/app/src/i18n/resources/ko.ts
+++ b/packages/app/src/i18n/resources/ko.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const ko: TranslationResources = {
+  pluginCombobox: {
+    searching: "검색 중…",
+    empty: "결과 없음",
+    failed: "검색 실패: {{message}}",
+  },
   paneFind: {
     connectionFailure: "이 채팅을 검색할 수 없습니다. 호스트 연결을 확인하고 다시 시도하세요.",
     historyChangedFailure: "검색 중에 채팅이 변경되었습니다. 다시 검색하세요.",
@@ -380,6 +385,24 @@ export const ko: TranslationResources = {
       answerPlaceholder: "답변을 입력하세요...",
       otherPlaceholder: "기타...",
     },
+    backgroundWork: {
+      pillOne: "백그라운드 작업 1개",
+      pillMany: "백그라운드 작업 {{count}}개",
+      notRunning: "더 이상 실행 중이 아님",
+      dismiss: "닫기",
+      stop: "중지",
+      stopping: "중지 중…",
+      stopError: "중지를 확인하지 못했습니다.",
+      label: "백그라운드",
+      title: "백그라운드 작업",
+      waiting: "작업 세부 정보를 기다리는 중",
+      error: "백그라운드 작업을 불러오지 못했습니다",
+      retry: "다시 시도",
+      running: "백그라운드 작업 실행 중",
+      shell: "셸",
+      monitor: "모니터",
+      other: "기타 작업",
+    },
     todo: {
       title: "작업",
       empty: "아직 작업이 없습니다.",
@@ -939,6 +962,9 @@ export const ko: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "기준 브랜치",
+        },
         openChangesTab: "변경사항 탭 열기",
         openDiffTab: "Diff 탭 열기",
         closeChangesTab: "변경사항 탭 닫기",
@@ -1160,6 +1186,8 @@ export const ko: TranslationResources = {
     title: "새로운 소식",
     installed: "설치됨",
     showMore: "더 보기",
+    showAllChanges: "모든 변경 사항 보기",
+    hideAllChanges: "모든 변경 사항 숨기기",
     openWebsite: "전체 변경 내역",
     error: {
       title: "변경 내역을 불러오지 못했습니다",
@@ -1167,6 +1195,14 @@ export const ko: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "사이드바 보기를 불러오지 못했습니다.",
+      useDefault: "기본 보기 사용",
+      readFailed: "사이드바 보기 설정을 불러오지 못했습니다.",
+      agentUnavailable: "에이전트를 더 이상 사용할 수 없습니다",
+      terminalUnavailable: "터미널을 더 이상 사용할 수 없습니다",
+      projectUnavailable: "프로젝트를 더 이상 사용할 수 없습니다",
+    },
     statusGroupAccessibility: "{{label}} 그룹",
     statusBucket: {
       needsInput: "입력 필요",
@@ -1242,6 +1278,7 @@ export const ko: TranslationResources = {
       hosts: "호스트",
       settings: "설정",
       closeSidebar: "사이드바 닫기",
+      moreActions: "추가 작업",
     },
     footer: {
       usage: "사용량",
@@ -1346,6 +1383,9 @@ export const ko: TranslationResources = {
         hostDisconnected: "호스트가 연결되어 있지 않습니다",
         hideFailed: "워크스페이스를 숨기지 못했습니다",
         archiveFailed: "워크스페이스를 보관하지 못했습니다.",
+        archived: "워크스페이스를 보관했습니다",
+        undoArchive: "실행 취소",
+        undoArchiveFailed: "보관을 취소하지 못했습니다",
       },
     },
   },
@@ -1552,6 +1592,9 @@ export const ko: TranslationResources = {
       cli: {
         statusFailed: "CLI 설치 상태를 확인할 수 없습니다.",
         installFailed: "Paseo CLI를 설치할 수 없습니다.",
+        uninstallFailed: "Paseo CLI를 제거할 수 없습니다.",
+        keptForeign:
+          "Paseo가 설치하지 않은 paseo 명령은 그대로 두었습니다. 제거하려면 직접 삭제하세요.",
       },
     },
   },
@@ -1603,6 +1646,7 @@ export const ko: TranslationResources = {
     openPath: "경로 열기",
   },
   branchSwitcher: {
+    failedToLoad: "브랜치를 불러오지 못했습니다. 선택기를 다시 열어 재시도하세요.",
     triggerTooltip: "워크스페이스 브랜치 전환",
     currentBranch: "현재 브랜치: {{branchName}}. 브랜치를 전환하려면 누르세요.",
     placeholder: "브랜치 전환...",
@@ -1626,7 +1670,11 @@ export const ko: TranslationResources = {
     loadingCommands: "명령 불러오는 중...",
     noFiles: "파일 또는 디렉터리를 찾을 수 없습니다",
     noCommands: "명령을 찾을 수 없습니다",
-    failedToLoad: "불러오지 못했습니다",
+    loadingProviderCommands: "{{provider}} 명령 불러오는 중...",
+    commandsFailed: "명령을 불러오지 못했습니다",
+    providerCommandsFailed: "{{provider}} 명령을 불러오지 못했습니다",
+    filesFailed: "파일을 검색하지 못했습니다",
+    skillTag: "스킬",
     chooseProjectForCommands: "명령을 보려면 프로젝트를 선택하세요",
     chooseModelForCommands: "명령을 보려면 모델을 선택하세요",
   },
@@ -1653,6 +1701,60 @@ export const ko: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "{{total}}단계 중 {{current}}단계",
+      skip: "설정 건너뛰기",
+      continue: "계속",
+      finish: "완료",
+      steps: {
+        appearance: {
+          label: "모양",
+          title: "Paseo에 오신 것을 환영합니다",
+          description: "먼저 모양을 골라 보세요",
+        },
+        providers: {
+          label: "제공자",
+          title: "에이전트",
+          description: "Paseo는 이 컴퓨터에 이미 설치된 에이전트 CLI를 사용합니다",
+        },
+        projects: {
+          label: "프로젝트",
+          title: "프로젝트 추가",
+          description: "에이전트가 어디에서 작업하길 원하나요",
+          addProject: "프로젝트 추가",
+          added: "추가됨",
+          suggestions: {
+            loading: "작업했던 폴더를 찾는 중",
+            empty: "최근 프로젝트를 찾지 못했습니다",
+            lastUsed: "마지막 사용 {{time}}",
+            addSelected_one: "프로젝트 {{count}}개 추가",
+            addSelected_other: "프로젝트 {{count}}개 추가",
+            adding: "추가하는 중…",
+            addFailed: "이 폴더를 추가하지 못했습니다",
+          },
+        },
+        orchestration: {
+          label: "오케스트레이션",
+          title: "에이전트가 Paseo를 사용하도록 허용",
+          description: "에이전트가 워크스페이스를 만들고 다른 에이전트와 대화하게 하세요",
+        },
+        phone: {
+          label: "모바일",
+          title: "어디서나 에이전트와 함께",
+          description:
+            "모든 기능을 갖춘 네이티브 모바일 앱으로 휴대폰에서 어떤 Paseo 컴퓨터든 제어할 수 있습니다",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "연결 방법 선택",
+          connectDocs: "문서",
+          openConnectDocs: "연결 문서 열기",
+          recommended: "권장",
+          relay: { title: "릴레이", hint: "엔드투엔드 암호화, QR 코드를 스캔하세요" },
+          tailscale: { title: "Tailscale", hint: "약간의 설정이 필요합니다" },
+        },
+      },
+    },
     title: "Paseo에 오신 것을 환영합니다",
     subtitle: "시작하려면 컴퓨터를 연결하세요",
     actions: {
@@ -1871,6 +1973,8 @@ export const ko: TranslationResources = {
       notNow: "지금은 아님",
       directConnectionHint:
         "릴레이 없이 TCP, Tailscale 또는 다른 VPN을 통해 직접 연결하세요. QR 코드가 생성되지 않습니다.",
+      tailscaleDocs: "Tailscale 설정",
+      tailscaleDocsAccessibility: "Tailscale로 연결하는 방법 읽기",
       updateRequired: "Paseo 데스크톱에서 릴레이를 활성화하려면 호스트를 업데이트하세요.",
       unavailable: "페어링 정보를 사용할 수 없습니다.",
       hint: "휴대폰의 Paseo로 이 QR 코드를 스캔하거나 아래 링크를 복사하세요.",
@@ -2334,6 +2438,11 @@ export const ko: TranslationResources = {
     general: {
       title: "일반",
       sending: "전송",
+      setup: {
+        label: "초기 설정",
+        description: "모양, 제공자, 프로젝트, 휴대폰 페어링을 다시 진행합니다",
+        action: "설정 다시 보기",
+      },
       browserData: {
         title: "브라우저 데이터",
         siteData: "쿠키 및 사이트 데이터",
@@ -2493,6 +2602,13 @@ export const ko: TranslationResources = {
         description: "프롬프트 사이를 이동하기 위한 개요 표시",
       },
       sidebar: {
+        view: {
+          title: "사이드바 보기",
+          label: "보기",
+          default: "기본 보기",
+          unavailable:
+            "선택한 보기를 사용할 수 없거나 비활성화되어 있습니다. 기본 보기를 표시합니다.",
+        },
         header: {
           title: "헤더",
           description: "사이드바 상단에 표시할 항목과 순서를 선택하세요",
@@ -2623,11 +2739,7 @@ export const ko: TranslationResources = {
       commandLine: {
         title: "명령줄",
         description: "터미널에서 에이전트를 제어하고 스크립팅합니다",
-      },
-      actions: {
-        install: "설치",
-        installing: "설치 중...",
-        installed: "설치됨",
+        accessibilityLabel: "Paseo CLI 설치",
       },
     },
     permissions: {
@@ -2705,10 +2817,9 @@ export const ko: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "오케스트레이션 스킬",
         title: "오케스트레이션 스킬",
-        description: "CLI를 통해 에이전트가 오케스트레이션하도록 가르칩니다",
+        description: "에이전트에게 Paseo 도구 사용법을 알려 줍니다",
         updateAvailable: "업데이트 사용 가능",
         updateTitle: "Paseo 스킬을 업데이트할까요?",
-        updateFallback: "번들된 스킬을 내 컴퓨터에 동기화합니다.",
         uninstallTitle: "Paseo 스킬을 제거할까요?",
         uninstallMessage:
           "~/.agents, ~/.claude, ~/.codex에서 모든 Paseo 오케스트레이션 스킬을 제거합니다.",
@@ -2726,9 +2837,6 @@ export const ko: TranslationResources = {
         uninstallFailed: "오케스트레이션 스킬을 제거할 수 없습니다.",
         saveSelectionFailed: "오케스트레이션 스킬 선택을 저장하지 못했습니다.",
         actions: {
-          install: "설치",
-          installing: "설치 중...",
-          installed: "설치됨",
           update: "업데이트",
           working: "작업 중...",
           remove: "제거",
@@ -2750,6 +2858,7 @@ export const ko: TranslationResources = {
           title: "Paseo 도구 활성화",
           hint: "에이전트가 워크트리, 에이전트, 일정을 관리할 수 있습니다",
           accessibilityLabel: "Paseo 도구 주입",
+          updateFailed: "Paseo 도구를 업데이트할 수 없습니다.",
         },
         systemPrompt: {
           title: "시스템 프롬프트",
diff --git a/packages/app/src/i18n/resources/plugin-settings.ts b/packages/app/src/i18n/resources/plugin-settings.ts
index 8146ad9747..a5d829bff1 100644
--- a/packages/app/src/i18n/resources/plugin-settings.ts
+++ b/packages/app/src/i18n/resources/plugin-settings.ts
@@ -1,7 +1,7 @@
 const shared = {
   logs: {
     action: "Logs",
-    title: "Logs: {{id}}",
+    title: "Logs: {{name}}",
     loading: "Loading logs…",
     refresh: "Refresh",
     refreshing: "Refreshing…",
@@ -33,7 +33,8 @@ export const pluginSettings = {
     installing: "جارٍ التثبيت…",
     status: { running: "قيد التشغيل", disabled: "معطّلة", failed: "فشلت" },
     actions: {
-      menu: "إجراءات {{id}}",
+      menu: "إجراءات {{name}}",
+      settings: "الإعدادات",
       reload: "إعادة تحميل",
       reloading: "جارٍ إعادة التحميل…",
       enable: "تفعيل",
@@ -44,16 +45,16 @@ export const pluginSettings = {
       removing: "جارٍ الإزالة…",
     },
     feedback: {
-      installed: "تم تثبيت {{id}}",
-      reload: "تمت إعادة تحميل {{id}}",
-      enable: "تم تفعيل {{id}}",
-      disable: "تم تعطيل {{id}}",
-      remove: "تمت إزالة {{id}}",
-      kept: "تم الإبقاء على {{id}}",
+      installed: "تم تثبيت {{name}}",
+      reload: "تمت إعادة تحميل {{name}}",
+      enable: "تم تفعيل {{name}}",
+      disable: "تم تعطيل {{name}}",
+      remove: "تمت إزالة {{name}}",
+      kept: "تم الإبقاء على {{name}}",
       globalEnabled: "تم تفعيل الإضافات",
       globalDisabled: "تم تعطيل الإضافات",
     },
-    removeConfirmTitle: "إزالة {{id}}؟",
+    removeConfirmTitle: "إزالة {{name}}؟",
     removeConfirmMessage: "يؤدي هذا إلى إزالة الإعداد فقط. لن يُحذف مجلد المصدر.",
     states: {
       offlineTitle: "مضيف الإضافات غير متصل",
@@ -88,7 +89,8 @@ export const pluginSettings = {
     installing: "Instalando…",
     status: { running: "en ejecución", disabled: "desactivado", failed: "fallido" },
     actions: {
-      menu: "Acciones para {{id}}",
+      menu: "Acciones para {{name}}",
+      settings: "Configuración",
       reload: "Recargar",
       reloading: "Recargando…",
       enable: "Activar",
@@ -99,16 +101,16 @@ export const pluginSettings = {
       removing: "Eliminando…",
     },
     feedback: {
-      installed: "{{id}} instalado",
-      reload: "{{id}} recargado",
-      enable: "{{id}} activado",
-      disable: "{{id}} desactivado",
-      remove: "{{id}} eliminado",
-      kept: "Se conservó {{id}}",
+      installed: "{{name}} instalado",
+      reload: "{{name}} recargado",
+      enable: "{{name}} activado",
+      disable: "{{name}} desactivado",
+      remove: "{{name}} eliminado",
+      kept: "Se conservó {{name}}",
       globalEnabled: "Plugins activados",
       globalDisabled: "Plugins desactivados",
     },
-    removeConfirmTitle: "¿Eliminar {{id}}?",
+    removeConfirmTitle: "¿Eliminar {{name}}?",
     removeConfirmMessage: "Esto elimina la configuración. El directorio de origen no se borra.",
     states: {
       offlineTitle: "El host de plugins está sin conexión",
@@ -143,7 +145,8 @@ export const pluginSettings = {
     installing: "Installation…",
     status: { running: "actif", disabled: "désactivé", failed: "échec" },
     actions: {
-      menu: "Actions pour {{id}}",
+      menu: "Actions pour {{name}}",
+      settings: "Paramètres",
       reload: "Recharger",
       reloading: "Rechargement…",
       enable: "Activer",
@@ -154,16 +157,16 @@ export const pluginSettings = {
       removing: "Suppression…",
     },
     feedback: {
-      installed: "{{id}} installé",
-      reload: "{{id}} rechargé",
-      enable: "{{id}} activé",
-      disable: "{{id}} désactivé",
-      remove: "{{id}} supprimé",
-      kept: "{{id}} conservé",
+      installed: "{{name}} installé",
+      reload: "{{name}} rechargé",
+      enable: "{{name}} activé",
+      disable: "{{name}} désactivé",
+      remove: "{{name}} supprimé",
+      kept: "{{name}} conservé",
       globalEnabled: "Plugins activés",
       globalDisabled: "Plugins désactivés",
     },
-    removeConfirmTitle: "Supprimer {{id}} ?",
+    removeConfirmTitle: "Supprimer {{name}} ?",
     removeConfirmMessage: "La configuration sera supprimée. Le dossier source ne sera pas effacé.",
     states: {
       offlineTitle: "L’hôte des plugins est hors ligne",
@@ -198,7 +201,8 @@ export const pluginSettings = {
     installing: "インストール中…",
     status: { running: "実行中", disabled: "無効", failed: "失敗" },
     actions: {
-      menu: "{{id}} のアクション",
+      menu: "{{name}} のアクション",
+      settings: "設定",
       reload: "再読み込み",
       reloading: "再読み込み中…",
       enable: "有効化",
@@ -209,16 +213,16 @@ export const pluginSettings = {
       removing: "削除中…",
     },
     feedback: {
-      installed: "{{id}} をインストールしました",
-      reload: "{{id}} を再読み込みしました",
-      enable: "{{id}} を有効にしました",
-      disable: "{{id}} を無効にしました",
-      remove: "{{id}} を削除しました",
-      kept: "{{id}} を保持しました",
+      installed: "{{name}} をインストールしました",
+      reload: "{{name}} を再読み込みしました",
+      enable: "{{name}} を有効にしました",
+      disable: "{{name}} を無効にしました",
+      remove: "{{name}} を削除しました",
+      kept: "{{name}} を保持しました",
       globalEnabled: "プラグインを有効にしました",
       globalDisabled: "プラグインを無効にしました",
     },
-    removeConfirmTitle: "{{id}} を削除しますか？",
+    removeConfirmTitle: "{{name}} を削除しますか？",
     removeConfirmMessage: "設定のみを削除します。ソースディレクトリは削除されません。",
     states: {
       offlineTitle: "プラグインホストはオフラインです",
@@ -252,7 +256,8 @@ export const pluginSettings = {
     installing: "설치 중…",
     status: { running: "실행 중", disabled: "비활성화", failed: "실패" },
     actions: {
-      menu: "{{id}} 작업",
+      menu: "{{name}} 작업",
+      settings: "설정",
       reload: "다시 로드",
       reloading: "다시 로드 중…",
       enable: "활성화",
@@ -263,16 +268,16 @@ export const pluginSettings = {
       removing: "제거 중…",
     },
     feedback: {
-      installed: "{{id}} 설치됨",
-      reload: "{{id}} 다시 로드됨",
-      enable: "{{id}} 활성화됨",
-      disable: "{{id}} 비활성화됨",
-      remove: "{{id}} 제거됨",
-      kept: "{{id}} 유지됨",
+      installed: "{{name}} 설치됨",
+      reload: "{{name}} 다시 로드됨",
+      enable: "{{name}} 활성화됨",
+      disable: "{{name}} 비활성화됨",
+      remove: "{{name}} 제거됨",
+      kept: "{{name}} 유지됨",
       globalEnabled: "플러그인 활성화됨",
       globalDisabled: "플러그인 비활성화됨",
     },
-    removeConfirmTitle: "{{id}}을(를) 제거할까요?",
+    removeConfirmTitle: "{{name}}을(를) 제거할까요?",
     removeConfirmMessage: "설정만 제거합니다. 소스 디렉터리는 삭제되지 않습니다.",
     states: {
       offlineTitle: "플러그인 호스트가 오프라인입니다",
@@ -307,7 +312,8 @@ export const pluginSettings = {
     installing: "Instalando…",
     status: { running: "em execução", disabled: "desativado", failed: "falhou" },
     actions: {
-      menu: "Ações para {{id}}",
+      menu: "Ações para {{name}}",
+      settings: "Configurações",
       reload: "Recarregar",
       reloading: "Recarregando…",
       enable: "Ativar",
@@ -318,16 +324,16 @@ export const pluginSettings = {
       removing: "Removendo…",
     },
     feedback: {
-      installed: "{{id}} instalado",
-      reload: "{{id}} recarregado",
-      enable: "{{id}} ativado",
-      disable: "{{id}} desativado",
-      remove: "{{id}} removido",
-      kept: "{{id}} mantido",
+      installed: "{{name}} instalado",
+      reload: "{{name}} recarregado",
+      enable: "{{name}} ativado",
+      disable: "{{name}} desativado",
+      remove: "{{name}} removido",
+      kept: "{{name}} mantido",
       globalEnabled: "Plugins ativados",
       globalDisabled: "Plugins desativados",
     },
-    removeConfirmTitle: "Remover {{id}}?",
+    removeConfirmTitle: "Remover {{name}}?",
     removeConfirmMessage: "Isso remove a configuração. O diretório de origem não será excluído.",
     states: {
       offlineTitle: "O host de plugins está offline",
@@ -362,7 +368,8 @@ export const pluginSettings = {
     installing: "Установка…",
     status: { running: "работает", disabled: "отключён", failed: "ошибка" },
     actions: {
-      menu: "Действия для {{id}}",
+      menu: "Действия для {{name}}",
+      settings: "Настройки",
       reload: "Перезагрузить",
       reloading: "Перезагрузка…",
       enable: "Включить",
@@ -373,16 +380,16 @@ export const pluginSettings = {
       removing: "Удаление…",
     },
     feedback: {
-      installed: "{{id}} установлен",
-      reload: "{{id}} перезагружен",
-      enable: "{{id}} включён",
-      disable: "{{id}} отключён",
-      remove: "{{id}} удалён",
-      kept: "{{id}} сохранён",
+      installed: "{{name}} установлен",
+      reload: "{{name}} перезагружен",
+      enable: "{{name}} включён",
+      disable: "{{name}} отключён",
+      remove: "{{name}} удалён",
+      kept: "{{name}} сохранён",
       globalEnabled: "Плагины включены",
       globalDisabled: "Плагины отключены",
     },
-    removeConfirmTitle: "Удалить {{id}}?",
+    removeConfirmTitle: "Удалить {{name}}?",
     removeConfirmMessage: "Конфигурация будет удалена. Исходный каталог останется на месте.",
     states: {
       offlineTitle: "Хост плагинов не в сети",
@@ -416,7 +423,8 @@ export const pluginSettings = {
     installing: "正在安装…",
     status: { running: "运行中", disabled: "已禁用", failed: "失败" },
     actions: {
-      menu: "{{id}} 的操作",
+      menu: "{{name}} 的操作",
+      settings: "设置",
       reload: "重新加载",
       reloading: "正在重新加载…",
       enable: "启用",
@@ -427,16 +435,16 @@ export const pluginSettings = {
       removing: "正在移除…",
     },
     feedback: {
-      installed: "已安装 {{id}}",
-      reload: "已重新加载 {{id}}",
-      enable: "已启用 {{id}}",
-      disable: "已禁用 {{id}}",
-      remove: "已移除 {{id}}",
-      kept: "已保留 {{id}}",
+      installed: "已安装 {{name}}",
+      reload: "已重新加载 {{name}}",
+      enable: "已启用 {{name}}",
+      disable: "已禁用 {{name}}",
+      remove: "已移除 {{name}}",
+      kept: "已保留 {{name}}",
       globalEnabled: "插件已启用",
       globalDisabled: "插件已禁用",
     },
-    removeConfirmTitle: "移除 {{id}}？",
+    removeConfirmTitle: "移除 {{name}}？",
     removeConfirmMessage: "这会移除配置，但不会删除源目录。",
     states: {
       offlineTitle: "插件主机离线",
diff --git a/packages/app/src/i18n/resources/pt-BR.ts b/packages/app/src/i18n/resources/pt-BR.ts
index 54bd7b19ac..f8a21183cc 100644
--- a/packages/app/src/i18n/resources/pt-BR.ts
+++ b/packages/app/src/i18n/resources/pt-BR.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const ptBR: TranslationResources = {
+  pluginCombobox: {
+    searching: "Pesquisando…",
+    empty: "Nenhum resultado",
+    failed: "Falha na pesquisa: {{message}}",
+  },
   paneFind: {
     connectionFailure:
       "Não foi possível pesquisar nesta conversa. Verifique a conexão com o host e tente novamente.",
@@ -383,6 +388,24 @@ export const ptBR: TranslationResources = {
       answerPlaceholder: "Digite sua resposta...",
       otherPlaceholder: "Outro...",
     },
+    backgroundWork: {
+      pillOne: "1 tarefa em segundo plano",
+      pillMany: "{{count}} tarefas em segundo plano",
+      notRunning: "Não está mais em execução",
+      dismiss: "Dispensar",
+      stop: "Parar",
+      stopping: "Parando…",
+      stopError: "Não foi possível confirmar a parada.",
+      label: "Segundo plano",
+      title: "Trabalho em segundo plano",
+      waiting: "Aguardando os detalhes",
+      error: "Não foi possível carregar o trabalho em segundo plano",
+      retry: "Tentar novamente",
+      running: "Trabalho em segundo plano em andamento",
+      shell: "Shell",
+      monitor: "Monitor",
+      other: "Outro trabalho",
+    },
     todo: {
       title: "Tarefas",
       empty: "Nenhuma tarefa ainda.",
@@ -955,6 +978,9 @@ export const ptBR: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Branch base",
+        },
         openChangesTab: "Abrir a aba Alterações",
         openDiffTab: "Abrir a aba Diff",
         closeChangesTab: "Fechar a aba Alterações",
@@ -1179,6 +1205,8 @@ export const ptBR: TranslationResources = {
     title: "Novidades",
     installed: "Instalada",
     showMore: "Mostrar mais",
+    showAllChanges: "Mostrar todas as mudanças",
+    hideAllChanges: "Ocultar todas as mudanças",
     openWebsite: "Changelog completo",
     error: {
       title: "Não foi possível carregar o changelog",
@@ -1186,6 +1214,14 @@ export const ptBR: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "Não foi possível carregar a visualização da barra lateral.",
+      useDefault: "Usar visualização padrão",
+      readFailed: "Não foi possível carregar sua preferência de visualização da barra lateral.",
+      agentUnavailable: "O agente não está mais disponível",
+      terminalUnavailable: "O terminal não está mais disponível",
+      projectUnavailable: "O projeto não está mais disponível",
+    },
     statusGroupAccessibility: "Grupo {{label}}",
     statusBucket: {
       needsInput: "Precisa de resposta",
@@ -1261,6 +1297,7 @@ export const ptBR: TranslationResources = {
       hosts: "Hosts",
       settings: "Configurações",
       closeSidebar: "Fechar barra lateral",
+      moreActions: "Mais ações",
     },
     footer: {
       usage: "Uso",
@@ -1365,6 +1402,9 @@ export const ptBR: TranslationResources = {
         hostDisconnected: "Host não está conectado",
         hideFailed: "Falha ao ocultar workspace",
         archiveFailed: "Falha ao arquivar workspace",
+        archived: "Workspace arquivado",
+        undoArchive: "Desfazer",
+        undoArchiveFailed: "Não foi possível desfazer o arquivamento",
       },
     },
   },
@@ -1573,6 +1613,9 @@ export const ptBR: TranslationResources = {
       cli: {
         statusFailed: "Não foi possível verificar o status de instalação da CLI.",
         installFailed: "Não foi possível instalar a CLI do Paseo.",
+        uninstallFailed: "Não foi possível desinstalar a CLI do Paseo.",
+        keptForeign:
+          "Um comando paseo que o Paseo não instalou foi mantido. Remova-o manualmente para desinstalar.",
       },
     },
   },
@@ -1624,6 +1667,7 @@ export const ptBR: TranslationResources = {
     openPath: "Abrir caminho",
   },
   branchSwitcher: {
+    failedToLoad: "Não foi possível carregar as branches. Reabra o seletor para tentar novamente.",
     triggerTooltip: "Trocar branch do workspace",
     currentBranch: "Branch atual: {{branchName}}. Pressione para trocar de branch.",
     placeholder: "Trocar branch...",
@@ -1647,7 +1691,11 @@ export const ptBR: TranslationResources = {
     loadingCommands: "Carregando comandos...",
     noFiles: "Nenhum arquivo ou diretório encontrado",
     noCommands: "Nenhum comando encontrado",
-    failedToLoad: "Falha ao carregar",
+    loadingProviderCommands: "Carregando comandos do {{provider}}...",
+    commandsFailed: "Não foi possível carregar os comandos",
+    providerCommandsFailed: "Não foi possível carregar os comandos do {{provider}}",
+    filesFailed: "Não foi possível buscar arquivos",
+    skillTag: "Skill",
     chooseProjectForCommands: "Escolha um projeto para ver os comandos",
     chooseModelForCommands: "Selecione um modelo para ver os comandos",
   },
@@ -1674,6 +1722,60 @@ export const ptBR: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "Etapa {{current}} de {{total}}",
+      skip: "Pular configuração",
+      continue: "Continuar",
+      finish: "Concluir",
+      steps: {
+        appearance: {
+          label: "Aparência",
+          title: "Boas-vindas ao Paseo",
+          description: "Vamos começar escolhendo uma aparência",
+        },
+        providers: {
+          label: "Provedores",
+          title: "Seus agentes",
+          description: "O Paseo usa as CLIs de agentes já instaladas neste computador",
+        },
+        projects: {
+          label: "Projetos",
+          title: "Adicione seus projetos",
+          description: "Onde você quer que seus agentes trabalhem",
+          addProject: "Adicionar projeto",
+          added: "Adicionado",
+          suggestions: {
+            loading: "Procurando pastas em que você trabalhou",
+            empty: "Nenhum projeto recente encontrado",
+            lastUsed: "Último uso {{time}}",
+            addSelected_one: "Adicionar {{count}} projeto",
+            addSelected_other: "Adicionar {{count}} projetos",
+            adding: "Adicionando…",
+            addFailed: "Não foi possível adicionar esta pasta",
+          },
+        },
+        orchestration: {
+          label: "Orquestração",
+          title: "Deixe os agentes usarem o Paseo",
+          description: "Deixe seus agentes criarem workspaces e conversarem com outros agentes",
+        },
+        phone: {
+          label: "Celular",
+          title: "Leve seus agentes com você",
+          description:
+            "O app móvel nativo completo permite controlar qualquer computador com Paseo pelo seu celular",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "Escolha como se conectar",
+          connectDocs: "Docs",
+          openConnectDocs: "Abrir documentação de conectividade",
+          recommended: "Recomendado",
+          relay: { title: "Relay", hint: "Criptografia de ponta a ponta, escaneie um código QR" },
+          tailscale: { title: "Tailscale", hint: "Requer alguma configuração" },
+        },
+      },
+    },
     title: "Bem-vindo ao Paseo",
     subtitle: "Conecte seu computador para começar",
     actions: {
@@ -1894,6 +1996,8 @@ export const ptBR: TranslationResources = {
       notNow: "Agora não",
       directConnectionHint:
         "Sem relay, conecte diretamente por TCP, Tailscale ou outra VPN. Nenhum código QR é criado.",
+      tailscaleDocs: "Configurar Tailscale",
+      tailscaleDocsAccessibility: "Ler como conectar pelo Tailscale",
       updateRequired: "Atualize o host para ativar o relay pelo Paseo Desktop.",
       unavailable: "Oferta de pareamento indisponível.",
       hint: "Escaneie este QR code com o Paseo no seu celular ou copie o link abaixo.",
@@ -2357,6 +2461,11 @@ export const ptBR: TranslationResources = {
     general: {
       title: "Geral",
       sending: "Envio",
+      setup: {
+        label: "Configuração inicial",
+        description: "Rever aparência, provedores, projetos e pareamento do celular",
+        action: "Mostrar configuração novamente",
+      },
       browserData: {
         title: "Dados do navegador",
         siteData: "Cookies e dados de sites",
@@ -2517,6 +2626,13 @@ export const ptBR: TranslationResources = {
         description: "Mostrar uma estrutura para navegar entre prompts",
       },
       sidebar: {
+        view: {
+          title: "Visualização da barra lateral",
+          label: "Visualização",
+          default: "Visualização padrão",
+          unavailable:
+            "A visualização selecionada está indisponível ou desativada. Exibindo a visualização padrão.",
+        },
         header: {
           title: "Cabeçalho",
           description: "Escolha quais itens aparecem no topo da barra lateral e em que ordem",
@@ -2649,11 +2765,7 @@ export const ptBR: TranslationResources = {
       commandLine: {
         title: "Linha de comando",
         description: "Controle agentes e execute scripts pelo terminal",
-      },
-      actions: {
-        install: "Instalar",
-        installing: "Instalando...",
-        installed: "Instalado",
+        accessibilityLabel: "Instalar a CLI do Paseo",
       },
     },
     permissions: {
@@ -2731,10 +2843,9 @@ export const ptBR: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "Skills de orquestração",
         title: "Skills de orquestração",
-        description: "Ensine seus agentes a orquestrar pela CLI",
+        description: "Ensine seus agentes a usar as ferramentas do Paseo",
         updateAvailable: "Atualização disponível",
         updateTitle: "Atualizar Paseo skills?",
-        updateFallback: "Sincronize as skills incluídas com sua máquina.",
         uninstallTitle: "Desinstalar Paseo skills?",
         uninstallMessage:
           "Remove todas as skills de orquestração do Paseo de ~/.agents, ~/.claude e ~/.codex.",
@@ -2753,9 +2864,6 @@ export const ptBR: TranslationResources = {
         uninstallFailed: "Não foi possível desinstalar as skills de orquestração.",
         saveSelectionFailed: "Não foi possível salvar a seleção de skills de orquestração.",
         actions: {
-          install: "Instalar",
-          installing: "Instalando...",
-          installed: "Instalado",
           update: "Atualizar",
           working: "Trabalhando...",
           remove: "Remover",
@@ -2777,6 +2885,7 @@ export const ptBR: TranslationResources = {
           title: "Ativar ferramentas do Paseo",
           hint: "Agentes poderão gerenciar worktrees, agentes e agendamentos",
           accessibilityLabel: "Injetar ferramentas do Paseo",
+          updateFailed: "Não foi possível atualizar as ferramentas do Paseo.",
         },
         systemPrompt: {
           title: "Prompt do sistema",
diff --git a/packages/app/src/i18n/resources/ru.ts b/packages/app/src/i18n/resources/ru.ts
index 750a74e8d0..634d0d6622 100644
--- a/packages/app/src/i18n/resources/ru.ts
+++ b/packages/app/src/i18n/resources/ru.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const ru: TranslationResources = {
+  pluginCombobox: {
+    searching: "Поиск…",
+    empty: "Нет результатов",
+    failed: "Не удалось выполнить поиск: {{message}}",
+  },
   paneFind: {
     connectionFailure:
       "Не удалось выполнить поиск в чате. Проверьте подключение к хосту и повторите попытку.",
@@ -383,6 +388,24 @@ export const ru: TranslationResources = {
       answerPlaceholder: "Введите ответ...",
       otherPlaceholder: "Другой ответ...",
     },
+    backgroundWork: {
+      pillOne: "1 фоновая задача",
+      pillMany: "Фоновые задачи: {{count}}",
+      notRunning: "Больше не выполняется",
+      dismiss: "Закрыть",
+      stop: "Остановить",
+      stopping: "Остановка…",
+      stopError: "Не удалось подтвердить остановку.",
+      label: "В фоне",
+      title: "Фоновые задачи",
+      waiting: "Ожидание сведений о задачах",
+      error: "Не удалось загрузить фоновые задачи",
+      retry: "Повторить",
+      running: "Фоновые задачи выполняются",
+      shell: "Оболочка",
+      monitor: "Монитор",
+      other: "Другая задача",
+    },
     todo: {
       title: "Задачи",
       empty: "Задач пока нет.",
@@ -949,6 +972,9 @@ export const ru: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Базовая ветка",
+        },
         openChangesTab: "Открыть вкладку «Изменения»",
         openDiffTab: "Открыть вкладку «Дифф»",
         closeChangesTab: "Закрыть вкладку «Изменения»",
@@ -1170,6 +1196,8 @@ export const ru: TranslationResources = {
     title: "Что нового",
     installed: "Установлена",
     showMore: "Показать ещё",
+    showAllChanges: "Показать все изменения",
+    hideAllChanges: "Скрыть все изменения",
     openWebsite: "Полный список изменений",
     error: {
       title: "Не удалось загрузить список изменений",
@@ -1177,6 +1205,14 @@ export const ru: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "Не удалось загрузить вид боковой панели.",
+      useDefault: "Использовать стандартный вид",
+      readFailed: "Не удалось загрузить настройку вида боковой панели.",
+      agentUnavailable: "Агент больше недоступен",
+      terminalUnavailable: "Терминал больше недоступен",
+      projectUnavailable: "Проект больше недоступен",
+    },
     statusGroupAccessibility: "Группа «{{label}}»",
     statusBucket: {
       needsInput: "Ожидает ввода",
@@ -1253,6 +1289,7 @@ export const ru: TranslationResources = {
       hosts: "Хосты",
       settings: "Настройки",
       closeSidebar: "Закрыть боковую панель",
+      moreActions: "Дополнительные действия",
     },
     footer: {
       usage: "Использование",
@@ -1357,6 +1394,9 @@ export const ru: TranslationResources = {
         hostDisconnected: "Хост не подключён",
         hideFailed: "Не удалось скрыть рабочее пространство",
         archiveFailed: "Не удалось архивировать рабочее пространство",
+        archived: "Рабочее пространство архивировано",
+        undoArchive: "Отменить",
+        undoArchiveFailed: "Не удалось отменить архивацию",
       },
     },
   },
@@ -1570,6 +1610,9 @@ export const ru: TranslationResources = {
       cli: {
         statusFailed: "Не удалось проверить состояние установки CLI.",
         installFailed: "Не удалось установить Paseo CLI.",
+        uninstallFailed: "Не удалось удалить Paseo CLI.",
+        keptForeign:
+          "Команда paseo, установленная не Paseo, оставлена. Чтобы удалить её, сделайте это вручную.",
       },
     },
   },
@@ -1621,6 +1664,7 @@ export const ru: TranslationResources = {
     openPath: "Открыть путь",
   },
   branchSwitcher: {
+    failedToLoad: "Не удалось загрузить ветки. Откройте список заново, чтобы повторить попытку.",
     triggerTooltip: "Переключить ветку рабочего пространства",
     currentBranch: "Текущая ветка: {{branchName}}. Нажмите, чтобы переключить ветку.",
     placeholder: "Сменить ветку...",
@@ -1645,7 +1689,11 @@ export const ru: TranslationResources = {
     loadingCommands: "Загрузка команд...",
     noFiles: "Файлы и каталоги не найдены",
     noCommands: "Команды не найдены",
-    failedToLoad: "Не удалось загрузить",
+    loadingProviderCommands: "Загрузка команд {{provider}}...",
+    commandsFailed: "Не удалось загрузить команды",
+    providerCommandsFailed: "Не удалось загрузить команды {{provider}}",
+    filesFailed: "Не удалось найти файлы",
+    skillTag: "Навык",
     chooseProjectForCommands: "Выберите проект, чтобы увидеть команды",
     chooseModelForCommands: "Выберите модель, чтобы увидеть команды",
   },
@@ -1672,6 +1720,61 @@ export const ru: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "Шаг {{current}} из {{total}}",
+      skip: "Пропустить настройку",
+      continue: "Продолжить",
+      finish: "Готово",
+      steps: {
+        appearance: {
+          label: "Оформление",
+          title: "Добро пожаловать в Paseo",
+          description: "Начнём с выбора оформления",
+        },
+        providers: {
+          label: "Провайдеры",
+          title: "Ваши агенты",
+          description: "Paseo использует CLI агентов, уже установленные на этом компьютере",
+        },
+        projects: {
+          label: "Проекты",
+          title: "Добавьте проекты",
+          description: "Где будут работать ваши агенты",
+          addProject: "Добавить проект",
+          added: "Добавлено",
+          suggestions: {
+            loading: "Ищем папки, в которых вы работали",
+            empty: "Недавних проектов не найдено",
+            lastUsed: "Последнее использование {{time}}",
+            addSelected_one: "Добавить {{count}} проект",
+            addSelected_other: "Добавить проекты: {{count}}",
+            adding: "Добавляем…",
+            addFailed: "Не удалось добавить эту папку",
+          },
+        },
+        orchestration: {
+          label: "Оркестрация",
+          title: "Дайте агентам доступ к Paseo",
+          description:
+            "Разрешите агентам создавать рабочие пространства и общаться с другими агентами",
+        },
+        phone: {
+          label: "Мобильный",
+          title: "Агенты всегда под рукой",
+          description:
+            "Полнофункциональное нативное мобильное приложение позволяет управлять любым компьютером с Paseo с телефона",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "Выберите способ подключения",
+          connectDocs: "Документация",
+          openConnectDocs: "Открыть документацию по подключению",
+          recommended: "Рекомендуется",
+          relay: { title: "Ретранслятор", hint: "Сквозное шифрование, отсканируйте QR-код" },
+          tailscale: { title: "Tailscale", hint: "Требует небольшой настройки" },
+        },
+      },
+    },
     title: "Добро пожаловать в Paseo",
     subtitle: "Подключите компьютер, чтобы начать",
     actions: {
@@ -1893,6 +1996,8 @@ export const ru: TranslationResources = {
       notNow: "Не сейчас",
       directConnectionHint:
         "Без ретранслятора подключайтесь напрямую через TCP, Tailscale или другую VPN. QR-код создаваться не будет.",
+      tailscaleDocs: "Настроить Tailscale",
+      tailscaleDocsAccessibility: "Узнать, как подключиться через Tailscale",
       updateRequired: "Обновите хост, чтобы включить ретранслятор из Paseo Desktop.",
       unavailable: "Данные для сопряжения недоступны.",
       hint: "Отсканируйте этот QR-код с помощью Paseo на телефоне или скопируйте ссылку ниже.",
@@ -2359,6 +2464,11 @@ export const ru: TranslationResources = {
     general: {
       title: "Основные",
       sending: "Отправка",
+      setup: {
+        label: "Первоначальная настройка",
+        description: "Снова пройти оформление, провайдеры, проекты и привязку телефона",
+        action: "Показать настройку снова",
+      },
       browserData: {
         title: "Данные браузера",
         siteData: "Файлы cookie и данные сайтов",
@@ -2522,6 +2632,12 @@ export const ru: TranslationResources = {
         description: "Показывать оглавление для перехода между запросами",
       },
       sidebar: {
+        view: {
+          title: "Вид боковой панели",
+          label: "Вид",
+          default: "Стандартный вид",
+          unavailable: "Выбранный вид недоступен или отключён. Показан стандартный вид.",
+        },
         header: {
           title: "Верх",
           description:
@@ -2655,11 +2771,7 @@ export const ru: TranslationResources = {
       commandLine: {
         title: "Командная строка",
         description: "Управляйте агентами и автоматизируйте их работу из терминала",
-      },
-      actions: {
-        install: "Установить",
-        installing: "Установка...",
-        installed: "Установлено",
+        accessibilityLabel: "Установить Paseo CLI",
       },
     },
     permissions: {
@@ -2738,14 +2850,13 @@ export const ru: TranslationResources = {
       skills: {
         sectionTitle: "Навыки оркестрации",
         title: "Навыки оркестрации",
-        description: "Научите агентов координировать работу через CLI",
+        description: "Научите агентов пользоваться инструментами Paseo",
         docs: "Навыки",
         openDocs: "Открыть документацию по навыкам",
         unavailable: "Подключитесь к этому хосту, чтобы управлять навыками оркестрации",
         unsupported: "Обновите этот хост, чтобы управлять навыками оркестрации",
         updateAvailable: "Доступно обновление",
         updateTitle: "Обновить навыки Paseo?",
-        updateFallback: "Встроенные навыки будут синхронизированы с этим хостом.",
         uninstallTitle: "Удалить навыки Paseo?",
         uninstallMessage:
           "Удаляет все навыки оркестрации Paseo из ~/.agents, ~/.claude и ~/.codex на этом хосте.",
@@ -2763,9 +2874,6 @@ export const ru: TranslationResources = {
         uninstallFailed: "Не удалось удалить навыки оркестрации.",
         saveSelectionFailed: "Не удалось сохранить выбор навыков оркестрации.",
         actions: {
-          install: "Установить",
-          installing: "Установка...",
-          installed: "Установлено",
           update: "Обновить",
           working: "Выполняется...",
           remove: "Удалить",
@@ -2787,6 +2895,7 @@ export const ru: TranslationResources = {
           title: "Включить инструменты Paseo",
           hint: "Агенты смогут управлять worktree, агентами и расписаниями.",
           accessibilityLabel: "Добавить инструменты Paseo",
+          updateFailed: "Не удалось обновить инструменты Paseo.",
         },
         systemPrompt: {
           title: "Системный промпт",
diff --git a/packages/app/src/i18n/resources/zh-CN.ts b/packages/app/src/i18n/resources/zh-CN.ts
index 674bdcf1a9..5a65dc7082 100644
--- a/packages/app/src/i18n/resources/zh-CN.ts
+++ b/packages/app/src/i18n/resources/zh-CN.ts
@@ -2,6 +2,11 @@ import { en, type TranslationResources } from "./en";
 import { pluginSettings } from "./plugin-settings";
 
 export const zhCN: TranslationResources = {
+  pluginCombobox: {
+    searching: "搜索中…",
+    empty: "无结果",
+    failed: "搜索失败：{{message}}",
+  },
   paneFind: {
     connectionFailure: "无法搜索此聊天。请检查主机连接后重试。",
     historyChangedFailure: "搜索期间聊天已更改。请重新搜索。",
@@ -379,6 +384,24 @@ export const zhCN: TranslationResources = {
       answerPlaceholder: "输入你的回答...",
       otherPlaceholder: "其他...",
     },
+    backgroundWork: {
+      pillOne: "1 个后台任务",
+      pillMany: "{{count}} 个后台任务",
+      notRunning: "已不再运行",
+      dismiss: "关闭",
+      stop: "停止",
+      stopping: "正在停止…",
+      stopError: "无法确认已停止。",
+      label: "后台",
+      title: "后台任务",
+      waiting: "正在等待后台任务详情",
+      error: "无法加载后台任务",
+      retry: "重试",
+      running: "后台任务运行中",
+      shell: "Shell",
+      monitor: "监控",
+      other: "其他任务",
+    },
     todo: {
       title: "任务",
       empty: "还没有任务。",
@@ -924,6 +947,9 @@ export const zhCN: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "基准分支",
+        },
         openChangesTab: "打开“更改”标签页",
         openDiffTab: "打开 Diff 标签页",
         closeChangesTab: "关闭“更改”标签页",
@@ -1145,6 +1171,8 @@ export const zhCN: TranslationResources = {
     title: "新功能",
     installed: "已安装",
     showMore: "显示更多",
+    showAllChanges: "显示全部变更",
+    hideAllChanges: "收起全部变更",
     openWebsite: "完整更新日志",
     error: {
       title: "无法加载更新日志",
@@ -1152,6 +1180,14 @@ export const zhCN: TranslationResources = {
     },
   },
   sidebar: {
+    view: {
+      failed: "无法加载侧边栏视图。",
+      useDefault: "使用默认视图",
+      readFailed: "无法加载侧边栏视图偏好设置。",
+      agentUnavailable: "此智能体已不可用",
+      terminalUnavailable: "此终端已不可用",
+      projectUnavailable: "此项目已不可用",
+    },
     statusGroupAccessibility: "{{label}} 分组",
     statusBucket: {
       needsInput: "需要输入",
@@ -1227,6 +1263,7 @@ export const zhCN: TranslationResources = {
       hosts: "Hosts",
       settings: "设置",
       closeSidebar: "关闭侧边栏",
+      moreActions: "更多操作",
     },
     footer: {
       usage: "使用情况",
@@ -1328,6 +1365,9 @@ export const zhCN: TranslationResources = {
         hostDisconnected: "Host 未连接",
         hideFailed: "隐藏 workspace 失败",
         archiveFailed: "归档工作区失败",
+        archived: "工作区已归档",
+        undoArchive: "撤销",
+        undoArchiveFailed: "无法撤销归档",
       },
     },
   },
@@ -1527,6 +1567,8 @@ export const zhCN: TranslationResources = {
       cli: {
         statusFailed: "无法检查 CLI 安装状态。",
         installFailed: "无法安装 Paseo CLI。",
+        uninstallFailed: "无法卸载 Paseo CLI。",
+        keptForeign: "已保留一个不是由 Paseo 安装的 paseo 命令。如需卸载，请手动删除。",
       },
     },
   },
@@ -1577,6 +1619,7 @@ export const zhCN: TranslationResources = {
     openPath: "打开路径",
   },
   branchSwitcher: {
+    failedToLoad: "无法加载分支，请重新打开选择器以重试。",
     triggerTooltip: "切换工作区分支",
     currentBranch: "当前分支：{{branchName}}。按下以切换分支。",
     placeholder: "切换分支...",
@@ -1599,7 +1642,11 @@ export const zhCN: TranslationResources = {
     loadingCommands: "正在加载 commands...",
     noFiles: "没有找到文件或目录",
     noCommands: "没有找到 commands",
-    failedToLoad: "加载失败",
+    loadingProviderCommands: "正在加载 {{provider}} commands...",
+    commandsFailed: "无法加载 commands",
+    providerCommandsFailed: "无法加载 {{provider}} commands",
+    filesFailed: "无法搜索文件",
+    skillTag: "Skill",
     chooseProjectForCommands: "选择项目以查看命令",
     chooseModelForCommands: "选择模型以查看命令",
   },
@@ -1626,6 +1673,59 @@ export const zhCN: TranslationResources = {
     },
   },
   onboarding: {
+    setup: {
+      title: "Paseo",
+      stepCounter: "第 {{current}} 步，共 {{total}} 步",
+      skip: "跳过设置",
+      continue: "继续",
+      finish: "完成",
+      steps: {
+        appearance: {
+          label: "外观",
+          title: "欢迎使用 Paseo",
+          description: "先选择一个外观",
+        },
+        providers: {
+          label: "提供方",
+          title: "你的代理",
+          description: "Paseo 使用这台电脑上已安装的代理 CLI",
+        },
+        projects: {
+          label: "项目",
+          title: "添加项目",
+          description: "你希望代理在哪里工作",
+          addProject: "添加项目",
+          added: "已添加",
+          suggestions: {
+            loading: "正在查找你工作过的文件夹",
+            empty: "未找到最近的项目",
+            lastUsed: "上次使用 {{time}}",
+            addSelected_one: "添加 {{count}} 个项目",
+            addSelected_other: "添加 {{count}} 个项目",
+            adding: "正在添加…",
+            addFailed: "无法添加此文件夹",
+          },
+        },
+        orchestration: {
+          label: "编排",
+          title: "让代理使用 Paseo",
+          description: "让你的代理创建工作区并与其他代理对话",
+        },
+        phone: {
+          label: "移动端",
+          title: "随身带上你的代理",
+          description: "功能完整的原生移动应用让你可以在手机上控制任意一台 Paseo 电脑",
+          appStore: "App Store",
+          googlePlay: "Google Play",
+          connectTitle: "选择连接方式",
+          connectDocs: "文档",
+          openConnectDocs: "打开连接文档",
+          recommended: "推荐",
+          relay: { title: "中继", hint: "端到端加密，扫描二维码" },
+          tailscale: { title: "Tailscale", hint: "需要一些设置" },
+        },
+      },
+    },
     title: "欢迎使用 Paseo",
     subtitle: "连接你的电脑即可开始",
     actions: {
@@ -1840,6 +1940,8 @@ export const zhCN: TranslationResources = {
       notNow: "暂不",
       directConnectionHint:
         "不使用中继时，请通过 TCP、Tailscale 或其他 VPN 直接连接。不会生成二维码。",
+      tailscaleDocs: "设置 Tailscale",
+      tailscaleDocsAccessibility: "了解如何通过 Tailscale 连接",
       updateRequired: "请更新主机，以便从 Paseo Desktop 启用中继。",
       unavailable: "配对 offer 不可用。",
       hint: "用手机上的 Paseo 扫描此二维码，或复制下方链接。",
@@ -2301,6 +2403,11 @@ export const zhCN: TranslationResources = {
     general: {
       title: "通用",
       sending: "发送",
+      setup: {
+        label: "首次设置",
+        description: "重新设置外观、提供方、项目和手机配对",
+        action: "再次显示设置",
+      },
       browserData: {
         title: "浏览器数据",
         siteData: "Cookie 和网站数据",
@@ -2454,6 +2561,12 @@ export const zhCN: TranslationResources = {
         description: "显示用于在提示词之间跳转的大纲",
       },
       sidebar: {
+        view: {
+          title: "侧边栏视图",
+          label: "视图",
+          default: "默认视图",
+          unavailable: "所选视图不可用或已禁用。正在显示默认视图。",
+        },
         header: {
           title: "顶部",
           description: "选择侧边栏顶部显示的项目及其顺序",
@@ -2582,11 +2695,7 @@ export const zhCN: TranslationResources = {
       commandLine: {
         title: "命令行",
         description: "从终端控制 Agent 并运行脚本",
-      },
-      actions: {
-        install: "安装",
-        installing: "正在安装...",
-        installed: "已安装",
+        accessibilityLabel: "安装 Paseo CLI",
       },
     },
     permissions: {
@@ -2664,10 +2773,9 @@ export const zhCN: TranslationResources = {
         ...en.settings.host.skills,
         sectionTitle: "编排 skills",
         title: "编排 skills",
-        description: "教会 Agent 通过 CLI 编排任务",
+        description: "教你的代理如何使用 Paseo 工具",
         updateAvailable: "有更新可用",
         updateTitle: "更新 Paseo skills？",
-        updateFallback: "将内置 skills 同步到你的机器。",
         uninstallTitle: "卸载 Paseo skills？",
         uninstallMessage: "会从 ~/.agents、~/.claude、~/.codex 移除所有 Paseo 编排 skills。",
         choose: "选择 skills",
@@ -2684,9 +2792,6 @@ export const zhCN: TranslationResources = {
         uninstallFailed: "无法卸载编排 skills。",
         saveSelectionFailed: "无法保存编排 skills 的选择。",
         actions: {
-          install: "安装",
-          installing: "正在安装...",
-          installed: "已安装",
           update: "更新",
           working: "处理中...",
           remove: "移除",
@@ -2708,6 +2813,7 @@ export const zhCN: TranslationResources = {
           title: "启用 Paseo tools",
           hint: "Agent 将能够管理 worktree、Agent 和计划",
           accessibilityLabel: "注入 Paseo tools",
+          updateFailed: "无法更新 Paseo 工具。",
         },
         systemPrompt: {
           title: "System prompt",
diff --git a/packages/app/src/keyboard/actions.ts b/packages/app/src/keyboard/actions.ts
index 1bf78d923f..ef656a40a5 100644
--- a/packages/app/src/keyboard/actions.ts
+++ b/packages/app/src/keyboard/actions.ts
@@ -52,6 +52,7 @@ export type KeyboardActionId =
   | "workspace.project.pick"
   | "worktree.new"
   | "workspace.archive"
+  | "workspace.archive.undo"
   | "workspace.pin"
   | "view.toggle.focus"
   | "theme.cycle"
diff --git a/packages/app/src/keyboard/availability.test.ts b/packages/app/src/keyboard/availability.test.ts
index 282a879006..9bca173528 100644
--- a/packages/app/src/keyboard/availability.test.ts
+++ b/packages/app/src/keyboard/availability.test.ts
@@ -1,11 +1,68 @@
 import { describe, expect, it } from "vitest";
-import { keyboardShortcutsAvailable } from "./availability";
+import { createHardwareKeyboardPresence } from "./internal/hardware-presence";
+import { buildEffectiveBindings } from "./keyboard-shortcuts";
+import { createKeyboardPipeline } from "./internal/pipeline";
+import { createOverlayRegistry } from "./internal/overlays";
+import { nativeKeyboardInput } from "./internal/sources/contract";
 
-describe("keyboardShortcutsAvailable", () => {
-  it("matches the environments where the shortcut dispatcher runs", () => {
-    expect(keyboardShortcutsAvailable({ isNative: false, isCompact: false })).toBe(true);
-    expect(keyboardShortcutsAvailable({ isNative: false, isCompact: true })).toBe(false);
-    expect(keyboardShortcutsAvailable({ isNative: true, isCompact: false })).toBe(false);
-    expect(keyboardShortcutsAvailable({ isNative: true, isCompact: true })).toBe(false);
+describe("hardware keyboard availability", () => {
+  it("publishes connection changes and cleans up the capability subscription", () => {
+    let present = false;
+    const changes = new Set<() => void>();
+    const presence = createHardwareKeyboardPresence({
+      read: () => present,
+      watch: (changed) => {
+        changes.add(changed);
+        return () => {
+          changes.delete(changed);
+        };
+      },
+    });
+    const observed: boolean[] = [];
+    const release = presence.subscribe(() => observed.push(presence.getSnapshot()));
+    expect(presence.getSnapshot()).toBe(false);
+    present = true;
+    for (const changed of changes) changed();
+    expect(presence.getSnapshot()).toBe(true);
+    for (const changed of changes) changed();
+    present = false;
+    for (const changed of changes) changed();
+    expect(observed).toEqual([true, false]);
+    release();
+    expect(changes.size).toBe(0);
+  });
+
+  it("routes compact Electron input independently of hint availability", () => {
+    const presence = createHardwareKeyboardPresence({ read: () => false, watch: () => () => {} });
+    const actions: string[] = [];
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({}),
+      isCapturing: () => false,
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+      overlays: createOverlayRegistry(),
+    });
+    pipeline.keyDown(
+      nativeKeyboardInput(
+        {
+          key: "k",
+          code: "KeyK",
+          metaKey: true,
+          ctrlKey: false,
+          altKey: false,
+          shiftKey: false,
+          repeat: false,
+          preventDefault() {},
+          stopPropagation() {},
+        },
+        "other",
+      ),
+    );
+    expect(presence.getSnapshot()).toBe(false);
+    expect(actions).toEqual(["command-center.toggle"]);
+    pipeline.dispose();
   });
 });
diff --git a/packages/app/src/keyboard/availability.ts b/packages/app/src/keyboard/availability.ts
index ec3957f58f..31395f0f01 100644
--- a/packages/app/src/keyboard/availability.ts
+++ b/packages/app/src/keyboard/availability.ts
@@ -1,19 +1,9 @@
-import { useIsCompactFormFactor } from "@/constants/layout";
-import { isNative } from "@/constants/platform";
-
-interface KeyboardShortcutEnvironment {
-  isNative: boolean;
-  isCompact: boolean;
-}
-
-export function keyboardShortcutsAvailable({
-  isNative: native,
-  isCompact,
-}: KeyboardShortcutEnvironment): boolean {
-  return !native && !isCompact;
-}
-
-export function useKeyboardShortcutsAvailable(): boolean {
-  const isCompact = useIsCompactFormFactor();
-  return keyboardShortcutsAvailable({ isNative, isCompact });
+import { useSyncExternalStore } from "react";
+import { hardwareKeyboardPresence } from "./internal/presence";
+export function useHardwareKeyboardPresent(): boolean {
+  return useSyncExternalStore(
+    hardwareKeyboardPresence.subscribe,
+    hardwareKeyboardPresence.getSnapshot,
+    () => false,
+  );
 }
diff --git a/packages/app/src/keyboard/index.ts b/packages/app/src/keyboard/index.ts
new file mode 100644
index 0000000000..c8836c8e08
--- /dev/null
+++ b/packages/app/src/keyboard/index.ts
@@ -0,0 +1,13 @@
+export { useOverlayRegistration } from "./internal/overlay-registration";
+export type { KeyboardInputEvent } from "./internal/overlays";
+export {
+  dispatchTopOverlayKeyDown,
+  hasActiveOverlay,
+  getTopOverlayKeys,
+  getTopOverlayLayer,
+  subscribeOverlays,
+} from "./internal/overlay-dispatch";
+export { useKeyboardFocusSurface } from "./internal/use-focus-surface";
+export { usesDesktopBindings, supportsConfigurableComposerSendKeys } from "./internal/conventions";
+export type { BrowserKeyboardPolicy } from "./internal/sources/electron-browser";
+export { useHardwareKeyboardPresent } from "./availability";
diff --git a/packages/app/src/keyboard/internal/conventions.ts b/packages/app/src/keyboard/internal/conventions.ts
new file mode 100644
index 0000000000..0c457cf20d
--- /dev/null
+++ b/packages/app/src/keyboard/internal/conventions.ts
@@ -0,0 +1,3 @@
+export const usesDesktopBindings = true;
+// Native composer Return retains its existing submit path in this feature.
+export const supportsConfigurableComposerSendKeys = false;
diff --git a/packages/app/src/keyboard/internal/conventions.web.ts b/packages/app/src/keyboard/internal/conventions.web.ts
new file mode 100644
index 0000000000..0f75b6bc63
--- /dev/null
+++ b/packages/app/src/keyboard/internal/conventions.web.ts
@@ -0,0 +1,3 @@
+import { isElectronRuntime } from "@/desktop/host";
+export const usesDesktopBindings = isElectronRuntime();
+export const supportsConfigurableComposerSendKeys = true;
diff --git a/packages/app/src/keyboard/internal/dom-popover.ts b/packages/app/src/keyboard/internal/dom-popover.ts
new file mode 100644
index 0000000000..e7e9717fca
--- /dev/null
+++ b/packages/app/src/keyboard/internal/dom-popover.ts
@@ -0,0 +1,6 @@
+export function keyBelongsToDomPopover(_event: { key: string }): boolean {
+  return false;
+}
+export function hasOpenDomPopover(): boolean {
+  return false;
+}
diff --git a/packages/app/src/keyboard/internal/dom-popover.web.ts b/packages/app/src/keyboard/internal/dom-popover.web.ts
new file mode 100644
index 0000000000..ac4b6570a6
--- /dev/null
+++ b/packages/app/src/keyboard/internal/dom-popover.web.ts
@@ -0,0 +1,24 @@
+/**
+ * True while an element shown with the Popover API is open. Such a layer
+ * floats above the app like a registered overlay but lives outside the
+ * registry: plugins draw their panels this way, since they cannot register.
+ */
+export function hasOpenDomPopover(): boolean {
+  if (typeof document === "undefined") return false;
+  try {
+    return document.querySelector(":popover-open") !== null;
+  } catch {
+    // An engine without the Popover API rejects the selector, and has none open.
+    return false;
+  }
+}
+
+/**
+ * Whether a key belongs to an open popover rather than to the app's shortcuts.
+ * An open popover (a plugin's panel) is the top layer and closes on its own
+ * Escape listener, which runs after the shortcut engine's capture listener:
+ * Escape must not also interrupt the running agent.
+ */
+export function keyBelongsToDomPopover(event: Pick<KeyboardEvent, "key">): boolean {
+  return event.key === "Escape" && hasOpenDomPopover();
+}
diff --git a/packages/app/src/keyboard/internal/focus-surfaces.ts b/packages/app/src/keyboard/internal/focus-surfaces.ts
new file mode 100644
index 0000000000..5bdeb6fa0d
--- /dev/null
+++ b/packages/app/src/keyboard/internal/focus-surfaces.ts
@@ -0,0 +1,23 @@
+import { hasFocusedTextInput } from "./focused-text-input";
+import type { KeyboardFocusScope } from "../actions";
+export type KeyboardFocusSurface = "message-input" | "terminal";
+
+export function createKeyboardFocusScope(hasEditableFocus: () => boolean = () => false) {
+  const surfaces = new Map<symbol, KeyboardFocusSurface>();
+  return {
+    declare(surface: KeyboardFocusSurface) {
+      const token = Symbol(surface);
+      surfaces.set(token, surface);
+      return () => {
+        surfaces.delete(token);
+      };
+    },
+    resolve(commandCenterOpen: boolean): KeyboardFocusScope {
+      if (commandCenterOpen) return "command-center";
+      let focused: KeyboardFocusScope = hasEditableFocus() ? "editable" : "other";
+      for (const surface of surfaces.values()) focused = surface;
+      return focused;
+    },
+  };
+}
+export const focusSurfaces = createKeyboardFocusScope(hasFocusedTextInput);
diff --git a/packages/app/src/keyboard/internal/focused-text-input.ts b/packages/app/src/keyboard/internal/focused-text-input.ts
new file mode 100644
index 0000000000..87c7159e7e
--- /dev/null
+++ b/packages/app/src/keyboard/internal/focused-text-input.ts
@@ -0,0 +1,6 @@
+// oxlint-disable-next-line no-restricted-imports -- Keyboard boundary reads focus state; it does not render an input.
+import { TextInput } from "react-native";
+
+export function hasFocusedTextInput(): boolean {
+  return TextInput.State.currentlyFocusedInput() !== null;
+}
diff --git a/packages/app/src/keyboard/internal/focused-text-input.web.ts b/packages/app/src/keyboard/internal/focused-text-input.web.ts
new file mode 100644
index 0000000000..2a9de8633f
--- /dev/null
+++ b/packages/app/src/keyboard/internal/focused-text-input.web.ts
@@ -0,0 +1,3 @@
+export function hasFocusedTextInput(): boolean {
+  return false;
+}
diff --git a/packages/app/src/keyboard/internal/hardware-presence.ts b/packages/app/src/keyboard/internal/hardware-presence.ts
new file mode 100644
index 0000000000..701b67c919
--- /dev/null
+++ b/packages/app/src/keyboard/internal/hardware-presence.ts
@@ -0,0 +1,32 @@
+interface PresenceSource {
+  read(): boolean;
+  watch(changed: () => void): () => void;
+}
+export function createHardwareKeyboardPresence(source: PresenceSource) {
+  let present = source.read();
+  const listeners = new Set<() => void>();
+  let stop: (() => void) | undefined;
+  const update = () => {
+    const next = source.read();
+    if (present === next) return;
+    present = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    getSnapshot: () => present,
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      if (listeners.size === 1) {
+        stop = source.watch(update);
+        update();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stop?.();
+          stop = undefined;
+        }
+      };
+    },
+  };
+}
diff --git a/packages/app/src/keyboard/internal/overlay-contract.ts b/packages/app/src/keyboard/internal/overlay-contract.ts
new file mode 100644
index 0000000000..1061ecc42a
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlay-contract.ts
@@ -0,0 +1,10 @@
+import type { RefObject } from "react";
+import type { KeyboardInputEvent } from "./overlays";
+export interface OverlayRegistration {
+  active: boolean;
+  layer: number;
+  keys: readonly string[];
+  onKeyDown(event: KeyboardInputEvent): boolean;
+  restoreFocusRef?: RefObject<unknown>;
+  manageFocus?: boolean;
+}
diff --git a/packages/app/src/keyboard/internal/overlay-dispatch.ts b/packages/app/src/keyboard/internal/overlay-dispatch.ts
new file mode 100644
index 0000000000..0d38f2afe6
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlay-dispatch.ts
@@ -0,0 +1,8 @@
+import { overlays } from "./overlays";
+export const dispatchTopOverlayKeyDown = overlays.dispatch;
+export const hasActiveOverlay = overlays.hasActive;
+export const getTopOverlayKeys = overlays.getKeys;
+export const subscribeOverlays = overlays.subscribe;
+export function getTopOverlayLayer(): number {
+  return overlays.getTop()?.getLayer() ?? 0;
+}
diff --git a/packages/app/src/keyboard/internal/overlay-registration.ts b/packages/app/src/keyboard/internal/overlay-registration.ts
new file mode 100644
index 0000000000..31c2c0d494
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlay-registration.ts
@@ -0,0 +1,18 @@
+import type { OverlayRegistration } from "./overlay-contract";
+import { useLayoutEffect, useRef } from "react";
+import { overlays } from "./overlays";
+
+const setScope = (_node: unknown) => {};
+export function useOverlayRegistration(input: OverlayRegistration) {
+  const current = useRef(input);
+  current.current = input;
+  useLayoutEffect(() => {
+    if (!input.active) return;
+    return overlays.register({
+      getLayer: () => current.current.layer,
+      getKeys: () => current.current.keys,
+      onKeyDown: (event) => current.current.onKeyDown(event),
+    });
+  }, [input.active]);
+  return setScope;
+}
diff --git a/packages/app/src/keyboard/internal/overlay-registration.web.ts b/packages/app/src/keyboard/internal/overlay-registration.web.ts
new file mode 100644
index 0000000000..92beb60acf
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlay-registration.web.ts
@@ -0,0 +1,264 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { overlays, type OverlayEntry, type KeyboardInputEvent } from "./overlays";
+import type { OverlayRegistration } from "./overlay-contract";
+type WebOverlayKeyHandler = (event: KeyboardInputEvent) => boolean;
+
+interface WebOverlayEntry {
+  getLayer: () => number;
+  getKeys: () => readonly string[];
+  getScope: () => HTMLElement | null;
+  getKeyHandler: () => WebOverlayKeyHandler;
+  restoreFocus: HTMLElement | null;
+  manageFocus: boolean;
+}
+
+const focusEntries = new WeakMap<OverlayEntry, WebOverlayEntry>();
+let webOverlayListenersAttached = false;
+let webOverlayFocusCheckQueued = false;
+
+interface RemoveWebOverlayOptions {
+  restoreFocus?: boolean;
+}
+
+function getTopWebOverlay(): WebOverlayEntry | undefined {
+  const top = overlays.getTop();
+  return top ? focusEntries.get(top) : undefined;
+}
+
+function getFocusableElements(scope: HTMLElement): HTMLElement[] {
+  const selector = [
+    "a[href]",
+    "button:not([disabled])",
+    "input:not([disabled])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    '[tabindex]:not([tabindex="-1"])',
+  ].join(",");
+
+  return Array.from(scope.querySelectorAll<HTMLElement>(selector)).filter(
+    (element) =>
+      element.getAttribute("aria-hidden") !== "true" &&
+      !element.hasAttribute("hidden") &&
+      element.getClientRects().length > 0,
+  );
+}
+
+function focusFirstElement(scope: HTMLElement): void {
+  const firstMenuItem = scope.querySelector<HTMLElement>(
+    '[data-menu-item="true"]:not([data-menu-disabled="true"])',
+  );
+  const first = firstMenuItem ?? getFocusableElements(scope)[0];
+  (first ?? scope).focus();
+}
+
+function handleWebOverlayFocus(event: FocusEvent): void {
+  const top = getTopWebOverlay();
+  const scope = top?.getScope();
+  if (!top?.manageFocus || !scope || scope.contains(event.target as Node)) return;
+  if (webOverlayFocusCheckQueued) return;
+
+  // React can autofocus a child before its parent scope ref attaches. Defer
+  // enforcement until the commit finishes so a newly mounted higher overlay
+  // can register without the previous scope stealing the requested focus.
+  webOverlayFocusCheckQueued = true;
+  queueMicrotask(() => {
+    webOverlayFocusCheckQueued = false;
+    const currentTop = getTopWebOverlay();
+    const currentScope = currentTop?.getScope();
+    if (!currentTop?.manageFocus || !currentScope || currentScope.contains(document.activeElement))
+      return;
+    focusFirstElement(currentScope);
+  });
+}
+
+/**
+ * Gives the top painted overlay first refusal on a key before app-wide shortcuts run.
+ * The window listener below is the fallback for keys nobody routes through the shortcut engine.
+ */
+function dispatchOverlayEntry(entry: WebOverlayEntry, event: KeyboardInputEvent): boolean {
+  // Composition keys belong to the active text field. A modal must not turn an
+  // IME candidate confirmation into an overlay shortcut before the browser has
+  // committed the composed text.
+  if (event.isComposing || event.key === "Process") return false;
+
+  const top = entry;
+  const scope = entry.getScope();
+  if (!scope) return top.getKeyHandler()(event);
+
+  if (top.manageFocus && event.key === "Tab") {
+    const focusable = getFocusableElements(scope);
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    const shouldWrapBackward = event.shiftKey && (!scope.contains(active) || active === first);
+    const shouldWrapForward = !event.shiftKey && (!scope.contains(active) || active === last);
+    if (shouldWrapBackward || shouldWrapForward) {
+      event.preventDefault();
+      event.stopPropagation();
+      (shouldWrapBackward ? last : first)?.focus();
+      if (!first) scope.focus();
+      return true;
+    }
+  }
+
+  if (!top.getKeyHandler()(event)) return false;
+  event.stopPropagation();
+  return true;
+}
+
+function handleWebOverlayKeyDown(event: KeyboardEvent): void {
+  if (overlays.dispatch(event)) event.stopImmediatePropagation();
+}
+
+function attachWebOverlayListeners(): void {
+  if (webOverlayListenersAttached) return;
+  window.addEventListener("keydown", handleWebOverlayKeyDown, true);
+  document.addEventListener("focusin", handleWebOverlayFocus, true);
+  webOverlayListenersAttached = true;
+}
+
+function detachWebOverlayListeners(): void {
+  if (!webOverlayListenersAttached || overlays.hasActive()) return;
+  window.removeEventListener("keydown", handleWebOverlayKeyDown, true);
+  document.removeEventListener("focusin", handleWebOverlayFocus, true);
+  webOverlayListenersAttached = false;
+}
+
+function addWebOverlay(entry: WebOverlayEntry): (options?: RemoveWebOverlayOptions) => void {
+  const registration: OverlayEntry = {
+    getLayer: entry.getLayer,
+    getKeys: entry.getKeys,
+    onKeyDown: (event) => dispatchOverlayEntry(entry, event),
+  };
+  focusEntries.set(registration, entry);
+  const remove = overlays.register(registration);
+  attachWebOverlayListeners();
+
+  const focusFrame = window.requestAnimationFrame(() => {
+    const scope = entry.getScope();
+    if (
+      entry.manageFocus &&
+      getTopWebOverlay() === entry &&
+      scope &&
+      !scope.contains(document.activeElement)
+    ) {
+      focusFirstElement(scope);
+    }
+  });
+
+  return (options) => {
+    window.cancelAnimationFrame(focusFrame);
+    remove();
+    detachWebOverlayListeners();
+    if (
+      entry.manageFocus &&
+      options?.restoreFocus !== false &&
+      entry.restoreFocus &&
+      document.contains(entry.restoreFocus)
+    ) {
+      entry.restoreFocus.focus();
+    }
+  };
+}
+
+/**
+ * Registers a focus scope in the same relative layer model used for painting.
+ * Only the highest painted overlay receives keyboard input. By default, focus is trapped
+ * there and restored to the opener when it closes; hover surfaces preserve focus instead.
+ */
+export function useOverlayRegistration({
+  active,
+  layer,
+  keys,
+  onKeyDown,
+  manageFocus = true,
+  restoreFocusRef: preferredRestoreFocusRef,
+}: OverlayRegistration) {
+  const scopeRef = useRef<HTMLElement | null>(null);
+  const keysRef = useRef(keys);
+  keysRef.current = keys;
+  const layerRef = useRef(layer);
+  const keyHandlerRef = useRef(onKeyDown);
+  const capturedRestoreFocusRef = useRef<HTMLElement | null>(null);
+  const removeEntryRef = useRef<((options?: RemoveWebOverlayOptions) => void) | null>(null);
+  const detachedRemoveEntryRef = useRef<((options?: RemoveWebOverlayOptions) => void) | null>(null);
+  const registeredRef = useRef(false);
+  const activeRef = useRef(active);
+  const wasActiveRef = useRef(false);
+
+  activeRef.current = active;
+  layerRef.current = layer;
+  keyHandlerRef.current = onKeyDown;
+  if (active && !wasActiveRef.current && typeof document !== "undefined") {
+    const requestedRestoreTarget = preferredRestoreFocusRef?.current;
+    if (requestedRestoreTarget instanceof HTMLElement) {
+      capturedRestoreFocusRef.current = requestedRestoreTarget;
+    } else {
+      capturedRestoreFocusRef.current =
+        document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    }
+  }
+  wasActiveRef.current = active;
+
+  const syncRegistration = useCallback(() => {
+    const shouldRegister =
+      activeRef.current && typeof window !== "undefined" && typeof document !== "undefined";
+    if (!shouldRegister) {
+      const shouldRestoreFocus = !activeRef.current;
+      if (registeredRef.current || shouldRestoreFocus) {
+        removeEntryRef.current?.({ restoreFocus: shouldRestoreFocus });
+      }
+      registeredRef.current = false;
+      if (shouldRestoreFocus) {
+        removeEntryRef.current = null;
+        detachedRemoveEntryRef.current = null;
+      }
+      return;
+    }
+    if (registeredRef.current) return;
+
+    detachedRemoveEntryRef.current = null;
+    const entry: WebOverlayEntry = {
+      getLayer: () => layerRef.current,
+      getKeys: () => keysRef.current,
+      getScope: () => scopeRef.current,
+      getKeyHandler: () => keyHandlerRef.current,
+      restoreFocus: capturedRestoreFocusRef.current,
+      manageFocus,
+    };
+    removeEntryRef.current = addWebOverlay(entry);
+    registeredRef.current = true;
+  }, [manageFocus]);
+
+  const setScope = useCallback(
+    (node: unknown) => {
+      scopeRef.current =
+        typeof HTMLElement !== "undefined" && node instanceof HTMLElement ? node : null;
+      if (!scopeRef.current && activeRef.current) {
+        const removeEntry = removeEntryRef.current;
+        removeEntry?.({ restoreFocus: false });
+        detachedRemoveEntryRef.current = removeEntry;
+        removeEntryRef.current = null;
+        registeredRef.current = false;
+        return;
+      }
+      // Host refs attach before descendant layout effects and autofocus. Register
+      // here so the previous overlay cannot redirect that pending focus.
+      syncRegistration();
+    },
+    [syncRegistration],
+  );
+
+  useLayoutEffect(() => {
+    syncRegistration();
+    return () => {
+      const removeEntry = removeEntryRef.current ?? detachedRemoveEntryRef.current;
+      removeEntry?.();
+      removeEntryRef.current = null;
+      detachedRemoveEntryRef.current = null;
+      registeredRef.current = false;
+    };
+  }, [active, syncRegistration]);
+
+  return setScope;
+}
diff --git a/packages/app/src/keyboard/internal/overlays.test.ts b/packages/app/src/keyboard/internal/overlays.test.ts
new file mode 100644
index 0000000000..09f734e606
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlays.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { createOverlayRegistry } from "./overlays";
+
+function keyEvent(key: string) {
+  return {
+    key,
+    code: key,
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    repeat: false,
+    isComposing: false,
+    preventDefault() {},
+    stopPropagation() {},
+  };
+}
+
+describe("overlay keyboard ownership", () => {
+  it("offers a key only to the highest layer and consumes it once without DOM focus", () => {
+    const registry = createOverlayRegistry();
+    const calls: string[] = [];
+    const remove = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Escape"],
+      onKeyDown: (event) => {
+        calls.push(`modal:${event.key}`);
+        return true;
+      },
+    });
+    const removeMenu = registry.register({
+      getLayer: () => 30,
+      getKeys: () => ["Enter"],
+      onKeyDown: (event) => {
+        calls.push(`menu:${event.key}`);
+        return event.key === "Enter";
+      },
+    });
+    expect(registry.dispatch(keyEvent("Escape"))).toBe(false);
+    expect(calls).toEqual(["menu:Escape"]);
+    expect(registry.getKeys()).toEqual(["Enter"]);
+    removeMenu();
+    expect(registry.dispatch(keyEvent("Escape"))).toBe(true);
+    expect(calls).toEqual(["menu:Escape", "modal:Escape"]);
+    remove();
+    expect(registry.dispatch(keyEvent("Escape"))).toBe(false);
+  });
+});
+
+describe("overlay registration lifecycle", () => {
+  it("uses the newest registration at equal layers and ignores composition", () => {
+    const registry = createOverlayRegistry();
+    const calls: string[] = [];
+    const first = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Escape"],
+      onKeyDown: () => {
+        calls.push("first");
+        return true;
+      },
+    });
+    const second = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Enter"],
+      onKeyDown: () => {
+        calls.push("second");
+        return true;
+      },
+    });
+    expect(registry.dispatch({ ...keyEvent("Enter"), isComposing: true })).toBe(false);
+    expect(calls).toEqual([]);
+    expect(registry.dispatch(keyEvent("Enter"))).toBe(true);
+    expect(calls).toEqual(["second"]);
+    second();
+    expect(registry.dispatch(keyEvent("Escape"))).toBe(true);
+    expect(calls).toEqual(["second", "first"]);
+    first();
+  });
+
+  it("notifies subscribers when top key ownership changes", () => {
+    const registry = createOverlayRegistry();
+    const observed: string[][] = [];
+    const unsubscribe = registry.subscribe(() => observed.push([...registry.getKeys()]));
+    const release = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Enter"],
+      onKeyDown: () => false,
+    });
+    release();
+    release();
+    unsubscribe();
+    expect(observed).toEqual([["Enter"], []]);
+  });
+});
diff --git a/packages/app/src/keyboard/internal/overlays.ts b/packages/app/src/keyboard/internal/overlays.ts
new file mode 100644
index 0000000000..150842f6c6
--- /dev/null
+++ b/packages/app/src/keyboard/internal/overlays.ts
@@ -0,0 +1,53 @@
+import type { KeyboardShortcutInput } from "../keyboard-shortcuts";
+
+export interface KeyboardInputEvent extends KeyboardShortcutInput {
+  isComposing?: boolean;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+export interface OverlayEntry {
+  getLayer(): number;
+  getKeys(): readonly string[];
+  onKeyDown(event: KeyboardInputEvent): boolean;
+}
+export function createOverlayRegistry() {
+  const entries: OverlayEntry[] = [];
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+  function getTop(): OverlayEntry | undefined {
+    return entries.reduce<OverlayEntry | undefined>(
+      (top, entry) => (!top || entry.getLayer() >= top.getLayer() ? entry : top),
+      undefined,
+    );
+  }
+  return {
+    getTop,
+    getKeys: () => getTop()?.getKeys() ?? [],
+    hasActive: () => entries.length > 0,
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    register(entry: OverlayEntry) {
+      entries.push(entry);
+      notify();
+      return () => {
+        const index = entries.indexOf(entry);
+        if (index < 0) return;
+        entries.splice(index, 1);
+        notify();
+      };
+    },
+    dispatch(event: KeyboardInputEvent): boolean {
+      if (event.isComposing || event.key === "Process") return false;
+      if (!getTop()?.onKeyDown(event)) return false;
+      event.stopPropagation();
+      return true;
+    },
+  };
+}
+export const overlays = createOverlayRegistry();
diff --git a/packages/app/src/keyboard/internal/pipeline.ts b/packages/app/src/keyboard/internal/pipeline.ts
new file mode 100644
index 0000000000..297cb7eabd
--- /dev/null
+++ b/packages/app/src/keyboard/internal/pipeline.ts
@@ -0,0 +1,60 @@
+import {
+  resolveKeyboardShortcut,
+  type ChordState,
+  type KeyboardShortcutContext,
+  type KeyboardShortcutMatch,
+  type ParsedShortcutBinding,
+} from "../keyboard-shortcuts";
+import type { KeyboardSourceInput } from "./sources/contract";
+import type { createOverlayRegistry } from "./overlays";
+
+interface KeyboardPipelineOptions {
+  getContext(): Omit<KeyboardShortcutContext, "focusScope">;
+  getBindings(): readonly ParsedShortcutBinding[];
+  isCapturing(): boolean;
+  dispatch(match: KeyboardShortcutMatch, input: KeyboardSourceInput): boolean;
+  overlays: ReturnType<typeof createOverlayRegistry>;
+  beforeResolve?(input: KeyboardSourceInput): boolean;
+  chordChanged?(previous: ChordState, next: ChordState, input: KeyboardSourceInput | null): void;
+}
+function emptyChord(): ChordState {
+  return { candidateIndices: [], step: 0, timeoutId: null };
+}
+
+export function createKeyboardPipeline(options: KeyboardPipelineOptions) {
+  let chord = emptyChord();
+  function reset() {
+    const previous = chord;
+    if (chord.timeoutId !== null) clearTimeout(chord.timeoutId);
+    chord = emptyChord();
+    options.chordChanged?.(previous, chord, null);
+  }
+  return {
+    dispose: reset,
+    keyDown(input: KeyboardSourceInput): boolean {
+      const event = input.event;
+      if (options.overlays.dispatch(event)) return true;
+      if (event.isComposing || event.key === "Process" || options.isCapturing()) return false;
+      if (options.beforeResolve && !options.beforeResolve(input)) return false;
+      const previous = chord;
+      const result = resolveKeyboardShortcut({
+        event,
+        context: { ...options.getContext(), focusScope: input.focusScope },
+        bindings: options.getBindings(),
+        chordState: chord,
+        onChordReset: reset,
+      });
+      chord = result.nextChordState;
+      options.chordChanged?.(previous, chord, input);
+      if (result.preventDefault) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      if (!result.match) return false;
+      if (!options.dispatch(result.match, input)) return false;
+      if (result.match.preventDefault) event.preventDefault();
+      if (result.match.stopPropagation) event.stopPropagation();
+      return true;
+    },
+  };
+}
diff --git a/packages/app/src/keyboard/internal/presence.ts b/packages/app/src/keyboard/internal/presence.ts
new file mode 100644
index 0000000000..9856f2b2e9
--- /dev/null
+++ b/packages/app/src/keyboard/internal/presence.ts
@@ -0,0 +1,6 @@
+import { createHardwareKeyboardPresence } from "./hardware-presence";
+import { getHardwareKeyboardPresent, subscribeHardwareKeyboardPresence } from "./sources/hardware";
+export const hardwareKeyboardPresence = createHardwareKeyboardPresence({
+  read: getHardwareKeyboardPresent,
+  watch: subscribeHardwareKeyboardPresence,
+});
diff --git a/packages/app/src/keyboard/internal/presence.web.ts b/packages/app/src/keyboard/internal/presence.web.ts
new file mode 100644
index 0000000000..ff92ad24f2
--- /dev/null
+++ b/packages/app/src/keyboard/internal/presence.web.ts
@@ -0,0 +1,31 @@
+import { createHardwareKeyboardPresence } from "./hardware-presence";
+
+export function createWebHardwareKeyboardPresence(
+  pointer: MediaQueryList | null,
+  events: Window | null,
+) {
+  let observedKeyboard = false;
+  return createHardwareKeyboardPresence({
+    read: () => observedKeyboard || pointer?.matches === true,
+    watch(changed) {
+      if (!events) return () => {};
+      const onKeyDown = (event: KeyboardEvent) => {
+        if (!(event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)) return;
+        observedKeyboard = true;
+        changed();
+      };
+      pointer?.addEventListener("change", changed);
+      events.addEventListener("keydown", onKeyDown, true);
+      return () => {
+        pointer?.removeEventListener("change", changed);
+        events.removeEventListener("keydown", onKeyDown, true);
+      };
+    },
+  });
+}
+const events = typeof window === "undefined" ? null : window;
+const pointer =
+  events && typeof events.matchMedia === "function"
+    ? events.matchMedia("(hover: hover) and (pointer: fine)")
+    : null;
+export const hardwareKeyboardPresence = createWebHardwareKeyboardPresence(pointer, events);
diff --git a/packages/app/src/keyboard/internal/sources/contract.ts b/packages/app/src/keyboard/internal/sources/contract.ts
new file mode 100644
index 0000000000..886dbc3548
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/contract.ts
@@ -0,0 +1,27 @@
+import type { KeyboardFocusScope } from "../../actions";
+import type { KeyboardInputEvent } from "../overlays";
+export interface KeyboardSourceInput {
+  event: KeyboardInputEvent;
+  focusScope: KeyboardFocusScope;
+  captureFocusRestore(): void;
+}
+export interface KeyboardSourceHandlers {
+  keyDown(input: KeyboardSourceInput): void;
+  keyUp(event: KeyboardInputEvent): void;
+  blur(): void;
+  commandCenterOpen(): boolean;
+}
+export function nativeKeyboardInput(
+  event: KeyboardInputEvent,
+  focusScope: KeyboardFocusScope,
+): KeyboardSourceInput {
+  return { event, focusScope, captureFocusRestore() {} };
+}
+
+import type { ChordState, ParsedShortcutBinding } from "../../keyboard-shortcuts";
+export interface KeyboardPolicyInput {
+  bindings: readonly ParsedShortcutBinding[];
+  chordState?: ChordState;
+  isMac: boolean;
+  enabled: boolean;
+}
diff --git a/packages/app/src/keyboard/internal/sources/dom.web.ts b/packages/app/src/keyboard/internal/sources/dom.web.ts
new file mode 100644
index 0000000000..004be62836
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/dom.web.ts
@@ -0,0 +1,44 @@
+import { resolveKeyboardFocusScope } from "../../focus-scope";
+import { setCommandCenterFocusRestoreElement } from "@/utils/command-center-focus-restore";
+import { keyBelongsToDomPopover } from "../dom-popover";
+import type { KeyboardSourceHandlers } from "./contract";
+export function attachDomKeyboardSource(handlers: KeyboardSourceHandlers): () => void {
+  const down = (event: KeyboardEvent) => {
+    if (document.visibilityState !== "visible" || keyBelongsToDomPopover(event)) return;
+    handlers.keyDown({
+      event: {
+        key: event.key,
+        code: event.code,
+        altKey: event.altKey,
+        ctrlKey: event.ctrlKey,
+        metaKey: event.metaKey,
+        shiftKey: event.shiftKey,
+        repeat: event.repeat,
+        isComposing: event.isComposing || event.keyCode === 229,
+        preventDefault: () => event.preventDefault(),
+        stopPropagation: () => event.stopImmediatePropagation(),
+      },
+      focusScope: resolveKeyboardFocusScope({
+        target: event.target,
+        commandCenterOpen: handlers.commandCenterOpen(),
+      }),
+      captureFocusRestore() {
+        const target = event.target instanceof Element ? event.target : null;
+        const editable = target?.closest("textarea, input, [contenteditable='true']");
+        const focused = editable instanceof HTMLElement ? editable : document.activeElement;
+        setCommandCenterFocusRestoreElement(focused instanceof HTMLElement ? focused : null);
+      },
+    });
+  };
+  const up = (event: KeyboardEvent) => handlers.keyUp(event);
+  window.addEventListener("keydown", down, true);
+  window.addEventListener("keyup", up, true);
+  window.addEventListener("blur", handlers.blur);
+  document.addEventListener("visibilitychange", handlers.blur);
+  return () => {
+    window.removeEventListener("keydown", down, true);
+    window.removeEventListener("keyup", up, true);
+    window.removeEventListener("blur", handlers.blur);
+    document.removeEventListener("visibilitychange", handlers.blur);
+  };
+}
diff --git a/packages/app/src/desktop/browser/shortcuts.test.ts b/packages/app/src/keyboard/internal/sources/electron-browser.test.ts
similarity index 75%
rename from packages/app/src/desktop/browser/shortcuts.test.ts
rename to packages/app/src/keyboard/internal/sources/electron-browser.test.ts
index 804ed73369..abcc98b7fd 100644
--- a/packages/app/src/desktop/browser/shortcuts.test.ts
+++ b/packages/app/src/keyboard/internal/sources/electron-browser.test.ts
@@ -1,10 +1,11 @@
 import { describe, expect, it } from "vitest";
 import {
+  attachElectronBrowserSource,
   buildBrowserKeyboardPolicy,
   parseBrowserShortcutInput,
   shouldPublishBrowserShortcutPolicy,
-} from "./shortcuts";
-import { buildEffectiveBindings, resolveKeyboardShortcut } from "../../keyboard/keyboard-shortcuts";
+} from "./electron-browser";
+import { buildEffectiveBindings, resolveKeyboardShortcut } from "../../keyboard-shortcuts";
 
 describe("buildBrowserKeyboardPolicy", () => {
   it("publishes only chord starts while no browser chord is pending", () => {
@@ -13,7 +14,11 @@ describe("buildBrowserKeyboardPolicy", () => {
       "workspace-terminal-new-ctrl-shift-t-non-mac": "Ctrl+F12 Ctrl+F11",
     });
 
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: false, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({
+      bindings,
+      isMac: false,
+      usesDesktopBindings: true,
+    });
 
     expect(policy.prefixes).toContainEqual({
       alt: false,
@@ -51,7 +56,7 @@ describe("buildBrowserKeyboardPolicy", () => {
       bindings,
       chordState: { candidateIndices: [chordIndex], step: 1, timeoutId: null },
       isMac: false,
-      isDesktop: true,
+      usesDesktopBindings: true,
     });
 
     expect(policy.prefixes).toEqual([
@@ -85,7 +90,7 @@ describe("buildBrowserKeyboardPolicy", () => {
       context: {
         commandCenterOpen: false,
         focusScope: "browser",
-        isDesktop: true,
+        usesDesktopBindings: true,
         isMac: false,
       },
       chordState: { candidateIndices: [chordIndex], step: 1, timeoutId: null },
@@ -101,7 +106,11 @@ describe("buildBrowserKeyboardPolicy", () => {
       "settings-toggle-ctrl-comma-non-mac": "Ctrl+F10 F9",
     });
 
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: false, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({
+      bindings,
+      isMac: false,
+      usesDesktopBindings: true,
+    });
 
     expect(policy.prefixes).not.toContainEqual({
       alt: false,
@@ -125,7 +134,7 @@ describe("buildBrowserKeyboardPolicy", () => {
     });
 
     expect(
-      buildBrowserKeyboardPolicy({ bindings, isMac: true, isDesktop: true }).prefixes,
+      buildBrowserKeyboardPolicy({ bindings, isMac: true, usesDesktopBindings: true }).prefixes,
     ).toContainEqual({
       alt: false,
       code: "KeyY",
@@ -141,7 +150,11 @@ describe("buildBrowserKeyboardPolicy", () => {
       "workspace-tab-close-current-ctrl-w-non-mac": "Ctrl+Y",
     });
 
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: false, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({
+      bindings,
+      isMac: false,
+      usesDesktopBindings: true,
+    });
 
     expect(policy.prefixes).not.toContainEqual({
       alt: false,
@@ -164,7 +177,7 @@ describe("buildBrowserKeyboardPolicy", () => {
   it("leaves macOS browser back and forward shortcuts in the guest", () => {
     const bindings = buildEffectiveBindings({});
 
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, usesDesktopBindings: true });
 
     for (const code of ["BracketLeft", "BracketRight"]) {
       expect(policy.prefixes).not.toContainEqual({
@@ -180,7 +193,7 @@ describe("buildBrowserKeyboardPolicy", () => {
 
   it("marks editable-only exclusions for enforcement inside the guest", () => {
     const bindings = buildEffectiveBindings({});
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, usesDesktopBindings: true });
 
     expect(policy.prefixes).toContainEqual({
       alt: false,
@@ -194,7 +207,11 @@ describe("buildBrowserKeyboardPolicy", () => {
 
   it("does not publish plain browser keys", () => {
     const bindings = buildEffectiveBindings({});
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: false, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({
+      bindings,
+      isMac: false,
+      usesDesktopBindings: true,
+    });
 
     expect(policy.prefixes).not.toContainEqual({
       alt: false,
@@ -214,7 +231,7 @@ describe("buildBrowserKeyboardPolicy", () => {
 
   it("publishes Cmd+B with its logical key for non-QWERTY layouts", () => {
     const bindings = buildEffectiveBindings({});
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, usesDesktopBindings: true });
 
     expect(policy.prefixes).toContainEqual({
       alt: false,
@@ -228,7 +245,7 @@ describe("buildBrowserKeyboardPolicy", () => {
 
   it("publishes the physical code needed for macOS Option shortcuts", () => {
     const bindings = buildEffectiveBindings({});
-    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, isDesktop: true });
+    const policy = buildBrowserKeyboardPolicy({ bindings, isMac: true, usesDesktopBindings: true });
 
     expect(policy.prefixes).toContainEqual({
       alt: true,
@@ -320,3 +337,49 @@ describe("parseBrowserShortcutInput", () => {
     expect(parseBrowserShortcutInput(payload)).toBeNull();
   });
 });
+
+describe("Electron guest source through shared resolution", () => {
+  it("replays guest input through user rebinds and preserves focus restoration", async () => {
+    const { createKeyboardPipeline } = await import("../pipeline");
+    const { createOverlayRegistry } = await import("../overlays");
+    const actions: string[] = [];
+    const restored: string[] = [];
+    let receive: (payload: unknown) => void = () => {};
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({ "command-center-toggle-cmd-k-mac": "Cmd+J" }),
+      isCapturing: () => false,
+      overlays: createOverlayRegistry(),
+      dispatch: (match, input) => {
+        actions.push(match.action);
+        input.captureFocusRestore();
+        return true;
+      },
+    });
+    const detach = attachElectronBrowserSource(
+      {
+        subscribe(handler) {
+          receive = handler;
+          return () => {
+            receive = () => {};
+          };
+        },
+        captureFocusRestore: (id) => restored.push(id),
+      },
+      { keyDown: pipeline.keyDown, keyUp() {}, blur() {}, commandCenterOpen: () => false },
+    );
+    receive({
+      browserId: "tab-1",
+      key: "j",
+      code: "KeyJ",
+      alt: false,
+      control: false,
+      meta: true,
+      shift: false,
+    });
+    expect(actions).toEqual(["command-center.toggle"]);
+    expect(restored).toEqual(["tab-1"]);
+    detach();
+    pipeline.dispose();
+  });
+});
diff --git a/packages/app/src/desktop/browser/shortcuts.ts b/packages/app/src/keyboard/internal/sources/electron-browser.ts
similarity index 84%
rename from packages/app/src/desktop/browser/shortcuts.ts
rename to packages/app/src/keyboard/internal/sources/electron-browser.ts
index 2bd7def5ed..64c6edb754 100644
--- a/packages/app/src/desktop/browser/shortcuts.ts
+++ b/packages/app/src/keyboard/internal/sources/electron-browser.ts
@@ -3,8 +3,8 @@ import {
   matchesKeyboardShortcutContext,
   type KeyboardShortcutInput,
   type ParsedShortcutBinding,
-} from "../../keyboard/keyboard-shortcuts";
-import type { KeyCombo } from "../../keyboard/shortcut-string";
+} from "../../keyboard-shortcuts";
+import type { KeyCombo } from "../../shortcut-string";
 
 export interface BrowserShortcutPrefix {
   alt: boolean;
@@ -32,7 +32,7 @@ interface BrowserShortcutPolicyInput {
   bindings: readonly ParsedShortcutBinding[];
   chordState?: ChordState;
   isMac: boolean;
-  isDesktop: boolean;
+  usesDesktopBindings: boolean;
 }
 
 export function shouldPublishBrowserShortcutPolicy(input: {
@@ -149,7 +149,7 @@ function buildBrowserShortcutPrefixes(input: BrowserShortcutPolicyInput): Browse
   const prefixes = new Map<string, BrowserShortcutPrefix>();
   const context = {
     isMac: input.isMac,
-    isDesktop: input.isDesktop,
+    usesDesktopBindings: input.usesDesktopBindings,
     focusScope: "browser" as const,
     commandCenterOpen: false,
   };
@@ -209,3 +209,26 @@ export function buildBrowserKeyboardPolicy(
   }
   return { menuPrefixes, prefixes };
 }
+
+interface ElectronBrowserKeySource {
+  subscribe(handler: (payload: unknown) => void): (() => void) | Promise<() => void>;
+  captureFocusRestore(browserId: string): void;
+}
+export function attachElectronBrowserSource(
+  source: ElectronBrowserKeySource,
+  handlers: import("./contract").KeyboardSourceHandlers,
+): () => void {
+  const subscription = source.subscribe((payload) => {
+    const input = parseBrowserShortcutInput(payload);
+    if (!input) return;
+    handlers.keyDown({
+      event: { ...input, preventDefault() {}, stopPropagation() {} },
+      focusScope: "browser",
+      captureFocusRestore: () => source.captureFocusRestore(input.browserId),
+    });
+  });
+  return () => {
+    if (typeof subscription === "function") subscription();
+    else void subscription.then((dispose) => dispose());
+  };
+}
diff --git a/packages/app/src/keyboard/internal/sources/hardware.android.ts b/packages/app/src/keyboard/internal/sources/hardware.android.ts
new file mode 100644
index 0000000000..cfe7a15cb9
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/hardware.android.ts
@@ -0,0 +1,29 @@
+import { requireNativeModule } from "expo-modules-core";
+import type { HardwareKeyboardEvent } from "./hardware";
+interface HardwareKeyboardModule {
+  getHardwareKeyboardPresent(): boolean;
+  addListener(event: "onHardwareKeyboardPresenceChanged", handler: () => void): { remove(): void };
+  setOverlayKeys(keys: readonly string[]): void;
+  addListener(
+    event: "onHardwareKeyboardShortcut",
+    handler: (event: HardwareKeyboardEvent) => void,
+  ): { remove(): void };
+}
+const module = requireNativeModule<HardwareKeyboardModule>("PaseoHardwareKeyboard");
+export function subscribeHardwareKeyboard(
+  handler: (event: HardwareKeyboardEvent) => void,
+): () => void {
+  const subscription = module.addListener("onHardwareKeyboardShortcut", handler);
+  return () => subscription.remove();
+}
+export function setHardwareKeyboardOverlayKeys(keys: readonly string[]): void {
+  module.setOverlayKeys(keys);
+}
+
+export function getHardwareKeyboardPresent(): boolean {
+  return module.getHardwareKeyboardPresent();
+}
+export function subscribeHardwareKeyboardPresence(changed: () => void): () => void {
+  const subscription = module.addListener("onHardwareKeyboardPresenceChanged", changed);
+  return () => subscription.remove();
+}
diff --git a/packages/app/src/keyboard/internal/sources/hardware.ios.ts b/packages/app/src/keyboard/internal/sources/hardware.ios.ts
new file mode 100644
index 0000000000..cfe7a15cb9
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/hardware.ios.ts
@@ -0,0 +1,29 @@
+import { requireNativeModule } from "expo-modules-core";
+import type { HardwareKeyboardEvent } from "./hardware";
+interface HardwareKeyboardModule {
+  getHardwareKeyboardPresent(): boolean;
+  addListener(event: "onHardwareKeyboardPresenceChanged", handler: () => void): { remove(): void };
+  setOverlayKeys(keys: readonly string[]): void;
+  addListener(
+    event: "onHardwareKeyboardShortcut",
+    handler: (event: HardwareKeyboardEvent) => void,
+  ): { remove(): void };
+}
+const module = requireNativeModule<HardwareKeyboardModule>("PaseoHardwareKeyboard");
+export function subscribeHardwareKeyboard(
+  handler: (event: HardwareKeyboardEvent) => void,
+): () => void {
+  const subscription = module.addListener("onHardwareKeyboardShortcut", handler);
+  return () => subscription.remove();
+}
+export function setHardwareKeyboardOverlayKeys(keys: readonly string[]): void {
+  module.setOverlayKeys(keys);
+}
+
+export function getHardwareKeyboardPresent(): boolean {
+  return module.getHardwareKeyboardPresent();
+}
+export function subscribeHardwareKeyboardPresence(changed: () => void): () => void {
+  const subscription = module.addListener("onHardwareKeyboardPresenceChanged", changed);
+  return () => subscription.remove();
+}
diff --git a/packages/app/src/keyboard/internal/sources/hardware.ts b/packages/app/src/keyboard/internal/sources/hardware.ts
new file mode 100644
index 0000000000..c6631886d1
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/hardware.ts
@@ -0,0 +1,18 @@
+import type { KeyboardShortcutInput } from "../../keyboard-shortcuts";
+export interface HardwareKeyboardEvent extends KeyboardShortcutInput {
+  isComposing: boolean;
+  phase: "down" | "up";
+}
+export function subscribeHardwareKeyboard(
+  _handler: (event: HardwareKeyboardEvent) => void,
+): () => void {
+  return () => {};
+}
+export function setHardwareKeyboardOverlayKeys(_keys: readonly string[]): void {}
+
+export function getHardwareKeyboardPresent(): boolean {
+  return false;
+}
+export function subscribeHardwareKeyboardPresence(_changed: () => void): () => void {
+  return () => {};
+}
diff --git a/packages/app/src/keyboard/internal/sources/index.ts b/packages/app/src/keyboard/internal/sources/index.ts
new file mode 100644
index 0000000000..5d886b979a
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/index.ts
@@ -0,0 +1,11 @@
+import type { KeyboardSourceHandlers } from "./contract";
+import { setHardwareKeyboardOverlayKeys, subscribeHardwareKeyboard } from "./hardware";
+import { attachHardwareKeyboardSource } from "./native";
+export function attachKeyboardSources(handlers: KeyboardSourceHandlers): () => void {
+  return attachHardwareKeyboardSource(
+    { subscribe: subscribeHardwareKeyboard, setOverlayKeys: setHardwareKeyboardOverlayKeys },
+    handlers,
+  );
+}
+
+export function publishKeyboardPolicy(_input: import("./contract").KeyboardPolicyInput): void {}
diff --git a/packages/app/src/keyboard/internal/sources/index.web.ts b/packages/app/src/keyboard/internal/sources/index.web.ts
new file mode 100644
index 0000000000..da6023be5b
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/index.web.ts
@@ -0,0 +1,32 @@
+import { usesDesktopBindings } from "../conventions";
+import { getDesktopHost } from "@/desktop/host";
+import { getResidentBrowserWebview } from "@/desktop/browser/resident-webviews";
+import { setCommandCenterFocusRestoreElement } from "@/utils/command-center-focus-restore";
+import { buildBrowserKeyboardPolicy, attachElectronBrowserSource } from "./electron-browser";
+import { attachDomKeyboardSource } from "./dom.web";
+import type { KeyboardSourceHandlers } from "./contract";
+export function attachKeyboardSources(handlers: KeyboardSourceHandlers): () => void {
+  const detachDom = attachDomKeyboardSource(handlers);
+  const host = getDesktopHost();
+  const subscribeGuest = host?.events?.on;
+  const detachGuest = subscribeGuest
+    ? attachElectronBrowserSource(
+        {
+          subscribe: (handler) => subscribeGuest("browser-shortcut-input", handler),
+          captureFocusRestore: (browserId) =>
+            setCommandCenterFocusRestoreElement(getResidentBrowserWebview(browserId)),
+        },
+        handlers,
+      )
+    : () => {};
+  return () => {
+    detachDom();
+    detachGuest();
+  };
+}
+export function publishKeyboardPolicy(input: import("./contract").KeyboardPolicyInput): void {
+  const policy = input.enabled
+    ? buildBrowserKeyboardPolicy({ ...input, usesDesktopBindings: usesDesktopBindings })
+    : { menuPrefixes: [], prefixes: [] };
+  void getDesktopHost()?.browser?.setShortcutPolicy?.(policy);
+}
diff --git a/packages/app/src/keyboard/internal/sources/native.ts b/packages/app/src/keyboard/internal/sources/native.ts
new file mode 100644
index 0000000000..995e9df491
--- /dev/null
+++ b/packages/app/src/keyboard/internal/sources/native.ts
@@ -0,0 +1,31 @@
+import { focusSurfaces } from "../focus-surfaces";
+import { overlays } from "../overlays";
+import { nativeKeyboardInput, type KeyboardSourceHandlers } from "./contract";
+import type { HardwareKeyboardEvent } from "./hardware";
+interface HardwareKeySource {
+  subscribe(handler: (event: HardwareKeyboardEvent) => void): () => void;
+  setOverlayKeys(keys: readonly string[]): void;
+}
+export function attachHardwareKeyboardSource(
+  source: HardwareKeySource,
+  handlers: KeyboardSourceHandlers,
+): () => void {
+  const updateKeys = () => source.setOverlayKeys(overlays.getKeys());
+  updateKeys();
+  const unsubscribeOverlays = overlays.subscribe(updateKeys);
+  const unsubscribeHardware = source.subscribe((input) => {
+    const event = { ...input, preventDefault() {}, stopPropagation() {} };
+    if (input.phase === "up") {
+      handlers.keyUp(event);
+      return;
+    }
+    handlers.keyDown(
+      nativeKeyboardInput(event, focusSurfaces.resolve(handlers.commandCenterOpen())),
+    );
+  });
+  return () => {
+    unsubscribeHardware();
+    unsubscribeOverlays();
+    source.setOverlayKeys([]);
+  };
+}
diff --git a/packages/app/src/keyboard/internal/use-focus-surface.ts b/packages/app/src/keyboard/internal/use-focus-surface.ts
new file mode 100644
index 0000000000..e10514285e
--- /dev/null
+++ b/packages/app/src/keyboard/internal/use-focus-surface.ts
@@ -0,0 +1,7 @@
+import { useLayoutEffect } from "react";
+import { focusSurfaces, type KeyboardFocusSurface } from "./focus-surfaces";
+export function useKeyboardFocusSurface(surface: KeyboardFocusSurface, focused: boolean): void {
+  useLayoutEffect(() => {
+    if (focused) return focusSurfaces.declare(surface);
+  }, [surface, focused]);
+}
diff --git a/packages/app/src/keyboard/internal/use-focus-surface.web.ts b/packages/app/src/keyboard/internal/use-focus-surface.web.ts
new file mode 100644
index 0000000000..6f74924a81
--- /dev/null
+++ b/packages/app/src/keyboard/internal/use-focus-surface.web.ts
@@ -0,0 +1,2 @@
+import type { KeyboardFocusSurface } from "./focus-surfaces";
+export function useKeyboardFocusSurface(_surface: KeyboardFocusSurface, _focused: boolean): void {}
diff --git a/packages/app/src/keyboard/keyboard-action-dispatcher.ts b/packages/app/src/keyboard/keyboard-action-dispatcher.ts
index a3f2b4c515..ba27e4b354 100644
--- a/packages/app/src/keyboard/keyboard-action-dispatcher.ts
+++ b/packages/app/src/keyboard/keyboard-action-dispatcher.ts
@@ -51,6 +51,7 @@ export type KeyboardActionId =
   | "workspace.project.pick"
   | "worktree.new"
   | "workspace.archive"
+  | "workspace.archive.undo"
   | "workspace.pin"
   // Command-center only: no keybind, so these are absent from route-shortcut.ts.
   | "workspace.rename"
@@ -109,6 +110,7 @@ export type KeyboardActionDefinition =
   | { id: "workspace.project.pick"; scope: KeyboardActionScope }
   | { id: "worktree.new"; scope: KeyboardActionScope }
   | { id: "workspace.archive"; scope: KeyboardActionScope }
+  | { id: "workspace.archive.undo"; scope: KeyboardActionScope }
   | { id: "workspace.pin"; scope: KeyboardActionScope }
   | { id: "workspace.rename"; scope: KeyboardActionScope }
   | { id: "workspace.setup.show"; scope: KeyboardActionScope };
diff --git a/packages/app/src/keyboard/keyboard-shortcuts.test.ts b/packages/app/src/keyboard/keyboard-shortcuts.test.ts
index 770d7e710c..9eddf4b5b5 100644
--- a/packages/app/src/keyboard/keyboard-shortcuts.test.ts
+++ b/packages/app/src/keyboard/keyboard-shortcuts.test.ts
@@ -40,7 +40,7 @@ function shortcutContext(
 ): KeyboardShortcutContext {
   return {
     isMac: false,
-    isDesktop: false,
+    usesDesktopBindings: false,
     focusScope: "other",
     commandCenterOpen: false,
     ...overrides,
@@ -128,7 +128,7 @@ interface HelpSectionCase {
   name: string;
   context: {
     isMac: boolean;
-    isDesktop: boolean;
+    usesDesktopBindings: boolean;
   };
   expectedKeys: Record<string, string[]>;
 }
@@ -174,49 +174,49 @@ describe("keyboard-shortcuts", () => {
     {
       name: "matches workspace index jump on web via Alt+digit",
       event: { key: "2", code: "Digit2", altKey: true },
-      context: { isDesktop: false },
+      context: { usesDesktopBindings: false },
       action: "workspace.navigate.index",
       payload: { index: 2 },
     },
     {
       name: "matches workspace index jump on desktop via Mod+digit",
       event: { key: "2", code: "Digit2", metaKey: true },
-      context: { isMac: true, isDesktop: true },
+      context: { isMac: true, usesDesktopBindings: true },
       action: "workspace.navigate.index",
       payload: { index: 2 },
     },
     {
       name: "matches tab index jump on mac desktop via Cmd+Alt+digit",
       event: { key: "@", code: "Digit2", metaKey: true, altKey: true },
-      context: { isMac: true, isDesktop: true },
+      context: { isMac: true, usesDesktopBindings: true },
       action: "workspace.tab.navigate.index",
       payload: { index: 2 },
     },
     {
       name: "matches tab index jump on non-mac desktop via Alt+digit",
       event: { key: "2", code: "Digit2", altKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       action: "workspace.tab.navigate.index",
       payload: { index: 2 },
     },
     {
       name: "matches tab index jump on web via Alt+Shift+digit",
       event: { key: "@", code: "Digit2", altKey: true, shiftKey: true },
-      context: { isDesktop: false },
+      context: { usesDesktopBindings: false },
       action: "workspace.tab.navigate.index",
       payload: { index: 2 },
     },
     {
       name: "matches workspace relative navigation on web via Alt+[",
       event: { key: "[", code: "BracketLeft", altKey: true },
-      context: { isDesktop: false },
+      context: { usesDesktopBindings: false },
       action: "workspace.navigate.relative",
       payload: { delta: -1 },
     },
     {
       name: "matches workspace relative navigation on desktop via Mod+]",
       event: { key: "]", code: "BracketRight", ctrlKey: true },
-      context: { isDesktop: true },
+      context: { usesDesktopBindings: true },
       action: "workspace.navigate.relative",
       payload: { delta: 1 },
     },
@@ -235,19 +235,19 @@ describe("keyboard-shortcuts", () => {
     {
       name: "matches Alt+Shift+W to close current tab on web",
       event: { key: "W", code: "KeyW", altKey: true, shiftKey: true },
-      context: { isDesktop: false },
+      context: { usesDesktopBindings: false },
       action: "workspace.tab.close.current",
     },
     {
       name: "matches Cmd+W to close current tab on mac desktop",
       event: { key: "w", code: "KeyW", metaKey: true },
-      context: { isMac: true, isDesktop: true },
+      context: { isMac: true, usesDesktopBindings: true },
       action: "workspace.tab.close.current",
     },
     {
       name: "matches Ctrl+W to close current tab on non-mac desktop",
       event: { key: "w", code: "KeyW", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       action: "workspace.tab.close.current",
     },
     {
@@ -371,7 +371,7 @@ describe("keyboard-shortcuts", () => {
     {
       name: "matches Alt+[ to previous workspace on macOS web when Option substitutes event.key",
       event: { key: "\u201C", code: "BracketLeft", altKey: true },
-      context: { isMac: true, isDesktop: false },
+      context: { isMac: true, usesDesktopBindings: false },
       action: "workspace.navigate.relative",
       payload: { delta: -1 },
       preventDefault: true,
@@ -380,7 +380,7 @@ describe("keyboard-shortcuts", () => {
     {
       name: "matches Alt+] to next workspace on macOS web when Option substitutes event.key",
       event: { key: "\u2018", code: "BracketRight", altKey: true },
-      context: { isMac: true, isDesktop: false },
+      context: { isMac: true, usesDesktopBindings: false },
       action: "workspace.navigate.relative",
       payload: { delta: 1 },
       preventDefault: true,
@@ -389,7 +389,7 @@ describe("keyboard-shortcuts", () => {
     {
       name: "matches Alt+Shift+W to close current tab on macOS web when Option substitutes event.key",
       event: { key: "\u201E", code: "KeyW", altKey: true, shiftKey: true },
-      context: { isMac: true, isDesktop: false },
+      context: { isMac: true, usesDesktopBindings: false },
       action: "workspace.tab.close.current",
     },
   ];
@@ -408,6 +408,25 @@ describe("keyboard-shortcuts", () => {
     },
   );
 
+  describe("undo archive workspace", () => {
+    it.each([
+      { isMac: true, event: { key: "z", code: "KeyZ", metaKey: true } },
+      { isMac: false, event: { key: "z", code: "KeyZ", ctrlKey: true } },
+    ])("routes Cmd/Ctrl+Z outside text and terminals (mac: $isMac)", ({ isMac, event }) => {
+      expectShortcutResolution({ event, context: { isMac }, action: "workspace.archive.undo" });
+    });
+
+    it.each(["editable", "message-input", "terminal"] as const)(
+      "leaves Cmd+Z to the focused %s",
+      (focusScope) => {
+        expectNoShortcutResolution({
+          event: { key: "z", code: "KeyZ", metaKey: true },
+          context: { isMac: true, focusScope },
+        });
+      },
+    );
+  });
+
   it("leaves Escape to an editable field", () => {
     expectNoShortcutResolution({
       event: { key: "Escape", code: "Escape" },
@@ -453,12 +472,12 @@ describe("keyboard-shortcuts", () => {
     {
       name: "does not close tab with Ctrl+W on mac desktop (Cmd+W only)",
       event: { key: "w", code: "KeyW", ctrlKey: true },
-      context: { isMac: true, isDesktop: true },
+      context: { isMac: true, usesDesktopBindings: true },
     },
     {
       name: "does not close tab with Ctrl+W on non-mac desktop when terminal is focused",
       event: { key: "w", code: "KeyW", ctrlKey: true },
-      context: { isMac: false, isDesktop: true, focusScope: "terminal" },
+      context: { isMac: false, usesDesktopBindings: true, focusScope: "terminal" },
     },
     {
       name: "does not match Ctrl+T on mac (Cmd only)",
@@ -468,7 +487,7 @@ describe("keyboard-shortcuts", () => {
     {
       name: "keeps mac Option+digit available for international text input",
       event: { key: "@", code: "Digit2", altKey: true },
-      context: { isMac: true, isDesktop: true, focusScope: "message-input" },
+      context: { isMac: true, usesDesktopBindings: true, focusScope: "message-input" },
     },
     {
       name: "does not match Ctrl+K for command center on non-mac in terminal",
@@ -538,7 +557,7 @@ describe("keyboard-shortcuts", () => {
     {
       name: "keeps Dvorak Cmd+V available for paste in message input",
       event: { key: "v", code: "Period", metaKey: true },
-      context: { isMac: true, isDesktop: true, focusScope: "message-input" },
+      context: { isMac: true, usesDesktopBindings: true, focusScope: "message-input" },
     },
     // Sanity: the macOS Option-substitution fallback must still respect
     // modifier checks — pressing Option+T alone (no Cmd) must not trigger
@@ -595,7 +614,7 @@ describe("keyboard-shortcuts", () => {
 
     const firstResult = resolveShortcut({
       event: { key: "w", code: "KeyW", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       bindings,
     });
 
@@ -606,7 +625,7 @@ describe("keyboard-shortcuts", () => {
 
     const secondResult = resolveShortcut({
       event: { key: "s", code: "KeyS" },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       chordState: firstResult.nextChordState,
       bindings,
     });
@@ -622,7 +641,7 @@ describe("keyboard-shortcuts", () => {
   it("resolves a browser-origin shortcut with browser focus instead of host focus", () => {
     expectShortcutResolution({
       event: { key: "t", code: "KeyT", ctrlKey: true },
-      context: { isDesktop: true, focusScope: "browser" },
+      context: { usesDesktopBindings: true, focusScope: "browser" },
       action: "workspace.tab.menu.open",
     });
   });
@@ -636,12 +655,12 @@ describe("keyboard-shortcuts", () => {
     // so the stream for Ctrl+K, release, Ctrl+J is four keydowns, not two.
     const firstModifier = resolveShortcut({
       event: { key: "Control", code: "ControlLeft", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       bindings,
     });
     const firstStep = resolveShortcut({
       event: { key: "k", code: "KeyK", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       chordState: firstModifier.nextChordState,
       bindings,
     });
@@ -649,13 +668,13 @@ describe("keyboard-shortcuts", () => {
 
     const secondModifier = resolveShortcut({
       event: { key: "Control", code: "ControlLeft", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       chordState: firstStep.nextChordState,
       bindings,
     });
     const secondStep = resolveShortcut({
       event: { key: "j", code: "KeyJ", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       chordState: secondModifier.nextChordState,
       bindings,
     });
@@ -673,7 +692,7 @@ describe("keyboard-shortcuts", () => {
 
     const result = resolveShortcut({
       event: { key: "w", code: "KeyW", ctrlKey: true },
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       onChordReset,
       bindings,
     });
@@ -703,7 +722,7 @@ describe("keyboard-shortcut help sections", () => {
   const helpCases: HelpSectionCase[] = [
     {
       name: "uses web defaults for workspace and tab jump",
-      context: { isMac: true, isDesktop: false },
+      context: { isMac: true, usesDesktopBindings: false },
       expectedKeys: {
         "new-agent": ["mod", "O"],
         "workspace-tab-new": ["mod", "T"],
@@ -717,7 +736,7 @@ describe("keyboard-shortcut help sections", () => {
     },
     {
       name: "uses desktop defaults for workspace and tab jump",
-      context: { isMac: true, isDesktop: true },
+      context: { isMac: true, usesDesktopBindings: true },
       expectedKeys: {
         "new-agent": ["mod", "O"],
         "new-workspace": ["mod", "N"],
@@ -735,7 +754,7 @@ describe("keyboard-shortcut help sections", () => {
     },
     {
       name: "uses non-mac desktop defaults for tab jump and close tab",
-      context: { isMac: false, isDesktop: true },
+      context: { isMac: false, usesDesktopBindings: true },
       expectedKeys: {
         "workspace-tab-jump-index": ["alt", "1-9"],
         "workspace-tab-close-current": ["ctrl", "W"],
@@ -743,7 +762,7 @@ describe("keyboard-shortcut help sections", () => {
     },
     {
       name: "uses ctrl+b for the left sidebar and ctrl+period for both sidebars on non-mac",
-      context: { isMac: false, isDesktop: false },
+      context: { isMac: false, usesDesktopBindings: false },
       // Derived from `combo: "Ctrl+B"` / `"Ctrl+."`, so the token is `ctrl` where
       // these rows used to be hand-authored as `mod`. Both bindings are non-mac
       // only and `formatShortcut` labels either token "Ctrl" there, so the badge
@@ -764,7 +783,7 @@ describe("keyboard-shortcut help sections", () => {
   });
 
   describe("rows derive their keys from the binding that fires", () => {
-    const macDesktop = { isMac: true, isDesktop: true };
+    const macDesktop = { isMac: true, usesDesktopBindings: true };
     const NEW_WORKSPACE_BINDING = "workspace-new-cmd-n-mac";
     const MAC_INDEX_BINDING = "workspace-navigate-index-cmd-digit-mac";
     const PANE_FOCUS_LEFT_BINDING = "workspace-pane-focus-left-cmd-shift-left";
@@ -849,7 +868,10 @@ describe("keyboard-shortcut help sections", () => {
     // Same story on the other side: these rows said `mod`, the non-mac combos
     // say `Ctrl`, and non-mac labels both as "Ctrl".
     it("still renders the sidebar toggles as Ctrl+B and Ctrl+. on non-mac", () => {
-      const sections = buildKeyboardShortcutHelpSections({ isMac: false, isDesktop: false });
+      const sections = buildKeyboardShortcutHelpSections({
+        isMac: false,
+        usesDesktopBindings: false,
+      });
       const left = findRow(sections, "toggle-left-sidebar")?.chord;
       const both = findRow(sections, "toggle-both-sidebars")?.chord;
       expect(formatShortcut(left?.[0] ?? [], "non-mac")).toBe("Ctrl+B");
@@ -858,7 +880,7 @@ describe("keyboard-shortcut help sections", () => {
   });
 
   it("returns stable i18n keys for section titles and help rows", () => {
-    const sections = buildKeyboardShortcutHelpSections({ isMac: true, isDesktop: true });
+    const sections = buildKeyboardShortcutHelpSections({ isMac: true, usesDesktopBindings: true });
     const workspaces = sections.find((section) => section.id === "workspaces");
     const layout = sections.find((section) => section.id === "layout");
     const openProject = findRow(sections, "new-agent");
@@ -875,10 +897,10 @@ describe("keyboard-shortcut help sections", () => {
 
   it("gives every help row an explicit place in its section's order", () => {
     const platforms = [
-      { isMac: true, isDesktop: true },
-      { isMac: false, isDesktop: true },
-      { isMac: true, isDesktop: false },
-      { isMac: false, isDesktop: false },
+      { isMac: true, usesDesktopBindings: true },
+      { isMac: false, usesDesktopBindings: true },
+      { isMac: true, usesDesktopBindings: false },
+      { isMac: false, usesDesktopBindings: false },
     ];
     const unplaced: string[] = [];
     for (const platform of platforms) {
@@ -894,7 +916,7 @@ describe("keyboard-shortcut help sections", () => {
   });
 
   it("leads the general section with the command center and file search", () => {
-    const sections = buildKeyboardShortcutHelpSections({ isMac: true, isDesktop: true });
+    const sections = buildKeyboardShortcutHelpSections({ isMac: true, usesDesktopBindings: true });
 
     expect(sections[0]?.id).toBe("general");
     expect(sections[0]?.rows.slice(0, 2).map((row) => row.id)).toEqual([
@@ -904,28 +926,30 @@ describe("keyboard-shortcut help sections", () => {
   });
 
   it("reuses the project-picker binding ids for rebindable file search", () => {
-    expect(getBindingIdForAction("search-files", { isMac: true, isDesktop: true })).toBe(
+    expect(getBindingIdForAction("search-files", { isMac: true, usesDesktopBindings: true })).toBe(
       "workspace-project-pick-cmd-p-mac",
     );
-    expect(getBindingIdForAction("search-files", { isMac: false, isDesktop: true })).toBe(
+    expect(getBindingIdForAction("search-files", { isMac: false, usesDesktopBindings: true })).toBe(
       "workspace-project-pick-ctrl-p-non-mac",
     );
     expect(
-      findRow(buildKeyboardShortcutHelpSections({ isMac: true, isDesktop: true }), "search-files")
-        ?.chord,
+      findRow(
+        buildKeyboardShortcutHelpSections({ isMac: true, usesDesktopBindings: true }),
+        "search-files",
+      )?.chord,
     ).not.toBeNull();
   });
 
   it("does not expose Enter send behavior as rebindable shortcut rows", () => {
-    const sections = buildKeyboardShortcutHelpSections({ isMac: true, isDesktop: true });
+    const sections = buildKeyboardShortcutHelpSections({ isMac: true, usesDesktopBindings: true });
 
     expect(findRow(sections, "message-input-send")).toBeNull();
     expect(findRow(sections, "message-input-queue")).toBeNull();
     expect(
-      getBindingIdForAction("message-input-send", { isMac: true, isDesktop: true }),
+      getBindingIdForAction("message-input-send", { isMac: true, usesDesktopBindings: true }),
     ).toBeNull();
     expect(
-      getBindingIdForAction("message-input-queue", { isMac: true, isDesktop: true }),
+      getBindingIdForAction("message-input-queue", { isMac: true, usesDesktopBindings: true }),
     ).toBeNull();
   });
 });
@@ -934,45 +958,61 @@ describe("getWorkspaceIndexJumpModifierKey", () => {
   const MAC_INDEX_BINDING = "workspace-navigate-index-cmd-digit-mac";
 
   it("uses Alt on web, regardless of OS", () => {
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: false })).toBe("Alt");
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: false, isDesktop: false })).toBe("Alt");
-  });
-
-  it("uses Cmd (Meta) on desktop Mac, not Control or Alt", () => {
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true })).toBe("Meta");
-  });
-
-  it("uses Ctrl on desktop non-Mac, not Meta or Alt", () => {
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: false, isDesktop: true })).toBe("Control");
-  });
-
-  it("derives the modifier from the effective binding, not the platform", () => {
-    const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: "Alt+Digit" });
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true }, bindings)).toBe(
+    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: false })).toBe(
+      "Alt",
+    );
+    expect(getWorkspaceIndexJumpModifierKey({ isMac: false, usesDesktopBindings: false })).toBe(
       "Alt",
     );
   });
 
+  it("uses Cmd (Meta) on desktop Mac, not Control or Alt", () => {
+    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true })).toBe(
+      "Meta",
+    );
+  });
+
+  it("uses Ctrl on desktop non-Mac, not Meta or Alt", () => {
+    expect(getWorkspaceIndexJumpModifierKey({ isMac: false, usesDesktopBindings: true })).toBe(
+      "Control",
+    );
+  });
+
+  it("derives the modifier from the effective binding, not the platform", () => {
+    const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: "Alt+Digit" });
+    expect(
+      getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true }, bindings),
+    ).toBe("Alt");
+  });
+
   it("suppresses the badges when the jump shortcut is unassigned", () => {
     const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: UNASSIGNED_COMBO });
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true }, bindings)).toBeNull();
+    expect(
+      getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true }, bindings),
+    ).toBeNull();
   });
 
   it("suppresses the badges when the jump shortcut is rebound to one concrete digit", () => {
     // Capture can only ever produce a concrete digit, never the 1-9 wildcard,
     // so the badges would advertise eight workspaces that no longer respond.
     const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: "Cmd+3" });
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true }, bindings)).toBeNull();
+    expect(
+      getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true }, bindings),
+    ).toBeNull();
   });
 
   it("suppresses the badges for a multi-step chord", () => {
     const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: "Cmd+K Cmd+Digit" });
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true }, bindings)).toBeNull();
+    expect(
+      getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true }, bindings),
+    ).toBeNull();
   });
 
   it("suppresses the badges when the combo needs a second modifier", () => {
     const bindings = buildEffectiveBindings({ [MAC_INDEX_BINDING]: "Cmd+Shift+Digit" });
-    expect(getWorkspaceIndexJumpModifierKey({ isMac: true, isDesktop: true }, bindings)).toBeNull();
+    expect(
+      getWorkspaceIndexJumpModifierKey({ isMac: true, usesDesktopBindings: true }, bindings),
+    ).toBeNull();
   });
 });
 
@@ -999,7 +1039,7 @@ function withoutDefaultCombo(helpId: string): ParsedShortcutBinding[] {
 
 describe("unassigned shortcuts", () => {
   const TAB_NEW_BINDING = "workspace-tab-new-ctrl-t-non-mac";
-  const desktopNonMac = { isMac: false, isDesktop: true };
+  const desktopNonMac = { isMac: false, usesDesktopBindings: true };
 
   function findRow(sections: ReturnType<typeof buildKeyboardShortcutHelpSections>, id: string) {
     for (const section of sections) {
@@ -1102,13 +1142,13 @@ describe("unassigned shortcuts", () => {
       const bindings = buildEffectiveBindings({ "sidebar-toggle-left-mac-cmd-b": combo! });
 
       expect(
-        resolveShortcut({ event, context: { isMac: true, isDesktop: true }, bindings }).match
-          ?.action,
+        resolveShortcut({ event, context: { isMac: true, usesDesktopBindings: true }, bindings })
+          .match?.action,
       ).toBe("sidebar.toggle.left");
       expect(
         resolveShortcut({
           event: { key: "x", code: "KeyB", metaKey: true },
-          context: { isMac: true, isDesktop: true },
+          context: { isMac: true, usesDesktopBindings: true },
           bindings,
         }).match,
       ).toBeNull();
@@ -1293,7 +1333,7 @@ describe("unassigned shortcuts", () => {
 });
 
 describe("direct new-tab target shortcuts", () => {
-  const desktopNonMac = { isMac: false, isDesktop: true };
+  const desktopNonMac = { isMac: false, usesDesktopBindings: true };
   const targetCases = [
     ["a", "KeyA", "workspace.tab.target.agent"],
     ["b", "KeyB", "workspace.tab.target.browser"],
@@ -1323,7 +1363,7 @@ describe("direct new-tab target shortcuts", () => {
   it.each(targetCases)("routes Cmd+Shift+%s directly to %s", (key, code, action) => {
     const result = resolveShortcut({
       event: { key, code, metaKey: true, shiftKey: true },
-      context: { isMac: true, isDesktop: true, focusScope: "other" },
+      context: { isMac: true, usesDesktopBindings: true, focusScope: "other" },
       bindings: buildEffectiveBindings({}),
     });
     expect(result.match?.action).toBe(action);
@@ -1368,19 +1408,19 @@ describe("number-group shortcut capture", () => {
     for (let index = 1; index <= 9; index++) {
       const result = resolveShortcut({
         event: { key: String(index), code: `Digit${index}`, ctrlKey: true },
-        context: { isMac: true, isDesktop: true, focusScope: "message-input" },
+        context: { isMac: true, usesDesktopBindings: true, focusScope: "message-input" },
         bindings,
       });
       expect(result.match?.action).toBe(action);
       expect(result.match?.payload).toEqual({ index });
     }
-    expect(resolveShortcutKeysForAction(row, overrides, { isMac: true, isDesktop: true })).toEqual([
-      ["ctrl", "1-9"],
-    ]);
+    expect(
+      resolveShortcutKeysForAction(row, overrides, { isMac: true, usesDesktopBindings: true }),
+    ).toEqual([["ctrl", "1-9"]]);
     expect(
       resolveShortcut({
         event: { key: "0", code: "Digit0", ctrlKey: true },
-        context: { isMac: true, isDesktop: true },
+        context: { isMac: true, usesDesktopBindings: true },
         bindings,
       }).match,
     ).toBeNull();
diff --git a/packages/app/src/keyboard/keyboard-shortcuts.ts b/packages/app/src/keyboard/keyboard-shortcuts.ts
index 9f6329c013..d6db467da3 100644
--- a/packages/app/src/keyboard/keyboard-shortcuts.ts
+++ b/packages/app/src/keyboard/keyboard-shortcuts.ts
@@ -18,7 +18,7 @@ export type { KeyCombo } from "@/keyboard/shortcut-string";
 
 export interface KeyboardShortcutContext {
   isMac: boolean;
-  isDesktop: boolean;
+  usesDesktopBindings: boolean;
   focusScope: KeyboardFocusScope;
   commandCenterOpen: boolean;
 }
@@ -63,14 +63,14 @@ export interface KeyboardShortcutHelpSection {
 
 interface KeyboardShortcutPlatformContext {
   isMac: boolean;
-  isDesktop: boolean;
+  usesDesktopBindings: boolean;
 }
 
 interface ShortcutWhen {
   /** true = mac only, false = non-mac only */
   mac?: boolean;
-  /** true = desktop only, false = web only */
-  desktop?: boolean;
+  /** Desktop keyboard conventions on Electron/native; browser conventions otherwise. */
+  desktopBindings?: boolean;
   /** false = disabled when a text-editing surface is focused */
   editable?: false;
   /** false = disabled when terminal is focused */
@@ -169,6 +169,7 @@ export const SHORTCUT_HELP_ROW_ORDER: Record<ShortcutSectionId, readonly string[
     "workspace-next",
     "pin-workspace",
     "archive-workspace",
+    "undo-archive-workspace",
   ],
   "tabs-panes": [
     "workspace-tab-new",
@@ -361,6 +362,31 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     },
   },
 
+  // --- Undo archive workspace ---
+  // Only claims the key while an archive can be undone; otherwise text undo runs as usual.
+  {
+    id: "workspace-archive-undo-cmd-z-mac",
+    action: "workspace.archive.undo",
+    combo: "Cmd+Z",
+    when: { mac: true, commandCenter: false, editable: false, terminal: false },
+    help: {
+      id: "undo-archive-workspace",
+      section: "workspaces",
+      label: "Undo archive workspace",
+    },
+  },
+  {
+    id: "workspace-archive-undo-ctrl-z-non-mac",
+    action: "workspace.archive.undo",
+    combo: "Ctrl+Z",
+    when: { mac: false, commandCenter: false, editable: false, terminal: false },
+    help: {
+      id: "undo-archive-workspace",
+      section: "workspaces",
+      label: "Undo archive workspace",
+    },
+  },
+
   // --- Pin workspace ---
   {
     id: "workspace-pin-cmd-shift-p-mac",
@@ -502,7 +528,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-close-current-cmd-w-mac",
     action: "workspace.tab.close.current",
     combo: "Cmd+W",
-    when: { mac: true, desktop: true, commandCenter: false },
+    when: { mac: true, desktopBindings: true, commandCenter: false },
     help: {
       id: "workspace-tab-close-current",
       section: "tabs-panes",
@@ -513,7 +539,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-close-current-ctrl-w-non-mac",
     action: "workspace.tab.close.current",
     combo: "Ctrl+W",
-    when: { mac: false, desktop: true, commandCenter: false, terminal: false },
+    when: { mac: false, desktopBindings: true, commandCenter: false, terminal: false },
     help: {
       id: "workspace-tab-close-current",
       section: "tabs-panes",
@@ -524,7 +550,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-close-current-alt-shift-w-web",
     action: "workspace.tab.close.current",
     combo: "Alt+Shift+W",
-    when: { desktop: false, commandCenter: false },
+    when: { desktopBindings: false, commandCenter: false },
     help: {
       id: "workspace-tab-close-current",
       section: "tabs-panes",
@@ -537,7 +563,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-index-cmd-digit-mac",
     action: "workspace.navigate.index",
     combo: "Cmd+Digit",
-    when: { mac: true, desktop: true, commandCenter: false },
+    when: { mac: true, desktopBindings: true, commandCenter: false },
     payload: { type: "index" },
     help: {
       id: "workspace-jump-index",
@@ -550,7 +576,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-index-ctrl-digit-non-mac",
     action: "workspace.navigate.index",
     combo: "Ctrl+Digit",
-    when: { mac: false, desktop: true, commandCenter: false, terminal: false },
+    when: { mac: false, desktopBindings: true, commandCenter: false, terminal: false },
     payload: { type: "index" },
     help: {
       id: "workspace-jump-index",
@@ -563,7 +589,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-index-alt-digit-web",
     action: "workspace.navigate.index",
     combo: "Alt+Digit",
-    when: { desktop: false, commandCenter: false },
+    when: { desktopBindings: false, commandCenter: false },
     payload: { type: "index" },
     help: {
       id: "workspace-jump-index",
@@ -578,7 +604,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-navigate-index-cmd-alt-digit-mac-desktop",
     action: "workspace.tab.navigate.index",
     combo: "Cmd+Alt+Digit",
-    when: { mac: true, desktop: true, commandCenter: false },
+    when: { mac: true, desktopBindings: true, commandCenter: false },
     payload: { type: "index" },
     help: {
       id: "workspace-tab-jump-index",
@@ -591,7 +617,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-navigate-index-alt-digit-desktop",
     action: "workspace.tab.navigate.index",
     combo: "Alt+Digit",
-    when: { mac: false, desktop: true, commandCenter: false },
+    when: { mac: false, desktopBindings: true, commandCenter: false },
     payload: { type: "index" },
     help: {
       id: "workspace-tab-jump-index",
@@ -604,7 +630,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-tab-navigate-index-alt-shift-digit-web",
     action: "workspace.tab.navigate.index",
     combo: "Alt+Shift+Digit",
-    when: { desktop: false, commandCenter: false },
+    when: { desktopBindings: false, commandCenter: false },
     payload: { type: "index" },
     help: {
       id: "workspace-tab-jump-index",
@@ -619,7 +645,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-cmd-left-mac",
     action: "workspace.navigate.relative",
     combo: "Cmd+[",
-    when: { mac: true, desktop: true, commandCenter: false },
+    when: { mac: true, desktopBindings: true, commandCenter: false },
     payload: { type: "delta", delta: -1 },
     help: {
       id: "workspace-prev",
@@ -631,7 +657,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-ctrl-left-non-mac",
     action: "workspace.navigate.relative",
     combo: "Ctrl+[",
-    when: { mac: false, desktop: true, commandCenter: false, terminal: false },
+    when: { mac: false, desktopBindings: true, commandCenter: false, terminal: false },
     payload: { type: "delta", delta: -1 },
     help: {
       id: "workspace-prev",
@@ -643,7 +669,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-cmd-right-mac",
     action: "workspace.navigate.relative",
     combo: "Cmd+]",
-    when: { mac: true, desktop: true, commandCenter: false },
+    when: { mac: true, desktopBindings: true, commandCenter: false },
     payload: { type: "delta", delta: 1 },
     help: {
       id: "workspace-next",
@@ -655,7 +681,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-ctrl-right-non-mac",
     action: "workspace.navigate.relative",
     combo: "Ctrl+]",
-    when: { mac: false, desktop: true, commandCenter: false, terminal: false },
+    when: { mac: false, desktopBindings: true, commandCenter: false, terminal: false },
     payload: { type: "delta", delta: 1 },
     help: {
       id: "workspace-next",
@@ -667,7 +693,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-alt-left-web",
     action: "workspace.navigate.relative",
     combo: "Alt+[",
-    when: { desktop: false, commandCenter: false },
+    when: { desktopBindings: false, commandCenter: false },
     payload: { type: "delta", delta: -1 },
     help: {
       id: "workspace-prev",
@@ -679,7 +705,7 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
     id: "workspace-navigate-relative-alt-right-web",
     action: "workspace.navigate.relative",
     combo: "Alt+]",
-    when: { desktop: false, commandCenter: false },
+    when: { desktopBindings: false, commandCenter: false },
     payload: { type: "delta", delta: 1 },
     help: {
       id: "workspace-next",
@@ -1344,7 +1370,8 @@ export function matchesKeyboardShortcutContext(
 ): boolean {
   if (!when) return true;
   if (when.mac !== undefined && when.mac !== context.isMac) return false;
-  if (when.desktop !== undefined && when.desktop !== context.isDesktop) return false;
+  if (when.desktopBindings !== undefined && when.desktopBindings !== context.usesDesktopBindings)
+    return false;
   if (
     when.editable === false &&
     (context.focusScope === "message-input" || context.focusScope === "editable")
@@ -1409,7 +1436,8 @@ function helpMatchesPlatform(
   context: KeyboardShortcutPlatformContext,
 ): boolean {
   if (when?.mac !== undefined && when.mac !== context.isMac) return false;
-  if (when?.desktop !== undefined && when.desktop !== context.isDesktop) return false;
+  if (when?.desktopBindings !== undefined && when.desktopBindings !== context.usesDesktopBindings)
+    return false;
   return true;
 }
 
@@ -1573,7 +1601,7 @@ export function resolveKeyboardShortcut(input: {
 
 export function getBindingIdForAction(
   actionId: string,
-  platform: { isMac: boolean; isDesktop: boolean },
+  platform: { isMac: boolean; usesDesktopBindings: boolean },
 ): string | null {
   for (const binding of DEFAULT_BINDINGS) {
     if (binding.help?.id !== actionId) {
@@ -1611,7 +1639,7 @@ function displayChordForBinding(binding: ParsedShortcutBinding): ShortcutKey[][]
 
 export function getDefaultKeysForAction(
   actionId: string,
-  platform: { isMac: boolean; isDesktop: boolean },
+  platform: { isMac: boolean; usesDesktopBindings: boolean },
   bindings: readonly ParsedShortcutBinding[] = DEFAULT_BINDINGS,
 ): ShortcutKey[][] | null {
   for (const binding of bindings) {
@@ -1638,7 +1666,7 @@ export function getDefaultKeysForAction(
 export function resolveShortcutKeysForAction(
   actionId: string,
   overrides: ShortcutOverrides,
-  platform: { isMac: boolean; isDesktop: boolean },
+  platform: { isMac: boolean; usesDesktopBindings: boolean },
 ): ShortcutKey[][] | null {
   const bindingId = getBindingIdForAction(actionId, platform);
   if (bindingId === null) {
@@ -1680,7 +1708,7 @@ export function resolveShortcutKeysForAction(
  * the shortcut delivers.
  */
 export function getWorkspaceIndexJumpModifierKey(
-  platform: { isMac: boolean; isDesktop: boolean },
+  platform: { isMac: boolean; usesDesktopBindings: boolean },
   bindings: readonly ParsedShortcutBinding[] = DEFAULT_BINDINGS,
 ): "Alt" | "Meta" | "Control" | null {
   const binding = bindings.find(function (candidate) {
diff --git a/packages/app/src/keyboard/native-shortcuts.browser.test.ts b/packages/app/src/keyboard/native-shortcuts.browser.test.ts
new file mode 100644
index 0000000000..004eb912b2
--- /dev/null
+++ b/packages/app/src/keyboard/native-shortcuts.browser.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { buildEffectiveBindings } from "./keyboard-shortcuts";
+import { createKeyboardPipeline } from "./internal/pipeline";
+import { createOverlayRegistry } from "./internal/overlays";
+describe("DOM source adapter", () => {
+  it("runs DOM input through the same resolver, preserving cancellation and cleanup", async () => {
+    const { attachDomKeyboardSource } = await import("./internal/sources/dom.web");
+    const actions: string[] = [];
+    const input = document.createElement("textarea");
+    input.dataset.testid = "message-input";
+    document.body.append(input);
+    input.focus();
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: false, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({ "command-center-toggle-cmd-k-mac": "Cmd+J" }),
+      isCapturing: () => false,
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+      overlays: createOverlayRegistry(),
+    });
+    const detach = attachDomKeyboardSource({
+      keyDown: pipeline.keyDown,
+      keyUp() {},
+      blur() {},
+      commandCenterOpen: () => false,
+    });
+    const event = new KeyboardEvent("keydown", {
+      key: "j",
+      code: "KeyJ",
+      metaKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    input.dispatchEvent(event);
+    expect(actions).toEqual(["command-center.toggle"]);
+    expect(event.defaultPrevented).toBe(true);
+    detach();
+    input.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "j", code: "KeyJ", metaKey: true, bubbles: true }),
+    );
+    expect(actions).toHaveLength(1);
+    input.remove();
+    pipeline.dispose();
+  });
+});
diff --git a/packages/app/src/keyboard/native-shortcuts.test.ts b/packages/app/src/keyboard/native-shortcuts.test.ts
new file mode 100644
index 0000000000..e155fa2ba1
--- /dev/null
+++ b/packages/app/src/keyboard/native-shortcuts.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { buildEffectiveBindings } from "./keyboard-shortcuts";
+import { createKeyboardPipeline } from "./internal/pipeline";
+import { createOverlayRegistry } from "./internal/overlays";
+import { nativeKeyboardInput } from "./internal/sources/contract";
+
+function keyboardEvent(key: string, code: string, isMac = true) {
+  return {
+    key,
+    code,
+    altKey: false,
+    ctrlKey: !isMac,
+    metaKey: isMac,
+    shiftKey: false,
+    repeat: false,
+    preventDefault() {},
+    stopPropagation() {},
+  };
+}
+
+describe("shared keyboard source pipeline", () => {
+  it.each([true, false])("resolves hardware input and user rebinds with mac=%s", (isMac) => {
+    const actions: string[] = [];
+    const bindings = buildEffectiveBindings({ "command-center-toggle-cmd-k-mac": "Cmd+J" });
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => bindings,
+      isCapturing: () => false,
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+      overlays: createOverlayRegistry(),
+    });
+    pipeline.keyDown(nativeKeyboardInput(keyboardEvent("k", "KeyK", isMac), "message-input"));
+    expect(actions).toEqual(isMac ? [] : ["command-center.toggle"]);
+    pipeline.keyDown(nativeKeyboardInput(keyboardEvent("j", "KeyJ", isMac), "message-input"));
+    expect(actions).toEqual(["command-center.toggle"]);
+    pipeline.dispose();
+  });
+});
+
+describe("overlay and focus precedence in the source pipeline", () => {
+  it("dismisses an overlay without interrupting, then interrupts only the composer", () => {
+    const registry = createOverlayRegistry();
+    const actions: string[] = [];
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({}),
+      isCapturing: () => false,
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+      overlays: registry,
+    });
+    let dismissals = 0;
+    const remove = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Escape"],
+      onKeyDown: (event) => {
+        if (event.key !== "Escape") return false;
+        dismissals++;
+        return true;
+      },
+    });
+    const escape = { ...keyboardEvent("Escape", "Escape"), metaKey: false };
+    pipeline.keyDown(nativeKeyboardInput(escape, "message-input"));
+    expect(dismissals).toBe(1);
+    expect(actions).toEqual([]);
+    remove();
+    pipeline.keyDown(nativeKeyboardInput(escape, "terminal"));
+    expect(actions).toEqual([]);
+    pipeline.keyDown(nativeKeyboardInput(escape, "message-input"));
+    expect(actions).toEqual(["agent.interrupt"]);
+    pipeline.dispose();
+  });
+
+  it("does not turn IME confirmation into overlay selection", () => {
+    const registry = createOverlayRegistry();
+    let selections = 0;
+    const remove = registry.register({
+      getLayer: () => 20,
+      getKeys: () => ["Enter"],
+      onKeyDown: () => {
+        selections++;
+        return true;
+      },
+    });
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: true, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({}),
+      isCapturing: () => false,
+      dispatch: () => true,
+      overlays: registry,
+    });
+    pipeline.keyDown(
+      nativeKeyboardInput(
+        { ...keyboardEvent("Enter", "Enter"), metaKey: false, isComposing: true },
+        "message-input",
+      ),
+    );
+    expect(selections).toBe(0);
+    remove();
+    pipeline.dispose();
+  });
+
+  it.each([true, false])(
+    "uses hardware conventions for workspace index jumps with mac=%s",
+    (isMac) => {
+      const payloads: unknown[] = [];
+      const pipeline = createKeyboardPipeline({
+        getContext: () => ({ isMac, usesDesktopBindings: true, commandCenterOpen: false }),
+        getBindings: () => buildEffectiveBindings({}),
+        isCapturing: () => false,
+        dispatch: (match) => {
+          payloads.push([match.action, match.payload]);
+          return true;
+        },
+        overlays: createOverlayRegistry(),
+      });
+      pipeline.keyDown(nativeKeyboardInput(keyboardEvent("3", "Digit3", isMac), "message-input"));
+      expect(payloads).toEqual([["workspace.navigate.index", { index: 3 }]]);
+      pipeline.dispose();
+    },
+  );
+});
+
+describe("hardware source adapter", () => {
+  it.each([true, false])(
+    "delivers hardware down/up and declared focus with mac=%s",
+    async (isMac) => {
+      const { attachHardwareKeyboardSource } = await import("./internal/sources/native");
+      const { focusSurfaces } = await import("./internal/focus-surfaces");
+      const actions: string[] = [];
+      const releases: string[] = [];
+      const events = new Set<
+        (event: import("./internal/sources/hardware").HardwareKeyboardEvent) => void
+      >();
+      const releaseFocus = focusSurfaces.declare("message-input");
+      const pipeline = createKeyboardPipeline({
+        getContext: () => ({ isMac, usesDesktopBindings: true, commandCenterOpen: false }),
+        getBindings: () => buildEffectiveBindings({}),
+        isCapturing: () => false,
+        dispatch: (match) => {
+          actions.push(match.action);
+          return true;
+        },
+        overlays: createOverlayRegistry(),
+      });
+      const detach = attachHardwareKeyboardSource(
+        {
+          subscribe(handler) {
+            events.add(handler);
+            return () => {
+              events.delete(handler);
+            };
+          },
+          setOverlayKeys() {},
+        },
+        {
+          keyDown: pipeline.keyDown,
+          keyUp: (event) => releases.push(event.key),
+          blur() {},
+          commandCenterOpen: () => false,
+        },
+      );
+      const down = {
+        ...keyboardEvent("k", "KeyK", isMac),
+        isComposing: false,
+        phase: "down" as const,
+      };
+      for (const listener of events) listener(down);
+      for (const listener of events) listener({ ...down, phase: "up" });
+      expect(actions).toEqual(["command-center.toggle"]);
+      expect(releases).toEqual(["k"]);
+      detach();
+      releaseFocus();
+      pipeline.dispose();
+      expect(events.size).toBe(0);
+    },
+  );
+});
diff --git a/packages/app/src/keyboard/native-terminal-keyboard.test.ts b/packages/app/src/keyboard/native-terminal-keyboard.test.ts
new file mode 100644
index 0000000000..fbebddcfab
--- /dev/null
+++ b/packages/app/src/keyboard/native-terminal-keyboard.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { createKeyboardFocusScope } from "./internal/focus-surfaces";
+
+describe("declared keyboard focus", () => {
+  it("recognizes ordinary native editors while preserving declared scopes", () => {
+    let focused = false;
+    const scope = createKeyboardFocusScope(() => focused);
+    expect(scope.resolve(false)).toBe("other");
+    focused = true;
+    expect(scope.resolve(false)).toBe("editable");
+    const release = scope.declare("message-input");
+    expect(scope.resolve(false)).toBe("message-input");
+    expect(scope.resolve(true)).toBe("command-center");
+    release();
+    expect(scope.resolve(false)).toBe("editable");
+    focused = false;
+    expect(scope.resolve(false)).toBe("other");
+  });
+  it("tracks composer and terminal focus without stale cleanup losing the new owner", () => {
+    const scope = createKeyboardFocusScope();
+    expect(scope.resolve(false)).toBe("other");
+    const releaseTerminal = scope.declare("terminal");
+    expect(scope.resolve(false)).toBe("terminal");
+    const releaseComposer = scope.declare("message-input");
+    releaseTerminal();
+    expect(scope.resolve(false)).toBe("message-input");
+    expect(scope.resolve(true)).toBe("command-center");
+    releaseComposer();
+    releaseComposer();
+    expect(scope.resolve(false)).toBe("other");
+  });
+});
diff --git a/packages/app/src/keyboard/route-shortcut.ts b/packages/app/src/keyboard/route-shortcut.ts
index aa7679a7bf..79579689fd 100644
--- a/packages/app/src/keyboard/route-shortcut.ts
+++ b/packages/app/src/keyboard/route-shortcut.ts
@@ -48,6 +48,7 @@ const PASSTHROUGH_DISPATCH: Record<string, KeyboardActionDefinition> = {
   "workspace.new": { id: "workspace.new", scope: "sidebar" },
   "workspace.project.pick": { id: "workspace.project.pick", scope: "workspace" },
   "workspace.archive": { id: "workspace.archive", scope: "sidebar" },
+  "workspace.archive.undo": { id: "workspace.archive.undo", scope: "global" },
   "workspace.pin": { id: "workspace.pin", scope: "sidebar" },
   "worktree.new": { id: "worktree.new", scope: "sidebar" },
   "workspace.terminal.new": { id: "workspace.terminal.new", scope: "workspace" },
diff --git a/packages/app/src/keyboard/shift/index.ts b/packages/app/src/keyboard/shift/index.ts
index e54fc7ace9..e570bd3fee 100644
--- a/packages/app/src/keyboard/shift/index.ts
+++ b/packages/app/src/keyboard/shift/index.ts
@@ -1,5 +1,4 @@
 export { KeyboardShiftProvider, useKeyboardShiftStyle } from "./internal/provider";
-export { useKeyboardShift, useSettledKeyboardShift } from "./internal/context";
+export { useKeyboardShift } from "./internal/context";
 export { KeyboardTranslateView } from "./internal/translate";
 export { useKeyboardAnchor } from "./internal/anchor";
-export { useKeyboardStreamInset } from "./internal/stream";
diff --git a/packages/app/src/keyboard/shift/internal/context.ts b/packages/app/src/keyboard/shift/internal/context.ts
index f010c01255..b86005e214 100644
--- a/packages/app/src/keyboard/shift/internal/context.ts
+++ b/packages/app/src/keyboard/shift/internal/context.ts
@@ -17,6 +17,7 @@ export const KeyboardShiftContext = createContext<KeyboardShiftContextValue | nu
 export interface KeyboardTranslation {
   enabled: boolean;
   bottomClearance: number;
+  keyboardGap: number;
 }
 
 export interface WindowRect {
@@ -38,10 +39,9 @@ export interface KeyboardTranslationScope {
 
 /** Views outside a KeyboardTranslateView stay put. */
 export const KeyboardTranslationContext = createContext<KeyboardTranslationScope>({
-  translation: { enabled: false, bottomClearance: 0 },
+  translation: { enabled: false, bottomClearance: 0, keyboardGap: 0 },
   measureAtRest: measureInWindow,
 });
-export const SettledKeyboardShiftContext = createContext<number | null>(null);
 
 /** Read the app-wide keyboard inset without loading its native provider implementation. */
 export function useKeyboardShift(): KeyboardShiftContextValue {
@@ -51,12 +51,3 @@ export function useKeyboardShift(): KeyboardShiftContextValue {
   }
   return context;
 }
-
-/** Read the keyboard inset published after native keyboard motion has settled. */
-export function useSettledKeyboardShift(): number {
-  const context = useContext(SettledKeyboardShiftContext);
-  if (context === null) {
-    throw new Error("useSettledKeyboardShift must be used inside KeyboardShiftProvider");
-  }
-  return context;
-}
diff --git a/packages/app/src/keyboard/shift/internal/policy.test.ts b/packages/app/src/keyboard/shift/internal/policy.test.ts
index 6867f3ffa1..6b278ed224 100644
--- a/packages/app/src/keyboard/shift/internal/policy.test.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.test.ts
@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import {
-  resolveStreamKeyboardInset,
   shouldReconcileHiddenKeyboardEnd,
   resolveKeyboardLift,
   resolveKeyboardShift,
@@ -29,30 +28,22 @@ describe("keyboard layout reservation", () => {
   });
 });
 
-describe("resolveStreamKeyboardInset", () => {
-  it("uses the native scroll inset on iOS without changing content size", () => {
-    expect(resolveStreamKeyboardInset({ platform: "ios", settledShift: 311 })).toEqual({
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: 311 },
-    });
-  });
-
-  it("keeps Android's exact content-container padding behavior", () => {
-    expect(resolveStreamKeyboardInset({ platform: "android", settledShift: 311 })).toEqual({
-      contentContainerPaddingBottom: 311,
-      contentInset: undefined,
-    });
-  });
-
-  it("does not expose a negative inset", () => {
-    expect(resolveStreamKeyboardInset({ platform: "ios", settledShift: -1 })).toEqual({
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: 0 },
-    });
-  });
-});
-
 describe("resolveKeyboardShift", () => {
+  it.each([0, -1])(
+    "ignores a rotation report with height %s and progress one",
+    (rawKeyboardHeight) => {
+      expect(
+        resolveKeyboardShift({
+          rawKeyboardHeight,
+          keyboardProgress: 1,
+          bottomInset: 24,
+          isIos: true,
+          iosMinHeight: 120,
+        }),
+      ).toBe(0);
+    },
+  );
+
   it("keeps the existing open-keyboard offset behavior", () => {
     expect(
       resolveKeyboardShift({
@@ -92,16 +83,46 @@ describe("resolveKeyboardShift", () => {
 
 describe("resolveKeyboardLift", () => {
   it("lifts a docked view by the whole shift", () => {
-    expect(resolveKeyboardLift({ shift: 302, enabled: true, bottomClearance: 0 })).toBe(302);
+    expect(
+      resolveKeyboardLift({ shift: 302, enabled: true, bottomClearance: 0, keyboardGap: 0 }),
+    ).toBe(302);
   });
 
   it("lets the keyboard fill a centered form's clearance before lifting it", () => {
-    expect(resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 267 })).toBe(136);
-    expect(resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 455 })).toBe(0);
+    expect(
+      resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 267, keyboardGap: 0 }),
+    ).toBe(136);
+    expect(
+      resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 455, keyboardGap: 0 }),
+    ).toBe(0);
+  });
+
+  it("rises a docked composer's gap beyond the keyboard overlap, never at rest", () => {
+    const docked = { enabled: true, bottomClearance: 0, keyboardGap: 16 };
+    expect(resolveKeyboardLift({ ...docked, shift: 0 })).toBe(0);
+    expect(resolveKeyboardLift({ ...docked, shift: 8 })).toBe(16);
+    expect(resolveKeyboardLift({ ...docked, shift: 276 })).toBe(292);
+  });
+
+  it("measures the shift from the window's bottom clearance, not the rectangular inset", () => {
+    // iPhone Duo outer screen: the bar guide rests 24pt up where safeAreaInsets reports 34.
+    const shift = resolveKeyboardShift({
+      rawKeyboardHeight: 300,
+      keyboardProgress: 1,
+      bottomInset: 24,
+      isIos: true,
+      iosMinHeight: 120,
+    });
+    expect(shift).toBe(276);
+    const lift = resolveKeyboardLift({ shift, enabled: true, bottomClearance: 0, keyboardGap: 16 });
+    const restingComposerBottom = 24;
+    expect(restingComposerBottom + lift - 300).toBe(16);
   });
 
   it("keeps a disabled view in place", () => {
-    expect(resolveKeyboardLift({ shift: 302, enabled: false, bottomClearance: 0 })).toBe(0);
+    expect(
+      resolveKeyboardLift({ shift: 302, enabled: false, bottomClearance: 0, keyboardGap: 0 }),
+    ).toBe(0);
   });
 });
 
diff --git a/packages/app/src/keyboard/shift/internal/policy.ts b/packages/app/src/keyboard/shift/internal/policy.ts
index 4e618c8a49..3cd290fd94 100644
--- a/packages/app/src/keyboard/shift/internal/policy.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.ts
@@ -10,26 +10,6 @@ export function reserveKeyboardLayoutShift(input: {
   return input.phase === "start" ? Math.max(input.current, input.target) : input.target;
 }
 
-export function resolveStreamKeyboardInset(input: {
-  platform: "android" | "ios";
-  settledShift: number;
-}): {
-  contentContainerPaddingBottom: number;
-  contentInset: { bottom: number } | undefined;
-} {
-  const settledShift = Math.max(0, input.settledShift);
-  if (input.platform === "ios") {
-    return {
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: settledShift },
-    };
-  }
-  return {
-    contentContainerPaddingBottom: settledShift,
-    contentInset: undefined,
-  };
-}
-
 export function resolveKeyboardShift(input: {
   rawKeyboardHeight: number;
   keyboardProgress: number;
@@ -57,9 +37,14 @@ export function resolveKeyboardLift(input: {
   shift: number;
   enabled: boolean;
   bottomClearance: number;
+  keyboardGap: number;
 }): number {
   "worklet";
-  return input.enabled ? Math.max(0, input.shift - input.bottomClearance) : 0;
+  if (!input.enabled) return 0;
+  // The gap opens over the shift's first points, so the view never rises at rest.
+  return (
+    Math.max(0, input.shift - input.bottomClearance) + Math.min(input.keyboardGap, input.shift)
+  );
 }
 
 export function shouldReconcileHiddenKeyboardEnd(input: {
diff --git a/packages/app/src/keyboard/shift/internal/provider.ts b/packages/app/src/keyboard/shift/internal/provider.ts
index 7b2ff46eae..a99a148aef 100644
--- a/packages/app/src/keyboard/shift/internal/provider.ts
+++ b/packages/app/src/keyboard/shift/internal/provider.ts
@@ -1,4 +1,4 @@
-import { createElement, useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { createElement, useEffect, useMemo, type ReactNode } from "react";
 import { Platform } from "react-native";
 import type { ViewStyle } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
@@ -8,19 +8,17 @@ import {
 } from "react-native-keyboard-controller";
 import {
   useAnimatedStyle,
-  useAnimatedReaction,
   useDerivedValue,
   useSharedValue,
   type SharedValue,
 } from "react-native-reanimated";
-import { scheduleOnRN } from "react-native-worklets";
 import {
   DEFAULT_IOS_KEYBOARD_INSET_MIN_HEIGHT,
   resolveKeyboardShift,
   reserveKeyboardLayoutShift,
   shouldReconcileHiddenKeyboardEnd,
 } from "./policy";
-import { KeyboardShiftContext, SettledKeyboardShiftContext, useKeyboardShift } from "./context";
+import { KeyboardShiftContext, useKeyboardShift } from "./context";
 
 type KeyboardShiftMode = "translate" | "padding";
 
@@ -31,11 +29,6 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
   const isIos = Platform.OS === "ios";
   const isMoving = useSharedValue(false);
   const layoutShift = useSharedValue(0);
-  const [settledShift, setSettledShift] = useState(0);
-  const publishSettledShift = useCallback((nextShift: number) => {
-    setSettledShift((currentShift) => (currentShift === nextShift ? currentShift : nextShift));
-  }, []);
-
   useEffect(() => {
     bottomInset.value = insets.bottom;
   }, [bottomInset, insets.bottom]);
@@ -93,16 +86,6 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
     [bottomInset, isIos, isMoving, keyboardHeight, keyboardProgress, layoutShift],
   );
 
-  useAnimatedReaction(
-    () => ({ moving: isMoving.value, shift: shift.value }),
-    (current, previous) => {
-      if (!current.moving && (previous === null || previous.moving)) {
-        scheduleOnRN(publishSettledShift, current.shift);
-      }
-    },
-    [isMoving, publishSettledShift, shift],
-  );
-
   const value = useMemo(
     () => ({
       shift,
@@ -113,11 +96,7 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
     [bottomInset, isMoving, layoutShift, shift],
   );
 
-  return createElement(
-    KeyboardShiftContext.Provider,
-    { value },
-    createElement(SettledKeyboardShiftContext.Provider, { value: settledShift }, children),
-  );
+  return createElement(KeyboardShiftContext.Provider, { value }, children);
 }
 
 export function useKeyboardShiftStyle(input: { mode: KeyboardShiftMode; enabled?: boolean }): {
diff --git a/packages/app/src/keyboard/shift/internal/stream.ts b/packages/app/src/keyboard/shift/internal/stream.ts
deleted file mode 100644
index 45fe167fe4..0000000000
--- a/packages/app/src/keyboard/shift/internal/stream.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { useMemo } from "react";
-import { Platform } from "react-native";
-import { useSettledKeyboardShift } from "./context";
-import { resolveStreamKeyboardInset } from "./policy";
-
-/** Preserve the translated inverted list's far-end scroll range only after motion settles. */
-export function useKeyboardStreamInset() {
-  const settledShift = useSettledKeyboardShift();
-  return useMemo(
-    () =>
-      resolveStreamKeyboardInset({
-        platform: Platform.OS === "ios" ? "ios" : "android",
-        settledShift,
-      }),
-    [settledShift],
-  );
-}
diff --git a/packages/app/src/keyboard/shift/internal/translate.android.tsx b/packages/app/src/keyboard/shift/internal/translate.android.tsx
index cec2f0fcfd..5766c001ac 100644
--- a/packages/app/src/keyboard/shift/internal/translate.android.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.android.tsx
@@ -10,18 +10,27 @@ interface KeyboardTranslateViewProps extends ViewProps {
   enabled?: boolean;
   /** Space below the view's resting position that the keyboard may fill before the view moves. */
   bottomClearance?: number;
+  /**
+   * Distance the view rises beyond the keyboard's overlap of the safe area, so content
+   * resting on the safe-area boundary keeps this gap above the open keyboard.
+   */
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled = true,
   bottomClearance = 0,
+  keyboardGap = 0,
   style,
   ...props
 }: KeyboardTranslateViewProps) {
   const { shift } = useKeyboardShift();
   const frameRef = useRef<View>(null);
-  const translation = useMemo(() => ({ enabled, bottomClearance }), [bottomClearance, enabled]);
+  const translation = useMemo(
+    () => ({ enabled, bottomClearance, keyboardGap }),
+    [bottomClearance, enabled, keyboardGap],
+  );
   const scope = useKeyboardTranslationScope(frameRef, translation);
   const keyboardStyle = useAnimatedStyle(() => ({
     transform: [{ translateY: -resolveKeyboardLift({ shift: shift.value, ...translation }) }],
diff --git a/packages/app/src/keyboard/shift/internal/translate.ios.tsx b/packages/app/src/keyboard/shift/internal/translate.ios.tsx
index 8628ba8b8c..5b5f378e0d 100644
--- a/packages/app/src/keyboard/shift/internal/translate.ios.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.ios.tsx
@@ -10,30 +10,40 @@ interface KeyboardTranslateViewProps extends ViewProps {
   enabled?: boolean;
   /** Space below the view's resting position that the keyboard may fill before the view moves. */
   bottomClearance?: number;
+  /**
+   * Distance the view rises beyond the keyboard's overlap of the safe area, so content
+   * resting on the safe-area boundary keeps this gap above the open keyboard.
+   */
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled = true,
   bottomClearance = 0,
+  keyboardGap = 0,
   style,
   ...props
 }: KeyboardTranslateViewProps) {
   const insets = useSafeAreaInsets();
   const { height, progress } = useKeyboardAnimation();
-  const translateY = useMemo(
-    () =>
-      Animated.add(
-        Animated.add(height, Animated.multiply(progress, insets.bottom)),
-        bottomClearance,
-      ).interpolate({
-        inputRange: [-1, 0],
-        outputRange: [-1, 0],
-        extrapolateLeft: "extend",
-        extrapolateRight: "clamp",
-      }),
-    [bottomClearance, height, insets.bottom, progress],
-  );
+  // Mirrors resolveKeyboardLift on the native driver: `overlap` is the negated shift.
+  const translateY = useMemo(() => {
+    const overlap = Animated.add(height, Animated.multiply(progress, insets.bottom));
+    const lift = Animated.add(overlap, bottomClearance).interpolate({
+      inputRange: [-1, 0],
+      outputRange: [-1, 0],
+      extrapolateLeft: "extend",
+      extrapolateRight: "clamp",
+    });
+    if (!(keyboardGap > 0)) return lift;
+    const gap = overlap.interpolate({
+      inputRange: [-keyboardGap, 0],
+      outputRange: [-keyboardGap, 0],
+      extrapolate: "clamp",
+    });
+    return Animated.add(lift, gap);
+  }, [bottomClearance, height, insets.bottom, keyboardGap, progress]);
   // Fullscreen resizes this view while disabling translation. iOS Fabric can
   // reapply its previous transform during that layout commit. Keep the graph
   // attached and apply the mode on the native animation frame; a static zero or
@@ -57,7 +67,10 @@ export function KeyboardTranslateView({
   );
 
   const frameRef = useRef<View>(null);
-  const translation = useMemo(() => ({ enabled, bottomClearance }), [bottomClearance, enabled]);
+  const translation = useMemo(
+    () => ({ enabled, bottomClearance, keyboardGap }),
+    [bottomClearance, enabled, keyboardGap],
+  );
   const scope = useKeyboardTranslationScope(frameRef, translation);
 
   return (
diff --git a/packages/app/src/keyboard/shift/internal/translate.tsx b/packages/app/src/keyboard/shift/internal/translate.tsx
index 6a0506c301..b04613d495 100644
--- a/packages/app/src/keyboard/shift/internal/translate.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.tsx
@@ -5,12 +5,14 @@ interface KeyboardTranslateViewProps extends ViewProps {
   children: ReactNode;
   enabled?: boolean;
   bottomClearance?: number;
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled: _enabled,
   bottomClearance: _bottomClearance,
+  keyboardGap: _keyboardGap,
   ...props
 }: KeyboardTranslateViewProps) {
   return <View {...props}>{children}</View>;
diff --git a/packages/app/src/keyboard/shortcut-help-search.test.ts b/packages/app/src/keyboard/shortcut-help-search.test.ts
index 201d4865f0..b5cecf2a4e 100644
--- a/packages/app/src/keyboard/shortcut-help-search.test.ts
+++ b/packages/app/src/keyboard/shortcut-help-search.test.ts
@@ -7,7 +7,7 @@ import {
 } from "./keyboard-shortcuts";
 import { filterShortcutHelpSections, shortcutSearchText } from "./shortcut-help-search";
 
-const MAC_DESKTOP = { isMac: true, isDesktop: true };
+const MAC_DESKTOP = { isMac: true, usesDesktopBindings: true };
 const NEW_WORKSPACE_BINDING = "workspace-new-cmd-n-mac";
 
 /**
diff --git a/packages/app/src/keyboard/shortcut-string.ts b/packages/app/src/keyboard/shortcut-string.ts
index 6b80009633..05c83aff51 100644
--- a/packages/app/src/keyboard/shortcut-string.ts
+++ b/packages/app/src/keyboard/shortcut-string.ts
@@ -237,7 +237,9 @@ export function chordStringToShortcutKeys(s: string): ShortcutKey[][] {
   return s.split(" ").map(comboStringToShortcutKeys);
 }
 
-export function heldModifiersFromEvent(event: KeyboardEvent): string | null {
+export function heldModifiersFromEvent(
+  event: Pick<KeyboardEvent, "key" | "code" | "altKey" | "ctrlKey" | "metaKey" | "shiftKey">,
+): string | null {
   const parts: string[] = [];
   if (event.ctrlKey) parts.push("Ctrl");
   if (event.altKey) parts.push("Alt");
@@ -255,7 +257,9 @@ export function isModifierKeyCode(code: string): boolean {
   return MODIFIER_CODES.has(code);
 }
 
-export function keyboardEventToComboString(event: KeyboardEvent): string | null {
+export function keyboardEventToComboString(
+  event: Pick<KeyboardEvent, "key" | "code" | "altKey" | "ctrlKey" | "metaKey" | "shiftKey">,
+): string | null {
   if (isModifierKeyCode(event.code)) {
     return null;
   }
diff --git a/packages/app/src/keyboard/use-shortcuts.ts b/packages/app/src/keyboard/use-shortcuts.ts
new file mode 100644
index 0000000000..b762d8dfcf
--- /dev/null
+++ b/packages/app/src/keyboard/use-shortcuts.ts
@@ -0,0 +1,274 @@
+import { usesDesktopBindings } from "./internal/conventions";
+import { createKeyboardPipeline } from "./internal/pipeline";
+import { overlays } from "./internal/overlays";
+import { attachKeyboardSources, publishKeyboardPolicy } from "./internal/sources";
+import type { KeyboardSourceInput } from "./internal/sources/contract";
+import type { KeyboardInputEvent } from "./internal/overlays";
+import { hasActiveOverlay } from "./internal/overlay-dispatch";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { usePathname, useRouter } from "expo-router";
+import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
+import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
+import { useKeyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher-context";
+import {
+  type ChordState,
+  buildEffectiveBindings,
+  getWorkspaceIndexJumpModifierKey,
+} from "@/keyboard/keyboard-shortcuts";
+import { shouldPublishBrowserShortcutPolicy } from "@/keyboard/internal/sources/electron-browser";
+import type { KeyboardShortcutPayload } from "@/keyboard/actions";
+import {
+  routeKeyboardShortcut,
+  type ShortcutAction,
+  type ShortcutCallbackName,
+} from "@/keyboard/route-shortcut";
+import { getShortcutOs } from "@/utils/shortcut-platform";
+import { useOpenAddProject } from "@/hooks/use-open-add-project";
+import { useStableEvent } from "@/hooks/use-stable-event";
+import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
+import { buildOpenProjectRoute } from "@/utils/host-routes";
+import {
+  type ActiveWorkspaceSelection,
+  navigateToLastWorkspace,
+  useActiveWorkspaceSelection,
+} from "@/stores/navigation-active-workspace-store";
+
+export function useKeyboardShortcuts({
+  enabled,
+  isMobile,
+  isWorkspaceFocusModeEnabled,
+  toggleAgentList,
+  toggleBothSidebars,
+  exitFocusMode,
+  cycleTheme,
+}: {
+  enabled: boolean;
+  isMobile: boolean;
+  isWorkspaceFocusModeEnabled: boolean;
+  toggleAgentList: () => void;
+  toggleBothSidebars?: () => void;
+  exitFocusMode: () => void;
+  cycleTheme?: () => void;
+}) {
+  const keyboardActionDispatcher = useKeyboardActionDispatcher();
+  const pathname = usePathname();
+  const router = useRouter();
+  const resetModifiers = useKeyboardShortcutsStore((s) => s.resetModifiers);
+  const { overrides } = useKeyboardShortcutOverrides();
+  const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
+  const isMac = getShortcutOs() === "mac";
+  const openProjectPickerAction = useOpenAddProject();
+  const activeWorkspaceSelection = useActiveWorkspaceSelection();
+  const keyboardWorkspaceSelectionRef = useRef<ActiveWorkspaceSelection | null>(null);
+  const publishBrowserShortcutPolicy = useCallback(
+    (chordState?: ChordState) => {
+      publishKeyboardPolicy({ bindings, chordState, isMac, enabled });
+    },
+    [bindings, enabled, isMac],
+  );
+
+  useEffect(() => {
+    if (activeWorkspaceSelection) {
+      keyboardWorkspaceSelectionRef.current = activeWorkspaceSelection;
+    }
+  }, [activeWorkspaceSelection]);
+
+  useEffect(() => {
+    publishBrowserShortcutPolicy();
+  }, [publishBrowserShortcutPolicy]);
+
+  // Only the modifier that actually performs the workspace-index jump on this
+  // runtime should reveal the sidebar number badges (Alt on web, Cmd on
+  // desktop Mac, Ctrl on desktop non-Mac). The store ORs altDown/cmdOrCtrlDown
+  // to drive badge visibility, so we set the flag matching this runtime.
+  // Derived from the effective bindings: `null` when the user unassigned or
+  // rebound the jump shortcut, and no `event.key` ever equals null, so the
+  // badges simply never appear.
+  const badgeModifierKey = getWorkspaceIndexJumpModifierKey(
+    { isMac, usesDesktopBindings: usesDesktopBindings },
+    bindings,
+  );
+
+  // The keyup listener matches the released key against the current modifier,
+  // so a modifier held while the jump binding changes could never be released
+  // and the badges would stay up until a blur. Clear them when it changes.
+  useEffect(() => {
+    resetModifiers();
+  }, [badgeModifierKey, resetModifiers]);
+
+  const setBadgeModifierDown = (down: boolean) => {
+    const state = useKeyboardShortcutsStore.getState();
+    if (usesDesktopBindings) {
+      state.setCmdOrCtrlDown(down);
+    } else {
+      state.setAltDown(down);
+    }
+  };
+
+  const callbacksByName: Record<ShortcutCallbackName, (() => void) | undefined> = {
+    "toggle-agent-list": toggleAgentList,
+    "toggle-both-sidebars": toggleBothSidebars,
+    "cycle-theme": cycleTheme,
+  };
+
+  const performShortcutAction = (
+    action: ShortcutAction,
+    captureFocusRestore: () => void,
+  ): boolean => {
+    switch (action.kind) {
+      case "none":
+        return false;
+      case "dispatch":
+        return keyboardActionDispatcher.dispatch(action.action);
+      case "navigate-workspace":
+        keyboardWorkspaceSelectionRef.current = {
+          serverId: action.serverId,
+          workspaceId: action.workspaceId,
+        };
+        navigateToWorkspace({ serverId: action.serverId, workspaceId: action.workspaceId });
+        return true;
+      case "navigate-last-workspace":
+        if (navigateToLastWorkspace()) {
+          return true;
+        }
+        router.replace(buildOpenProjectRoute());
+        return true;
+      case "router-replace":
+        router.replace(action.route as Parameters<typeof router.replace>[0]);
+        return true;
+      case "router-back":
+        router.back();
+        return true;
+      case "router-push":
+        router.push(action.route as Parameters<typeof router.push>[0]);
+        return true;
+      case "open-project-picker":
+        void openProjectPickerAction();
+        return true;
+      case "callback":
+        callbacksByName[action.name]?.();
+        return true;
+      case "command-center-toggle": {
+        if (action.nextOpen) {
+          captureFocusRestore();
+        }
+        useKeyboardShortcutsStore
+          .getState()
+          .setCommandCenterOpen(action.nextOpen, action.scope ?? null);
+        return true;
+      }
+      case "shortcuts-dialog-toggle":
+        useKeyboardShortcutsStore.getState().setShortcutsDialogOpen(action.nextOpen);
+        return true;
+    }
+  };
+
+  const routeAndPerformShortcut = (input: {
+    action: string;
+    payload: KeyboardShortcutPayload;
+    captureFocusRestore: () => void;
+  }): boolean => {
+    const store = useKeyboardShortcutsStore.getState();
+    const shortcutAction = routeKeyboardShortcut(
+      { action: input.action, payload: input.payload },
+      {
+        pathname,
+        isMobile,
+        sidebarShortcutTargets: store.sidebarShortcutWorkspaceTargets,
+        navigationActiveWorkspace:
+          keyboardWorkspaceSelectionRef.current ?? activeWorkspaceSelection,
+        commandCenterOpen: store.commandCenterOpen,
+        shortcutsDialogOpen: store.shortcutsDialogOpen,
+      },
+    );
+    const handled = performShortcutAction(shortcutAction, input.captureFocusRestore);
+    if (handled && isWorkspaceFocusModeEnabled && input.action.startsWith("sidebar.")) {
+      exitFocusMode();
+    }
+    return handled;
+  };
+
+  const getContext = useStableEvent(() => ({
+    isMac,
+    usesDesktopBindings: usesDesktopBindings,
+    commandCenterOpen: useKeyboardShortcutsStore.getState().commandCenterOpen,
+  }));
+  const getBindings = useStableEvent(() => bindings);
+  const isCapturing = useStableEvent(() => useKeyboardShortcutsStore.getState().capturingShortcut);
+  const dispatchMatch = useStableEvent(
+    (match: import("./keyboard-shortcuts").KeyboardShortcutMatch, input: KeyboardSourceInput) =>
+      routeAndPerformShortcut({
+        action: match.action,
+        payload: match.payload,
+        captureFocusRestore: input.captureFocusRestore,
+      }),
+  );
+  const chordChanged = useStableEvent(
+    (previous: ChordState, next: ChordState, input: KeyboardSourceInput | null) => {
+      const isBrowserInput = input !== null && "browserId" in input.event;
+      if (
+        !input ||
+        shouldPublishBrowserShortcutPolicy({
+          isBrowserInput,
+          previousChordState: previous,
+          nextChordState: next,
+        })
+      ) {
+        publishBrowserShortcutPolicy(next);
+      }
+    },
+  );
+  const beforeResolve = useStableEvent((input: KeyboardSourceInput) => {
+    const event = input.event;
+    const key = event.key ?? "";
+    if (key === "Escape" && pathname.startsWith("/settings") && !isMobile && hasActiveOverlay()) {
+      return false;
+    }
+    if (key === badgeModifierKey && !event.shiftKey) {
+      setBadgeModifierDown(true);
+    }
+    if (key === "Shift") {
+      const state = useKeyboardShortcutsStore.getState();
+      if (state.altDown || state.cmdOrCtrlDown) {
+        state.resetModifiers();
+      }
+    }
+
+    return true;
+  });
+
+  const pipeline = useMemo(
+    () =>
+      createKeyboardPipeline({
+        getContext,
+        getBindings,
+        isCapturing,
+        dispatch: dispatchMatch,
+        overlays,
+        beforeResolve,
+        chordChanged,
+      }),
+    [getContext, getBindings, isCapturing, dispatchMatch, beforeResolve, chordChanged],
+  );
+
+  const handleKeyUp = useStableEvent((event: KeyboardInputEvent) => {
+    const key = event.key ?? "";
+    if (key === badgeModifierKey) {
+      setBadgeModifierDown(false);
+    }
+  });
+
+  useEffect(() => {
+    if (!enabled) return;
+    const detach = attachKeyboardSources({
+      keyDown: pipeline.keyDown,
+      keyUp: handleKeyUp,
+      blur: resetModifiers,
+      commandCenterOpen: () => useKeyboardShortcutsStore.getState().commandCenterOpen,
+    });
+    return () => {
+      detach();
+      pipeline.dispose();
+    };
+  }, [enabled, pipeline, handleKeyUp, resetModifiers]);
+}
diff --git a/packages/app/src/lib/overlay-root.browser.test.tsx b/packages/app/src/lib/overlay-root.browser.test.tsx
index bd20d2aeeb..7f0d5115ac 100644
--- a/packages/app/src/lib/overlay-root.browser.test.tsx
+++ b/packages/app/src/lib/overlay-root.browser.test.tsx
@@ -1,19 +1,22 @@
+import { useGlobalOverlayLayer } from "./overlay-root";
+import { useOverlayRegistration } from "@/keyboard";
 import React, { type RefCallback } from "react";
 import { flushSync } from "react-dom";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  hasOpenDomPopover,
-  keyBelongsToDomPopover,
-  useWebOverlayRegistration,
-} from "./overlay-root";
+import { hasOpenDomPopover, keyBelongsToDomPopover } from "@/keyboard/internal/dom-popover";
 
 function nextFrame(): Promise<void> {
   return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
 
 function OverlayHarness({ active, showScope }: { active: boolean; showScope: boolean }) {
-  const setScope = useWebOverlayRegistration({ active, layer: 20, onKeyDown: () => false });
+  const setScope = useOverlayRegistration({
+    keys: ["Escape"],
+    active,
+    layer: 20,
+    onKeyDown: () => false,
+  });
   return showScope ? (
     <div data-testid="scope" ref={setScope as RefCallback<HTMLDivElement>} tabIndex={-1}>
       <input data-testid="overlay-input" />
@@ -21,7 +24,7 @@ function OverlayHarness({ active, showScope }: { active: boolean; showScope: boo
   ) : null;
 }
 
-describe("useWebOverlayRegistration in the browser", () => {
+describe("useOverlayRegistration in the browser", () => {
   let root: Root;
   let container: HTMLDivElement;
   let opener: HTMLButtonElement;
@@ -104,3 +107,93 @@ describe("Escape with a plugin popover open", () => {
     expect(keyBelongsToDomPopover({ key: "Escape" })).toBe(true);
   });
 });
+
+describe("DOM source through the shared resolver", () => {
+  it("uses user rebinds from a focused composer and cancels the DOM default", async () => {
+    const { attachDomKeyboardSource } = await import("@/keyboard/internal/sources/dom.web");
+    const { createKeyboardPipeline } = await import("@/keyboard/internal/pipeline");
+    const { createOverlayRegistry } = await import("@/keyboard/internal/overlays");
+    const { buildEffectiveBindings } = await import("@/keyboard/keyboard-shortcuts");
+    const actions: string[] = [];
+    const input = document.createElement("textarea");
+    input.dataset.testid = "message-input-root";
+    document.body.append(input);
+    input.focus();
+    const pipeline = createKeyboardPipeline({
+      getContext: () => ({ isMac: true, usesDesktopBindings: false, commandCenterOpen: false }),
+      getBindings: () => buildEffectiveBindings({ "command-center-toggle-cmd-k-mac": "Cmd+J" }),
+      isCapturing: () => false,
+      overlays: createOverlayRegistry(),
+      dispatch: (match) => {
+        actions.push(match.action);
+        return true;
+      },
+    });
+    const detach = attachDomKeyboardSource({
+      keyDown: pipeline.keyDown,
+      keyUp() {},
+      blur() {},
+      commandCenterOpen: () => false,
+    });
+    const event = new KeyboardEvent("keydown", {
+      key: "j",
+      code: "KeyJ",
+      metaKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    input.dispatchEvent(event);
+    expect(actions).toEqual(["command-center.toggle"]);
+    expect(event.defaultPrevented).toBe(true);
+    detach();
+    pipeline.dispose();
+    input.remove();
+  });
+});
+
+it("recognizes a hardware keyboard from modified input without a fine pointer", async () => {
+  const { createWebHardwareKeyboardPresence } = await import("@/keyboard/internal/presence.web");
+  const presence = createWebHardwareKeyboardPresence(window.matchMedia("(width: 0px)"), window);
+  const values: boolean[] = [];
+  const release = presence.subscribe(() => values.push(presence.getSnapshot()));
+  expect(presence.getSnapshot()).toBe(false);
+  window.dispatchEvent(new KeyboardEvent("keydown", { key: "a", code: "KeyA" }));
+  expect(presence.getSnapshot()).toBe(false);
+  window.dispatchEvent(new KeyboardEvent("keydown", { key: "k", code: "KeyK", ctrlKey: true }));
+  expect(presence.getSnapshot()).toBe(true);
+  expect(values).toEqual([true]);
+  release();
+});
+
+function LayerHarness({ active, child }: { active: boolean; child: boolean }) {
+  const layer = useGlobalOverlayLayer("modal", active);
+  useOverlayRegistration({
+    active: child,
+    layer: 200,
+    keys: ["Escape"],
+    manageFocus: false,
+    onKeyDown: () => false,
+  });
+  return <span data-testid="layer">{layer}</span>;
+}
+
+it("keeps the opening layer across rerenders and captures a new layer on reopening", () => {
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  function render(active: boolean, child: boolean) {
+    flushSync(() => root.render(<LayerHarness active={active} child={child} />));
+    return container.textContent;
+  }
+  try {
+    expect(render(false, false)).toBe("20");
+    expect(render(true, false)).toBe("20");
+    expect(render(true, true)).toBe("20");
+    expect(render(true, true)).toBe("20");
+    render(false, true);
+    expect(render(true, true)).toBe("220");
+  } finally {
+    root.unmount();
+    container.remove();
+  }
+});
diff --git a/packages/app/src/lib/overlay-root.test.tsx b/packages/app/src/lib/overlay-root.test.tsx
deleted file mode 100644
index 6671cd50f9..0000000000
--- a/packages/app/src/lib/overlay-root.test.tsx
+++ /dev/null
@@ -1,91 +0,0 @@
-// @vitest-environment jsdom
-import { act, renderHook } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { dispatchTopWebOverlayKeyDown, useWebOverlayRegistration } from "./overlay-root";
-
-describe("useWebOverlayRegistration", () => {
-  let opener: HTMLButtonElement;
-  let input: HTMLInputElement;
-  let scope: HTMLDivElement;
-
-  beforeEach(() => {
-    vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
-      callback(0);
-      return 0;
-    });
-    vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {});
-
-    opener = document.createElement("button");
-    input = document.createElement("input");
-    scope = document.createElement("div");
-    scope.tabIndex = -1;
-    scope.append(input);
-    document.body.append(opener, scope);
-    opener.focus();
-    expect(document.activeElement).toBe(opener);
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-    document.body.replaceChildren();
-  });
-
-  it("does not restore opener focus when an active overlay scope detaches", () => {
-    const { result, unmount } = renderHook(() =>
-      useWebOverlayRegistration({ active: true, layer: 20, onKeyDown: () => false }),
-    );
-
-    act(() => result.current(scope));
-    const openerFocus = vi.spyOn(opener, "focus");
-    input.focus();
-    expect(document.activeElement).toBe(input);
-
-    act(() => result.current(null));
-
-    expect(openerFocus).not.toHaveBeenCalled();
-    expect(document.activeElement).toBe(input);
-    unmount();
-  });
-
-  it("restores opener focus when an overlay closes", () => {
-    const { result, rerender, unmount } = renderHook(
-      ({ active }: { active: boolean }) =>
-        useWebOverlayRegistration({ active, layer: 20, onKeyDown: () => false }),
-      { initialProps: { active: true } },
-    );
-
-    act(() => result.current(scope));
-    const openerFocus = vi.spyOn(opener, "focus");
-    input.focus();
-    expect(document.activeElement).toBe(input);
-
-    act(() => rerender({ active: false }));
-
-    expect(openerFocus).toHaveBeenCalled();
-    unmount();
-  });
-
-  it("restores opener focus when an active overlay unmounts after its scope detaches", () => {
-    const { result, unmount } = renderHook(() =>
-      useWebOverlayRegistration({ active: true, layer: 20, onKeyDown: () => false }),
-    );
-
-    act(() => result.current(scope));
-    const openerFocus = vi.spyOn(opener, "focus");
-    input.focus();
-    expect(document.activeElement).toBe(input);
-
-    act(() => result.current(null));
-    expect(openerFocus).not.toHaveBeenCalled();
-
-    unmount();
-
-    expect(openerFocus).toHaveBeenCalled();
-  });
-
-  it("leaves IME composition keys with the focused editor", () => {
-    const event = new KeyboardEvent("keydown", { key: "Process", bubbles: true });
-    expect(dispatchTopWebOverlayKeyDown(event)).toBe(false);
-    expect(event.defaultPrevented).toBe(false);
-  });
-});
diff --git a/packages/app/src/lib/overlay-root.ts b/packages/app/src/lib/overlay-root.ts
index d1ab0b9787..b4448b866e 100644
--- a/packages/app/src/lib/overlay-root.ts
+++ b/packages/app/src/lib/overlay-root.ts
@@ -1,13 +1,5 @@
-import {
-  createContext,
-  createElement,
-  useCallback,
-  useContext,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  type ReactNode,
-} from "react";
+import { createContext, createElement, useContext, useState, type ReactNode } from "react";
+import { getTopOverlayLayer } from "@/keyboard";
 
 /**
  * Shared overlay root for web portals (modals, toasts, etc.)
@@ -62,13 +54,27 @@ export function useOverlayLayer(kind: OverlayKind): number {
  * was topmost when it opened. Global hosts live outside their opener's React
  * tree, so context alone cannot preserve that relative ownership.
  */
-export function useGlobalWebOverlayLayer(kind: OverlayKind, active: boolean): number {
+export function useGlobalOverlayLayer(kind: OverlayKind, active: boolean): number {
   const contextualLayer = useOverlayLayer(kind);
-  return useMemo(() => {
-    if (!active) return contextualLayer;
-    const topLayer = getTopWebOverlay()?.getLayer() ?? 0;
-    return Math.max(contextualLayer, topLayer + OVERLAY_Z[kind]);
-  }, [active, contextualLayer, kind]);
+  const captureOpening = () => ({
+    active,
+    contextualLayer,
+    kind,
+    layer: active
+      ? Math.max(contextualLayer, getTopOverlayLayer() + OVERLAY_Z[kind])
+      : contextualLayer,
+  });
+  const [opening, setOpening] = useState(captureOpening);
+  if (
+    opening.active !== active ||
+    opening.contextualLayer !== contextualLayer ||
+    opening.kind !== kind
+  ) {
+    const next = captureOpening();
+    setOpening(next);
+    return next.layer;
+  }
+  return opening.layer;
 }
 
 export function useCurrentOverlayLayer(): number {
@@ -78,304 +84,3 @@ export function useCurrentOverlayLayer(): number {
 export function OverlayLayerProvider({ layer, children }: { layer: number; children?: ReactNode }) {
   return createElement(OverlayLayerContext.Provider, { value: layer }, children);
 }
-
-type WebOverlayKeyHandler = (event: KeyboardEvent) => boolean;
-
-interface WebOverlayEntry {
-  id: symbol;
-  order: number;
-  getLayer: () => number;
-  getScope: () => HTMLElement | null;
-  getKeyHandler: () => WebOverlayKeyHandler;
-  restoreFocus: HTMLElement | null;
-  manageFocus: boolean;
-}
-
-const webOverlayEntries: WebOverlayEntry[] = [];
-let webOverlayOrder = 0;
-let webOverlayListenersAttached = false;
-let webOverlayFocusCheckQueued = false;
-
-interface RemoveWebOverlayOptions {
-  restoreFocus?: boolean;
-}
-
-function getTopWebOverlay(): WebOverlayEntry | undefined {
-  return webOverlayEntries.reduce<WebOverlayEntry | undefined>((top, entry) => {
-    if (!top) return entry;
-    const layerDifference = entry.getLayer() - top.getLayer();
-    return layerDifference > 0 || (layerDifference === 0 && entry.order > top.order) ? entry : top;
-  }, undefined);
-}
-
-export function hasActiveWebOverlay(): boolean {
-  return getTopWebOverlay() !== undefined;
-}
-
-/**
- * True while an element shown with the Popover API is open. Such a layer
- * floats above the app like a registered overlay but lives outside the
- * registry: plugins draw their panels this way, since they cannot register.
- */
-export function hasOpenDomPopover(): boolean {
-  if (typeof document === "undefined") return false;
-  try {
-    return document.querySelector(":popover-open") !== null;
-  } catch {
-    // An engine without the Popover API rejects the selector, and has none open.
-    return false;
-  }
-}
-
-/**
- * Whether a key belongs to an open popover rather than to the app's shortcuts.
- * An open popover (a plugin's panel) is the top layer and closes on its own
- * Escape listener, which runs after the shortcut engine's capture listener:
- * Escape must not also interrupt the running agent.
- */
-export function keyBelongsToDomPopover(event: Pick<KeyboardEvent, "key">): boolean {
-  return event.key === "Escape" && hasOpenDomPopover();
-}
-
-function getFocusableElements(scope: HTMLElement): HTMLElement[] {
-  const selector = [
-    "a[href]",
-    "button:not([disabled])",
-    "input:not([disabled])",
-    "select:not([disabled])",
-    "textarea:not([disabled])",
-    '[tabindex]:not([tabindex="-1"])',
-  ].join(",");
-
-  return Array.from(scope.querySelectorAll<HTMLElement>(selector)).filter(
-    (element) =>
-      element.getAttribute("aria-hidden") !== "true" &&
-      !element.hasAttribute("hidden") &&
-      element.getClientRects().length > 0,
-  );
-}
-
-function focusFirstElement(scope: HTMLElement): void {
-  const firstMenuItem = scope.querySelector<HTMLElement>(
-    '[data-menu-item="true"]:not([data-menu-disabled="true"])',
-  );
-  const first = firstMenuItem ?? getFocusableElements(scope)[0];
-  (first ?? scope).focus();
-}
-
-function handleWebOverlayFocus(event: FocusEvent): void {
-  const top = getTopWebOverlay();
-  const scope = top?.getScope();
-  if (!top?.manageFocus || !scope || scope.contains(event.target as Node)) return;
-  if (webOverlayFocusCheckQueued) return;
-
-  // React can autofocus a child before its parent scope ref attaches. Defer
-  // enforcement until the commit finishes so a newly mounted higher overlay
-  // can register without the previous scope stealing the requested focus.
-  webOverlayFocusCheckQueued = true;
-  queueMicrotask(() => {
-    webOverlayFocusCheckQueued = false;
-    const currentTop = getTopWebOverlay();
-    const currentScope = currentTop?.getScope();
-    if (!currentTop?.manageFocus || !currentScope || currentScope.contains(document.activeElement))
-      return;
-    focusFirstElement(currentScope);
-  });
-}
-
-/**
- * Gives the top painted overlay first refusal on a key before app-wide shortcuts run.
- * The window listener below is the fallback for keys nobody routes through the shortcut engine.
- */
-export function dispatchTopWebOverlayKeyDown(event: KeyboardEvent): boolean {
-  // Composition keys belong to the active text field. A modal must not turn an
-  // IME candidate confirmation into an overlay shortcut before the browser has
-  // committed the composed text.
-  if (event.isComposing || event.key === "Process") return false;
-
-  const top = getTopWebOverlay();
-  const scope = top?.getScope();
-  if (!top || !scope) return false;
-
-  if (top.manageFocus && event.key === "Tab") {
-    const focusable = getFocusableElements(scope);
-    const first = focusable[0];
-    const last = focusable[focusable.length - 1];
-    const active = document.activeElement;
-    const shouldWrapBackward = event.shiftKey && (!scope.contains(active) || active === first);
-    const shouldWrapForward = !event.shiftKey && (!scope.contains(active) || active === last);
-    if (shouldWrapBackward || shouldWrapForward) {
-      event.preventDefault();
-      event.stopImmediatePropagation();
-      (shouldWrapBackward ? last : first)?.focus();
-      if (!first) scope.focus();
-      return true;
-    }
-  }
-
-  if (!top.getKeyHandler()(event)) return false;
-  event.stopImmediatePropagation();
-  return true;
-}
-
-function handleWebOverlayKeyDown(event: KeyboardEvent): void {
-  dispatchTopWebOverlayKeyDown(event);
-}
-
-function attachWebOverlayListeners(): void {
-  if (webOverlayListenersAttached) return;
-  window.addEventListener("keydown", handleWebOverlayKeyDown, true);
-  document.addEventListener("focusin", handleWebOverlayFocus, true);
-  webOverlayListenersAttached = true;
-}
-
-function detachWebOverlayListeners(): void {
-  if (!webOverlayListenersAttached || webOverlayEntries.length > 0) return;
-  window.removeEventListener("keydown", handleWebOverlayKeyDown, true);
-  document.removeEventListener("focusin", handleWebOverlayFocus, true);
-  webOverlayListenersAttached = false;
-}
-
-function addWebOverlay(entry: WebOverlayEntry): (options?: RemoveWebOverlayOptions) => void {
-  webOverlayEntries.push(entry);
-  attachWebOverlayListeners();
-
-  const focusFrame = window.requestAnimationFrame(() => {
-    const scope = entry.getScope();
-    if (
-      entry.manageFocus &&
-      getTopWebOverlay() === entry &&
-      scope &&
-      !scope.contains(document.activeElement)
-    ) {
-      focusFirstElement(scope);
-    }
-  });
-
-  return (options) => {
-    window.cancelAnimationFrame(focusFrame);
-    const index = webOverlayEntries.findIndex((candidate) => candidate.id === entry.id);
-    if (index !== -1) webOverlayEntries.splice(index, 1);
-    detachWebOverlayListeners();
-    if (
-      entry.manageFocus &&
-      options?.restoreFocus !== false &&
-      entry.restoreFocus &&
-      document.contains(entry.restoreFocus)
-    ) {
-      entry.restoreFocus.focus();
-    }
-  };
-}
-
-interface WebOverlayRegistration {
-  active: boolean;
-  layer: number;
-  onKeyDown: WebOverlayKeyHandler;
-  restoreFocusRef?: React.RefObject<unknown>;
-  /** Hover surfaces claim overlay keys while preserving the user's existing focus. */
-  manageFocus?: boolean;
-}
-
-/**
- * Registers a focus scope in the same relative layer model used for painting.
- * Only the highest painted overlay receives keyboard input. By default, focus is trapped
- * there and restored to the opener when it closes; hover surfaces preserve focus instead.
- */
-export function useWebOverlayRegistration({
-  active,
-  layer,
-  onKeyDown,
-  manageFocus = true,
-  restoreFocusRef: preferredRestoreFocusRef,
-}: WebOverlayRegistration) {
-  const idRef = useRef(Symbol("web-overlay"));
-  const scopeRef = useRef<HTMLElement | null>(null);
-  const layerRef = useRef(layer);
-  const keyHandlerRef = useRef(onKeyDown);
-  const capturedRestoreFocusRef = useRef<HTMLElement | null>(null);
-  const removeEntryRef = useRef<((options?: RemoveWebOverlayOptions) => void) | null>(null);
-  const detachedRemoveEntryRef = useRef<((options?: RemoveWebOverlayOptions) => void) | null>(null);
-  const registeredRef = useRef(false);
-  const activeRef = useRef(active);
-  const wasActiveRef = useRef(false);
-
-  activeRef.current = active;
-  layerRef.current = layer;
-  keyHandlerRef.current = onKeyDown;
-  if (active && !wasActiveRef.current && typeof document !== "undefined") {
-    const requestedRestoreTarget = preferredRestoreFocusRef?.current;
-    if (requestedRestoreTarget instanceof HTMLElement) {
-      capturedRestoreFocusRef.current = requestedRestoreTarget;
-    } else {
-      capturedRestoreFocusRef.current =
-        document.activeElement instanceof HTMLElement ? document.activeElement : null;
-    }
-  }
-  wasActiveRef.current = active;
-
-  const syncRegistration = useCallback(() => {
-    const shouldRegister =
-      activeRef.current &&
-      scopeRef.current != null &&
-      typeof window !== "undefined" &&
-      typeof document !== "undefined";
-    if (!shouldRegister) {
-      const shouldRestoreFocus = !activeRef.current;
-      if (registeredRef.current || shouldRestoreFocus) {
-        removeEntryRef.current?.({ restoreFocus: shouldRestoreFocus });
-      }
-      registeredRef.current = false;
-      if (shouldRestoreFocus) {
-        removeEntryRef.current = null;
-        detachedRemoveEntryRef.current = null;
-      }
-      return;
-    }
-    if (registeredRef.current) return;
-
-    detachedRemoveEntryRef.current = null;
-    const entry: WebOverlayEntry = {
-      id: idRef.current,
-      order: ++webOverlayOrder,
-      getLayer: () => layerRef.current,
-      getScope: () => scopeRef.current,
-      getKeyHandler: () => keyHandlerRef.current,
-      restoreFocus: capturedRestoreFocusRef.current,
-      manageFocus,
-    };
-    removeEntryRef.current = addWebOverlay(entry);
-    registeredRef.current = true;
-  }, [manageFocus]);
-
-  const setScope = useCallback(
-    (node: unknown) => {
-      scopeRef.current =
-        typeof HTMLElement !== "undefined" && node instanceof HTMLElement ? node : null;
-      if (!scopeRef.current && activeRef.current) {
-        const removeEntry = removeEntryRef.current;
-        removeEntry?.({ restoreFocus: false });
-        detachedRemoveEntryRef.current = removeEntry;
-        removeEntryRef.current = null;
-        registeredRef.current = false;
-      }
-      // Host refs attach before descendant layout effects and autofocus. Register
-      // here so the previous overlay cannot redirect that pending focus.
-      syncRegistration();
-    },
-    [syncRegistration],
-  );
-
-  useLayoutEffect(() => {
-    syncRegistration();
-    return () => {
-      const removeEntry = removeEntryRef.current ?? detachedRemoveEntryRef.current;
-      removeEntry?.();
-      removeEntryRef.current = null;
-      detachedRemoveEntryRef.current = null;
-      registeredRef.current = false;
-    };
-  }, [active, syncRegistration]);
-
-  return setScope;
-}
diff --git a/packages/app/src/mobile-panels/gesture-intent.test.ts b/packages/app/src/mobile-panels/gesture-intent.test.ts
index 74035096fb..a85c25e81b 100644
--- a/packages/app/src/mobile-panels/gesture-intent.test.ts
+++ b/packages/app/src/mobile-panels/gesture-intent.test.ts
@@ -3,19 +3,36 @@ import { describe, expect, it } from "vitest";
 import { resolveMobilePanelGestureIntent } from "./gesture-intent";
 
 describe("mobile panel gesture intent", () => {
+  it("rejects a pending swipe when presentation changes before activation", () => {
+    expect(
+      resolveMobilePanelGestureIntent({
+        enabled: false,
+        deltaX: 40,
+        deltaY: 2,
+        direction: 1,
+        openGesturesBlocked: false,
+        openEdge: null,
+      }),
+    ).toBe("fail");
+  });
+
   it("blocks both panel-opening directions while the active surface owns horizontal dragging", () => {
     expect([
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: 40,
         deltaY: 2,
         direction: 1,
         openGesturesBlocked: true,
+        openEdge: null,
       }),
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: -40,
         deltaY: 2,
         direction: -1,
         openGesturesBlocked: true,
+        openEdge: null,
       }),
     ]).toEqual(["fail", "fail"]);
   });
@@ -23,17 +40,68 @@ describe("mobile panel gesture intent", () => {
   it("keeps ordinary horizontal panel gestures available when unblocked", () => {
     expect([
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: 40,
         deltaY: 2,
         direction: 1,
         openGesturesBlocked: false,
+        openEdge: null,
       }),
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: -40,
         deltaY: 2,
         direction: -1,
         openGesturesBlocked: false,
+        openEdge: null,
       }),
     ]).toEqual(["activate", "activate"]);
   });
+
+  it("opens phone web drawers only from the edge they slide in from", () => {
+    const swipe = { deltaY: 2, openGesturesBlocked: false };
+    expect([
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: 40,
+        direction: 1,
+        openEdge: { startX: 200, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: 40,
+        direction: 1,
+        openEdge: { startX: 12, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: -40,
+        direction: -1,
+        openEdge: { startX: 200, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: -40,
+        direction: -1,
+        openEdge: { startX: 388, windowWidth: 400 },
+      }),
+    ]).toEqual(["fail", "activate", "fail", "activate"]);
+  });
+
+  it("opens from anywhere when the layout does not require an edge start", () => {
+    expect(
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        deltaX: 40,
+        deltaY: 2,
+        direction: 1,
+        openGesturesBlocked: false,
+        openEdge: null,
+      }),
+    ).toBe("activate");
+  });
 });
diff --git a/packages/app/src/mobile-panels/gesture-intent.ts b/packages/app/src/mobile-panels/gesture-intent.ts
index 3399670924..6722ec0c0f 100644
--- a/packages/app/src/mobile-panels/gesture-intent.ts
+++ b/packages/app/src/mobile-panels/gesture-intent.ts
@@ -1,14 +1,39 @@
 export type MobilePanelGestureDirection = -1 | 1;
 export type MobilePanelGestureIntent = "activate" | "fail" | "wait";
 
+/** How far from the window edge an edge-only open gesture may start. */
+export const MOBILE_PANEL_OPEN_EDGE_WIDTH = 32;
+
+/**
+ * Where an edge-only open gesture started. Phone web opens drawers only from the edge they slide in
+ * from: interior horizontal scrollers (terminals, code blocks, diffs) keep their swipes there.
+ */
+export interface MobilePanelOpenEdge {
+  startX: number;
+  windowWidth: number;
+}
+
+function startsAtOpenEdge(edge: MobilePanelOpenEdge, direction: MobilePanelGestureDirection) {
+  "worklet";
+  return direction === 1
+    ? edge.startX <= MOBILE_PANEL_OPEN_EDGE_WIDTH
+    : edge.startX >= edge.windowWidth - MOBILE_PANEL_OPEN_EDGE_WIDTH;
+}
+
 export function resolveMobilePanelGestureIntent(input: {
+  enabled: boolean;
   deltaX: number;
   deltaY: number;
   direction: MobilePanelGestureDirection;
   openGesturesBlocked: boolean;
+  /** Required start edge for opening gestures, or `null` when they may start anywhere. */
+  openEdge: MobilePanelOpenEdge | null;
 }): MobilePanelGestureIntent {
   "worklet";
-  if (input.openGesturesBlocked) {
+  if (!input.enabled || input.openGesturesBlocked) {
+    return "fail";
+  }
+  if (input.openEdge && !startsAtOpenEdge(input.openEdge, input.direction)) {
     return "fail";
   }
   const directedDelta = input.deltaX * input.direction;
diff --git a/packages/app/src/mobile-panels/gestures.ts b/packages/app/src/mobile-panels/gestures.ts
index 2b3f3e11fe..c5261b298f 100644
--- a/packages/app/src/mobile-panels/gestures.ts
+++ b/packages/app/src/mobile-panels/gestures.ts
@@ -1,15 +1,27 @@
 import { createContext, useContext, useRef, type RefObject, useCallback, useMemo } from "react";
-import { Gesture, type GestureType } from "react-native-gesture-handler";
-import { useSharedValue } from "react-native-reanimated";
+import { Gesture, PointerType, type GestureType } from "react-native-gesture-handler";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { isWeb } from "@/constants/platform";
 import { useHorizontalScrollOptional } from "@/contexts/horizontal-scroll-context";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import { usePanelStore } from "@/stores/panel-store";
 import { canBeginMobilePanelGesture, isMobilePanelGestureCurrent } from "./model";
 import { useMobilePanelsRuntime } from "./provider";
 import { resolveMobilePanelGestureIntent } from "./gesture-intent";
 
-const MOBILE_WEB_EDGE_SWIPE_WIDTH = 32;
+/** A horizontal surface takes the current touch before either panel opens. */
+export function usePanelAwareHorizontalScrollGesture() {
+  const { leftOpenGestureRef, rightOpenGestureRef } = useMobilePanelsRuntime();
+  return useMemo(
+    () =>
+      Gesture.Native()
+        .blocksExternalGesture(leftOpenGestureRef, rightOpenGestureRef)
+        .disallowInterruption(true),
+    [leftOpenGestureRef, rightOpenGestureRef],
+  );
+}
 
 function isCurrentSelection(startedRevision: number): boolean {
   return usePanelStore.getState().mobilePanel.revision === startedRevision;
@@ -23,6 +35,15 @@ function useGestureState() {
   };
 }
 
+/**
+ * Gates a sidebar pan on the UI thread. The sidebar flips between the dock and the overlay at
+ * runtime, and on Android flipping the handler's `.enabled()` config from false back to true left
+ * it inert until the app reloaded (RNGH 2.32), so `.enabled()` only carries the device capability.
+ */
+function useGestureGate(enabled: boolean) {
+  return useDerivedValue(() => enabled, [enabled]);
+}
+
 function useRevisionCommit(action: () => void) {
   return useCallback(
     (revision: number) => {
@@ -39,24 +60,35 @@ export function useOpenAgentListGesture(enabled: boolean) {
     beginGesture,
     finishGesture,
     leftOpenGestureRef,
+    leftPanelWidth: width,
     motionState,
     openGesturesBlocked,
     position,
     updateGesture,
     windowWidth,
   } = useMobilePanelsRuntime();
+  const { touchScreen: hasTouchScreen } = usePointerCapabilities();
+  // Phone web keeps interior swipes for the page's horizontal scrollers; the wide overlay opens
+  // from anywhere in the workspace.
+  const isCompact = useIsCompactFormFactor();
+  const openFromEdgeOnly = isWeb && isCompact;
   const horizontalScroll = useHorizontalScrollOptional();
   const { startedRevision, touchStartX, touchStartY } = useGestureState();
   const showMobileAgentList = usePanelStore((state) => state.showMobileAgentList);
   const commit = useRevisionCommit(showMobileAgentList);
+  const gate = useGestureGate(enabled);
 
   return useMemo(
     () =>
       Gesture.Pan()
         .withRef(leftOpenGestureRef)
-        .enabled(enabled)
+        .enabled(hasTouchScreen)
         .manualActivation(true)
-        .onTouchesDown((event) => {
+        .onTouchesDown((event, stateManager) => {
+          if (!gate.value || event.pointerType !== PointerType.TOUCH) {
+            stateManager.fail();
+            return;
+          }
           const touch = event.changedTouches[0];
           if (touch) {
             touchStartX.value = touch.absoluteX;
@@ -76,15 +108,16 @@ export function useOpenAgentListGesture(enabled: boolean) {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: gate.value,
             deltaX,
             deltaY,
             direction: 1,
             openGesturesBlocked: openGesturesBlocked.value,
+            openEdge: openFromEdgeOnly ? { startX: touchStartX.value, windowWidth } : null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent", position.value) ||
             horizontalScroll?.isAnyScrolledRight.value ||
-            (isWeb && touchStartX.value > MOBILE_WEB_EDGE_SWIPE_WIDTH) ||
             panIntent === "fail"
           ) {
             stateManager.fail();
@@ -98,10 +131,10 @@ export function useOpenAgentListGesture(enabled: boolean) {
           startedRevision.value = beginGesture({ origin: "agent" });
         })
         .onUpdate((event) => {
-          updateGesture(startedRevision.value, -event.translationX / windowWidth);
+          updateGesture(startedRevision.value, -event.translationX / width);
         })
         .onEnd((event, success) => {
-          const shouldOpen = event.translationX > windowWidth / 3 || event.velocityX > 500;
+          const shouldOpen = event.translationX > width / 3 || event.velocityX > 500;
           const result = finishGesture({
             startedRevision: startedRevision.value,
             target: shouldOpen ? "agent-list" : "agent",
@@ -113,43 +146,53 @@ export function useOpenAgentListGesture(enabled: boolean) {
         }),
     [
       commit,
-      enabled,
       beginGesture,
+      gate,
       finishGesture,
+      hasTouchScreen,
       horizontalScroll?.isAnyScrolledRight,
       leftOpenGestureRef,
       motionState,
+      openFromEdgeOnly,
       openGesturesBlocked,
       position,
       startedRevision,
       touchStartX,
       touchStartY,
       updateGesture,
+      width,
       windowWidth,
     ],
   );
 }
 
-export function useCloseAgentListGesture() {
+export function useCloseAgentListGesture(enabled = true) {
   const {
     beginGesture,
     finishGesture,
     leftCloseGestureRef,
+    leftPanelWidth: width,
     motionState,
     position,
     updateGesture,
-    windowWidth,
   } = useMobilePanelsRuntime();
+  const { touchScreen: hasTouchScreen } = usePointerCapabilities();
   const { startedRevision, touchStartX, touchStartY } = useGestureState();
   const showMobileAgent = usePanelStore((state) => state.showMobileAgent);
   const commit = useRevisionCommit(showMobileAgent);
+  const gate = useGestureGate(enabled);
 
   const gesture = useMemo(
     () =>
       Gesture.Pan()
         .withRef(leftCloseGestureRef)
+        .enabled(hasTouchScreen)
         .manualActivation(true)
-        .onTouchesDown((event) => {
+        .onTouchesDown((event, stateManager) => {
+          if (!gate.value || event.pointerType !== PointerType.TOUCH) {
+            stateManager.fail();
+            return;
+          }
           const touch = event.changedTouches[0];
           if (touch) {
             touchStartX.value = touch.absoluteX;
@@ -169,10 +212,12 @@ export function useCloseAgentListGesture() {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: gate.value,
             deltaX,
             deltaY,
             direction: -1,
             openGesturesBlocked: false,
+            openEdge: null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent-list", position.value) ||
@@ -191,10 +236,10 @@ export function useCloseAgentListGesture() {
           });
         })
         .onUpdate((event) => {
-          updateGesture(startedRevision.value, -1 - event.translationX / windowWidth);
+          updateGesture(startedRevision.value, -1 - event.translationX / width);
         })
         .onEnd((event, success) => {
-          const shouldClose = event.translationX < -windowWidth / 3 || event.velocityX < -500;
+          const shouldClose = event.translationX < -width / 3 || event.velocityX < -500;
           const result = finishGesture({
             startedRevision: startedRevision.value,
             target: shouldClose ? "agent" : "agent-list",
@@ -207,6 +252,8 @@ export function useCloseAgentListGesture() {
     [
       beginGesture,
       commit,
+      gate,
+      hasTouchScreen,
       finishGesture,
       leftCloseGestureRef,
       motionState,
@@ -215,7 +262,7 @@ export function useCloseAgentListGesture() {
       touchStartX,
       touchStartY,
       updateGesture,
-      windowWidth,
+      width,
     ],
   );
 
@@ -269,14 +316,15 @@ export function useOpenFileExplorerGesture({ enabled, onOpen }: OpenFileExplorer
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: enabled,
             deltaX,
             deltaY,
             direction: -1,
             openGesturesBlocked: openGesturesBlocked.value,
+            openEdge: isWeb ? { startX: touchStartX.value, windowWidth } : null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent", position.value) ||
-            (isWeb && touchStartX.value < windowWidth - MOBILE_WEB_EDGE_SWIPE_WIDTH) ||
             panIntent === "fail"
           ) {
             stateManager.fail();
@@ -363,10 +411,12 @@ export function useCloseFileExplorerGesture(enabled = true) {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: enabled,
             deltaX,
             deltaY,
             direction: 1,
             openGesturesBlocked: false,
+            openEdge: null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "file-explorer", position.value) ||
diff --git a/packages/app/src/mobile-panels/model.test.ts b/packages/app/src/mobile-panels/model.test.ts
index 5e2d8e229c..ca4ef04a8a 100644
--- a/packages/app/src/mobile-panels/model.test.ts
+++ b/packages/app/src/mobile-panels/model.test.ts
@@ -17,6 +17,7 @@ class MobilePanelsScenario {
   private startedRevision = -1;
   private state: MobilePanelMotionState;
   readonly commits: MobilePanelCommit[] = [];
+  readonly animations: MobilePanelView[] = [];
 
   constructor(target: MobilePanelView = "agent") {
     this.state = createMobilePanelMotionState({ target, revision: this.nextRevision });
@@ -74,6 +75,9 @@ class MobilePanelsScenario {
     if (transition.commit) {
       this.commits.push(transition.commit);
     }
+    if (transition.animationTarget) {
+      this.animations.push(transition.animationTarget);
+    }
   }
 }
 
@@ -237,6 +241,29 @@ describe("mobile panel ownership", () => {
     expect(panels.commits).toEqual([]);
   });
 
+  it("returns an interrupted drag to the anchor when the command keeps its target", () => {
+    const panels = new MobilePanelsScenario();
+
+    panels.beginGesture("agent").command("agent").finishGesture("agent-list");
+
+    expect(panels.animations).toEqual(["agent"]);
+    expect(panels.snapshot()).toEqual({
+      target: "agent",
+      motionTarget: "agent",
+      settledTarget: "agent",
+      revision: 1,
+    });
+    expect(panels.commits).toEqual([]);
+  });
+
+  it("lets the command for a completed drag adopt the drag's finishing motion", () => {
+    const panels = new MobilePanelsScenario();
+
+    panels.beginGesture("agent").finishGesture("agent-list").command("agent-list");
+
+    expect(panels.animations).toEqual(["agent-list"]);
+  });
+
   it("keeps the latest rapid command when position reaches a stale anchor", () => {
     const panels = new MobilePanelsScenario();
 
diff --git a/packages/app/src/mobile-panels/model.ts b/packages/app/src/mobile-panels/model.ts
index a7b821e82e..363bcfc450 100644
--- a/packages/app/src/mobile-panels/model.ts
+++ b/packages/app/src/mobile-panels/model.ts
@@ -78,7 +78,9 @@ export function transitionMobilePanel(
     if (event.selection.revision <= state.revision) {
       return { state };
     }
-    const continuesCurrentMotion = state.motionTarget === event.selection.target;
+    // An interrupted drag left the position between anchors, so it moves back even when the
+    // target is unchanged. Without a drag, the command adopts motion already heading there.
+    const continuesCurrentMotion = !state.gesture && state.motionTarget === event.selection.target;
     return {
       animationTarget: continuesCurrentMotion ? undefined : event.selection.target,
       state: {
diff --git a/packages/app/src/mobile-panels/presentation.tsx b/packages/app/src/mobile-panels/presentation.tsx
index cb919e4595..7336e7c029 100644
--- a/packages/app/src/mobile-panels/presentation.tsx
+++ b/packages/app/src/mobile-panels/presentation.tsx
@@ -29,26 +29,27 @@ export function MobilePanelOverlay({
   dockVisible = false,
   frameStyle,
 }: MobilePanelOverlayProps) {
-  const { position, windowWidth } = useMobilePanelsRuntime();
+  const { leftPanelWidth, position, windowWidth } = useMobilePanelsRuntime();
   const showMobileAgent = usePanelStore((state) => state.showMobileAgent);
   const overlayOpen = useIsMobilePanelActive(panel);
   const docked = presentation === "dock";
   const isOpen = docked ? dockVisible : overlayOpen;
   const hostId = useId();
   const isLeft = panel === "agent-list";
+  const width = isLeft ? leftPanelWidth : windowWidth;
 
   const sidebarAnimatedStyle = useAnimatedStyle(() => {
     if (docked) return { transform: [{ translateX: 0 }] };
-    const frame = getMobilePanelFrame(position.value, windowWidth);
+    const frame = getMobilePanelFrame(position.value, width);
     return {
       transform: [{ translateX: isLeft ? frame.leftTranslateX : frame.rightTranslateX }],
     };
-  }, [docked, isLeft, windowWidth]);
+  }, [docked, isLeft, width]);
 
   const backdropAnimatedStyle = useAnimatedStyle(() => {
-    const frame = getMobilePanelFrame(position.value, windowWidth);
+    const frame = getMobilePanelFrame(position.value, width);
     return { opacity: isLeft ? frame.leftBackdropOpacity : frame.rightBackdropOpacity };
-  }, [isLeft, windowWidth]);
+  }, [isLeft, width]);
 
   const overlayAnimatedStyle = useAnimatedStyle(() => {
     if (docked) return { opacity: 1, display: "flex" as const, pointerEvents: "box-none" as const };
@@ -73,11 +74,11 @@ export function MobilePanelOverlay({
     () => [
       docked ? styles.dockedPanel : styles.panel,
       !docked && positionedPanelStyle,
-      !docked && { width: windowWidth },
+      !docked && { width },
       panelStyle,
       sidebarAnimatedStyle,
     ],
-    [docked, panelStyle, positionedPanelStyle, sidebarAnimatedStyle, windowWidth],
+    [docked, panelStyle, positionedPanelStyle, sidebarAnimatedStyle, width],
   );
   let overlayPointerEvents: "auto" | "box-none" | "none";
   if (!isWeb) {
diff --git a/packages/app/src/mobile-panels/provider.tsx b/packages/app/src/mobile-panels/provider.tsx
index b2f97a2547..77c00558ce 100644
--- a/packages/app/src/mobile-panels/provider.tsx
+++ b/packages/app/src/mobile-panels/provider.tsx
@@ -1,3 +1,6 @@
+import { useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
+import { subscribeMobilePanelSelection } from "./selection";
+
 import {
   createContext,
   useCallback,
@@ -20,7 +23,10 @@ import {
   withTiming,
   type SharedValue,
 } from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import { resolveDesktopSidebarWidth } from "@/components/desktop-sidebar-layout";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
 import {
   usePanelStore,
@@ -45,6 +51,7 @@ interface MobilePanelsRuntime {
   beginGesture: (input: BeginGestureInput) => number;
   finishGesture: (input: FinishGestureInput) => MobilePanelCommit | null;
   leftCloseGestureRef: RefObject<GestureType | undefined>;
+  leftPanelWidth: number;
   leftOpenGestureRef: RefObject<GestureType | undefined>;
   motionState: SharedValue<MobilePanelMotionState>;
   openGesturesBlocked: SharedValue<boolean>;
@@ -68,8 +75,36 @@ interface FinishGestureInput {
 const MobilePanelsContext = createContext<MobilePanelsRuntime | null>(null);
 const MobilePanelActiveContext = createContext<MobilePanelView>("agent");
 
+/**
+ * The left sidebar's width: the full window for the compact drawer, the saved sidebar width
+ * clamped to the safe viewport on wide layouts. The wide dock, its overlay, and the gestures that
+ * drag it all read this one value.
+ */
+function useResolvedLeftPanelWidth(windowWidth: number): number {
+  const isCompact = useIsCompactFormFactor();
+  const insets = useSafeAreaInsets();
+  const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
+  const { height: windowHeight } = useWindowDimensions();
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
+  });
+  if (isCompact) return windowWidth;
+  return (
+    divisionLayout?.sidebarWidth ??
+    resolveDesktopSidebarWidth({
+      requestedWidth: sidebarWidth,
+      viewportWidth: windowWidth - insets.left - insets.right,
+    })
+  );
+}
+
 export function MobilePanelsProvider({ children }: { children: ReactNode }) {
   const { width: windowWidth } = useWindowDimensions();
+  const leftPanelWidth = useResolvedLeftPanelWidth(windowWidth);
   const initialSelection = useRef(usePanelStore.getState().mobilePanel).current;
   const position = useSharedValue(getMobilePanelAnchor(initialSelection.target));
   const motionState = useSharedValue(createMobilePanelMotionState(initialSelection));
@@ -152,11 +187,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
   );
 
   useEffect(() => {
-    return usePanelStore.subscribe((state, previousState) => {
-      const selection = state.mobilePanel;
-      if (selection === previousState.mobilePanel) {
-        return;
-      }
+    return subscribeMobilePanelSelection((selection) => {
       scheduleOnUI(applySelection, selection);
     });
   }, [applySelection]);
@@ -217,6 +248,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
       finishGesture,
       leftCloseGestureRef,
       leftOpenGestureRef,
+      leftPanelWidth,
       motionState,
       openGesturesBlocked,
       position,
@@ -228,6 +260,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
     [
       beginGesture,
       finishGesture,
+      leftPanelWidth,
       motionState,
       openGesturesBlocked,
       position,
@@ -255,6 +288,11 @@ export function useMobilePanelsRuntime(): MobilePanelsRuntime {
   return context;
 }
 
+/** The resolved left sidebar width shared by the dock, the overlay, and their gestures. */
+export function useLeftPanelWidth(): number {
+  return useMobilePanelsRuntime().leftPanelWidth;
+}
+
 export function useIsMobilePanelActive(panel: MobilePanelView): boolean {
   return useContext(MobilePanelActiveContext) === panel;
 }
diff --git a/packages/app/src/mobile-panels/selection.ts b/packages/app/src/mobile-panels/selection.ts
new file mode 100644
index 0000000000..f47d9e737c
--- /dev/null
+++ b/packages/app/src/mobile-panels/selection.ts
@@ -0,0 +1,14 @@
+import { usePanelStore, type MobilePanelSelection } from "@/stores/panel-store";
+
+/** Observe panel commands, including layout commands published before subscription. */
+export function subscribeMobilePanelSelection(
+  onSelection: (selection: MobilePanelSelection) => void,
+) {
+  const unsubscribe = usePanelStore.subscribe((state, previousState) => {
+    if (state.mobilePanel !== previousState.mobilePanel) {
+      onSelection(state.mobilePanel);
+    }
+  });
+  onSelection(usePanelStore.getState().mobilePanel);
+  return unsubscribe;
+}
diff --git a/packages/app/src/navigation/agent-route-resolution-view.tsx b/packages/app/src/navigation/agent-route-resolution-view.tsx
index 4518285b81..796e570309 100644
--- a/packages/app/src/navigation/agent-route-resolution-view.tsx
+++ b/packages/app/src/navigation/agent-route-resolution-view.tsx
@@ -57,10 +57,10 @@ export function AgentRouteResolutionView({
           <Text style={styles.error}>{resolution.error}</Text>
         </View>
         <View style={styles.actions}>
-          <Button size="sm" variant="default" leftIcon={RotateCw} onPress={onRetry}>
+          <Button variant="default" leftIcon={RotateCw} onPress={onRetry}>
             {t("common.actions.retry")}
           </Button>
-          <Button size="sm" variant="outline" leftIcon={ArrowLeftToLine} onPress={onBack}>
+          <Button variant="outline" leftIcon={ArrowLeftToLine} onPress={onBack}>
             {t("common.actions.back")}
           </Button>
         </View>
@@ -95,10 +95,10 @@ export function AgentRouteResolutionView({
       </View>
       {!isConnecting ? (
         <View style={styles.actions}>
-          <Button size="sm" variant="default" leftIcon={RotateCw} onPress={onRetry}>
+          <Button variant="default" leftIcon={RotateCw} onPress={onRetry}>
             {t("common.actions.retry")}
           </Button>
-          <Button size="sm" variant="outline" leftIcon={Settings} onPress={onManageHost}>
+          <Button variant="outline" leftIcon={Settings} onPress={onManageHost}>
             {t("workspace.route.manageHost")}
           </Button>
         </View>
diff --git a/packages/app/src/navigation/host-runtime-bootstrap.test.ts b/packages/app/src/navigation/host-runtime-bootstrap.test.ts
index 6e1e130090..fe7687886c 100644
--- a/packages/app/src/navigation/host-runtime-bootstrap.test.ts
+++ b/packages/app/src/navigation/host-runtime-bootstrap.test.ts
@@ -177,6 +177,7 @@ describe("resolveStartupRoute", () => {
     workspaceSelectionStatus: "unknown" as const,
     isWorkspaceSelectionLoaded: true,
     hasGivenUpWaitingForHost: false,
+    isWaitingForSetup: false,
   };
   const baseHostInput = {
     route: { kind: "host" as const, serverId: "server-saved" },
@@ -278,6 +279,28 @@ describe("resolveStartupRoute", () => {
     ).toEqual({ kind: "redirect", href: "/h/srv-desktop" });
   });
 
+  it("holds the splash over the empty home while setup may still open", () => {
+    expect(
+      resolveStartupRoute({
+        ...baseIndexInput,
+        hosts: [{ serverId: "srv-desktop" }],
+        anyOnlineHostServerId: "srv-desktop",
+        isWaitingForSetup: true,
+      }),
+    ).toEqual({ kind: "splash" });
+  });
+
+  it("restores a saved workspace without waiting for setup", () => {
+    expect(
+      resolveStartupRoute({
+        ...baseIndexInput,
+        hosts: [{ serverId: "server-1" }],
+        workspaceSelection: { serverId: "server-1", workspaceId: "workspace-a" },
+        isWaitingForSetup: true,
+      }),
+    ).toEqual({ kind: "redirect", href: "/h/server-1" });
+  });
+
   it("keeps a known connecting host in app-owned routing instead of showing welcome", () => {
     expect(
       resolveStartupRoute({
diff --git a/packages/app/src/navigation/host-runtime-bootstrap.ts b/packages/app/src/navigation/host-runtime-bootstrap.ts
index 8ee1f7bfb2..c78b40c1cc 100644
--- a/packages/app/src/navigation/host-runtime-bootstrap.ts
+++ b/packages/app/src/navigation/host-runtime-bootstrap.ts
@@ -117,6 +117,8 @@ export interface ResolveIndexStartupRouteInput extends ResolveStartupRouteBaseIn
   workspaceSelectionStatus: WorkspaceSelectionStatus;
   isWorkspaceSelectionLoaded: boolean;
   hasGivenUpWaitingForHost: boolean;
+  /** Setup may still open over the empty home; see `useIsSetupDecisionPending`. */
+  isWaitingForSetup: boolean;
 }
 
 export interface ResolveHostStartupRouteInput extends ResolveStartupRouteBaseInput {
@@ -198,6 +200,12 @@ function resolveReadyIndexStartupRoute(input: ResolveIndexStartupRouteInput): St
     };
   }
 
+  // Without a workspace to restore, startup lands on the empty home. A new user's setup opens
+  // over it, so hold the splash until that is known instead of flashing the home first.
+  if (input.isWaitingForSetup) {
+    return { kind: "splash" };
+  }
+
   if (input.anyOnlineHostServerId) {
     return { kind: "redirect", href: buildHostRootRoute(input.anyOnlineHostServerId) };
   }
diff --git a/packages/app/src/onboarding/index.ts b/packages/app/src/onboarding/index.ts
new file mode 100644
index 0000000000..78d3da6016
--- /dev/null
+++ b/packages/app/src/onboarding/index.ts
@@ -0,0 +1,11 @@
+/**
+ * First-run setup: a one-time modal that walks a new user through the surfaces Settings
+ * already has — appearance, providers, projects, Paseo tools and phone pairing.
+ *
+ * The app shell mounts the host, startup waits for its decision, and Settings reopens it. Whether
+ * it opens, which steps it has, and how completion is remembered stay inside; import from
+ * `@/onboarding` only.
+ */
+export { OnboardingHost } from "./onboarding-host";
+export { useOpenOnboarding } from "./use-open-onboarding";
+export { useIsSetupDecisionPending } from "./use-setup-decision-pending";
diff --git a/packages/app/src/onboarding/internal/completion-storage.ts b/packages/app/src/onboarding/internal/completion-storage.ts
new file mode 100644
index 0000000000..f50ef7cacf
--- /dev/null
+++ b/packages/app/src/onboarding/internal/completion-storage.ts
@@ -0,0 +1,25 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { z } from "zod";
+import { readValidatedJson } from "@/storage/validated-storage";
+import type { OnboardingCompletionStorage } from "./model";
+
+export const ONBOARDING_STORAGE_KEY = "@paseo:onboarding";
+
+const OnboardingRecordSchema = z.object({ completedAt: z.string() });
+
+export const asyncStorageOnboardingCompletion: OnboardingCompletionStorage = {
+  async isCompleted() {
+    const record = await readValidatedJson(
+      AsyncStorage,
+      ONBOARDING_STORAGE_KEY,
+      OnboardingRecordSchema,
+    );
+    return record !== null;
+  },
+  async markCompleted() {
+    await AsyncStorage.setItem(
+      ONBOARDING_STORAGE_KEY,
+      JSON.stringify({ completedAt: new Date().toISOString() }),
+    );
+  },
+};
diff --git a/packages/app/src/onboarding/internal/model.test.ts b/packages/app/src/onboarding/internal/model.test.ts
new file mode 100644
index 0000000000..5838876e91
--- /dev/null
+++ b/packages/app/src/onboarding/internal/model.test.ts
@@ -0,0 +1,220 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createOnboardingModel,
+  type OnboardingCompletionStorage,
+  type OnboardingModel,
+  type OnboardingSetupHost,
+} from "./model";
+
+class MemoryCompletionStorage implements OnboardingCompletionStorage {
+  completed: boolean;
+
+  constructor(completed = false) {
+    this.completed = completed;
+  }
+
+  async isCompleted(): Promise<boolean> {
+    return this.completed;
+  }
+
+  async markCompleted(): Promise<void> {
+    this.completed = true;
+  }
+}
+
+const FRESH_HOST: OnboardingSetupHost = {
+  serverId: "local",
+  isConnected: true,
+  hasHydratedWorkspaces: true,
+  hasProjects: false,
+};
+
+/** Presses Continue on whatever step is showing. */
+function advance(model: OnboardingModel) {
+  const state = model.getState();
+  if (state.status !== "open") throw new Error("setup is not open");
+  model.next(state.visit);
+}
+
+function currentVisit(model: OnboardingModel): number {
+  const state = model.getState();
+  if (state.status !== "open") throw new Error("setup is not open");
+  return state.visit;
+}
+
+async function openModel(storage = new MemoryCompletionStorage()) {
+  const model = createOnboardingModel({ storage });
+  await model.ready;
+  return model;
+}
+
+describe("onboarding model", () => {
+  it("opens on the appearance step for a connected host with no projects", async () => {
+    const model = await openModel();
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+
+    expect(model.getState()).toMatchObject({
+      status: "open",
+      serverId: "local",
+      steps: ["appearance", "providers", "projects", "orchestration", "phone"],
+      stepIndex: 0,
+    });
+  });
+
+  it("waits until the host is connected and its workspaces are hydrated", async () => {
+    const model = await openModel();
+
+    model.applySetupHost(null, { includePhoneStep: true });
+    model.applySetupHost({ ...FRESH_HOST, isConnected: false }, { includePhoneStep: true });
+    model.applySetupHost(
+      { ...FRESH_HOST, hasHydratedWorkspaces: false },
+      { includePhoneStep: true },
+    );
+    expect(model.getState()).toEqual({ status: "deciding" });
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+    expect(model.getState().status).toBe("open");
+  });
+
+  it("stays hidden for a host that already has projects, even after they are removed", async () => {
+    const model = await openModel();
+
+    model.applySetupHost({ ...FRESH_HOST, hasProjects: true }, { includePhoneStep: true });
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+
+    expect(model.getState()).toEqual({ status: "hidden" });
+  });
+
+  it("stays hidden once setup was completed on this client", async () => {
+    const model = await openModel(new MemoryCompletionStorage(true));
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+
+    expect(model.getState()).toEqual({ status: "hidden" });
+  });
+
+  it("decides only after the completion record has loaded", async () => {
+    const model = createOnboardingModel({ storage: new MemoryCompletionStorage(true) });
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+    expect(model.getState()).toEqual({ status: "deciding" });
+
+    await model.ready;
+    expect(model.getState()).toEqual({ status: "hidden" });
+  });
+
+  it("keeps the modal open when the host gains its first project during setup", async () => {
+    const model = await openModel();
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+    advance(model);
+    advance(model);
+
+    model.applySetupHost({ ...FRESH_HOST, hasProjects: true }, { includePhoneStep: true });
+
+    expect(model.getState()).toMatchObject({ status: "open", stepIndex: 2 });
+  });
+
+  it("omits the phone step when the client is a phone", async () => {
+    const model = await openModel();
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: false });
+
+    expect(model.getState()).toMatchObject({
+      steps: ["appearance", "providers", "projects", "orchestration"],
+    });
+  });
+
+  it("moves between steps without leaving the step list", async () => {
+    const model = await openModel();
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: false });
+
+    model.back();
+    expect(model.getState()).toMatchObject({ stepIndex: 0 });
+    advance(model);
+    advance(model);
+    advance(model);
+    expect(model.getState()).toMatchObject({ stepIndex: 3 });
+    model.goTo("providers");
+    expect(model.getState()).toMatchObject({ stepIndex: 1 });
+    model.back();
+    expect(model.getState()).toMatchObject({ stepIndex: 0 });
+  });
+
+  it("ignores a late advance from a step visit the user already left", async () => {
+    const model = await openModel(new MemoryCompletionStorage(true));
+    model.reopen("local", { includePhoneStep: true });
+    model.goTo("projects");
+
+    // Projects are still being added when the user leaves Projects and comes back.
+    const addingFrom = currentVisit(model);
+    model.goTo("appearance");
+    model.goTo("projects");
+    model.next(addingFrom);
+    expect(model.getState()).toMatchObject({ stepIndex: 2 });
+
+    // Or closes setup, opens it again and returns to Projects before the add finishes.
+    await model.complete();
+    model.reopen("local", { includePhoneStep: true });
+    model.goTo("projects");
+    model.next(addingFrom);
+    expect(model.getState()).toMatchObject({ status: "open", stepIndex: 2 });
+  });
+
+  it("moving on from the last step finishes setup, unless the user left that step first", async () => {
+    const storage = new MemoryCompletionStorage();
+    const model = await openModel(storage);
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: false });
+    model.goTo("orchestration");
+
+    // Finish is applying choices when the user goes back to Projects.
+    const finishingFrom = currentVisit(model);
+    model.back();
+    model.next(finishingFrom);
+    expect(model.getState()).toMatchObject({ status: "open", stepIndex: 2 });
+    expect(storage.completed).toBe(false);
+
+    advance(model);
+    advance(model);
+    await vi.waitFor(() => expect(storage.completed).toBe(true));
+    expect(model.getState()).toEqual({ status: "hidden" });
+  });
+
+  it("records completion when setup closes, so it does not open again", async () => {
+    const storage = new MemoryCompletionStorage();
+    const model = await openModel(storage);
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+
+    await model.complete();
+
+    expect(model.getState()).toEqual({ status: "hidden" });
+    expect(storage.completed).toBe(true);
+    const relaunched = await openModel(storage);
+    relaunched.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+    expect(relaunched.getState()).toEqual({ status: "hidden" });
+  });
+
+  it("reopens on the first step for an existing user", async () => {
+    const model = await openModel(new MemoryCompletionStorage(true));
+    model.applySetupHost({ ...FRESH_HOST, hasProjects: true }, { includePhoneStep: true });
+
+    model.reopen("local", { includePhoneStep: true });
+
+    expect(model.getState()).toMatchObject({ status: "open", serverId: "local", stepIndex: 0 });
+  });
+
+  it("notifies subscribers on every state change", async () => {
+    const model = await openModel();
+    const seen: string[] = [];
+    model.subscribe(() => {
+      const state = model.getState();
+      seen.push(state.status === "open" ? `open:${state.stepIndex}` : state.status);
+    });
+
+    model.applySetupHost(FRESH_HOST, { includePhoneStep: true });
+    advance(model);
+    await model.complete();
+
+    expect(seen).toEqual(["open:0", "open:1", "hidden"]);
+  });
+});
diff --git a/packages/app/src/onboarding/internal/model.ts b/packages/app/src/onboarding/internal/model.ts
new file mode 100644
index 0000000000..f8aaf46d4f
--- /dev/null
+++ b/packages/app/src/onboarding/internal/model.ts
@@ -0,0 +1,170 @@
+export type OnboardingStepId = "appearance" | "providers" | "projects" | "orchestration" | "phone";
+
+const STEPS_WITHOUT_PHONE: readonly OnboardingStepId[] = [
+  "appearance",
+  "providers",
+  "projects",
+  "orchestration",
+];
+const STEPS_WITH_PHONE: readonly OnboardingStepId[] = [...STEPS_WITHOUT_PHONE, "phone"];
+
+export interface OnboardingCompletionStorage {
+  isCompleted(): Promise<boolean>;
+  markCompleted(): Promise<void>;
+}
+
+/** The host setup runs against: the desktop's managed daemon, otherwise the first saved host. */
+export interface OnboardingSetupHost {
+  serverId: string;
+  isConnected: boolean;
+  hasHydratedWorkspaces: boolean;
+  hasProjects: boolean;
+}
+
+export interface OnboardingStepOptions {
+  /** False when the client is itself a phone, where pairing a phone makes no sense. */
+  includePhoneStep: boolean;
+}
+
+export type OnboardingState =
+  | { status: "deciding" }
+  | { status: "hidden" }
+  | {
+      status: "open";
+      serverId: string;
+      steps: readonly OnboardingStepId[];
+      stepIndex: number;
+      /** Identifies this stay on the current step; it changes on every move, close or reopen. */
+      visit: number;
+    };
+
+export interface OnboardingModel {
+  /** Resolves once the completion record has loaded. */
+  ready: Promise<void>;
+  getState(): OnboardingState;
+  subscribe(listener: () => void): () => void;
+  applySetupHost(host: OnboardingSetupHost | null, options: OnboardingStepOptions): void;
+  reopen(serverId: string, options: OnboardingStepOptions): void;
+  /**
+   * Moves on from the step visit the caller saw; from the last step, that finishes setup. A no-op
+   * once that visit ended, so an action that finishes late never moves a step the user left or
+   * closes a setup they went back in, or closed and reopened.
+   */
+  next(visit: number): void;
+  back(): void;
+  goTo(step: OnboardingStepId): void;
+  /** Closes setup, whether the user finished or skipped it, and remembers that on this client. */
+  complete(): Promise<void>;
+}
+
+type Completion = "loading" | "completed" | "pending";
+
+interface PendingHost {
+  host: OnboardingSetupHost | null;
+  options: OnboardingStepOptions;
+}
+
+function isReadyForSetup(host: OnboardingSetupHost | null): host is OnboardingSetupHost {
+  return host !== null && host.isConnected && host.hasHydratedWorkspaces;
+}
+
+export function createOnboardingModel(input: {
+  storage: OnboardingCompletionStorage;
+}): OnboardingModel {
+  const listeners = new Set<() => void>();
+  let state: OnboardingState = { status: "deciding" };
+  let completion: Completion = "loading";
+  let pendingHost: PendingHost | null = null;
+  let visits = 0;
+
+  function openState(serverId: string, options: OnboardingStepOptions): OnboardingState {
+    visits += 1;
+    return {
+      status: "open",
+      serverId,
+      steps: options.includePhoneStep ? STEPS_WITH_PHONE : STEPS_WITHOUT_PHONE,
+      stepIndex: 0,
+      visit: visits,
+    };
+  }
+
+  function setState(next: OnboardingState) {
+    state = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  // The gate is decided once per launch: a host that later loses its projects, or a
+  // project added during setup, never flips the decision.
+  function decide() {
+    if (state.status !== "deciding" || completion === "loading") return;
+    if (completion === "completed") {
+      setState({ status: "hidden" });
+      return;
+    }
+    const host = pendingHost?.host ?? null;
+    if (!pendingHost || !isReadyForSetup(host)) return;
+    setState(
+      host.hasProjects ? { status: "hidden" } : openState(host.serverId, pendingHost.options),
+    );
+  }
+
+  function moveTo(stepIndex: number) {
+    if (state.status !== "open") return;
+    const clamped = Math.max(0, Math.min(stepIndex, state.steps.length - 1));
+    if (clamped === state.stepIndex) return;
+    visits += 1;
+    setState({ ...state, stepIndex: clamped, visit: visits });
+  }
+
+  async function loadCompletion(): Promise<void> {
+    try {
+      completion = (await input.storage.isCompleted()) ? "completed" : "pending";
+    } catch {
+      // An unreadable record must not trap an existing user in setup.
+      completion = "completed";
+    }
+    decide();
+  }
+
+  const ready = loadCompletion();
+
+  async function complete() {
+    completion = "completed";
+    setState({ status: "hidden" });
+    await input.storage.markCompleted();
+  }
+
+  return {
+    ready,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    applySetupHost(host, options) {
+      pendingHost = { host, options };
+      decide();
+    },
+    reopen(serverId, options) {
+      setState(openState(serverId, options));
+    },
+    next(visit) {
+      if (state.status !== "open" || state.visit !== visit) return;
+      if (state.stepIndex === state.steps.length - 1) void complete();
+      else moveTo(state.stepIndex + 1);
+    },
+    back() {
+      if (state.status === "open") moveTo(state.stepIndex - 1);
+    },
+    goTo(step) {
+      if (state.status !== "open") return;
+      const stepIndex = state.steps.indexOf(step);
+      if (stepIndex >= 0) moveTo(stepIndex);
+    },
+    complete,
+  };
+}
diff --git a/packages/app/src/onboarding/internal/onboarding-instance.ts b/packages/app/src/onboarding/internal/onboarding-instance.ts
new file mode 100644
index 0000000000..d6f73456fb
--- /dev/null
+++ b/packages/app/src/onboarding/internal/onboarding-instance.ts
@@ -0,0 +1,10 @@
+import { asyncStorageOnboardingCompletion } from "./completion-storage";
+import { createOnboardingModel, type OnboardingModel } from "./model";
+
+let instance: OnboardingModel | null = null;
+
+/** The app's one setup model, created on first use so storage is read once per launch. */
+export function getOnboardingModel(): OnboardingModel {
+  instance ??= createOnboardingModel({ storage: asyncStorageOnboardingCompletion });
+  return instance;
+}
diff --git a/packages/app/src/onboarding/internal/onboarding-modal.tsx b/packages/app/src/onboarding/internal/onboarding-modal.tsx
new file mode 100644
index 0000000000..0eb0418185
--- /dev/null
+++ b/packages/app/src/onboarding/internal/onboarding-modal.tsx
@@ -0,0 +1,394 @@
+import { useCallback, useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { Text, View, type PressableStateCallbackType } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { Check } from "lucide-react-native";
+import {
+  AdaptiveModalSheet,
+  FULL_SHEET_SNAP_POINTS,
+  SheetFooter,
+} from "@/components/adaptive-modal-sheet";
+import { PaseoLogo } from "@/components/icons/paseo-logo";
+import { Button } from "@/components/ui/button";
+import { PressHighlight } from "@/components/ui/press-highlight";
+import { ScrollView } from "@/components/ui/scroll-view";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { useProjectSuggestions, type ProjectSuggestionsController } from "@/project-suggestions";
+import type { Theme } from "@/styles/theme";
+import type { OnboardingModel, OnboardingState, OnboardingStepId } from "./model";
+import { useOrchestrationSetup, type OrchestrationSetupController } from "./orchestration-setup";
+import { OnboardingStepContent } from "./steps";
+
+type OpenState = Extract<OnboardingState, { status: "open" }>;
+
+const ThemedCheck = withUnistyles(Check);
+const accentForegroundMapping = (theme: Theme) => ({ color: theme.colors.accentForeground });
+
+export function OnboardingModal({ model, state }: { model: OnboardingModel; state: OpenState }) {
+  const { t } = useTranslation();
+  const isCompact = useIsCompactFormFactor();
+  const step = state.steps[state.stepIndex];
+  const isFirst = state.stepIndex === 0;
+  const isLast = state.stepIndex === state.steps.length - 1;
+  // Held here so Continue can add the checked folders; reading history from the first step means
+  // the Projects step rarely waits.
+  const projectSuggestions = useProjectSuggestions(state.serverId);
+  const { addChecked } = projectSuggestions;
+  const orchestration = useOrchestrationSetup(state.serverId);
+  const { apply: applyOrchestration } = orchestration;
+
+  const handleComplete = useCallback(() => {
+    void model.complete();
+  }, [model]);
+  const handleBack = useCallback(() => model.back(), [model]);
+  const { visit } = state;
+  // A step's own work runs before it moves on; from the last step, moving on finishes setup.
+  const handleAdvance = useCallback(() => model.next(visit), [model, visit]);
+  const handleAddSuggestions = useCallback(() => {
+    void (async () => {
+      if (await addChecked()) handleAdvance();
+    })();
+  }, [addChecked, handleAdvance]);
+  const handleApplyOrchestration = useCallback(() => {
+    void (async () => {
+      if (await applyOrchestration()) handleAdvance();
+    })();
+  }, [applyOrchestration, handleAdvance]);
+  const primary = usePrimaryAction({
+    step,
+    isLast,
+    projectSuggestions,
+    orchestration,
+    onAdvance: handleAdvance,
+    onAddSuggestions: handleAddSuggestions,
+    onApplyOrchestration: handleApplyOrchestration,
+  });
+
+  // The compact sheet stacks a title row, the step and the actions. The desktop card gives the
+  // step rail the full height instead: the brand tops the rail, the actions close the step pane,
+  // and the sheet floats its close button.
+  const compactHeader = useMemo(
+    () => ({
+      title: t("onboarding.setup.title"),
+      leading: <PaseoLogo size={LOGO_SIZE} />,
+      subtitle: (
+        <Text style={styles.stepCounter}>
+          {t("onboarding.setup.stepCounter", {
+            current: state.stepIndex + 1,
+            total: state.steps.length,
+          })}
+        </Text>
+      ),
+    }),
+    [state.stepIndex, state.steps.length, t],
+  );
+
+  const actions = (
+    <>
+      <View>
+        {isLast ? null : (
+          <Button variant="outline" onPress={handleComplete}>
+            {t("onboarding.setup.skip")}
+          </Button>
+        )}
+      </View>
+      <View style={styles.footerActions}>
+        {isFirst ? null : (
+          <Button variant="secondary" onPress={handleBack}>
+            {t("common.actions.back")}
+          </Button>
+        )}
+        <Button variant="default" onPress={primary.onPress} loading={primary.busy}>
+          {primary.label}
+        </Button>
+      </View>
+    </>
+  );
+
+  return (
+    <AdaptiveModalSheet
+      visible
+      onClose={handleComplete}
+      header={isCompact ? compactHeader : undefined}
+      footer={isCompact ? actions : undefined}
+      scrollable={false}
+      snapPoints={FULL_SHEET_SNAP_POINTS}
+      desktopMaxWidth={880}
+      desktopHeight={640}
+      contentStyle={styles.content}
+      testID="onboarding-modal"
+    >
+      <View style={styles.body}>
+        {isCompact ? null : <StepRail state={state} onSelect={model.goTo} />}
+        <View style={styles.pane}>
+          <ScrollView style={styles.paneScroll}>
+            {/* Padding lives on a wrapper: the ScrollView's contentContainerStyle skips Unistyles. */}
+            <View style={styles.paneContent}>
+              <View style={styles.stepHeader}>
+                <Text style={styles.stepTitle} accessibilityRole="header">
+                  {t(`onboarding.setup.steps.${step}.title`)}
+                </Text>
+                <Text style={styles.stepDescription}>
+                  {t(`onboarding.setup.steps.${step}.description`)}
+                </Text>
+              </View>
+              <OnboardingStepContent
+                step={step}
+                serverId={state.serverId}
+                projectSuggestions={projectSuggestions}
+                orchestration={orchestration}
+              />
+            </View>
+          </ScrollView>
+          {isCompact ? null : <SheetFooter>{actions}</SheetFooter>}
+        </View>
+      </View>
+    </AdaptiveModalSheet>
+  );
+}
+
+/**
+ * The footer's main button. On Projects, with folders checked, it adds them and moves on only once
+ * every one was added. On Orchestration it applies the switches and moves on once they all took.
+ * Otherwise it moves on. Moving on from the last step finishes setup, so that step's work still
+ * runs first; Orchestration is last in the compact layout.
+ */
+function usePrimaryAction(input: {
+  step: OnboardingStepId;
+  isLast: boolean;
+  projectSuggestions: ProjectSuggestionsController;
+  orchestration: OrchestrationSetupController;
+  onAdvance: () => void;
+  onAddSuggestions: () => void;
+  onApplyOrchestration: () => void;
+}): { label: string; busy: boolean; onPress: () => void } {
+  const { t } = useTranslation();
+  const {
+    step,
+    isLast,
+    projectSuggestions,
+    orchestration,
+    onAdvance,
+    onAddSuggestions,
+    onApplyOrchestration,
+  } = input;
+  const { checkedCount, isAdding } = projectSuggestions;
+  const advanceLabel = isLast ? t("onboarding.setup.finish") : t("onboarding.setup.continue");
+  // Rows leave the list as they are added, so the count can reach zero while adding.
+  if (step === "projects" && (isAdding || checkedCount > 0)) {
+    return {
+      label: isAdding
+        ? t("onboarding.setup.steps.projects.suggestions.adding")
+        : t("onboarding.setup.steps.projects.suggestions.addSelected", { count: checkedCount }),
+      busy: isAdding,
+      onPress: onAddSuggestions,
+    };
+  }
+  if (step === "orchestration") {
+    return { label: advanceLabel, busy: orchestration.isApplying, onPress: onApplyOrchestration };
+  }
+  return { label: advanceLabel, busy: false, onPress: onAdvance };
+}
+
+function StepRail({
+  state,
+  onSelect,
+}: {
+  state: OpenState;
+  onSelect: (step: OnboardingStepId) => void;
+}) {
+  const { t } = useTranslation();
+  return (
+    <View style={styles.rail}>
+      <View style={styles.railBrand}>
+        <PaseoLogo size={LOGO_SIZE} />
+        <Text style={styles.railTitle} numberOfLines={1}>
+          {t("onboarding.setup.title")}
+        </Text>
+      </View>
+      <View style={styles.railSteps}>
+        {state.steps.map((step, index) => (
+          <StepRailItem
+            key={step}
+            step={step}
+            number={index + 1}
+            current={index === state.stepIndex}
+            done={index < state.stepIndex}
+            onSelect={onSelect}
+          />
+        ))}
+      </View>
+    </View>
+  );
+}
+
+function StepRailItem({
+  step,
+  number,
+  current,
+  done,
+  onSelect,
+}: {
+  step: OnboardingStepId;
+  number: number;
+  current: boolean;
+  done: boolean;
+  onSelect: (step: OnboardingStepId) => void;
+}) {
+  const { t } = useTranslation();
+  const label = t(`onboarding.setup.steps.${step}.label`);
+  const handlePress = useCallback(() => onSelect(step), [onSelect, step]);
+  const accessibilityState = useMemo(() => ({ selected: current }), [current]);
+  const itemStyle = useCallback(
+    ({ hovered }: PressableStateCallbackType & { hovered?: boolean }) => [
+      styles.railItem,
+      hovered && !current && styles.railItemHovered,
+      current && styles.railItemCurrent,
+    ],
+    [current],
+  );
+  return (
+    <PressHighlight
+      style={itemStyle}
+      onPress={handlePress}
+      accessibilityRole="tab"
+      accessibilityLabel={label}
+      accessibilityState={accessibilityState}
+      aria-selected={current}
+    >
+      <View style={done || current ? styles.railBadgeActive : styles.railBadge}>
+        {done ? (
+          <ThemedCheck size={12} strokeWidth={3} uniProps={accentForegroundMapping} />
+        ) : (
+          <Text style={current ? styles.railBadgeTextActive : styles.railBadgeText}>{number}</Text>
+        )}
+      </View>
+      <Text style={current ? styles.railLabelCurrent : styles.railLabel} numberOfLines={1}>
+        {label}
+      </Text>
+    </PressHighlight>
+  );
+}
+
+const BADGE_SIZE = 20;
+const LOGO_SIZE = 20;
+
+const styles = StyleSheet.create((theme) => ({
+  content: {
+    padding: 0,
+    gap: 0,
+  },
+  body: {
+    flex: 1,
+    minHeight: 0,
+    flexDirection: "row",
+  },
+  rail: {
+    width: 200,
+    padding: theme.spacing[3],
+    borderRightWidth: theme.borderWidth[1],
+    borderRightColor: theme.colors.surface2,
+    backgroundColor: theme.colors.surface1,
+  },
+  // Inset like a rail item, so the logo sits on the badges' column.
+  railBrand: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+    paddingHorizontal: theme.spacing[2],
+    paddingVertical: theme.spacing[2],
+    marginBottom: theme.spacing[4],
+  },
+  railTitle: {
+    flexShrink: 1,
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.base,
+    fontWeight: theme.fontWeight.medium,
+  },
+  railSteps: {
+    gap: theme.spacing[1],
+  },
+  railItem: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+    paddingHorizontal: theme.spacing[2],
+    paddingVertical: theme.spacing[2],
+    borderRadius: theme.borderRadius.full,
+  },
+  railItemHovered: {
+    backgroundColor: theme.colors.surface2,
+  },
+  railItemCurrent: {
+    backgroundColor: theme.colors.surface2,
+  },
+  railBadge: {
+    width: BADGE_SIZE,
+    height: BADGE_SIZE,
+    borderRadius: BADGE_SIZE / 2,
+    borderWidth: theme.borderWidth[1],
+    borderColor: theme.colors.border,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  railBadgeActive: {
+    width: BADGE_SIZE,
+    height: BADGE_SIZE,
+    borderRadius: BADGE_SIZE / 2,
+    borderWidth: theme.borderWidth[1],
+    borderColor: theme.colors.accent,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  railBadgeText: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.base,
+  },
+  railBadgeTextActive: {
+    color: theme.colors.accentForeground,
+    fontSize: theme.fontSize.base,
+  },
+  railLabel: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.base,
+  },
+  railLabelCurrent: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.base,
+    fontWeight: theme.fontWeight.medium,
+  },
+  pane: {
+    flex: 1,
+    minHeight: 0,
+  },
+  paneScroll: {
+    flex: 1,
+    minHeight: 0,
+  },
+  paneContent: {
+    padding: theme.spacing[6],
+    gap: theme.spacing[6],
+  },
+  stepHeader: {
+    gap: theme.spacing[2],
+  },
+  stepTitle: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.xl,
+    fontWeight: theme.fontWeight.medium,
+  },
+  stepDescription: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.base,
+    lineHeight: theme.fontSize.base * 1.5,
+  },
+  stepCounter: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+  },
+  footerActions: {
+    flexDirection: "row",
+    gap: theme.spacing[2],
+  },
+}));
diff --git a/packages/app/src/onboarding/internal/orchestration-setup.ts b/packages/app/src/onboarding/internal/orchestration-setup.ts
new file mode 100644
index 0000000000..5606379dab
--- /dev/null
+++ b/packages/app/src/onboarding/internal/orchestration-setup.ts
@@ -0,0 +1,113 @@
+import { useCallback, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  areSkillsInstalled,
+  hasSelectedSkills,
+  useAgentSkills,
+  type AgentSkillsController,
+} from "@/agent-skills";
+import { useToast } from "@/contexts/toast-context";
+import { useCliInstall } from "@/desktop/hooks/use-install-status";
+import { useDaemonConfig } from "@/hooks/use-daemon-config";
+
+export type OrchestrationChoice = "tools" | "skills" | "cli";
+type Choices = Record<OrchestrationChoice, boolean>;
+
+const ALL_ON: Choices = { tools: true, skills: true, cli: true };
+
+export interface OrchestrationSetupController {
+  choices: Choices;
+  setChoice: (choice: OrchestrationChoice, on: boolean) => void;
+  /** Only the choices this host and app can act on: skills need host support, the CLI the desktop app. */
+  offered: Choices;
+  /** The skills row's picker and Update act on the host directly, through this. */
+  skills: AgentSkillsController;
+  isApplying: boolean;
+  /**
+   * Brings the host in line with the choices; resolves true only when every one took. Each failure
+   * is shown to the user.
+   */
+  apply: () => Promise<boolean>;
+}
+
+/**
+ * The Orchestration step's choices. Everything starts on and nothing touches the host or this
+ * computer until Continue applies them, the way checked projects are added.
+ */
+export function useOrchestrationSetup(serverId: string): OrchestrationSetupController {
+  const { t } = useTranslation();
+  const toast = useToast();
+  const skills = useAgentSkills(serverId);
+  const cli = useCliInstall();
+  const { config, patchConfig } = useDaemonConfig(serverId);
+  const [chosen, setChosen] = useState<Choices>(ALL_ON);
+  // With nothing picked there is nothing to install, so skills read as off, as they do in Settings.
+  const skillsSelected = skills.status === null || hasSelectedSkills(skills.status);
+  const choices = useMemo<Choices>(
+    () => ({ ...chosen, skills: chosen.skills && skillsSelected }),
+    [chosen, skillsSelected],
+  );
+  const [isApplying, setIsApplying] = useState(false);
+  const offered: Choices = {
+    tools: true,
+    skills: skills.connected && skills.supported,
+    cli: cli.available,
+  };
+
+  const setChoice = useCallback((choice: OrchestrationChoice, on: boolean) => {
+    setChosen((current) => ({ ...current, [choice]: on }));
+  }, []);
+
+  // What the host and this computer have now, or null while it is still being read. A choice is
+  // skipped only when it is known to match; an unknown state is always written.
+  const toolsOn = config ? config.mcp.injectIntoAgents !== false : null;
+  const skillsInstalled = skills.status ? areSkillsInstalled(skills.status) : null;
+  const cliInstalled = cli.status ? cli.status.installed : null;
+  const { reconcile, uninstall } = skills;
+  const { setInstalled: setCliInstalled } = cli;
+  const offersSkills = offered.skills;
+  const offersCli = offered.cli;
+
+  const setTools = useCallback(
+    (on: boolean) =>
+      patchConfig({ mcp: { injectIntoAgents: on } })
+        .then(Boolean, () => false)
+        .then((done) => {
+          if (!done) toast.error(t("settings.host.orchestration.enableTools.updateFailed"));
+          return done;
+        }),
+    [patchConfig, t, toast],
+  );
+  const setSkillsInstalled = useCallback(
+    (on: boolean) => (on ? reconcile() : uninstall()),
+    [reconcile, uninstall],
+  );
+
+  const apply = useCallback(async () => {
+    setIsApplying(true);
+    try {
+      const results = await Promise.all([
+        choices.tools === toolsOn ? true : setTools(choices.tools),
+        !offersSkills || choices.skills === skillsInstalled
+          ? true
+          : setSkillsInstalled(choices.skills),
+        !offersCli || choices.cli === cliInstalled ? true : setCliInstalled(choices.cli),
+      ]);
+      return results.every(Boolean);
+    } finally {
+      setIsApplying(false);
+    }
+  }, [
+    choices,
+    toolsOn,
+    setTools,
+    offersSkills,
+    skillsInstalled,
+    setSkillsInstalled,
+    offersCli,
+    cliInstalled,
+    setCliInstalled,
+  ]);
+
+  return { choices, setChoice, offered, skills, isApplying, apply };
+}
diff --git a/packages/app/src/onboarding/internal/steps/appearance-step.tsx b/packages/app/src/onboarding/internal/steps/appearance-step.tsx
new file mode 100644
index 0000000000..54ee902a62
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/appearance-step.tsx
@@ -0,0 +1,5 @@
+import { ThemePicker } from "@/appearance/theme-picker";
+
+export function AppearanceStep() {
+  return <ThemePicker />;
+}
diff --git a/packages/app/src/onboarding/internal/steps/index.tsx b/packages/app/src/onboarding/internal/steps/index.tsx
new file mode 100644
index 0000000000..ca1fd9060a
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/index.tsx
@@ -0,0 +1,33 @@
+import type { ProjectSuggestionsController } from "@/project-suggestions";
+import type { OnboardingStepId } from "../model";
+import type { OrchestrationSetupController } from "../orchestration-setup";
+import { AppearanceStep } from "./appearance-step";
+import { OrchestrationStep } from "./orchestration-step";
+import { PhoneStep } from "./phone-step";
+import { ProjectsStep } from "./projects-step";
+import { ProvidersStep } from "./providers-step";
+
+export function OnboardingStepContent({
+  step,
+  serverId,
+  projectSuggestions,
+  orchestration,
+}: {
+  step: OnboardingStepId;
+  serverId: string;
+  projectSuggestions: ProjectSuggestionsController;
+  orchestration: OrchestrationSetupController;
+}) {
+  switch (step) {
+    case "appearance":
+      return <AppearanceStep />;
+    case "providers":
+      return <ProvidersStep serverId={serverId} />;
+    case "projects":
+      return <ProjectsStep serverId={serverId} suggestions={projectSuggestions} />;
+    case "orchestration":
+      return <OrchestrationStep setup={orchestration} />;
+    case "phone":
+      return <PhoneStep serverId={serverId} />;
+  }
+}
diff --git a/packages/app/src/onboarding/internal/steps/orchestration-step.tsx b/packages/app/src/onboarding/internal/steps/orchestration-step.tsx
new file mode 100644
index 0000000000..da41f591b9
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/orchestration-step.tsx
@@ -0,0 +1,30 @@
+import { useCallback } from "react";
+import { AgentSkillsRow } from "@/agent-skills";
+import { SettingsCard } from "@/components/settings";
+import { CommandLineRow } from "@/desktop/components/integrations-section";
+import { PaseoToolsRow } from "@/screens/settings/paseo-tools-card";
+import type { OrchestrationSetupController } from "../orchestration-setup";
+
+/** Three switches, all on to start; Continue applies them. */
+export function OrchestrationStep({ setup }: { setup: OrchestrationSetupController }) {
+  const { choices, setChoice, offered, isApplying } = setup;
+  const setTools = useCallback((on: boolean) => setChoice("tools", on), [setChoice]);
+  const setSkills = useCallback((on: boolean) => setChoice("skills", on), [setChoice]);
+  const setCli = useCallback((on: boolean) => setChoice("cli", on), [setChoice]);
+  return (
+    <SettingsCard>
+      <PaseoToolsRow value={choices.tools} onValueChange={setTools} disabled={isApplying} />
+      {offered.skills ? (
+        <AgentSkillsRow
+          skills={setup.skills}
+          value={choices.skills}
+          onValueChange={setSkills}
+          disabled={isApplying}
+        />
+      ) : null}
+      {offered.cli ? (
+        <CommandLineRow value={choices.cli} onValueChange={setCli} disabled={isApplying} />
+      ) : null}
+    </SettingsCard>
+  );
+}
diff --git a/packages/app/src/onboarding/internal/steps/phone-step.tsx b/packages/app/src/onboarding/internal/steps/phone-step.tsx
new file mode 100644
index 0000000000..582c23a06b
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/phone-step.tsx
@@ -0,0 +1,105 @@
+import { useCallback, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { AppleIcon } from "@/components/icons/apple-icon";
+import { GooglePlayIcon } from "@/components/icons/google-play-icon";
+import { SettingsCard, SettingsDetailRow, SettingsSection } from "@/components/settings";
+import { Button } from "@/components/ui/button";
+import { StatusBadge } from "@/components/ui/status-badge";
+import { PairDeviceModal } from "@/desktop/components/pair-device-modal";
+import {
+  CONNECTIVITY_DOCS_URL,
+  TAILSCALE_DOCS_URL,
+} from "@/desktop/components/pair-device-section";
+import { ICON_SIZE } from "@/styles/theme";
+import { openExternalUrl } from "@/utils/open-external-url";
+
+const APP_STORE_URL = "https://apps.apple.com/app/paseo-pocket-engineer/id6758887924";
+const PLAY_STORE_URL = "https://play.google.com/store/apps/details?id=sh.paseo";
+
+// Button calls a one-argument function with its icon colour, so the Apple mark follows the theme.
+const renderAppleIcon = (color: string) => <AppleIcon color={color} size={ICON_SIZE.sm} />;
+const renderGooglePlayIcon = () => <GooglePlayIcon size={ICON_SIZE.sm} />;
+
+function openUrl(url: string) {
+  void openExternalUrl(url).catch(console.error);
+}
+
+/** Get the app, then connect it: the relay pairs in a modal, Tailscale is a docs page away. */
+export function PhoneStep({ serverId }: { serverId: string }) {
+  const { t } = useTranslation();
+  const [isPairing, setIsPairing] = useState(false);
+  const openAppStore = useCallback(() => openUrl(APP_STORE_URL), []);
+  const openPlayStore = useCallback(() => openUrl(PLAY_STORE_URL), []);
+  const openTailscaleDocs = useCallback(() => openUrl(TAILSCALE_DOCS_URL), []);
+  const openPairing = useCallback(() => setIsPairing(true), []);
+  const closePairing = useCallback(() => setIsPairing(false), []);
+  const recommendedBadge = useMemo(
+    () => (
+      <StatusBadge
+        size="xs"
+        variant="success"
+        label={t("onboarding.setup.steps.phone.recommended")}
+      />
+    ),
+    [t],
+  );
+  const docsLink = useMemo(
+    () => ({
+      href: CONNECTIVITY_DOCS_URL,
+      label: t("onboarding.setup.steps.phone.connectDocs"),
+      accessibilityLabel: t("onboarding.setup.steps.phone.openConnectDocs"),
+    }),
+    [t],
+  );
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.storeLinks}>
+        <Button variant="outline" leftIcon={renderAppleIcon} onPress={openAppStore}>
+          {t("onboarding.setup.steps.phone.appStore")}
+        </Button>
+        <Button variant="outline" leftIcon={renderGooglePlayIcon} onPress={openPlayStore}>
+          {t("onboarding.setup.steps.phone.googlePlay")}
+        </Button>
+      </View>
+      <SettingsSection title={t("onboarding.setup.steps.phone.connectTitle")} link={docsLink}>
+        <SettingsCard>
+          <SettingsDetailRow
+            label={t("onboarding.setup.steps.phone.relay.title")}
+            labelAccessory={recommendedBadge}
+            hint={t("onboarding.setup.steps.phone.relay.hint")}
+            onPress={openPairing}
+            testID="onboarding-phone-relay"
+          />
+          <SettingsDetailRow
+            label={t("onboarding.setup.steps.phone.tailscale.title")}
+            hint={t("onboarding.setup.steps.phone.tailscale.hint")}
+            summary={t("onboarding.setup.steps.phone.connectDocs")}
+            onPress={openTailscaleDocs}
+            external
+            testID="onboarding-phone-tailscale"
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <PairDeviceModal
+        serverId={serverId}
+        visible={isPairing}
+        onClose={closePairing}
+        testID="onboarding-pair-device-card"
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    gap: theme.spacing[6],
+  },
+  storeLinks: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: theme.spacing[2],
+  },
+}));
diff --git a/packages/app/src/onboarding/internal/steps/projects-step.tsx b/packages/app/src/onboarding/internal/steps/projects-step.tsx
new file mode 100644
index 0000000000..9f64f6d839
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/projects-step.tsx
@@ -0,0 +1,109 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { Text, View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { Check, FolderPlus } from "lucide-react-native";
+import { Button } from "@/components/ui/button";
+import { useOpenAddProject } from "@/hooks/use-open-add-project";
+import {
+  FolderProjectIcon,
+  ProjectSuggestionList,
+  type ProjectSuggestionsController,
+} from "@/project-suggestions";
+import { useProjectRootPaths } from "@/stores/session-store-hooks";
+import { settingsStyles } from "@/styles/settings";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+
+const ThemedCheck = withUnistyles(Check);
+const successMapping = (theme: Theme) => ({ color: theme.colors.palette.green[400] });
+
+function basename(path: string): string {
+  const segments = path.split(/[\\/]/).filter((segment) => segment.length > 0);
+  return segments.at(-1) ?? path;
+}
+
+/** Adding the checked suggestions is the setup's primary action; see the modal footer. */
+export function ProjectsStep({
+  serverId,
+  suggestions,
+}: {
+  serverId: string;
+  suggestions: ProjectSuggestionsController;
+}) {
+  const { t } = useTranslation();
+  const openAddProject = useOpenAddProject();
+  const projectRootPaths = useProjectRootPaths(serverId);
+  const handleAddProject = useCallback(() => openAddProject(serverId), [openAddProject, serverId]);
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.actions}>
+        <Button variant="outline" leftIcon={FolderPlus} onPress={handleAddProject}>
+          {t("onboarding.setup.steps.projects.addProject")}
+        </Button>
+      </View>
+      {projectRootPaths.length > 0 ? (
+        <View style={settingsStyles.card}>
+          {projectRootPaths.map((rootPath, index) => (
+            <View
+              key={rootPath}
+              style={[settingsStyles.row, index > 0 && settingsStyles.rowBorder]}
+            >
+              <View style={settingsStyles.rowContent}>
+                <View style={styles.titleLine}>
+                  <FolderProjectIcon
+                    serverId={serverId}
+                    rootPath={rootPath}
+                    name={basename(rootPath)}
+                  />
+                  <Text style={[settingsStyles.rowTitle, styles.title]} numberOfLines={1}>
+                    {basename(rootPath)}
+                  </Text>
+                </View>
+                <Text style={[settingsStyles.rowHint, styles.underTitle]} numberOfLines={1}>
+                  {rootPath}
+                </Text>
+              </View>
+              <View style={styles.addedBadge}>
+                <ThemedCheck size={14} uniProps={successMapping} />
+                <Text style={styles.addedLabel}>{t("onboarding.setup.steps.projects.added")}</Text>
+              </View>
+            </View>
+          ))}
+        </View>
+      ) : null}
+      <ProjectSuggestionList serverId={serverId} suggestions={suggestions} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    gap: theme.spacing[4],
+  },
+  actions: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: theme.spacing[2],
+  },
+  titleLine: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  title: {
+    flexShrink: 1,
+  },
+  underTitle: {
+    marginLeft: ICON_SIZE.md + theme.spacing[2],
+  },
+  addedBadge: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[1],
+  },
+  addedLabel: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+  },
+}));
diff --git a/packages/app/src/onboarding/internal/steps/providers-step.tsx b/packages/app/src/onboarding/internal/steps/providers-step.tsx
new file mode 100644
index 0000000000..84235fe921
--- /dev/null
+++ b/packages/app/src/onboarding/internal/steps/providers-step.tsx
@@ -0,0 +1,10 @@
+import { View } from "react-native";
+import { ProvidersSection } from "@/screens/settings/providers-section";
+
+export function ProvidersStep({ serverId }: { serverId: string }) {
+  return (
+    <View>
+      <ProvidersSection serverId={serverId} />
+    </View>
+  );
+}
diff --git a/packages/app/src/onboarding/internal/use-setup-host.ts b/packages/app/src/onboarding/internal/use-setup-host.ts
new file mode 100644
index 0000000000..0680e8a466
--- /dev/null
+++ b/packages/app/src/onboarding/internal/use-setup-host.ts
@@ -0,0 +1,14 @@
+import { useLocalDaemonServerIdState } from "@/hooks/use-is-local-daemon";
+import { useHosts } from "@/runtime/host-runtime";
+
+/**
+ * The host setup configures: the desktop's built-in daemon, otherwise the first saved host.
+ * Null while the desktop daemon is still reporting its id, or when there is no host at all.
+ */
+export function useSetupHostServerId(): string | null {
+  const localDaemon = useLocalDaemonServerIdState();
+  const hosts = useHosts();
+  if (localDaemon.status === "loading") return null;
+  if (localDaemon.status === "resolved" && localDaemon.serverId) return localDaemon.serverId;
+  return hosts[0]?.serverId ?? null;
+}
diff --git a/packages/app/src/onboarding/onboarding-host.tsx b/packages/app/src/onboarding/onboarding-host.tsx
new file mode 100644
index 0000000000..28280c7c70
--- /dev/null
+++ b/packages/app/src/onboarding/onboarding-host.tsx
@@ -0,0 +1,40 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { isNative } from "@/constants/platform";
+import { useDirectoryDemand } from "@/hooks/use-directory-demand";
+import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { useHasHydratedWorkspaces, useProjectRootPaths } from "@/stores/session-store-hooks";
+import { getOnboardingModel } from "./internal/onboarding-instance";
+import { OnboardingModal } from "./internal/onboarding-modal";
+import { useSetupHostServerId } from "./internal/use-setup-host";
+
+/** Mounted once by the app shell. Decides whether setup opens, then owns the modal. */
+export function OnboardingHost() {
+  // Native phones are set up from a desktop; setup never opens there.
+  if (isNative) return null;
+  return <OnboardingGate />;
+}
+
+function OnboardingGate() {
+  const model = getOnboardingModel();
+  const state = useSyncExternalStore(model.subscribe, model.getState, model.getState);
+  const serverId = useSetupHostServerId();
+  const isConnected = useHostRuntimeIsConnected(serverId ?? "");
+  const hasHydratedWorkspaces = useHasHydratedWorkspaces(serverId);
+  const projectRootPaths = useProjectRootPaths(serverId);
+  const isCompact = useIsCompactFormFactor();
+  const hasProjects = projectRootPaths.length > 0;
+
+  // Without demand nothing may ask a fresh host for its workspaces, and the gate would wait forever.
+  useDirectoryDemand(state.status === "hidden" ? null : serverId);
+
+  useEffect(() => {
+    model.applySetupHost(
+      serverId ? { serverId, isConnected, hasHydratedWorkspaces, hasProjects } : null,
+      { includePhoneStep: !isCompact },
+    );
+  }, [model, serverId, isConnected, hasHydratedWorkspaces, hasProjects, isCompact]);
+
+  if (state.status !== "open") return null;
+  return <OnboardingModal model={model} state={state} />;
+}
diff --git a/packages/app/src/onboarding/use-open-onboarding.ts b/packages/app/src/onboarding/use-open-onboarding.ts
new file mode 100644
index 0000000000..1f4a93328e
--- /dev/null
+++ b/packages/app/src/onboarding/use-open-onboarding.ts
@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { getOnboardingModel } from "./internal/onboarding-instance";
+import { useSetupHostServerId } from "./internal/use-setup-host";
+
+/** Reopens setup on its first step. Null when there is no host to set up. */
+export function useOpenOnboarding(): (() => void) | null {
+  const serverId = useSetupHostServerId();
+  const isCompact = useIsCompactFormFactor();
+  const open = useCallback(() => {
+    if (!serverId) return;
+    getOnboardingModel().reopen(serverId, { includePhoneStep: !isCompact });
+  }, [isCompact, serverId]);
+  return serverId ? open : null;
+}
diff --git a/packages/app/src/onboarding/use-setup-decision-pending.ts b/packages/app/src/onboarding/use-setup-decision-pending.ts
new file mode 100644
index 0000000000..5918833ce6
--- /dev/null
+++ b/packages/app/src/onboarding/use-setup-decision-pending.ts
@@ -0,0 +1,24 @@
+import { useSyncExternalStore } from "react";
+import { isNative } from "@/constants/platform";
+import { useHostRuntimeConnectionStatus } from "@/runtime/host-runtime";
+import { getOnboardingModel } from "./internal/onboarding-instance";
+import { useSetupHostServerId } from "./internal/use-setup-host";
+
+/**
+ * True while this launch may still open setup: it has not been decided, and the setup host is
+ * connecting, or connected and loading its workspaces. Startup keeps its loading screen up
+ * meanwhile, so a new user lands on setup rather than on the empty home first. False on phones,
+ * where setup never opens, when there is no setup host, and while the host is unreachable.
+ */
+export const useIsSetupDecisionPending: () => boolean = isNative
+  ? () => false
+  : useIsSetupDecisionPendingOnDesktop;
+
+function useIsSetupDecisionPendingOnDesktop(): boolean {
+  const model = getOnboardingModel();
+  const state = useSyncExternalStore(model.subscribe, model.getState, model.getState);
+  const serverId = useSetupHostServerId();
+  const connectionStatus = useHostRuntimeConnectionStatus(serverId ?? "");
+  if (state.status !== "deciding" || !serverId) return false;
+  return connectionStatus !== "offline" && connectionStatus !== "error";
+}
diff --git a/packages/app/src/pane-find/index.tsx b/packages/app/src/pane-find/index.tsx
index 761ac187e1..f1ee6cfb69 100644
--- a/packages/app/src/pane-find/index.tsx
+++ b/packages/app/src/pane-find/index.tsx
@@ -145,8 +145,6 @@ export const PaneFind = forwardRef<PaneFindHandle, PaneFindProps>(function PaneF
   const controlSize = smallIconButtonChromeFrameSize(isCompact);
   const glyphSize = paneContentToolbarIconSize(isCompact);
   const rowHeight = Math.max(COLLAPSED_FIELD_HEIGHT, controlSize);
-  // Keep the replace actions on the same row height as the icon controls beside them.
-  const actionSize = isCompact ? "sm" : "xs";
   const input = useRef<EditingTextInputHandle>(null);
   const replacementInput = useRef<EditingTextInputHandle>(null);
   useLayoutEffect(() => {
@@ -293,7 +291,7 @@ export const PaneFind = forwardRef<PaneFindHandle, PaneFindProps>(function PaneF
             />
             <Button
               variant="ghost"
-              size={actionSize}
+              size="sm"
               style={styles.replaceAction}
               disabled={!canNavigate}
               onPress={replace.onReplace}
@@ -302,7 +300,7 @@ export const PaneFind = forwardRef<PaneFindHandle, PaneFindProps>(function PaneF
             </Button>
             <Button
               variant="ghost"
-              size={actionSize}
+              size="sm"
               style={styles.replaceAction}
               disabled={!canNavigate}
               onPress={replace.onReplaceAll}
diff --git a/packages/app/src/panels/agent-panel-descriptor.test.tsx b/packages/app/src/panels/agent-panel-descriptor.test.tsx
index ac57778111..eb5aba735f 100644
--- a/packages/app/src/panels/agent-panel-descriptor.test.tsx
+++ b/packages/app/src/panels/agent-panel-descriptor.test.tsx
@@ -105,6 +105,29 @@ describe("shared agent descriptor", () => {
     expect(describeAgent({ isTurnActive: true }).statusBucket).toBe("running");
   });
 
+  it("shows background work as running without making the turn active", () => {
+    expect(describeAgent({ backgroundWork: { count: 1 } })).toMatchObject({
+      statusBucket: "running",
+      subtitle: "Background work running",
+    });
+    expect(
+      describeAgent({
+        backgroundWork: { count: 1 },
+        attentionReason: "error",
+        requiresAttention: true,
+      }).statusBucket,
+    ).toBe("failed");
+    expect(describeAgent({ backgroundWork: { count: 1 }, status: "error" }).statusBucket).toBe(
+      "running",
+    );
+  });
+
+  it("localizes the background work detail", async () => {
+    await i18n.changeLanguage("zh-CN");
+    expect(describeAgent({ backgroundWork: { count: 1 } }).subtitle).toBe("后台任务运行中");
+    await i18n.changeLanguage("en");
+  });
+
   it("surfaces pending permissions even while the turn is running", () => {
     expect(describeAgent({ isTurnActive: true, pendingPermissionCount: 1 }).statusBucket).toBe(
       "needs_input",
diff --git a/packages/app/src/panels/agent-panel.tsx b/packages/app/src/panels/agent-panel.tsx
index 712d9d65a1..cf582a99f5 100644
--- a/packages/app/src/panels/agent-panel.tsx
+++ b/packages/app/src/panels/agent-panel.tsx
@@ -28,12 +28,12 @@ import { FileDropZone } from "@/components/file-drop/file-drop-zone";
 import { useRetainedPanelActive } from "@/components/retained-panel";
 import { RetainedChatContent } from "./retained-chat-content";
 import { Composer } from "@/composer";
+import { AgentCommandsProvider } from "@/agent-commands";
 import {
   useComposerEditingSession,
   useComposerFullscreen,
   type ComposerEditingSession,
 } from "@/composer/editing-session";
-import { useWorkspaceHasDiffStat } from "@/composer/workspace-diff-stat";
 import {
   resolveComposerTrackControlClearance,
   resolveComposerTrackTailClearance,
@@ -65,7 +65,6 @@ import { useAgentFactsLine } from "@/panels/agent-facts-line";
 import { PaneSubtitle } from "@/panels/pane-subtitle";
 import { definePanel } from "@/panels/panel-registry";
 import { RenderProfile } from "@/utils/render-profiler";
-import { useHasPluginComposerPills } from "@/plugins";
 import { buildDraftPanelDescriptor } from "@/panels/draft-panel-descriptor";
 import {
   type HostRuntimeConnectionStatus,
@@ -79,26 +78,27 @@ import {
   deriveRouteBottomAnchorIntent,
   deriveRouteBottomAnchorRequest,
 } from "@/screens/agent/agent-ready-screen-bottom-anchor";
-import { WorkspaceDraftAgentTab } from "@/composer/draft/workspace-tab";
-import { AgentTracks, hasAgentTracks } from "@/panels/agent-tracks";
+import { WorkspaceDraftComposer } from "@/composer/draft/workspace-tab";
+import { type DraftConversation, useDraftTimeline } from "@/composer/draft/timeline";
+import { AgentTracks } from "@/panels/agent-tracks";
+import { OverlayDismissalScope } from "@/components/ui/overlay-dismissal";
 import { ParentAgentCallout, useParentAgentId } from "@/subagents/parent";
 import { useCreateFlowStore } from "@/stores/create-flow-store";
 import { buildDraftStoreKey, generateDraftId } from "@/stores/draft-keys";
 import {
   selectAgentTimelineState,
-  selectAgentTurnPresentation,
+  selectAgentTimelineTurnPresentation,
   type Agent,
   useSessionStore,
 } from "@/stores/session-store";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
-import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
+import { buildWorkspaceTabPersistenceKey, type WorkspaceTabTarget } from "@/workspace-tabs/model";
 import { openWorkspaceChanges } from "@/workspace-tabs/open-supporting-view";
 import { useSettings } from "@/hooks/use-settings";
 import type { Theme } from "@/styles/theme";
 import type { PendingPermission } from "@/types/shared";
-import type { StreamItem, TodoEntry } from "@/types/stream";
+import type { StreamItem } from "@/types/stream";
 import type { ViewedTimelineStatus, ViewedTimelineUiBridge } from "@/timeline/viewed-timeline-sync";
-import { useArchiveFinishedSubagents, useSubagentsForParent } from "@/subagents";
 import { getInitDeferred, getInitKey } from "@/utils/agent-initialization";
 import { derivePendingPermissionKey, normalizeAgentSnapshot } from "@/utils/agent-snapshots";
 import { applyLegacyDaemonWorkspaceOwnership } from "@/workspace/legacy-daemon-workspaces";
@@ -117,7 +117,8 @@ interface ChatAgentStateShape {
   model?: Agent["model"];
   thinkingOptionId?: Agent["thinkingOptionId"];
   runtimeInfo?: Agent["runtimeInfo"];
-  features?: Agent["features"];
+  options?: Agent["options"];
+  controls?: Agent["controls"];
   lastError?: Agent["lastError"] | null;
 }
 
@@ -176,7 +177,8 @@ function selectChatAgentState(
     model: agent.model,
     thinkingOptionId: agent.thinkingOptionId,
     runtimeInfo: agent.runtimeInfo,
-    features: agent.features,
+    options: agent.options,
+    controls: agent.controls,
     lastError: agent.lastError ?? null,
     archivedAt: agent.archivedAt ?? null,
     requiresAttention: agent.requiresAttention ?? false,
@@ -203,7 +205,8 @@ function buildChatAgentFromState(
     model: state.model,
     thinkingOptionId: state.thinkingOptionId,
     runtimeInfo: state.runtimeInfo,
-    features: state.features,
+    options: state.options,
+    controls: state.controls,
     lastError: state.lastError ?? null,
     projectPlacement,
   };
@@ -217,7 +220,7 @@ function AgentLoadErrorView({ message, onRetry }: { message: string; onRetry: ()
         <Text style={styles.errorText}>{t("agentPanel.states.failedToLoad")}</Text>
         <Text style={styles.statusText}>{message}</Text>
         <View style={styles.errorAction}>
-          <Button size="sm" variant="secondary" onPress={onRetry} testID="agent-load-error-retry">
+          <Button variant="secondary" onPress={onRetry} testID="agent-load-error-retry">
             {t("common.actions.retry")}
           </Button>
         </View>
@@ -226,6 +229,29 @@ function AgentLoadErrorView({ message, onRetry }: { message: string; onRetry: ()
   );
 }
 
+/** A draft has no agent to wait for; an agent shows its loading and error states until ready. */
+function renderConversationNonReadyView(args: {
+  draft: DraftConversation | null;
+  agentId: string | undefined;
+  cwd: string | null;
+  viewState: AgentScreenViewState;
+  effectiveAgent: AgentScreenAgent | null;
+  t: TFunction;
+  onRetryLoad: () => void;
+}): React.ReactElement | null {
+  if (args.draft) {
+    return null;
+  }
+  const nonReadyView = renderChatAgentNonReadyView(args);
+  if (nonReadyView) {
+    return nonReadyView;
+  }
+  invariant(args.agentId, "agent id is defined when agent content is ready");
+  invariant(args.effectiveAgent, "effectiveAgent is defined when the non-ready view is absent");
+  invariant(args.cwd, "agent cwd is defined when agent content is ready");
+  return null;
+}
+
 function renderChatAgentNonReadyView(args: {
   viewState: AgentScreenViewState;
   effectiveAgent: AgentScreenAgent | null;
@@ -304,17 +330,31 @@ function storeFetchedAgentDetail(input: {
   return hydrated;
 }
 
-function AgentPanel() {
+type ConversationTarget = Extract<WorkspaceTabTarget, { kind: "agent" } | { kind: "draft" }>;
+
+/** The agent a conversation shows; a draft has none until its first prompt creates one. */
+function resolveConversationAgentId(target: ConversationTarget): string | undefined {
+  return target.kind === "agent" ? target.agentId.trim() || undefined : undefined;
+}
+
+/**
+ * Drafts and agents render through one chain so the timeline stays mounted when the draft's
+ * first prompt creates the agent and the tab retargets. The agent gates are idle for a draft.
+ */
+export function AgentConversationPanel() {
   const { serverId, workspaceId, target, openFileInWorkspace } = usePaneContext();
   const { isInteractive } = usePaneFocus();
-  invariant(target.kind === "agent", "AgentPanel requires agent target");
+  invariant(
+    target.kind === "agent" || target.kind === "draft",
+    "AgentConversationPanel requires an agent or draft target",
+  );
 
   return (
     <RetainedChatContent>
       <AgentPanelContent
         serverId={serverId}
         workspaceId={workspaceId}
-        agentId={target.agentId}
+        target={target}
         isPaneFocused={isInteractive}
         onOpenWorkspaceFile={openFileInWorkspace}
       />
@@ -322,55 +362,6 @@ function AgentPanel() {
   );
 }
 
-function DraftPanel() {
-  const {
-    serverId,
-    workspaceId,
-    tabId,
-    target,
-    openFileInWorkspace,
-    openImportSheet,
-    retargetCurrentTab,
-  } = usePaneContext();
-  const { isInteractive } = usePaneFocus();
-  invariant(target.kind === "draft", "DraftPanel requires draft target");
-
-  const handleCreated = useCallback(
-    (agentSnapshot: Parameters<typeof normalizeAgentSnapshot>[0]) => {
-      const normalized = normalizeAgentSnapshot(agentSnapshot, serverId);
-      const agent = applyLegacyDaemonWorkspaceOwnership({ serverId, agent: normalized });
-      getHostRuntimeStore().acceptAgentSnapshot(serverId, agent);
-      retargetCurrentTab({ kind: "agent", agentId: agentSnapshot.id });
-    },
-    [retargetCurrentTab, serverId],
-  );
-
-  return (
-    <WorkspaceDraftAgentTab
-      serverId={serverId}
-      workspaceId={workspaceId}
-      tabId={tabId}
-      draftId={target.draftId}
-      initialSetup={target.setup}
-      isPaneFocused={isInteractive}
-      onOpenWorkspaceFile={openFileInWorkspace}
-      onCreated={handleCreated}
-      onOpenImportSheet={openImportSheet}
-    />
-  );
-}
-
-export function AgentConversationPanel() {
-  const { target } = usePaneContext();
-  if (target.kind === "draft") {
-    return <DraftPanel />;
-  }
-  if (target.kind === "agent") {
-    return <AgentPanel />;
-  }
-  invariant(false, "AgentConversationPanel requires an agent or draft target");
-}
-
 export const agentPanelRegistration = definePanel("agent", {
   component: AgentConversationPanel,
   useDescriptor: useAgentDescriptor,
@@ -445,18 +436,18 @@ type AgentLookupState =
 function AgentPanelContent({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   onOpenWorkspaceFile,
 }: {
   serverId: string;
   workspaceId: string;
-  agentId: string;
+  target: ConversationTarget;
   isPaneFocused: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
-  const resolvedAgentId = agentId.trim() || undefined;
+  const resolvedAgentId = resolveConversationAgentId(target);
   const resolvedServerId = serverId.trim() || undefined;
   const daemons = useHosts();
   const runtimeServerId = resolvedServerId ?? "";
@@ -485,7 +476,7 @@ function AgentPanelContent({
       : runtimeConnectionStatus;
   const lastConnectionError = runtimeLastError;
 
-  if (!resolvedServerId || (!runtimeClient && !hasCachedAgent)) {
+  if (target.kind === "agent" && (!resolvedServerId || (!runtimeClient && !hasCachedAgent))) {
     return (
       <AgentSessionUnavailableState
         serverLabel={serverLabel}
@@ -499,9 +490,9 @@ function AgentPanelContent({
 
   return (
     <AgentPanelBody
-      serverId={resolvedServerId}
+      serverId={resolvedServerId ?? serverId}
       workspaceId={workspaceId}
-      agentId={resolvedAgentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={runtimeClient}
       isConnected={runtimeIsConnected}
@@ -513,7 +504,7 @@ function AgentPanelContent({
 function AgentPanelBody({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -521,13 +512,14 @@ function AgentPanelBody({
 }: {
   serverId: string;
   workspaceId: string;
-  agentId?: string;
+  target: ConversationTarget;
   isPaneFocused: boolean;
   client: ReturnType<typeof useHostRuntimeClient>;
   isConnected: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
+  const agentId = resolveConversationAgentId(target);
   const { isArchivingAgent: _isArchivingAgent } = useArchiveAgent();
   const hasSession = useSessionStore((state) => Boolean(state.sessions[serverId]));
   const projectPlacement = useStoreWithEqualityFn(
@@ -636,13 +628,14 @@ function AgentPanelBody({
           model: agentState.model,
           thinkingOptionId: agentState.thinkingOptionId,
           runtimeInfo: agentState.runtimeInfo,
-          features: agentState.features,
+          options: agentState.options,
+          controls: agentState.controls,
           lastError: agentState.lastError ?? null,
           projectPlacement,
         }
       : null;
 
-  if (!agent) {
+  if (target.kind === "agent" && !agent) {
     return (
       <View style={styles.container} testID="agent-loading">
         <View style={styles.errorContainer}>
@@ -656,7 +649,7 @@ function AgentPanelBody({
     <ChatAgentContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={client}
       isConnected={isConnected}
@@ -668,7 +661,7 @@ function AgentPanelBody({
 function ChatAgentContent({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -676,19 +669,19 @@ function ChatAgentContent({
 }: {
   serverId: string;
   workspaceId: string;
-  agentId?: string;
+  target: ConversationTarget;
   isPaneFocused: boolean;
   client: ReturnType<typeof useHostRuntimeClient>;
   isConnected: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
+  const { tabId } = usePaneContext();
+  const agentId = resolveConversationAgentId(target);
   const isPaneVisible = useRetainedPanelActive();
   const { api: toastApi, toast: toastState, dismiss: dismissToast } = useToastHost();
   const { isArchivingAgent } = useArchiveAgent();
   const streamViewRef = useRef<AgentStreamViewHandle>(null);
-  const clearOnAgentBlurRef = useRef<() => void>(() => {});
-  const wasPaneFocusedRef = useRef(isPaneFocused);
   const initAttemptTokenRef = useRef(0);
   const routeBottomAnchorRequestRef = useRef<{
     routeKey: string;
@@ -734,13 +727,11 @@ function ChatAgentContent({
     (listener: () => void) => viewedTimelineSync?.subscribe(listener) ?? (() => {}),
     [viewedTimelineSync],
   );
-  const readTimelineStatus = useCallback(
-    () =>
-      !agentId || !viewedTimelineSync
-        ? ("ready" as const)
-        : viewedTimelineSync.getAgentTimelineStatus(agentId),
-    [agentId, viewedTimelineSync],
-  );
+  const readTimelineStatus = useCallback((): ViewedTimelineStatus => {
+    if (!agentId) return "ready";
+    // Until the owner is published nothing has confirmed this chat, so its check has not begun.
+    return viewedTimelineSync?.getAgentTimelineStatus(agentId) ?? "checking";
+  }, [agentId, viewedTimelineSync]);
   const timelineStatus = useSyncExternalStore(
     subscribeToVisibilityCatchUp,
     readTimelineStatus,
@@ -763,35 +754,31 @@ function ChatAgentContent({
   const hasHydratedHistoryBefore =
     hasAppliedAuthoritativeHistory || replicaTimelineStatus === "painted";
 
+  const focusRequest = useWorkspaceLayoutStore((state) => {
+    const request = state.focusRequest;
+    return request?.workspaceKey === `${serverId}:${workspaceId}` && request.tabId === tabId
+      ? request
+      : null;
+  });
+  const reportAttentionError = useCallback(
+    (error: unknown) => {
+      toastApi.show(String(error), { variant: "error", durationMs: null });
+    },
+    [toastApi],
+  );
   const attentionController = useAgentAttentionClear({
     agentId,
     client,
     isConnected,
+    isAgentDataReady: agentHistorySyncGeneration === historySyncGeneration,
     requiresAttention: agentState.requiresAttention,
     attentionReason: agentState.attentionReason,
     isScreenFocused: isPaneFocused,
+    focusRequest,
+    onError: reportAttentionError,
   });
-  useEffect(() => {
-    clearOnAgentBlurRef.current = attentionController.clearOnAgentBlur;
-  }, [attentionController.clearOnAgentBlur]);
-
   const isArchivingCurrentAgent = Boolean(agentId && isArchivingAgent({ serverId, agentId }));
 
-  useEffect(() => {
-    if (wasPaneFocusedRef.current && !isPaneFocused) {
-      clearOnAgentBlurRef.current();
-    }
-    wasPaneFocusedRef.current = isPaneFocused;
-  }, [isPaneFocused]);
-
-  useEffect(() => {
-    return () => {
-      if (wasPaneFocusedRef.current) {
-        clearOnAgentBlurRef.current();
-      }
-    };
-  }, []);
-
   const isInitializing = agentId ? isInitializingFromMap : false;
   const isHistorySyncing = useMemo(() => {
     if (!agentId || !isInitializing) {
@@ -989,17 +976,23 @@ function ChatAgentContent({
     visibilityCatchUpStatus,
   ]);
 
-  const nonReadyView = renderChatAgentNonReadyView({
+  const draft = useMemo<DraftConversation | null>(
+    () =>
+      target.kind === "draft"
+        ? { tabId, workspaceId, draftId: target.draftId, setup: target.setup }
+        : null,
+    [tabId, target, workspaceId],
+  );
+  const nonReadyView = renderConversationNonReadyView({
+    draft,
+    agentId,
+    cwd: agentState.cwd,
     viewState,
     effectiveAgent,
     t,
     onRetryLoad: retryAgentLoad,
   });
   if (nonReadyView) return nonReadyView;
-  invariant(agentId, "agent id is defined when agent content is ready");
-  invariant(effectiveAgent, "effectiveAgent is defined when the non-ready view is absent");
-  const agentCwd = agentState.cwd;
-  invariant(agentCwd, "agent cwd is defined when agent content is ready");
   const showHistorySyncOverlay =
     viewState.tag === "ready" &&
     viewState.sync.status === "catching_up" &&
@@ -1014,13 +1007,15 @@ function ChatAgentContent({
     <ChatAgentReadyContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      agentId={agentId ?? tabId}
+      draft={draft}
       isPaneFocused={isPaneFocused}
       isArchivingCurrentAgent={isArchivingCurrentAgent}
       agentState={agentState}
       effectiveAgent={effectiveAgent}
       routeBottomAnchorRequest={routeBottomAnchorRequest}
       hasAppliedAuthoritativeHistory={hasAppliedAuthoritativeHistory}
+      hasCachedHistory={replicaTimelineStatus === "painted"}
       toastApi={toastApi}
       toast={toastState}
       dismiss={dismissToast}
@@ -1032,7 +1027,7 @@ function ChatAgentContent({
       showHistorySyncOverlay={showHistorySyncOverlay}
       showHistorySyncError={showHistorySyncError}
       isRetryingHistorySync={isRetryingHistorySync}
-      cwd={agentCwd}
+      cwd={agentState.cwd ?? ""}
       retryTimelineSync={retryTimelineSync}
       onAttentionInputFocus={attentionController.clearOnInputFocus}
       onAttentionPromptSend={attentionController.clearOnPromptSend}
@@ -1045,12 +1040,14 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   serverId,
   workspaceId,
   agentId,
+  draft,
   isPaneFocused,
   isArchivingCurrentAgent,
   agentState,
   effectiveAgent,
   routeBottomAnchorRequest,
   hasAppliedAuthoritativeHistory,
+  hasCachedHistory,
   toastApi,
   toast,
   dismiss,
@@ -1070,13 +1067,16 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
 }: {
   serverId: string;
   workspaceId: string;
+  /** The agent's id, or the tab id while a draft has no agent yet. */
   agentId: string;
+  draft: DraftConversation | null;
   isPaneFocused: boolean;
   isArchivingCurrentAgent: boolean;
   agentState: ChatAgentSelectedState;
-  effectiveAgent: AgentScreenAgent;
+  effectiveAgent: AgentScreenAgent | null;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
+  hasCachedHistory: boolean;
   toastApi: ToastApi;
   toast: ToastState | null;
   dismiss: () => void;
@@ -1096,31 +1096,15 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
 }) {
   const { t } = useTranslation();
   // The workspace sheet is for looking; Open as tab brings the agent back with its composer.
-  const showsComposer = usePaneContext().host !== "sheet";
+  const paneHost = usePaneContext().host;
+  const showsComposer = draft !== null || paneHost !== "sheet";
   // The dock lays out fullscreen for the same session the composer edits in.
   const composerEditingSession = useComposerEditingSession("chat");
   const isComposerFullscreen = useComposerFullscreen(composerEditingSession);
-  const subagentRows = useSubagentsForParent({ serverId, parentAgentId: agentId });
-  const tasks = useSessionStore((state): TodoEntry[] | undefined =>
-    state.sessions[serverId]?.agentTasks.get(agentId),
-  );
-  const archiveFinishedSubagents = useArchiveFinishedSubagents({
-    serverId,
-    parentAgentId: agentId,
-    rows: subagentRows,
-  });
-  const hasPluginComposerPills = useHasPluginComposerPills(serverId, workspaceId, agentId);
   const hasActiveComposer = !agentState.archivedAt && !isArchivingCurrentAgent;
   const parentAgentId = useParentAgentId(serverId, agentId);
   // With a composer the parent is a pill above it; without one, the box takes the composer's place.
   const parentPillAgentId = showsComposer ? parentAgentId : null;
-  const hasVisibleAgentTracks = hasAgentTracks({
-    parentAgentId: parentPillAgentId,
-    subagentRows,
-    tasks,
-    archiveFinishedStatus: archiveFinishedSubagents.status,
-    hasPluginComposerPills,
-  });
   const rawAgentInputDraft = useAgentInputDraft({
     draftKey: buildDraftStoreKey({
       serverId,
@@ -1170,7 +1154,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   const parentCallout = parentAgentId ? (
     <ParentAgentCallout serverId={serverId} parentAgentId={parentAgentId} />
   ) : null;
-  const composerSection = showsComposer ? (
+  const agentComposerSection = showsComposer ? (
     <RenderProfile id={`AgentComposerSection:${agentId}`}>
       <AgentComposerSection
         agentId={agentId}
@@ -1191,35 +1175,52 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   ) : (
     parentCallout
   );
+  const composerSection = draft ? (
+    <DraftComposerSection
+      serverId={serverId}
+      draft={draft}
+      isPaneFocused={isPaneFocused}
+      editingSession={composerEditingSession}
+    />
+  ) : (
+    agentComposerSection
+  );
+  const handleAttentionInteraction = useCallback(() => {
+    onAttentionInputFocus();
+    return false;
+  }, [onAttentionInputFocus]);
   const streamContent = (
-    <View style={animatedStaticStyles.content}>
+    <View
+      style={animatedStaticStyles.content}
+      onStartShouldSetResponderCapture={handleAttentionInteraction}
+    >
       {showsComposer ? null : <SheetAgentFacts serverId={serverId} agentId={agentId} />}
       <RenderProfile id={`AgentStreamSection:${agentId}`}>
         <AgentStreamSection
           streamViewRef={streamViewRef}
           serverId={serverId}
-          workspaceId={workspaceId}
           agentId={agentId}
           agent={effectiveAgent}
+          draft={draft}
           routeBottomAnchorRequest={routeBottomAnchorRequest}
           hasAppliedAuthoritativeHistory={hasAppliedAuthoritativeHistory}
+          isInitialHistoryLoading={
+            routeBottomAnchorRequest?.reason === "initial-entry" &&
+            !hasCachedHistory &&
+            !showHistorySyncError
+          }
+          revealInitialHistory={hasCachedHistory || showHistorySyncError}
           hasActiveComposer={hasActiveComposer}
-          hasVisibleAgentTracks={hasVisibleAgentTracks}
           toast={toastApi}
           onOpenWorkspaceFile={onOpenWorkspaceFile}
         />
       </RenderProfile>
-      {hasActiveComposer ? (
+      {hasActiveComposer && !draft ? (
         <AgentTracks
           serverId={serverId}
           workspaceId={workspaceId}
           agentId={agentId}
           parentAgentId={parentPillAgentId}
-          subagentRows={subagentRows}
-          tasks={tasks}
-          archiveFinishedStatus={archiveFinishedSubagents.status}
-          onArchiveFinished={archiveFinishedSubagents.archiveFinished}
-          hasPluginComposerPills={hasPluginComposerPills}
         />
       ) : null}
     </View>
@@ -1255,7 +1256,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
     </ChatSurface>
   );
 
-  return (
+  const content = (
     <RewindComposerRestoreProvider
       textSource={agentInputDraft.textSource}
       setText={agentInputDraft.replaceText}
@@ -1274,8 +1275,40 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
       </View>
     </RewindComposerRestoreProvider>
   );
+  return wrapAgentCommandProvider({
+    enabled: showsComposer && hasActiveComposer && !draft,
+    serverId,
+    agentId,
+    editingSession: composerEditingSession,
+    children: content,
+  });
 });
 
+function wrapAgentCommandProvider({
+  enabled,
+  serverId,
+  agentId,
+  editingSession,
+  children,
+}: {
+  enabled: boolean;
+  serverId: string;
+  agentId: string;
+  editingSession: ComposerEditingSession;
+  children: ReactNode;
+}) {
+  return (
+    <AgentCommandsProvider
+      serverId={serverId}
+      agentId={agentId}
+      editingSession={editingSession}
+      enabled={enabled}
+    >
+      {children}
+    </AgentCommandsProvider>
+  );
+}
+
 function ChatSurface({
   children,
   disabled,
@@ -1285,10 +1318,14 @@ function ChatSurface({
   disabled: boolean;
   fullscreen: boolean;
 }) {
+  // The tracks above the composer open their pages from outside it, so focusing the composer
+  // closes everything the chat opened.
   return (
-    <FileDropZone style={styles.container} disabled={disabled}>
-      <ComposerDock fullscreen={fullscreen}>{children}</ComposerDock>
-    </FileDropZone>
+    <OverlayDismissalScope>
+      <FileDropZone style={styles.container} disabled={disabled}>
+        <ComposerDock fullscreen={fullscreen}>{children}</ComposerDock>
+      </FileDropZone>
+    </OverlayDismissalScope>
   );
 }
 
@@ -1308,7 +1345,6 @@ function TimelineSyncErrorCallout({
             {t("agentPanel.states.timelineSyncFailed")}
           </Text>
           <Button
-            size="sm"
             variant="secondary"
             onPress={onRetry}
             disabled={isRetrying}
@@ -1334,36 +1370,37 @@ function SheetAgentFacts({ serverId, agentId }: { serverId: string; agentId: str
 const AgentStreamSection = memo(function AgentStreamSection({
   streamViewRef,
   serverId,
-  workspaceId,
   agentId,
   agent,
+  draft,
   routeBottomAnchorRequest,
   hasAppliedAuthoritativeHistory,
+  isInitialHistoryLoading,
+  revealInitialHistory,
   hasActiveComposer,
-  hasVisibleAgentTracks,
   toast,
   onOpenWorkspaceFile,
 }: {
   streamViewRef: React.RefObject<AgentStreamViewHandle | null>;
   serverId: string;
-  workspaceId: string;
   agentId?: string;
-  agent: AgentScreenAgent;
+  agent: AgentScreenAgent | null;
+  draft: DraftConversation | null;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
+  isInitialHistoryLoading: boolean;
+  revealInitialHistory: boolean;
   hasActiveComposer: boolean;
-  hasVisibleAgentTracks: boolean;
   toast: ReturnType<typeof useToastHost>["api"];
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const isCompactFormFactor = useIsCompactFormFactor();
-  const hasWorkspaceDiffStat = useWorkspaceHasDiffStat(serverId, workspaceId);
-  const hasVisibleComposerTracks =
-    hasActiveComposer && (hasVisibleAgentTracks || hasWorkspaceDiffStat);
-  const bottomOverlayTailClearance = hasVisibleComposerTracks
+  // The track bar's space is reserved whenever the bar is mounted, pills or not: pills come and go
+  // every turn, and the transcript must not jump with them.
+  const bottomOverlayTailClearance = hasActiveComposer
     ? resolveComposerTrackTailClearance(isCompactFormFactor)
     : 0;
-  const bottomOverlayControlClearance = hasVisibleComposerTracks
+  const bottomOverlayControlClearance = hasActiveComposer
     ? resolveComposerTrackControlClearance(isCompactFormFactor)
     : 0;
   const streamItemsRaw = useAgentStreamTail(serverId, agentId);
@@ -1377,7 +1414,7 @@ const AgentStreamSection = memo(function AgentStreamSection({
   const turnPresentation = useSessionStore(
     useShallow((state) =>
       agentId
-        ? selectAgentTurnPresentation(state.sessions[serverId], agentId)
+        ? selectAgentTimelineTurnPresentation(state.sessions[serverId], agentId)
         : { isActive: false, isCancelling: false, startedAt: null, turnId: null },
     ),
   );
@@ -1408,7 +1445,31 @@ const AgentStreamSection = memo(function AgentStreamSection({
     }
     return new Map(pendingPermissionList.map((permission) => [permission.key, permission]));
   }, [pendingPermissionList]);
+  // A draft's timeline exists only while its first prompt creates the agent. The created agent's
+  // timeline then replaces this input in the same mounted view.
+  const draftTimeline = useDraftTimeline({ serverId, draft });
 
+  if (draftTimeline) {
+    return (
+      <AgentStreamView
+        ref={streamViewRef}
+        agentId={draftTimeline.agent.id}
+        serverId={serverId}
+        context={draftTimeline.agent}
+        streamItems={draftTimeline.streamItems}
+        pendingPermissions={EMPTY_PENDING_PERMISSIONS}
+        bottomOverlayTailClearance={bottomOverlayTailClearance}
+        bottomOverlayControlClearance={bottomOverlayControlClearance}
+        toast={toast}
+        pendingMessageSubmissions={draftTimeline.pendingMessageSubmissions}
+        turnPresentation={draftTimeline.turnPresentation}
+        onOpenWorkspaceFile={onOpenWorkspaceFile}
+      />
+    );
+  }
+  if (!agent) {
+    return null;
+  }
   return (
     <AgentStreamView
       ref={streamViewRef}
@@ -1419,6 +1480,8 @@ const AgentStreamSection = memo(function AgentStreamSection({
       pendingPermissions={pendingPermissions}
       routeBottomAnchorRequest={routeBottomAnchorRequest}
       isAuthoritativeHistoryReady={hasAppliedAuthoritativeHistory}
+      isInitialHistoryLoading={isInitialHistoryLoading}
+      revealInitialHistory={revealInitialHistory}
       bottomOverlayTailClearance={bottomOverlayTailClearance}
       bottomOverlayControlClearance={bottomOverlayControlClearance}
       toast={toast}
@@ -1429,6 +1492,44 @@ const AgentStreamSection = memo(function AgentStreamSection({
   );
 });
 
+/** The draft's composer, which creates the agent and retargets this tab to it. */
+function DraftComposerSection({
+  serverId,
+  draft,
+  isPaneFocused,
+  editingSession,
+}: {
+  serverId: string;
+  draft: DraftConversation;
+  isPaneFocused: boolean;
+  editingSession: ComposerEditingSession;
+}) {
+  const { openImportSheet, retargetCurrentTab } = usePaneContext();
+  const handleCreated = useCallback(
+    (agentSnapshot: Parameters<typeof normalizeAgentSnapshot>[0]) => {
+      const normalized = normalizeAgentSnapshot(agentSnapshot, serverId);
+      const agent = applyLegacyDaemonWorkspaceOwnership({ serverId, agent: normalized });
+      getHostRuntimeStore().acceptAgentSnapshot(serverId, agent);
+      retargetCurrentTab({ kind: "agent", agentId: agentSnapshot.id });
+    },
+    [retargetCurrentTab, serverId],
+  );
+
+  return (
+    <WorkspaceDraftComposer
+      serverId={serverId}
+      workspaceId={draft.workspaceId}
+      tabId={draft.tabId}
+      draftId={draft.draftId}
+      initialSetup={draft.setup}
+      isPaneFocused={isPaneFocused}
+      editingSession={editingSession}
+      onCreated={handleCreated}
+      onOpenImportSheet={openImportSheet}
+    />
+  );
+}
+
 const AgentComposerSection = memo(function AgentComposerSection({
   agentId,
   serverId,
diff --git a/packages/app/src/panels/agent-tracks.tsx b/packages/app/src/panels/agent-tracks.tsx
index 6984633bcc..c4abe7a3fd 100644
--- a/packages/app/src/panels/agent-tracks.tsx
+++ b/packages/app/src/panels/agent-tracks.tsx
@@ -1,7 +1,7 @@
 import type { AgentAddress } from "@getpaseo/protocol/addresses";
-import { memo, useCallback, type ReactElement } from "react";
+import { memo, useCallback, useMemo, type ReactElement } from "react";
+import { BackgroundWorkTrack, createHostBackgroundWorkModel } from "@/background-work";
 import { WorkspaceDiffStatPill } from "@/composer/diff-stat-pill";
-import { useWorkspaceHasDiffStat } from "@/composer/workspace-diff-stat";
 import { AgentTaskList } from "@/composer/task-list";
 import { ComposerTrackBar } from "@/composer/tracks";
 import { useIsCompactFormFactor } from "@/constants/layout";
@@ -10,11 +10,11 @@ import { useSettings } from "@/hooks/use-settings";
 import { PluginComposerPills } from "@/plugins";
 import { useSessionStore } from "@/stores/session-store";
 import {
-  type ArchiveFinishedStatus,
+  useArchiveFinishedSubagents,
   useArchiveSubagent,
   useDetachSubagent,
   useSubagentSheetTab,
-  type SubagentRow,
+  useSubagentsForParent,
 } from "@/subagents";
 import { ParentAgentPill } from "@/subagents/parent";
 import { SubagentsTrack } from "@/subagents/track";
@@ -36,24 +36,31 @@ export const AgentTracks = memo(function AgentTracks({
   workspaceId,
   agentId,
   parentAgentId,
-  subagentRows,
-  tasks,
-  archiveFinishedStatus,
-  onArchiveFinished,
-  hasPluginComposerPills,
 }: {
   serverId: string;
   workspaceId: string;
   agentId: string;
   parentAgentId: string | null;
-  subagentRows: SubagentRow[];
-  tasks: TodoEntry[] | undefined;
-  archiveFinishedStatus: ArchiveFinishedStatus;
-  onArchiveFinished: () => void;
-  hasPluginComposerPills: boolean;
-}): ReactElement | null {
+}): ReactElement {
+  const subagentRows = useSubagentsForParent({ serverId, parentAgentId: agentId });
+  const tasks = useSessionStore((state): TodoEntry[] | undefined =>
+    state.sessions[serverId]?.agentTasks.get(agentId),
+  );
+  const archiveFinishedSubagents = useArchiveFinishedSubagents({
+    serverId,
+    parentAgentId: agentId,
+    rows: subagentRows,
+  });
   const { tabId } = usePaneContext();
-  const hasWorkspaceDiffStat = useWorkspaceHasDiffStat(serverId, workspaceId);
+  const backgroundWorkCount = useSessionStore((state) => {
+    const session = state.sessions[serverId];
+    const agent = session?.agents.get(agentId) ?? session?.agentDetails.get(agentId);
+    return agent?.backgroundWork?.count ?? 0;
+  });
+  const backgroundModel = useMemo(
+    () => createHostBackgroundWorkModel(serverId, agentId),
+    [serverId, agentId],
+  );
   const isCompact = useIsCompactFormFactor();
   const openInSidePane = useSettings((settings) => settings.openInSidePane);
   const workspaceKey = buildWorkspaceTabPersistenceKey({ serverId, workspaceId });
@@ -112,21 +119,9 @@ export const AgentTracks = memo(function AgentTracks({
     });
   }, [isCompact, openInSidePane, workspaceKey]);
 
-  if (
-    !hasWorkspaceDiffStat &&
-    !hasAgentTracks({
-      parentAgentId,
-      subagentRows,
-      tasks,
-      archiveFinishedStatus,
-      hasPluginComposerPills,
-    })
-  ) {
-    return null;
-  }
-
   return (
     <ComposerTrackBar>
+      <BackgroundWorkTrack model={backgroundModel} count={backgroundWorkCount} />
       {parentAgentId ? <ParentAgentPill serverId={serverId} parentAgentId={parentAgentId} /> : null}
       <AgentTaskList tasks={tasks} />
       <SubagentsTrack
@@ -136,8 +131,8 @@ export const AgentTracks = memo(function AgentTracks({
         onOpenProviderSubagent={handleOpenProviderSubagent}
         sheetTabFor={sheetTabFor}
         onArchiveSubagent={archiveSubagent}
-        onArchiveFinished={onArchiveFinished}
-        archiveFinishedStatus={archiveFinishedStatus}
+        onArchiveFinished={archiveFinishedSubagents.archiveFinished}
+        archiveFinishedStatus={archiveFinishedSubagents.status}
         onDetachSubagent={canDetachSubagents ? detachSubagent : undefined}
       />
       <PluginComposerPills
@@ -154,25 +149,3 @@ export const AgentTracks = memo(function AgentTracks({
     </ComposerTrackBar>
   );
 });
-
-export function hasAgentTracks({
-  parentAgentId,
-  subagentRows,
-  tasks,
-  archiveFinishedStatus,
-  hasPluginComposerPills = false,
-}: {
-  parentAgentId: string | null;
-  subagentRows: readonly SubagentRow[];
-  tasks: readonly TodoEntry[] | undefined;
-  archiveFinishedStatus: ArchiveFinishedStatus;
-  hasPluginComposerPills?: boolean;
-}): boolean {
-  return (
-    parentAgentId !== null ||
-    subagentRows.length > 0 ||
-    Boolean(tasks?.length) ||
-    archiveFinishedStatus.kind !== "idle" ||
-    hasPluginComposerPills
-  );
-}
diff --git a/packages/app/src/panels/pane-context.tsx b/packages/app/src/panels/pane-context.tsx
index 52b33e5960..956293e6a0 100644
--- a/packages/app/src/panels/pane-context.tsx
+++ b/packages/app/src/panels/pane-context.tsx
@@ -74,6 +74,11 @@ export function usePaneContext(): PaneContextValue {
   return value;
 }
 
+/** The host of the pane around this component, or null on a screen with no panes. */
+export function usePaneHost(): PaneHost | null {
+  return useContext(PaneContext)?.host ?? null;
+}
+
 export function usePaneFocus(): PaneFocusContextValue {
   const value = useContext(PaneFocusContext);
   invariant(value, "PaneFocusContext is required");
diff --git a/packages/app/src/panels/provider-subagent-panel.tsx b/packages/app/src/panels/provider-subagent-panel.tsx
index 99a38c2f8b..039595b6a4 100644
--- a/packages/app/src/panels/provider-subagent-panel.tsx
+++ b/packages/app/src/panels/provider-subagent-panel.tsx
@@ -26,12 +26,13 @@ import {
   providerSubagentLifecycleStatus,
   refreshProviderSubagents,
   observeProviderSubagentTimeline,
+  loadOlderProviderSubagentTimeline,
   useProviderSubagentStore,
 } from "@/subagents/provider-store";
 import { useTranslation } from "react-i18next";
 import type { PendingPermission } from "@/types/shared";
 import type { StreamItem } from "@/types/stream";
-import { deriveSidebarStateBucket } from "@/utils/sidebar-agent-state";
+import { deriveSubagentStatusBucket } from "@/subagents";
 import { TIMELINE_FETCH_PAGE_SIZE } from "@/timeline/timeline-fetch-policy";
 import type { TurnPresentation } from "@/timeline/turn-liveness";
 import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
@@ -107,10 +108,7 @@ function useProviderSubagentDescriptor(
     titleState: descriptor ? "ready" : "loading",
     icon: useProviderIcon(provider, context.serverId),
     statusBucket: descriptor
-      ? deriveSidebarStateBucket({
-          status: providerSubagentLifecycleStatus(descriptor.status),
-          requiresAttention: descriptor.status === "failed",
-        })
+      ? deriveSubagentStatusBucket(providerSubagentLifecycleStatus(descriptor.status))
       : null,
   };
 }
@@ -180,26 +178,24 @@ function ProviderSubagentPanel() {
     });
   }, [client, supported, serverId, target.parentAgentId, target.subagentId]);
 
-  const loadOlder = useCallback((): boolean => {
+  const loadOlder = useCallback(async (): Promise<boolean> => {
     if (!client || !supported || isLoadingOlder || !timeline?.hasOlder || !timeline.epoch) {
       return false;
     }
-    const firstSeq = timeline.cursor?.startSeq ?? null;
-    if (firstSeq === null) return false;
     setIsLoadingOlder(true);
-    void client
-      .fetchProviderSubagentTimeline(target.parentAgentId, target.subagentId, {
-        direction: "before",
-        cursor: { epoch: timeline.epoch, seq: firstSeq },
+    try {
+      return await loadOlderProviderSubagentTimeline({
+        client,
+        serverId,
+        parentAgentId: target.parentAgentId,
+        subagentId: target.subagentId,
         limit: TIMELINE_FETCH_PAGE_SIZE,
-      })
-      .then((payload) => {
-        useProviderSubagentStore.getState().replaceTimeline(serverId, payload);
-        return undefined;
-      })
-      .catch(() => undefined)
-      .finally(() => setIsLoadingOlder(false));
-    return true;
+      });
+    } catch {
+      return false;
+    } finally {
+      setIsLoadingOlder(false);
+    }
   }, [
     client,
     isLoadingOlder,
diff --git a/packages/app/src/panels/setup-panel.tsx b/packages/app/src/panels/setup-panel.tsx
index 19110d2ee0..27b82b3489 100644
--- a/packages/app/src/panels/setup-panel.tsx
+++ b/packages/app/src/panels/setup-panel.tsx
@@ -155,7 +155,7 @@ function BlockedSetupNotice({
         testID="workspace-setup-blocked"
       >
         {supportsSetupRun ? (
-          <Button accessibilityRole="button" onPress={runSetup} loading={isRunningSetup} size="sm">
+          <Button accessibilityRole="button" onPress={runSetup} loading={isRunningSetup}>
             {t("workspace.setup.blocked.run")}
           </Button>
         ) : null}
diff --git a/packages/app/src/plugins/actions.ts b/packages/app/src/plugins/actions.ts
index b61eae7c1d..e4a87f65e1 100644
--- a/packages/app/src/plugins/actions.ts
+++ b/packages/app/src/plugins/actions.ts
@@ -1,3 +1,5 @@
+import { pluginComposersSource } from "./composer-items/source";
+import { getPluginClientApi } from "./client-state/api";
 import { callPluginRpc } from "@getpaseo/plugin/client/host";
 import type {
   PluginAgentCommandContext,
@@ -32,7 +34,7 @@ export function createPluginCapabilities(
     navigation.openSurface(plugin.id, screenId, params);
   }
   return {
-    paseo: plugin.paseo,
+    paseo: getPluginClientApi(plugin).paseo,
     rpc: (contract, input) => callPluginRpc(contract, plugin.invoke, input),
     openSettings(screenId) {
       if (!plugin.settingsScreens.some((screen) => screen.id === screenId))
@@ -40,6 +42,7 @@ export function createPluginCapabilities(
       navigation.openSettings(plugin.id, screenId);
     },
     openScreen,
+    composers: (selector) => pluginComposersSource(plugin).resolve(selector),
     // COMPAT(pluginSidebarAliases): added in v0.11.0, remove after 2027-03-29
     openSurface: (screenId) => openScreen({ screenId }),
   };
diff --git a/packages/app/src/plugins/buttons/model.test.ts b/packages/app/src/plugins/buttons/model.test.ts
index 8c07a8615e..ac3aba7672 100644
--- a/packages/app/src/plugins/buttons/model.test.ts
+++ b/packages/app/src/plugins/buttons/model.test.ts
@@ -17,12 +17,18 @@ function installation(): InstalledPlugin {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => undefined,
     settingsScreens: [],
     surfaces: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
diff --git a/packages/app/src/plugins/buttons/view.tsx b/packages/app/src/plugins/buttons/view.tsx
index 3db4381597..1876fef431 100644
--- a/packages/app/src/plugins/buttons/view.tsx
+++ b/packages/app/src/plugins/buttons/view.tsx
@@ -13,7 +13,7 @@ import {
 } from "react";
 import { Pressable, Text, View, useWindowDimensions } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { AlertCircle, ChevronDown, MoreHorizontal } from "lucide-react-native";
+import { AlertCircle, ChevronDown, ChevronUp, MoreHorizontal } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import {
   MenuRoot,
@@ -247,7 +247,11 @@ function ButtonControl({ view }: { view: ButtonView }) {
   const composer = entry.placement === "composer";
   const disabled = button.disabled || entry.pending;
   const expanded = button.behavior.kind !== "action";
-  const chevron = !composer && !props.layout.compact && expanded;
+  // A chevron marks a button that opens something. Composer pills keep their label on compact and
+  // open their surface above, so theirs points up and shows at every width; compact headers drop
+  // the label and the chevron with it.
+  const chevron = expanded && (composer || !props.layout.compact);
+  const Chevron = composer ? ChevronUp : ChevronDown;
   let label = button.label;
   if (composer) label = button.label ?? button.title;
   else if (props.layout.compact) label = undefined;
@@ -284,7 +288,7 @@ function ButtonControl({ view }: { view: ButtonView }) {
       ) : null}
       {chevron ? (
         <View testID="plugin-button-chevron">
-          <ChevronDown size={12} color={props.theme.colors.foregroundMuted} />
+          <Chevron size={12} color={props.theme.colors.foregroundMuted} />
         </View>
       ) : null}
     </>
@@ -559,14 +563,6 @@ function useButtons(serverId: string, workspaceId: string, agentId: string | nul
   );
 }
 
-export function useHasPluginComposerPills(
-  serverId: string,
-  workspaceId: string,
-  agentId: string,
-): boolean {
-  return useButtons(serverId, workspaceId, agentId).length > 0;
-}
-
 export function PluginComposerPills({
   serverId,
   workspaceId,
@@ -660,8 +656,8 @@ const styles = StyleSheet.create((theme) => ({
     gap: { xs: theme.spacing[1], md: theme.spacing[2] },
   },
   headerButton: {
-    height: { xs: 32, md: HEADER_CONTROL_HEIGHT },
-    minWidth: { xs: 32, md: HEADER_CONTROL_HEIGHT },
+    height: HEADER_CONTROL_HEIGHT,
+    minWidth: HEADER_CONTROL_HEIGHT,
     paddingHorizontal: theme.spacing[2],
     flexDirection: "row",
     alignItems: "center",
diff --git a/packages/app/src/plugins/catalog-sync-model.test.ts b/packages/app/src/plugins/catalog-sync-model.test.ts
index 98a8a3cf37..c6efe493ed 100644
--- a/packages/app/src/plugins/catalog-sync-model.test.ts
+++ b/packages/app/src/plugins/catalog-sync-model.test.ts
@@ -1,3 +1,4 @@
+import { getPluginClientApi } from "./client-state/api";
 import appPackage from "../../package.json";
 import { afterEach, expect, it } from "vitest";
 import { QueryObserver } from "@tanstack/react-query";
@@ -139,7 +140,7 @@ function harness() {
           },
           installation.lifetime.signal,
         ),
-        paseo: installation.paseo,
+        paseo: getPluginClientApi(installation).paseo,
         i18n: installation.i18n,
         rpc: async () => {
           throw new Error("Unexpected runtime RPC");
@@ -149,10 +150,14 @@ function harness() {
         },
         openScreen() {},
         openSurface() {},
+        composers: () => [],
         async playAudio() {},
         openPanel() {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });
@@ -196,6 +201,83 @@ async function connected() {
   return { ...h, stop };
 }
 
+it("keeps a restored plugin screen loading until its catalog arrives", async () => {
+  const h = harness();
+  expect(h.registry.getCatalogStatus("host")).toBe("loading");
+  const pending = Promise.withResolvers<Catalog>();
+  class PendingClient extends CatalogClient {
+    override getPluginCatalog() {
+      this.fetches++;
+      return pending.promise;
+    }
+  }
+  const client = new PendingClient();
+  h.sync({ client });
+
+  expect(h.registry.getCatalogStatus("host")).toBe("loading");
+  expect(h.registry.getSnapshot()).toEqual([]);
+  pending.resolve(client.catalog);
+
+  await expect.poll(() => h.registry.getCatalogStatus("host")).toBe("ready");
+  expect(h.installed().id).toBe("reports");
+  expect(client.fetches).toBe(1);
+});
+
+it("settles an empty catalog without leaving missing plugin screens loading", async () => {
+  const h = harness();
+  h.client.catalog = [];
+  const snapshot = h.registry.getSnapshot();
+  const statuses: string[] = [];
+  cleanups.push(
+    h.registry.subscribe(() => {
+      statuses.push(h.registry.getCatalogStatus("host"));
+    }),
+  );
+  h.sync();
+
+  await expect.poll(() => h.registry.getCatalogStatus("host")).toBe("ready");
+  expect(h.registry.getSnapshot()).toBe(snapshot);
+  expect(statuses).toEqual(["loading", "ready"]);
+});
+
+it("settles a failed catalog request instead of loading indefinitely", async () => {
+  const h = harness();
+  class FailingClient extends CatalogClient {
+    override async getPluginCatalog(): Promise<Catalog> {
+      throw new Error("Catalog request failed");
+    }
+  }
+  h.sync({ client: new FailingClient() });
+
+  await expect.poll(() => h.registry.getCatalogStatus("host")).toBe("error");
+  expect(h.registry.getSnapshot()).toEqual([]);
+});
+
+it("ignores an old failed request after a new connection loads its catalog", async () => {
+  const h = harness();
+  const pending = Promise.withResolvers<Catalog>();
+  const started = Promise.withResolvers<void>();
+  class PendingClient extends CatalogClient {
+    override getPluginCatalog() {
+      started.resolve();
+      return pending.promise;
+    }
+  }
+  const stop = h.sync({ client: new PendingClient() });
+  await started.promise;
+  stop();
+  h.sync();
+  await expect.poll(() => h.registry.getCatalogStatus("host")).toBe("ready");
+  const plugin = h.installed();
+
+  pending.reject(new Error("Old connection failed"));
+  await pending.promise.catch(() => undefined);
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+  expect(h.registry.getCatalogStatus("host")).toBe("ready");
+  expect(h.installed()).toBe(plugin);
+});
+
 function settingsQuery(plugin: InstalledPlugin) {
   return {
     queryKey: pluginSettingsKey("preferences"),
diff --git a/packages/app/src/plugins/catalog-sync-model.ts b/packages/app/src/plugins/catalog-sync-model.ts
index 6571294a68..3c11aef63b 100644
--- a/packages/app/src/plugins/catalog-sync-model.ts
+++ b/packages/app/src/plugins/catalog-sync-model.ts
@@ -9,7 +9,10 @@ interface CatalogSyncInput {
   audio: Pick<AudioEngine, "play"> | null;
   connected: boolean;
   supported: boolean;
-  registry: Pick<PluginRegistry, "installCatalog" | "getSnapshot" | "removeHost">;
+  registry: Pick<
+    PluginRegistry,
+    "installCatalog" | "getSnapshot" | "removeHost" | "setCatalogStatus"
+  >;
 }
 
 export function syncPluginCatalog({
@@ -22,30 +25,36 @@ export function syncPluginCatalog({
 }: CatalogSyncInput): () => void {
   if (!supported || !audio) {
     registry.removeHost(serverId);
+    registry.setCatalogStatus(serverId, "ready");
     return () => {};
   }
   // A dropped socket reconnects on the same client, so installations keep rendering offline.
   if (!connected) return () => {};
+  registry.setCatalogStatus(serverId, "loading");
   const installationOptions = { client, audio };
   let cancelled = false;
   let refreshQueue = Promise.resolve();
   function refresh(replacePluginId?: string) {
-    refreshQueue = refreshQueue.then(() =>
-      client
+    refreshQueue = refreshQueue.then(() => {
+      if (cancelled) return undefined;
+      registry.setCatalogStatus(serverId, "loading");
+      return client
         .getPluginCatalog()
         .then((catalog) => {
           if (!cancelled) {
             registry.installCatalog(serverId, catalog, { ...installationOptions, replacePluginId });
+            registry.setCatalogStatus(serverId, "ready");
           }
           return undefined;
         })
         .catch((error) => {
           if (!cancelled) {
+            registry.setCatalogStatus(serverId, "error");
             console.warn(`[Plugins] Failed to load catalog for ${serverId}`, error);
           }
           return undefined;
-        }),
-    );
+        });
+    });
     return refreshQueue;
   }
   const observation = client.observeEvents([
diff --git a/packages/app/src/plugins/client-runtime.ts b/packages/app/src/plugins/client-runtime.ts
index 61e921bd0f..184d24a8f6 100644
--- a/packages/app/src/plugins/client-runtime.ts
+++ b/packages/app/src/plugins/client-runtime.ts
@@ -1,7 +1,7 @@
 import { createPlayAudio, type AudioEngine } from "@/audio";
-import { getHostRuntimeStore } from "@/runtime/host-runtime";
-import { createPluginHosts } from "./hosts";
+import { getPluginClientApi } from "./client-state/api";
 import type { PluginClientOpenPanelOptions } from "@getpaseo/plugin/client";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
 import {
   createPluginAgentActionContext,
   createPluginCapabilities,
@@ -26,7 +26,7 @@ export function createPluginClientRuntime(
     ...capabilities,
     i18n: installation.i18n,
     playAudio: createPlayAudio(audio, installation.lifetime.signal),
-    hosts: createPluginHosts(getHostRuntimeStore(), installation.lifetime.signal),
+    hosts: getPluginClientApi(installation).hosts,
     addComposerPill(contribution) {
       return pluginButtonStore.addComposerPill(installation, contribution);
     },
@@ -36,6 +36,8 @@ export function createPluginClientRuntime(
     openPanel(panelId, options) {
       openClientPanel({ installation, state, panelId, options });
     },
+    subscribe: (contract, input, onEvent, options) =>
+      subscribePluginRpc(contract, installation.subscribe, input, onEvent, options),
   };
 }
 
diff --git a/packages/app/src/plugins/client-state/api.ts b/packages/app/src/plugins/client-state/api.ts
new file mode 100644
index 0000000000..4ce3425f9a
--- /dev/null
+++ b/packages/app/src/plugins/client-state/api.ts
@@ -0,0 +1,68 @@
+import { createPluginReferenceApi } from "@getpaseo/plugin/client/host";
+import { router } from "expo-router";
+import { i18n } from "@/i18n/i18next";
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
+import { usePanelStore } from "@/stores/panel-store";
+import { buildNewWorkspaceRoute } from "@/utils/host-routes";
+import { createPluginHosts } from "../hosts";
+import type { InstalledPlugin } from "../types";
+import { createPluginClientStateSource } from "./source";
+
+interface InstallationApi {
+  paseo: ReturnType<typeof createPluginReferenceApi>;
+  hosts: ReturnType<typeof createPluginHosts>;
+}
+// Registry presentation clones share the installation lifetime and its client pool.
+const apis = new WeakMap<AbortSignal, InstallationApi>();
+
+export function getPluginClientApi(plugin: InstalledPlugin): InstallationApi {
+  const cached = apis.get(plugin.lifetime.signal);
+  if (cached) return cached;
+  const state = createPluginClientStateSource();
+  const hosts = createPluginHosts(getHostRuntimeStore(), plugin.lifetime.signal);
+  const paseo = createPluginReferenceApi({
+    paseo: plugin.paseo,
+    resolveHost: hosts.getPaseoClient,
+    readProject: state.getProject,
+    navigation: {
+      openWorkspace(ref) {
+        navigateToWorkspace({ serverId: ref.hostId, workspaceId: ref.id });
+      },
+      openAgent(ref) {
+        const agent = state.getAgent(ref);
+        if (!agent) throw new Error(i18n.t("sidebar.view.agentUnavailable"));
+        navigateToWorkspace({
+          serverId: ref.hostId,
+          workspaceId: agent.workspace.id,
+          target: { kind: "agent", agentId: ref.id },
+        });
+      },
+      openTerminal(ref) {
+        const terminal = state.getTerminal(ref);
+        if (!terminal) throw new Error(i18n.t("sidebar.view.terminalUnavailable"));
+        navigateToWorkspace({
+          serverId: ref.hostId,
+          workspaceId: terminal.workspace.id,
+          target: { kind: "terminal", terminalId: ref.id },
+        });
+      },
+      openProject(ref) {
+        const project = state.getProject(ref);
+        if (!project) throw new Error(i18n.t("sidebar.view.projectUnavailable"));
+        usePanelStore.getState().showMobileAgent();
+        router.push(
+          buildNewWorkspaceRoute({
+            serverId: ref.hostId,
+            projectId: ref.id,
+            sourceDirectory: project.rootPath,
+            displayName: project.displayName,
+          }),
+        );
+      },
+    },
+  });
+  const api = { paseo, hosts };
+  apis.set(plugin.lifetime.signal, api);
+  return api;
+}
diff --git a/packages/app/src/plugins/client-state/connected-hosts.ts b/packages/app/src/plugins/client-state/connected-hosts.ts
new file mode 100644
index 0000000000..4dfffa6b8d
--- /dev/null
+++ b/packages/app/src/plugins/client-state/connected-hosts.ts
@@ -0,0 +1,72 @@
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import type { PluginConnectedHostsSource } from "./source";
+
+interface PluginHostsRuntime {
+  getHosts(): readonly { serverId: string }[];
+  getSnapshot(serverId: string): { connectionStatus: string } | null | undefined;
+  subscribeAll(listener: () => void): () => void;
+  subscribeHostList(listener: () => void): () => void;
+  acquireDirectoryDemand(serverId: string): () => void;
+}
+
+export function createConnectedPluginHosts(
+  getRuntime: () => PluginHostsRuntime,
+): PluginConnectedHostsSource {
+  let snapshot: readonly string[] = [];
+  const listeners = new Set<() => void>();
+  let release: (() => void) | null = null;
+
+  const source: PluginConnectedHostsSource = {
+    getSnapshot() {
+      const runtime = getRuntime();
+      const next = runtime
+        .getHosts()
+        .filter((host) => runtime.getSnapshot(host.serverId)?.connectionStatus === "online")
+        .map((host) => host.serverId);
+      if (next.length !== snapshot.length || next.some((id, index) => id !== snapshot[index]))
+        snapshot = Object.freeze(next);
+      return snapshot;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      if (!release) {
+        const runtime = getRuntime();
+        const demands = new Map<string, () => void>();
+        const reconcile = () => {
+          const ids = new Set(source.getSnapshot());
+          for (const [id, releaseDemand] of demands) {
+            if (!ids.has(id)) {
+              demands.delete(id);
+              releaseDemand();
+            }
+          }
+          for (const id of ids) {
+            if (!demands.has(id)) demands.set(id, runtime.acquireDirectoryDemand(id));
+          }
+        };
+        const notify = () => {
+          reconcile();
+          for (const subscriber of listeners) subscriber();
+        };
+        const releaseRuntime = runtime.subscribeAll(notify);
+        const releaseHosts = runtime.subscribeHostList(notify);
+        reconcile();
+        release = () => {
+          releaseRuntime();
+          releaseHosts();
+          for (const releaseDemand of demands.values()) releaseDemand();
+          demands.clear();
+        };
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0 && release) {
+          release();
+          release = null;
+        }
+      };
+    },
+  };
+  return source;
+}
+export const connectedPluginHosts = createConnectedPluginHosts(getHostRuntimeStore);
diff --git a/packages/app/src/plugins/client-state/fixtures.ts b/packages/app/src/plugins/client-state/fixtures.ts
new file mode 100644
index 0000000000..08fbc53af3
--- /dev/null
+++ b/packages/app/src/plugins/client-state/fixtures.ts
@@ -0,0 +1,54 @@
+import type { Agent, WorkspaceDescriptor } from "@/stores/session-store";
+export const workspace: WorkspaceDescriptor = {
+  createdAt: null,
+  lastUserMessageAt: null,
+  id: "workspace-1",
+  projectId: "project-1",
+  projectDisplayName: "Paseo",
+  projectRootPath: "/repo/paseo",
+  workspaceDirectory: "/repo/paseo/review",
+  projectKind: "git",
+  workspaceKind: "worktree",
+  name: "Review",
+  title: "Plugin review",
+  pinnedAt: null,
+  status: "running",
+  statusEnteredAt: new Date("2026-08-16T10:00:00.000Z"),
+  archivingAt: null,
+  diffStat: { additions: 12, deletions: 3 },
+  scripts: [],
+};
+
+export const agent: Agent = {
+  serverId: "host-1",
+  id: "agent-1",
+  provider: "codex",
+  status: "running",
+  turn: { phase: "idle", cancellationRequestId: null },
+  createdAt: new Date("2026-08-16T10:01:00.000Z"),
+  updatedAt: new Date("2026-08-16T10:02:00.000Z"),
+  lastUserMessageAt: null,
+  lastActivityAt: new Date("2026-08-16T10:03:00.000Z"),
+  capabilities: {
+    supportsStreaming: true,
+    supportsSessionPersistence: true,
+    supportsDynamicModes: true,
+    supportsMcpServers: true,
+    supportsReasoningStream: true,
+    supportsToolInvocations: true,
+  },
+  currentModeId: "code",
+  availableModes: [],
+  pendingPermissions: [],
+  persistence: null,
+  title: "Implement plugin panels",
+  cwd: "/repo/paseo/review",
+  workspaceId: "workspace-1",
+  model: "gpt-5.6",
+  thinkingOptionId: "high",
+  requiresAttention: true,
+  attentionReason: "permission",
+  parentAgentId: null,
+  labels: { phase: "implementation" },
+  metadata: { "linear.issue": { id: "ENG-1" } },
+};
diff --git a/packages/app/src/plugins/client-state/refs.ts b/packages/app/src/plugins/client-state/refs.ts
new file mode 100644
index 0000000000..edfdd9562c
--- /dev/null
+++ b/packages/app/src/plugins/client-state/refs.ts
@@ -0,0 +1,3 @@
+import { createEntityRefs } from "@getpaseo/plugin/client/host";
+
+export const entityRefs = createEntityRefs();
diff --git a/packages/app/src/plugins/client-state/snapshots.test.ts b/packages/app/src/plugins/client-state/snapshots.test.ts
index 0c90185e53..d0f09008d9 100644
--- a/packages/app/src/plugins/client-state/snapshots.test.ts
+++ b/packages/app/src/plugins/client-state/snapshots.test.ts
@@ -1,66 +1,20 @@
+import { i18n } from "@/i18n/i18next";
+import { fr } from "@/i18n/resources/fr";
 import { describe, expect, it } from "vitest";
-import type { Agent, WorkspaceDescriptor } from "@/stores/session-store";
-import { createPluginAgentSnapshot, createPluginWorkspaceSnapshot } from "./snapshots";
-
-const workspace: WorkspaceDescriptor = {
-  createdAt: null,
-  lastUserMessageAt: null,
-  id: "workspace-1",
-  projectId: "project-1",
-  projectDisplayName: "Paseo",
-  projectRootPath: "/repo/paseo",
-  workspaceDirectory: "/repo/paseo/review",
-  projectKind: "git",
-  workspaceKind: "worktree",
-  name: "Review",
-  title: "Plugin review",
-  pinnedAt: null,
-  status: "running",
-  statusEnteredAt: new Date("2026-08-16T10:00:00.000Z"),
-  archivingAt: null,
-  diffStat: { additions: 12, deletions: 3 },
-  scripts: [],
-};
-
-const agent: Agent = {
-  serverId: "host-1",
-  id: "agent-1",
-  provider: "codex",
-  status: "running",
-  turn: { phase: "idle", cancellationRequestId: null },
-  createdAt: new Date("2026-08-16T10:01:00.000Z"),
-  updatedAt: new Date("2026-08-16T10:02:00.000Z"),
-  lastUserMessageAt: null,
-  lastActivityAt: new Date("2026-08-16T10:03:00.000Z"),
-  capabilities: {
-    supportsStreaming: true,
-    supportsSessionPersistence: true,
-    supportsDynamicModes: true,
-    supportsMcpServers: true,
-    supportsReasoningStream: true,
-    supportsToolInvocations: true,
-  },
-  currentModeId: "code",
-  availableModes: [],
-  pendingPermissions: [],
-  persistence: null,
-  title: "Implement plugin panels",
-  cwd: "/repo/paseo/review",
-  workspaceId: "workspace-1",
-  model: "gpt-5.6",
-  thinkingOptionId: "high",
-  requiresAttention: true,
-  attentionReason: "permission",
-  parentAgentId: null,
-  labels: { phase: "implementation" },
-};
+import type { WorkspaceDescriptor } from "@/stores/session-store";
+import {
+  createPluginAgentSnapshot,
+  createPluginWorkspaceSnapshot,
+  createPluginProjectSnapshot,
+} from "./snapshots";
 
+import { workspace, agent } from "./fixtures";
 describe("plugin context snapshots", () => {
   it("commits a deeply immutable normalized workspace snapshot synchronously", () => {
-    const snapshot = createPluginWorkspaceSnapshot(workspace);
-    expect(createPluginWorkspaceSnapshot(workspace)).toBe(snapshot);
+    const snapshot = createPluginWorkspaceSnapshot(workspace, "host-1");
+    expect(createPluginWorkspaceSnapshot(workspace, "host-1")).toBe(snapshot);
 
-    expect(snapshot).toEqual({
+    expect(snapshot).toMatchObject({
       id: "workspace-1",
       projectId: "project-1",
       projectDisplayName: "Paseo",
@@ -90,7 +44,7 @@ describe("plugin context snapshots", () => {
     const snapshot = createPluginAgentSnapshot(agent, workspace.id);
     expect(createPluginAgentSnapshot(agent, workspace.id)).toBe(snapshot);
 
-    expect(snapshot).toEqual({
+    expect(snapshot).toMatchObject({
       id: "agent-1",
       workspaceId: "workspace-1",
       provider: "codex",
@@ -107,15 +61,98 @@ describe("plugin context snapshots", () => {
       attentionReason: "permission",
       parentAgentId: null,
       labels: { phase: "implementation" },
+      metadata: { "linear.issue": { id: "ENG-1" } },
     });
     expect(snapshot.labels).not.toBe(agent.labels);
     expect(Object.isFrozen(snapshot)).toBe(true);
     expect(Object.isFrozen(snapshot.labels)).toBe(true);
     expect(Reflect.set(snapshot, "title", "Hostile rename")).toBe(false);
     expect(Reflect.set(snapshot.labels, "phase", "hostile")).toBe(false);
+    const issue = snapshot.metadata["linear.issue"] as { id: string };
+    expect(Reflect.set(issue, "id", "hostile")).toBe(false);
+    expect(agent.metadata?.["linear.issue"]).toEqual({ id: "ENG-1" });
     expect(snapshot.title).toBe("Implement plugin panels");
     expect(snapshot.labels).toEqual({ phase: "implementation" });
     expect(agent.title).toBe("Implement plugin panels");
     expect(agent.labels).toEqual({ phase: "implementation" });
   });
 });
+
+describe("sidebar entity snapshots", () => {
+  it("interns cross-host references and preserves identity across unrelated reads", () => {
+    const first = createPluginWorkspaceSnapshot(workspace, "host-1");
+    const second = createPluginWorkspaceSnapshot(workspace, "host-2");
+    expect(first.ref).not.toBe(second.ref);
+    expect(first.ref.hostId).toBe("host-1");
+    expect(first.project.id).toBe(workspace.projectId);
+    expect(Object.isFrozen(first.labels)).toBe(true);
+    expect(createPluginWorkspaceSnapshot(workspace, "host-1")).toBe(first);
+    expect(createPluginAgentSnapshot(agent, workspace.id).workspace).toBe(first.ref);
+  });
+
+  it("invalidates a done workspace when its effective root-agent status changes", () => {
+    const idle: WorkspaceDescriptor = { ...workspace, status: "done" };
+    const before = createPluginWorkspaceSnapshot(idle, "host-1");
+    const activity = new Map([
+      [idle.id, { agentId: agent.id, status: "needs_input" as const, enteredAt: null }],
+    ]);
+    const after = createPluginWorkspaceSnapshot(idle, "host-1", {
+      workspaceAgentActivity: activity,
+    });
+    expect(before.indicator).toBe("done");
+    expect(after.status).toBe("done");
+    expect(after.indicator).toBe("needs_input");
+    expect(after.indicatorLabel).toBe("Needs input");
+    expect(after.ref).toBe(before.ref);
+    expect(
+      createPluginWorkspaceSnapshot(idle, "host-1", { workspaceAgentActivity: activity }),
+    ).toBe(after);
+  });
+
+  it("reads projects without requiring a workspace", () => {
+    const project = {
+      projectId: "empty",
+      projectDisplayName: "Empty",
+      projectCustomName: null,
+      projectRootPath: "/empty",
+      projectKind: "git" as const,
+    };
+    const snapshot = createPluginProjectSnapshot(project, "host-1");
+    expect(createPluginProjectSnapshot(project, "host-1")).toBe(snapshot);
+    expect(snapshot.displayName).toBe("Empty");
+    expect(snapshot.ref.id).toBe("empty");
+    expect(Object.isFrozen(snapshot)).toBe(true);
+  });
+});
+
+it("uses the app status labels and invalidates a snapshot on language change", async () => {
+  i18n.addResourceBundle("fr", "translation", fr);
+  const previousLanguage = i18n.language;
+  try {
+    await i18n.changeLanguage("en");
+    const english = createPluginWorkspaceSnapshot(workspace, "host-1");
+    expect(english.indicatorLabel).toBe("Working");
+    await i18n.changeLanguage("fr");
+    const french = createPluginWorkspaceSnapshot(workspace, "host-1");
+    expect(french).not.toBe(english);
+    expect(french.ref).toBe(english.ref);
+    expect(french.indicatorLabel).toBe("En cours");
+    expect(createPluginWorkspaceSnapshot(workspace, "host-1")).toBe(french);
+  } finally {
+    await i18n.changeLanguage(previousLanguage);
+  }
+});
+
+it("preserves the host-qualified parent of a remotely delegated agent", () => {
+  const child = {
+    ...agent,
+    serverId: "host-2",
+    parentAgentId: null,
+    labels: { "paseo.parent-server-id": "host-1", "paseo.parent-agent-id": "parent" },
+  };
+  expect(createPluginAgentSnapshot(child, workspace.id).parentAgent).toMatchObject({
+    hostId: "host-1",
+    id: "parent",
+    kind: "agent",
+  });
+});
diff --git a/packages/app/src/plugins/client-state/snapshots.ts b/packages/app/src/plugins/client-state/snapshots.ts
index 67a08830cd..d805913201 100644
--- a/packages/app/src/plugins/client-state/snapshots.ts
+++ b/packages/app/src/plugins/client-state/snapshots.ts
@@ -1,16 +1,58 @@
-import type { PluginAgentSnapshot, PluginWorkspaceSnapshot } from "@getpaseo/plugin";
-import type { Agent, WorkspaceDescriptor } from "@/stores/session-store";
+import { getParentAddressFromLabels } from "@getpaseo/protocol/agent-labels";
+import { i18n } from "@/i18n/i18next";
+import type {
+  PluginAgentSnapshot,
+  PluginWorkspaceSnapshot,
+  PluginProjectSnapshot,
+} from "@getpaseo/plugin";
+import type { Agent, WorkspaceDescriptor, ProjectDescriptor } from "@/stores/session-store";
+import { cloneAndFreeze } from "../freeze";
 
-const workspaceSnapshots = new WeakMap<WorkspaceDescriptor, PluginWorkspaceSnapshot>();
+import { entityRefs } from "./refs";
+import { deriveEffectiveWorkspaceStatus } from "@/workspace-status";
+
+interface CachedWorkspace {
+  language: string;
+  snapshot: PluginWorkspaceSnapshot;
+}
+const workspaceSnapshots = new WeakMap<WorkspaceDescriptor, Map<string, CachedWorkspace>>();
 const agentSnapshots = new WeakMap<Agent, Map<string, PluginAgentSnapshot>>();
 
 export function createPluginWorkspaceSnapshot(
   workspace: WorkspaceDescriptor,
+  hostId: string,
+  context: Omit<Parameters<typeof deriveEffectiveWorkspaceStatus>[0], "workspace" | "serverId"> & {
+    parentAgent?: PluginWorkspaceSnapshot["parentAgent"];
+  } = {},
 ): PluginWorkspaceSnapshot {
-  const cached = workspaceSnapshots.get(workspace);
-  if (cached) return cached;
+  const indicator = deriveEffectiveWorkspaceStatus({
+    ...context,
+    workspace,
+    serverId: hostId,
+  }).status;
+  const parentAgent = context.parentAgent ?? null;
+  const cached = workspaceSnapshots.get(workspace)?.get(hostId);
+  if (
+    cached &&
+    cached.language === i18n.language &&
+    cached.snapshot.indicator === indicator &&
+    cached.snapshot.parentAgent === parentAgent
+  )
+    return cached.snapshot;
   const diffStat = workspace.diffStat ? Object.freeze({ ...workspace.diffStat }) : null;
   const snapshot = Object.freeze({
+    ref: entityRefs.workspace(hostId, workspace.id),
+    hostId,
+    project: entityRefs.project(hostId, workspace.projectId),
+    pinnedAt: workspace.pinnedAt ?? null,
+    labels: Object.freeze([...(workspace.labels ?? [])]),
+    background: workspace.background ?? false,
+    branch: workspace.gitRuntime?.currentBranch ?? null,
+    createdAt: serializeTimestamp(workspace.createdAt),
+    lastPromptAt: serializeTimestamp(workspace.lastUserMessageAt),
+    parentAgent,
+    indicator,
+    indicatorLabel: i18n.t(indicatorLabelKeys[indicator]),
     id: workspace.id,
     projectId: workspace.projectId,
     projectDisplayName: workspace.projectDisplayName,
@@ -21,18 +63,25 @@ export function createPluginWorkspaceSnapshot(
     name: workspace.name,
     title: workspace.title ?? null,
     status: workspace.status,
-    statusEnteredAt: workspace.statusEnteredAt?.toISOString() ?? null,
+    statusEnteredAt: serializeTimestamp(workspace.statusEnteredAt),
     archivingAt: workspace.archivingAt,
     diffStat,
   });
-  workspaceSnapshots.set(workspace, snapshot);
+  const byHost = workspaceSnapshots.get(workspace) ?? new Map<string, CachedWorkspace>();
+  byHost.set(hostId, { language: i18n.language, snapshot });
+  workspaceSnapshots.set(workspace, byHost);
   return snapshot;
 }
 
 export function createPluginAgentSnapshot(agent: Agent, workspaceId: string): PluginAgentSnapshot {
   const cached = agentSnapshots.get(agent)?.get(workspaceId);
   if (cached) return cached;
+  const parent = getParentAddressFromLabels(agent.labels, agent.serverId);
   const snapshot = Object.freeze({
+    ref: entityRefs.agent(agent.serverId, agent.id),
+    hostId: agent.serverId,
+    workspace: entityRefs.workspace(agent.serverId, workspaceId),
+    parentAgent: parent ? entityRefs.agent(parent.serverId, parent.agentId) : null,
     id: agent.id,
     workspaceId,
     provider: agent.provider,
@@ -49,9 +98,43 @@ export function createPluginAgentSnapshot(agent: Agent, workspaceId: string): Pl
     attentionReason: agent.attentionReason ?? null,
     parentAgentId: agent.parentAgentId,
     labels: Object.freeze({ ...agent.labels }),
+    metadata: cloneAndFreeze(agent.metadata ?? {}),
   });
   const byWorkspace = agentSnapshots.get(agent) ?? new Map<string, PluginAgentSnapshot>();
   byWorkspace.set(workspaceId, snapshot);
   agentSnapshots.set(agent, byWorkspace);
   return snapshot;
 }
+
+const indicatorLabelKeys = {
+  needs_input: "sidebar.statusBucket.needsInput",
+  failed: "sidebar.statusBucket.failed",
+  running: "sidebar.statusBucket.working",
+  attention: "sidebar.statusBucket.readyToReview",
+  done: "sidebar.statusBucket.done",
+} as const;
+const projectSnapshots = new WeakMap<ProjectDescriptor, Map<string, PluginProjectSnapshot>>();
+
+export function createPluginProjectSnapshot(
+  project: ProjectDescriptor,
+  hostId: string,
+): PluginProjectSnapshot {
+  const cached = projectSnapshots.get(project)?.get(hostId);
+  if (cached) return cached;
+  const snapshot = Object.freeze({
+    ref: entityRefs.project(hostId, project.projectId),
+    hostId,
+    displayName: project.projectCustomName ?? project.projectDisplayName,
+    rootPath: project.projectRootPath,
+    kind: project.projectKind,
+    iconRevision: project.projectCustomIconRevision ?? project.projectIconRevision ?? null,
+  });
+  const byHost = projectSnapshots.get(project) ?? new Map<string, PluginProjectSnapshot>();
+  byHost.set(hostId, snapshot);
+  projectSnapshots.set(project, byHost);
+  return snapshot;
+}
+
+function serializeTimestamp(value: Date | null): string | null {
+  return value ? value.toISOString() : null;
+}
diff --git a/packages/app/src/plugins/client-state/source-retention.test.ts b/packages/app/src/plugins/client-state/source-retention.test.ts
new file mode 100644
index 0000000000..b11fc5d731
--- /dev/null
+++ b/packages/app/src/plugins/client-state/source-retention.test.ts
@@ -0,0 +1,55 @@
+import { setFlagsFromString } from "node:v8";
+import { runInNewContext } from "node:vm";
+import { setImmediate } from "node:timers/promises";
+import { expect, it } from "vitest";
+import { useSessionStore } from "@/stores/session-store";
+import { createPluginClientStateSource } from "./source";
+import { workspace } from "./fixtures";
+
+setFlagsFromString("--expose_gc");
+const collectGarbage: () => void = runInNewContext("gc");
+setFlagsFromString("--no-expose_gc");
+
+function observeHost() {
+  const hostId = "removed-plugin-host";
+  let hosts = [hostId];
+  const store = useSessionStore.getState();
+  store.initializeSession(hostId, null);
+  store.setWorkspaces(hostId, new Map([[workspace.id, { ...workspace }]]));
+  const source = createPluginClientStateSource(undefined, {
+    hosts: { getSnapshot: () => hosts, subscribe: () => () => {} },
+  });
+  const release = source.subscribe(() => source.getSnapshot());
+  source.getSnapshot();
+  const reference = new WeakRef(useSessionStore.getState().sessions[hostId]!.workspaces);
+  const remove = () => {
+    hosts = [];
+    store.clearSession(hostId);
+  };
+  return { reference, release, remove };
+}
+
+it("releases removed hosts' projected data while other plugin readers remain", async () => {
+  const { reference, release, remove } = observeHost();
+  remove();
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      await setImmediate();
+      collectGarbage();
+    }
+    expect(reference.deref()).toBeUndefined();
+  } finally {
+    release();
+  }
+});
+
+it("releases previous projections when the last plugin reader leaves", async () => {
+  const { reference, release, remove } = observeHost();
+  release();
+  remove();
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await setImmediate();
+    collectGarbage();
+  }
+  expect(reference.deref()).toBeUndefined();
+});
diff --git a/packages/app/src/plugins/client-state/source.browser.test.tsx b/packages/app/src/plugins/client-state/source.browser.test.tsx
new file mode 100644
index 0000000000..46e31c7cab
--- /dev/null
+++ b/packages/app/src/plugins/client-state/source.browser.test.tsx
@@ -0,0 +1,420 @@
+import { Nested } from "../../../../../plugin-examples/sidebar-views/client/nested";
+import { lightTheme } from "@/styles/theme";
+import { toPluginTheme } from "../theme";
+import { createConnectedPluginHosts } from "./connected-hosts";
+import { i18n } from "@/i18n/i18next";
+import { fr } from "@/i18n/resources/fr";
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { createEntityRefs, PluginClientStateProvider } from "@getpaseo/plugin/client/host";
+import {
+  useAgents,
+  useWorkspaces,
+  useWorkspace,
+  useAgent,
+  type WorkspaceRef,
+  type AgentRef,
+} from "@getpaseo/plugin/client";
+import { useSessionStore, type Agent } from "@/stores/session-store";
+import { createPluginClientStateSource, type PluginConnectedHostsSource } from "./source";
+import { agent, workspace } from "./fixtures";
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+const renders = new Map<string, number>();
+function count(key: string) {
+  renders.set(key, (renders.get(key) ?? 0) + 1);
+}
+function WorkspaceRow({ reference }: { reference: WorkspaceRef }) {
+  const item = useWorkspace(reference);
+  count(reference.key);
+  return (
+    <div>
+      {item?.name}:{item?.indicator}
+    </div>
+  );
+}
+function Workspaces() {
+  count("workspaces");
+  const items = useWorkspaces({ orderBy: "name" });
+  return (
+    <div>
+      {items.map((reference) => (
+        <WorkspaceRow key={reference.key} reference={reference} />
+      ))}
+    </div>
+  );
+}
+function SelectedWorkspace({ reference }: { reference: WorkspaceRef }) {
+  const name = useWorkspace(reference, (item) => ({ name: item.name }));
+  const custom = useWorkspace(reference, undefined, (a, b) => a?.name === b?.name);
+  count("selected");
+  return (
+    <div>
+      {name?.name}:{custom?.name}
+    </div>
+  );
+}
+function AgentRow({ reference }: { reference: AgentRef }) {
+  const item = useAgent(reference);
+  return <div>{item?.title}</div>;
+}
+function AgentSection({ section }: { section: string }) {
+  const agents = useAgents({
+    where: (item) => (item.requiresAttention ? "waiting" : item.status) === section,
+  });
+  count(section);
+  return (
+    <div>
+      {agents.map((reference) => (
+        <AgentRow key={reference.key} reference={reference} />
+      ))}
+    </div>
+  );
+}
+function Agents() {
+  return (
+    <div>
+      <AgentSection section="running" />
+      <AgentSection section="waiting" />
+      <AgentSection section="idle" />
+    </div>
+  );
+}
+function seedHost(hostId: string) {
+  const store = useSessionStore.getState();
+  store.initializeSession(hostId, null);
+  store.setWorkspaces(
+    hostId,
+    new Map([
+      ["workspace-1", { ...workspace, id: "workspace-1", status: "done", name: "First" }],
+      ["workspace-2", { ...workspace, id: "workspace-2", status: "done", name: "Second" }],
+    ]),
+  );
+  store.setProjects(hostId, [
+    {
+      projectId: "empty",
+      projectDisplayName: "Empty project",
+      projectCustomName: null,
+      projectRootPath: "/empty",
+      projectKind: "git",
+    },
+  ]);
+  store.setAgents(
+    hostId,
+    new Map<string, Agent>([
+      [
+        "agent-1",
+        {
+          ...agent,
+          serverId: hostId,
+          id: "agent-1",
+          workspaceId: "workspace-1",
+          status: "running",
+          requiresAttention: false,
+          attentionReason: null,
+          turn: { phase: "open", turnId: null, startedAt: null, cancellationRequestId: null },
+        },
+      ],
+      [
+        "agent-2",
+        {
+          ...agent,
+          serverId: hostId,
+          id: "agent-2",
+          workspaceId: "workspace-2",
+          status: "running",
+          requiresAttention: false,
+          attentionReason: null,
+          turn: { phase: "open", turnId: null, startedAt: null, cancellationRequestId: null },
+        },
+      ],
+    ]),
+  );
+}
+it("keeps archived agents readable individually while excluding them from collections", () => {
+  seedHost("host-1");
+  const source = createPluginClientStateSource("host-1", { hosts: new ConnectedHosts() });
+  const reference = source.getSnapshot().agents[0]!.ref;
+  useSessionStore.getState().setAgents(
+    "host-1",
+    new Map([
+      [
+        agent.id,
+        {
+          ...agent,
+          archivedAt: new Date("2026-11-01T00:00:00.000Z"),
+        },
+      ],
+    ]),
+  );
+  expect(source.getSnapshot().agents).toEqual([]);
+  expect(source.getAgent(reference)?.title).toBe(agent.title);
+  expect(source.getAgent(agent.id)).toBe(source.getAgent(reference));
+});
+
+it("demands directories for connected hosts and releases them with its last reader", () => {
+  const hostId = "plugin-demand-host";
+  let online = true;
+  let demands = 0;
+  const listeners = new Set<() => void>();
+  const hosts = createConnectedPluginHosts(() => ({
+    getHosts: () => [{ serverId: hostId }],
+    getSnapshot: () => ({ connectionStatus: online ? "online" : "offline" }),
+    subscribeAll: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    subscribeHostList: () => () => {},
+    acquireDirectoryDemand: () => {
+      demands++;
+      seedHost(hostId);
+      return () => {
+        demands--;
+      };
+    },
+  }));
+  const source = createPluginClientStateSource(undefined, { hosts });
+  const first = source.subscribe(() => {});
+  const second = source.subscribe(() => {});
+  expect(demands).toBe(1);
+  expect(source.getSnapshot().workspaces.map((item) => item.hostId)).toEqual([hostId, hostId]);
+  useSessionStore
+    .getState()
+    .setWorkspaces(
+      hostId,
+      (previous) =>
+        new Map([...previous].map(([id, item]) => [id, { ...item, name: "Live update" }])),
+    );
+  expect(source.getSnapshot().workspaces.map((item) => item.name)).toEqual([
+    "Live update",
+    "Live update",
+  ]);
+  online = false;
+  for (const listener of listeners) listener();
+  expect(demands).toBe(0);
+  expect(source.getSnapshot().workspaces).toEqual([]);
+  online = true;
+  for (const listener of listeners) listener();
+  expect(demands).toBe(1);
+  first();
+  expect(demands).toBe(1);
+  second();
+  expect(demands).toBe(0);
+  expect(listeners.size).toBe(0);
+});
+
+function waitForInput() {
+  useSessionStore.getState().setAgents("host-1", (previous) => {
+    const current = previous.get("agent-1");
+    if (!current) throw new Error("Missing test agent");
+    const next = new Map(previous);
+    next.set(current.id, {
+      ...current,
+      status: "idle",
+      turn: { phase: "idle", cancellationRequestId: null },
+      requiresAttention: true,
+      attentionReason: "permission",
+    });
+    return next;
+  });
+}
+class ConnectedHosts implements PluginConnectedHostsSource {
+  private ids: readonly string[] = ["host-1"];
+  private listeners = new Set<() => void>();
+  getSnapshot = () => this.ids;
+  subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  connect(id: string) {
+    this.ids = [...this.ids, id];
+    for (const listener of this.listeners) listener();
+  }
+}
+function mount(children: React.ReactNode, hosts = new ConnectedHosts()) {
+  const source = createPluginClientStateSource("host-1", { hosts });
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() =>
+    root?.render(<PluginClientStateProvider source={source}>{children}</PluginClientStateProvider>),
+  );
+  return source;
+}
+afterEach(() => {
+  act(() => root?.unmount());
+  container?.remove();
+  root = null;
+  container = null;
+  useSessionStore.getState().clearSession("host-1");
+  useSessionStore.getState().clearSession("host-2");
+  renders.clear();
+});
+
+it("shows a restored child in the nested example while its cached parent remains archived", () => {
+  seedHost("host-1");
+  const parent = {
+    ...agent,
+    id: "archived-parent",
+    title: "Archived parent",
+    archivedAt: new Date("2026-11-01T00:00:00Z"),
+  };
+  const child = {
+    ...agent,
+    id: "restored-child",
+    title: "Restored child",
+    parentAgentId: parent.id,
+    labels: { "paseo.parent-agent-id": parent.id },
+    archivedAt: parent.archivedAt,
+  };
+  const store = useSessionStore.getState();
+  store.setProjects("host-1", [
+    {
+      projectId: workspace.projectId,
+      projectDisplayName: "Project",
+      projectCustomName: null,
+      projectRootPath: workspace.projectRootPath,
+      projectKind: "git",
+    },
+  ]);
+  store.setAgents(
+    "host-1",
+    new Map<string, Agent>([
+      [parent.id, parent],
+      [child.id, child],
+    ]),
+  );
+  const view = {
+    theme: toPluginTheme(lightTheme),
+    layout: { compact: false, platform: "web" as const },
+    active: { workspace: null, agent: null },
+    navigation: { openWorkspace() {}, openAgent() {}, openProject() {}, openTerminal() {} },
+    dismiss() {},
+  };
+  const source = mount(<Nested {...view} />);
+  expect(source.getAgent(parent.id)?.title).toBe(parent.title);
+  expect(container?.textContent).not.toContain(child.title);
+  act(() =>
+    store.setAgents(
+      "host-1",
+      new Map<string, Agent>([
+        [parent.id, parent],
+        [child.id, { ...child, archivedAt: null }],
+      ]),
+    ),
+  );
+  expect(container?.querySelector('[aria-label="Open agent Restored child"]')).not.toBeNull();
+  expect(container?.querySelector('[aria-label="Open agent Archived parent"]')).toBeNull();
+});
+
+describe("sidebar data hooks through the app store and plugin provider", () => {
+  it("renders only one workspace row when its root agent starts waiting", () => {
+    seedHost("host-1");
+    const source = mount(<Workspaces />);
+    const first = source.getSnapshot().workspaces[0]!;
+    const second = source.getSnapshot().workspaces[1]!;
+    const before = source.getSnapshot();
+    act(waitForInput);
+    expect(renders.get("workspaces")).toBe(1);
+    expect(renders.get(first.ref.key)).toBe(2);
+    expect(renders.get(second.ref.key)).toBe(1);
+    expect(source.getSnapshot().workspaces[0]?.indicator).toBe("needs_input");
+    expect(source.getSnapshot().workspaces[1]).toBe(before.workspaces[1]);
+  });
+  it("moves the agent and renders only its two affected sections without memo", () => {
+    seedHost("host-1");
+    mount(<Agents />);
+    act(waitForInput);
+    expect(renders.get("running")).toBe(2);
+    expect(renders.get("waiting")).toBe(2);
+    expect(renders.get("idle")).toBe(1);
+  });
+  it("uses shallow selected equality and custom equality without a selector", () => {
+    seedHost("host-1");
+    const source = createPluginClientStateSource("host-1", { hosts: new ConnectedHosts() });
+    mount(<SelectedWorkspace reference={source.getSnapshot().workspaces[0]!.ref} />);
+    act(waitForInput);
+    expect(renders.get("selected")).toBe(1);
+  });
+  it("refreshes translated labels through the subscribed source when language changes", async () => {
+    seedHost("host-1");
+    i18n.addResourceBundle("fr", "translation", fr);
+    const source = mount(<Workspaces />);
+    const before = source.getSnapshot().workspaces[0]!;
+    const previousLanguage = i18n.language;
+    try {
+      await act(async () => {
+        await i18n.changeLanguage("fr");
+      });
+      const after = source.getSnapshot().workspaces[0]!;
+      expect(after).not.toBe(before);
+      expect(after.indicatorLabel).toBe("En cours");
+      expect(after.ref).toBe(before.ref);
+      expect(renders.get(before.ref.key)).toBe(2);
+      expect(renders.get("workspaces")).toBe(1);
+    } finally {
+      await act(async () => {
+        await i18n.changeLanguage(previousLanguage);
+      });
+    }
+  });
+  it("adds a newly connected host and exposes projects with no workspaces", () => {
+    seedHost("host-1");
+    seedHost("host-2");
+    const hosts = new ConnectedHosts();
+    const source = mount(<Workspaces />, hosts);
+    expect(source.getSnapshot().workspaces).toHaveLength(2);
+    expect(source.getSnapshot().projects[0]?.displayName).toBe("Empty project");
+    act(() => hosts.connect("host-2"));
+    expect(source.getSnapshot().workspaces).toHaveLength(4);
+    expect(source.getSnapshot().projects).toHaveLength(2);
+    expect(new Set(source.getSnapshot().workspaces.map((item) => item.ref.key)).size).toBe(4);
+  });
+});
+
+it("observes terminals only while a terminal reader is subscribed", () => {
+  let active = 0;
+  const source = createPluginClientStateSource(undefined, {
+    hosts: { getSnapshot: () => [], subscribe: () => () => {} },
+    terminals: {
+      getSnapshot: () => [],
+      subscribe: () => {
+        active++;
+        return () => {
+          active--;
+        };
+      },
+    },
+  });
+  const releaseWorkspace = source.subscribe(() => {});
+  expect(active).toBe(0);
+  const releaseTerminal = source.subscribe(() => {}, { terminals: true });
+  const releaseSecond = source.subscribe(() => {}, { terminals: true });
+  expect(active).toBe(1);
+  releaseTerminal();
+  expect(active).toBe(1);
+  releaseSecond();
+  expect(active).toBe(0);
+  releaseWorkspace();
+});
+
+it("terminal row reads propagate only the referenced host's observation error", () => {
+  const error = new Error("Update the host");
+  const source = createPluginClientStateSource(undefined, {
+    hosts: { getSnapshot: () => [], subscribe: () => () => {} },
+    terminals: {
+      getSnapshot: () => [],
+      subscribe: () => () => {},
+      getErrors: () => new Map([["unsupported", error]]),
+    },
+  });
+  const refs = createEntityRefs();
+  expect(() => source.getTerminal(refs.terminal("unsupported", "retained"))).toThrow(error);
+  expect(source.getTerminal(refs.terminal("supported", "missing"))).toBeNull();
+});
diff --git a/packages/app/src/plugins/client-state/source.ts b/packages/app/src/plugins/client-state/source.ts
index 142c1f3575..137c6624cb 100644
--- a/packages/app/src/plugins/client-state/source.ts
+++ b/packages/app/src/plugins/client-state/source.ts
@@ -1,21 +1,248 @@
-import type { PluginClientStateSource } from "@getpaseo/plugin/client/host";
-import { useSessionStore } from "@/stores/session-store";
-import { selectWorkspace } from "@/stores/session-store-hooks/selectors";
+import { i18n } from "@/i18n/i18next";
+import type { PluginClientSnapshot, PluginClientStateSource } from "@getpaseo/plugin/client/host";
+import type { PluginTerminalSnapshot } from "@getpaseo/plugin";
+import { useCreateFlowStore } from "@/stores/create-flow-store";
+import { useSessionStore, type SessionState } from "@/stores/session-store";
 import { normalizeWorkspaceOpaqueId } from "@/utils/workspace-identity";
-import { createPluginAgentSnapshot, createPluginWorkspaceSnapshot } from "./snapshots";
+import { connectedPluginHosts } from "./connected-hosts";
+import { pluginTerminals } from "./terminals";
+import { entityRefs } from "./refs";
+import {
+  createPluginAgentSnapshot,
+  createPluginProjectSnapshot,
+  createPluginWorkspaceSnapshot,
+} from "./snapshots";
 
-export function createPluginClientStateSource(serverId: string): PluginClientStateSource {
-  return {
-    subscribe: useSessionStore.subscribe,
-    getWorkspace(workspaceId) {
-      const workspace = selectWorkspace(useSessionStore.getState(), serverId, workspaceId);
-      return workspace ? createPluginWorkspaceSnapshot(workspace) : null;
+export interface PluginConnectedHostsSource {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): readonly string[];
+}
+
+export interface PluginTerminalsSource {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): readonly PluginTerminalSnapshot[];
+  getErrors?(): ReadonlyMap<string, Error>;
+}
+
+const emptyTerminals: readonly PluginTerminalSnapshot[] = Object.freeze([]);
+const listeners = new Set<() => void>();
+let releaseStores: (() => void) | null = null;
+
+// Every plugin host shares one subscription to each app store.
+function subscribeStores(listener: () => void): () => void {
+  if (!releaseStores) {
+    const notify = () => {
+      for (const subscriber of listeners) subscriber();
+    };
+    i18n.on("languageChanged", notify);
+    const releaseSession = useSessionStore.subscribe((state) => {
+      for (const hostId of hostProjections.keys()) {
+        if (!state.sessions[hostId]) hostProjections.delete(hostId);
+      }
+      notify();
+    });
+    const releaseCreate = useCreateFlowStore.subscribe(notify);
+    releaseStores = () => {
+      i18n.off("languageChanged", notify);
+      releaseSession();
+      releaseCreate();
+    };
+  }
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0 && releaseStores) {
+      releaseStores();
+      releaseStores = null;
+      hostProjections.clear();
+    }
+  };
+}
+
+interface HostProjection {
+  language: string;
+  workspaces: SessionState["workspaces"];
+  agents: SessionState["agents"];
+  projects: SessionState["projects"];
+  activity: SessionState["workspaceAgentActivity"];
+  pending: ReturnType<typeof useCreateFlowStore.getState>["pendingByDraftId"];
+  snapshot: Omit<PluginClientSnapshot, "terminals">;
+  workspaceById: Map<string, PluginClientSnapshot["workspaces"][number]>;
+  agentById: Map<string, PluginClientSnapshot["agents"][number]>;
+  projectById: Map<string, PluginClientSnapshot["projects"][number]>;
+}
+const hostProjections = new Map<string, HostProjection>();
+
+function projectHost(hostId: string): HostProjection | null {
+  const session = useSessionStore.getState().sessions[hostId];
+  if (!session) {
+    hostProjections.delete(hostId);
+    return null;
+  }
+  const pending = useCreateFlowStore.getState().pendingByDraftId;
+  const previous = hostProjections.get(hostId);
+  const unchanged =
+    previous &&
+    previous.language === i18n.language &&
+    previous.workspaces === session.workspaces &&
+    previous.agents === session.agents &&
+    previous.projects === session.projects &&
+    previous.activity === session.workspaceAgentActivity &&
+    previous.pending === pending;
+  if (unchanged) return previous;
+  const workspaces = Array.from(session.workspaces.values(), (workspace) => {
+    const activity = session.workspaceAgentActivity.get(workspace.id);
+    const root = activity ? session.agents.get(activity.agentId) : undefined;
+    return createPluginWorkspaceSnapshot(workspace, hostId, {
+      pendingCreateAttempts: pending,
+      workspaceAgentActivity: session.workspaceAgentActivity,
+      parentAgent: root ? createPluginAgentSnapshot(root, workspace.id).parentAgent : null,
+    });
+  });
+  const agents: PluginClientSnapshot["agents"][number][] = [];
+  for (const agent of session.agents.values()) {
+    const workspaceId = normalizeWorkspaceOpaqueId(agent.workspaceId);
+    if (!workspaceId || agent.archivedAt) continue;
+    agents.push(createPluginAgentSnapshot(agent, workspaceId));
+  }
+  const projects = Array.from(session.projects.values(), (project) =>
+    createPluginProjectSnapshot(project, hostId),
+  );
+  const projection: HostProjection = {
+    language: i18n.language,
+    workspaces: session.workspaces,
+    agents: session.agents,
+    projects: session.projects,
+    activity: session.workspaceAgentActivity,
+    pending,
+    snapshot: {
+      workspaces: Object.freeze(workspaces),
+      agents: Object.freeze(agents),
+      projects: Object.freeze(projects),
     },
-    getAgent(agentId) {
-      const session = useSessionStore.getState().sessions[serverId];
-      const agent = session?.agents.get(agentId) ?? session?.agentDetails.get(agentId) ?? null;
-      const workspaceId = normalizeWorkspaceOpaqueId(agent?.workspaceId);
-      return agent && workspaceId ? createPluginAgentSnapshot(agent, workspaceId) : null;
+    workspaceById: new Map(workspaces.map((workspace) => [workspace.id, workspace])),
+    agentById: new Map(agents.map((agent) => [agent.id, agent])),
+    projectById: new Map(projects.map((project) => [project.ref.id, project])),
+  };
+  hostProjections.set(hostId, projection);
+  return projection;
+}
+
+function sameSequence<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+/** A host scope only resolves legacy string ids. Ref lookups and collections span hosts. */
+export function createPluginClientStateSource(
+  serverId?: string,
+  options: { hosts?: PluginConnectedHostsSource; terminals?: PluginTerminalsSource } = {},
+): PluginClientStateSource {
+  const terminals = options.terminals ?? pluginTerminals;
+  const hosts = options.hosts ?? connectedPluginHosts;
+  const subscribers = new Set<() => void>();
+  const terminalSubscribers = new Set<() => void>();
+  let releaseTerminals: (() => void) | null = null;
+  let release: (() => void) | null = null;
+  let previousProjections: readonly HostProjection[] = [];
+  let previousTerminals = emptyTerminals;
+  let previousTerminalErrors: ReadonlyMap<string, Error> | undefined;
+  let snapshot: PluginClientSnapshot = {
+    workspaces: [],
+    agents: [],
+    projects: [],
+    terminals: emptyTerminals,
+  };
+  function getSnapshot(): PluginClientSnapshot {
+    const ids = hosts.getSnapshot();
+    const projections: HostProjection[] = [];
+    for (const id of ids) {
+      const projection = projectHost(id);
+      if (projection) projections.push(projection);
+    }
+    const terminalSnapshots = terminals.getSnapshot();
+    const terminalErrors = terminals.getErrors?.();
+    if (
+      sameSequence(previousProjections, projections) &&
+      previousTerminals === terminalSnapshots &&
+      previousTerminalErrors === terminalErrors
+    )
+      return snapshot;
+    previousProjections = projections;
+    previousTerminals = terminalSnapshots;
+    previousTerminalErrors = terminalErrors;
+    snapshot = Object.freeze({
+      workspaces: Object.freeze(projections.flatMap((host) => host.snapshot.workspaces)),
+      agents: Object.freeze(projections.flatMap((host) => host.snapshot.agents)),
+      projects: Object.freeze(projections.flatMap((host) => host.snapshot.projects)),
+      terminals: terminalSnapshots,
+      terminalErrors,
+    });
+    return snapshot;
+  }
+  return {
+    subscribe(listener, subscriptionOptions) {
+      subscribers.add(listener);
+      if (subscriptionOptions?.terminals) {
+        terminalSubscribers.add(listener);
+        releaseTerminals ??= terminals.subscribe(() => {
+          for (const subscriber of terminalSubscribers) subscriber();
+        });
+      }
+      if (!release) {
+        const notify = () => {
+          for (const subscriber of subscribers) subscriber();
+        };
+        const releaseStore = subscribeStores(notify);
+        const releaseHosts = hosts.subscribe(notify);
+        release = () => {
+          releaseStore();
+          releaseHosts();
+        };
+      }
+      return () => {
+        subscribers.delete(listener);
+        terminalSubscribers.delete(listener);
+        if (terminalSubscribers.size === 0 && releaseTerminals) {
+          releaseTerminals();
+          releaseTerminals = null;
+        }
+        if (subscribers.size === 0 && release) {
+          release();
+          release = null;
+          previousProjections = [];
+          previousTerminals = emptyTerminals;
+          previousTerminalErrors = undefined;
+          snapshot = { workspaces: [], agents: [], projects: [], terminals: emptyTerminals };
+        }
+      };
+    },
+    getSnapshot,
+    getWorkspace(reference) {
+      const ref =
+        typeof reference === "string" && serverId
+          ? entityRefs.workspace(serverId, reference)
+          : reference;
+      if (typeof ref === "string") return null;
+      return projectHost(ref.hostId)?.workspaceById.get(ref.id) ?? null;
+    },
+    getAgent(reference) {
+      const ref =
+        typeof reference === "string" && serverId
+          ? entityRefs.agent(serverId, reference)
+          : reference;
+      if (typeof ref === "string") return null;
+      const projected = projectHost(ref.hostId)?.agentById.get(ref.id);
+      if (projected) return projected;
+      const session = useSessionStore.getState().sessions[ref.hostId];
+      const detail = session?.agents.get(ref.id) ?? session?.agentDetails.get(ref.id);
+      const workspaceId = normalizeWorkspaceOpaqueId(detail?.workspaceId);
+      return detail && workspaceId ? createPluginAgentSnapshot(detail, workspaceId) : null;
+    },
+    getProject: (ref) => projectHost(ref.hostId)?.projectById.get(ref.id) ?? null,
+    getTerminal(ref) {
+      const error = terminals.getErrors?.().get(ref.hostId);
+      if (error) throw error;
+      return terminals.getSnapshot().find((terminal) => terminal.ref === ref) ?? null;
     },
   };
 }
diff --git a/packages/app/src/plugins/client-state/terminals.ts b/packages/app/src/plugins/client-state/terminals.ts
new file mode 100644
index 0000000000..6b2630d7e7
--- /dev/null
+++ b/packages/app/src/plugins/client-state/terminals.ts
@@ -0,0 +1,154 @@
+import type { PluginTerminalSnapshot } from "@getpaseo/plugin";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { TerminalsChanged } from "@getpaseo/protocol/messages";
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { entityRefs } from "./refs";
+import type { PluginTerminalsSource } from "./source";
+
+interface TerminalHost {
+  serverId: string;
+  client: DaemonClient;
+  epoch: number;
+}
+export interface TerminalHostsSource {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): readonly TerminalHost[];
+}
+interface Observation {
+  client: DaemonClient;
+  epoch: number;
+  items: readonly PluginTerminalSnapshot[];
+  release(): void;
+}
+
+/** One owned observation per connected host, shared by every plugin surface. */
+export function createPluginTerminalsSource(hosts: TerminalHostsSource): PluginTerminalsSource {
+  const observations = new Map<string, Observation>();
+  const listeners = new Set<() => void>();
+  let snapshot: readonly PluginTerminalSnapshot[] = Object.freeze([]);
+  let errors: ReadonlyMap<string, Error> = new Map();
+  let releaseHosts: (() => void) | null = null;
+  function publish() {
+    const next = [...observations.values()].flatMap((item) => item.items);
+    if (next.length !== snapshot.length || next.some((item, index) => item !== snapshot[index]))
+      snapshot = Object.freeze(next);
+    for (const listener of listeners) listener();
+  }
+  function receive(hostId: string, observation: Observation, payload: TerminalsChanged["payload"]) {
+    if (observations.get(hostId) !== observation) return;
+    const previous = new Map(observation.items.map((item) => [item.ref.id, item]));
+    observation.items = Object.freeze(
+      payload.terminals.flatMap((terminal) => {
+        // Host-wide observation includes unowned legacy terminals. Sidebar navigation needs a workspace.
+        if (!terminal.workspaceId) return [];
+        const ref = entityRefs.terminal(hostId, terminal.id);
+        const workspace = entityRefs.workspace(hostId, terminal.workspaceId);
+        const title = terminal.title ?? terminal.name;
+        const createdAt = terminal.createdAt ?? null;
+        const isScript = terminal.isScript === true;
+        const cached = previous.get(terminal.id);
+        if (
+          cached &&
+          cached.workspace === workspace &&
+          cached.title === title &&
+          cached.createdAt === createdAt &&
+          cached.isScript === isScript
+        )
+          return [cached];
+        return [Object.freeze({ ref, hostId, workspace, title, createdAt, isScript })];
+      }),
+    );
+    errors = new Map([...errors].filter(([id]) => id !== hostId));
+    publish();
+  }
+  function reconcile() {
+    const active = new Map(hosts.getSnapshot().map((host) => [host.serverId, host]));
+    for (const [id, observation] of observations) {
+      if (
+        active.get(id)?.client !== observation.client ||
+        active.get(id)?.epoch !== observation.epoch
+      ) {
+        observations.delete(id);
+        observation.release();
+      }
+    }
+    errors = new Map([...errors].filter(([id]) => active.has(id)));
+    for (const [hostId, { client, epoch }] of active) {
+      if (observations.has(hostId)) continue;
+      const observation: Observation = { client, epoch, items: [], release() {} };
+      observations.set(hostId, observation);
+      try {
+        // The SDK owns the capability gate; a failed host is reported only to terminal readers.
+        const subscription = client.observeTerminals({});
+        const unsubscribe = subscription.subscribe({
+          snapshot: (payload) => receive(hostId, observation, payload),
+          update: (message) => {
+            if (message.type === "terminals_changed") receive(hostId, observation, message.payload);
+          },
+          error: (error) => {
+            if (observations.get(hostId) !== observation) return;
+            errors = new Map(errors).set(
+              hostId,
+              error instanceof Error ? error : new Error(String(error)),
+            );
+            publish();
+          },
+        });
+        void subscription.ready.catch(() => {}); // Observer owns error delivery.
+        observation.release = () => {
+          unsubscribe();
+          void subscription.release().catch(() => {});
+        };
+      } catch (error) {
+        errors = new Map(errors).set(
+          hostId,
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    }
+    publish();
+  }
+  return {
+    getSnapshot: () => snapshot,
+    getErrors: () => errors,
+    subscribe(listener) {
+      listeners.add(listener);
+      if (!releaseHosts) {
+        releaseHosts = hosts.subscribe(reconcile);
+        reconcile();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size && releaseHosts) {
+          releaseHosts();
+          releaseHosts = null;
+          for (const observation of observations.values()) observation.release();
+          observations.clear();
+          snapshot = Object.freeze([]);
+          errors = new Map();
+        }
+      };
+    },
+  };
+}
+
+export const pluginTerminals = createPluginTerminalsSource({
+  getSnapshot() {
+    const runtime = getHostRuntimeStore();
+    return runtime.getHosts().flatMap((host) => {
+      const state = runtime.getSnapshot(host.serverId);
+      return state?.connectionStatus === "online" && state.client
+        ? [{ serverId: host.serverId, client: state.client, epoch: state.connectionEpoch }]
+        : [];
+    });
+  },
+  subscribe(listener) {
+    const runtime = getHostRuntimeStore();
+    const releaseRuntime = runtime.subscribeAll(listener);
+    const releaseHosts = runtime.subscribeHostList(listener);
+    return () => {
+      releaseRuntime();
+      releaseHosts();
+    };
+  },
+});
diff --git a/packages/app/src/plugins/command-center/contributions.test.ts b/packages/app/src/plugins/command-center/contributions.test.ts
index e70304b883..95e739d50b 100644
--- a/packages/app/src/plugins/command-center/contributions.test.ts
+++ b/packages/app/src/plugins/command-center/contributions.test.ts
@@ -13,7 +13,20 @@ import { z } from "zod";
 import type { InstalledPlugin } from "../types";
 import { buildPluginCommandCenterContributions } from "./contributions";
 
+import { entityRefs } from "../client-state/refs";
 const workspace: PluginWorkspaceSnapshot = {
+  ref: entityRefs.workspace("host-1", "workspace-1"),
+  hostId: "host-1",
+  project: entityRefs.project("host-1", "project-1"),
+  pinnedAt: null,
+  labels: [],
+  background: false,
+  branch: null,
+  createdAt: null,
+  lastPromptAt: null,
+  parentAgent: null,
+  indicator: "running",
+  indicatorLabel: "Running",
   id: "workspace-1",
   projectId: "project-1",
   projectDisplayName: "Paseo",
@@ -30,6 +43,10 @@ const workspace: PluginWorkspaceSnapshot = {
 };
 
 const agent: PluginAgentSnapshot = {
+  ref: entityRefs.agent("host-1", "agent-1"),
+  hostId: "host-1",
+  workspace: workspace.ref,
+  parentAgent: null,
   id: "agent-1",
   workspaceId: workspace.id,
   provider: "codex",
@@ -46,6 +63,7 @@ const agent: PluginAgentSnapshot = {
   attentionReason: null,
   parentAgentId: null,
   labels: {},
+  metadata: {},
 };
 
 const inspect = defineRpc({
@@ -71,6 +89,9 @@ function plugin(onAgentSelect: AgentCommandItem["onSelect"]): InstalledPlugin {
         clientType: "cli",
       }),
     ),
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     invoke: async (method: string, input: unknown) => {
       expect(method).toBe("review.inspect");
       return { value: inspect.input.parse(input).value + 1 };
@@ -79,9 +100,12 @@ function plugin(onAgentSelect: AgentCommandItem["onSelect"]): InstalledPlugin {
     cleanup: () => {},
     settingsScreens: [],
     surfaces: [{ id: "main", title: "Main", Component: () => null }],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [
       {
         id: "details",
@@ -128,6 +152,15 @@ function stateSource() {
     subscribe() {
       return () => {};
     },
+    getSnapshot() {
+      return { workspaces: [workspace], agents: [agent], projects: [], terminals: [] };
+    },
+    getProject() {
+      return null;
+    },
+    getTerminal() {
+      return null;
+    },
     getWorkspace(id: string) {
       return id === workspace.id ? workspace : null;
     },
diff --git a/packages/app/src/plugins/command-center/registration.tsx b/packages/app/src/plugins/command-center/registration.tsx
index faf3b9215f..9686aab731 100644
--- a/packages/app/src/plugins/command-center/registration.tsx
+++ b/packages/app/src/plugins/command-center/registration.tsx
@@ -1,5 +1,5 @@
 import { usePathname } from "expo-router";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { useCommandCenterActions } from "@/command-center/provider";
 import { useToast } from "@/contexts/toast-context";
 import { useHostRuntimeClient } from "@/runtime/host-runtime";
@@ -9,6 +9,7 @@ import { useWorkspaceExists } from "@/stores/session-store-hooks";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
 import { normalizeWorkspaceOpaqueId } from "@/utils/workspace-identity";
 import { createPluginClientStateSource } from "../client-state/source";
+import { publishFocusedAgent } from "../focused-agent";
 import { hostIdFromPathname } from "../routes";
 import { useInstalledPlugins } from "../registry";
 import { buildPluginCommandCenterContributions } from "./contributions";
@@ -37,6 +38,15 @@ export function PluginCommandCenterActions() {
       normalizeWorkspaceOpaqueId(agent?.workspaceId) === normalizeWorkspaceOpaqueId(workspaceId)
     );
   });
+  const handedAgentId = agentExists ? focusedAgentId : null;
+  // The agent a plugin's `{ focused: true }` composer names is the one handed to agent items.
+  // Known limit: this publishes in an effect, so a command that runs on the first commit after a
+  // route change can still see the previous route's agent. Publishing from a shared
+  // navigation/focus context would remove the gap.
+  useEffect(() => {
+    publishFocusedAgent(serverId && handedAgentId ? { serverId, agentId: handedAgentId } : null);
+    return () => publishFocusedAgent(null);
+  }, [handedAgentId, serverId]);
   const client = useHostRuntimeClient(serverId ?? "");
   const installed = useInstalledPlugins();
   const plugins = useMemo(
@@ -54,23 +64,13 @@ export function PluginCommandCenterActions() {
       plugins,
       state: stateSource,
       workspaceId: workspaceExists ? workspaceId : null,
-      agentId: agentExists ? focusedAgentId : null,
+      agentId: handedAgentId,
       navigation: createPluginNavigation({ serverId, workspaceId }),
       reportError(error) {
         toast.error(error instanceof Error ? error.message : String(error));
       },
     });
-  }, [
-    agentExists,
-    client,
-    focusedAgentId,
-    plugins,
-    serverId,
-    stateSource,
-    toast,
-    workspaceExists,
-    workspaceId,
-  ]);
+  }, [client, handedAgentId, plugins, serverId, stateSource, toast, workspaceExists, workspaceId]);
 
   useCommandCenterActions({
     sourceId: serverId ? `plugins:${serverId}` : "plugins",
diff --git a/packages/app/src/plugins/composer-items/index.tsx b/packages/app/src/plugins/composer-items/index.tsx
new file mode 100644
index 0000000000..6689018456
--- /dev/null
+++ b/packages/app/src/plugins/composer-items/index.tsx
@@ -0,0 +1,93 @@
+import { useMemo, useSyncExternalStore } from "react";
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { PluginComposerProvider } from "@getpaseo/plugin/client/host";
+import { withUnistyles } from "react-native-unistyles";
+import {
+  ComposerControlSurfaceProvider,
+  type ComposerControlSurface,
+} from "@/composer/agent-controls/composer-control";
+import { useComposerModel } from "@/composer/model";
+import { PluginItemList, pluginThemeMapping, usePluginItemHost } from "../item-host";
+import { PluginEnvironmentProvider } from "../popover";
+import { useInstalledPlugins } from "../registry";
+import type { InstalledPlugin } from "../types";
+import { toPluginComposer } from "./model";
+
+function useServerPlugins(serverId: string | null): InstalledPlugin[] {
+  const installed = useInstalledPlugins();
+  return useMemo(
+    () =>
+      serverId === null
+        ? []
+        : installed.filter(
+            (plugin) => plugin.serverId === serverId && plugin.composerItems.length > 0,
+          ),
+    [installed, serverId],
+  );
+}
+
+/** How many composer items the host's plugins registered, whether or not each renders anything. */
+export function usePluginComposerItemCount(serverId: string | null): number {
+  const plugins = useServerPlugins(serverId);
+  return plugins.reduce((count, plugin) => count + plugin.composerItems.length, 0);
+}
+
+/**
+ * The host's plugin composer items. They read and command the composer they are mounted in, so
+ * they render only where a composer provides its input and agent.
+ */
+export function PluginComposerItems({
+  serverId,
+  surface,
+}: {
+  serverId: string | null;
+  surface: ComposerControlSurface;
+}) {
+  const plugins = useServerPlugins(serverId);
+  if (serverId === null || plugins.length === 0) return null;
+  return (
+    <ComposerControlSurfaceProvider value={surface}>
+      {plugins.map((plugin) => (
+        <ThemedPluginComposerItems key={plugin.id} plugin={plugin} uniProps={pluginThemeMapping} />
+      ))}
+    </ComposerControlSurfaceProvider>
+  );
+}
+
+function PluginComposerItemsHost({
+  plugin,
+  theme,
+}: {
+  plugin: InstalledPlugin;
+  theme: PluginHostProps["theme"];
+}) {
+  const model = useComposerModel();
+  const { environment, props } = usePluginItemHost(plugin, theme);
+  const state = useSyncExternalStore(
+    model?.subscribe ?? subscribeNothing,
+    model ? model.getState : noState,
+    model ? model.getState : noState,
+  );
+  const composer = useMemo(
+    () => (model && state ? toPluginComposer({ plugin, model, state }) : null),
+    [model, plugin, state],
+  );
+  if (!composer) return null;
+  return (
+    <PluginEnvironmentProvider environment={environment}>
+      <PluginComposerProvider composer={composer}>
+        <PluginItemList plugin={plugin} items={plugin.composerItems} props={props} />
+      </PluginComposerProvider>
+    </PluginEnvironmentProvider>
+  );
+}
+
+const ThemedPluginComposerItems = withUnistyles(PluginComposerItemsHost);
+
+function subscribeNothing() {
+  return () => undefined;
+}
+
+function noState(): null {
+  return null;
+}
diff --git a/packages/app/src/plugins/composer-items/model.test.ts b/packages/app/src/plugins/composer-items/model.test.ts
new file mode 100644
index 0000000000..234e06ed90
--- /dev/null
+++ b/packages/app/src/plugins/composer-items/model.test.ts
@@ -0,0 +1,355 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { PluginTranslationRuntime } from "@getpaseo/plugin/client/host";
+import { QueryClient } from "@tanstack/react-query";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+import type { UserComposerAttachment } from "@/attachments/types";
+import { composerModelFromHalves } from "@/composer/halves-model";
+import type { ComposerAgent, ComposerInput } from "@/composer/session";
+import {
+  setCommandCenterFocusRestoreElement,
+  takeCommandCenterFocusRestoreElement,
+} from "@/utils/command-center-focus-restore";
+import type { InstalledPlugin } from "../types";
+import { toPluginComposer } from "./model";
+
+function installed(): InstalledPlugin {
+  return {
+    id: "review",
+    serverId: "host-1",
+    clientBundle: "bundle",
+    lifetime: new AbortController(),
+    locale: "en",
+    i18n: new PluginTranslationRuntime({ getLocale: () => "en", subscribe: () => () => {} }),
+    queryClient: new QueryClient(),
+    paseo: {} as InstalledPlugin["paseo"],
+    invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
+    cleanup: () => {},
+    settingsScreens: [],
+    surfaces: [],
+    sidebarItems: { header: [], footer: [] },
+    legacySidebarItems: [],
+    sidebarViews: [],
+    filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
+    workspacePanels: [],
+    commandCenterItems: [],
+    clientSlashCommands: [],
+    attachmentSources: [
+      {
+        id: "issues",
+        title: "Issues",
+        pickerTitle: "Issues",
+        searchPlaceholder: "Search issues",
+        icon: "Bug",
+        search: defineRpc({
+          name: "issues.search",
+          input: z.object({}),
+          output: z.array(z.object({})),
+        }),
+      },
+    ],
+    themes: [],
+    timelineTransformers: [],
+    timelineRenderers: [],
+  };
+}
+
+const issue = {
+  id: "ISS-1",
+  identifier: "ISS-1",
+  title: "Fix it",
+  url: "https://example.com/ISS-1",
+  text: "Fix it",
+  resourceType: "issue",
+};
+
+function fakeAgent(context: ComposerAgent["context"], locked = false) {
+  const calls: string[] = [];
+  const agent: ComposerAgent = {
+    context,
+    locked,
+    isLocked: () => locked,
+    provider: "claude",
+    model: "sonnet",
+    mode: "default",
+    thinking: null,
+    options: { effort: "high" },
+    metadata: { flag: true },
+    // A running agent keeps its provider, as the real adapter does.
+    setProvider: async (provider) => {
+      if (context === "agent") throw new Error("A running agent cannot change provider.");
+      calls.push(`provider:${provider}`);
+    },
+    setModel: async (model) => void calls.push(`model:${model}`),
+    setMode: async (mode) => void calls.push(`mode:${mode}`),
+    setThinking: async (thinking) => void calls.push(`thinking:${thinking}`),
+    setOptions: async (patch) => void calls.push(`options:${JSON.stringify(patch)}`),
+    setMetadata: async (patch: Record<string, JsonValue>) =>
+      void calls.push(`metadata:${JSON.stringify(patch)}`),
+  };
+  return { agent, calls };
+}
+
+function fakeInput(initial: UserComposerAttachment[] = [], locked = false) {
+  const state = { text: "", attachments: initial };
+  const view = { revealed: true, focused: [] as unknown[] };
+  const input: ComposerInput = {
+    locked,
+    isLocked: () => locked,
+    isLive: () => true,
+    revealed: true,
+    isRevealed: () => view.revealed,
+    focus: async (options) => {
+      view.focused.push(options);
+    },
+    textSource: { getSnapshot: () => state.text, subscribe: () => () => {} },
+    setText: (text) => {
+      state.text = text;
+    },
+    insertText: (text) => {
+      state.text += text;
+    },
+    get attachments() {
+      return state.attachments;
+    },
+    changeAttachments: (updater) => {
+      state.attachments = updater(state.attachments);
+    },
+  };
+  return { input, state, view };
+}
+
+function compose(agent: ComposerAgent, input: ComposerInput) {
+  const model = composerModelFromHalves({ agent, input });
+  return toPluginComposer({ plugin: installed(), model, state: model.getState() });
+}
+
+describe("toPluginComposer", () => {
+  it("reads the agent the composer configures and the context it sits in", () => {
+    const { agent } = fakeAgent("new-workspace");
+    const { input, state } = fakeInput();
+    state.text = "hello";
+    const composer = compose(agent, input);
+    expect(composer.context).toBe("new-workspace");
+    expect(composer.prompt).toBe("hello");
+    expect(composer.agent).toEqual({
+      provider: "claude",
+      model: "sonnet",
+      mode: "default",
+      thinking: null,
+      options: { effort: "high" },
+      metadata: { flag: true },
+    });
+  });
+
+  it.each(["agent", "draft"] as const)(
+    "sends every command to the %s composer's agent",
+    async (context) => {
+      const { agent, calls } = fakeAgent(context);
+      const { input } = fakeInput();
+      const composer = compose(agent, input);
+      await composer.setModel("gpt");
+      await composer.setMode("plan");
+      await composer.setThinking("high");
+      await composer.setOptions({ effort: "low" });
+      await composer.setMetadata({ flag: null });
+      expect(calls).toEqual([
+        "model:gpt",
+        "mode:plan",
+        "thinking:high",
+        'options:{"effort":"low"}',
+        'metadata:{"flag":null}',
+      ]);
+    },
+  );
+
+  it("lets a draft change provider and tells a running agent it cannot", async () => {
+    const { input } = fakeInput();
+    const draft = fakeAgent("draft");
+    await compose(draft.agent, input).setProvider("codex");
+    expect(draft.calls).toEqual(["provider:codex"]);
+
+    const running = fakeAgent("agent");
+    await expect(compose(running.agent, input).setProvider("codex")).rejects.toThrow(
+      "A running agent cannot change provider.",
+    );
+    expect(running.calls).toEqual([]);
+  });
+
+  it("changes the prompt and inserts at the cursor", () => {
+    const { agent } = fakeAgent("draft");
+    const { input, state } = fakeInput();
+    const composer = compose(agent, input);
+    composer.setPrompt("a");
+    composer.insertText("b");
+    expect(state.text).toBe("ab");
+  });
+
+  it("refuses every prompt and agent command while the composer is locked", async () => {
+    const { agent, calls } = fakeAgent("new-workspace", true);
+    const { input, state } = fakeInput([], true);
+    const composer = compose(agent, input);
+
+    expect(() => composer.setPrompt("a")).toThrow("The composer is locked");
+    expect(() => composer.insertText("b")).toThrow("The composer is locked");
+    expect(() => composer.addAttachment({ sourceId: "issues", item: issue })).toThrow(
+      "The composer is locked",
+    );
+    await expect(composer.setProvider("codex")).rejects.toThrow("The composer is locked");
+    await expect(composer.setModel("gpt")).rejects.toThrow("The composer is locked");
+    await expect(composer.setMode("plan")).rejects.toThrow("The composer is locked");
+    await expect(composer.setThinking("high")).rejects.toThrow("The composer is locked");
+    await expect(composer.setOptions({ effort: "low" })).rejects.toThrow("The composer is locked");
+    await expect(composer.setMetadata({ flag: null })).rejects.toThrow("The composer is locked");
+    expect(state.text).toBe("");
+    expect(calls).toEqual([]);
+  });
+
+  it("refuses a command a plugin kept from before the composer locked", async () => {
+    const { agent } = fakeAgent("new-workspace");
+    const { input } = fakeInput();
+    const composer = compose(agent, input);
+
+    // The plugin's action was awaiting an RPC when the user submitted.
+    const lock = { locked: true };
+    agent.isLocked = () => lock.locked;
+    input.isLocked = () => lock.locked;
+
+    expect(() => composer.insertText("late")).toThrow("The composer is locked");
+    expect(() => composer.addAttachment({ sourceId: "issues", item: issue })).toThrow(
+      "The composer is locked",
+    );
+    expect(() => composer.removeAttachment({ sourceId: "issues", itemId: issue.id })).toThrow(
+      "The composer is locked",
+    );
+    await expect(composer.setOptions({ effort: "low" })).rejects.toThrow("The composer is locked");
+  });
+
+  it("focuses the input of the draft composer on screen, with the selection asked for", async () => {
+    const { agent } = fakeAgent("draft");
+    const { input, view } = fakeInput();
+    const composer = compose(agent, input);
+
+    await composer.focus({ selection: { start: 0, end: 4 } });
+
+    expect(view.focused).toEqual([{ selection: { start: 0, end: 4 } }]);
+  });
+
+  it("rejects focus on a draft composer that is not on screen, leaving the user where they are", async () => {
+    const { agent } = fakeAgent("draft");
+    const { input, view } = fakeInput();
+    view.revealed = false;
+    const composer = compose(agent, input);
+
+    await expect(composer.focus()).rejects.toThrow("not on screen");
+    expect(view.focused).toEqual([]);
+  });
+
+  it("focuses while the composer is locked, since the cursor changes nothing it holds", async () => {
+    const { agent } = fakeAgent("new-workspace");
+    const { input, view } = fakeInput([], true);
+    const composer = compose(agent, input);
+
+    await composer.focus();
+
+    expect(view.focused).toEqual([undefined]);
+  });
+
+  it("keeps the Command Center from taking focus back when it closes", async () => {
+    const { agent } = fakeAgent("draft");
+    const { input } = fakeInput();
+    const composer = compose(agent, input);
+    setCommandCenterFocusRestoreElement({} as HTMLElement);
+
+    await composer.focus();
+
+    expect(takeCommandCenterFocusRestoreElement()).toBeNull();
+  });
+
+  it("hands out options and metadata a plugin cannot change", () => {
+    const { agent } = fakeAgent("draft");
+    agent.metadata = { nested: { list: [1] } };
+    const { input } = fakeInput();
+    const composer = compose(agent, input);
+
+    expect(Object.isFrozen(composer.agent.options)).toBe(true);
+    expect(Object.isFrozen(composer.agent.metadata)).toBe(true);
+    expect(Object.isFrozen((composer.agent.metadata as { nested: object }).nested)).toBe(true);
+    expect(agent.metadata).toEqual({ nested: { list: [1] } });
+    expect(Object.isFrozen(agent.metadata)).toBe(false);
+  });
+
+  it("hands out attachment items a plugin cannot change", () => {
+    const { agent } = fakeAgent("draft");
+    const { input, state } = fakeInput();
+    const handedIn = { ...issue };
+    compose(agent, input).addAttachment({ sourceId: "issues", item: handedIn });
+    // The draft keeps its own copy, so the object the plugin handed in is not the draft's.
+    handedIn.title = "Changed after adding";
+
+    const [attachment] = compose(agent, input).attachments;
+
+    expect(attachment.item).toEqual(issue);
+    expect(Object.isFrozen(attachment.item)).toBe(true);
+    const [stored] = state.attachments;
+    expect(stored.kind === "plugin_resource" && Object.isFrozen(stored.item)).toBe(false);
+  });
+
+  it("hands the composer its own copy of the options and metadata a plugin sets", async () => {
+    const { agent } = fakeAgent("draft");
+    const kept: Record<string, unknown> = {};
+    agent.setOptions = async (patch) => void (kept.options = patch);
+    agent.setMetadata = async (patch) => void (kept.metadata = patch);
+    const { input } = fakeInput();
+    const composer = compose(agent, input);
+
+    const sandbox = { mode: "read-only" };
+    const linked = { id: "ISS-1" };
+    await composer.setOptions({ sandbox });
+    await composer.setMetadata({ linked });
+    sandbox.mode = "full-access";
+    linked.id = "ISS-2";
+
+    expect(kept.options).toEqual({ sandbox: { mode: "read-only" } });
+    expect(kept.metadata).toEqual({ linked: { id: "ISS-1" } });
+  });
+
+  it("adds and removes the plugin's own attachments only", () => {
+    const { agent } = fakeAgent("agent");
+    const other: UserComposerAttachment = {
+      kind: "plugin_resource",
+      pluginId: "other",
+      sourceId: "issues",
+      sourceTitle: "Issues",
+      sourceIcon: "Bug",
+      item: issue,
+    };
+    const { input, state } = fakeInput([other]);
+    const composer = compose(agent, input);
+
+    composer.addAttachment({ sourceId: "issues", item: issue });
+    composer.addAttachment({ sourceId: "issues", item: issue });
+    expect(state.attachments).toHaveLength(2);
+
+    const next = compose(agent, input);
+    expect(next.attachments).toEqual([{ sourceId: "issues", item: issue }]);
+
+    composer.removeAttachment({ sourceId: "issues", itemId: "ISS-1" });
+    expect(state.attachments).toEqual([other]);
+  });
+
+  it("rejects an attachment from a source the plugin did not register", () => {
+    const { agent } = fakeAgent("agent");
+    const { input } = fakeInput();
+    const composer = compose(agent, input);
+    expect(() => composer.addAttachment({ sourceId: "nope", item: issue })).toThrow(
+      "Unknown attachment source: nope",
+    );
+  });
+});
diff --git a/packages/app/src/plugins/composer-items/model.ts b/packages/app/src/plugins/composer-items/model.ts
new file mode 100644
index 0000000000..15de534ff3
--- /dev/null
+++ b/packages/app/src/plugins/composer-items/model.ts
@@ -0,0 +1,88 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginComposer } from "@getpaseo/plugin/client";
+import type { UserComposerAttachment } from "@/attachments/types";
+import type { ComposerModel, ComposerState } from "@/composer/model";
+import type { InstalledPlugin } from "../types";
+import { createPluginResourceAttachment } from "../attachments/model";
+import { cloneAndFreeze, ownCopy } from "../freeze";
+import { clearCommandCenterFocusRestoreElement } from "@/utils/command-center-focus-restore";
+
+function isPluginAttachment(
+  attachment: UserComposerAttachment,
+  pluginId: string,
+  sourceId: string,
+  itemId?: string,
+): boolean {
+  return (
+    attachment.kind === "plugin_resource" &&
+    attachment.pluginId === pluginId &&
+    attachment.sourceId === sourceId &&
+    (itemId === undefined || attachment.item.id === itemId)
+  );
+}
+
+/**
+ * What a plugin sees of a composer. Reads are `state`; every command goes to the model, so the
+ * mounted composer, a panel's handle and a Command Center item all reach the same one.
+ */
+export function toPluginComposer(input: {
+  plugin: InstalledPlugin;
+  model: ComposerModel;
+  state: ComposerState;
+}): PluginComposer {
+  const { plugin, model, state } = input;
+  return {
+    context: state.context,
+    prompt: state.prompt,
+    attachments: state.attachments.flatMap((attachment) =>
+      attachment.kind === "plugin_resource" && attachment.pluginId === plugin.id
+        ? [{ sourceId: attachment.sourceId, item: cloneAndFreeze(attachment.item) }]
+        : [],
+    ),
+    // Provider options are JSON on the wire.
+    agent: {
+      provider: state.provider,
+      model: state.model,
+      mode: state.mode,
+      thinking: state.thinking,
+      options: cloneAndFreeze(state.options as Record<string, JsonValue>),
+      metadata: cloneAndFreeze(state.metadata),
+    },
+    setPrompt: (text) => model.setPrompt(text),
+    insertText: (text) => model.insertText(text),
+    focus(options) {
+      // The Command Center, which may have run this command, gives focus back when it closes.
+      clearCommandCenterFocusRestoreElement();
+      return model.focus(options);
+    },
+    addAttachment({ sourceId, item }) {
+      const source = plugin.attachmentSources.find((candidate) => candidate.id === sourceId);
+      if (!source) throw new Error(`Unknown attachment source: ${sourceId}`);
+      const attachment = createPluginResourceAttachment(
+        {
+          pluginId: plugin.id,
+          sourceId,
+          sourceTitle: plugin.i18n.resolve(source.title, plugin.locale),
+          sourceIcon: source.icon,
+        },
+        ownCopy(item),
+      );
+      model.changeAttachments((current) =>
+        current.some((candidate) => isPluginAttachment(candidate, plugin.id, sourceId, item.id))
+          ? current
+          : [...current, attachment],
+      );
+    },
+    removeAttachment({ sourceId, itemId }) {
+      model.changeAttachments((current) =>
+        current.filter((candidate) => !isPluginAttachment(candidate, plugin.id, sourceId, itemId)),
+      );
+    },
+    setProvider: (provider) => model.setProvider(provider),
+    setModel: (modelId) => model.setModel(modelId),
+    setMode: (modeId) => model.setMode(modeId),
+    setThinking: (thinkingOptionId) => model.setThinking(thinkingOptionId),
+    setOptions: (patch) => model.setOptions(ownCopy(patch)),
+    setMetadata: (patch) => model.setMetadata(ownCopy(patch)),
+  };
+}
diff --git a/packages/app/src/plugins/composer-items/source.test.ts b/packages/app/src/plugins/composer-items/source.test.ts
new file mode 100644
index 0000000000..a9be4012d0
--- /dev/null
+++ b/packages/app/src/plugins/composer-items/source.test.ts
@@ -0,0 +1,393 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { createPaseoApi } from "@getpaseo/client";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { PluginTranslationRuntime } from "@getpaseo/plugin/client/host";
+import { QueryClient } from "@tanstack/react-query";
+import { z } from "zod";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { providersSnapshotQueryRoot } from "@/data/providers-snapshot";
+import { queryClient } from "@/data/query-client";
+import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
+import { useDraftStore } from "@/stores/draft-store";
+import { useSessionStore, type Agent, type WorkspaceDescriptor } from "@/stores/session-store";
+import { createPluginClientStateSource } from "../client-state/source";
+import { buildPluginCommandCenterContributions } from "../command-center/contributions";
+import { publishFocusedAgent } from "../focused-agent";
+import type { InstalledPlugin } from "../types";
+import { pluginComposersSource } from "./source";
+
+const serverId = "host-1";
+
+function plugin(): InstalledPlugin {
+  return {
+    id: "review",
+    serverId,
+    clientBundle: "bundle",
+    lifetime: new AbortController(),
+    locale: "en",
+    i18n: new PluginTranslationRuntime({ getLocale: () => "en", subscribe: () => () => {} }),
+    queryClient: new QueryClient(),
+    paseo: createPaseoApi(
+      new DaemonClient({
+        url: "ws://127.0.0.1:1",
+        clientId: "plugin-composer-test",
+        clientType: "cli",
+      }),
+    ),
+    invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
+    cleanup: () => {},
+    settingsScreens: [],
+    surfaces: [],
+    sidebarItems: { header: [], footer: [] },
+    legacySidebarItems: [],
+    sidebarViews: [],
+    filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
+    workspacePanels: [],
+    commandCenterItems: [],
+    clientSlashCommands: [],
+    attachmentSources: [
+      {
+        id: "issues",
+        title: "Issues",
+        pickerTitle: "Issues",
+        searchPlaceholder: "Search",
+        icon: "Bug",
+        search: defineRpc({
+          name: "issues.search",
+          input: z.object({}),
+          output: z.array(z.object({})),
+        }),
+      },
+    ],
+    themes: [],
+    timelineTransformers: [],
+    timelineRenderers: [],
+  };
+}
+
+function agent(id: string, archivedAt: Date | null = null): Agent {
+  return {
+    serverId,
+    id,
+    provider: "claude",
+    status: "idle",
+    turn: { phase: "idle", cancellationRequestId: null },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastUserMessageAt: null,
+    lastActivityAt: new Date(),
+    capabilities: {
+      supportsStreaming: true,
+      supportsSessionPersistence: true,
+      supportsDynamicModes: true,
+      supportsMcpServers: true,
+      supportsReasoningStream: true,
+      supportsToolInvocations: true,
+    },
+    currentModeId: "default",
+    availableModes: [],
+    pendingPermissions: [],
+    persistence: null,
+    title: null,
+    cwd: "/repo",
+    workspaceId: "workspace-1",
+    model: null,
+    parentAgentId: null,
+    labels: {},
+    archivedAt,
+  };
+}
+
+beforeEach(() => {
+  useDraftStore.setState({ drafts: {}, textReplacementRequestByDraftKey: {} });
+  const store = useSessionStore.getState();
+  store.initializeSession(serverId, {} as never);
+  store.setAgents(
+    serverId,
+    new Map([
+      ["agent-1", agent("agent-1")],
+      ["agent-2", agent("agent-2", new Date())],
+    ]),
+  );
+});
+
+afterEach(() => {
+  publishFocusedAgent(null);
+  useSessionStore.getState().clearSession(serverId);
+});
+
+describe("a plugin's composers by reference", () => {
+  it("names a running agent by id, and nothing for an unknown or archived one", () => {
+    const source = pluginComposersSource(plugin());
+    expect(source.resolve({ agentId: "agent-1" })).toHaveLength(1);
+    expect(source.resolve({ agentId: "nope" })).toEqual([]);
+    expect(source.resolve({ agentId: "agent-2" })).toEqual([]);
+  });
+
+  it("follows the agent the Command Center hands out, and is empty when there is none", () => {
+    const source = pluginComposersSource(plugin());
+    let notified = 0;
+    const stop = source.subscribe({ focused: true }, () => {
+      notified += 1;
+    });
+    expect(source.resolve({ focused: true })).toEqual([]);
+
+    publishFocusedAgent({ serverId, agentId: "agent-1" });
+    const [focused] = source.resolve({ focused: true });
+    expect(focused?.context).toBe("agent");
+    expect(notified).toBeGreaterThan(0);
+
+    // Leaving the workspace for a plugin screen or New workspace publishes no agent.
+    publishFocusedAgent(null);
+    expect(source.resolve({ focused: true })).toEqual([]);
+
+    // Another host's focused agent is not this plugin's.
+    publishFocusedAgent({ serverId: "host-2", agentId: "agent-1" });
+    expect(source.resolve({ focused: true })).toEqual([]);
+    stop();
+  });
+
+  it("is not told when another component creates a query while it renders", () => {
+    const source = pluginComposersSource(plugin());
+    let notified = 0;
+    const stop = source.subscribe({ agentId: "agent-1" }, () => {
+      notified += 1;
+    });
+    // `useQuery` does this during a render, and a subscriber that updates then makes React warn
+    // that one component updated another while rendering.
+    queryClient.getQueryCache().build(queryClient, { queryKey: ["created-during-a-render"] });
+    expect(notified).toBe(0);
+    stop();
+  });
+
+  it("delivers a draft change once to each of several components watching the same agent", () => {
+    const source = pluginComposersSource(plugin());
+    const delivered = [0, 0, 0];
+    const stops: Array<() => void> = [];
+    for (const index of delivered.keys()) {
+      stops.push(source.subscribe({ agentId: "agent-1" }, () => void (delivered[index] += 1)));
+    }
+    const before = [...delivered];
+    source.resolve({ agentId: "agent-1" })[0]?.insertText("typed");
+    expect(delivered.map((count, index) => count - before[index])).toEqual([1, 1, 1]);
+    for (const stop of stops) stop();
+  });
+
+  it("returns the same array until a composer changes", () => {
+    const source = pluginComposersSource(plugin());
+    const first = source.resolve({ agentId: "agent-1" });
+    expect(source.resolve({ agentId: "agent-1" })).toBe(first);
+    first[0]?.insertText("hello");
+    const next = source.resolve({ agentId: "agent-1" });
+    expect(next).not.toBe(first);
+    expect(next[0]?.prompt).toBe("hello");
+  });
+});
+
+describe("a plugin component watching a composer by reference", () => {
+  const catalog = (defaultThinkingOptionId: string): ProviderSnapshotEntry[] => [
+    {
+      provider: "claude",
+      status: "ready",
+      enabled: true,
+      models: [
+        {
+          provider: "claude",
+          id: "opus",
+          label: "Opus",
+          isDefault: true,
+          defaultThinkingOptionId,
+          thinkingOptions: [
+            { id: "low", label: "Low" },
+            { id: "high", label: "High" },
+          ],
+        },
+      ],
+    },
+  ];
+
+  afterEach(() => {
+    queryClient.clear();
+  });
+
+  async function until(read: () => unknown, expected: unknown) {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      if (Object.is(read(), expected)) return;
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    expect(read()).toBe(expected);
+  }
+
+  function hostWithDefaultThinking(initial: string) {
+    const host = { defaultThinking: initial };
+    const client = {
+      async getProvidersSnapshot() {
+        return {
+          entries: catalog(host.defaultThinking),
+          generatedAt: "2026-11-04T10:00:00.000Z",
+          requestId: "snapshot",
+        };
+      },
+    } as unknown as DaemonClient;
+    const store = useSessionStore.getState();
+    store.clearSession(serverId);
+    store.initializeSession(serverId, client);
+    store.updateSessionServerInfo(serverId, {
+      serverId,
+      hostname: null,
+      version: null,
+      features: { providersSnapshot: true },
+    } as never);
+    store.setAgents(serverId, new Map([["agent-1", agent("agent-1")]]));
+    return host;
+  }
+
+  it("refreshes a catalog that was invalidated while nothing watched, when watching resumes", async () => {
+    const host = hostWithDefaultThinking("high");
+    const source = pluginComposersSource(plugin());
+    const stopFirst = source.subscribe({ agentId: "agent-1" }, () => {});
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "high");
+    stopFirst();
+
+    // Reconnect repair only refetches what is watched, so this catalog is invalidated and kept.
+    host.defaultThinking = "low";
+    await queryClient.invalidateQueries({ queryKey: providersSnapshotQueryRoot(serverId) });
+
+    const stopAgain = source.subscribe({ agentId: "agent-1" }, () => {});
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "low");
+    stopAgain();
+  });
+
+  it("refreshes an invalidated catalog for a command that reads once", async () => {
+    const host = hostWithDefaultThinking("high");
+    const source = pluginComposersSource(plugin());
+    const stopFirst = source.subscribe({ agentId: "agent-1" }, () => {});
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "high");
+    stopFirst();
+    host.defaultThinking = "low";
+    await queryClient.invalidateQueries({ queryKey: providersSnapshotQueryRoot(serverId) });
+
+    // A command cannot wait, so this read still shows the old catalog and starts the refresh.
+    source.resolve({ agentId: "agent-1" });
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "low");
+  });
+
+  it("sees the catalog the host changed while away once the host reconnects, with no picker open", async () => {
+    let hostDefault = "high";
+    const client = {
+      async getProvidersSnapshot() {
+        return {
+          entries: catalog(hostDefault),
+          generatedAt: "2026-11-04T10:00:00.000Z",
+          requestId: "snapshot",
+        };
+      },
+    } as unknown as DaemonClient;
+    const store = useSessionStore.getState();
+    store.clearSession(serverId);
+    store.initializeSession(serverId, client);
+    store.updateSessionServerInfo(serverId, {
+      serverId,
+      hostname: null,
+      version: null,
+      features: { providersSnapshot: true },
+    } as never);
+    store.setAgents(serverId, new Map([["agent-1", agent("agent-1")]]));
+
+    const source = pluginComposersSource(plugin());
+    const stop = source.subscribe({ agentId: "agent-1" }, () => {});
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "high");
+
+    // Reconnecting invalidates the provider catalogs, which refetches the ones something watches.
+    hostDefault = "low";
+    await queryClient.invalidateQueries({ queryKey: providersSnapshotQueryRoot(serverId) });
+
+    await until(() => source.resolve({ agentId: "agent-1" })[0]?.agent.thinking, "low");
+    stop();
+  });
+});
+
+describe("a Command Center item reaching an agent's composer by id", () => {
+  // The real client-state source reads these stores. A lookup that came back empty would make the
+  // Command Center return before calling the item, and nothing would be reported.
+  const workspace: WorkspaceDescriptor = {
+    createdAt: null,
+    lastUserMessageAt: null,
+    id: "workspace-1",
+    projectId: "project-1",
+    projectDisplayName: "Repo",
+    projectRootPath: "/repo",
+    workspaceDirectory: "/repo",
+    projectKind: "git",
+    workspaceKind: "checkout",
+    name: "Repo",
+    title: null,
+    pinnedAt: null,
+    status: "running",
+    statusEnteredAt: null,
+    archivingAt: null,
+    diffStat: null,
+    scripts: [],
+  };
+
+  function markForReview(rejection?: Error) {
+    const patches: unknown[] = [];
+    const client = {
+      async setAgentMetadata(_agentId: string, patch: unknown) {
+        patches.push(patch);
+        if (rejection) throw rejection;
+      },
+    } as unknown as DaemonClient;
+    useSessionStore.getState().clearSession(serverId);
+    useSessionStore.getState().initializeSession(serverId, client);
+    useSessionStore.getState().setAgents(serverId, new Map([["agent-1", agent("agent-1")]]));
+    useSessionStore.getState().setWorkspaces(serverId, new Map([[workspace.id, workspace]]));
+    const installed = plugin();
+    installed.commandCenterItems = [
+      {
+        id: "mark",
+        title: "Mark for review",
+        icon: "Flag",
+        context: "agent",
+        async onSelect({ agent: handed, composers }) {
+          for (const composer of composers({ agentId: handed.id })) {
+            await composer.setMetadata({ needsReview: true });
+          }
+        },
+      },
+    ];
+    const reported: unknown[] = [];
+    const [item] = buildPluginCommandCenterContributions({
+      plugins: [installed],
+      state: createPluginClientStateSource(serverId),
+      workspaceId: "workspace-1",
+      agentId: "agent-1",
+      navigation: {
+        openSettings() {},
+        openSurface() {},
+        openWorkspacePanel() {},
+        openAgentPanel() {},
+      },
+      reportError: (error) => reported.push(error),
+    });
+    return { run: item?.run, patches, reported };
+  }
+
+  it("changes the agent's metadata through the daemon", async () => {
+    const { run, patches, reported } = markForReview();
+    await run?.();
+    expect(patches).toEqual([{ needsReview: true }]);
+    expect(reported).toEqual([]);
+  });
+
+  it("reports what the daemon rejected", async () => {
+    const { run, reported } = markForReview(new Error("metadata refused"));
+    await run?.();
+    expect(reported).toEqual([new Error("metadata refused")]);
+  });
+});
diff --git a/packages/app/src/plugins/composer-items/source.ts b/packages/app/src/plugins/composer-items/source.ts
new file mode 100644
index 0000000000..12c3d8853d
--- /dev/null
+++ b/packages/app/src/plugins/composer-items/source.ts
@@ -0,0 +1,98 @@
+import type { PluginComposer, PluginComposerSelector } from "@getpaseo/plugin/client";
+import type { PluginComposersSource } from "@getpaseo/plugin/client/host";
+import { agentComposer } from "@/composer/agent-composer";
+import type { ComposerState } from "@/composer/model";
+import { useSessionStore } from "@/stores/session-store";
+import { getFocusedAgent, subscribeFocusedAgent } from "../focused-agent";
+import type { InstalledPlugin } from "../types";
+import { toPluginComposer } from "./model";
+
+const NO_COMPOSERS: readonly PluginComposer[] = Object.freeze([]);
+const sources = new WeakMap<InstalledPlugin, PluginComposersSource>();
+
+/**
+ * The composers a plugin reaches by reference: one per running agent, open in a tab or not. The
+ * same source serves `useComposers` in every surface and `composers()` in every command.
+ */
+export function pluginComposersSource(plugin: InstalledPlugin): PluginComposersSource {
+  let source = sources.get(plugin);
+  if (!source) {
+    source = createSource(plugin);
+    sources.set(plugin, source);
+  }
+  return source;
+}
+
+function createSource(plugin: InstalledPlugin): PluginComposersSource {
+  const { serverId } = plugin;
+  // Handles and result arrays are reused while nothing they read has changed, so a subscriber
+  // that re-reads on every notification renders only when its composers did change.
+  const handles = new WeakMap<ComposerState, PluginComposer>();
+  const results = new WeakMap<PluginComposer, readonly PluginComposer[]>();
+
+  function runningAgentId(agentId: string): string | null {
+    const session = useSessionStore.getState().sessions[serverId];
+    const agent = session?.agents.get(agentId) ?? session?.agentDetails.get(agentId) ?? null;
+    return agent && !agent.archivedAt ? agent.id : null;
+  }
+
+  function focusedAgentId(): string | null {
+    const focused = getFocusedAgent();
+    return focused?.serverId === serverId ? focused.agentId : null;
+  }
+
+  /** The running agent a selector names now, or null. */
+  function namedAgentId(selector: PluginComposerSelector): string | null {
+    const requested = "agentId" in selector ? selector.agentId : focusedAgentId();
+    return requested === null ? null : runningAgentId(requested);
+  }
+
+  return {
+    subscribe(selector, listener) {
+      // Watching a composer is what keeps its model catalog current, so the subscription holds
+      // the model the selector names now and moves with it as focus and agents change.
+      let held: { agentId: string; stop: () => void } | null = null;
+      function hold() {
+        const agentId = namedAgentId(selector);
+        if (held?.agentId === agentId) return;
+        held?.stop();
+        held = agentId
+          ? { agentId, stop: agentComposer(serverId, agentId).subscribe(listener) }
+          : null;
+      }
+      hold();
+      const stops = [
+        useSessionStore.subscribe(() => {
+          hold();
+          listener();
+        }),
+        subscribeFocusedAgent(() => {
+          hold();
+          listener();
+        }),
+      ];
+      return () => {
+        for (const stop of stops) stop();
+        held?.stop();
+        held = null;
+      };
+    },
+    resolve(selector: PluginComposerSelector) {
+      const agentId = namedAgentId(selector);
+      if (agentId === null) return NO_COMPOSERS;
+      const model = agentComposer(serverId, agentId);
+      const state = model.getState();
+      let composer = handles.get(state);
+      if (!composer) {
+        composer = toPluginComposer({ plugin, model, state });
+        handles.set(state, composer);
+      }
+      let result = results.get(composer);
+      if (!result) {
+        result = Object.freeze([composer]);
+        results.set(composer, result);
+      }
+      return result;
+    },
+  };
+}
diff --git a/packages/app/src/plugins/evaluate.test.ts b/packages/app/src/plugins/evaluate.test.ts
index 1aae11f63d..69ede1feed 100644
--- a/packages/app/src/plugins/evaluate.test.ts
+++ b/packages/app/src/plugins/evaluate.test.ts
@@ -55,6 +55,29 @@ describe("evaluatePluginClientBundle", () => {
     expect(active).toBe(0);
   });
 
+  it("registers sidebar views without selecting one and removes them on cleanup", async () => {
+    const plugin = evaluatePluginClientBundle(
+      "sidebar",
+      bundle(`
+      plugin.addSidebarView({ id: "workspaces", title: "Workspaces", Component() { return null; } });
+    `),
+    );
+    expect(plugin.sidebarViews.map((view) => view.id)).toEqual(["workspaces"]);
+    await plugin.cleanup();
+    expect(plugin.sidebarViews).toEqual([]);
+  });
+  it("rejects duplicate sidebar view ids", () => {
+    expect(() =>
+      evaluatePluginClientBundle(
+        "sidebar",
+        bundle(`
+      const view = { id: "workspaces", title: "Workspaces", Component() { return null; } };
+      plugin.addSidebarView(view); plugin.addSidebarView(view);
+    `),
+      ),
+    ).toThrow("Duplicate sidebar view");
+  });
+
   it("accepts memoized settings screens", () => {
     const plugin = evaluatePluginClientBundle(
       "settings",
@@ -531,6 +554,38 @@ describe("evaluatePluginClientBundle", () => {
     ).toThrow("Duplicate Command Center item: review");
   });
 
+  it("collects composer items and releases an id on removal", () => {
+    const plugin = evaluatePluginClientBundle(
+      "review",
+      bundle(`
+        function Item() { return null; }
+        const remove = plugin.addComposerItem({ id: "flag", Component: Item });
+        remove();
+        plugin.addComposerItem({ id: "flag", Component: Item });
+      `),
+    );
+    expect(plugin.composerItems.map((item) => item.id)).toEqual(["flag"]);
+  });
+
+  it("rejects duplicate and non-component composer items", () => {
+    expect(() =>
+      evaluatePluginClientBundle(
+        "review",
+        bundle(`
+          function Item() { return null; }
+          plugin.addComposerItem({ id: "flag", Component: Item });
+          plugin.addComposerItem({ id: "flag", Component: Item });
+        `),
+      ),
+    ).toThrow("Duplicate composer item: flag");
+    expect(() =>
+      evaluatePluginClientBundle(
+        "review",
+        bundle(`plugin.addComposerItem({ id: "flag", Component: "nope" })`),
+      ),
+    ).toThrow("Composer item flag is not a component");
+  });
+
   it("runs the client entry with the full runtime context", () => {
     const plugin = evaluatePluginClientBundle(
       "review",
diff --git a/packages/app/src/plugins/evaluate.ts b/packages/app/src/plugins/evaluate.ts
index ea37209f57..f3e89122dd 100644
--- a/packages/app/src/plugins/evaluate.ts
+++ b/packages/app/src/plugins/evaluate.ts
@@ -110,7 +110,9 @@ export type PluginClientRuntime = Pick<
   | "openSettings"
   | "openScreen"
   | "openSurface"
+  | "composers"
   | "openPanel"
+  | "subscribe"
   | "addComposerPill"
   | "addHeaderButton"
 > & { hosts: ReturnType<typeof createPluginHosts> };
@@ -128,9 +130,12 @@ export function runPluginClientBundle(
   const collector: Omit<EvaluatedPlugin, "id" | "cleanup"> = {
     surfaces: [],
     settingsScreens: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
@@ -140,12 +145,15 @@ export function runPluginClientBundle(
     timelineRenderers: [],
   };
   const surfaceIds = new Set<string>();
+  const sidebarViewIds = new Set<string>();
   const settingsScreenIds = new Set<string>();
   const sidebarItemIds: Record<PluginSidebarSection, Set<string>> = {
     header: new Set(),
     footer: new Set(),
   };
   const filePanelIds = new Set<string>();
+  const composerItemIds = new Set<string>();
+  const newWorkspaceItemIds = new Set<string>();
   const workspacePanelIds = new Set<string>();
   const commandCenterItemIds = new Set<string>();
   const clientSlashCommandNames = new Set<string>();
@@ -269,6 +277,46 @@ export function runPluginClientBundle(
         () => surfaceIds.delete(normalizedId),
       );
     },
+    addComposerItem(contribution) {
+      const normalizedId = requireId(contribution.id, "composer item id");
+      if (composerItemIds.has(normalizedId))
+        throw new Error(`Duplicate composer item: ${normalizedId}`);
+      if (!isComponentType(contribution.Component)) {
+        throw new Error(`Composer item ${normalizedId} is not a component`);
+      }
+      composerItemIds.add(normalizedId);
+      return register(
+        collector.composerItems,
+        { id: normalizedId, Component: contribution.Component },
+        () => composerItemIds.delete(normalizedId),
+      );
+    },
+    addNewWorkspaceItem(contribution) {
+      const normalizedId = requireId(contribution.id, "New workspace item id");
+      if (newWorkspaceItemIds.has(normalizedId))
+        throw new Error(`Duplicate New workspace item: ${normalizedId}`);
+      if (!isComponentType(contribution.Component)) {
+        throw new Error(`New workspace item ${normalizedId} is not a component`);
+      }
+      newWorkspaceItemIds.add(normalizedId);
+      return register(
+        collector.newWorkspaceItems,
+        { id: normalizedId, Component: contribution.Component },
+        () => newWorkspaceItemIds.delete(normalizedId),
+      );
+    },
+    addSidebarView(contribution) {
+      const normalizedId = requireId(contribution.id, "sidebar view id");
+      if (sidebarViewIds.has(normalizedId))
+        throw new Error(`Duplicate sidebar view: ${normalizedId}`);
+      if (!isComponentType(contribution.Component))
+        throw new Error(`Sidebar view ${normalizedId} is not a component`);
+      const title = requirePluginText(contribution.title);
+      sidebarViewIds.add(normalizedId);
+      return register(collector.sidebarViews, { ...contribution, id: normalizedId, title }, () =>
+        sidebarViewIds.delete(normalizedId),
+      );
+    },
     addSidebarHeaderItem(contribution: PluginSidebarItemContribution) {
       return addSidebarItem("header", contribution);
     },
@@ -517,7 +565,8 @@ export function runPluginClientBundle(
     if (name === "@getpaseo/plugin/client")
       return {
         ...pluginClientRuntime,
-        useSettings,
+        useSettings: (definition: import("@getpaseo/plugin").SettingsDefinition) =>
+          useSettings(definition, id),
         openExternalUrl,
         getPaseoClient: (serverId: string) => runtime.hosts.getPaseoClient(serverId),
         useHosts: () =>
@@ -582,9 +631,12 @@ export function runPluginClientBundle(
     cleanup,
     surfaces: collector.surfaces,
     settingsScreens: collector.settingsScreens,
+    sidebarViews: collector.sidebarViews,
     sidebarItems: collector.sidebarItems,
     legacySidebarItems: collector.legacySidebarItems,
     filePanels: collector.filePanels,
+    composerItems: collector.composerItems,
+    newWorkspaceItems: collector.newWorkspaceItems,
     workspacePanels: collector.workspacePanels as EvaluatedPlugin["workspacePanels"],
     commandCenterItems: collector.commandCenterItems,
     clientSlashCommands: collector.clientSlashCommands,
diff --git a/packages/app/src/plugins/focused-agent.ts b/packages/app/src/plugins/focused-agent.ts
new file mode 100644
index 0000000000..d5a7121067
--- /dev/null
+++ b/packages/app/src/plugins/focused-agent.ts
@@ -0,0 +1,30 @@
+/**
+ * The agent the user has focused: the one the Command Center hands to agent items. The Command
+ * Center registration reads the router and the workspace layout, publishes the answer here, and
+ * publishes `null` outside a workspace. A plugin's `{ focused: true }` composer reads it from here,
+ * so both name the same agent and neither imports the navigation or layout stores.
+ */
+export interface FocusedAgent {
+  serverId: string;
+  agentId: string;
+}
+
+let current: FocusedAgent | null = null;
+const listeners = new Set<() => void>();
+
+export function publishFocusedAgent(next: FocusedAgent | null): void {
+  if (current?.serverId === next?.serverId && current?.agentId === next?.agentId) return;
+  current = next;
+  for (const listener of listeners) listener();
+}
+
+export function getFocusedAgent(): FocusedAgent | null {
+  return current;
+}
+
+export function subscribeFocusedAgent(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
diff --git a/packages/app/src/plugins/freeze.ts b/packages/app/src/plugins/freeze.ts
new file mode 100644
index 0000000000..7c2f4e9e74
--- /dev/null
+++ b/packages/app/src/plugins/freeze.ts
@@ -0,0 +1,25 @@
+// Plugins and the host never share an object: each direction crosses through a deep copy.
+
+function deepCopy<T>(value: T, finish: <V extends object>(copied: V) => V): T {
+  if (Array.isArray(value)) {
+    return finish(value.map((entry) => deepCopy(entry, finish))) as T;
+  }
+  if (value !== null && typeof value === "object") {
+    return finish(
+      Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [key, deepCopy(entry, finish)]),
+      ),
+    ) as T;
+  }
+  return value;
+}
+
+/** A deep copy no plugin can change. Plugins read data through it, never the host's own objects. */
+export function cloneAndFreeze<T>(value: T): T {
+  return deepCopy(value, Object.freeze);
+}
+
+/** A deep copy the host owns. Plugin commands hand data in through it, never the plugin's own objects. */
+export function ownCopy<T>(value: T): T {
+  return deepCopy(value, (copied) => copied);
+}
diff --git a/packages/app/src/plugins/icons.ts b/packages/app/src/plugins/icons.ts
index aa2a5765c9..7956ac40dc 100644
--- a/packages/app/src/plugins/icons.ts
+++ b/packages/app/src/plugins/icons.ts
@@ -25,6 +25,11 @@ function findLucideIcon(name: string): LucideIcon | null {
   return isComponent(candidate) ? (candidate as LucideIcon) : null;
 }
 
+/** Whether `name` is a Lucide icon, so a caller can fall back before drawing nothing. */
+export function isLucideIconName(name: string): boolean {
+  return findLucideIcon(name) !== null;
+}
+
 function isComponent(value: unknown): boolean {
   return (
     typeof value === "function" ||
diff --git a/packages/app/src/plugins/index.ts b/packages/app/src/plugins/index.ts
index ac3500e7e9..425c925804 100644
--- a/packages/app/src/plugins/index.ts
+++ b/packages/app/src/plugins/index.ts
@@ -3,9 +3,4 @@ export { buildLegacyPluginSurfaceRedirectRoute } from "./routes";
 export { PluginSurfaceScreen } from "./surface-screen";
 export { usePluginAttachmentPicker } from "./attachments/picker";
 export { PluginResourceAttachmentPill } from "./attachments/pill";
-export {
-  PluginComposerPills,
-  PluginHeaderButtons,
-  useHasPluginComposerPills,
-  usePluginWorkspaceMenu,
-} from "./buttons/view";
+export { PluginComposerPills, PluginHeaderButtons, usePluginWorkspaceMenu } from "./buttons/view";
diff --git a/packages/app/src/plugins/installation-provider.test.tsx b/packages/app/src/plugins/installation-provider.test.tsx
index 18af532044..b4f7735e86 100644
--- a/packages/app/src/plugins/installation-provider.test.tsx
+++ b/packages/app/src/plugins/installation-provider.test.tsx
@@ -1,7 +1,8 @@
 import { PluginTranslationRuntime } from "@getpaseo/plugin/client/host";
 import { usePaseo, useRpc } from "@getpaseo/plugin/client";
 import { defineRpc } from "@getpaseo/plugin";
-import type { PaseoApi } from "@getpaseo/client";
+import { createPaseoApi, type PaseoApi } from "@getpaseo/client";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { QueryClient } from "@tanstack/react-query";
 import React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
@@ -24,18 +25,30 @@ function installation(invoked: string[]): InstalledPlugin {
     lifetime: new AbortController(),
     locale: "en",
     i18n: new PluginTranslationRuntime({ getLocale: () => "en", subscribe: () => () => {} }),
-    paseo: { dispose: async () => undefined } as PaseoApi,
+    paseo: createPaseoApi(
+      new DaemonClient({
+        url: "ws://127.0.0.1:1",
+        clientId: "installation-provider",
+        reconnect: { enabled: false },
+      }),
+    ),
     invoke: async (method) => {
       invoked.push(method);
       return { state: "green" };
     },
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     queryClient: new QueryClient(),
     cleanup: () => undefined,
     settingsScreens: [],
     surfaces: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
@@ -72,4 +85,6 @@ it("gives every surface the installation's client and RPCs on its first frame",
   expect(received.every((paseo) => paseo === plugin.paseo)).toBe(true);
   await expect(rpc!({})).resolves.toEqual({ state: "green" });
   expect(invoked).toEqual(["deploys.status"]);
+  plugin.lifetime.abort();
+  await plugin.paseo.dispose();
 });
diff --git a/packages/app/src/plugins/installation-provider.tsx b/packages/app/src/plugins/installation-provider.tsx
index 552f8080b8..19fb3bc8ab 100644
--- a/packages/app/src/plugins/installation-provider.tsx
+++ b/packages/app/src/plugins/installation-provider.tsx
@@ -1,10 +1,13 @@
+import { getPluginClientApi } from "./client-state/api";
 import { QueryClientProvider } from "@tanstack/react-query";
 import {
   PaseoApiProvider,
+  PluginComposersProvider,
   PluginRpcProvider,
   PluginTranslationProvider,
 } from "@getpaseo/plugin/client/host";
 import React, { type ReactNode } from "react";
+import { pluginComposersSource } from "./composer-items/source";
 import type { InstalledPlugin } from "./types";
 
 /** Every plugin surface renders under its installation: one query cache, one Paseo client, RPCs. */
@@ -17,9 +20,13 @@ export function PluginInstallationProvider({
 }) {
   return (
     <QueryClientProvider client={plugin.queryClient}>
-      <PaseoApiProvider paseo={plugin.paseo}>
-        <PluginRpcProvider invoke={plugin.invoke}>
-          <PluginTranslationProvider runtime={plugin.i18n}>{children}</PluginTranslationProvider>
+      <PaseoApiProvider paseo={getPluginClientApi(plugin).paseo}>
+        <PluginRpcProvider invoke={plugin.invoke} subscribe={plugin.subscribe}>
+          <PluginTranslationProvider runtime={plugin.i18n}>
+            <PluginComposersProvider source={pluginComposersSource(plugin)}>
+              {children}
+            </PluginComposersProvider>
+          </PluginTranslationProvider>
         </PluginRpcProvider>
       </PaseoApiProvider>
     </QueryClientProvider>
diff --git a/packages/app/src/plugins/item-host.tsx b/packages/app/src/plugins/item-host.tsx
new file mode 100644
index 0000000000..2df4198e7a
--- /dev/null
+++ b/packages/app/src/plugins/item-host.tsx
@@ -0,0 +1,74 @@
+import { useMemo, type ComponentType } from "react";
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { useToast } from "@/contexts/toast-api-context";
+import { useHosts } from "@/runtime/host-runtime";
+import type { Theme } from "@/styles/theme";
+import { createPluginClientStateSource } from "./client-state/source";
+import { resolvePluginPlatform } from "./platform";
+import type { PluginEnvironment } from "./popover";
+import { SurfaceErrorBoundary } from "./surface-error-boundary";
+import { toPluginTheme } from "./theme";
+import type { InstalledPlugin } from "./types";
+
+/** `withUnistyles` mapping that hands a host the plugin theme. */
+export const pluginThemeMapping = (theme: Theme) => ({ theme: toPluginTheme(theme) });
+
+function renderNothing() {
+  return null;
+}
+
+/** What a plugin's items on a host surface (composer, New workspace) share: environment and props. */
+export function usePluginItemHost(
+  plugin: InstalledPlugin,
+  theme: PluginHostProps["theme"],
+): { environment: PluginEnvironment; props: PluginHostProps } {
+  const toast = useToast();
+  const compact = useIsCompactFormFactor();
+  const hosts = useHosts();
+  const hostLabel =
+    hosts.find((host) => host.serverId === plugin.serverId)?.label ?? plugin.serverId;
+  const environment = useMemo<PluginEnvironment>(
+    () => ({
+      installation: plugin,
+      toast,
+      state: createPluginClientStateSource(plugin.serverId),
+    }),
+    [plugin, toast],
+  );
+  const props = useMemo<PluginHostProps>(
+    () => ({
+      theme,
+      host: { id: plugin.serverId, label: hostLabel },
+      layout: { compact, platform: resolvePluginPlatform() },
+    }),
+    [compact, hostLabel, plugin.serverId, theme],
+  );
+  return { environment, props };
+}
+
+/** Mounts each item behind its own boundary; a throwing item draws nothing. */
+export function PluginItemList({
+  plugin,
+  items,
+  props,
+}: {
+  plugin: InstalledPlugin;
+  items: readonly { id: string; Component: ComponentType<PluginHostProps> }[];
+  props: PluginHostProps;
+}) {
+  return (
+    <>
+      {items.map(({ id, Component }) => (
+        <SurfaceErrorBoundary
+          key={id}
+          installation={plugin}
+          Surface={Component}
+          renderError={renderNothing}
+        >
+          <Component {...props} />
+        </SurfaceErrorBoundary>
+      ))}
+    </>
+  );
+}
diff --git a/packages/app/src/plugins/new-workspace-items/index.tsx b/packages/app/src/plugins/new-workspace-items/index.tsx
new file mode 100644
index 0000000000..642cc9360e
--- /dev/null
+++ b/packages/app/src/plugins/new-workspace-items/index.tsx
@@ -0,0 +1,113 @@
+import { Fragment, useMemo } from "react";
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { PluginNewWorkspaceProvider } from "@getpaseo/plugin/client/host";
+import { withUnistyles } from "react-native-unistyles";
+import {
+  ComposerControlLockProvider,
+  ComposerControlSurfaceProvider,
+} from "@/composer/agent-controls/composer-control";
+import type { PickerItem } from "@/screens/new-workspace-picker-item";
+import {
+  useNewWorkspaceSetupState,
+  type NewWorkspaceSetup,
+} from "@/screens/new-workspace/setup-model";
+import { PluginItemList, pluginThemeMapping, usePluginItemHost } from "../item-host";
+import { PluginEnvironmentProvider } from "../popover";
+import { useInstalledPlugins } from "../registry";
+import type { InstalledPlugin } from "../types";
+import { toPluginNewWorkspace } from "./model";
+
+/** What the screen derives and the items read; the rest is in the setup model. */
+export interface NewWorkspaceItemsScreen {
+  project: { id: string; name: string } | null;
+  isolation: "local" | "worktree";
+  baseItem: PickerItem | null;
+  locked: boolean;
+}
+
+function useServerPlugins(serverId: string): InstalledPlugin[] {
+  const installed = useInstalledPlugins();
+  return useMemo(
+    () =>
+      installed.filter(
+        (plugin) => plugin.serverId === serverId && plugin.newWorkspaceItems.length > 0,
+      ),
+    [installed, serverId],
+  );
+}
+
+/**
+ * The selected host's plugin items on the New workspace screen, drawn as setup fields. They read
+ * the screen's choices and command them through the setup model. Items are mounted for one
+ * project on one host: a change of either remounts them, so nothing an item fetched or chose for
+ * the previous target stays on screen, and an item that sets up on mount sets up for the new one.
+ */
+export function PluginNewWorkspaceItems({
+  serverId,
+  screen,
+  setup,
+}: {
+  serverId: string;
+  screen: NewWorkspaceItemsScreen;
+  setup: NewWorkspaceSetup;
+}) {
+  const plugins = useServerPlugins(serverId);
+  return (
+    <ComposerControlSurfaceProvider value="field">
+      <ComposerControlLockProvider value={screen.locked}>
+        <Fragment key={`${serverId}\n${screen.project?.id ?? ""}`}>
+          {plugins.map((plugin) => (
+            <ThemedPluginNewWorkspaceItems
+              key={plugin.id}
+              plugin={plugin}
+              serverId={serverId}
+              screen={screen}
+              setup={setup}
+              uniProps={pluginThemeMapping}
+            />
+          ))}
+        </Fragment>
+      </ComposerControlLockProvider>
+    </ComposerControlSurfaceProvider>
+  );
+}
+
+function PluginNewWorkspaceItemsHost({
+  plugin,
+  theme,
+  serverId,
+  screen,
+  setup,
+}: {
+  plugin: InstalledPlugin;
+  serverId: string;
+  theme: PluginHostProps["theme"];
+  screen: NewWorkspaceItemsScreen;
+  setup: NewWorkspaceSetup;
+}) {
+  const { environment, props } = usePluginItemHost(plugin, theme);
+  const { branch, metadata } = useNewWorkspaceSetupState(setup);
+  const projectId = screen.project?.id ?? null;
+  const commands = useMemo(
+    () => setup.commandsFor({ serverId, projectId }),
+    [setup, serverId, projectId],
+  );
+  const newWorkspace = useMemo(
+    () =>
+      toPluginNewWorkspace({
+        host: props.host,
+        view: { ...screen, branch, metadata },
+        commands,
+      }),
+    [branch, metadata, props.host, screen, commands],
+  );
+  return (
+    <PluginEnvironmentProvider environment={environment}>
+      <PluginNewWorkspaceProvider newWorkspace={newWorkspace}>
+        <PluginItemList plugin={plugin} items={plugin.newWorkspaceItems} props={props} />
+      </PluginNewWorkspaceProvider>
+    </PluginEnvironmentProvider>
+  );
+}
+
+const ThemedPluginNewWorkspaceItems = withUnistyles(PluginNewWorkspaceItemsHost);
diff --git a/packages/app/src/plugins/new-workspace-items/model.test.ts b/packages/app/src/plugins/new-workspace-items/model.test.ts
new file mode 100644
index 0000000000..1a90194126
--- /dev/null
+++ b/packages/app/src/plugins/new-workspace-items/model.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildBranchPickerItems,
+  pickerItemToCheckoutRequest,
+  type PickerItem,
+} from "@/screens/new-workspace-picker-item";
+import { createNewWorkspaceSetup } from "@/screens/new-workspace/setup-model";
+import { toPluginNewWorkspace } from "./model";
+
+const HOST = { id: "host", label: "Host" } as Parameters<typeof toPluginNewWorkspace>[0]["host"];
+
+function viewOf(baseItem: PickerItem | null) {
+  return {
+    project: { id: "p", name: "repo" },
+    isolation: "worktree" as const,
+    baseItem,
+    branch: null,
+    metadata: {},
+    locked: false,
+  };
+}
+
+describe("the base ref a plugin reads", () => {
+  it("names the exact ref creation uses, so setting it back picks the same base", async () => {
+    // `release` exists locally and on origin, and the two have diverged.
+    const rows = buildBranchPickerItems([
+      {
+        name: "release",
+        committerDate: 0,
+        hasLocal: true,
+        hasRemote: true,
+        localAhead: 2,
+        localBehind: 1,
+      },
+    ]);
+    const origin = rows.find((row) => row.kind === "branch" && row.refName.includes("remotes"));
+    if (!origin) throw new Error("expected an origin row");
+
+    const chosen: PickerItem[] = [];
+    const setup = createNewWorkspaceSetup(
+      {
+        serverId: "host-a",
+        locked: false,
+        project: { id: "p", name: "repo" },
+        canCreateWorktree: true,
+        supportsMetadata: true,
+      },
+      { persistIsolation: () => {}, syncBaseAttachment: (item) => chosen.push(item) },
+    );
+    const read = toPluginNewWorkspace({
+      host: HOST,
+      view: viewOf(origin),
+      commands: setup.commandsFor({ serverId: "host-a", projectId: "p" }),
+    });
+
+    expect(read.baseRef).toEqual({ type: "branch", name: "refs/remotes/origin/release" });
+    if (read.baseRef?.type !== "branch") throw new Error("expected a branch");
+    await read.setBaseRef(read.baseRef);
+
+    expect(pickerItemToCheckoutRequest(chosen[0] ?? null)).toEqual(
+      pickerItemToCheckoutRequest(origin),
+    );
+  });
+});
+
+describe("the metadata a plugin sets", () => {
+  it("stays what the plugin set when the plugin reuses the object it handed in", async () => {
+    const setup = createNewWorkspaceSetup(
+      {
+        serverId: "host-a",
+        locked: false,
+        project: { id: "p", name: "repo" },
+        canCreateWorktree: true,
+        supportsMetadata: true,
+      },
+      { persistIsolation: () => {}, syncBaseAttachment: () => {} },
+    );
+    const plugin = toPluginNewWorkspace({
+      host: HOST,
+      view: { ...viewOf(null), metadata: setup.getSnapshot().metadata },
+      commands: setup.commandsFor({ serverId: "host-a", projectId: "p" }),
+    });
+
+    const issue = { id: "ISS-1" };
+    await plugin.setMetadata({ issue });
+    issue.id = "ISS-2";
+
+    expect(setup.getSnapshot().metadata).toEqual({ issue: { id: "ISS-1" } });
+  });
+});
diff --git a/packages/app/src/plugins/new-workspace-items/model.ts b/packages/app/src/plugins/new-workspace-items/model.ts
new file mode 100644
index 0000000000..099538a891
--- /dev/null
+++ b/packages/app/src/plugins/new-workspace-items/model.ts
@@ -0,0 +1,42 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginHostProps, PluginNewWorkspace } from "@getpaseo/plugin/client";
+import type { PickerItem } from "@/screens/new-workspace-picker-item";
+import type { SetupCommands } from "@/screens/new-workspace/setup-model";
+import { cloneAndFreeze, ownCopy } from "../freeze";
+
+/** What the New workspace screen shows at render; the plugin reads it, never writes it. */
+export interface NewWorkspaceView {
+  project: { id: string; name: string } | null;
+  /** What the screen will create. */
+  isolation: "local" | "worktree";
+  baseItem: PickerItem | null;
+  branch: string | null;
+  metadata: Readonly<Record<string, JsonValue>>;
+  locked: boolean;
+}
+
+/** `name` is the exact ref creation uses, so a plugin can set back what it read. */
+function toBaseRef(item: PickerItem | null): PluginNewWorkspace["baseRef"] {
+  if (!item) return null;
+  return item.kind === "branch"
+    ? { type: "branch", name: item.refName }
+    : { type: "change-request", number: item.item.number };
+}
+
+export function toPluginNewWorkspace(input: {
+  host: PluginHostProps["host"];
+  view: NewWorkspaceView;
+  commands: SetupCommands;
+}): PluginNewWorkspace {
+  const { host, view, commands } = input;
+  return {
+    host: cloneAndFreeze({ id: host.id, label: host.label }),
+    project: cloneAndFreeze(view.project),
+    isolation: view.isolation,
+    baseRef: cloneAndFreeze(toBaseRef(view.baseItem)),
+    branch: view.branch,
+    metadata: cloneAndFreeze(view.metadata),
+    ...commands,
+    setMetadata: (patch) => commands.setMetadata(ownCopy(patch)),
+  };
+}
diff --git a/packages/app/src/plugins/plugin-list.ts b/packages/app/src/plugins/plugin-list.ts
new file mode 100644
index 0000000000..387e0c6b56
--- /dev/null
+++ b/packages/app/src/plugins/plugin-list.ts
@@ -0,0 +1,36 @@
+import type { PluginListItem } from "@getpaseo/protocol/messages";
+import { useFetchQuery } from "@/data/query";
+import { useHostFeature } from "@/runtime/host-features";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+
+/** A host's configured plugins, as listed on Settings → Plugins. One cache entry per host. */
+export function usePluginList(serverId: string, options: { enabled?: boolean } = {}) {
+  const client = useHostRuntimeClient(serverId);
+  const connected = useHostRuntimeIsConnected(serverId);
+  const supported = useHostFeature(serverId, "pluginManagement");
+  return useFetchQuery({
+    queryKey: ["plugins", serverId] as const,
+    queryFn: async () => {
+      if (!client) throw new Error("Plugin host is offline");
+      return client.listPlugins();
+    },
+    enabled: (options.enabled ?? true) && Boolean(client && connected && supported),
+    dataShape: "list",
+    staleTimeMs: 1_000,
+  });
+}
+
+/** The manifest's display name, or the plugin id when it has none. */
+export function pluginDisplayName(plugin: Pick<PluginListItem, "id" | "name">): string {
+  return plugin.name ?? plugin.id;
+}
+
+/** The display name of one configured plugin; its id until the list loads. */
+export function usePluginDisplayName(
+  target: { serverId: string; pluginId: string } | null,
+): string | undefined {
+  const plugins = usePluginList(target?.serverId ?? "", { enabled: target !== null });
+  if (!target) return undefined;
+  const plugin = plugins.data?.find((candidate) => candidate.id === target.pluginId);
+  return plugin ? pluginDisplayName(plugin) : target.pluginId;
+}
diff --git a/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx b/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx
new file mode 100644
index 0000000000..d4cf2df5bc
--- /dev/null
+++ b/packages/app/src/plugins/react-native/composer-controls.browser.test.tsx
@@ -0,0 +1,164 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ComboboxItem } from "@getpaseo/plugin/client/ui";
+import type { ToastApi } from "@/components/toast-host";
+import { ComposerControlSurfaceProvider } from "@/composer/agent-controls/composer-control";
+import { ToastApiProvider } from "@/contexts/toast-api-context";
+import { i18n } from "@/i18n/i18next";
+import { Combobox } from "./composer-controls";
+
+beforeEach(async () => {
+  vi.stubGlobal("React", React);
+  await i18n.changeLanguage("en");
+});
+afterEach(cleanup);
+
+interface Issue extends ComboboxItem {
+  branch: string;
+}
+
+const ONE: Issue = { id: "1", label: "Slow sidebar", branch: "one" };
+const TWO: Issue = { id: "2", label: "Crash on resume", branch: "two" };
+const THREE: Issue = { id: "3", label: "Crash on launch", branch: "three" };
+
+interface Search {
+  query: string;
+  resolve(items: Issue[]): void;
+  reject(error: Error): void;
+}
+
+/** A search the test settles by hand, so it decides which one finishes first. */
+function controlledSearch() {
+  const searches: Search[] = [];
+  const search = ({ query }: { query: string }) =>
+    new Promise<Issue[]>((resolve, reject) => {
+      searches.push({ query, resolve, reject });
+    });
+  const forQuery = (query: string) => {
+    const found = searches.find((candidate) => candidate.query === query);
+    if (!found) throw new Error(`No search for "${query}" yet`);
+    return found;
+  };
+  const reject = (index: number, error: Error) => searches[index]?.reject(error);
+  return { search, forQuery, reject, queries: () => searches.map((candidate) => candidate.query) };
+}
+
+const toast = { error: vi.fn() } as unknown as ToastApi;
+const ignoreSelect = () => undefined;
+
+function Harness({
+  search,
+  value,
+  onSelect = ignoreSelect,
+}: {
+  search: (event: { query: string }) => Promise<Issue[]>;
+  value: ComboboxItem | null;
+  onSelect?: (event: { item: Issue }) => void;
+}) {
+  const [queryClient] = React.useState(() => new QueryClient());
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ToastApiProvider api={toast}>
+        <ComposerControlSurfaceProvider value="field">
+          <Combobox
+            title="Issue"
+            icon="CircleDot"
+            value={value}
+            search={search}
+            onSelect={onSelect}
+          />
+        </ComposerControlSurfaceProvider>
+      </ToastApiProvider>
+    </QueryClientProvider>
+  );
+}
+
+function renderCombobox(input: {
+  search: (event: { query: string }) => Promise<Issue[]>;
+  value?: ComboboxItem | null;
+  onSelect?: (event: { item: Issue }) => void;
+}) {
+  render(<Harness search={input.search} value={input.value ?? null} onSelect={input.onSelect} />);
+  fireEvent.click(screen.getByRole("button", { name: "Issue" }));
+}
+
+describe("plugin Combobox", () => {
+  it("searches when the list opens, shows the results, and hands the picked item back", async () => {
+    const controlled = controlledSearch();
+    const onSelect = vi.fn();
+    renderCombobox({ search: controlled.search, onSelect });
+
+    await waitFor(() => expect(controlled.queries()).toEqual([""]));
+    expect(screen.getByText("Searching…")).toBeTruthy();
+    controlled.forQuery("").resolve([ONE, TWO]);
+
+    fireEvent.click(await screen.findByText("Crash on resume"));
+    expect(onSelect).toHaveBeenCalledWith({ item: TWO });
+  });
+
+  it("shows the error and not stale results when the search fails", async () => {
+    const controlled = controlledSearch();
+    renderCombobox({ search: controlled.search });
+
+    await waitFor(() => expect(controlled.queries()).toEqual([""]));
+    controlled.forQuery("").reject(new Error("tracker is down"));
+
+    expect(await screen.findByText("Search failed: tracker is down")).toBeTruthy();
+  });
+
+  it("keeps the previous results while a newer search runs and ignores a superseded one", async () => {
+    const controlled = controlledSearch();
+    renderCombobox({ search: controlled.search });
+    await waitFor(() => expect(controlled.queries()).toEqual([""]));
+    controlled.forQuery("").resolve([ONE, TWO]);
+    await screen.findByText("Slow sidebar");
+
+    const input = screen.getByRole("textbox");
+    fireEvent.change(input, { target: { value: "c" } });
+    await waitFor(() => expect(controlled.queries()).toEqual(["", "c"]));
+    expect(screen.getByText("Slow sidebar")).toBeTruthy();
+
+    fireEvent.change(input, { target: { value: "cr" } });
+    await waitFor(() => expect(controlled.queries()).toEqual(["", "c", "cr"]));
+    controlled.forQuery("cr").resolve([TWO]);
+    await waitFor(() => expect(screen.queryByText("Slow sidebar")).toBeNull());
+    controlled.forQuery("c").resolve([ONE]);
+
+    // Searches settle in order, so once a later one has landed the stale one has been handled.
+    fireEvent.change(input, { target: { value: "cra" } });
+    await waitFor(() => expect(controlled.queries()).toEqual(["", "c", "cr", "cra"]));
+    controlled.forQuery("cra").resolve([THREE]);
+    await screen.findByText("Crash on launch");
+    expect(screen.queryByText("Slow sidebar")).toBeNull();
+  });
+
+  it("shows the error and not the previous results when a reopened list fails to refresh", async () => {
+    const controlled = controlledSearch();
+    renderCombobox({ search: controlled.search });
+    await waitFor(() => expect(controlled.queries()).toEqual([""]));
+    controlled.forQuery("").resolve([ONE]);
+    await screen.findByText("Slow sidebar");
+
+    fireEvent.keyDown(screen.getByRole("textbox"), { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("textbox")).toBeNull());
+    fireEvent.click(screen.getByRole("button", { name: "Issue" }));
+    await waitFor(() => expect(controlled.queries()).toEqual(["", ""]));
+    controlled.reject(1, new Error("tracker is down"));
+
+    expect(await screen.findByText("Search failed: tracker is down")).toBeTruthy();
+    expect(screen.queryByText("Slow sidebar")).toBeNull();
+  });
+
+  it("shows a chosen value that the search no longer returns", async () => {
+    const controlled = controlledSearch();
+    renderCombobox({ search: controlled.search, value: { id: "9", label: "PAS-9 Old issue" } });
+
+    expect(screen.getByRole("button", { name: "Issue" }).textContent).toContain("PAS-9 Old issue");
+    await waitFor(() => expect(controlled.queries()).toEqual([""]));
+    controlled.forQuery("").resolve([ONE]);
+    await screen.findByText("Slow sidebar");
+    expect(screen.getByRole("button", { name: "Issue" }).textContent).toContain("PAS-9 Old issue");
+  });
+});
diff --git a/packages/app/src/plugins/react-native/composer-controls.tsx b/packages/app/src/plugins/react-native/composer-controls.tsx
new file mode 100644
index 0000000000..eeb5d581bd
--- /dev/null
+++ b/packages/app/src/plugins/react-native/composer-controls.tsx
@@ -0,0 +1,188 @@
+import type {
+  ActionProps,
+  ComboboxItem,
+  ComboboxProps,
+  SelectProps,
+  ToggleProps,
+} from "@getpaseo/plugin/client/ui";
+import { useEffect, useId, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  ComposerControl,
+  useComposerControlLocked,
+  useComposerControlSurface,
+  type ComposerControlItem,
+} from "@/composer/agent-controls/composer-control";
+import { useComposerLocked } from "@/composer/session";
+import { useFetchQuery } from "@/data/query";
+import { toErrorMessage } from "@/utils/error-messages";
+import { parsePluginIcon, pluginIconComponent } from "../icons";
+
+/** Icons resolve at render, so an invalid one throws to the item's boundary. */
+function usePluginControlIcon(icon: ToggleProps["icon"]) {
+  return useMemo(() => pluginIconComponent(parsePluginIcon("Composer control", icon)), [icon]);
+}
+
+/** Draws one plugin control where its item sits: inline, a row in the sheet, or a field. */
+function PluginComposerControl({
+  item,
+  disabled,
+  onOpenChange,
+}: {
+  item: ComposerControlItem;
+  disabled: boolean | undefined;
+  onOpenChange?: (open: boolean) => void;
+}) {
+  const surface = useComposerControlSurface();
+  const composerLocked = useComposerLocked();
+  const fieldLocked = useComposerControlLocked();
+  const locked = composerLocked || fieldLocked;
+  const [open, setOpen] = useState(false);
+  const handleOpenChange = useMemo(
+    () => (next: boolean) => {
+      setOpen(next);
+      onOpenChange?.(next);
+    },
+    [onOpenChange],
+  );
+  return (
+    <ComposerControl
+      item={item}
+      surface={surface}
+      disabled={disabled || locked}
+      open={open}
+      onOpenChange={handleOpenChange}
+    />
+  );
+}
+
+export function Toggle({ title, icon, disabled, value, onValueChange }: ToggleProps) {
+  const Icon = usePluginControlIcon(icon);
+  const item = useMemo<ComposerControlItem>(
+    () => ({
+      id: "plugin-toggle",
+      type: "toggle",
+      title,
+      icon: Icon,
+      highlight: value ? "blue" : undefined,
+      value,
+      onChange: (next) => onValueChange({ value: next }),
+    }),
+    [Icon, onValueChange, title, value],
+  );
+  return <PluginComposerControl item={item} disabled={disabled} />;
+}
+
+export function Select<Value extends string>({
+  title,
+  icon,
+  disabled,
+  value,
+  options,
+  onValueChange,
+}: SelectProps<Value>) {
+  const Icon = usePluginControlIcon(icon);
+  const item = useMemo<ComposerControlItem>(
+    () => ({
+      id: "plugin-select",
+      type: "select",
+      title,
+      icon: Icon,
+      value,
+      choices: options,
+      onChange: (next) => onValueChange({ value: next as Value }),
+      showCaret: true,
+    }),
+    [Icon, onValueChange, options, title, value],
+  );
+  return <PluginComposerControl item={item} disabled={disabled} />;
+}
+
+export function Action({ title, icon, disabled, onPress }: ActionProps) {
+  const Icon = usePluginControlIcon(icon);
+  const item = useMemo<ComposerControlItem>(
+    () => ({ id: "plugin-action", type: "action", title, icon: Icon, onPress: () => onPress({}) }),
+    [Icon, onPress, title],
+  );
+  return <PluginComposerControl item={item} disabled={disabled} />;
+}
+
+const SEARCH_DEBOUNCE_MS = 200;
+const NO_RESULTS: readonly never[] = [];
+
+/** The query settles after the user stops typing; an empty query applies at once. */
+function useDebounced(query: string): string {
+  const [settled, setSettled] = useState(query);
+  useEffect(() => {
+    if (query === "") return setSettled("");
+    const timer = setTimeout(() => setSettled(query), SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(timer);
+  }, [query]);
+  return settled;
+}
+
+/**
+ * Searches while the list is open. The search runs once per settled query, keeps the previous
+ * results on screen while the next one loads, and drops a search a newer one replaced.
+ */
+export function Combobox<Item extends ComboboxItem>({
+  title,
+  icon,
+  disabled,
+  value,
+  search,
+  onSelect,
+}: ComboboxProps<Item>) {
+  const { t } = useTranslation();
+  const Icon = usePluginControlIcon(icon);
+  const instanceId = useId();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const settled = useDebounced(query);
+  const results = useFetchQuery({
+    queryKey: ["plugin-combobox", instanceId, settled],
+    queryFn: () => search({ query: settled }),
+    dataShape: "list",
+    staleTimeMs: 0,
+    enabled: open,
+    gcTime: 0,
+    retry: false,
+  });
+  // A failed search shows its error, not the results of an earlier one.
+  const items: readonly Item[] = results.isError ? NO_RESULTS : (results.data ?? NO_RESULTS);
+  const item = useMemo<ComposerControlItem>(() => {
+    const choices = items.map(({ id, label, description }) => ({ value: id, label, description }));
+    return {
+      id: "plugin-combobox",
+      type: "select",
+      title,
+      icon: Icon,
+      value: value?.id ?? null,
+      valueLabel: value?.label,
+      choices,
+      onChange: (id) => {
+        const picked = items.find((candidate) => candidate.id === id);
+        return picked ? onSelect({ item: picked }) : undefined;
+      },
+      searchable: true,
+      remoteSearch: true,
+      onSearchQueryChange: setQuery,
+      emptyText: comboboxEmptyText({ t, results, query, settled }),
+      showCaret: true,
+    };
+  }, [Icon, items, onSelect, query, results, settled, t, title, value]);
+  return <PluginComposerControl item={item} disabled={disabled} onOpenChange={setOpen} />;
+}
+
+function comboboxEmptyText(input: {
+  t: (key: string, options?: Record<string, unknown>) => string;
+  results: { isError: boolean; isFetching: boolean; error: unknown };
+  query: string;
+  settled: string;
+}): string {
+  const { t, results, query, settled } = input;
+  if (results.isError)
+    return t("pluginCombobox.failed", { message: toErrorMessage(results.error) });
+  if (results.isFetching || query !== settled) return t("pluginCombobox.searching");
+  return t("pluginCombobox.empty");
+}
diff --git a/packages/app/src/plugins/react-native/runtime-context-bridge.browser.test.tsx b/packages/app/src/plugins/react-native/runtime-context-bridge.browser.test.tsx
new file mode 100644
index 0000000000..803d71ff0a
--- /dev/null
+++ b/packages/app/src/plugins/react-native/runtime-context-bridge.browser.test.tsx
@@ -0,0 +1,79 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, expect, it, vi } from "vitest";
+import type { PluginNewWorkspace, PluginPaseoApi } from "@getpaseo/plugin/client";
+import {
+  PaseoApiProvider,
+  PluginNewWorkspaceProvider,
+  PluginRpcProvider,
+  PluginTranslationProvider,
+  PluginTranslationRuntime,
+  usePluginRuntimeContextBridge,
+  type PluginRuntimeContextBridge,
+  type PluginSubscribe,
+} from "@getpaseo/plugin/client/host";
+import { useNewWorkspace } from "@getpaseo/plugin/client";
+
+// App sources compile against the classic JSX runtime, which expects React on the global, as the
+// other browser tests here arrange.
+beforeEach(() => vi.stubGlobal("React", React));
+
+const newWorkspace = {
+  host: { id: "host_1", label: "Laptop" },
+  project: { id: "project_1", name: "paseo" },
+  isolation: "worktree",
+  baseRef: { type: "branch", name: "refs/remotes/origin/main" },
+  branch: null,
+  metadata: {},
+} as PluginNewWorkspace;
+
+const translations = new PluginTranslationRuntime({
+  getLocale: () => "en",
+  subscribe: () => () => undefined,
+});
+const paseo = {} as PluginPaseoApi;
+const rejectRpc = () => Promise.reject(new Error("no rpc in this test"));
+const noSubscribe: PluginSubscribe = () =>
+  Object.assign(() => undefined, { ready: Promise.resolve(), release: () => Promise.resolve() });
+
+/** An item the way a plugin writes one: it reads the setup it sits in and shows the branch base. */
+function BaseRefLabel() {
+  const setup = useNewWorkspace();
+  return (
+    <span data-testid="base">{setup.baseRef?.type === "branch" ? setup.baseRef.name : "none"}</span>
+  );
+}
+
+it("a New workspace item rendered through a portal host still finds its setup", () => {
+  let bridge: PluginRuntimeContextBridge | null = null;
+  function Capture() {
+    bridge = usePluginRuntimeContextBridge();
+    return null;
+  }
+  const surface = createRoot(document.createElement("div"));
+  act(() =>
+    surface.render(
+      <PaseoApiProvider paseo={paseo}>
+        <PluginRpcProvider invoke={rejectRpc} subscribe={noSubscribe}>
+          <PluginTranslationProvider runtime={translations}>
+            <PluginNewWorkspaceProvider newWorkspace={newWorkspace}>
+              <Capture />
+            </PluginNewWorkspaceProvider>
+          </PluginTranslationProvider>
+        </PluginRpcProvider>
+      </PaseoApiProvider>,
+    ),
+  );
+  if (!bridge) throw new Error("bridge did not mount");
+
+  // A portal host, such as the modal sheet, mounts the item in a separate React tree.
+  const portalElement = document.createElement("div");
+  const portal = createRoot(portalElement);
+  act(() => portal.render(<>{bridge!(<BaseRefLabel />)}</>));
+  expect(portalElement.querySelector('[data-testid="base"]')?.textContent).toBe(
+    "refs/remotes/origin/main",
+  );
+
+  act(() => portal.unmount());
+  act(() => surface.unmount());
+});
diff --git a/packages/app/src/plugins/react-native/ui.ts b/packages/app/src/plugins/react-native/ui.ts
index e431aa32eb..8b7d17216d 100644
--- a/packages/app/src/plugins/react-native/ui.ts
+++ b/packages/app/src/plugins/react-native/ui.ts
@@ -20,6 +20,7 @@ export { FilePanelLoading as Loading } from "@/file-panels/loading";
 export { SettingsGroup } from "@/components/settings";
 
 export { Icon } from "../icons";
+export { Action, Combobox, Select, Toggle } from "./composer-controls";
 export { Modal } from "./modal";
 export { ScrollView, FlatList } from "./scroll-view";
 export { TextInput } from "./text-input";
diff --git a/packages/app/src/plugins/registry-lifecycle.test.ts b/packages/app/src/plugins/registry-lifecycle.test.ts
index d2d02cb568..18a4a148b1 100644
--- a/packages/app/src/plugins/registry-lifecycle.test.ts
+++ b/packages/app/src/plugins/registry-lifecycle.test.ts
@@ -1,3 +1,4 @@
+import { getPluginClientApi } from "./client-state/api";
 import { filePanelTitle } from "@/file-panels/choice/presentation";
 import { i18n } from "@/i18n/i18next";
 import { createPluginHosts } from "./hosts";
@@ -50,18 +51,22 @@ function registry(
           },
           installation.lifetime.signal,
         ),
-        paseo: installation.paseo,
+        paseo: getPluginClientApi(installation).paseo,
         i18n: installation.i18n,
         rpc: async () => {
           throw new Error("Unexpected plugin RPC");
         },
         openScreen: () => {},
         openSurface: () => {},
+        composers: () => [],
         openSettings: () => {},
         playAudio: async () => {},
         openPanel: () => {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });
diff --git a/packages/app/src/plugins/registry-requirements.test.ts b/packages/app/src/plugins/registry-requirements.test.ts
index dedefe0b0d..6e9103b33a 100644
--- a/packages/app/src/plugins/registry-requirements.test.ts
+++ b/packages/app/src/plugins/registry-requirements.test.ts
@@ -1,3 +1,4 @@
+import { getPluginClientApi } from "./client-state/api";
 import { createPluginHosts } from "./hosts";
 import { afterEach, expect, it } from "vitest";
 import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -25,7 +26,7 @@ function registry(version: string) {
           },
           installation.lifetime.signal,
         ),
-        paseo: installation.paseo,
+        paseo: getPluginClientApi(installation).paseo,
         i18n: installation.i18n,
         rpc: async () => {
           throw new Error("No RPC in this plugin");
@@ -35,10 +36,14 @@ function registry(version: string) {
         },
         openScreen() {},
         openSurface() {},
+        composers: () => [],
         async playAudio() {},
         openPanel() {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });
diff --git a/packages/app/src/plugins/registry.ts b/packages/app/src/plugins/registry.ts
index cfe4f7212a..042050ed3a 100644
--- a/packages/app/src/plugins/registry.ts
+++ b/packages/app/src/plugins/registry.ts
@@ -8,10 +8,12 @@ import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { assertPluginCompatibility } from "@getpaseo/protocol/plugin-requirements";
 import { resolveAppVersion } from "@/utils/app-version";
 import { createPluginClientRuntime } from "./client-runtime";
+import { createPluginSubscribe } from "./subscriptions";
 import { runPluginClientBundle } from "./evaluate";
 import type { InstalledPlugin } from "./types";
 
 type CatalogPlugin = Awaited<ReturnType<DaemonClient["getPluginCatalog"]>>[number];
+export type PluginCatalogStatus = "loading" | "ready" | "error";
 
 export class PluginRegistry {
   private readonly byHost = new Map<string, InstalledPlugin[]>();
@@ -19,6 +21,7 @@ export class PluginRegistry {
   private snapshot: InstalledPlugin[] = [];
   private readonly disposed = new WeakSet<InstalledPlugin>();
   private readonly evaluationErrors = new Map<string, string>();
+  private readonly catalogStatuses = new Map<string, PluginCatalogStatus>();
   /** The client each host's installations were bound to; their Paseo API and RPCs call it. */
   private readonly clientByHost = new Map<string, DaemonClient>();
 
@@ -41,6 +44,16 @@ export class PluginRegistry {
     return this.evaluationErrors.get(`${serverId}/${pluginId}`);
   }
 
+  getCatalogStatus(serverId: string): PluginCatalogStatus {
+    return this.catalogStatuses.get(serverId) ?? "loading";
+  }
+
+  setCatalogStatus(serverId: string, status: PluginCatalogStatus): void {
+    if (this.catalogStatuses.get(serverId) === status) return;
+    this.catalogStatuses.set(serverId, status);
+    for (const listener of this.listeners) listener();
+  }
+
   installCatalog(
     serverId: string,
     catalog: CatalogPlugin[],
@@ -89,12 +102,18 @@ export class PluginRegistry {
           return [existing];
         }
         const client = options.client;
+        const lifetime = new AbortController();
         installation = {
-          lifetime: new AbortController(),
+          lifetime,
           locale: this.dependencies.localeSource.getLocale(),
           i18n: new PluginTranslationRuntime(this.dependencies.localeSource),
           paseo: createPaseoApi(client),
           invoke: (method, input) => client.invokePluginRpc(entry.id, method, input),
+          subscribe: createPluginSubscribe({
+            client,
+            pluginId: entry.id,
+            lifetime: lifetime.signal,
+          }),
           id: entry.id,
           serverId,
           clientBundle: entry.clientBundle,
@@ -103,9 +122,12 @@ export class PluginRegistry {
           cleanup: () => undefined,
           surfaces: [],
           settingsScreens: [],
+          sidebarViews: [],
           sidebarItems: { header: [], footer: [] },
           legacySidebarItems: [],
           filePanels: [],
+          composerItems: [],
+          newWorkspaceItems: [],
           workspacePanels: [],
           commandCenterItems: [],
           clientSlashCommands: [],
@@ -170,8 +192,14 @@ export class PluginRegistry {
   }
 
   removeHost(serverId: string): void {
+    const hadCatalog = this.catalogStatuses.delete(serverId);
     const installed = this.byHost.get(serverId);
-    if (!installed) return;
+    if (!installed) {
+      if (hadCatalog) {
+        for (const listener of this.listeners) listener();
+      }
+      return;
+    }
     for (const plugin of installed) this.dispose(plugin);
     for (const key of this.evaluationErrors.keys()) {
       if (key.startsWith(`${serverId}/`)) this.evaluationErrors.delete(key);
@@ -246,6 +274,14 @@ export function useInstalledPlugin(serverId: string, pluginId: string): Installe
   );
 }
 
+export function usePluginCatalogStatus(serverId: string): PluginCatalogStatus {
+  return useSyncExternalStore(
+    pluginRegistry.subscribe,
+    () => pluginRegistry.getCatalogStatus(serverId),
+    () => pluginRegistry.getCatalogStatus(serverId),
+  );
+}
+
 export function usePluginInstallations(pluginId: string): InstalledPlugin[] {
   const installed = useInstalledPlugins();
   return useMemo(() => installed.filter((plugin) => plugin.id === pluginId), [installed, pluginId]);
diff --git a/packages/app/src/plugins/settings/device.test.ts b/packages/app/src/plugins/settings/device.test.ts
new file mode 100644
index 0000000000..607e66976b
--- /dev/null
+++ b/packages/app/src/plugins/settings/device.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { createDeviceSettings } from "./device";
+
+function device(records = new Map<string, string>()) {
+  return createDeviceSettings({
+    getItem: async (key) => records.get(key) ?? null,
+    setItem: async (key, value) => {
+      records.set(key, value);
+    },
+  });
+}
+const definition = defineSettings({
+  id: "layout",
+  scope: "device",
+  version: 1,
+  schema: z.object({ collapsed: z.array(z.string()).default([]) }),
+});
+
+describe("device plugin settings", () => {
+  it("shares one installation across hosts and keeps other installations separate", async () => {
+    const settings = device();
+    const first = settings("plugin", definition);
+    const second = settings("plugin", definition);
+    const before = await first.read();
+    expect(before).toEqual({ status: "ready", revision: "missing", values: { collapsed: [] } });
+    const saved = await first.write({ revision: before.revision, values: { collapsed: ["work"] } });
+    expect(saved.status).toBe("saved");
+    expect(await second.read()).toMatchObject({ status: "ready", values: { collapsed: ["work"] } });
+    expect(await settings("other", definition).read()).toEqual(before);
+  });
+  it("serializes competing writes and resets through the same revision contract", async () => {
+    const settings = device()("plugin", definition);
+    const initial = await settings.read();
+    const results = await Promise.all([
+      settings.write({ revision: initial.revision, values: { collapsed: ["a"] } }),
+      settings.write({ revision: initial.revision, values: { collapsed: ["b"] } }),
+    ]);
+    expect(results.map((result) => result.status)).toEqual(["saved", "conflict"]);
+    const current = await settings.read();
+    expect(await settings.reset({ revision: current.revision })).toMatchObject({
+      status: "saved",
+      values: { collapsed: [] },
+    });
+  });
+  it("validates writes and migrates saved layout values", async () => {
+    const settings = device();
+    const first = settings("plugin", definition);
+    expect(await first.write({ revision: "missing", values: { collapsed: 3 } })).toMatchObject({
+      status: "invalid",
+    });
+    await first.write({ revision: "missing", values: { collapsed: ["a"] } });
+    const upgraded = settings(
+      "plugin",
+      defineSettings({
+        ...definition,
+        version: 2,
+        migrate: (_values, from) => ({ collapsed: [`v${from}`] }),
+      }),
+    );
+    expect(await upgraded.read()).toMatchObject({ status: "ready", values: { collapsed: ["v1"] } });
+  });
+});
+
+it("persists a validated migration once and returns the persisted revision across restarts", async () => {
+  const records = new Map<string, string>();
+  const settings = device(records);
+  await settings("plugin", definition).write({ revision: "missing", values: { collapsed: ["a"] } });
+  let migrations = 0;
+  const upgraded = defineSettings({
+    ...definition,
+    version: 2,
+    migrate: () => {
+      migrations++;
+      return { collapsed: ["migrated"] };
+    },
+  });
+  const first = await settings("plugin", upgraded).read();
+  const restarted = device(records)("plugin", upgraded);
+  expect(await restarted.read()).toEqual(first);
+  expect(migrations).toBe(1);
+  expect(first).toEqual({
+    status: "ready",
+    revision: JSON.stringify({ version: 2, values: { collapsed: ["migrated"] } }),
+    values: { collapsed: ["migrated"] },
+  });
+  expect(
+    await restarted.write({
+      revision: JSON.stringify({ version: 1, values: { collapsed: ["a"] } }),
+      values: { collapsed: [] },
+    }),
+  ).toMatchObject({ status: "conflict" });
+  expect(
+    await restarted.write({ revision: first.revision, values: { collapsed: [] } }),
+  ).toMatchObject({ status: "saved" });
+});
diff --git a/packages/app/src/plugins/settings/device.ts b/packages/app/src/plugins/settings/device.ts
new file mode 100644
index 0000000000..523eed599f
--- /dev/null
+++ b/packages/app/src/plugins/settings/device.ts
@@ -0,0 +1,80 @@
+import {
+  settingsRpc,
+  type SettingsDefinition,
+  type RpcOutput,
+  type RpcInput,
+} from "@getpaseo/plugin";
+import { z } from "zod";
+
+interface DeviceStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+type ReadResult = RpcOutput<ReturnType<typeof settingsRpc>["read"]>;
+type WriteResult = RpcOutput<ReturnType<typeof settingsRpc>["write"]>;
+type WriteInput = RpcInput<ReturnType<typeof settingsRpc>["write"]>;
+const envelope = z.object({ version: z.number().int().positive(), values: z.json() });
+
+/** One writer per device; installations with the same id share their layout settings across hosts. */
+export function createDeviceSettings(storage: DeviceStorage) {
+  let queue: Promise<unknown> = Promise.resolve();
+  function serial<T>(work: () => Promise<T>): Promise<T> {
+    const result = queue.then(work);
+    queue = result.catch(() => undefined);
+    return result;
+  }
+  return function settings(installationId: string, definition: SettingsDefinition) {
+    const key = `@paseo:plugin-device-settings:${installationId}/${definition.id}`;
+    async function read(): Promise<ReadResult> {
+      const raw = await storage.getItem(key);
+      let revision = raw ?? "missing";
+      try {
+        let values: unknown = {};
+        let migrated = false;
+        if (raw !== null) {
+          const stored = envelope.parse(JSON.parse(raw));
+          if (stored.version > definition.version)
+            throw new Error("Update this plugin to read its newer settings");
+          values = stored.values;
+          if (stored.version < definition.version) {
+            if (!definition.migrate)
+              throw new Error("This plugin has no migration for its saved settings");
+            values = await definition.migrate(values, stored.version);
+            migrated = true;
+          }
+        }
+        const parsed = z.json().parse(await definition.schema.parseAsync(values));
+        if (migrated) {
+          const serialized = JSON.stringify({ version: definition.version, values: parsed });
+          await storage.setItem(key, serialized);
+          revision = serialized;
+        }
+        return { status: "ready", revision, values: parsed };
+      } catch (error) {
+        return {
+          status: "invalid",
+          revision,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+    function write(input: WriteInput): Promise<WriteResult> {
+      return serial(async () => {
+        const raw = await storage.getItem(key);
+        if ((raw ?? "missing") !== input.revision)
+          return { status: "conflict", error: "Settings changed. Reload before saving." };
+        const parsed = await definition.schema.safeParseAsync(input.values);
+        if (!parsed.success) return { status: "invalid", error: parsed.error.message };
+        const values = z.json().parse(parsed.data);
+        const serialized = JSON.stringify({ version: definition.version, values });
+        await storage.setItem(key, serialized);
+        return { status: "saved", revision: serialized, values };
+      });
+    }
+    return {
+      read: () => serial(read),
+      write,
+      reset: (input: { revision: string }) => write({ revision: input.revision, values: {} }),
+    };
+  };
+}
diff --git a/packages/app/src/plugins/settings/index.tsx b/packages/app/src/plugins/settings/index.tsx
index 3399f241ac..f2e510872a 100644
--- a/packages/app/src/plugins/settings/index.tsx
+++ b/packages/app/src/plugins/settings/index.tsx
@@ -1,17 +1,20 @@
 import { useCallback, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Platform, Text, View } from "react-native";
+import { Platform, ScrollView, Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { router } from "expo-router";
-import { ArrowLeft } from "lucide-react-native";
+import { ArrowLeft, Settings } from "lucide-react-native";
 import type { PluginHostProps } from "@getpaseo/plugin/client";
 import { Button } from "@/components/ui/button";
-import { DropdownMenuItem } from "@/components/ui/dropdown-menu";
+import { ToolbarButton, paneContentToolbarIconSize } from "@/components/ui/pane-content-toolbar";
+import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { useHostFeature } from "@/runtime/host-features";
 import { useHostRuntimeClient, useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import type { Theme } from "@/styles/theme";
+import { PluginIconView } from "../icons";
 import { useInstalledPlugin } from "../registry";
+import type { InstalledPlugin } from "../types";
 import { PluginInstallationProvider } from "../installation-provider";
 import { SurfaceErrorBoundary } from "../surface-error-boundary";
 import { toPluginTheme } from "../theme";
@@ -23,45 +26,84 @@ interface SettingsIdentity {
   screenId: string;
 }
 
-function PluginSettingsMenuItem({
-  serverId,
-  pluginId,
-  screenId,
-  title,
-  disabled,
-}: SettingsIdentity & { title: string; disabled?: boolean }) {
-  const open = useCallback(
-    () => router.push(buildPluginSettingsRoute(serverId, pluginId, screenId)),
-    [serverId, pluginId, screenId],
-  );
+const ThemedSettingsIcon = withUnistyles(Settings);
+const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+/** Opens the plugin's settings at its first screen. Renders nothing when it has none. */
+export function PluginSettingsButton({ serverId, pluginId }: Omit<SettingsIdentity, "screenId">) {
+  const { t } = useTranslation();
+  const plugin = useInstalledPlugin(serverId, pluginId);
+  const supported = useHostFeature(serverId, "pluginSettings");
+  const firstScreenId = plugin?.settingsScreens[0]?.id;
+  const open = useCallback(() => {
+    if (firstScreenId) router.push(buildPluginSettingsRoute(serverId, pluginId, firstScreenId));
+  }, [serverId, pluginId, firstScreenId]);
+  const compact = useIsCompactFormFactor();
+  if (!supported || !firstScreenId) return null;
   return (
-    <DropdownMenuItem onSelect={open} disabled={disabled}>
-      {title}
-    </DropdownMenuItem>
+    <ToolbarButton
+      label={t("settings.plugins.actions.settings")}
+      compact={compact}
+      onPress={open}
+      testID={`plugin-settings-${pluginId}`}
+    >
+      <ThemedSettingsIcon size={paneContentToolbarIconSize(compact)} uniProps={mutedIconMapping} />
+    </ToolbarButton>
   );
 }
 
-export function PluginSettingsMenuItems({
-  serverId,
-  pluginId,
-  disabled,
-}: Omit<SettingsIdentity, "screenId"> & { disabled?: boolean }) {
-  const plugin = useInstalledPlugin(serverId, pluginId);
-  const supported = useHostFeature(serverId, "pluginSettings");
-  if (!supported || !plugin) return null;
+function renderNoIcon() {
+  return null;
+}
+
+/** A plugin-supplied icon component may throw; its tab then shows the label alone. */
+function SettingsTabIcon({
+  plugin,
+  icon,
+  size,
+  color,
+}: {
+  plugin: InstalledPlugin;
+  icon: InstalledPlugin["settingsScreens"][number]["icon"];
+  size: number;
+  color: string;
+}) {
   return (
-    <>
-      {plugin.settingsScreens.map((screen) => (
-        <PluginSettingsMenuItem
-          key={screen.id}
-          serverId={serverId}
-          pluginId={pluginId}
-          screenId={screen.id}
-          title={plugin.i18n.resolve(screen.title, plugin.locale)}
-          disabled={disabled}
-        />
-      ))}
-    </>
+    <SurfaceErrorBoundary installation={plugin} Surface={icon} renderError={renderNoIcon}>
+      <PluginIconView icon={icon} size={size} color={color} />
+    </SurfaceErrorBoundary>
+  );
+}
+
+/**
+ * One tab per registered settings screen. A plugin with a single screen shows no tabs.
+ * Render inside the installation's provider: tab icons may be plugin components.
+ */
+function SettingsTabs({ plugin, screenId }: { plugin: InstalledPlugin; screenId: string }) {
+  const options = useMemo<SegmentedControlOption<string>[]>(
+    () =>
+      plugin.settingsScreens.map((screen) => ({
+        value: screen.id,
+        label: plugin.i18n.resolve(screen.title, plugin.locale),
+        icon: ({ color, size }) => (
+          <SettingsTabIcon plugin={plugin} icon={screen.icon} size={size} color={color} />
+        ),
+        testID: `plugin-settings-tab-${screen.id}`,
+      })),
+    [plugin],
+  );
+  // Tabs swap the screen in place, so Back still returns to the Plugins page.
+  const select = useCallback((id: string) => router.setParams({ screenId: id }), []);
+  if (options.length < 2) return null;
+  return (
+    <ScrollView
+      horizontal
+      showsHorizontalScrollIndicator={false}
+      style={styles.tabs}
+      testID="plugin-settings-tabs"
+    >
+      <SegmentedControl options={options} value={screenId} onValueChange={select} />
+    </ScrollView>
   );
 }
 
@@ -85,7 +127,7 @@ function SettingsContent({
     (error: string) => (
       <View>
         <Text style={styles.message}>{error}</Text>
-        <Button variant="outline" size="sm" onPress={retry}>
+        <Button variant="outline" onPress={retry}>
           {t("common.actions.retry")}
         </Button>
       </View>
@@ -112,18 +154,19 @@ function SettingsContent({
     return <Text style={styles.message}>{t("settings.plugins.screens.unavailable")}</Text>;
   const Component = screen.Component;
   return (
-    <View>
-      <SurfaceErrorBoundary
-        installation={plugin}
-        Surface={Component}
-        resetKey={attempt}
-        renderError={renderError}
-      >
-        <PluginInstallationProvider plugin={plugin}>
+    <PluginInstallationProvider plugin={plugin}>
+      <View>
+        <SettingsTabs plugin={plugin} screenId={screen.id} />
+        <SurfaceErrorBoundary
+          installation={plugin}
+          Surface={Component}
+          resetKey={attempt}
+          renderError={renderError}
+        >
           <Component theme={theme} layout={layout} host={host} />
-        </PluginInstallationProvider>
-      </SurfaceErrorBoundary>
-    </View>
+        </SurfaceErrorBoundary>
+      </View>
+    </PluginInstallationProvider>
   );
 }
 const ThemedSettingsContent = withUnistyles(SettingsContent);
@@ -141,7 +184,6 @@ export function PluginSettingsContent({
         <Button
           onPress={onBackToPlugins}
           variant="ghost"
-          size="sm"
           leftIcon={ArrowLeft}
           style={styles.backButton}
         >
@@ -154,5 +196,6 @@ export function PluginSettingsContent({
 }
 const styles = StyleSheet.create((theme) => ({
   message: { color: theme.colors.foregroundMuted },
+  tabs: { flexGrow: 0, marginBottom: theme.spacing[4] },
   backButton: { alignSelf: "flex-start", paddingHorizontal: 0, marginBottom: theme.spacing[4] },
 }));
diff --git a/packages/app/src/plugins/settings/use-settings.ts b/packages/app/src/plugins/settings/use-settings.ts
index decf4bfe05..b65dc4dc03 100644
--- a/packages/app/src/plugins/settings/use-settings.ts
+++ b/packages/app/src/plugins/settings/use-settings.ts
@@ -1,3 +1,6 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { queryClient as appQueryClient } from "@/data/query-client";
+import { createDeviceSettings } from "./device";
 import type { SettingsState } from "@getpaseo/plugin/client";
 import { useMemo } from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
@@ -8,6 +11,8 @@ import { useReplicaQuery } from "@/data/query";
 import { z, type ZodType } from "zod";
 import { pluginSettingsKey } from "./query";
 
+const deviceSettings = createDeviceSettings(AsyncStorage);
+
 function message(error: unknown): string {
   if (error instanceof z.ZodError) return error.issues.map((issue) => issue.message).join("\n");
   return error instanceof Error ? error.message : String(error);
@@ -15,34 +20,49 @@ function message(error: unknown): string {
 
 export function useSettings<Schema extends ZodType>(
   definition: SettingsDefinition<Schema>,
+  installationId: string,
 ): SettingsState<Schema> {
   const rpc = useMemo(() => settingsRpc(definition.id), [definition.id]);
   const read = useRpc(rpc.read);
   const write = useRpc(rpc.write);
   const reset = useRpc(rpc.reset);
-  const client = useQueryClient();
-  const key = pluginSettingsKey(definition.id);
-  const query = useReplicaQuery({
-    queryKey: key,
-    pushEvent: "plugin_settings_changed",
-    queryFn: () => read({}),
-    retry: false,
-  });
-  const mutation = useMutation({
-    mutationFn: async (
-      input: { revision: string; values: z.output<Schema> } | { revision: string },
-    ) => {
-      const result =
-        "values" in input
-          ? await write({
-              revision: input.revision,
-              values: z.json().parse(await definition.schema.parseAsync(input.values)),
-            })
-          : await reset(input);
-      if (result.status !== "saved") throw new Error(result.error);
-      client.setQueryData(key, { ...result, status: "ready" });
+  const installationClient = useQueryClient();
+  const device = definition.scope === "device";
+  const client = device ? appQueryClient : installationClient;
+  const key = device
+    ? ["plugin-device-settings", installationId, definition.id, definition.version]
+    : pluginSettingsKey(definition.id);
+  const local = useMemo(
+    () => deviceSettings(installationId, definition),
+    [installationId, definition],
+  );
+  const query = useReplicaQuery(
+    {
+      queryKey: key,
+      pushEvent: device ? "plugin_device_settings_saved" : "plugin_settings_changed",
+      queryFn: () => (device ? local.read() : read({})),
+      retry: false,
     },
-  });
+    client,
+  );
+  const mutation = useMutation(
+    {
+      mutationFn: async (
+        input: { revision: string; values: z.output<Schema> } | { revision: string },
+      ) => {
+        const result =
+          "values" in input
+            ? await (device ? local.write : write)({
+                revision: input.revision,
+                values: z.json().parse(await definition.schema.parseAsync(input.values)),
+              })
+            : await (device ? local.reset : reset)(input);
+        if (result.status !== "saved") throw new Error(result.error);
+        client.setQueryData(key, { ...result, status: "ready" });
+      },
+    },
+    client,
+  );
   async function save(values: z.output<Schema>, revision: string) {
     try {
       await mutation.mutateAsync({ values, revision });
diff --git a/packages/app/src/plugins/sidebar-groups.test.ts b/packages/app/src/plugins/sidebar-groups.test.ts
index e204c28d9d..635f3d8eac 100644
--- a/packages/app/src/plugins/sidebar-groups.test.ts
+++ b/packages/app/src/plugins/sidebar-groups.test.ts
@@ -26,14 +26,20 @@ function installed(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     settingsScreens: [],
     surfaces: [{ id: "surface", title: "Surface", Component: () => null }],
+    sidebarViews: [],
     sidebarItems: {
       header: [{ id: contributionId, title: "Example", Component: () => null }],
       footer: [{ id: "status", title: "Status", Component: () => null }],
     },
     legacySidebarItems,
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
diff --git a/packages/app/src/plugins/sidebar-view/catalog.ts b/packages/app/src/plugins/sidebar-view/catalog.ts
new file mode 100644
index 0000000000..3711cb8414
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/catalog.ts
@@ -0,0 +1,25 @@
+import type { InstalledPlugin } from "../types";
+
+export interface SidebarViewEntry {
+  id: string;
+  title: string;
+  plugin: InstalledPlugin;
+  view: InstalledPlugin["sidebarViews"][number];
+}
+
+export function sidebarViews(plugins: readonly InstalledPlugin[]): SidebarViewEntry[] {
+  const entries = new Map<string, SidebarViewEntry>();
+  for (const plugin of plugins) {
+    for (const view of plugin.sidebarViews) {
+      const id = `${plugin.id}/${view.id}`;
+      if (!entries.has(id))
+        entries.set(id, {
+          id,
+          title: plugin.i18n.resolve(view.title, plugin.locale),
+          plugin,
+          view,
+        });
+    }
+  }
+  return [...entries.values()];
+}
diff --git a/packages/app/src/plugins/sidebar-view/frame.browser.test.tsx b/packages/app/src/plugins/sidebar-view/frame.browser.test.tsx
new file mode 100644
index 0000000000..730b80e292
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/frame.browser.test.tsx
@@ -0,0 +1,69 @@
+import React, { act, useMemo } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, expect, it } from "vitest";
+import { SidebarViewFrame } from "./frame";
+import { useSidebarViewSelection, type SidebarViewStorage } from "./selection";
+
+const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+let defaultRenders = 0;
+function DefaultView() {
+  defaultRenders++;
+  return <div>Default sidebar</div>;
+}
+function PluginView() {
+  return <div>Stored plugin sidebar</div>;
+}
+function Sidebar({ storage }: { storage: SidebarViewStorage }) {
+  const selection = useSidebarViewSelection(storage);
+  const fallback = useMemo(() => <DefaultView />, []);
+  const selected =
+    selection.state.status === "ready" && selection.state.selection === "example/workspaces";
+  const view = selected ? <PluginView /> : null;
+  return (
+    <SidebarViewFrame state={selection.state} fallback={fallback} reload={selection.reload}>
+      {view}
+    </SidebarViewFrame>
+  );
+}
+afterEach(() => {
+  act(() => root?.unmount());
+  container?.remove();
+  root = null;
+  container = null;
+  defaultRenders = 0;
+  client.clear();
+});
+
+function deferredStorage() {
+  let finishRead: (value: string) => void = () => {
+    throw new Error("Read not started");
+  };
+  const read = new Promise<string>((resolve) => {
+    finishRead = resolve;
+  });
+  const storage: SidebarViewStorage = { getItem: () => read, setItem: async () => {} };
+  return { storage, finishRead };
+}
+
+it("never renders the default before a stored plugin selection is known", async () => {
+  const { storage, finishRead } = deferredStorage();
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  await act(async () =>
+    root?.render(
+      <QueryClientProvider client={client}>
+        <Sidebar storage={storage} />
+      </QueryClientProvider>,
+    ),
+  );
+  expect(defaultRenders).toBe(0);
+  await act(async () => {
+    finishRead("example/workspaces");
+  });
+  await expect.poll(() => container?.textContent).toContain("Stored plugin sidebar");
+  expect(defaultRenders).toBe(0);
+});
diff --git a/packages/app/src/plugins/sidebar-view/frame.tsx b/packages/app/src/plugins/sidebar-view/frame.tsx
new file mode 100644
index 0000000000..c059530be8
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/frame.tsx
@@ -0,0 +1,34 @@
+import { SidebarAgentListSkeleton } from "@/components/sidebar-agent-list-skeleton";
+import type { ReactNode } from "react";
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/button";
+import type { SidebarViewSelectionState } from "./selection";
+
+export function SidebarViewFrame({
+  state,
+  fallback,
+  children,
+  reload,
+}: {
+  state: SidebarViewSelectionState;
+  fallback: ReactNode;
+  children: ReactNode;
+  reload(): void;
+}) {
+  const { t } = useTranslation();
+  if (state.status === "loading") return <SidebarAgentListSkeleton />;
+  if (state.status === "error")
+    return (
+      <View style={styles.failure}>
+        <Text style={styles.text}>{t("sidebar.view.readFailed")}</Text>
+        <Button onPress={reload}>{t("common.actions.retry")}</Button>
+      </View>
+    );
+  return children ?? fallback;
+}
+const styles = StyleSheet.create((theme) => ({
+  failure: { padding: theme.spacing[4], gap: theme.spacing[3] },
+  text: { color: theme.colors.foreground },
+}));
diff --git a/packages/app/src/plugins/sidebar-view/index.tsx b/packages/app/src/plugins/sidebar-view/index.tsx
new file mode 100644
index 0000000000..266ae9b1c6
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/index.tsx
@@ -0,0 +1,173 @@
+import { useTranslation } from "react-i18next";
+import { SidebarViewFrame } from "./frame";
+import type { PluginSidebarViewProps } from "@getpaseo/plugin/client";
+import type { PluginTheme } from "@getpaseo/plugin";
+import { router } from "expo-router";
+import { useMemo, useCallback, type ReactNode } from "react";
+import { Text, View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { Button } from "@/components/ui/button";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { useToast } from "@/contexts/toast-context";
+import {
+  navigateToWorkspace,
+  useActiveWorkspaceSelection,
+} from "@/stores/navigation-active-workspace-store";
+import { useSessionStore } from "@/stores/session-store";
+import { buildNewWorkspaceRoute } from "@/utils/host-routes";
+import type { Theme } from "@/styles/theme";
+import { createPluginClientStateSource } from "../client-state/source";
+import { entityRefs } from "../client-state/refs";
+import { PluginEnvironmentProvider } from "../popover";
+import { resolvePluginPlatform } from "../platform";
+import { useInstalledPlugins } from "../registry";
+import { SurfaceErrorBoundary } from "../surface-error-boundary";
+import { toPluginTheme } from "../theme";
+import { sidebarViews, type SidebarViewEntry } from "./catalog";
+import { useSidebarViewSelection } from "./selection";
+
+const source = createPluginClientStateSource();
+const themeMapping = (theme: Theme) => ({ theme: toPluginTheme(theme) });
+
+export function SidebarViewSlot({ children, dismiss }: { children: ReactNode; dismiss(): void }) {
+  const { t } = useTranslation();
+  const installed = useInstalledPlugins();
+  const { state, reload, setSelection, pending, error } = useSidebarViewSelection();
+  const restoreDefault = useCallback(() => setSelection("default"), [setSelection]);
+  const renderError = useCallback(
+    () => (
+      <View style={styles.placeholder}>
+        <Text style={styles.text}>{t("sidebar.view.failed")}</Text>
+        <Button onPress={restoreDefault} disabled={pending}>
+          {t("sidebar.view.useDefault")}
+        </Button>
+        {error ? <Text style={styles.text}>{error.message}</Text> : null}
+      </View>
+    ),
+    [restoreDefault, pending, error, t],
+  );
+  const entry =
+    state.status === "ready"
+      ? sidebarViews(installed).find((view) => view.id === state.selection)
+      : undefined;
+  const view = entry ? (
+    <View style={styles.content} testID="plugin-sidebar-view">
+      <SurfaceErrorBoundary
+        installation={entry.plugin}
+        Surface={entry.view.Component}
+        renderError={renderError}
+      >
+        <ThemedSidebarView entry={entry} dismiss={dismiss} uniProps={themeMapping} />
+      </SurfaceErrorBoundary>
+    </View>
+  ) : null;
+  return (
+    <SidebarViewFrame state={state} fallback={children} reload={reload}>
+      {view}
+    </SidebarViewFrame>
+  );
+}
+
+function SidebarView({
+  entry,
+  dismiss,
+  theme,
+}: {
+  entry: SidebarViewEntry;
+  dismiss(): void;
+  theme: PluginTheme;
+}) {
+  const { t } = useTranslation();
+  const toast = useToast();
+  const compact = useIsCompactFormFactor();
+  const selection = useActiveWorkspaceSelection();
+  const focusedAgentId = useSessionStore((state) =>
+    selection ? (state.sessions[selection.serverId]?.focusedAgentId ?? null) : null,
+  );
+  const activeWorkspace = selection
+    ? entityRefs.workspace(selection.serverId, selection.workspaceId)
+    : null;
+  const activeAgent =
+    selection && focusedAgentId ? entityRefs.agent(selection.serverId, focusedAgentId) : null;
+  const environment = useMemo(
+    () => ({ installation: entry.plugin, state: source, toast }),
+    [entry.plugin, toast],
+  );
+  const navigation = useMemo<PluginSidebarViewProps["navigation"]>(
+    () => ({
+      openWorkspace(ref) {
+        navigateToWorkspace({ serverId: ref.hostId, workspaceId: ref.id });
+        dismiss();
+      },
+      openAgent(ref) {
+        const agent = source.getAgent(ref);
+        if (!agent) {
+          toast.error(t("sidebar.view.agentUnavailable"));
+          return;
+        }
+        navigateToWorkspace({
+          serverId: ref.hostId,
+          workspaceId: agent.workspace.id,
+          target: { kind: "agent", agentId: ref.id },
+        });
+        dismiss();
+      },
+      openTerminal(ref) {
+        const terminal = source.getTerminal(ref);
+        if (!terminal) {
+          toast.error(t("sidebar.view.terminalUnavailable"));
+          return;
+        }
+        navigateToWorkspace({
+          serverId: ref.hostId,
+          workspaceId: terminal.workspace.id,
+          target: { kind: "terminal", terminalId: ref.id },
+        });
+        dismiss();
+      },
+      openProject(ref) {
+        const project = source.getProject(ref);
+        if (!project) {
+          toast.error(t("sidebar.view.projectUnavailable"));
+          return;
+        }
+        router.push(
+          buildNewWorkspaceRoute({
+            serverId: ref.hostId,
+            projectId: ref.id,
+            sourceDirectory: project.rootPath,
+            displayName: project.displayName,
+          }),
+        );
+        dismiss();
+      },
+    }),
+    [dismiss, toast, t],
+  );
+  const layout = useMemo(() => ({ compact, platform: resolvePluginPlatform() }), [compact]);
+  const active = useMemo(
+    () => ({ workspace: activeWorkspace, agent: activeAgent }),
+    [activeWorkspace, activeAgent],
+  );
+  const Component = entry.view.Component;
+  return (
+    <PluginEnvironmentProvider environment={environment}>
+      <Component
+        theme={theme}
+        layout={layout}
+        active={active}
+        navigation={navigation}
+        dismiss={dismiss}
+      />
+    </PluginEnvironmentProvider>
+  );
+}
+const ThemedSidebarView = withUnistyles(SidebarView);
+
+const styles = StyleSheet.create((theme) => ({
+  content: { flex: 1 },
+  placeholder: { padding: theme.spacing[4], gap: theme.spacing[3] },
+  text: { color: theme.colors.foreground },
+}));
+
+export { SidebarViewPicker } from "./picker";
diff --git a/packages/app/src/plugins/sidebar-view/picker.tsx b/packages/app/src/plugins/sidebar-view/picker.tsx
new file mode 100644
index 0000000000..920df1c797
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/picker.tsx
@@ -0,0 +1,58 @@
+import { Text } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { useTranslation } from "react-i18next";
+import { SettingsCard, SettingsRow, SettingsSection, SettingsSelect } from "@/components/settings";
+import { Button } from "@/components/ui/button";
+import { useInstalledPlugins } from "../registry";
+import { sidebarViews } from "./catalog";
+import { useSidebarViewSelection } from "./selection";
+
+export function SidebarViewPicker() {
+  const { t } = useTranslation();
+  const views = sidebarViews(useInstalledPlugins());
+  const { state, reload, setSelection, pending, error } = useSidebarViewSelection();
+  let content;
+  if (state.status === "loading") {
+    content = (
+      <SettingsRow label={t("settings.appearance.sidebar.view.label")}>
+        <Text style={styles.message}>{t("common.loading")}</Text>
+      </SettingsRow>
+    );
+  } else if (state.status === "error") {
+    content = (
+      <SettingsRow
+        label={t("settings.appearance.sidebar.view.label")}
+        hint={t("sidebar.view.readFailed")}
+      >
+        <Button onPress={reload}>{t("common.actions.retry")}</Button>
+      </SettingsRow>
+    );
+  } else {
+    const missing =
+      state.selection !== "default" && !views.some((view) => view.id === state.selection);
+    const value = missing ? "default" : state.selection;
+    let hint: string | undefined;
+    if (missing) hint = t("settings.appearance.sidebar.view.unavailable");
+    if (error) hint = error.message;
+    const options = [
+      { value: "default", label: t("settings.appearance.sidebar.view.default") },
+      ...views.map((view) => ({ value: view.id, label: view.title })),
+    ];
+    content = (
+      <SettingsSelect
+        label={t("settings.appearance.sidebar.view.label")}
+        value={value}
+        options={options}
+        onValueChange={setSelection}
+        disabled={pending}
+        hint={hint}
+      />
+    );
+  }
+  return (
+    <SettingsSection title={t("settings.appearance.sidebar.view.title")}>
+      <SettingsCard>{content}</SettingsCard>
+    </SettingsSection>
+  );
+}
+const styles = StyleSheet.create((theme) => ({ message: { color: theme.colors.foregroundMuted } }));
diff --git a/packages/app/src/plugins/sidebar-view/selection.ts b/packages/app/src/plugins/sidebar-view/selection.ts
new file mode 100644
index 0000000000..f1c8eb08a2
--- /dev/null
+++ b/packages/app/src/plugins/sidebar-view/selection.ts
@@ -0,0 +1,47 @@
+import { useCallback } from "react";
+import { useFetchQuery } from "@/data/query";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+const key = "sidebar.view";
+const queryKey = [key];
+
+export interface SidebarViewStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+export type SidebarViewSelectionState =
+  | { status: "loading" }
+  | { status: "error"; error: Error }
+  | { status: "ready"; selection: string };
+
+export function useSidebarViewSelection(storage: SidebarViewStorage = AsyncStorage) {
+  const client = useQueryClient();
+  const query = useFetchQuery({
+    queryKey,
+    queryFn: async () => (await storage.getItem(key)) ?? "default",
+    dataShape: "value",
+    immutableWhen: () => true,
+  });
+  const save = useMutation({
+    mutationFn: (selection: string) => storage.setItem(key, selection),
+    onSuccess: (_result, selection) => {
+      client.setQueryData(queryKey, selection);
+    },
+  });
+  let state: SidebarViewSelectionState;
+  if (query.isPending) state = { status: "loading" };
+  else if (query.isError) state = { status: "error", error: query.error };
+  else state = { status: "ready", selection: query.data };
+  const { refetch } = query;
+  const reload = useCallback(() => {
+    void refetch();
+  }, [refetch]);
+  return {
+    state,
+    reload,
+    setSelection: save.mutate,
+    pending: save.isPending,
+    error: save.error,
+  };
+}
diff --git a/packages/app/src/plugins/subscriptions.test.ts b/packages/app/src/plugins/subscriptions.test.ts
new file mode 100644
index 0000000000..927a54c178
--- /dev/null
+++ b/packages/app/src/plugins/subscriptions.test.ts
@@ -0,0 +1,189 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import type { PluginSubscriptionClosed } from "@getpaseo/plugin/client";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { SubscriptionObserver } from "@getpaseo/client";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { expect, it } from "vitest";
+import { z } from "zod";
+import { createPluginSubscribe } from "./subscriptions";
+
+const changes = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ ref: z.string() }),
+  event: z.union([z.instanceof(Uint8Array), z.object({ path: z.string() })]),
+});
+
+type Observed = Parameters<DaemonClient["observePluginRpc"]>;
+
+/** One host-side subscription as the daemon client exposes it, driven by the test. */
+class HostSubscription {
+  readonly released: Promise<void>;
+  isReleased = false;
+  private observer: SubscriptionObserver<never> | null = null;
+  private accept!: () => void;
+  private refuse!: (error: Error) => void;
+  private markReleased!: () => void;
+  readonly ready = new Promise<never>((resolve, reject) => {
+    this.accept = () => resolve({ requestId: "r", subscriptionId: "s" } as never);
+    this.refuse = reject;
+  });
+
+  constructor(
+    readonly method: string,
+    readonly input: unknown,
+    readonly signal: AbortSignal | undefined,
+  ) {
+    void this.ready.catch(() => undefined);
+    this.released = new Promise((resolve) => {
+      this.markReleased = resolve;
+    });
+    signal?.addEventListener("abort", () => void this.release(), { once: true });
+  }
+
+  handle() {
+    return {
+      subscriptionId: "s",
+      ready: this.ready,
+      subscribe: (observer: SubscriptionObserver<never>) => {
+        this.observer = observer;
+        return () => undefined;
+      },
+      release: () => this.release(),
+    };
+  }
+
+  acknowledge() {
+    this.accept();
+  }
+
+  refuseWith(error: Error) {
+    this.refuse(error);
+    this.observer?.error?.(error);
+  }
+
+  event(event: unknown) {
+    this.observer?.update({
+      type: "plugin.rpc.event",
+      payload: { subscriptionId: "s", event },
+    } as SessionOutboundMessage);
+  }
+
+  bytes(payload: Uint8Array) {
+    this.observer?.binary?.(payload);
+  }
+
+  closed(error?: string) {
+    this.observer?.update({
+      type: "plugin.rpc.closed",
+      payload: { subscriptionId: "s", ...(error ? { error } : {}) },
+    } as SessionOutboundMessage);
+  }
+
+  async release() {
+    this.isReleased = true;
+    this.markReleased();
+  }
+}
+
+/** An installation's subscribe on a host the test drives, and what one subscriber observed. */
+function installation() {
+  const subscriptions: HostSubscription[] = [];
+  const client = {
+    observePluginRpc: (...[pluginId, method, input, options]: Observed) => {
+      expect(pluginId).toBe("diffs");
+      const subscription = new HostSubscription(method, input, options?.signal);
+      subscriptions.push(subscription);
+      return subscription.handle() as unknown as ReturnType<DaemonClient["observePluginRpc"]>;
+    },
+  };
+  const lifetime = new AbortController();
+  const subscribe = createPluginSubscribe({ client, pluginId: "diffs", lifetime: lifetime.signal });
+  function open(ref: string, signal?: AbortSignal) {
+    const received: string[] = [];
+    const closed: PluginSubscriptionClosed[] = [];
+    const handle = subscribePluginRpc(
+      changes,
+      subscribe,
+      { ref },
+      (event) =>
+        received.push(event instanceof Uint8Array ? `bytes:${[...event]}` : `path:${event.path}`),
+      { signal, onClosed: (result) => closed.push(result) },
+    );
+    return { handle, received, closed, host: subscriptions[subscriptions.length - 1]! };
+  }
+  return { open, lifetime };
+}
+
+it("delivers JSON and byte events in order and releases the host subscription", async () => {
+  const { open } = installation();
+  const { handle, received, closed, host } = open("main");
+  expect(host.method).toBe("diff.watch");
+  expect(host.input).toEqual({ ref: "main" });
+  host.acknowledge();
+  await handle.ready;
+
+  host.event({ path: "a.ts" });
+  host.bytes(new Uint8Array([1, 2]));
+  expect(received).toEqual(["path:a.ts", "bytes:1,2"]);
+
+  handle();
+  await host.released;
+  expect(closed).toEqual([]);
+});
+
+it("reports a refusal, a failure after going live, and a clean close", async () => {
+  const { open } = installation();
+  const refused = open("a");
+  refused.host.refuseWith(new Error("no such ref"));
+  await expect(refused.handle.ready).rejects.toThrow("no such ref");
+  expect(refused.closed).toEqual([{ error: new Error("no such ref") }]);
+
+  const failed = open("b");
+  failed.host.acknowledge();
+  await failed.handle.ready;
+  failed.host.closed("Plugin stopped: diffs");
+  expect(failed.closed).toEqual([{ error: new Error("Plugin stopped: diffs") }]);
+  await failed.host.released;
+
+  // A handler that returns at once closes in the same tick the host accepts it.
+  const finished = open("c");
+  finished.host.acknowledge();
+  finished.host.closed();
+  await expect(finished.handle.ready).resolves.toBeUndefined();
+  expect(finished.closed).toEqual([{}]);
+});
+
+it("closes a subscription whose event fails the contract and drops what follows", async () => {
+  const { open } = installation();
+  const { handle, received, closed, host } = open("a");
+  host.acknowledge();
+  await handle.ready;
+  host.event({ path: 3 });
+  host.event({ path: "late.ts" });
+  expect(received).toEqual([]);
+  expect(closed).toEqual([
+    { error: new Error("Plugin subscription diff.watch sent an invalid event") },
+  ]);
+  await host.released;
+});
+
+it("releases on its signal, on its remover, and when the installation stops", async () => {
+  const { open, lifetime } = installation();
+  const controller = new AbortController();
+  const bySignal = open("a", controller.signal);
+  bySignal.host.acknowledge();
+  await bySignal.handle.ready;
+  controller.abort();
+  await bySignal.host.released;
+
+  const byRemover = open("b");
+  byRemover.handle();
+  await byRemover.host.released;
+
+  const byLifetime = open("c");
+  byLifetime.host.event({ path: "a.ts" });
+  expect(byLifetime.received).toEqual(["path:a.ts"]);
+  lifetime.abort();
+  await byLifetime.host.released;
+});
diff --git a/packages/app/src/plugins/subscriptions.ts b/packages/app/src/plugins/subscriptions.ts
new file mode 100644
index 0000000000..bff6614682
--- /dev/null
+++ b/packages/app/src/plugins/subscriptions.ts
@@ -0,0 +1,52 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { PluginSubscribe } from "@getpaseo/plugin/client/host";
+
+/**
+ * Plugin subscriptions on the installation's client. The client re-subscribes after a reconnect;
+ * the installation's lifetime releases whatever its surfaces left open.
+ */
+export function createPluginSubscribe(input: {
+  client: Pick<DaemonClient, "observePluginRpc">;
+  pluginId: string;
+  lifetime: AbortSignal;
+}): PluginSubscribe {
+  const { client, pluginId, lifetime } = input;
+  return (method, subscriptionInput, observer) => {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    lifetime.addEventListener("abort", abort, { once: true });
+    controller.signal.addEventListener(
+      "abort",
+      () => lifetime.removeEventListener("abort", abort),
+      { once: true },
+    );
+    if (lifetime.aborted) controller.abort();
+    const subscription = client.observePluginRpc(pluginId, method, subscriptionInput, {
+      signal: controller.signal,
+    });
+    subscription.subscribe({
+      snapshot: () => undefined,
+      update: (message) => {
+        if (message.type === "plugin.rpc.event") observer.event(message.payload.event);
+        else if (message.type === "plugin.rpc.closed") {
+          controller.abort();
+          const error = message.payload.error;
+          observer.closed(error === undefined ? undefined : new Error(error));
+        }
+      },
+      binary: (payload) => observer.event(payload),
+      error: (error) => {
+        controller.abort();
+        observer.closed(error instanceof Error ? error : new Error(String(error)));
+      },
+    });
+    const release = () => {
+      controller.abort();
+      return subscription.release();
+    };
+    return Object.assign(() => void release().catch(() => undefined), {
+      ready: subscription.ready.then(() => undefined),
+      release,
+    });
+  };
+}
diff --git a/packages/app/src/plugins/surface-contribution.test.ts b/packages/app/src/plugins/surface-contribution.test.ts
index 7e5f603ec1..8af246cf81 100644
--- a/packages/app/src/plugins/surface-contribution.test.ts
+++ b/packages/app/src/plugins/surface-contribution.test.ts
@@ -8,8 +8,25 @@ import {
   parsePluginOpenScreenInput,
   resolvePluginScreenTitle,
   resolvePluginSurfaceContribution,
+  resolvePluginSurfacePlaceholder,
 } from "./surface-contribution";
 
+it("shows loading instead of unavailable while the host catalog is pending", () => {
+  expect(
+    resolvePluginSurfacePlaceholder({ connectionStatus: "online", catalogStatus: "loading" }),
+  ).toBe("loading");
+});
+
+it.each([
+  ["online", "ready", "unavailable"],
+  ["online", "error", "error"],
+  ["connecting", "ready", "loading"],
+  ["offline", "loading", "offline"],
+  ["error", "loading", "offline"],
+] as const)("shows %s host with %s catalog as %s", (connectionStatus, catalogStatus, expected) => {
+  expect(resolvePluginSurfacePlaceholder({ connectionStatus, catalogStatus })).toBe(expected);
+});
+
 function installation(
   serverId: string,
   surfaces: string[],
@@ -26,9 +43,13 @@ function installation(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => undefined,
     settingsScreens: [],
     surfaces: surfaces.map((id) => ({ id, title: id, Component: () => null })),
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: sidebarItems.map((item) => ({
       ...item,
@@ -36,6 +57,8 @@ function installation(
       icon: "Blocks",
     })),
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
diff --git a/packages/app/src/plugins/surface-contribution.ts b/packages/app/src/plugins/surface-contribution.ts
index a226e1f55c..7d1d2c665c 100644
--- a/packages/app/src/plugins/surface-contribution.ts
+++ b/packages/app/src/plugins/surface-contribution.ts
@@ -5,6 +5,26 @@ import {
   pluginScreenParamsFromRoute,
 } from "./routes";
 import type { InstalledPlugin } from "./types";
+import type { PluginCatalogStatus } from "./registry";
+import type { HostRuntimeConnectionStatus } from "@/runtime/host-runtime";
+
+export type PluginSurfacePlaceholderStatus = "loading" | "offline" | "error" | "unavailable";
+
+interface PluginSurfacePlaceholderInput {
+  connectionStatus: HostRuntimeConnectionStatus;
+  catalogStatus: PluginCatalogStatus;
+}
+
+export function resolvePluginSurfacePlaceholder({
+  connectionStatus,
+  catalogStatus,
+}: PluginSurfacePlaceholderInput): PluginSurfacePlaceholderStatus {
+  if (connectionStatus === "offline" || connectionStatus === "error") return "offline";
+  if (connectionStatus !== "online") return "loading";
+  if (catalogStatus === "loading") return "loading";
+  if (catalogStatus === "error") return "error";
+  return "unavailable";
+}
 
 export type PluginSurfaceContributionIdentity =
   | { kind: "sidebar"; id: string }
diff --git a/packages/app/src/plugins/surface-screen.tsx b/packages/app/src/plugins/surface-screen.tsx
index 849775addd..b0d4a2368b 100644
--- a/packages/app/src/plugins/surface-screen.tsx
+++ b/packages/app/src/plugins/surface-screen.tsx
@@ -12,14 +12,19 @@ import { ScreenHeader } from "@/components/headers/screen-header";
 import { ScreenTitle } from "@/components/headers/screen-title";
 import { HostFilter } from "@/components/hosts/host-filter";
 import type { HostPickerHost } from "@/components/hosts/host-picker";
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import { useHostRuntimeClient, useHosts } from "@/runtime/host-runtime";
+import {
+  useHostRuntimeClient,
+  useHostRuntimeConnectionStatus,
+  useHosts,
+} from "@/runtime/host-runtime";
 import type { Theme } from "@/styles/theme";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { usePluginHostNavigation } from "./host-navigation";
 import { PluginIconView } from "./icons";
 import { toPluginTheme } from "./theme";
-import { useInstalledPlugin, usePluginInstallations } from "./registry";
+import { useInstalledPlugin, usePluginCatalogStatus, usePluginInstallations } from "./registry";
 import { buildPluginSurfaceRoute, pluginScreenParamsFromRoute } from "./routes";
 import {
   legacySidebarItemHostKey,
@@ -32,7 +37,9 @@ import {
   getPluginSurfaceContributionServerIds,
   resolvePluginScreenTitle,
   resolvePluginSurfaceContribution,
+  resolvePluginSurfacePlaceholder,
   type PluginSurfaceContributionIdentity,
+  type PluginSurfacePlaceholderStatus,
 } from "./surface-contribution";
 import { resolvePluginPlatform } from "./platform";
 
@@ -42,6 +49,28 @@ const pluginThemeMapping = (theme: Theme) => ({
   theme: toPluginTheme(theme),
 });
 const ThemedX = withUnistyles(X);
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const SURFACE_ERRORS = {
+  offline: "Plugin host is offline.",
+  error: "Could not load plugins. Reconnect to try again.",
+  unavailable: "This plugin surface is unavailable.",
+} as const;
+
+function PluginSurfacePlaceholder({ status }: { status: PluginSurfacePlaceholderStatus }) {
+  if (status === "loading") {
+    return (
+      <View
+        testID="plugin-surface-loading"
+        accessibilityRole="progressbar"
+        accessibilityLabel="Loading plugin"
+        style={styles.loading}
+      >
+        <ThemedLoadingSpinner size="large" uniProps={mutedColorMapping} />
+      </View>
+    );
+  }
+  return <Text style={styles.errorText}>{SURFACE_ERRORS[status]}</Text>;
+}
 
 function routeParam(value: string | string[] | undefined): string {
   return typeof value === "string" ? value : "";
@@ -137,6 +166,9 @@ export function PluginSurfaceScreen() {
   const installations = usePluginInstallations(pluginId);
   const hosts = useHosts();
   const client = useHostRuntimeClient(serverId);
+  const connectionStatus = useHostRuntimeConnectionStatus(serverId);
+  const catalogStatus = usePluginCatalogStatus(serverId);
+  const placeholderStatus = resolvePluginSurfacePlaceholder({ connectionStatus, catalogStatus });
   const compact = useIsCompactFormFactor();
   const { sidebarItem, surface } = useMemo(
     () => resolvePluginSurfaceContribution(plugin, identity),
@@ -239,9 +271,7 @@ export function PluginSurfaceScreen() {
             />
           </SurfaceErrorBoundary>
         ) : (
-          <Text style={styles.errorText}>
-            {plugin && surface ? "Plugin host is offline." : "This plugin surface is unavailable."}
-          </Text>
+          <PluginSurfacePlaceholder status={placeholderStatus} />
         )}
       </View>
     </View>
@@ -256,6 +286,11 @@ const styles = StyleSheet.create((theme) => ({
   body: {
     flex: 1,
   },
+  loading: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   errorText: {
     color: theme.colors.statusDanger,
     padding: theme.spacing[4],
diff --git a/packages/app/src/plugins/theme.test.ts b/packages/app/src/plugins/theme.test.ts
index 08ac674ca0..aeb7872a2e 100644
--- a/packages/app/src/plugins/theme.test.ts
+++ b/packages/app/src/plugins/theme.test.ts
@@ -56,11 +56,17 @@ function installed(serverId: string, themes: PluginThemeContribution[]): Install
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     settingsScreens: [],
     surfaces: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
diff --git a/packages/app/src/plugins/timeline/model.test.ts b/packages/app/src/plugins/timeline/model.test.ts
index ffd33ef0ff..957bd18686 100644
--- a/packages/app/src/plugins/timeline/model.test.ts
+++ b/packages/app/src/plugins/timeline/model.test.ts
@@ -18,12 +18,18 @@ function plugin(input: {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => {},
     settingsScreens: [],
     surfaces: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [],
     commandCenterItems: [],
     clientSlashCommands: [],
diff --git a/packages/app/src/plugins/timeline/projection.test.ts b/packages/app/src/plugins/timeline/projection.test.ts
index 2dc95ed339..58d36ad87c 100644
--- a/packages/app/src/plugins/timeline/projection.test.ts
+++ b/packages/app/src/plugins/timeline/projection.test.ts
@@ -14,6 +14,45 @@ function thought(text: string, status: "loading" | "ready" = "loading"): StreamI
 }
 
 describe("plugin timeline projection", () => {
+  it.each(["message", "finished", "errored", "permission-required", "closed"] as const)(
+    "preserves immutable agent-message provenance for %s cards",
+    (event) => {
+      const agentMessage = {
+        event,
+        sender: { id: "remote::reviewer", title: "QA question-timing #7014/#7000/#6809" },
+        text: "The original message, including **Markdown**.",
+      };
+      const source: StreamItem = {
+        kind: "tool_call",
+        id: "message-1",
+        timestamp: new Date("2026-01-01T00:00:00.000Z"),
+        payload: {
+          source: "agent",
+          data: {
+            provider: "codex",
+            callId: "delivery-1",
+            name: "agent_message",
+            status: "completed",
+            error: null,
+            detail: { type: "plain_text", text: agentMessage.text, icon: "bot" },
+            agentMessage,
+          },
+        },
+      };
+      const inspect: TimelineItemTransform = ({ item }) => {
+        expect(item.type).toBe("tool_call");
+        if (item.type !== "tool_call") throw new Error("Expected a tool call");
+        expect(item.agentMessage).toEqual(agentMessage);
+        expect(item.agentMessage).not.toBe(agentMessage);
+        expect(Object.isFrozen(item.agentMessage)).toBe(true);
+        expect(Object.isFrozen(item.agentMessage?.sender)).toBe(true);
+        return undefined;
+      };
+      expect(projectPluginTimelineItems([source], inspect)).toEqual([source]);
+      expect(Object.isFrozen(agentMessage.sender)).toBe(false);
+    },
+  );
+
   it("does not expose mutable tool detail from stream state", () => {
     const detail = { type: "read" as const, filePath: "/repo/original.ts" };
     const source: StreamItem = {
@@ -59,6 +98,8 @@ describe("plugin timeline projection", () => {
       {
         kind: "plugin",
         id: "inline-thinking/thought-1/0",
+        sourceId: "thought-1",
+        sourceKind: "thought",
         data: { text: "First", phase: "streaming" },
       },
     ]);
diff --git a/packages/app/src/plugins/timeline/projection.ts b/packages/app/src/plugins/timeline/projection.ts
index 0750bdb66a..4670191746 100644
--- a/packages/app/src/plugins/timeline/projection.ts
+++ b/packages/app/src/plugins/timeline/projection.ts
@@ -1,5 +1,6 @@
 import type { AgentTimelineItem, ToolCallTimelineItem } from "@getpaseo/protocol/agent-types";
 import type { AgentToolCallData, PluginTimelineStreamItem, StreamItem } from "@/types/stream";
+import { cloneAndFreeze } from "../freeze";
 import type { TimelineItemTransform } from "./model";
 
 type AssistantPhase = "streaming" | "complete";
@@ -9,26 +10,15 @@ const projectionCache = new WeakMap<
   WeakMap<StreamItem, Partial<Record<AssistantPhase, StreamItem[]>>>
 >();
 
-function cloneAndFreeze<T>(value: T): T {
-  if (Array.isArray(value)) {
-    return Object.freeze(value.map((entry) => cloneAndFreeze(entry))) as T;
-  }
-  if (value !== null && typeof value === "object") {
-    return Object.freeze(
-      Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneAndFreeze(entry)])),
-    ) as T;
-  }
-  return value;
-}
-
 function sourceToolCallTimelineItem(data: AgentToolCallData): ToolCallTimelineItem {
-  const { callId, name, status, error, detail, metadata } = data;
+  const { callId, name, status, error, detail, metadata, agentMessage } = data;
   const base = {
     type: "tool_call" as const,
     callId,
     name,
     detail,
     ...(metadata ? { metadata } : {}),
+    ...(agentMessage ? { agentMessage } : {}),
   };
   switch (status) {
     case "running":
@@ -75,6 +65,7 @@ function sourceTimelineItem(item: StreamItem): AgentTimelineItem | null {
         ...(item.preTokens !== undefined ? { preTokens: item.preTokens } : {}),
       };
     case "plugin":
+    case "turn_summary":
       return null;
   }
 }
@@ -105,6 +96,7 @@ function transformSourceItem(
       kind: "plugin",
       id: `${pluginItem.pluginId}/${pluginItem.id}`,
       sourceId: item.id,
+      sourceKind: item.kind,
       timestamp: item.timestamp,
       pluginId: pluginItem.pluginId,
       pluginItemId: pluginItem.id,
diff --git a/packages/app/src/plugins/timeline/view.test.tsx b/packages/app/src/plugins/timeline/view.test.tsx
index ff3ba9fd6b..7d96747279 100644
--- a/packages/app/src/plugins/timeline/view.test.tsx
+++ b/packages/app/src/plugins/timeline/view.test.tsx
@@ -9,7 +9,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const hostClient = vi.hoisted(() => ({ invokePluginRpc: async () => null }));
 const selectedHost = vi.hoisted(() => ({ client: null as DaemonClient | null }));
-vi.mock("@/runtime/host-runtime", () => ({
+vi.mock("@/runtime/host-runtime", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@/runtime/host-runtime")>()),
   useHostRuntimeClient: () => selectedHost.client ?? (hostClient as unknown as DaemonClient),
   useHosts: () => [{ serverId: "host-1", label: "Local" }],
 }));
diff --git a/packages/app/src/plugins/types.ts b/packages/app/src/plugins/types.ts
index 9c2a88a210..497df5c59c 100644
--- a/packages/app/src/plugins/types.ts
+++ b/packages/app/src/plugins/types.ts
@@ -11,8 +11,11 @@ import type {
   PluginFilePanelContribution as SDKPluginFilePanelContribution,
   PluginCommandCenterItemContribution as SDKPluginCommandCenterItemContribution,
   PluginClientSlashCommandContribution as SDKPluginClientSlashCommandContribution,
+  PluginComposerItemContribution,
+  PluginNewWorkspaceItemContribution,
   PluginComposerPillContribution as SDKPluginComposerPillContribution,
   PluginSidebarContribution as SDKPluginSidebarContribution,
+  PluginSidebarViewContribution,
   PluginSidebarItemContribution as SDKPluginSidebarItemContribution,
   PluginScreenContribution as SDKPluginScreenContribution,
   PluginSettingsScreenContribution as SDKPluginSettingsScreenContribution,
@@ -48,11 +51,14 @@ export interface EvaluatedPlugin {
   cleanup: PluginCleanup;
   surfaces: PluginScreenContribution[];
   settingsScreens: PluginSettingsScreenContribution[];
+  sidebarViews: PluginSidebarViewContribution<PluginText>[];
   sidebarItems: Record<PluginSidebarSection, PluginSidebarItemContribution[]>;
   // COMPAT(pluginSidebarAliases): added in v0.11.0, remove after 2027-03-29
   /** `addSidebarItem` registrations, so `/plugin/<id>/sidebar/<item>` routes keep resolving. */
   legacySidebarItems: PluginSidebarContribution[];
   filePanels: PluginFilePanelContribution[];
+  composerItems: PluginComposerItemContribution[];
+  newWorkspaceItems: PluginNewWorkspaceItemContribution[];
   workspacePanels: EvaluatedPluginWorkspacePanelContribution[];
   commandCenterItems: PluginCommandCenterItemContribution[];
   clientSlashCommands: PluginClientSlashCommandContribution[];
@@ -71,6 +77,8 @@ export interface InstalledPlugin extends EvaluatedPlugin {
   paseo: PaseoApi;
   /** Calls one of the plugin's server RPC methods on its host. */
   invoke(method: string, input: unknown): Promise<unknown>;
+  /** Subscribes to one of the plugin's server subscriptions; released with the lifetime. */
+  subscribe: import("@getpaseo/plugin/client/host").PluginSubscribe;
   serverId: string;
   requirements?: PluginRequirements;
   clientBundle: string;
@@ -82,6 +90,8 @@ export type {
   PluginAttachmentSourceContribution,
   PluginCommandCenterItemContribution,
   PluginClientSlashCommandContribution,
+  PluginComposerItemContribution,
+  PluginNewWorkspaceItemContribution,
   PluginComposerPillContribution,
   PluginSidebarContribution,
   PluginSidebarItemContribution,
diff --git a/packages/app/src/plugins/workspace-panels/resolution.test.ts b/packages/app/src/plugins/workspace-panels/resolution.test.ts
index 1208106721..6ceb95f1a1 100644
--- a/packages/app/src/plugins/workspace-panels/resolution.test.ts
+++ b/packages/app/src/plugins/workspace-panels/resolution.test.ts
@@ -15,12 +15,18 @@ function installed(): InstalledPlugin {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => {},
     settingsScreens: [],
     surfaces: [],
+    sidebarViews: [],
     sidebarItems: { header: [], footer: [] },
     legacySidebarItems: [],
     filePanels: [],
+    composerItems: [],
+    newWorkspaceItems: [],
     workspacePanels: [
       {
         id: "details",
diff --git a/packages/app/src/project-suggestions/index.ts b/packages/app/src/project-suggestions/index.ts
new file mode 100644
index 0000000000..cf8697f9f9
--- /dev/null
+++ b/packages/app/src/project-suggestions/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Project suggestions: folders the user already ran agents in, offered as projects to add.
+ * Requires the host's `projectSuggestions` feature; on older hosts the list renders nothing.
+ */
+export { FolderProjectIcon } from "./internal/folder-project-icon";
+export { ProjectSuggestionList } from "./internal/project-suggestions";
+export {
+  useProjectSuggestions,
+  type ProjectSuggestionsController,
+} from "./internal/use-project-suggestions";
diff --git a/packages/app/src/project-suggestions/internal/folder-project-icon.tsx b/packages/app/src/project-suggestions/internal/folder-project-icon.tsx
new file mode 100644
index 0000000000..a81076c658
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/folder-project-icon.tsx
@@ -0,0 +1,39 @@
+import { StyleSheet } from "react-native-unistyles";
+import { ProjectIconView } from "@/components/project-icon-view";
+import { projectIconDataUri, useProjectIcon } from "@/projects/icons";
+import { ICON_SIZE } from "@/styles/theme";
+
+// The initial sits in a 16px square, below the smallest font-size token.
+const INITIAL_FONT_SIZE = 10;
+
+/**
+ * The icon of a folder that may not be a project yet: the icon the host discovers in it, or a
+ * colored initial. Keyed on the folder, so a suggestion keeps its color once it is added here.
+ */
+export function FolderProjectIcon({
+  serverId,
+  rootPath,
+  name,
+}: {
+  serverId: string;
+  rootPath: string;
+  name: string;
+}) {
+  const { icon } = useProjectIcon({ serverId, cwd: rootPath });
+  return (
+    <ProjectIconView
+      iconDataUri={projectIconDataUri(icon)}
+      initial={name.trim().charAt(0).toUpperCase() || "?"}
+      projectViewKey={rootPath}
+      size={ICON_SIZE.md}
+      textStyle={styles.initial}
+    />
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  initial: {
+    fontSize: INITIAL_FONT_SIZE,
+    fontWeight: theme.fontWeight.semibold,
+  },
+}));
diff --git a/packages/app/src/project-suggestions/internal/project-suggestions.tsx b/packages/app/src/project-suggestions/internal/project-suggestions.tsx
new file mode 100644
index 0000000000..8dddb9238b
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/project-suggestions.tsx
@@ -0,0 +1,207 @@
+import { useCallback, useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { type Animated, Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { SkeletonPulse, useSkeletonPulse } from "@/components/ui/skeleton";
+import { Switch } from "@/components/ui/switch";
+import { useTimeAgo } from "@/hooks/use-time-ago";
+import { projectIconRadius } from "@/components/project-icon-view";
+import { settingsStyles } from "@/styles/settings";
+import { ICON_SIZE } from "@/styles/theme";
+import { FolderProjectIcon } from "./folder-project-icon";
+import type { ProjectSuggestion } from "./suggestions";
+import type {
+  ProjectSuggestionsController,
+  SuggestionRow as SuggestionRowModel,
+} from "./use-project-suggestions";
+
+const INITIAL_SKELETON_ROWS = [0, 1, 2];
+const TRAILING_SKELETON_ROWS = [0];
+
+/**
+ * Folders the user already ran agents in, ready to add as projects. Rows appear as each provider
+ * answers, with skeleton rows while any is still reading; a provider that cannot read its history
+ * adds nothing. Adding the checked rows is the owner's primary action, through the same
+ * controller. Renders nothing on a host that cannot suggest projects.
+ */
+export function ProjectSuggestionList({
+  serverId,
+  suggestions,
+}: {
+  serverId: string;
+  suggestions: ProjectSuggestionsController;
+}) {
+  const { t } = useTranslation();
+  const { list } = suggestions;
+  if (list.status === "unsupported") return null;
+  if (list.rows.length === 0 && !list.isReading) {
+    return (
+      <Text style={styles.statusText}>
+        {t("onboarding.setup.steps.projects.suggestions.empty")}
+      </Text>
+    );
+  }
+
+  return (
+    <View
+      style={settingsStyles.card}
+      accessibilityLabel={
+        list.isReading ? t("onboarding.setup.steps.projects.suggestions.loading") : undefined
+      }
+    >
+      {list.rows.map((row, index) => (
+        <SuggestionRow
+          key={row.suggestion.rootPath}
+          serverId={serverId}
+          row={row}
+          first={index === 0}
+          disabled={list.isAdding}
+          onToggle={list.toggle}
+        />
+      ))}
+      {list.isReading ? <SkeletonRows afterRows={list.rows.length > 0} /> : null}
+    </View>
+  );
+}
+
+function SuggestionRow({
+  serverId,
+  row,
+  first,
+  disabled,
+  onToggle,
+}: {
+  serverId: string;
+  row: SuggestionRowModel;
+  first: boolean;
+  disabled: boolean;
+  onToggle: (suggestion: ProjectSuggestion) => void;
+}) {
+  const { t } = useTranslation();
+  const { suggestion, checked, addFailure } = row;
+  const handleValueChange = useCallback(() => onToggle(suggestion), [onToggle, suggestion]);
+  const lastActivity = useTimeAgo(useMemo(() => new Date(suggestion.lastActivityAt), [suggestion]));
+  return (
+    <View
+      style={[settingsStyles.row, !first && settingsStyles.rowBorder]}
+      testID="project-suggestion"
+    >
+      <View style={settingsStyles.rowContent}>
+        <View style={styles.titleLine}>
+          <FolderProjectIcon
+            serverId={serverId}
+            rootPath={suggestion.rootPath}
+            name={suggestion.displayName}
+          />
+          <Text style={[settingsStyles.rowTitle, styles.title]} numberOfLines={1}>
+            {suggestion.displayName}
+          </Text>
+        </View>
+        <View style={styles.underTitle}>
+          <Text style={settingsStyles.rowHint} numberOfLines={1}>
+            {suggestion.rootPath}
+          </Text>
+          <Text style={[settingsStyles.rowHint, styles.lastUsed]} numberOfLines={1}>
+            {t("onboarding.setup.steps.projects.suggestions.lastUsed", { time: lastActivity })}
+          </Text>
+          {addFailure === undefined ? null : (
+            <Text style={settingsStyles.rowError}>
+              {addFailure ?? t("onboarding.setup.steps.projects.suggestions.addFailed")}
+            </Text>
+          )}
+        </View>
+      </View>
+      <Switch
+        value={checked}
+        onValueChange={handleValueChange}
+        disabled={disabled}
+        accessibilityLabel={suggestion.displayName}
+      />
+    </View>
+  );
+}
+
+/** Placeholder rows in the shape of a suggestion: icon and name, path, and the switch. */
+function SkeletonRows({ afterRows }: { afterRows: boolean }) {
+  const pulse = useSkeletonPulse();
+  const rows = afterRows ? TRAILING_SKELETON_ROWS : INITIAL_SKELETON_ROWS;
+  return rows.map((row) => <SkeletonRow key={row} pulse={pulse} bordered={afterRows || row > 0} />);
+}
+
+function SkeletonRow({ pulse, bordered }: { pulse: Animated.Value; bordered: boolean }) {
+  return (
+    <View
+      style={[settingsStyles.row, bordered && settingsStyles.rowBorder]}
+      testID="project-suggestions-skeleton"
+    >
+      <View style={settingsStyles.rowContent}>
+        <View style={styles.titleLine}>
+          <SkeletonPulse pulse={pulse} style={styles.skeletonIcon} />
+          <SkeletonPulse pulse={pulse} style={styles.skeletonTitle} />
+        </View>
+        <View style={[styles.underTitle, styles.skeletonHints]}>
+          <SkeletonPulse pulse={pulse} style={styles.skeletonPath} />
+          <SkeletonPulse pulse={pulse} style={styles.skeletonLastUsed} />
+        </View>
+      </View>
+      <SkeletonPulse pulse={pulse} style={styles.skeletonSwitch} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  titleLine: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  title: {
+    flexShrink: 1,
+  },
+  // Path and last use line up under the name, past the icon.
+  underTitle: {
+    marginLeft: ICON_SIZE.md + theme.spacing[2],
+  },
+  lastUsed: {
+    color: theme.colors.foregroundExtraMuted,
+  },
+  statusText: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+  },
+  skeletonSwitch: {
+    width: 34,
+    height: 20,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonIcon: {
+    width: ICON_SIZE.md,
+    height: ICON_SIZE.md,
+    borderRadius: projectIconRadius(ICON_SIZE.md),
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonTitle: {
+    width: 120,
+    height: 12,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonHints: {
+    marginTop: theme.spacing[2],
+    gap: theme.spacing[2],
+  },
+  skeletonPath: {
+    width: 220,
+    maxWidth: "100%",
+    height: 10,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonLastUsed: {
+    width: 90,
+    height: 10,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+  },
+}));
diff --git a/packages/app/src/project-suggestions/internal/suggestions.test.ts b/packages/app/src/project-suggestions/internal/suggestions.test.ts
new file mode 100644
index 0000000000..1876e05cbb
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/suggestions.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import {
+  addSuggestedProjects,
+  isStillReading,
+  isSuggestionChecked,
+  mergeProviderSuggestions,
+  type ProjectSuggestion,
+  type ProviderSuggestions,
+} from "./suggestions";
+
+const NOW = new Date("2026-10-31T12:00:00.000Z");
+
+function suggestion(
+  rootPath: string,
+  overrides: Partial<ProjectSuggestion> = {},
+): ProjectSuggestion {
+  return {
+    rootPath,
+    displayName: rootPath.split("/").at(-1) ?? rootPath,
+    sessionCount: 1,
+    providerIds: ["claude"],
+    lastActivityAt: "2026-10-30T12:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("mergeProviderSuggestions", () => {
+  it("shows one row per folder across providers that answered, newest first", () => {
+    const rows = mergeProviderSuggestions(
+      [
+        {
+          provider: "claude",
+          status: "answered",
+          suggestions: [
+            suggestion("/dev/app", { sessionCount: 2, lastActivityAt: "2026-10-29T00:00:00.000Z" }),
+            suggestion("/dev/docs", { lastActivityAt: "2026-10-20T00:00:00.000Z" }),
+          ],
+        },
+        {
+          provider: "codex",
+          status: "answered",
+          suggestions: [
+            suggestion("/dev/app", {
+              sessionCount: 3,
+              providerIds: ["codex"],
+              lastActivityAt: "2026-10-30T00:00:00.000Z",
+            }),
+          ],
+        },
+        { provider: "opencode", status: "loading" },
+      ],
+      new Set(),
+    );
+
+    expect(rows).toEqual([
+      suggestion("/dev/app", {
+        sessionCount: 5,
+        providerIds: ["claude", "codex"],
+        lastActivityAt: "2026-10-30T00:00:00.000Z",
+      }),
+      suggestion("/dev/docs", { lastActivityAt: "2026-10-20T00:00:00.000Z" }),
+    ]);
+  });
+
+  it("drops folders that are already projects", () => {
+    const rows = mergeProviderSuggestions(
+      [
+        {
+          provider: "claude",
+          status: "answered",
+          suggestions: [suggestion("/dev/app"), suggestion("/dev/docs")],
+        },
+      ],
+      new Set(["/dev/app"]),
+    );
+
+    expect(rows.map((row) => row.rootPath)).toEqual(["/dev/docs"]);
+  });
+});
+
+describe("isSuggestionChecked", () => {
+  const busyRecent = suggestion("/dev/app", { sessionCount: 3 });
+  const quiet = suggestion("/dev/docs", { sessionCount: 2 });
+  const busyOld = suggestion("/dev/legacy", {
+    sessionCount: 9,
+    lastActivityAt: "2026-09-01T00:00:00.000Z",
+  });
+
+  it("starts checked for folders used at least three times in the last 30 days", () => {
+    expect([busyRecent, quiet, busyOld].map((row) => isSuggestionChecked(row, {}, NOW))).toEqual([
+      true,
+      false,
+      false,
+    ]);
+  });
+
+  it("keeps the user's choice once they toggle a row", () => {
+    const choices = { "/dev/app": false, "/dev/docs": true };
+    expect(isSuggestionChecked(busyRecent, choices, NOW)).toBe(false);
+    expect(isSuggestionChecked(quiet, choices, NOW)).toBe(true);
+  });
+});
+
+describe("addSuggestedProjects", () => {
+  it("adds every folder and reports the ones the host refused", async () => {
+    const added: string[] = [];
+    const failures = await addSuggestedProjects(
+      ["/dev/app", "/dev/gone", "/dev/docs"],
+      async (path) => {
+        if (path === "/dev/gone") return { ok: false, error: "Directory not found" };
+        added.push(path);
+        return { ok: true };
+      },
+    );
+
+    expect(added).toEqual(["/dev/app", "/dev/docs"]);
+    expect(failures).toEqual(new Map([["/dev/gone", "Directory not found"]]));
+  });
+
+  it("keeps going when adding one folder throws", async () => {
+    const failures = await addSuggestedProjects(["/dev/app", "/dev/docs"], async (path) => {
+      if (path === "/dev/app") throw new Error("Host disconnected");
+      return { ok: true };
+    });
+
+    expect(failures).toEqual(new Map([["/dev/app", "Host disconnected"]]));
+  });
+});
+
+describe("isStillReading", () => {
+  it("keeps reading while any provider has not answered", () => {
+    const reading: ProviderSuggestions = { provider: "codex", status: "loading" };
+    const answered: ProviderSuggestions = {
+      provider: "opencode",
+      status: "answered",
+      suggestions: [],
+    };
+
+    expect(isStillReading([answered, reading])).toBe(true);
+    expect(isStillReading([answered, { ...answered, provider: "pi" }])).toBe(false);
+    expect(isStillReading([])).toBe(false);
+  });
+});
diff --git a/packages/app/src/project-suggestions/internal/suggestions.ts b/packages/app/src/project-suggestions/internal/suggestions.ts
new file mode 100644
index 0000000000..8b0268f1b1
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/suggestions.ts
@@ -0,0 +1,90 @@
+import type { ProjectSuggestion } from "@getpaseo/protocol/messages";
+
+export type { ProjectSuggestion };
+
+const PRESELECT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+const PRESELECT_MIN_SESSIONS = 3;
+
+/**
+ * One provider's answer. Each provider is asked separately so a slow one never holds up the rest.
+ * A provider that cannot read its history answers with whatever it found, often nothing.
+ */
+export type ProviderSuggestions =
+  | { provider: string; status: "loading" }
+  | { provider: string; status: "answered"; suggestions: ProjectSuggestion[] };
+
+/** Combines the providers that answered into one row per folder, most recent first. */
+export function mergeProviderSuggestions(
+  providers: readonly ProviderSuggestions[],
+  addedRootPaths: ReadonlySet<string>,
+): ProjectSuggestion[] {
+  const byRoot = new Map<string, ProjectSuggestion>();
+  for (const provider of providers) {
+    if (provider.status === "loading") continue;
+    for (const suggestion of provider.suggestions) {
+      if (addedRootPaths.has(suggestion.rootPath)) continue;
+      const existing = byRoot.get(suggestion.rootPath);
+      byRoot.set(
+        suggestion.rootPath,
+        existing ? combineSuggestions(existing, suggestion) : suggestion,
+      );
+    }
+  }
+  return Array.from(byRoot.values()).sort((a, b) =>
+    b.lastActivityAt.localeCompare(a.lastActivityAt),
+  );
+}
+
+function combineSuggestions(a: ProjectSuggestion, b: ProjectSuggestion): ProjectSuggestion {
+  return {
+    ...a,
+    sessionCount: a.sessionCount + b.sessionCount,
+    providerIds: Array.from(new Set([...a.providerIds, ...b.providerIds])).sort(),
+    lastActivityAt: a.lastActivityAt > b.lastActivityAt ? a.lastActivityAt : b.lastActivityAt,
+  };
+}
+
+/** True while any provider is still reading its history; the rows so far show meanwhile. */
+export function isStillReading(providers: readonly ProviderSuggestions[]): boolean {
+  return providers.some((provider) => provider.status === "loading");
+}
+
+/** Folders the user worked in often and recently start checked. */
+export function isPreselected(suggestion: ProjectSuggestion, now: Date): boolean {
+  return (
+    suggestion.sessionCount >= PRESELECT_MIN_SESSIONS &&
+    now.getTime() - Date.parse(suggestion.lastActivityAt) <= PRESELECT_WINDOW_MS
+  );
+}
+
+/**
+ * Checks start from the preselection; once the user toggles a row, their choice sticks even as
+ * more providers answer and the row's counts change.
+ */
+export function isSuggestionChecked(
+  suggestion: ProjectSuggestion,
+  choices: Readonly<Record<string, boolean>>,
+  now: Date,
+): boolean {
+  return choices[suggestion.rootPath] ?? isPreselected(suggestion, now);
+}
+
+/**
+ * Adds each folder in turn and returns the ones that failed, with the host's message when it gave
+ * one. Sequential so the sidebar fills in the order the user sees.
+ */
+export async function addSuggestedProjects(
+  rootPaths: readonly string[],
+  addProject: (rootPath: string) => Promise<{ ok: true } | { ok: false; error: string | null }>,
+): Promise<Map<string, string | null>> {
+  const failures = new Map<string, string | null>();
+  for (const rootPath of rootPaths) {
+    try {
+      const result = await addProject(rootPath);
+      if (!result.ok) failures.set(rootPath, result.error);
+    } catch (error) {
+      failures.set(rootPath, error instanceof Error ? error.message : null);
+    }
+  }
+  return failures;
+}
diff --git a/packages/app/src/project-suggestions/internal/use-project-suggestions.ts b/packages/app/src/project-suggestions/internal/use-project-suggestions.ts
new file mode 100644
index 0000000000..1f16cb1043
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/use-project-suggestions.ts
@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useMutation } from "@tanstack/react-query";
+import { useOpenProject } from "@/hooks/use-open-project";
+import { useProjectRootPaths } from "@/stores/session-store-hooks";
+import {
+  addSuggestedProjects,
+  isStillReading,
+  isSuggestionChecked,
+  mergeProviderSuggestions,
+  type ProjectSuggestion,
+} from "./suggestions";
+import { useProviderSuggestions } from "./use-provider-suggestions";
+
+export interface SuggestionRow {
+  suggestion: ProjectSuggestion;
+  checked: boolean;
+  /** Undefined when the folder was not attempted; null when the host gave no reason. */
+  addFailure: string | null | undefined;
+}
+
+export type SuggestionList =
+  | { status: "unsupported" }
+  | {
+      status: "ready";
+      rows: SuggestionRow[];
+      /** True while any provider, or the provider list itself, is still pending. */
+      isReading: boolean;
+      /** True while checked rows are being added; the selection is frozen until it settles. */
+      isAdding: boolean;
+      toggle: (suggestion: ProjectSuggestion) => void;
+    };
+
+export interface ProjectSuggestionsController {
+  list: SuggestionList;
+  checkedCount: number;
+  isAdding: boolean;
+  /**
+   * Adds every checked folder. Resolves true when all of them were added and no new row arrived
+   * checked meanwhile.
+   */
+  addChecked: () => Promise<boolean>;
+}
+
+/**
+ * The suggestion list and the user's selection. Whoever owns the step's primary action holds
+ * this, so proceeding can add what is checked; calling it early also starts reading history.
+ */
+export function useProjectSuggestions(serverId: string): ProjectSuggestionsController {
+  const state = useProviderSuggestions(serverId);
+  const projectRootPaths = useProjectRootPaths(serverId);
+  const openProject = useOpenProject(serverId);
+  const [now] = useState(() => new Date());
+  const [choices, setChoices] = useState<Record<string, boolean>>({});
+  const [addFailures, setAddFailures] = useState<Map<string, string | null>>(new Map());
+
+  const providers = state.status === "ready" ? state.providers : null;
+  const suggestions = useMemo(
+    () => (providers ? mergeProviderSuggestions(providers, new Set(projectRootPaths)) : []),
+    [providers, projectRootPaths],
+  );
+  const checkedRootPaths = useMemo(
+    () =>
+      suggestions
+        .filter((suggestion) => isSuggestionChecked(suggestion, choices, now))
+        .map((suggestion) => suggestion.rootPath),
+    [suggestions, choices, now],
+  );
+
+  const toggle = useCallback(
+    (suggestion: ProjectSuggestion) => {
+      setChoices((current) => ({
+        ...current,
+        [suggestion.rootPath]: !isSuggestionChecked(suggestion, current, now),
+      }));
+    },
+    [now],
+  );
+
+  const { mutateAsync, isPending } = useMutation({
+    mutationFn: (rootPaths: string[]) => addSuggestedProjects(rootPaths, openProject),
+    onSuccess: setAddFailures,
+  });
+  // A provider can answer while the add runs and bring in rows that start checked. Those were not
+  // part of the add, so the step stays put and offers to add them rather than moving on.
+  const latestChecked = useRef(checkedRootPaths);
+  useEffect(() => {
+    latestChecked.current = checkedRootPaths;
+  }, [checkedRootPaths]);
+  const addChecked = useCallback(async () => {
+    const attempted = new Set(checkedRootPaths);
+    const failures = await mutateAsync(checkedRootPaths);
+    const arrivedChecked = latestChecked.current.some((rootPath) => !attempted.has(rootPath));
+    return failures.size === 0 && !arrivedChecked;
+  }, [mutateAsync, checkedRootPaths]);
+
+  const list = useMemo((): SuggestionList => {
+    if (state.status === "unsupported") return state;
+    return {
+      status: "ready",
+      rows: suggestions.map((suggestion) => ({
+        suggestion,
+        checked: checkedRootPaths.includes(suggestion.rootPath),
+        addFailure: addFailures.get(suggestion.rootPath),
+      })),
+      isReading: state.status === "loading" || isStillReading(state.providers),
+      isAdding: isPending,
+      toggle,
+    };
+  }, [state, suggestions, checkedRootPaths, addFailures, isPending, toggle]);
+
+  return { list, checkedCount: checkedRootPaths.length, isAdding: isPending, addChecked };
+}
diff --git a/packages/app/src/project-suggestions/internal/use-provider-suggestions.ts b/packages/app/src/project-suggestions/internal/use-provider-suggestions.ts
new file mode 100644
index 0000000000..0c0cee5af1
--- /dev/null
+++ b/packages/app/src/project-suggestions/internal/use-provider-suggestions.ts
@@ -0,0 +1,76 @@
+import { useMemo } from "react";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { useFetchQueries } from "@/data/query";
+import { useProvidersSnapshot } from "@/hooks/use-providers-snapshot";
+import { useHostFeature } from "@/runtime/host-features";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import type { ProviderSuggestions } from "./suggestions";
+
+type SuggestionsResponse = Awaited<ReturnType<DaemonClient["listProjectSuggestions"]>>;
+
+// History changes slowly. Opening the step still re-asks, keeping the rows already shown.
+const SUGGESTIONS_STALE_TIME_MS = 5 * 60 * 1000;
+
+export type ProjectSuggestionsState =
+  | { status: "unsupported" }
+  /** The provider list itself has not arrived yet. */
+  | { status: "loading" }
+  | { status: "ready"; providers: ProviderSuggestions[] };
+
+function suggestionsQueryKey(serverId: string, provider: string) {
+  return ["project-suggestions", serverId, provider] as const;
+}
+
+/**
+ * Asks the host for suggestions once per enabled provider, in parallel. The queries are shared, so
+ * calling this early (when setup opens) means the Projects step usually finds them answered.
+ */
+export function useProviderSuggestions(serverId: string): ProjectSuggestionsState {
+  const supported = useHostFeature(serverId, "projectSuggestions");
+  const client = useHostRuntimeClient(serverId);
+  const isConnected = useHostRuntimeIsConnected(serverId);
+  const { entries } = useProvidersSnapshot(serverId, { enabled: supported });
+  const providers = useMemo(
+    () => entries?.filter((entry) => entry.enabled !== false).map((entry) => entry.provider),
+    [entries],
+  );
+
+  const results = useFetchQueries<SuggestionsResponse>(
+    (supported && providers ? providers : []).map((provider) => ({
+      queryKey: suggestionsQueryKey(serverId, provider),
+      dataShape: "value",
+      enabled: Boolean(client) && isConnected,
+      // Suggestions are a convenience: a provider that cannot answer simply adds nothing.
+      retry: false,
+      staleTimeMs: SUGGESTIONS_STALE_TIME_MS,
+      queryFn: () => {
+        if (!client) throw new Error("Host disconnected");
+        return client.listProjectSuggestions({ providers: [provider] });
+      },
+    })),
+  );
+
+  return useMemo((): ProjectSuggestionsState => {
+    if (!supported) return { status: "unsupported" };
+    if (!providers) return { status: "loading" };
+    return {
+      status: "ready",
+      providers: providers.map((provider, index) =>
+        toProviderSuggestions(provider, results[index]),
+      ),
+    };
+  }, [supported, providers, results]);
+}
+
+function toProviderSuggestions(
+  provider: string,
+  result: { data?: SuggestionsResponse; error: Error | null; isFetching: boolean } | undefined,
+): ProviderSuggestions {
+  if (result?.data) {
+    return { provider, status: "answered", suggestions: result.data.suggestions };
+  }
+  if (result?.error && !result.isFetching) {
+    return { provider, status: "answered", suggestions: [] };
+  }
+  return { provider, status: "loading" };
+}
diff --git a/packages/app/src/projects/icons.ts b/packages/app/src/projects/icons.ts
index ee52b2b57f..a39e8f4d68 100644
--- a/packages/app/src/projects/icons.ts
+++ b/packages/app/src/projects/icons.ts
@@ -30,7 +30,7 @@ function legacyIconQueryKey(serverId: string, cwd: string) {
   return ["projectIcon", serverId, "legacy", cwd] as const;
 }
 
-function iconDataUri(icon: ProjectIcon | null): string | null {
+export function projectIconDataUri(icon: ProjectIcon | null): string | null {
   if (!icon) return null;
   return `data:${icon.mimeType};base64,${icon.data}`;
 }
@@ -98,7 +98,7 @@ export function useProjectIcons(input: {
           () => getHostRuntimeStore().getClient(request.serverId),
           isHostRuntimeConnected(getHostRuntimeStore().getSnapshot(request.serverId)),
         ),
-        select: iconDataUri,
+        select: projectIconDataUri,
       };
     }),
   });
diff --git a/packages/app/src/provider-selection/agent-form-store.ts b/packages/app/src/provider-selection/agent-form-store.ts
new file mode 100644
index 0000000000..2db3837d22
--- /dev/null
+++ b/packages/app/src/provider-selection/agent-form-store.ts
@@ -0,0 +1,87 @@
+import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
+import type { AgentModelDefinition, AgentProvider } from "@getpaseo/protocol/agent-types";
+import type { FormPreferences } from "@/hooks/use-form-preferences";
+import {
+  INITIAL_AGENT_FORM_RESOLUTION,
+  INITIAL_USER_MODIFIED,
+  resolveAgentForm,
+  type AgentFormAction,
+  type AgentFormReducerState,
+} from "@/provider-selection/resolve-agent-form";
+
+/** What the host offers right now. The store reads it when a command runs, never earlier. */
+export interface AgentFormCatalog {
+  /** The providers the host can run. */
+  selectableProviders: ReadonlyMap<AgentProvider, AgentProviderDefinition>;
+  /** Each provider's selectable models; empty when the host has listed none. */
+  models: ReadonlyMap<string, AgentModelDefinition[]>;
+  providerPreferences: (
+    provider: AgentProvider,
+  ) => NonNullable<FormPreferences["providerPreferences"]>[AgentProvider] | undefined;
+}
+
+/**
+ * The draft form as a plain model: `resolveAgentForm` applied synchronously. A command reads
+ * `getState()` and the catalog when it runs, so the one after `await setProvider(...)` sees the
+ * new provider instead of the render that created it.
+ */
+export interface AgentFormStore {
+  getState: () => AgentFormReducerState;
+  dispatch: (action: AgentFormAction) => void;
+  subscribe: (listener: () => void) => () => void;
+  /** `false` when the provider is unknown or not ready; the form is left as it was. */
+  setProviderAndModel: (provider: AgentProvider, modelId: string) => boolean;
+  /** The id is kept as given; a catalog that does not list it is the provider's to refuse. */
+  setModel: (modelId: string) => void;
+}
+
+export function openAgentForm(catalog: () => AgentFormCatalog): AgentFormStore {
+  let state: AgentFormReducerState = {
+    form: { provider: null, modeId: "", model: "", thinkingOptionId: "" },
+    userModified: INITIAL_USER_MODIFIED,
+    resolution: INITIAL_AGENT_FORM_RESOLUTION,
+  };
+  const listeners = new Set<() => void>();
+  function dispatch(action: AgentFormAction): void {
+    const next = resolveAgentForm(state, action);
+    if (next === state) return;
+    state = next;
+    for (const listener of listeners) listener();
+  }
+  return {
+    getState: () => state,
+    dispatch,
+    setProviderAndModel: (provider, modelId) => {
+      const host = catalog();
+      const providerDef = host.selectableProviders.get(provider);
+      if (!providerDef) return false;
+      dispatch({
+        type: "SET_PROVIDER_AND_MODEL_FROM_USER",
+        provider,
+        modelId,
+        providerDef,
+        providerModels: host.models.get(provider) ?? null,
+        providerPrefs: host.providerPreferences(provider),
+      });
+      return true;
+    },
+    setModel: (modelId) => {
+      const { provider } = state.form;
+      const host = catalog();
+      const listed = provider ? host.models.get(provider) : undefined;
+      const models = listed?.length ? listed : null;
+      dispatch({
+        type: "SET_MODEL_FROM_USER",
+        modelId,
+        availableModels: models,
+        providerPrefs: provider ? host.providerPreferences(provider) : undefined,
+      });
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
diff --git a/packages/app/src/provider-selection/provider-selection.ts b/packages/app/src/provider-selection/provider-selection.ts
index e0313c6623..592824341a 100644
--- a/packages/app/src/provider-selection/provider-selection.ts
+++ b/packages/app/src/provider-selection/provider-selection.ts
@@ -5,7 +5,7 @@ import type {
   ProviderSnapshotEntry,
 } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
-import type { DraftCommandTarget } from "@/hooks/use-agent-commands-query";
+import type { DraftCommandTarget } from "@/agent-commands";
 import { i18n } from "@/i18n/i18next";
 import { compareMatchScores, scoreTextFields } from "@getpaseo/protocol/search/text-match";
 import { filterSelectableModels } from "./model-catalog";
@@ -312,7 +312,7 @@ export function buildDraftCommandTarget(input: {
   cwd: string;
   effectiveModelId: string;
   effectiveThinkingOptionId: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }): DraftCommandTarget {
   const cwd = input.cwd.trim();
   if (!cwd) {
@@ -332,7 +332,7 @@ export function buildDraftCommandTarget(input: {
     ...(input.effectiveThinkingOptionId
       ? { thinkingOptionId: input.effectiveThinkingOptionId }
       : {}),
-    ...(input.featureValues ? { featureValues: input.featureValues } : {}),
+    ...(input.providerOptions ? { providerOptions: input.providerOptions } : {}),
   };
   return { status: "ready", config };
 }
diff --git a/packages/app/src/provider-selection/resolve-agent-form.test.ts b/packages/app/src/provider-selection/resolve-agent-form.test.ts
index 3912d87e13..877898b979 100644
--- a/packages/app/src/provider-selection/resolve-agent-form.test.ts
+++ b/packages/app/src/provider-selection/resolve-agent-form.test.ts
@@ -284,7 +284,7 @@ describe("mergeSelectedComposerPreferences", () => {
             codex: {
               mode: "full-access",
               thinkingByModel: { "gpt-5.4-mini": "medium" },
-              featureValues: { fast_mode: true },
+              options: { fast_mode: true },
             },
             claude: { model: "claude-sonnet-4-6" },
           },
@@ -299,7 +299,7 @@ describe("mergeSelectedComposerPreferences", () => {
           model: "gpt-5.4",
           mode: "full-access",
           thinkingByModel: { "gpt-5.4-mini": "medium" },
-          featureValues: { fast_mode: true },
+          options: { fast_mode: true },
         },
         claude: { model: "claude-sonnet-4-6" },
       },
diff --git a/packages/app/src/review/comment-sheet.tsx b/packages/app/src/review/comment-sheet.tsx
index d54ec0ec96..6c025bbbf2 100644
--- a/packages/app/src/review/comment-sheet.tsx
+++ b/packages/app/src/review/comment-sheet.tsx
@@ -53,7 +53,6 @@ function OpenReviewCommentSheet({
     () => (
       <View style={styles.actions}>
         <Button
-          size="md"
           variant="secondary"
           accessibilityLabel={t("review.comment.cancelAccessibility")}
           onPress={onCancelEditor}
@@ -61,7 +60,6 @@ function OpenReviewCommentSheet({
           {t("review.comment.cancel")}
         </Button>
         <Button
-          size="md"
           variant="default"
           accessibilityLabel={t("review.comment.saveAccessibility")}
           disabled={!canSave}
@@ -85,7 +83,6 @@ function OpenReviewCommentSheet({
     >
       <FormTextInput
         key={editor.target.key + (editor.commentId ?? "new")}
-        size="md"
         multiline
         accessibilityLabel={t("review.comment.label")}
         placeholder={t("review.comment.placeholder")}
diff --git a/packages/app/src/review/feedback/surface.tsx b/packages/app/src/review/feedback/surface.tsx
index fac499152e..15702d459a 100644
--- a/packages/app/src/review/feedback/surface.tsx
+++ b/packages/app/src/review/feedback/surface.tsx
@@ -7,7 +7,7 @@ import { StyleSheet } from "react-native-unistyles";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem } from "@/components/ui/dropdown-menu";
 import { useMenuContext } from "@/components/ui/menu";
 import { Button } from "@/components/ui/button";
-import { buttonControlHeight } from "@/components/ui/control-geometry";
+import { controlHeightForLayout } from "@/components/ui/control-geometry";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { SPACING } from "@/styles/theme";
 import { FloatingActionButton } from "@/components/ui/floating-action-button";
@@ -64,7 +64,7 @@ function OpenReviewFeedbackAction({
         bottom:
           bottom +
           bottomOffset +
-          (isCompact ? 88 : buttonControlHeight.sm + SPACING[4] + SPACING[2]),
+          (isCompact ? 88 : controlHeightForLayout("md", isCompact) + SPACING[4] + SPACING[2]),
       },
     ],
     [bottom, bottomOffset, isCompact],
@@ -145,7 +145,6 @@ function FeedbackTrigger({
         <Button
           ref={triggerRef}
           variant="default"
-          size="sm"
           leftIcon={Send}
           accessibilityLabel={label}
           disabled={disabled}
diff --git a/packages/app/src/review/feedback/use-feedback.ts b/packages/app/src/review/feedback/use-feedback.ts
index 0596f3c55f..9080f6c26d 100644
--- a/packages/app/src/review/feedback/use-feedback.ts
+++ b/packages/app/src/review/feedback/use-feedback.ts
@@ -14,7 +14,7 @@ import { createMessageSubmissionWriter } from "@/composer/submission/writer";
 import { useSessionStore, selectAgentTurnPresentation } from "@/stores/session-store";
 import { FLOATING_ACTION_BUTTON_CLEARANCE } from "@/components/ui/floating-action-button";
 import { useIsCompactFormFactor } from "@/constants/layout";
-import { buttonControlHeight } from "@/components/ui/control-geometry";
+import { controlHeightForLayout } from "@/components/ui/control-geometry";
 import { SPACING } from "@/styles/theme";
 import { i18n } from "@/i18n/i18next";
 import {
@@ -114,7 +114,9 @@ export function useReviewFeedback(input: {
     state,
     clearance:
       state.commentCount > 0
-        ? (isCompact ? FLOATING_ACTION_BUTTON_CLEARANCE : buttonControlHeight.sm + SPACING[4]) + 44
+        ? (isCompact
+            ? FLOATING_ACTION_BUTTON_CLEARANCE
+            : controlHeightForLayout("md", isCompact) + SPACING[4]) + 44
         : 0,
   };
 }
diff --git a/packages/app/src/review/surface.tsx b/packages/app/src/review/surface.tsx
index 7466052456..4c78e112d8 100644
--- a/packages/app/src/review/surface.tsx
+++ b/packages/app/src/review/surface.tsx
@@ -484,7 +484,7 @@ export function InlineReviewEditor({
           hitSlop={SMALL_ACTION_HIT_SLOP}
           onPress={onCancel}
           variant="ghost"
-          size="xs"
+          size="sm"
         >
           {t("review.comment.cancel")}
         </Button>
@@ -495,7 +495,7 @@ export function InlineReviewEditor({
           disabled={!canSave}
           onPress={handleSave}
           variant="default"
-          size="xs"
+          size="sm"
         >
           {t("review.comment.save")}
         </Button>
diff --git a/packages/app/src/runtime/directory-sync/agent-replica.test.ts b/packages/app/src/runtime/directory-sync/agent-replica.test.ts
index 67a83cee87..e59854daec 100644
--- a/packages/app/src/runtime/directory-sync/agent-replica.test.ts
+++ b/packages/app/src/runtime/directory-sync/agent-replica.test.ts
@@ -8,6 +8,8 @@ import {
 } from "@/stores/session-store";
 import { normalizeAgentSnapshot } from "@/utils/agent-snapshots";
 import type { DirectoryReplicaMutation } from "@/runtime/replica-cache";
+import { useDraftStore } from "@/stores/draft-store";
+import { buildDraftStoreKey } from "@/stores/draft-keys";
 import { AgentDirectoryReplica } from "./agent-replica";
 
 function payload(title: string): AgentSnapshotPayload {
@@ -58,7 +60,7 @@ function entry(agent: AgentSnapshotPayload): FetchAgentsEntry {
 
 describe("AgentDirectoryReplica", () => {
   it.each(["delta", "snapshot"] as const)(
-    "does not erase freshly fetched history when the active directory removes it by %s",
+    "preserves history and unsent drafts when the active directory removes an agent by %s",
     (removal) => {
       const serverId = `agent-replica-history-${removal}`;
       const store = useSessionStore.getState();
@@ -68,6 +70,18 @@ describe("AgentDirectoryReplica", () => {
         () => undefined,
         () => undefined,
       );
+      const draftKey = buildDraftStoreKey({ serverId, agentId: "agent" });
+      const draft = {
+        text: "Keep this unsent draft",
+        attachments: [
+          {
+            kind: "workspace_file" as const,
+            path: "README.md",
+            selection: { kind: "whole_file" as const },
+          },
+        ],
+      };
+      useDraftStore.getState().saveDraftInput({ draftKey, draft });
       const archived = { ...payload("archived"), archivedAt: "2026-09-11T00:00:00.000Z" };
       replica.submitTimelineAgent(replica.captureTimeline("agent"), archived);
       store.applyAgentTimelineResponseState(serverId, "agent", {
@@ -93,7 +107,9 @@ describe("AgentDirectoryReplica", () => {
         status: "synced",
         items: [{ text: "server history" }],
       });
+      expect(useDraftStore.getState().getDraftInput(draftKey)).toEqual(draft);
       replica.remove("agent");
+      expect(useDraftStore.getState().getDraftInput(draftKey)).toBeUndefined();
       expect(selectAgentTimelineState(store.getSession(serverId), "agent")).toMatchObject({
         status: "cold",
       });
@@ -390,4 +406,39 @@ describe("AgentDirectoryReplica", () => {
     expect(useSessionStore.getState().sessions[serverId]?.agents.has("agent")).toBe(true);
     store.clearSession(serverId);
   });
+  it("keeps unchanged agent fields when an update changes only the status", () => {
+    const serverId = "agent-replica-unchanged-fields";
+    const store = useSessionStore.getState();
+    store.initializeSession(serverId, null as unknown as DaemonClient);
+    const replica = new AgentDirectoryReplica(
+      serverId,
+      () => undefined,
+      () => undefined,
+    );
+    const agentInStore = () => useSessionStore.getState().sessions[serverId]?.agents.get("agent");
+    replica.commitSnapshot([entry(payload("agent"))], []);
+    const before = agentInStore();
+
+    replica.applyDelta({
+      kind: "upsert",
+      agent: { ...payload("agent"), status: "running", updatedAt: "2026-07-17T00:02:00.000Z" },
+      project: entry(payload("agent")).project,
+    });
+    const afterDelta = agentInStore();
+    replica.commitSnapshot(
+      [entry({ ...payload("agent"), status: "idle", updatedAt: "2026-07-17T00:03:00.000Z" })],
+      [],
+    );
+    const afterSnapshot = agentInStore();
+
+    expect(afterDelta?.status).toBe("running");
+    expect(afterSnapshot?.status).toBe("idle");
+    for (const agent of [afterDelta, afterSnapshot]) {
+      expect(agent?.capabilities).toBe(before?.capabilities);
+      expect(agent?.availableModes).toBe(before?.availableModes);
+      expect(agent?.labels).toBe(before?.labels);
+      expect(agent?.projectPlacement).toBe(before?.projectPlacement);
+    }
+    store.clearSession(serverId);
+  });
 });
diff --git a/packages/app/src/runtime/directory-sync/index.test.ts b/packages/app/src/runtime/directory-sync/index.test.ts
index 6fae0a7e92..e4db5dfb71 100644
--- a/packages/app/src/runtime/directory-sync/index.test.ts
+++ b/packages/app/src/runtime/directory-sync/index.test.ts
@@ -16,7 +16,8 @@ import {
   normalizeWorkspaceDescriptor,
   useSessionStore,
 } from "@/stores/session-store";
-import { normalizeAgentSnapshot } from "@/utils/agent-snapshots";
+import { normalizeAgentSnapshot, projectAgentSnapshot } from "@/utils/agent-snapshots";
+import { deriveProjectPlacementFromCwd } from "@/utils/project-placement";
 import { selectWorkspaceDirectoryServerIds } from "@/stores/session-store-hooks/selectors";
 import { useWorkspaceLabels } from "@/workspace-labels";
 import type { DirectoryReplicaMutation } from "@/runtime/replica-cache";
@@ -41,12 +42,15 @@ class FakeDirectoryClient {
   supportsWorkspaceLabels = false;
   listWorkspaceLabelsCalls = 0;
   fetchAgentsCalls = 0;
+  observeAgentsCalls = 0;
   lastAgentOptions: unknown;
   fetchWorkspacesCalls = 0;
+  observeWorkspacesCalls = 0;
   lastWorkspaceOptions: unknown;
   listProjectsCalls = 0;
   lastProjectOptions: unknown;
   projectResult: ProjectListResult | null = null;
+  readonly listSnapshots: Promise<unknown>[] = [];
   private pendingAgentFetch: Promise<AgentFetchResult> | null = null;
   private pendingWorkspaceFetch: Promise<WorkspaceFetchResult> | null = null;
   private pendingProjectFetch: Promise<ProjectListResult> | null = null;
@@ -151,15 +155,22 @@ class FakeDirectoryClient {
   }
 
   observeAgents(options: Parameters<DaemonClient["observeAgents"]>[0]) {
-    return subscriptionFixture(this.fetchAgents({ ...options, subscribe: {} }), (receive) =>
-      this.on("agent_update", receive),
+    this.observeAgentsCalls += 1;
+    const subscription = subscriptionFixture(
+      this.fetchAgents({ ...options, subscribe: {} }),
+      (receive) => this.on("agent_update", receive),
     );
+    this.listSnapshots.push(subscription.ready);
+    return subscription;
   }
 
   observeWorkspaces(options: Parameters<DaemonClient["observeWorkspaces"]>[0]) {
-    return subscriptionFixture(this.fetchWorkspaces(options), (receive) =>
+    this.observeWorkspacesCalls += 1;
+    const subscription = subscriptionFixture(this.fetchWorkspaces(options), (receive) =>
       this.on("workspace_update", receive),
     );
+    this.listSnapshots.push(subscription.ready);
+    return subscription;
   }
 
   observeEvents(events: readonly SessionOutboundMessage["type"][]) {
@@ -592,6 +603,83 @@ describe("DirectorySync session readiness", () => {
     directory.dispose();
   });
 
+  it.each([
+    ["full", "before"],
+    ["full", "after"],
+    ["route", "before"],
+    ["route", "after"],
+  ] as const)(
+    "restores live directory updates when %s demand returns %s refresh completion",
+    async (demand, timing) => {
+      const serverId = `released-directory-${demand}-${timing}`;
+      const { client, directory } = createDirectory(serverId);
+      const store = useSessionStore.getState();
+      store.initializeSession(serverId, client as unknown as DaemonClient, 1);
+      store.updateSessionServerInfo(serverId, {
+        serverId,
+        hostname: null,
+        version: "test",
+        features: { workspaceMultiplicity: true, projectList: true },
+      });
+      const source = {};
+      function setDemand(demanded: boolean): void {
+        if (demand === "full") directory.setDemand(source, demanded);
+        else directory.setAgentRouteDemand(demanded ? ["agent-1"] : []);
+      }
+      const releaseProjects = client.holdProjectFetch();
+      const projects: ProjectListResult = { requestId: "projects", projects: [] };
+
+      try {
+        setDemand(true);
+        const refresh = directory.refreshDemand();
+        await expect
+          .poll(() => [client.observeAgentsCalls, client.observeWorkspacesCalls])
+          .toEqual([1, 1]);
+
+        await Promise.all(client.listSnapshots);
+        setDemand(false);
+        if (timing === "before") setDemand(true);
+        releaseProjects(projects);
+        await refresh;
+        if (timing === "after") setDemand(true);
+
+        await expect
+          .poll(() => [client.observeAgentsCalls, client.observeWorkspacesCalls])
+          .toEqual([2, 2]);
+        client.emit({
+          type: "agent_update",
+          payload: {
+            kind: "upsert",
+            agent: {
+              ...projectAgentSnapshot(createAgent(serverId, "agent-1")),
+              title: "Live title",
+            },
+            project: deriveProjectPlacementFromCwd("/repo"),
+          },
+        });
+        client.emit({
+          type: "workspace_update",
+          payload: {
+            kind: "upsert",
+            workspace: { ...createWorkspaceEntry("workspace-1"), name: "Live workspace" },
+          },
+        });
+
+        await expect
+          .poll(() => {
+            const session = useSessionStore.getState().sessions[serverId];
+            return [
+              session.agents.get("agent-1")?.title,
+              session.workspaces.get("workspace-1")?.name,
+            ];
+          })
+          .toEqual(["Live title", "Live workspace"]);
+      } finally {
+        directory.dispose();
+      }
+    },
+  );
+
   it("publishes cached directory data before the authoritative request completes", async () => {
     const serverId = "cached-directory";
     serverIds.add(serverId);
diff --git a/packages/app/src/runtime/directory-sync/index.ts b/packages/app/src/runtime/directory-sync/index.ts
index b59440d782..0f539a2b1d 100644
--- a/packages/app/src/runtime/directory-sync/index.ts
+++ b/packages/app/src/runtime/directory-sync/index.ts
@@ -4,6 +4,7 @@ import type {
   FetchAgentsEntry,
   FetchAgentsOptions,
 } from "@getpaseo/client/internal/daemon-client";
+import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import { fetchAgentTimelineOnce } from "@/timeline/fetch-agent-timeline-once";
 import {
   normalizeProjectDescriptor,
@@ -160,6 +161,7 @@ export class DirectorySync {
   private readonly fullDemandSources = new Set<object>();
   private readonly scriptStatusDemand = new Map<object, string>();
   private demandRefresh: Promise<void> | null = null;
+  private subscriptionGeneration = 0;
   private satisfiedDemandSource: DirectorySourceToken | null = null;
   private cursors: DirectoryCheckpoint = {};
 
@@ -262,6 +264,7 @@ export class DirectorySync {
   }
 
   private releaseSubscriptions(): void {
+    this.subscriptionGeneration += 1;
     for (const subscription of [
       this.agentSubscription,
       this.workspaceSubscription,
@@ -362,6 +365,7 @@ export class DirectorySync {
     this.observeDirectoryEvents();
     this.observeScriptStatusEvents();
     const source = this.connection.source;
+    const subscriptionGeneration = this.subscriptionGeneration;
     if (
       !force &&
       this.satisfiedDemandSource?.clientGeneration === source.clientGeneration &&
@@ -378,17 +382,19 @@ export class DirectorySync {
           ]).then(() => undefined);
     this.demandRefresh = refresh
       .then(() => {
-        this.satisfiedDemandSource = source;
+        if (this.subscriptionGeneration === subscriptionGeneration) {
+          this.satisfiedDemandSource = source;
+        }
         return undefined;
       })
       .finally(() => {
         this.demandRefresh = null;
         const current = this.connection.source;
-        if (
-          this.hasDemand() &&
-          (current.clientGeneration !== source.clientGeneration ||
-            current.connectionEpoch !== source.connectionEpoch)
-        ) {
+        const sourceChanged =
+          current.clientGeneration !== source.clientGeneration ||
+          current.connectionEpoch !== source.connectionEpoch;
+        const subscriptionsReleased = this.subscriptionGeneration !== subscriptionGeneration;
+        if (this.hasDemand() && (sourceChanged || subscriptionsReleased)) {
           void this.requestDemandRefresh().catch(() => undefined);
         }
       });
@@ -477,6 +483,26 @@ export class DirectorySync {
     return page;
   }
 
+  /**
+   * Captures these chats' lifecycle before a subscribe. The returned function keeps the agent rows
+   * its answer carries, which is what a timeline fetch would have delivered for each of them.
+   */
+  captureSubscribedAgents(
+    agentIds: string[],
+  ): (agents: Record<string, AgentSnapshotPayload>) => void {
+    const tokens = new Map(agentIds.map((id) => [id, this.agents.captureTimeline(id)]));
+    return (agents) => {
+      let accepted = false;
+      for (const [agentId, agent] of Object.entries(agents)) {
+        const token = tokens.get(agentId);
+        if (token && this.agents.submitTimelineAgent(token, agent)) accepted = true;
+      }
+      if (!accepted) return;
+      this.revision += 1;
+      this.persistCheckpoint();
+    };
+  }
+
   async refreshAgents(
     input: RefreshAgentDirectoryInput = {},
   ): Promise<RefreshAgentDirectoryResult> {
diff --git a/packages/app/src/runtime/directory-sync/internal/agent-store.ts b/packages/app/src/runtime/directory-sync/internal/agent-store.ts
index 97c8208da5..04f27e3112 100644
--- a/packages/app/src/runtime/directory-sync/internal/agent-store.ts
+++ b/packages/app/src/runtime/directory-sync/internal/agent-store.ts
@@ -21,6 +21,26 @@ function withoutAgent(agentId: string) {
   };
 }
 
+/**
+ * Every update arrives as a whole new agent, so each nested value (capabilities, modes, labels) is
+ * a new object even when it did not change. Keep the stored value for every field that is equal,
+ * and the stored agent when nothing changed, so a reader of one field sees a new value only when
+ * that field changes.
+ */
+function keepUnchangedFields(stored: Agent, incoming: Agent): Agent {
+  const next = { ...incoming };
+  let changed = Object.keys(stored).length !== Object.keys(next).length;
+  for (const key of Object.keys(next) as (keyof Agent)[]) {
+    if (next[key] === stored[key]) continue;
+    if (key in stored && equal(next[key], stored[key])) {
+      Object.assign(next, { [key]: stored[key] });
+    } else {
+      changed = true;
+    }
+  }
+  return changed ? next : stored;
+}
+
 function mergeSnapshotTurn(previous: Agent | undefined, incoming: Agent): Agent {
   if (!previous) return incoming;
   const activeTurn =
@@ -59,7 +79,8 @@ export class AgentStoreProjection {
     let accepted = agent;
     useSessionStore.getState().setAgents(this.serverId, (current) => {
       const previous = current.get(agent.id);
-      accepted = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
+      const winner = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
+      accepted = previous ? keepUnchangedFields(previous, winner) : winner;
       if (accepted === previous) return current;
       const next = new Map(current);
       next.set(agent.id, accepted);
@@ -117,7 +138,7 @@ export class AgentStoreProjection {
     for (const [agentId, fetchedAgent] of fetched) {
       const existing = current.get(agentId);
       const merged = mergeSnapshotTurn(existing, fetchedAgent);
-      agents.set(agentId, existing && equal(existing, merged) ? existing : merged);
+      agents.set(agentId, existing ? keepUnchangedFields(existing, merged) : merged);
       if (fetchedAgent.archivedAt) {
         clearArchiveAgentPending({ queryClient, serverId: this.serverId, agentId });
       }
@@ -169,9 +190,6 @@ export class AgentStoreProjection {
       agentLastActivity.delete(agentId);
       return { ...state, agentLastActivity };
     });
-    useDraftStore.getState().clearDraftInput({
-      draftKey: buildDraftStoreKey({ serverId: this.serverId, agentId }),
-    });
     const initKey = getInitKey(this.serverId, agentId);
     if (getInitDeferred(initKey)) {
       rejectInitDeferred(initKey, new Error("Agent was removed during initialization"));
@@ -180,11 +198,15 @@ export class AgentStoreProjection {
 
   remove(agentId: string): void {
     this.removeFromDirectory(agentId);
+    useDraftStore.getState().clearDraftInput({
+      draftKey: buildDraftStoreKey({ serverId: this.serverId, agentId }),
+    });
     // Only entity deletion destroys the transcript. A filtered active-list
     // response can arrive after a fresh history response for an archived agent.
     const store = useSessionStore.getState();
     const removeKey = withoutAgent(agentId);
     store.setAgentTimelineCursor(this.serverId, removeKey);
+    store.setAgentTimelineUnsettledTurn(this.serverId, agentId, null);
     store.setAgentAuthoritativeHistoryApplied(this.serverId, agentId, false);
     store.setAgentStreamTail(this.serverId, removeKey);
     store.clearAgentStreamHead(this.serverId, agentId);
diff --git a/packages/app/src/runtime/directory-sync/workspace-replica.test.ts b/packages/app/src/runtime/directory-sync/workspace-replica.test.ts
index 792c005100..e3aa345d74 100644
--- a/packages/app/src/runtime/directory-sync/workspace-replica.test.ts
+++ b/packages/app/src/runtime/directory-sync/workspace-replica.test.ts
@@ -9,6 +9,8 @@ import {
 import {
   clearWorkspaceArchivePending,
   markWorkspaceArchivePending,
+  markWorkspaceArchiveUndoPending,
+  settleWorkspaceArchiveIntent,
 } from "@/contexts/session-workspace-upserts";
 import { useWorkspaceSetupStore } from "@/stores/workspace-setup-store";
 import { WorkspaceDirectoryReplica } from "./workspace-replica";
@@ -378,3 +380,53 @@ it("restores a missing workspace after an archive failure without replacing a li
     store.clearSession(serverId);
   }
 });
+
+it("keeps a workspace whose archive is being undone when the host reports its removal", () => {
+  const serverId = "workspace-archive-undo";
+  const store = useSessionStore.getState();
+  store.initializeSession(serverId, null as unknown as DaemonClient);
+  const replica = new WorkspaceDirectoryReplica(serverId);
+  const restored = normalizeWorkspaceDescriptor(workspace("restored"));
+
+  const undo = markWorkspaceArchiveUndoPending({ serverId, workspaceId: restored.id });
+  try {
+    replica.acceptWorkspaces([restored]);
+
+    expect(replica.applyDelta({ kind: "remove", id: restored.id })).toEqual([]);
+    expect(useSessionStore.getState().sessions[serverId]?.workspaces.has(restored.id)).toBe(true);
+
+    settleWorkspaceArchiveIntent(undo);
+    replica.applyDelta({ kind: "remove", id: restored.id });
+    expect(useSessionStore.getState().sessions[serverId]?.workspaces.has(restored.id)).toBe(false);
+  } finally {
+    settleWorkspaceArchiveIntent(undo);
+    store.clearSession(serverId);
+  }
+});
+
+it("keeps a workspace whose archive is being undone when a refresh snapshot omits it", () => {
+  const serverId = "workspace-archive-undo-refresh";
+  const store = useSessionStore.getState();
+  store.initializeSession(serverId, null as unknown as DaemonClient);
+  const replica = new WorkspaceDirectoryReplica(serverId);
+  const restored = normalizeWorkspaceDescriptor(workspace("restored"));
+  const other = normalizeWorkspaceDescriptor(workspace("other"));
+  const workspaceIds = () => [
+    ...(useSessionStore.getState().sessions[serverId]?.workspaces.keys() ?? []),
+  ];
+
+  const undo = markWorkspaceArchiveUndoPending({ serverId, workspaceId: restored.id });
+  try {
+    replica.acceptWorkspaces([restored]);
+
+    replica.commitSnapshot({ workspaces: new Map([[other.id, other]]), projects: new Map() }, []);
+    expect(workspaceIds().sort()).toEqual(["other", "restored"]);
+
+    settleWorkspaceArchiveIntent(undo);
+    replica.commitSnapshot({ workspaces: new Map([[other.id, other]]), projects: new Map() }, []);
+    expect(workspaceIds()).toEqual(["other"]);
+  } finally {
+    settleWorkspaceArchiveIntent(undo);
+    store.clearSession(serverId);
+  }
+});
diff --git a/packages/app/src/runtime/directory-sync/workspace-replica.ts b/packages/app/src/runtime/directory-sync/workspace-replica.ts
index 8f21ebd214..b5a7895467 100644
--- a/packages/app/src/runtime/directory-sync/workspace-replica.ts
+++ b/packages/app/src/runtime/directory-sync/workspace-replica.ts
@@ -14,6 +14,7 @@ import { useWorkspaceSetupStore } from "@/stores/workspace-setup-store";
 import {
   clearWorkspaceArchivePending,
   shouldSuppressWorkspaceForLocalArchive,
+  shouldSuppressWorkspaceRemovalForLocalUndo,
 } from "@/contexts/session-workspace-upserts";
 import { resolveWorkspaceMapKeyByIdentity } from "@/utils/workspace-identity";
 import type { DirectoryReplicaMutation } from "@/runtime/replica-cache";
@@ -107,6 +108,15 @@ export class WorkspaceDirectoryReplica {
         workspaces.set(workspaceId, workspace);
       }
     }
+    // A snapshot taken while an undo runs can predate the restore; the host publishes the row.
+    for (const [workspaceId, workspace] of this.workspaces) {
+      if (
+        !workspaces.has(workspaceId) &&
+        shouldSuppressWorkspaceRemovalForLocalUndo({ serverId: this.serverId, workspaceId })
+      ) {
+        workspaces.set(workspaceId, workspace);
+      }
+    }
     for (const workspace of workspaces.values()) this.applySetupStatus(workspace);
     this.workspaces = workspaces;
     this.projects = new Map(snapshot.projects);
@@ -173,6 +183,12 @@ export class WorkspaceDirectoryReplica {
       kind: "remove";
     },
   ): DirectoryReplicaMutation[] {
+    // The archive this remove reports is being undone; the host publishes the restored row.
+    if (
+      shouldSuppressWorkspaceRemovalForLocalUndo({ serverId: this.serverId, workspaceId: delta.id })
+    ) {
+      return [];
+    }
     this.deleteWorkspace(delta.id);
     const mutations: DirectoryReplicaMutation[] = [
       { kind: "workspace", type: "delete", id: delta.id },
diff --git a/packages/app/src/runtime/host-logger.test.ts b/packages/app/src/runtime/host-logger.test.ts
new file mode 100644
index 0000000000..fa53ca7668
--- /dev/null
+++ b/packages/app/src/runtime/host-logger.test.ts
@@ -0,0 +1,72 @@
+import { expect, it } from "vitest";
+import { createHostLogger } from "./host-logger";
+
+it("preserves the original transport cause and tolerates a cyclic cause chain", () => {
+  const lines: string[] = [];
+  const capture = (...values: unknown[]) => lines.push(values.map(String).join(" "));
+  const logger = createHostLogger(() => "test-host", {
+    log: capture,
+    warn: capture,
+    error: capture,
+  });
+  const transport = new Error("socket closed");
+  const wrapper = new Error("Subscription failed", { cause: transport });
+  Object.defineProperty(transport, "cause", { value: wrapper });
+  logger.error({ err: wrapper }, "subscription_error");
+  const record = JSON.parse(lines[0]!.slice("subscription_error ".length));
+  expect(record.err.cause.message).toBe("socket closed");
+  expect(record.err.cause.stack).toBe(transport.stack);
+  expect(record.err.cause.cause).toBe("[Circular]");
+});
+
+it("retains host and error details in the desktop's text-only console capture", () => {
+  const lines: { level: string; text: string }[] = [];
+  const capture =
+    (level: string) =>
+    (...values: unknown[]) => {
+      lines.push({ level, text: values.map(String).join(" ") });
+    };
+  const logger = createHostLogger(() => "offline-host", {
+    log: capture("info"),
+    warn: capture("warn"),
+    error: capture("error"),
+  });
+  logger.warn(
+    { err: { name: "Error", message: "malformed ready envelope" } },
+    "relay_e2ee_channel_error",
+  );
+  expect(lines).toEqual([
+    {
+      level: "warn",
+      text: 'relay_e2ee_channel_error {"serverId":"offline-host","err":{"name":"Error","message":"malformed ready envelope"}}',
+    },
+  ]);
+});
+
+it("keeps native Error messages and severity without failing on circular diagnostics", () => {
+  const lines: { level: string; text: string }[] = [];
+  const capture =
+    (level: string) =>
+    (...values: unknown[]) => {
+      lines.push({ level, text: values.map(String).join(" ") });
+    };
+  const logger = createHostLogger(() => "test-host", {
+    log: capture("info"),
+    warn: capture("warn"),
+    error: capture("error"),
+  });
+  const record: { err: Error; self?: object } = { err: new Error("connection lost") };
+  record.self = record;
+  logger.error(record, "Connection failed");
+  expect(lines[0]?.level).toBe("error");
+  expect(lines[0]?.text).toContain('"message":"connection lost"');
+  expect(lines[0]?.text).toContain('"serverId":"test-host"');
+  expect(lines[0]?.text).toContain('"[Circular]"');
+  logger.info({ status: "offline" }, "Host status");
+  expect(lines[1]).toEqual({
+    level: "info",
+    text: 'Host status {"serverId":"test-host","status":"offline"}',
+  });
+  logger.debug({ status: "offline" }, "Host status");
+  expect(lines).toHaveLength(2);
+});
diff --git a/packages/app/src/runtime/host-logger.ts b/packages/app/src/runtime/host-logger.ts
new file mode 100644
index 0000000000..3950038600
--- /dev/null
+++ b/packages/app/src/runtime/host-logger.ts
@@ -0,0 +1,36 @@
+import type { Logger } from "@getpaseo/client/internal/daemon-client";
+
+export function createHostLogger(
+  readServerId: () => string | undefined,
+  output: Pick<Console, "log" | "warn" | "error"> = console,
+): Logger {
+  const format = (record: object, message?: string): string => {
+    const seen = new WeakSet<object>();
+    const details = JSON.stringify(
+      { serverId: readServerId(), ...record },
+      (_key, value: unknown) => {
+        if (value && typeof value === "object") {
+          if (seen.has(value)) return "[Circular]";
+          seen.add(value);
+          if (value instanceof Error) {
+            return {
+              ...value,
+              name: value.name,
+              message: value.message,
+              stack: value.stack,
+              cause: value.cause,
+            };
+          }
+        }
+        return value;
+      },
+    );
+    return message ? `${message} ${details}` : details;
+  };
+  return {
+    debug: () => {},
+    info: (record, message) => output.log(format(record, message)),
+    warn: (record, message) => output.warn(format(record, message)),
+    error: (record, message) => output.error(format(record, message)),
+  };
+}
diff --git a/packages/app/src/runtime/host-runtime.test.ts b/packages/app/src/runtime/host-runtime.test.ts
index 33e4f1a316..c802a945c3 100644
--- a/packages/app/src/runtime/host-runtime.test.ts
+++ b/packages/app/src/runtime/host-runtime.test.ts
@@ -430,6 +430,20 @@ function agentPermission(id: string): AgentPermissionRequest {
   return { id, provider: "codex", name: id, kind: "tool", title: id };
 }
 
+const relayPrimary: HostConnection = {
+  id: "relay:relay.paseo.sh:443",
+  type: "relay",
+  relayEndpoint: "relay.paseo.sh:443",
+  daemonPublicKeyB64: "pk_test",
+};
+
+const relayAlternate: HostConnection = {
+  id: "relay:relay-next.paseo.sh:443",
+  type: "relay",
+  relayEndpoint: "relay-next.paseo.sh:443",
+  daemonPublicKeyB64: "pk_test",
+};
+
 function makeHost(input?: Partial<HostProfile>): HostProfile {
   const direct: HostConnection = {
     id: "direct:lan:6767",
@@ -1189,6 +1203,151 @@ describe("HostRuntimeController", () => {
     expect(controller.getSnapshot().client).toBe(activeClient as unknown as DaemonClient);
   });
 
+  it.each([40, null])(
+    "keeps the selected connection when it reconnects before an alternative probe resolves with heartbeat RTT %s",
+    async (reconnectedRtt) => {
+      useHostRuntimeClock();
+      const primary: HostConnection = {
+        id: "relay:relay.paseo.sh:443",
+        type: "relay",
+        relayEndpoint: "relay.paseo.sh:443",
+        daemonPublicKeyB64: "pk_test",
+      };
+      const alternative: HostConnection = {
+        id: "relay:relay-next.paseo.sh:443",
+        type: "relay",
+        relayEndpoint: "relay-next.paseo.sh:443",
+        daemonPublicKeyB64: "pk_test",
+      };
+      const host = makeHost({
+        connections: [primary, alternative],
+        preferredConnectionId: primary.id,
+      });
+      const activeClient = new FakeDaemonClient();
+      activeClient.setConnectionState({ status: "connected" });
+      activeClient.heartbeatReportsRtt(40);
+      // The first alternative probe (startup) answers immediately; the one that
+      // runs after the foreground is slow, like a relay handshake on mobile.
+      const slowAlternativeProbe = createDeferred<void>();
+      let alternativeProbes = 0;
+      const createdClients: FakeDaemonClient[] = [];
+      const controller = new HostRuntimeController({
+        host,
+        deps: {
+          createClient: () => {
+            const client = new FakeDaemonClient();
+            createdClients.push(client);
+            return client as unknown as DaemonClient;
+          },
+          connectToDaemon: async ({ connection }) => {
+            if (connection.id !== alternative.id) {
+              throw new Error(`unexpected probe for ${connection.id}`);
+            }
+            alternativeProbes += 1;
+            if (alternativeProbes > 1) await slowAlternativeProbe.promise;
+            return {
+              client: makeConnectedProbeClient(60) as unknown as DaemonClient,
+              serverId: host.serverId,
+              hostname: host.label ?? null,
+            };
+          },
+          getClientId: async () => "cid_test_runtime",
+        },
+      });
+      await controller.start({
+        autoProbe: false,
+        initialConnection: {
+          connectionId: primary.id,
+          existingClient: activeClient as unknown as DaemonClient,
+        },
+      });
+      expect(controller.getSnapshot().activeConnectionId).toBe(primary.id);
+
+      // The relay closed the socket while the app was in the background.
+      activeClient.setConnectionState({ status: "disconnected", reason: "1012" });
+      await vi.advanceTimersByTimeAsync(130_000);
+
+      // Foreground: the probe cycle starts while the selected client is still down ...
+      const cycle = controller.runProbeCycleNow();
+      await vi.advanceTimersByTimeAsync(1_000);
+      expect(alternativeProbes).toBe(2);
+      // ... the selected client reconnects ...
+      activeClient.heartbeatReportsRtt(reconnectedRtt);
+      activeClient.setConnectionState({ status: "connected" });
+      expect(controller.getSnapshot().connectionStatus).toBe("online");
+      const statuses: string[] = [];
+      controller.subscribe(() => statuses.push(controller.getSnapshot().connectionStatus));
+      // ... and only then does the alternative probe come back.
+      slowAlternativeProbe.resolve();
+      await cycle;
+
+      // Once the selected connection is back online, nothing should take it down again.
+      expect(statuses.filter((status) => status !== "online")).toEqual([]);
+      expect(controller.getSnapshot().activeConnectionId).toBe(primary.id);
+      expect(controller.getSnapshot().client).toBe(activeClient as unknown as DaemonClient);
+      expect(activeClient.isDisposed()).toBe(false);
+      expect(createdClients).toEqual([]);
+    },
+  );
+
+  it("fails over when the selected connection stays down until an alternative probe resolves", async () => {
+    useHostRuntimeClock();
+    const primary: HostConnection = {
+      id: "relay:relay.paseo.sh:443",
+      type: "relay",
+      relayEndpoint: "relay.paseo.sh:443",
+      daemonPublicKeyB64: "pk_test",
+    };
+    const alternative: HostConnection = {
+      id: "relay:relay-next.paseo.sh:443",
+      type: "relay",
+      relayEndpoint: "relay-next.paseo.sh:443",
+      daemonPublicKeyB64: "pk_test",
+    };
+    const host = makeHost({
+      connections: [primary, alternative],
+      preferredConnectionId: primary.id,
+    });
+    const activeClient = new FakeDaemonClient();
+    activeClient.setConnectionState({ status: "connected" });
+    const slowAlternativeProbe = createDeferred<void>();
+    let alternativeProbes = 0;
+    const controller = new HostRuntimeController({
+      host,
+      deps: {
+        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
+        connectToDaemon: async () => {
+          alternativeProbes += 1;
+          if (alternativeProbes > 1) await slowAlternativeProbe.promise;
+          return {
+            client: makeConnectedProbeClient(60) as unknown as DaemonClient,
+            serverId: host.serverId,
+            hostname: host.label ?? null,
+          };
+        },
+        getClientId: async () => "cid_test_runtime",
+      },
+    });
+    await controller.start({
+      autoProbe: false,
+      initialConnection: {
+        connectionId: primary.id,
+        existingClient: activeClient as unknown as DaemonClient,
+      },
+    });
+
+    activeClient.setConnectionState({ status: "disconnected", reason: "1012" });
+    await vi.advanceTimersByTimeAsync(130_000);
+    const cycle = controller.runProbeCycleNow();
+    await vi.advanceTimersByTimeAsync(1_000);
+    slowAlternativeProbe.resolve();
+    await cycle;
+
+    expect(controller.getSnapshot().activeConnectionId).toBe(alternative.id);
+    expect(activeClient.isDisposed()).toBe(true);
+    await controller.stop();
+  });
+
   it("rejects probes that resolve to a different server id", async () => {
     const host = makeHost({
       serverId: "srv_old",
@@ -1421,6 +1580,233 @@ describe("HostRuntimeController", () => {
     expect(switched).toBe(true);
   });
 
+  it("keeps the live connection while one alternate sample is re-read at active ticks", async () => {
+    // Replays the recorded Android sequence: both relays probed at startup, the alternate
+    // measured once, then only the active connection is re-read every ten seconds.
+    useHostRuntimeClock();
+    const host = makeHost({
+      connections: [relayPrimary, relayAlternate],
+      preferredConnectionId: relayPrimary.id,
+    });
+    const clients: FakeDaemonClient[] = [];
+    const latencies: Record<string, number | Error> = {
+      [relayPrimary.id]: 1053,
+      [relayAlternate.id]: 251,
+    };
+    const controller = new HostRuntimeController({
+      host,
+      deps: makeDeps(latencies, clients),
+    });
+
+    await controller.start();
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayPrimary.id);
+    const activeClient = controller.getSnapshot().client as unknown as FakeDaemonClient;
+    const clientsAfterStart = clients.length;
+
+    await vi.advanceTimersByTimeAsync(10_500);
+    activeClient.heartbeatReportsRtt(376);
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    expect(clients.length).toBe(clientsAfterStart);
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayPrimary.id);
+    expect(controller.getSnapshot().client).toBe(activeClient);
+    expect(activeClient.isDisposed()).toBe(false);
+    await controller.stop();
+  });
+
+  it("does not hold the previous socket's RTT against a reconnected active connection", async () => {
+    // Replays the recorded foreground recovery: the active client reconnects on its own while an
+    // alternate probe is in flight. The recovered socket has no heartbeat RTT yet.
+    useHostRuntimeClock();
+    const host = makeHost({
+      connections: [relayPrimary, relayAlternate],
+      preferredConnectionId: relayPrimary.id,
+    });
+    const clients: FakeDaemonClient[] = [];
+    const latencies: Record<string, number | Error> = {
+      [relayPrimary.id]: 300,
+      [relayAlternate.id]: 392,
+    };
+    let connectGate: Promise<void> | null = null;
+    const baseDeps = makeDeps(latencies, clients);
+    const controller = new HostRuntimeController({
+      host,
+      deps: {
+        ...baseDeps,
+        connectToDaemon: async (input) => {
+          if (connectGate) await connectGate;
+          return baseDeps.connectToDaemon(input);
+        },
+      },
+    });
+
+    await controller.start();
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayPrimary.id);
+    const activeClient = controller.getSnapshot().client as unknown as FakeDaemonClient;
+    activeClient.heartbeatReportsRtt(403);
+    await vi.advanceTimersByTimeAsync(150_500);
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayPrimary.id);
+
+    activeClient.setConnectionState({ status: "disconnected", reason: "liveness_timeout" });
+    activeClient.setConnectionState({ status: "connecting", attempt: 2 });
+    activeClient.heartbeatReportsRtt(null);
+    latencies[relayAlternate.id] = 280;
+    const alternateConnect = createDeferred<void>();
+    connectGate = alternateConnect.promise;
+    await vi.advanceTimersByTimeAsync(2_800);
+    activeClient.setConnectionState({ status: "connected" });
+    await vi.advanceTimersByTimeAsync(500);
+    alternateConnect.resolve();
+    connectGate = null;
+    await vi.advanceTimersByTimeAsync(100);
+    expect(controller.getSnapshot().probeByConnectionId.get(relayAlternate.id)).toEqual({
+      status: "available",
+      latencyMs: 280,
+    });
+    const clientsAfterProbe = clients.length;
+
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    expect(clients.length).toBe(clientsAfterProbe);
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayPrimary.id);
+    expect(controller.getSnapshot().client).toBe(activeClient);
+    expect(activeClient.isDisposed()).toBe(false);
+    await controller.stop();
+  });
+
+  it("starts the switch streak over when the active socket reconnects", async () => {
+    useHostRuntimeClock();
+    const host = makeHost({ preferredConnectionId: "direct:lan:6767" });
+    const clients: FakeDaemonClient[] = [];
+    const latencies: Record<string, number | Error> = {
+      "direct:lan:6767": 15,
+      "relay:relay.paseo.sh:443": 60,
+    };
+    const controller = new HostRuntimeController({
+      host,
+      deps: makeDeps(latencies, clients),
+    });
+
+    await controller.start({ autoProbe: false });
+    expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+    const activeClient = controller.getSnapshot().client as unknown as FakeDaemonClient;
+
+    latencies["relay:relay.paseo.sh:443"] = 30;
+    activeClient.heartbeatReportsRtt(95);
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+      expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+    }
+
+    activeClient.setConnectionState({ status: "disconnected", reason: "network changed" });
+    activeClient.setConnectionState({ status: "connected" });
+    activeClient.heartbeatReportsRtt(95);
+    await vi.advanceTimersByTimeAsync(120_000);
+    await controller.runProbeCycleNow();
+    expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+    }
+    expect(controller.getSnapshot().activeConnectionId).toBe("relay:relay.paseo.sh:443");
+    await controller.stop();
+  });
+
+  it("ends the switch streak when a fresh probe of the alternate fails", async () => {
+    useHostRuntimeClock();
+    const host = makeHost({ preferredConnectionId: "direct:lan:6767" });
+    const clients: FakeDaemonClient[] = [];
+    const latencies: Record<string, number | Error> = {
+      "direct:lan:6767": 15,
+      "relay:relay.paseo.sh:443": 60,
+    };
+    const controller = new HostRuntimeController({
+      host,
+      deps: makeDeps(latencies, clients),
+    });
+
+    await controller.start({ autoProbe: false });
+    expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+    const activeClient = controller.getSnapshot().client as unknown as FakeDaemonClient;
+    activeClient.heartbeatReportsRtt(95);
+
+    latencies["relay:relay.paseo.sh:443"] = 30;
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+      expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+    }
+
+    latencies["relay:relay.paseo.sh:443"] = new Error("relay unreachable");
+    await vi.advanceTimersByTimeAsync(120_000);
+    await controller.runProbeCycleNow();
+    expect(controller.getSnapshot().probeByConnectionId.get("relay:relay.paseo.sh:443")).toEqual({
+      status: "unavailable",
+      latencyMs: null,
+    });
+
+    latencies["relay:relay.paseo.sh:443"] = 30;
+    await vi.advanceTimersByTimeAsync(120_000);
+    await controller.runProbeCycleNow();
+    expect(controller.getSnapshot().activeConnectionId).toBe("direct:lan:6767");
+
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+    }
+    expect(controller.getSnapshot().activeConnectionId).toBe("relay:relay.paseo.sh:443");
+    await controller.stop();
+  });
+
+  it("restarts the streak when a different candidate becomes the fastest fresh sample", async () => {
+    useHostRuntimeClock();
+    const direct: HostConnection = {
+      id: "direct:lan:6767",
+      type: "directTcp",
+      endpoint: "lan:6767",
+    };
+    const host = makeHost({
+      connections: [direct, relayPrimary, relayAlternate],
+      preferredConnectionId: direct.id,
+    });
+    const clients: FakeDaemonClient[] = [];
+    const latencies: Record<string, number | Error> = {
+      [direct.id]: 15,
+      [relayPrimary.id]: 60,
+      [relayAlternate.id]: 70,
+    };
+    const controller = new HostRuntimeController({
+      host,
+      deps: makeDeps(latencies, clients),
+    });
+
+    await controller.start({ autoProbe: false });
+    expect(controller.getSnapshot().activeConnectionId).toBe(direct.id);
+    const activeClient = controller.getSnapshot().client as unknown as FakeDaemonClient;
+    activeClient.heartbeatReportsRtt(95);
+
+    latencies[relayPrimary.id] = 30;
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+      expect(controller.getSnapshot().activeConnectionId).toBe(direct.id);
+    }
+
+    latencies[relayAlternate.id] = 20;
+    await vi.advanceTimersByTimeAsync(120_000);
+    await controller.runProbeCycleNow();
+    expect(controller.getSnapshot().activeConnectionId).toBe(direct.id);
+
+    for (let index = 0; index < 2; index += 1) {
+      await vi.advanceTimersByTimeAsync(120_000);
+      await controller.runProbeCycleNow();
+    }
+    expect(controller.getSnapshot().activeConnectionId).toBe(relayAlternate.id);
+    await controller.stop();
+  });
+
   it("exposes one snapshot with active connection and status from same source", async () => {
     const host = makeHost();
     const clients: FakeDaemonClient[] = [];
diff --git a/packages/app/src/runtime/host-runtime.ts b/packages/app/src/runtime/host-runtime.ts
index 386908da15..02337229a7 100644
--- a/packages/app/src/runtime/host-runtime.ts
+++ b/packages/app/src/runtime/host-runtime.ts
@@ -1,5 +1,6 @@
 import { createHostPluginClientBundleStore } from "@/plugins/client-bundles";
 import { watchdog } from "@/watchdog";
+import { createHostLogger } from "./host-logger";
 import { createHostChannelTransport } from "@getpaseo/client/internal/hosts";
 import type { OwnedSubscription } from "@getpaseo/client";
 import type { HostDirectory } from "@getpaseo/protocol/hosts";
@@ -590,6 +591,7 @@ function createDefaultDeps(
         runtimeGeneration,
         capabilities: appCapabilities,
         trace: createPerformanceTrace({ host: host.serverId, connection: connection.id }),
+        logger: createHostLogger(() => host.serverId),
         providerSnapshots: "wire",
         createPluginClientBundleStore: createHostPluginClientBundleStore,
         ...(host.password ? { password: host.password } : {}),
@@ -670,6 +672,7 @@ function createDefaultDeps(
             null,
           ),
           reconnect: { enabled: false },
+          logger: createHostLogger(() => host.serverId),
           appVersion: resolveAppVersion() ?? undefined,
           createPluginClientBundleStore: createHostPluginClientBundleStore,
         });
@@ -1022,6 +1025,9 @@ export class HostRuntimeController {
       }
 
       const currentActiveConnectionId = this.snapshot.activeConnectionId;
+      if (currentActiveConnectionId) {
+        this.reconcileActiveProbeWithClient(currentActiveConnectionId, probeByConnectionId);
+      }
       const activeProbe = currentActiveConnectionId
         ? probeByConnectionId.get(currentActiveConnectionId)
         : null;
@@ -1058,37 +1064,46 @@ export class HostRuntimeController {
             expectedProbeVersion: requestVersion,
           });
         }
-        this.switchCandidateConnectionId = null;
-        this.switchCandidateHitCount = 0;
+        this.resetSwitchCandidate();
         return;
       }
 
-      if (!activeProbe || activeProbe.status !== "available") {
+      // Adaptive switching counts fresh comparisons only. The probe map keeps the last known
+      // sample per connection for display and failover; a streak hit needs a candidate measured
+      // in this cycle and a heartbeat RTT from the socket that is active right now. Re-reading
+      // the cached map at every ten-second active tick turned one idle-probe sample into three
+      // "consecutive" wins, and a reconnected socket inherited its predecessor's RTT, so a
+      // working relay connection was replaced within seconds of coming online.
+      const sampledCandidates = connectionsToProbe.filter(
+        (connection) => connection.id !== currentActiveConnectionId,
+      );
+      if (sampledCandidates.length === 0) {
+        // An active-only tick carries no evidence about any candidate.
+        return;
+      }
+      const fastest =
+        sampledCandidates
+          .flatMap((connection) => {
+            const probe = probeByConnectionId.get(connection.id);
+            return probe?.status === "available"
+              ? [{ connectionId: connection.id, latencyMs: probe.latencyMs }]
+              : [];
+          })
+          .sort((left, right) => left.latencyMs - right.latencyMs)[0] ?? null;
+      if (!fastest) {
+        // Every candidate sampled this cycle failed: that breaks the streak.
+        this.resetSwitchCandidate();
         return;
       }
 
-      const available = Array.from(probeByConnectionId.entries())
-        .filter(
-          (entry): entry is [string, Extract<ConnectionProbeState, { status: "available" }>] =>
-            entry[1].status === "available",
-        )
-        .map(([connectionId, probe]) => ({
-          connectionId,
-          latencyMs: probe.latencyMs,
-        }))
-        .sort((left, right) => left.latencyMs - right.latencyMs);
-
-      const fastest = available[0] ?? null;
-      if (!fastest || fastest.connectionId === currentActiveConnectionId) {
-        this.switchCandidateConnectionId = null;
-        this.switchCandidateHitCount = 0;
+      const activeRttMs = this.currentActiveSocketRttMs();
+      if (activeRttMs === null) {
         return;
       }
 
-      const improvement = activeProbe.latencyMs - fastest.latencyMs;
+      const improvement = activeRttMs - fastest.latencyMs;
       if (improvement < ADAPTIVE_SWITCH_THRESHOLD_MS) {
-        this.switchCandidateConnectionId = null;
-        this.switchCandidateHitCount = 0;
+        this.resetSwitchCandidate();
         return;
       }
 
@@ -1100,8 +1115,7 @@ export class HostRuntimeController {
       }
 
       if (this.switchCandidateHitCount >= ADAPTIVE_SWITCH_CONSECUTIVE_PROBES) {
-        this.switchCandidateConnectionId = null;
-        this.switchCandidateHitCount = 0;
+        this.resetSwitchCandidate();
         await this.switchToConnection({
           connectionId: fastest.connectionId,
           expectedProbeVersion: requestVersion,
@@ -1212,6 +1226,40 @@ export class HostRuntimeController {
     });
   }
 
+  // The client clears its heartbeat RTT when a socket connects, so a connected client's RTT
+  // describes the socket in use right now; a reconnecting client still carries the old one.
+  private currentActiveSocketRttMs(): number | null {
+    const client = this.snapshot.client;
+    if (!client || client.getConnectionState().status !== "connected") return null;
+    return client.getLastLivenessRttMs();
+  }
+
+  private resetSwitchCandidate(): void {
+    this.switchCandidateConnectionId = null;
+    this.switchCandidateHitCount = 0;
+  }
+
+  // The active connection is probed through its own client, which may still be
+  // reconnecting when the probe starts. A verdict taken then is stale if the client
+  // has since connected, so the decision uses the client's current state.
+  private reconcileActiveProbeWithClient(
+    connectionId: string,
+    probeByConnectionId: Map<string, ConnectionProbeState>,
+  ): void {
+    if (probeByConnectionId.get(connectionId)?.status !== "unavailable") return;
+    if (this.authRejectedConnectionIds.has(connectionId)) return;
+    const client = this.snapshot.client;
+    if (!client || client.getConnectionState().status !== "connected") return;
+    const rttMs = client.getLastLivenessRttMs();
+    probeByConnectionId.set(
+      connectionId,
+      rttMs === null
+        ? { status: "pending", latencyMs: null }
+        : { status: "available", latencyMs: rttMs },
+    );
+    this.updateSnapshot({ probeByConnectionId: new Map(probeByConnectionId) });
+  }
+
   private isConnectionUnavailable(
     connectionId: string,
     probe: ConnectionProbeState | null | undefined,
@@ -1480,6 +1528,8 @@ export class HostRuntimeController {
           return;
         }
         if (state.status === "connected") this.learnRelaySecurity(client, connection.id);
+        // Switch evidence belongs to the socket it was measured against.
+        if (state.status !== "connected") this.resetSwitchCandidate();
         this.applyConnectionEvent({ type: "client_state", state, lastError: client.lastError });
         this.updateSnapshot({
           ...toSnapshotConnectionPatch(this.connectionMachineState, this.connectionEpoch),
@@ -2836,7 +2886,22 @@ export class HostRuntimeStore {
       replica,
       replaceDemandedAgentIds: (agentIds) => directory.setAgentRouteDemand(agentIds),
       drainQueuedAgentMessage: (agentId) => this.drainQueuedAgentMessage(serverId, agentId),
-      ports,
+      applyTurnLiveness: (agentId, transitions) =>
+        directory.applyAgentTurnLiveness(agentId, transitions),
+      ports: {
+        ...ports,
+        observe: (agentIds, cursors) => {
+          const keepAgents = directory.captureSubscribedAgents(agentIds);
+          const observation = ports.observe(agentIds, cursors);
+          return {
+            ready: observation.ready.then((answer) => {
+              if (answer?.agents) keepAgents(answer.agents);
+              return answer;
+            }),
+            release: () => observation.release(),
+          };
+        },
+      },
     });
   }
 
diff --git a/packages/app/src/runtime/replica-cache/index.test.ts b/packages/app/src/runtime/replica-cache/index.test.ts
index e4c76e4b60..9c8e8318d9 100644
--- a/packages/app/src/runtime/replica-cache/index.test.ts
+++ b/packages/app/src/runtime/replica-cache/index.test.ts
@@ -216,6 +216,19 @@ function timeline(text = "Cached") {
   };
 }
 
+it("keeps the unsettled turn with the cached messages", async () => {
+  const storage = new MemoryStorage();
+  const writer = createCache(storage);
+  const cached = {
+    ...timeline(),
+    unsettledTurn: { startedAt: new Date("2026-08-26T09:59:00.000Z"), turnId: "turn-1" },
+  };
+  writer.commitTimeline(SERVER_ID, "agent-1", cached);
+  await writer.flush();
+
+  expect(await createCache(storage).readTimeline(SERVER_ID, "agent-1")).toEqual(cached);
+});
+
 function commitDirectory(
   cache: ReplicaCache,
   serverId: string,
@@ -321,6 +334,26 @@ describe("ReplicaCache", () => {
     expect(restored?.range).toBeNull();
   });
 
+  it("preserves workspace parentage and its checkpoint across cache reopen", async () => {
+    const storage = new MemoryStorage();
+    const writer = createCache(storage);
+    const baseline = directory({ workspaces: { generation: "g", afterSeq: 8 } });
+    const workspace = normalizeWorkspaceDescriptor({
+      ...workspacePayload(),
+      parentWorkspaceId: "parent",
+    });
+    baseline.workspaces.set(workspace.id, workspace);
+    commitDirectory(writer, SERVER_ID, baseline);
+    await writer.flush();
+    const reader = createCache(storage);
+    const restored = await reader.readDirectory(SERVER_ID);
+    expect(restored.checkpoint).toEqual(baseline.checkpoint);
+    expect(restored.workspaces.get(workspace.id)?.parentWorkspaceId).toBe("parent");
+    expect((await reader.readWorkspace(SERVER_ID, workspace.id))?.workspace.parentWorkspaceId).toBe(
+      "parent",
+    );
+  });
+
   it("preserves workspace sorting timestamps across cache reopen", async () => {
     const storage = new MemoryStorage();
     const writer = createCache(storage);
@@ -513,6 +546,23 @@ describe("ReplicaCache", () => {
     expect(storage.changes[0]?.deletes).toEqual([]);
   });
 
+  it("keeps a background agent background across cache reopen", async () => {
+    const storage = new MemoryStorage();
+    const writer = createCache(storage);
+    const helper = { ...agent("helper"), background: true };
+    const visible = agent("visible");
+    writer.commitDirectoryMutations(SERVER_ID, [
+      { kind: "agent", type: "upsert", id: helper.id, value: helper },
+      { kind: "agent", type: "upsert", id: visible.id, value: visible },
+    ]);
+    await writer.flush();
+
+    const restored = await createCache(storage).readDirectory(SERVER_ID);
+
+    expect(restored.agents.get("helper")?.background).toBe(true);
+    expect(restored.agents.get("visible")?.background).toBe(false);
+  });
+
   it("round-trips identified and anonymous open turns without changing protocol status", async () => {
     const storage = new MemoryStorage();
     const writer = createCache(storage);
diff --git a/packages/app/src/runtime/replica-cache/index.ts b/packages/app/src/runtime/replica-cache/index.ts
index f4ebf0f001..448496ee0d 100644
--- a/packages/app/src/runtime/replica-cache/index.ts
+++ b/packages/app/src/runtime/replica-cache/index.ts
@@ -21,6 +21,7 @@ import {
   type StreamItem,
   type TimelinePosition,
 } from "@/types/stream";
+import type { UnsettledTurn } from "@/timeline/turn-liveness";
 import { normalizeAgentSnapshot } from "@/utils/agent-snapshots";
 import { clearLegacyReplicaCache } from "./legacy-cleanup";
 import {
@@ -68,6 +69,8 @@ export interface CachedTimeline {
   items: StreamItem[];
   range: AgentTimelineCursorState | null;
   hasOlder: boolean;
+  /** Set when these messages were captured while a turn was open and not yet caught up. */
+  unsettledTurn?: UnsettledTurn;
 }
 
 const PERSIST_DELAY_MS = 1_000;
@@ -241,6 +244,7 @@ const StoredAgentSnapshotSchema = z.strictObject({
   updatedAt: IsoDateSchema,
   lastUserMessageAt: IsoDateSchema.nullable(),
   status: AgentStatusSchema,
+  backgroundWork: z.object({ count: z.number().int().nonnegative() }).optional(),
   activeTurn: z
     .strictObject({
       turnId: z.string(),
@@ -256,6 +260,8 @@ const StoredAgentSnapshotSchema = z.strictObject({
   lastError: z.string().optional(),
   title: z.string().nullable(),
   labels: z.record(z.string(), z.string()),
+  // Optional: clients without background_agents never received a background agent to cache.
+  background: z.boolean().optional(),
   requiresAttention: z.boolean().optional(),
   attentionReason: z.enum(["finished", "error", "permission"]).nullable().optional(),
   attentionTimestamp: IsoDateSchema.nullable().optional(),
@@ -306,6 +312,7 @@ const WorkspaceGitRuntimeSchema = z
   .optional();
 
 const StoredWorkspaceSchema = z.strictObject({
+  parentWorkspaceId: z.string().optional(),
   // Require both keys: a cursor without these values would preserve the wrong sort on reconnect.
   createdAt: IsoDateSchema.nullable(),
   lastUserMessageAt: IsoDateSchema.nullable(),
@@ -361,6 +368,9 @@ const StoredTimelineSchema = z.strictObject({
     })
     .nullable(),
   hasOlder: z.boolean(),
+  unsettledTurn: z
+    .strictObject({ turnId: z.string().nullable(), startedAt: IsoDateSchema.nullable() })
+    .optional(),
 });
 
 type StoredAgent = z.infer<typeof StoredAgentSchema>;
@@ -421,6 +431,16 @@ function deserializeTimeline(stored: StoredTimeline | null): CachedTimeline | nu
     items: stored.items.map(deserializeTimelineItem),
     range: stored.range,
     hasOlder: stored.hasOlder,
+    ...(stored.unsettledTurn
+      ? {
+          unsettledTurn: {
+            turnId: stored.unsettledTurn.turnId,
+            startedAt: stored.unsettledTurn.startedAt
+              ? new Date(stored.unsettledTurn.startedAt)
+              : null,
+          },
+        }
+      : {}),
   };
 }
 
@@ -514,6 +534,9 @@ function serializeTimelineItem(item: StreamItem): StoredTimelineItem | null {
         version: item.version,
         data: item.data,
       };
+    // A folded turn's summary row is presentation, not timeline.
+    case "turn_summary":
+      return null;
   }
 }
 
@@ -634,6 +657,31 @@ function serializeAgentTurn(agent: Agent): NonNullable<StoredAgent["turn"]> {
   };
 }
 
+function serializeAgentCapabilities(
+  capabilities: Agent["capabilities"],
+): StoredAgent["snapshot"]["capabilities"] {
+  return {
+    supportsStreaming: capabilities.supportsStreaming,
+    supportsSessionPersistence: capabilities.supportsSessionPersistence,
+    ...(capabilities.supportsSessionListing !== undefined
+      ? { supportsSessionListing: capabilities.supportsSessionListing }
+      : {}),
+    supportsDynamicModes: capabilities.supportsDynamicModes,
+    supportsMcpServers: capabilities.supportsMcpServers,
+    supportsReasoningStream: capabilities.supportsReasoningStream,
+    supportsToolInvocations: capabilities.supportsToolInvocations,
+    ...(capabilities.supportsRewindConversation !== undefined
+      ? { supportsRewindConversation: capabilities.supportsRewindConversation }
+      : {}),
+    ...(capabilities.supportsRewindFiles !== undefined
+      ? { supportsRewindFiles: capabilities.supportsRewindFiles }
+      : {}),
+    ...(capabilities.supportsRewindBoth !== undefined
+      ? { supportsRewindBoth: capabilities.supportsRewindBoth }
+      : {}),
+  };
+}
+
 function serializeAgent(agent: Agent): StoredAgent {
   const snapshot = {
     id: agent.id,
@@ -654,26 +702,7 @@ function serializeAgent(agent: Agent): StoredAgent {
           },
         }
       : {}),
-    capabilities: {
-      supportsStreaming: agent.capabilities.supportsStreaming,
-      supportsSessionPersistence: agent.capabilities.supportsSessionPersistence,
-      ...(agent.capabilities.supportsSessionListing !== undefined
-        ? { supportsSessionListing: agent.capabilities.supportsSessionListing }
-        : {}),
-      supportsDynamicModes: agent.capabilities.supportsDynamicModes,
-      supportsMcpServers: agent.capabilities.supportsMcpServers,
-      supportsReasoningStream: agent.capabilities.supportsReasoningStream,
-      supportsToolInvocations: agent.capabilities.supportsToolInvocations,
-      ...(agent.capabilities.supportsRewindConversation !== undefined
-        ? { supportsRewindConversation: agent.capabilities.supportsRewindConversation }
-        : {}),
-      ...(agent.capabilities.supportsRewindFiles !== undefined
-        ? { supportsRewindFiles: agent.capabilities.supportsRewindFiles }
-        : {}),
-      ...(agent.capabilities.supportsRewindBoth !== undefined
-        ? { supportsRewindBoth: agent.capabilities.supportsRewindBoth }
-        : {}),
-    },
+    capabilities: serializeAgentCapabilities(agent.capabilities),
     currentModeId: agent.currentModeId,
     availableModes: [],
     pendingPermissions: [],
@@ -681,7 +710,9 @@ function serializeAgent(agent: Agent): StoredAgent {
     ...(agent.lastError ? { lastError: agent.lastError } : {}),
     title: agent.title,
     labels: agent.labels,
+    ...(agent.background ? { background: true } : {}),
     requiresAttention: agent.requiresAttention ?? false,
+    backgroundWork: agent.backgroundWork,
     attentionReason: agent.attentionReason ?? null,
     attentionTimestamp: agent.attentionTimestamp?.toISOString() ?? null,
     archivedAt: agent.archivedAt?.toISOString() ?? null,
@@ -720,6 +751,7 @@ function restoreWorkspace(stored: StoredWorkspace): WorkspaceDescriptor {
 
 function serializeWorkspace(workspace: WorkspaceDescriptor): StoredWorkspace {
   return {
+    parentWorkspaceId: workspace.parentWorkspaceId,
     createdAt: workspace.createdAt?.toISOString() ?? null,
     lastUserMessageAt: workspace.lastUserMessageAt?.toISOString() ?? null,
     id: workspace.id,
@@ -818,6 +850,14 @@ function serializeTimeline(timeline: CachedTimeline): StoredTimeline | null {
       ? { epoch: range.epoch, startSeq: range.startSeq, endSeq: range.endSeq }
       : null,
     hasOlder: canPersistCoverage ? timeline.hasOlder : false,
+    ...(timeline.unsettledTurn
+      ? {
+          unsettledTurn: {
+            turnId: timeline.unsettledTurn.turnId,
+            startedAt: timeline.unsettledTurn.startedAt?.toISOString() ?? null,
+          },
+        }
+      : {}),
   };
 }
 
diff --git a/packages/app/src/screens/new-workspace-picker-item.test.ts b/packages/app/src/screens/new-workspace-picker-item.test.ts
index a6c1e81845..fd1e97dd11 100644
--- a/packages/app/src/screens/new-workspace-picker-item.test.ts
+++ b/packages/app/src/screens/new-workspace-picker-item.test.ts
@@ -8,6 +8,7 @@ import {
   buildPickerOptionData,
   defaultBasePickerItem,
   pickerItemToCheckoutRequest,
+  startsNewBranch,
   type PickerItem,
 } from "./new-workspace-picker-item";
 
@@ -386,3 +387,20 @@ describe("starting-ref search", () => {
     },
   );
 });
+
+describe("startsNewBranch", () => {
+  it("is true for a branch-off and for no request, which is the default base on a detached HEAD", () => {
+    expect(startsNewBranch(undefined)).toBe(true);
+    expect(startsNewBranch({ action: "branch-off", refName: "main" })).toBe(true);
+  });
+
+  it("is false for a checkout of a branch or a change request", () => {
+    expect(startsNewBranch({ action: "checkout", refName: "feature" })).toBe(false);
+    expect(
+      startsNewBranch({
+        checkoutSource: { kind: "change_request", forge: "github", number: 7 },
+      }),
+    ).toBe(false);
+    expect(startsNewBranch({ githubPrNumber: 7 })).toBe(false);
+  });
+});
diff --git a/packages/app/src/screens/new-workspace-picker-item.ts b/packages/app/src/screens/new-workspace-picker-item.ts
index d02c7a0bf2..897f99a561 100644
--- a/packages/app/src/screens/new-workspace-picker-item.ts
+++ b/packages/app/src/screens/new-workspace-picker-item.ts
@@ -132,7 +132,7 @@ export interface BaseRefCheckoutStatus {
 
 // Display only. The exact ref is what every request carries; this is just how a ref reads in
 // a row label, so "refs/remotes/origin/other-name" shows as "other-name".
-function branchNameFromRef(refName: string): string {
+export function branchNameFromRef(refName: string): string {
   if (refName.startsWith("refs/heads/")) return refName.slice("refs/heads/".length);
   if (refName.startsWith(REMOTE_TRACKING_PREFIX)) {
     const remainder = refName.slice(REMOTE_TRACKING_PREFIX.length);
@@ -210,6 +210,17 @@ export function pickerItemToCheckoutRequest(
   }
 }
 
+/**
+ * Whether creating a worktree from this request cuts a new branch, which is what the daemon does
+ * for anything but a checkout. No request at all (a detached HEAD gives the screen no default
+ * base) cuts one from the repository's default branch.
+ */
+export function startsNewBranch(request: PickerCheckoutRequest | undefined): boolean {
+  if (!request) return true;
+  if (request.action === "checkout") return false;
+  return !request.checkoutSource && request.githubPrNumber === undefined;
+}
+
 export function prPickerOptionId(number: number): string {
   return `${PR_OPTION_PREFIX}${number}`;
 }
diff --git a/packages/app/src/screens/new-workspace-screen.tsx b/packages/app/src/screens/new-workspace-screen.tsx
index 3cb01ae9df..bab4df8f01 100644
--- a/packages/app/src/screens/new-workspace-screen.tsx
+++ b/packages/app/src/screens/new-workspace-screen.tsx
@@ -1,3 +1,4 @@
+import { useAddHost } from "@/hosts/add-host";
 import type {
   CreateAgentRequestOptions,
   CreateWorkspaceRequestOptions,
@@ -5,10 +6,10 @@ import type {
 import type { AgentSnapshotPayload, CreationSnapshot } from "@getpaseo/protocol/messages";
 import { encodeImages } from "@/utils/encode-images";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
-import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
+import { useIsFocused } from "expo-router/react-navigation";
 import { useTranslation } from "react-i18next";
-import { router } from "expo-router";
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { createNameId } from "mnemonic-id";
@@ -62,7 +63,6 @@ import type { KeyboardActionId } from "@/keyboard/keyboard-action-dispatcher";
 import { useFormPreferences } from "@/hooks/use-form-preferences";
 import type { CreateAgentInitialValues } from "@/hooks/use-agent-form-state";
 import { toErrorMessage } from "@/utils/error-messages";
-import { buildSettingsAddHostRoute } from "@/utils/host-routes";
 import {
   getHostProjectId,
   getWorktreeSupportForHostProject,
@@ -79,7 +79,7 @@ import type { MessagePayload } from "@/composer/types";
 import type { UserComposerAttachment } from "@/attachments/types";
 import type { AgentAttachment, ForgeSearchItem } from "@getpaseo/protocol/messages";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
-import type { AgentProvider } from "@getpaseo/protocol/agent-types";
+import type { AgentProvider, JsonValue } from "@getpaseo/protocol/agent-types";
 import type { WorkspaceDraftTabSetup, WorkspaceTabTarget } from "@/workspace-tabs/model";
 import { isEmptyWorkspaceSubmission, runCreateEmptyWorkspace } from "./new-workspace-empty";
 import {
@@ -91,6 +91,7 @@ import {
   defaultBasePickerItem,
   pickerItemLabel,
   pickerItemToCheckoutRequest,
+  startsNewBranch,
   type BranchPickerDetail,
   type PickerCheckoutRequest,
   type PickerItem,
@@ -98,10 +99,17 @@ import {
 } from "./new-workspace-picker-item";
 import {
   clearPickerPrAttachmentForTargetChange,
-  initialPickerSelectionState,
-  reducePickerSelection,
   syncPickerPrAttachment,
 } from "./new-workspace-picker-state";
+import {
+  PluginNewWorkspaceItems,
+  type NewWorkspaceItemsScreen,
+} from "@/plugins/new-workspace-items";
+import {
+  createNewWorkspaceSetup,
+  useNewWorkspaceSetupState,
+  type NewWorkspaceSetup,
+} from "./new-workspace/setup-model";
 import {
   resolveNewWorkspaceAutomaticServerId,
   resolveNewWorkspaceInitialServerId,
@@ -118,6 +126,7 @@ import {
 } from "./workspace/terminals/state";
 import { captureWorkspaceDraftCleanup } from "./new-workspace/background-handoff";
 import { useNewWorkspaceScreenPresence } from "./new-workspace/screen-presence";
+import { retriedAgentRequest } from "./new-workspace/retry-agent-request";
 
 function useIsNewWorkspaceDraftHandoffActive(input: {
   draftId: string | undefined;
@@ -193,30 +202,22 @@ interface WorkspaceIsolationState {
 // Preserve the user's worktree choice while route metadata is provisional. Once
 // the authoritative placement arrives, unsupported projects fall back to local.
 function useWorkspaceIsolation(input: {
+  setup: NewWorkspaceSetup;
   supportsMultiplicity: boolean;
-  worktreeSupport: "supported" | "unsupported" | "unknown";
+  canCreateWorktree: boolean;
 }): WorkspaceIsolationState {
-  const { supportsMultiplicity, worktreeSupport } = input;
+  const { setup, supportsMultiplicity, canCreateWorktree } = input;
   // The last isolation choice is remembered alongside the other New Workspace
   // form preferences (provider, model, mode). A manual in-screen pick overrides
   // the remembered default until the screen remounts.
-  const { preferences, updatePreferences } = useFormPreferences();
-  const [manualIsolation, setManualIsolation] = useState<"local" | "worktree" | null>(null);
+  const { preferences } = useFormPreferences();
+  const { manualIsolation } = useNewWorkspaceSetupState(setup);
   const isolation = manualIsolation ?? preferences.isolation ?? "local";
-  const canCreateWorktree = supportsMultiplicity && worktreeSupport !== "unsupported";
   const isWorktree = isolation === "worktree" && canCreateWorktree;
 
-  const setIsolation = useCallback(
-    (value: "local" | "worktree") => {
-      setManualIsolation(value);
-      void updatePreferences({ isolation: value });
-    },
-    [updatePreferences],
-  );
-
   return {
     isolation,
-    setIsolation,
+    setIsolation: setup.chooseIsolation,
     effectiveIsolation: isWorktree ? "worktree" : "local",
     canCreateWorktree,
     showRefPicker: !supportsMultiplicity || isWorktree,
@@ -271,7 +272,7 @@ interface WorkspaceDraftSubmissionConfig {
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: Record<string, unknown> | undefined;
   target: WorkspaceTabTarget;
 }
 
@@ -288,6 +289,10 @@ async function createMultiplicityWorkspace(input: {
   project: HostProjectListItem;
   sourceDirectory: string;
   checkoutRequest: PickerCheckoutRequest | undefined;
+  /** Names the new branch of a worktree cut from a branch. */
+  branchName: string | null;
+  /** Stored on the created workspace. */
+  metadata: Readonly<Record<string, JsonValue>>;
   withInitialAgent: boolean;
   agent?: CreateWorkspaceRequestOptions["agent"];
   onEvent?: (snapshot: CreationSnapshot) => void;
@@ -318,6 +323,9 @@ async function createMultiplicityWorkspace(input: {
           projectId,
           worktreeSlug: input.worktreeSlug,
           ...input.checkoutRequest,
+          ...(input.branchName && startsNewBranch(input.checkoutRequest)
+            ? { branchName: input.branchName }
+            : {}),
         }
       : {
           kind: "directory",
@@ -325,6 +333,7 @@ async function createMultiplicityWorkspace(input: {
           projectId,
         },
     ...(firstAgentContext ? { firstAgentContext } : {}),
+    ...(Object.keys(input.metadata).length > 0 ? { metadata: { ...input.metadata } } : {}),
   });
   if (payload.error || !payload.workspace) {
     throw new Error(payload.error ?? input.createFailedMessage);
@@ -374,7 +383,7 @@ function buildWorkspaceDraftSetupFromComposer(input: {
     modeId: input.composerState.effectiveModeId || null,
     model: input.composerState.effectiveModelId || null,
     thinkingOptionId: input.composerState.effectiveThinkingOptionId || null,
-    featureValues: input.composerState.featureValues ?? {},
+    providerOptions: input.composerState.providerOptions ?? {},
   };
 }
 
@@ -454,8 +463,9 @@ async function createWorkspaceChatAgent(input: CreateChatAgentInput): Promise<Su
       modeId: composerState.effectiveModeId || undefined,
       model: composerState.effectiveModelId || undefined,
       thinkingOptionId: composerState.effectiveThinkingOptionId || undefined,
-      featureValues: composerState.featureValues,
+      providerOptions: composerState.providerOptions,
     },
+    ...(Object.keys(composerState.metadata).length > 0 ? { metadata: composerState.metadata } : {}),
     initialPrompt: text,
     clientMessageId: `${input.draftId}:initial-message`,
     images: images?.length ? images : undefined,
@@ -509,14 +519,7 @@ async function createWorkspaceChatAgent(input: CreateChatAgentInput): Promise<Su
   const agentCreation = {
     result: Promise.resolve().then(() => execute()),
     retry: (request: CreateAgentRequestOptions) =>
-      execute({
-        ...initialAgent,
-        config: { ...request.config!, cwd },
-        initialPrompt: request.initialPrompt ?? "",
-        clientMessageId: initialAgent.clientMessageId,
-        images: request.images,
-        attachments: request.attachments,
-      }),
+      execute(retriedAgentRequest(initialAgent, request, cwd)),
   };
   await agentCreation.result;
   if (outcome === "background") clearConsumedDraft();
@@ -534,7 +537,8 @@ function buildComposerConfig(input: {
   return {
     initialServerId: serverId || null,
     initialValues: buildComposerInitialValues({ initialSetup }),
-    initialFeatureValues: initialSetup?.featureValues,
+    initialProviderOptions: initialSetup?.providerOptions,
+    context: "new-workspace" as const,
     isVisible: true,
     lockedWorkingDir: workingDir,
   };
@@ -567,7 +571,7 @@ function resolveWorkspaceDraftSubmissionConfig(input: {
       modeId: initialSetup.modeId,
       model: initialSetup.model,
       thinkingOptionId: initialSetup.thinkingOptionId,
-      featureValues: initialSetup.featureValues,
+      providerOptions: initialSetup.providerOptions,
       target: { kind: "draft", draftId, setup: initialSetup },
     };
   }
@@ -577,7 +581,7 @@ function resolveWorkspaceDraftSubmissionConfig(input: {
     modeId: composerState.effectiveModeId || null,
     model: composerState.effectiveModelId || null,
     thinkingOptionId: composerState.effectiveThinkingOptionId || null,
-    featureValues: composerState.featureValues,
+    providerOptions: composerState.providerOptions,
     target: { kind: "draft", draftId },
   };
 }
@@ -635,7 +639,7 @@ function submitWorkspaceDraft(input: SubmitDraftInput): SubmitOutcome {
     ...(submission.modeId ? { modeId: submission.modeId } : {}),
     ...(submission.model ? { model: submission.model } : {}),
     ...(submission.thinkingOptionId ? { thinkingOptionId: submission.thinkingOptionId } : {}),
-    ...(submission.featureValues ? { featureValues: submission.featureValues } : {}),
+    ...(submission.providerOptions ? { providerOptions: submission.providerOptions } : {}),
     allowEmptyText: true,
     agentCreation: input.agentCreation,
   });
@@ -906,6 +910,7 @@ export function NewWorkspaceScreen({
   const hostPickerAnchorRef = useRef<View | null>(null);
   const isDraftHandoffActive = useIsNewWorkspaceDraftHandoffActive({ draftId, selectedServerId });
   const isStillOnCreateScreen = useNewWorkspaceScreenPresence();
+  const isScreenFocused = useIsFocused();
 
   // Launch target: what the composer submits to (chat agent, or a terminal
   // profile). Mirrors useWorkspaceIsolation's pattern below: the derived
@@ -1000,22 +1005,31 @@ export function NewWorkspaceScreen({
     }),
   });
   const composerState = chatDraft.composerState;
-  const [pickerSelection, dispatchPickerSelection] = useReducer(
-    reducePickerSelection,
-    initialPickerSelectionState,
-  );
-  const selectedItem = pickerSelection.selectedItem;
+  const { setup, pluginProject, canCreateWorktree, isPending } = usePluginSetup({
+    serverId: selectedServerId,
+    project: selectedProject,
+    supportsMultiplicity: supportsWorkspaceMultiplicity,
+    pendingAction,
+    isDraftHandoffActive,
+    updatePreferences: updateFormPreferences,
+    setAttachments: chatDraft.setAttachments,
+  });
+  const dispatchPickerSelection = setup.dispatchPicker;
+  const selectedItem = useNewWorkspaceSetupState(setup).pickerSelection.selectedItem;
 
   const handleForgeChangeRequestDetected = useCallback(() => {
     dispatchPickerSelection({ type: "pr-detected" });
-  }, []);
+  }, [dispatchPickerSelection]);
 
-  const handleForgeChangeRequestAutoAttach = useCallback((item: ForgeSearchItem) => {
-    dispatchPickerSelection({
-      type: "pr-added",
-      item: { kind: "github-pr", item },
-    });
-  }, []);
+  const handleForgeChangeRequestAutoAttach = useCallback(
+    (item: ForgeSearchItem) => {
+      dispatchPickerSelection({
+        type: "pr-added",
+        item: { kind: "github-pr", item },
+      });
+    },
+    [dispatchPickerSelection],
+  );
 
   const withConnectedClient = useCallback(() => {
     const connectedClient = getHostRuntimeStore().getClient(selectedServerId);
@@ -1034,15 +1048,11 @@ export function NewWorkspaceScreen({
     cwd: selectedSourceDirectory ?? "",
   });
 
-  const worktreeSupport = selectedProject
-    ? getWorktreeSupportForHostProject({ project: selectedProject, serverId: selectedServerId })
-    : "unsupported";
-  const isPending = isNewWorkspacePending({ pendingAction, isDraftHandoffActive });
-  const { effectiveIsolation, setIsolation, canCreateWorktree, showRefPicker } =
-    useWorkspaceIsolation({
-      supportsMultiplicity: supportsWorkspaceMultiplicity,
-      worktreeSupport,
-    });
+  const { effectiveIsolation, setIsolation, showRefPicker } = useWorkspaceIsolation({
+    setup,
+    supportsMultiplicity: supportsWorkspaceMultiplicity,
+    canCreateWorktree,
+  });
 
   const branchSuggestionsQuery = useQuery({
     queryKey: [
@@ -1106,16 +1116,15 @@ export function NewWorkspaceScreen({
   }, [itemById, selectedOptionId]);
   const selectPickerItem = useCallback(
     (item: PickerItem) => {
-      const nextAttachments = syncPickerPrAttachment({
-        attachments: chatDraft.attachments,
-        item,
-      });
-
-      dispatchPickerSelection({ type: "picker-selected", item });
-      chatDraft.setAttachments(nextAttachments);
+      setup.chooseBase(item);
       setPickerOpen(false);
     },
-    [chatDraft],
+    [setup],
+  );
+
+  const pluginScreen = useMemo<NewWorkspaceItemsScreen>(
+    () => ({ project: pluginProject, isolation: effectiveIsolation, baseItem, locked: isPending }),
+    [baseItem, effectiveIsolation, isPending, pluginProject],
   );
 
   const handleSelectOption = useCallback(
@@ -1138,7 +1147,7 @@ export function NewWorkspaceScreen({
       chatDraft.setAttachments(nextAttachments);
       dispatchPickerSelection({ type: "target-changed" });
     },
-    [chatDraft],
+    [chatDraft, dispatchPickerSelection],
   );
 
   const handleSelectProjectOption = useCallback(
@@ -1166,9 +1175,7 @@ export function NewWorkspaceScreen({
     openAddProjectPicker(selectedServerId);
   }, [openAddProjectPicker, selectedServerId]);
 
-  const handleAddHost = useCallback(() => {
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, []);
+  const handleAddHost = useAddHost();
 
   const openPicker = useCallback(() => {
     setPickerOpen(true);
@@ -1258,6 +1265,8 @@ export function NewWorkspaceScreen({
         project: selectedProject,
         sourceDirectory: selectedSourceDirectory,
         checkoutRequest,
+        branchName: setup.getSnapshot().branch,
+        metadata: setup.getSnapshot().metadata,
         withInitialAgent: input.withInitialAgent,
         prompt: input.prompt,
         attachments: input.attachments,
@@ -1280,6 +1289,7 @@ export function NewWorkspaceScreen({
       selectedProject,
       selectedServerId,
       selectedSourceDirectory,
+      setup,
       supportsWorkspaceMultiplicity,
       t,
       withConnectedClient,
@@ -1460,6 +1470,9 @@ export function NewWorkspaceScreen({
   const formStack = useNewWorkspaceForm({
     isCompact,
     isPending,
+    pluginItems: (
+      <PluginNewWorkspaceItems serverId={selectedServerId} screen={pluginScreen} setup={setup} />
+    ),
     project: {
       anchorRef: projectPickerAnchorRef,
       open: openProjectPicker,
@@ -1533,7 +1546,7 @@ export function NewWorkspaceScreen({
       submitLabel={terminalSubmitLabel}
       agentId={draftKey}
       serverId={selectedServerId}
-      isPaneFocused={true}
+      isPaneFocused={isScreenFocused}
       onSubmitMessage={handleSubmitTerminalLaunch}
       allowEmptySubmit={true}
       submitButtonAccessibilityLabel={t("newWorkspace.launch.submit")}
@@ -1557,7 +1570,7 @@ export function NewWorkspaceScreen({
       editingSession={composerEditing.chat}
       agentId={draftKey}
       serverId={selectedServerId}
-      isPaneFocused={true}
+      isPaneFocused={isScreenFocused}
       onSubmitMessage={handleSubmitNewWorkspace}
       allowEmptySubmit={true}
       submitButtonAccessibilityLabel={t("newWorkspace.create")}
@@ -1600,6 +1613,54 @@ export function NewWorkspaceScreen({
   );
 }
 
+/**
+ * The setup model, built with what the screen has this render so a plugin item's mount effect can
+ * already run commands, and kept current on every commit.
+ */
+function usePluginSetup(input: {
+  serverId: string;
+  project: Parameters<typeof getHostProjectId>[0] | null;
+  supportsMultiplicity: boolean;
+  pendingAction: Parameters<typeof isNewWorkspacePending>[0]["pendingAction"];
+  isDraftHandoffActive: boolean;
+  updatePreferences: ReturnType<typeof useFormPreferences>["updatePreferences"];
+  setAttachments: ReturnType<typeof useAgentInputDraft>["setAttachments"];
+}) {
+  const {
+    serverId,
+    project,
+    supportsMultiplicity,
+    pendingAction,
+    isDraftHandoffActive,
+    updatePreferences,
+    setAttachments,
+  } = input;
+  const worktreeSupport = project
+    ? getWorktreeSupportForHostProject({ project, serverId })
+    : "unsupported";
+  const canCreateWorktree = supportsMultiplicity && worktreeSupport !== "unsupported";
+  const locked = isNewWorkspacePending({ pendingAction, isDraftHandoffActive });
+  const supportsMetadata = useHostFeature(serverId, "entityMetadata");
+  const projectId = project ? getHostProjectId(project, serverId) : null;
+  const projectName = project?.projectName ?? null;
+  const pluginProject = useMemo(
+    () => (projectId && projectName ? { id: projectId, name: projectName } : null),
+    [projectId, projectName],
+  );
+  const inputs = { serverId, locked, project: pluginProject, canCreateWorktree, supportsMetadata };
+  // Both are stable for the life of the screen: preferences write through the query client, and
+  // the draft is keyed per mount. A command and a pick run the same effects.
+  const [setup] = useState(() =>
+    createNewWorkspaceSetup(inputs, {
+      persistIsolation: (isolation) => void updatePreferences({ isolation }),
+      syncBaseAttachment: (item) =>
+        setAttachments((attachments) => syncPickerPrAttachment({ attachments, item })),
+    }),
+  );
+  useLayoutEffect(() => setup.syncInputs(inputs));
+  return { setup, pluginProject, canCreateWorktree, isPending: locked };
+}
+
 /** Terminal and chat launches edit in separate sessions; the screen follows the mounted one. */
 function useNewWorkspaceComposerEditing() {
   const terminal = useComposerEditingSession("terminal");
diff --git a/packages/app/src/screens/new-workspace/background-handoff.test.ts b/packages/app/src/screens/new-workspace/background-handoff.test.ts
index a84369fdf4..f8dbe177dd 100644
--- a/packages/app/src/screens/new-workspace/background-handoff.test.ts
+++ b/packages/app/src/screens/new-workspace/background-handoff.test.ts
@@ -69,7 +69,7 @@ describe("createWorkspaceAgentInBackground", () => {
           modeId: null,
           model: null,
           thinkingOptionId: null,
-          featureValues: {},
+          providerOptions: {},
         },
       });
     });
@@ -89,7 +89,7 @@ describe("createWorkspaceAgentInBackground", () => {
         modeId: null,
         model: null,
         thinkingOptionId: null,
-        featureValues: {},
+        providerOptions: {},
       },
     });
 
diff --git a/packages/app/src/screens/new-workspace/form/field-trigger.tsx b/packages/app/src/screens/new-workspace/form/field-trigger.tsx
index c82cadb14a..8c0be791dc 100644
--- a/packages/app/src/screens/new-workspace/form/field-trigger.tsx
+++ b/packages/app/src/screens/new-workspace/form/field-trigger.tsx
@@ -135,7 +135,7 @@ export const FieldTrigger = forwardRef<View, FieldTriggerProps>(function FieldTr
 });
 
 // Height of a badge. The desktop row sizes from it.
-export const FIELD_BADGE_HEIGHT = CONTROL_HEIGHTS.tight;
+export const FIELD_BADGE_HEIGHT = CONTROL_HEIGHTS.sm;
 // Height of a compact field: label line plus value line. The compact stack reserves rows from it.
 export const FIELD_HEIGHT = 56;
 
diff --git a/packages/app/src/screens/new-workspace/form/index.tsx b/packages/app/src/screens/new-workspace/form/index.tsx
index c1cf1e2482..3b2040d389 100644
--- a/packages/app/src/screens/new-workspace/form/index.tsx
+++ b/packages/app/src/screens/new-workspace/form/index.tsx
@@ -33,6 +33,8 @@ interface PickerControl {
 export interface NewWorkspaceFormProps {
   isCompact: boolean;
   isPending: boolean;
+  /** Plugin fields, drawn after the base ref. */
+  pluginItems: ReactNode;
   project: PickerControl & {
     options: ComboboxOption[];
     projectByOptionId: Map<string, HostProjectListItem>;
@@ -165,7 +167,7 @@ function useRefRenderOption(itemById: Map<string, PickerItem>, isPending: boolea
  */
 export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement {
   const { t } = useTranslation();
-  const { isCompact, isPending, project, host, isolation, base, launch } = props;
+  const { isCompact, isPending, pluginItems, project, host, isolation, base, launch } = props;
   const variant: FieldTriggerVariant = isCompact ? "field" : "badge";
   const projectPicker = useProjectPicker(project, isPending);
   const isolationPicker = useIsolationPicker(isolation, isPending);
@@ -337,6 +339,7 @@ export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement
         {hostField}
         {isolationField}
         {baseField}
+        {pluginItems}
         {launchField}
         {/* Isolation and Base come and go with the project; their rows stay reserved so the
             stack keeps one height and nothing above the composer jumps. */}
@@ -353,6 +356,7 @@ export function useNewWorkspaceForm(props: NewWorkspaceFormProps): ReactElement
       <View style={styles.desktopControl}>{hostField}</View>
       {isolationField ? <View style={styles.desktopControl}>{isolationField}</View> : null}
       {baseField ? <View style={styles.desktopControl}>{baseField}</View> : null}
+      {pluginItems}
       <View style={styles.launchSpacer} pointerEvents="none" />
       {launchField}
       {pickers}
diff --git a/packages/app/src/screens/new-workspace/import-session-button.tsx b/packages/app/src/screens/new-workspace/import-session-button.tsx
index 39d4efc1ce..331e274882 100644
--- a/packages/app/src/screens/new-workspace/import-session-button.tsx
+++ b/packages/app/src/screens/new-workspace/import-session-button.tsx
@@ -21,7 +21,6 @@ export function ImportSessionButton({
       <Button
         // Ghost for its muted text that turns foreground on hover; the pill adds the outline.
         variant="ghost"
-        size="sm"
         leftIcon={Import}
         onPress={onPress}
         style={compact ? null : styles.pill}
@@ -34,11 +33,12 @@ export function ImportSessionButton({
 }
 
 const styles = StyleSheet.create((theme) => ({
-  // The composer sits spacing[4] in from the dock and leaves spacing[4] below itself; the pill's
-  // border lines up with the composer's border.
+  // The composer sits spacing[4] in from the dock; the pill's border lines up with the
+  // composer's border, spacing[4] below it.
   wide: {
     alignItems: "flex-start",
     paddingHorizontal: theme.spacing[4],
+    paddingTop: theme.spacing[4],
   },
   pill: {
     borderRadius: theme.borderRadius.full,
diff --git a/packages/app/src/screens/new-workspace/retry-agent-request.test.ts b/packages/app/src/screens/new-workspace/retry-agent-request.test.ts
new file mode 100644
index 0000000000..248a044a3c
--- /dev/null
+++ b/packages/app/src/screens/new-workspace/retry-agent-request.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { retriedAgentRequest, type WorkspaceAgentRequest } from "./retry-agent-request";
+
+const initial: WorkspaceAgentRequest = {
+  config: { provider: "codex", cwd: "/repo", model: "gpt-6" },
+  metadata: { "issues.key": "PAS-1" },
+  initialPrompt: "first try",
+  clientMessageId: "draft_1:initial-message",
+};
+
+describe("retriedAgentRequest", () => {
+  it("creates with the metadata the draft resubmitted", () => {
+    const retried = retriedAgentRequest(
+      initial,
+      {
+        config: { provider: "codex", cwd: "/repo", model: "gpt-6" },
+        initialPrompt: "second try",
+        metadata: { "issues.key": "PAS-2" },
+      },
+      "/repo",
+    );
+    expect(retried.metadata).toEqual({ "issues.key": "PAS-2" });
+    expect(retried.initialPrompt).toBe("second try");
+    expect(retried.clientMessageId).toBe("draft_1:initial-message");
+  });
+
+  it("creates with no metadata once the draft cleared it", () => {
+    const retried = retriedAgentRequest(
+      initial,
+      { config: { provider: "codex", cwd: "/repo", model: "gpt-6" }, initialPrompt: "second try" },
+      "/repo",
+    );
+    expect("metadata" in retried).toBe(false);
+  });
+
+  it("keeps the first attempt's directory over the resubmitted config", () => {
+    const retried = retriedAgentRequest(
+      initial,
+      {
+        config: { provider: "codex", cwd: "/elsewhere", model: "gpt-6-mini" },
+        initialPrompt: "second try",
+      },
+      "/repo",
+    );
+    expect(retried.config).toEqual({ provider: "codex", cwd: "/repo", model: "gpt-6-mini" });
+  });
+});
diff --git a/packages/app/src/screens/new-workspace/retry-agent-request.ts b/packages/app/src/screens/new-workspace/retry-agent-request.ts
new file mode 100644
index 0000000000..4a7efa02cf
--- /dev/null
+++ b/packages/app/src/screens/new-workspace/retry-agent-request.ts
@@ -0,0 +1,28 @@
+import type {
+  CreateAgentRequestOptions,
+  CreateWorkspaceRequestOptions,
+} from "@getpaseo/client/internal/daemon-client";
+
+export type WorkspaceAgentRequest = NonNullable<CreateWorkspaceRequestOptions["agent"]>;
+
+/**
+ * The agent a retried creation asks for: everything the draft resubmitted (config, prompt,
+ * images, attachments and metadata, cleared included) on the first attempt's identity, so a
+ * retry creates what the composer shows now, not what it showed when creation first failed.
+ */
+export function retriedAgentRequest(
+  initial: WorkspaceAgentRequest,
+  request: CreateAgentRequestOptions,
+  cwd: string,
+): WorkspaceAgentRequest {
+  const { metadata: _replaced, ...identity } = initial;
+  return {
+    ...identity,
+    config: { ...request.config!, cwd },
+    initialPrompt: request.initialPrompt ?? "",
+    clientMessageId: initial.clientMessageId,
+    images: request.images,
+    attachments: request.attachments,
+    ...(request.metadata ? { metadata: request.metadata } : {}),
+  };
+}
diff --git a/packages/app/src/screens/new-workspace/setup-model.test.ts b/packages/app/src/screens/new-workspace/setup-model.test.ts
new file mode 100644
index 0000000000..2e395cd99f
--- /dev/null
+++ b/packages/app/src/screens/new-workspace/setup-model.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import type { PickerItem } from "../new-workspace-picker-item";
+import {
+  createNewWorkspaceSetup,
+  setupTargetOf,
+  type NewWorkspaceSetup,
+  type SetupEffects,
+  type SetupInputs,
+} from "./setup-model";
+
+const READY: SetupInputs = {
+  serverId: "host-a",
+  locked: false,
+  project: { id: "p1", name: "repo" },
+  canCreateWorktree: true,
+  supportsMetadata: true,
+};
+
+/** The commands an item mounted for `inputs`' project and host receives. */
+function commandsOf(setup: NewWorkspaceSetup, inputs: SetupInputs = READY) {
+  return setup.commandsFor(setupTargetOf(inputs));
+}
+
+function recordingEffects() {
+  const chosen: PickerItem[] = [];
+  const isolations: string[] = [];
+  const effects: SetupEffects = {
+    persistIsolation: (isolation) => isolations.push(isolation),
+    syncBaseAttachment: (item) => chosen.push(item),
+  };
+  return { effects, chosen, isolations };
+}
+
+describe("New workspace setup commands", () => {
+  it("accepts commands from the first moment, before the screen has committed", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+
+    await commandsOf(setup).setBranch("pas-101");
+
+    expect(setup.getSnapshot().branch).toBe("pas-101");
+  });
+
+  it("applies commands that run back to back without waiting for a render", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+
+    void commandsOf(setup).setBranch("pas-101");
+    void commandsOf(setup).setMetadata({ issue: "PAS-101", keep: true });
+    await commandsOf(setup).setMetadata({ keep: null });
+
+    expect(setup.getSnapshot().branch).toBe("pas-101");
+    expect(setup.getSnapshot().metadata).toEqual({ issue: "PAS-101" });
+  });
+
+  it("changes the model and runs the effects of a pick, for a base branch and an isolation choice", async () => {
+    const { effects, chosen, isolations } = recordingEffects();
+    const setup = createNewWorkspaceSetup(READY, effects);
+
+    await commandsOf(setup).setBaseRef({ type: "branch", name: " release " });
+    await commandsOf(setup).setIsolation("worktree");
+
+    expect(chosen).toMatchObject([{ kind: "branch", name: "release", refName: "release" }]);
+    expect(setup.getSnapshot().pickerSelection.selectedItem).toEqual(chosen[0]);
+    expect(isolations).toEqual(["worktree"]);
+    expect(setup.getSnapshot().manualIsolation).toBe("worktree");
+  });
+
+  it("shows a base ref's short name and keeps the exact ref for creation", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+
+    await commandsOf(setup).setBaseRef({ type: "branch", name: "refs/remotes/origin/release" });
+
+    expect(setup.getSnapshot().pickerSelection.selectedItem).toMatchObject({
+      name: "release",
+      refName: "refs/remotes/origin/release",
+    });
+  });
+
+  it("drops the branch and metadata chosen for another project, but not while the project resolves", async () => {
+    const resolving = { ...READY, project: null };
+    const setup = createNewWorkspaceSetup(resolving, recordingEffects().effects);
+    await commandsOf(setup, resolving).setBranch("pas-101");
+    setup.syncInputs(READY);
+    expect(setup.getSnapshot().branch).toBe("pas-101");
+
+    await commandsOf(setup).setMetadata({ issue: "PAS-101" });
+    setup.syncInputs({ ...READY, project: { id: "p2", name: "other" } });
+
+    expect(setup.getSnapshot().branch).toBeNull();
+    expect(setup.getSnapshot().metadata).toEqual({});
+  });
+
+  it("drops the branch and metadata when the host changes under the same project id", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+    await commandsOf(setup).setBranch("pas-101");
+    await commandsOf(setup).setMetadata({ issue: "PAS-101" });
+
+    setup.syncInputs({ ...READY, serverId: "host-b" });
+
+    expect(setup.getSnapshot().branch).toBeNull();
+    expect(setup.getSnapshot().metadata).toEqual({});
+  });
+
+  it("rejects a late command from the project or host the screen has left, and leaves the new choices alone", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+    const old = commandsOf(setup);
+    const otherProject = { ...READY, project: { id: "p2", name: "other" } };
+    const otherHost = { ...READY, serverId: "host-b" };
+
+    setup.syncInputs(otherProject);
+    await commandsOf(setup, otherProject).setBranch("chosen-for-p2");
+
+    const results = await Promise.allSettled([
+      old.setBranch("late"),
+      old.setMetadata({ issue: "late" }),
+      old.setIsolation("local"),
+      old.setBaseRef({ type: "branch", name: "late" }),
+    ]);
+    expect(results.map((result) => result.status)).toEqual(Array(4).fill("rejected"));
+    await expect(old.setBranch("late")).rejects.toThrow("moved to another project or host");
+    expect(setup.getSnapshot().branch).toBe("chosen-for-p2");
+    expect(setup.getSnapshot().metadata).toEqual({});
+    expect(setup.getSnapshot().manualIsolation).toBeNull();
+
+    setup.syncInputs(otherHost);
+    await expect(commandsOf(setup, otherProject).setBranch("late")).rejects.toThrow(
+      "moved to another project or host",
+    );
+  });
+
+  it("accepts commands again when the screen returns to the project they were made for", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+    const first = commandsOf(setup);
+
+    setup.syncInputs({ ...READY, project: { id: "p2", name: "other" } });
+    setup.syncInputs(READY);
+    await first.setBranch("back");
+
+    expect(setup.getSnapshot().branch).toBe("back");
+  });
+
+  it("rejects every command while the screen is locked, as the pickers do", async () => {
+    const setup = createNewWorkspaceSetup({ ...READY, locked: true }, recordingEffects().effects);
+
+    const results = await Promise.allSettled([
+      commandsOf(setup).setBranch("x"),
+      commandsOf(setup).setMetadata({ a: 1 }),
+      commandsOf(setup).setIsolation("local"),
+      commandsOf(setup).setBaseRef({ type: "branch", name: "main" }),
+    ]);
+
+    expect(results.map((result) => result.status)).toEqual(Array(4).fill("rejected"));
+    expect(setup.getSnapshot().branch).toBeNull();
+    expect(setup.getSnapshot().metadata).toEqual({});
+  });
+
+  it("reads the inputs when a command runs, so a project change after render is seen", async () => {
+    const setup = createNewWorkspaceSetup(READY, recordingEffects().effects);
+    const resolving = { ...READY, project: null };
+    setup.syncInputs(resolving);
+
+    await expect(
+      commandsOf(setup, resolving).setBaseRef({ type: "branch", name: "main" }),
+    ).rejects.toThrow("Choose a project first.");
+  });
+
+  it("rejects what the project or host cannot do", async () => {
+    const setup = createNewWorkspaceSetup(
+      { ...READY, canCreateWorktree: false, supportsMetadata: false },
+      recordingEffects().effects,
+    );
+
+    await expect(commandsOf(setup).setIsolation("worktree")).rejects.toThrow(
+      "cannot create worktrees",
+    );
+    await expect(commandsOf(setup).setMetadata({ a: 1 })).rejects.toThrow("Update the host");
+    await expect(commandsOf(setup).setBranch("  ")).rejects.toThrow("needs a name");
+    await commandsOf(setup).setBranch(null);
+    expect(setup.getSnapshot().branch).toBeNull();
+  });
+});
diff --git a/packages/app/src/screens/new-workspace/setup-model.ts b/packages/app/src/screens/new-workspace/setup-model.ts
new file mode 100644
index 0000000000..2a810d24c1
--- /dev/null
+++ b/packages/app/src/screens/new-workspace/setup-model.ts
@@ -0,0 +1,186 @@
+import { useSyncExternalStore } from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import { applyMetadataPatch } from "@/composer/draft/metadata";
+import { branchNameFromRef, type PickerItem } from "../new-workspace-picker-item";
+import {
+  initialPickerSelectionState,
+  reducePickerSelection,
+  type PickerSelectionEvent,
+  type PickerSelectionState,
+} from "../new-workspace-picker-state";
+
+type Isolation = "local" | "worktree";
+
+/** What the user has chosen on the New workspace screen, apart from project and host. */
+interface SetupState {
+  pickerSelection: PickerSelectionState;
+  manualIsolation: Isolation | null;
+  /** The name for a new worktree branch; null lets Paseo pick one. */
+  branch: string | null;
+  /** The created workspace's metadata. */
+  metadata: Readonly<Record<string, JsonValue>>;
+}
+
+/**
+ * What the screen derives from its hooks, given at construction and kept current on every
+ * commit, so a command reads it at the moment it runs rather than from the render that built it.
+ */
+export interface SetupInputs {
+  /** The host the screen creates on; a project id alone can repeat across hosts. */
+  serverId: string;
+  locked: boolean;
+  project: { id: string; name: string } | null;
+  canCreateWorktree: boolean;
+  supportsMetadata: boolean;
+}
+
+/** The project on the host a screen creates in; what an item is mounted for. */
+export interface SetupTarget {
+  serverId: string;
+  /** Null while the screen is still resolving its project. */
+  projectId: string | null;
+}
+
+export function setupTargetOf(input: Pick<SetupInputs, "serverId" | "project">): SetupTarget {
+  return { serverId: input.serverId, projectId: input.project?.id ?? null };
+}
+
+export interface SetupCommands {
+  setIsolation(isolation: Isolation): Promise<void>;
+  setBaseRef(ref: { type: "branch"; name: string }): Promise<void>;
+  setBranch(name: string | null): Promise<void>;
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+export interface NewWorkspaceSetup {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): SetupState;
+  /** Events other than a pick: a detected change request, a target change. */
+  dispatchPicker(event: PickerSelectionEvent): void;
+  /** The base picker's entry, and the one `setBaseRef` takes. */
+  chooseBase(item: PickerItem): void;
+  /** The isolation picker's entry, and the one `setIsolation` takes. */
+  chooseIsolation(isolation: Isolation): void;
+  syncInputs(inputs: SetupInputs): void;
+  /**
+   * Commands for the items mounted for `target`. Once the screen is on another project or host
+   * they reject, so a lookup that finishes after the switch cannot write into the new choices.
+   */
+  commandsFor(target: SetupTarget): SetupCommands;
+}
+
+/** What a pick does beyond changing the model, the same for the picker and for a command. */
+export interface SetupEffects {
+  /** Remembers the isolation as the default for the next New workspace screen. */
+  persistIsolation(isolation: Isolation): void;
+  /** Keeps the picker's change-request attachment in step with the chosen base. */
+  syncBaseAttachment(item: PickerItem): void;
+}
+
+const MOVED_MESSAGE =
+  "The New workspace screen moved to another project or host; this item belongs to the previous one.";
+const LOCKED_MESSAGE = "The New workspace screen is locked while the workspace is being created.";
+
+/**
+ * The New workspace screen's choices as one plain model. The pickers and the plugin commands
+ * write to it through the same entries, so a command sees what an earlier command or pick left,
+ * has the effects of a pick, and applies the same rules as the picker it stands in for. It is
+ * built with its inputs and effects, so a command does the same thing from a child's mount effect
+ * as from a button later.
+ */
+export function createNewWorkspaceSetup(
+  initial: SetupInputs,
+  effects: SetupEffects,
+): NewWorkspaceSetup {
+  let state: SetupState = {
+    pickerSelection: initialPickerSelectionState,
+    manualIsolation: null,
+    branch: null,
+    metadata: {},
+  };
+  let inputs = initial;
+  let screenTarget = initial.project ? `${initial.serverId}\n${initial.project.id}` : null;
+  const listeners = new Set<() => void>();
+  const update = (patch: Partial<SetupState>) => {
+    state = { ...state, ...patch };
+    for (const listener of listeners) listener();
+  };
+  const sameTarget = (target: SetupTarget) => {
+    const current = setupTargetOf(inputs);
+    return current.serverId === target.serverId && current.projectId === target.projectId;
+  };
+  const dispatchPicker = (event: PickerSelectionEvent) =>
+    update({ pickerSelection: reducePickerSelection(state.pickerSelection, event) });
+  const chooseBase = (item: PickerItem) => {
+    dispatchPicker({ type: "picker-selected", item });
+    effects.syncBaseAttachment(item);
+  };
+  const chooseIsolation = (isolation: Isolation) => {
+    update({ manualIsolation: isolation });
+    effects.persistIsolation(isolation);
+  };
+  const commandsFor = (target: SetupTarget): SetupCommands => {
+    const unlocked = (): SetupInputs => {
+      if (!sameTarget(target)) throw new Error(MOVED_MESSAGE);
+      if (inputs.locked) throw new Error(LOCKED_MESSAGE);
+      return inputs;
+    };
+    return {
+      async setIsolation(isolation) {
+        const current = unlocked();
+        if (isolation === "worktree" && !current.canCreateWorktree) {
+          throw new Error("This project cannot create worktrees.");
+        }
+        chooseIsolation(isolation);
+      },
+      async setBaseRef({ name }) {
+        const current = unlocked();
+        const refName = name.trim();
+        if (!current.project) throw new Error("Choose a project first.");
+        if (!refName) throw new Error("A base branch needs a name.");
+        chooseBase({
+          kind: "branch",
+          name: branchNameFromRef(refName),
+          refName,
+          accessibilityLabel: `${branchNameFromRef(refName)}, branch`,
+        });
+      },
+      async setBranch(name) {
+        unlocked();
+        const branch = name === null ? null : name.trim();
+        if (branch === "") throw new Error("A branch needs a name.");
+        update({ branch });
+      },
+      async setMetadata(patch) {
+        const current = unlocked();
+        if (!current.supportsMetadata) throw new Error("Update the host to use metadata.");
+        update({ metadata: applyMetadataPatch(state.metadata, patch) });
+      },
+    };
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getSnapshot: () => state,
+    dispatchPicker,
+    chooseBase,
+    chooseIsolation,
+    syncInputs: (next) => {
+      inputs = next;
+      // A branch and metadata are chosen for one project on one host. A project id can repeat
+      // across hosts (a remote repository keeps its key everywhere), so the host is part of the
+      // target. An absent project is a screen that is still resolving, not a switch.
+      if (!next.project) return;
+      const nextTarget = `${next.serverId}\n${next.project.id}`;
+      if (screenTarget && screenTarget !== nextTarget) update({ branch: null, metadata: {} });
+      screenTarget = nextTarget;
+    },
+    commandsFor,
+  };
+}
+
+export function useNewWorkspaceSetupState(setup: NewWorkspaceSetup): SetupState {
+  return useSyncExternalStore(setup.subscribe, setup.getSnapshot, setup.getSnapshot);
+}
diff --git a/packages/app/src/screens/project-settings-screen.tsx b/packages/app/src/screens/project-settings-screen.tsx
index a23784f5dc..ae6f31fef1 100644
--- a/packages/app/src/screens/project-settings-screen.tsx
+++ b/packages/app/src/screens/project-settings-screen.tsx
@@ -21,7 +21,6 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Alert } from "@/components/ui/alert";
-import { ExternalLink } from "@/components/ui/external-link";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { Switch } from "@/components/ui/switch";
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
@@ -160,7 +159,6 @@ function NoEditableTarget({
           testID="project-settings-back-button"
           onPress={onBackToProjects}
           variant="secondary"
-          size="md"
         >
           {t("settings.project.backToProjects")}
         </Button>
@@ -177,7 +175,6 @@ function BackToProjectsButton({ onPress }: { onPress: () => void }) {
       accessibilityLabel={t("settings.project.backToProjects")}
       onPress={onPress}
       variant="ghost"
-      size="sm"
       leftIcon={ArrowLeft}
       style={styles.backButton}
     >
@@ -420,7 +417,7 @@ function ReadFailureCallout({ kind, error, onReload }: ReadFailureCalloutProps)
   return (
     <View style={styles.errorBlock}>
       <Alert size="md" testID={testID} variant="error" title={title} description={description}>
-        <Button testID={`${testID}-action-0`} onPress={onReload} variant="outline" size="sm">
+        <Button testID={`${testID}-action-0`} onPress={onReload} variant="outline">
           {t("settings.project.actions.reload")}
         </Button>
       </Alert>
@@ -662,25 +659,21 @@ function ProjectConfigForm({
   );
 
   const setupDocsLink = useMemo(
-    () => (
-      <ExternalLink
-        href={WORKTREE_DOCS_URL}
-        label={t("settings.project.worktree.docs")}
-        tooltip={t("settings.project.worktree.docsTooltip")}
-        testID="worktree-setup-docs-link"
-      />
-    ),
+    () => ({
+      href: WORKTREE_DOCS_URL,
+      label: t("settings.project.worktree.docs"),
+      tooltip: t("settings.project.worktree.docsTooltip"),
+      testID: "worktree-setup-docs-link",
+    }),
     [t],
   );
   const teardownDocsLink = useMemo(
-    () => (
-      <ExternalLink
-        href={WORKTREE_DOCS_URL}
-        label={t("settings.project.worktree.docs")}
-        tooltip={t("settings.project.worktree.docsTooltip")}
-        testID="worktree-teardown-docs-link"
-      />
-    ),
+    () => ({
+      href: WORKTREE_DOCS_URL,
+      label: t("settings.project.worktree.docs"),
+      tooltip: t("settings.project.worktree.docsTooltip"),
+      testID: "worktree-teardown-docs-link",
+    }),
     [t],
   );
 
@@ -698,7 +691,7 @@ function ProjectConfigForm({
         <SettingsSection
           title={t("settings.project.worktree.setup")}
           testID="worktree-setup-section"
-          trailing={setupDocsLink}
+          link={setupDocsLink}
         >
           {hasUncommittedWorktreeSetupChanges ? (
             <Alert
@@ -720,7 +713,7 @@ function ProjectConfigForm({
         <SettingsSection
           title={t("settings.project.worktree.teardown")}
           testID="worktree-teardown-section"
-          trailing={teardownDocsLink}
+          link={teardownDocsLink}
           flush
         >
           <SettingsTextAreaCard
@@ -783,12 +776,7 @@ function ProjectConfigForm({
             title={t("settings.project.writeFailures.staleTitle")}
             description={t("settings.project.writeFailures.staleDescription")}
           >
-            <Button
-              testID="stale-callout-action-0"
-              onPress={handleReload}
-              variant="outline"
-              size="sm"
-            >
+            <Button testID="stale-callout-action-0" onPress={handleReload} variant="outline">
               {t("settings.project.actions.reload")}
             </Button>
           </Alert>
@@ -804,20 +792,10 @@ function ProjectConfigForm({
             title={t("settings.project.writeFailures.failedTitle")}
             description={t("settings.project.writeFailures.failedDescription")}
           >
-            <Button
-              testID="write-failed-callout-action-0"
-              onPress={handleSave}
-              variant="outline"
-              size="sm"
-            >
+            <Button testID="write-failed-callout-action-0" onPress={handleSave} variant="outline">
               {t("settings.project.actions.tryAgain")}
             </Button>
-            <Button
-              testID="write-failed-callout-action-1"
-              onPress={handleReload}
-              variant="outline"
-              size="sm"
-            >
+            <Button testID="write-failed-callout-action-1" onPress={handleReload} variant="outline">
               {t("settings.project.actions.reload")}
             </Button>
           </Alert>
@@ -829,7 +807,6 @@ function ProjectConfigForm({
           testID="save-button"
           accessibilityLabel={t("settings.project.actions.save")}
           variant="default"
-          size="md"
           disabled={saveDisabled}
           loading={saveMutation.isPending}
           onPress={handleSave}
@@ -1106,10 +1083,10 @@ function ScriptEditModal({ script, onChange, onCancel, onSave }: ScriptEditModal
         </View>
       </View>
       <View style={styles.modalFooter}>
-        <Button onPress={onCancel} variant="ghost" size="md" testID="script-edit-cancel">
+        <Button onPress={onCancel} variant="ghost" testID="script-edit-cancel">
           {t("settings.project.actions.cancel")}
         </Button>
-        <Button onPress={handleSavePress} variant="default" size="md" testID="script-edit-save">
+        <Button onPress={handleSavePress} variant="default" testID="script-edit-save">
           {t("settings.project.actions.save")}
         </Button>
       </View>
diff --git a/packages/app/src/screens/schedules-screen.tsx b/packages/app/src/screens/schedules-screen.tsx
index 3c76db14f2..ff18c4788d 100644
--- a/packages/app/src/screens/schedules-screen.tsx
+++ b/packages/app/src/screens/schedules-screen.tsx
@@ -277,20 +277,13 @@ function SchedulesScreenBody({
             />
           ) : null}
           <SegmentedControl
-            size="sm"
             value={statusFilter}
             onValueChange={onStatusFilterChange}
             options={STATUS_FILTER_OPTIONS}
             testID="schedules-status-filter"
           />
         </View>
-        <Button
-          variant="outline"
-          leftIcon={Plus}
-          onPress={onCreate}
-          size="sm"
-          testID="schedules-new"
-        >
+        <Button variant="outline" leftIcon={Plus} onPress={onCreate} testID="schedules-new">
           New schedule
         </Button>
       </View>
diff --git a/packages/app/src/screens/settings-screen.tsx b/packages/app/src/screens/settings-screen.tsx
index 78425bf20d..9c8b230e4c 100644
--- a/packages/app/src/screens/settings-screen.tsx
+++ b/packages/app/src/screens/settings-screen.tsx
@@ -1,4 +1,6 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useHardwareKeyboardPresent } from "@/keyboard";
+import { useAddHost } from "@/hosts/add-host";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { ComponentType, ReactNode } from "react";
 import {
   Alert,
@@ -74,10 +76,6 @@ import { WindowChromeRegion, WindowChromeSafeArea } from "@/utils/desktop-window
 import { confirmDialog } from "@/utils/confirm-dialog";
 import { BackHeader } from "@/components/headers/back-header";
 import { PageLayout } from "@/components/page-layout";
-import { AddHostMethodModal } from "@/components/add-host-method-modal";
-import { AddHostModal } from "@/components/add-host-modal";
-import { AddRemoteSshHostModal } from "@/components/add-remote-ssh-host-modal";
-import { PairLinkModal } from "@/components/pair-link-modal";
 import { KeyboardShortcutsSection } from "@/screens/settings/keyboard-shortcuts-section";
 import { EditorSection } from "@/screens/settings/editor-section";
 import { FilesSection } from "@/screens/settings/files-section";
@@ -116,7 +114,7 @@ import {
   HostTerminalsPage,
 } from "@/screens/settings/host-page";
 import { PluginSettingsContent } from "@/plugins/settings";
-import { useInstalledPlugins } from "@/plugins/registry";
+import { usePluginDisplayName } from "@/plugins/plugin-list";
 import { HostPluginsPage } from "@/screens/settings/plugins-page";
 import { MetadataGenerationPage } from "@/screens/settings/metadata-generation-page";
 import { HostVoicePage } from "@/screens/settings/voice/voice-page";
@@ -127,7 +125,7 @@ import {
   SETTINGS_DESKTOP_SIDEBAR_WIDTH,
   useIsCompactFormFactor,
 } from "@/constants/layout";
-import { densityIconBox, densityIconSize } from "@/styles/density";
+import { density, densityIconBox, densityIconSize } from "@/styles/density";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import {
   type EnableBuiltInDaemonOption,
@@ -145,7 +143,8 @@ import {
   useSettingsSidebarScroll,
 } from "@/navigation/settings-presentation";
 import { returnFromSettings, type SettingsView } from "@/navigation/settings-navigation";
-import { isWeb } from "@/constants/platform";
+import { isNative, isWeb } from "@/constants/platform";
+import { useOpenOnboarding } from "@/onboarding";
 
 // ---------------------------------------------------------------------------
 // View model
@@ -157,6 +156,7 @@ interface SidebarSectionItem {
   icon: ComponentType<{ size: number; color: string; strokeWidth?: number }>;
   desktopOnly?: boolean;
   webOnly?: boolean;
+  hardwareKeyboardOnly?: boolean;
   /** The page body, for pages that need nothing from the settings screen. */
   Content?: ComponentType;
 }
@@ -201,7 +201,7 @@ const SIDEBAR_SECTION_ITEMS: SidebarSectionItem[] = [
     id: "shortcuts",
     labelKey: "settings.sections.shortcuts",
     icon: Keyboard,
-    desktopOnly: true,
+    hardwareKeyboardOnly: true,
     Content: KeyboardShortcutsSection,
   },
   {
@@ -229,7 +229,12 @@ const SIDEBAR_SECTION_ITEMS: SidebarSectionItem[] = [
   { id: "about", labelKey: "settings.sections.about", icon: Info },
 ];
 
-function isSectionAvailable(item: SidebarSectionItem, isDesktopApp: boolean): boolean {
+function isSectionAvailable(
+  item: SidebarSectionItem,
+  isDesktopApp: boolean,
+  hardwareKeyboardPresent: boolean,
+): boolean {
+  if (item.hardwareKeyboardOnly && !hardwareKeyboardPresent) return false;
   return (!item.desktopOnly || isDesktopApp) && (!item.webOnly || isWeb);
 }
 
@@ -389,11 +394,28 @@ function GeneralSection({ settings, handleLanguageChange }: GeneralSectionProps)
             </DropdownMenuContent>
           </DropdownMenu>
         </View>
+        {isNative ? null : <ShowSetupAgainRow />}
       </View>
     </SettingsSection>
   );
 }
 
+function ShowSetupAgainRow() {
+  const { t } = useTranslation();
+  const openOnboarding = useOpenOnboarding();
+  return (
+    <View style={[settingsStyles.row, settingsStyles.rowBorder]}>
+      <View style={settingsStyles.rowContent}>
+        <Text style={settingsStyles.rowTitle}>{t("settings.general.setup.label")}</Text>
+        <Text style={settingsStyles.rowHint}>{t("settings.general.setup.description")}</Text>
+      </View>
+      <Button variant="secondary" onPress={openOnboarding ?? undefined} disabled={!openOnboarding}>
+        {t("settings.general.setup.action")}
+      </Button>
+    </View>
+  );
+}
+
 interface DiagnosticsSectionProps {
   voiceAudioEngine: ReturnType<typeof useVoiceAudioEngineOptional>;
   isPlaybackTestRunning: boolean;
@@ -420,7 +442,7 @@ function DiagnosticsSection({
             <Text style={settingsStyles.rowTitle}>{t("settings.diagnostics.app.rowTitle")}</Text>
             <Text style={settingsStyles.rowHint}>{t("settings.diagnostics.app.rowHint")}</Text>
           </View>
-          <Button variant="secondary" size="sm" onPress={openAppDiagnostic}>
+          <Button variant="secondary" onPress={openAppDiagnostic}>
             {t("settings.diagnostics.app.run")}
           </Button>
         </View>
@@ -433,7 +455,6 @@ function DiagnosticsSection({
           </View>
           <Button
             variant="secondary"
-            size="sm"
             onPress={handlePlayPress}
             disabled={!voiceAudioEngine || isPlaybackTestRunning}
           >
@@ -690,7 +711,6 @@ function DesktopAppUpdateRow() {
           </Text>
         </View>
         <SegmentedControl
-          size="sm"
           value={settings.releaseChannel}
           onValueChange={handleReleaseChannelChange}
           options={releaseChannelOptions}
@@ -712,7 +732,6 @@ function DesktopAppUpdateRow() {
         <View style={styles.aboutUpdateActions}>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleCheckForUpdates}
             disabled={isChecking || isInstalling}
           >
@@ -720,7 +739,6 @@ function DesktopAppUpdateRow() {
           </Button>
           <Button
             variant="default"
-            size="sm"
             onPress={handleInstallUpdate}
             disabled={isChecking || isInstalling || !isUpdateReady}
           >
@@ -955,7 +973,10 @@ function SettingsSidebar({
   const hasHosts = sortedHosts.length > 0;
   const enableBuiltInDaemonOption = useEnableBuiltInDaemonOption();
   const isDesktopApp = isElectronRuntime();
-  const items = SIDEBAR_SECTION_ITEMS.filter((item) => isSectionAvailable(item, isDesktopApp));
+  const hardwareKeyboardPresent = useHardwareKeyboardPresent();
+  const items = SIDEBAR_SECTION_ITEMS.filter((item) =>
+    isSectionAvailable(item, isDesktopApp, hardwareKeyboardPresent),
+  );
   const insets = useSafeAreaInsets();
   const isDesktop = layout === "desktop";
   const sidebarScroll = useSettingsSidebarScroll(isDesktop);
@@ -1089,22 +1110,17 @@ function SettingsSidebar({
 
 export interface SettingsScreenProps {
   view: SettingsView;
-  openAddHostIntent?: string | null;
 }
 
-export default function SettingsScreen({ view, openAddHostIntent = null }: SettingsScreenProps) {
+export default function SettingsScreen({ view }: SettingsScreenProps) {
   const router = useRouter();
   const { t } = useTranslation();
   const voiceAudioEngine = useVoiceAudioEngineOptional();
   const { settings, isLoading: settingsLoading, updateSettings } = useAppSettings();
-  const [isAddHostMethodVisible, setIsAddHostMethodVisible] = useState(false);
-  const [isDirectHostVisible, setIsDirectHostVisible] = useState(false);
-  const [isRemoteSshVisible, setIsRemoteSshVisible] = useState(false);
-  const [isPasteLinkVisible, setIsPasteLinkVisible] = useState(false);
   const [isPlaybackTestRunning, setIsPlaybackTestRunning] = useState(false);
   const [playbackTestResult, setPlaybackTestResult] = useState<string | null>(null);
-  const lastOpenedAddHostIntentRef = useRef<string | null>(null);
   const isDesktopApp = isElectronRuntime();
+  const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   const appVersion = resolveAppVersion();
   const appVersionText = formatVersionWithPrefix(appVersion);
   const isCompactLayout = useIsCompactFormFactor();
@@ -1164,50 +1180,10 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     }
   }, [isPlaybackTestRunning, t, voiceAudioEngine]);
 
-  const closeAddConnectionFlow = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsDirectHostVisible(false);
-    setIsRemoteSshVisible(false);
-    setIsPasteLinkVisible(false);
-  }, []);
-
-  const goBackToAddConnectionMethods = useCallback(() => {
-    setIsDirectHostVisible(false);
-    setIsRemoteSshVisible(false);
-    setIsPasteLinkVisible(false);
-    setIsAddHostMethodVisible(true);
-  }, []);
-
-  const handleAddHost = useCallback(() => {
-    setIsAddHostMethodVisible(true);
-  }, []);
-
-  useEffect(() => {
-    if (!openAddHostIntent || lastOpenedAddHostIntentRef.current === openAddHostIntent) {
-      return;
-    }
-    lastOpenedAddHostIntentRef.current = openAddHostIntent;
-    handleAddHost();
-  }, [handleAddHost, openAddHostIntent]);
-
-  const handleSelectDirectConnection = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsDirectHostVisible(true);
-  }, []);
-
-  const handleSelectRemoteSsh = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsRemoteSshVisible(true);
-  }, []);
-
-  const handleSelectPasteLink = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsPasteLinkVisible(true);
-  }, []);
-
   const handleHostAdded = useCallback(
-    ({ serverId }: { serverId: string }) => {
-      const target = buildSettingsHostSectionRoute(serverId, "connections");
+    (serverId: string) => {
+      selectSettingsHost(serverId);
+      const target = buildSettingsHostSectionRoute(serverId, "host");
       if (isCompactLayout) {
         router.push(target);
       } else {
@@ -1217,6 +1193,8 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     [isCompactLayout, router],
   );
 
+  const handleAddHost = useAddHost({ onAdded: handleHostAdded });
+
   const handleSelectSection = useCallback(
     (section: SettingsSectionSlug) => {
       const target = buildSettingsSectionRoute(section);
@@ -1272,14 +1250,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     [activeHostServerId, handleAddHost, isCompactLayout, router],
   );
 
-  const handleScanQr = useCallback(() => {
-    closeAddConnectionFlow();
-    router.push({
-      pathname: "/pair-scan",
-      params: { source: "settings" },
-    });
-  }, [closeAddConnectionFlow, router]);
-
   const handleHostRemoved = useCallback(() => {
     const fallback = buildSettingsSectionRoute("general");
     if (isCompactLayout) {
@@ -1297,15 +1267,10 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     returnFromSettings({ kind: "root" });
   }, []);
 
-  const installedPlugins = useInstalledPlugins();
+  // The header names the plugin; its tabs name the open settings screen.
+  const pluginDisplayName = usePluginDisplayName(view.kind === "plugin" ? view : null);
   const detailTitle = ((): string | undefined => {
-    if (view.kind === "plugin") {
-      const plugin = installedPlugins.find(
-        (candidate) => candidate.serverId === view.serverId && candidate.id === view.pluginId,
-      );
-      const screen = plugin?.settingsScreens.find((candidate) => candidate.id === view.screenId);
-      return `${view.pluginId} · ${plugin && screen ? plugin.i18n.resolve(screen.title, plugin.locale) : t("settings.title")}`;
-    }
+    if (view.kind === "plugin") return pluginDisplayName;
     if (view.kind === "host") {
       const item = HOST_SECTION_ITEMS.find((s) => s.id === view.section);
       return item ? t(item.labelKey) : undefined;
@@ -1346,7 +1311,7 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     }
     if (view.kind === "section") {
       const item = SIDEBAR_SECTION_ITEMS.find((candidate) => candidate.id === view.section);
-      if (!item || !isSectionAvailable(item, isDesktopApp)) return null;
+      if (!item || !isSectionAvailable(item, isDesktopApp, hardwareKeyboardPresent)) return null;
       switch (view.section) {
         case "general":
           return (
@@ -1388,37 +1353,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     );
   }
 
-  const addHostModals = (
-    <>
-      <AddHostMethodModal
-        visible={isAddHostMethodVisible}
-        onClose={closeAddConnectionFlow}
-        onDirectConnection={handleSelectDirectConnection}
-        onRemoteSsh={handleSelectRemoteSsh}
-        onPasteLink={handleSelectPasteLink}
-        onScanQr={handleScanQr}
-      />
-      <AddHostModal
-        visible={isDirectHostVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-      <AddRemoteSshHostModal
-        visible={isRemoteSshVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-      <PairLinkModal
-        visible={isPasteLinkVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-    </>
-  );
-
   // Mobile root: full-screen sidebar-as-list.
   if (isCompactLayout && view.kind === "root") {
     return (
@@ -1436,7 +1370,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
             layout="mobile"
           />
         </ScrollView>
-        {addHostModals}
       </View>
     );
   }
@@ -1447,7 +1380,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
         <PageLayout title={detailTitle} onBack={handleBackFromDetail}>
           {content}
         </PageLayout>
-        {addHostModals}
       </View>
     );
   }
@@ -1482,7 +1414,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
           </View>
         </WindowChromeRegion>
       </View>
-      {addHostModals}
     </View>
   );
 }
@@ -1592,7 +1523,7 @@ const sidebarStyles = StyleSheet.create((theme) => ({
     flexDirection: "row",
     alignItems: "center",
     gap: { xs: theme.spacing[3], md: theme.spacing[2] },
-    minHeight: { xs: 52, md: 28 },
+    minHeight: { xs: 52, md: density.tightRowHeight.md },
     paddingVertical: theme.spacing[1],
     paddingHorizontal: { xs: theme.spacing[4], md: theme.spacing[2] },
     borderRadius: { xs: 0, md: theme.borderRadius.lg },
@@ -1618,7 +1549,7 @@ const sidebarStyles = StyleSheet.create((theme) => ({
     flexDirection: "row",
     alignItems: "center",
     gap: { xs: theme.spacing[3], md: theme.spacing[2] },
-    minHeight: { xs: 52, md: 28 },
+    minHeight: { xs: 52, md: density.tightRowHeight.md },
     paddingVertical: theme.spacing[1],
     paddingHorizontal: { xs: theme.spacing[4], md: theme.spacing[2] },
     borderRadius: { xs: 0, md: theme.borderRadius.lg },
diff --git a/packages/app/src/screens/settings/appearance/appearance-section.tsx b/packages/app/src/screens/settings/appearance/appearance-section.tsx
index 2dfea09fd0..f42475dc48 100644
--- a/packages/app/src/screens/settings/appearance/appearance-section.tsx
+++ b/packages/app/src/screens/settings/appearance/appearance-section.tsx
@@ -1,23 +1,17 @@
-import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
-import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { Monitor, Moon, Sun } from "lucide-react-native";
+import { StyleSheet } from "react-native-unistyles";
 import {
   SYNTAX_THEME_OPTIONS,
   type SyntaxThemeId,
   type SyntaxThemeOption,
 } from "@getpaseo/highlight";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-} from "@/components/ui/dropdown-menu";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem } from "@/components/ui/dropdown-menu";
 import { DropdownTrigger } from "@/components/ui/dropdown-trigger";
 import { SettingsSection } from "@/components/settings/headings/settings-section";
-import { useContributedThemes } from "@/appearance/provider";
+import { ThemePicker } from "@/appearance/theme-picker";
 import { Button } from "@/components/ui/button";
 import {
   EditingTextInput as TextInput,
@@ -36,40 +30,12 @@ import {
   sanitizeFontFamily,
   useAppSettings,
   type AppSettings,
-  DEFAULT_THEME_PREFERENCE,
 } from "@/hooks/use-settings";
-import {
-  DEFAULT_MONO_FONT_STACK,
-  DEFAULT_UI_FONT_STACK,
-  ICON_SIZE,
-  PLUGIN_THEME_PREFERENCE,
-  THEME_OPTIONS,
-  THEME_SWATCHES,
-  type Theme,
-} from "@/styles/theme";
+import { DEFAULT_MONO_FONT_STACK, DEFAULT_UI_FONT_STACK } from "@/styles/theme";
 import { isNative } from "@/constants/platform";
-import type { PluginThemeOption } from "@/plugins/themes";
 import { settingsStyles } from "@/styles/settings";
 import { AppearancePreview } from "./appearance-preview";
 
-// ---------------------------------------------------------------------------
-// Theme-reactive leaf icons (withUnistyles + uniProps color mapping — no
-// useUnistyles). Icon sizes read the static ICON_SIZE token; the appearance
-// feature does not scale icons.
-// ---------------------------------------------------------------------------
-
-const ThemedSun = withUnistyles(Sun);
-const ThemedMoon = withUnistyles(Moon);
-const ThemedMonitor = withUnistyles(Monitor);
-
-const mutedColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
-
-type BuiltInThemePreference = Exclude<AppSettings["theme"], typeof PLUGIN_THEME_PREFERENCE>;
-
-function getThemeLabel(t: TFunction, value: BuiltInThemePreference): string {
-  return t(`settings.appearance.theme.options.${value}`);
-}
-
 // Platform default stacks can be the bare native tokens ("normal"/"monospace");
 // those read as a bug, so show a human label in the placeholder instead.
 const BARE_DEFAULT_STACKS: ReadonlySet<string> = new Set(["normal", "monospace"]);
@@ -86,148 +52,6 @@ function sizeDraftToOverride(value: string): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
-// ---------------------------------------------------------------------------
-// Theme picker
-// ---------------------------------------------------------------------------
-
-interface ThemeLeadingProps {
-  themeValue: BuiltInThemePreference;
-}
-
-function ThemeLeading({ themeValue }: ThemeLeadingProps) {
-  switch (themeValue) {
-    case "light":
-      return <ThemedSun size={ICON_SIZE.md} uniProps={mutedColorMapping} />;
-    case "dark":
-      return <ThemedMoon size={ICON_SIZE.md} uniProps={mutedColorMapping} />;
-    case "auto":
-      return <ThemedMonitor size={ICON_SIZE.md} uniProps={mutedColorMapping} />;
-    default:
-      return <ThemeSwatch color={THEME_SWATCHES[themeValue]} />;
-  }
-}
-
-interface ThemeSwatchProps {
-  color: string;
-}
-
-function ThemeSwatch({ color }: ThemeSwatchProps) {
-  const swatchStyle = useMemo(() => [styles.swatch, { backgroundColor: color }], [color]);
-  return <View style={swatchStyle} />;
-}
-
-interface ThemeMenuItemProps {
-  themeValue: BuiltInThemePreference;
-  selected: boolean;
-  onChange: (theme: BuiltInThemePreference) => void;
-}
-
-function ThemeMenuItem({ themeValue, selected, onChange }: ThemeMenuItemProps) {
-  const { t } = useTranslation();
-  const handleSelect = useCallback(() => {
-    onChange(themeValue);
-  }, [onChange, themeValue]);
-  const leading = useMemo(() => <ThemeLeading themeValue={themeValue} />, [themeValue]);
-  return (
-    <DropdownMenuItem selected={selected} onSelect={handleSelect} leading={leading}>
-      {getThemeLabel(t, themeValue)}
-    </DropdownMenuItem>
-  );
-}
-
-interface PluginThemeMenuItemProps {
-  option: PluginThemeOption;
-  selected: boolean;
-  onSelect: (option: PluginThemeOption) => void;
-}
-
-function PluginThemeMenuItem({ option, selected, onSelect }: PluginThemeMenuItemProps) {
-  const handleSelect = useCallback(() => {
-    onSelect(option);
-  }, [onSelect, option]);
-  const leading = useMemo(() => <ThemeSwatch color={option.swatch} />, [option.swatch]);
-  return (
-    <DropdownMenuItem selected={selected} onSelect={handleSelect} leading={leading}>
-      {option.name}
-    </DropdownMenuItem>
-  );
-}
-
-interface ThemeRowProps {
-  value: AppSettings["theme"];
-  pluginThemes: PluginThemeOption[];
-  selectedPluginTheme: PluginThemeOption | null;
-  onChange: (theme: BuiltInThemePreference) => void;
-  onSelectPluginTheme: (option: PluginThemeOption) => void;
-}
-
-function ThemeRow({
-  value,
-  pluginThemes,
-  selectedPluginTheme,
-  onChange,
-  onSelectPluginTheme,
-}: ThemeRowProps) {
-  const { t } = useTranslation();
-  // A selected contribution that is no longer installed shows the fallback the app renders.
-  const builtInValue = value === PLUGIN_THEME_PREFERENCE ? DEFAULT_THEME_PREFERENCE : value;
-  const selectedLabel = selectedPluginTheme
-    ? selectedPluginTheme.name
-    : getThemeLabel(t, builtInValue);
-  const leading = useMemo(
-    () =>
-      selectedPluginTheme ? (
-        <ThemeSwatch color={selectedPluginTheme.swatch} />
-      ) : (
-        <ThemeLeading themeValue={builtInValue} />
-      ),
-    [builtInValue, selectedPluginTheme],
-  );
-  return (
-    <View style={settingsStyles.row}>
-      <View style={settingsStyles.rowContent}>
-        <Text style={settingsStyles.rowTitle}>{t("settings.appearance.theme.title")}</Text>
-      </View>
-      <DropdownMenu>
-        <DropdownTrigger
-          accessibilityLabel={t("settings.appearance.theme.accessibilityLabel", {
-            value: selectedLabel,
-          })}
-          leading={leading}
-        >
-          {selectedLabel}
-        </DropdownTrigger>
-        <DropdownMenuContent side="bottom" align="end" width={200} scrollable>
-          {THEME_OPTIONS.map((option, index) => {
-            const previousOption = THEME_OPTIONS[index - 1];
-            return (
-              <Fragment key={option.name}>
-                {previousOption && previousOption.group !== option.group ? (
-                  <DropdownMenuSeparator />
-                ) : null}
-                <ThemeMenuItem
-                  themeValue={option.name}
-                  selected={selectedPluginTheme === null && builtInValue === option.name}
-                  onChange={onChange}
-                />
-              </Fragment>
-            );
-          })}
-          {pluginThemes.length > 0 ? <DropdownMenuSeparator /> : null}
-          {pluginThemes.map((option) => (
-            <PluginThemeMenuItem
-              key={option.id}
-              option={option}
-              selected={selectedPluginTheme?.id === option.id}
-              onSelect={onSelectPluginTheme}
-            />
-          ))}
-        </DropdownMenuContent>
-      </DropdownMenu>
-    </View>
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Fonts: family text fields + numeric size fields (commit on blur/submit)
 // ---------------------------------------------------------------------------
@@ -380,7 +204,6 @@ function ContentWidthRow({ value, onChange }: ContentWidthRowProps) {
         {value === null ? null : (
           <Button
             variant="ghost"
-            size="sm"
             onPress={reset}
             accessibilityLabel={t("settings.appearance.layout.resetAccessibility")}
           >
@@ -478,11 +301,6 @@ function SyntaxRow({ value, onChange }: SyntaxRowProps) {
 export function AppearanceSection() {
   const { t } = useTranslation();
   const { settings, updateSettings } = useAppSettings();
-  const {
-    options: pluginThemes,
-    selected: selectedPluginTheme,
-    select: selectPluginTheme,
-  } = useContributedThemes();
   const showInterfaceFontFamilyRow = !isNative;
   const uiFontPlaceholder = resolveDefaultStackPlaceholder(t, DEFAULT_UI_FONT_STACK);
   const monoFontPlaceholder = resolveDefaultStackPlaceholder(t, DEFAULT_MONO_FONT_STACK);
@@ -504,20 +322,6 @@ export function AppearanceSection() {
     setCodeSizeDraft(String(settings.codeFontSize));
   }, [settings.codeFontSize]);
 
-  const handleThemeChange = useCallback(
-    (theme: BuiltInThemePreference) => {
-      void updateSettings({ theme });
-    },
-    [updateSettings],
-  );
-
-  const handlePluginThemeChange = useCallback(
-    (option: PluginThemeOption) => {
-      selectPluginTheme(option);
-    },
-    [selectPluginTheme],
-  );
-
   const handleContentMaxWidthChange = useCallback(
     (contentMaxWidth: AppSettings["contentMaxWidth"]) => {
       void updateSettings({ contentMaxWidth });
@@ -627,14 +431,8 @@ export function AppearanceSection() {
   return (
     <View>
       <SettingsSection title={t("settings.appearance.theme.title")}>
-        <View style={settingsStyles.card}>
-          <ThemeRow
-            value={settings.theme}
-            pluginThemes={pluginThemes}
-            selectedPluginTheme={selectedPluginTheme}
-            onChange={handleThemeChange}
-            onSelectPluginTheme={handlePluginThemeChange}
-          />
+        <View style={[settingsStyles.card, styles.themeCard]}>
+          <ThemePicker />
         </View>
       </SettingsSection>
       <SettingsSection title={t("settings.appearance.fonts.title")}>
@@ -723,12 +521,8 @@ const styles = StyleSheet.create((theme) => ({
     borderTopWidth: theme.borderWidth[1],
     borderTopColor: theme.colors.border,
   },
-  swatch: {
-    width: ICON_SIZE.md,
-    height: ICON_SIZE.md,
-    borderRadius: ICON_SIZE.md / 2,
-    borderWidth: theme.borderWidth[1],
-    borderColor: theme.colors.border,
+  themeCard: {
+    padding: theme.spacing[3],
   },
   fontFamilyInput: {
     flexGrow: 1,
diff --git a/packages/app/src/screens/settings/files-section.tsx b/packages/app/src/screens/settings/files-section.tsx
index 7dec87b418..37d82d4946 100644
--- a/packages/app/src/screens/settings/files-section.tsx
+++ b/packages/app/src/screens/settings/files-section.tsx
@@ -100,7 +100,6 @@ function FilePanelSettingsRowView({
         </DropdownMenu>
         <Button
           variant="outline"
-          size="sm"
           onPress={askAgain}
           disabled={associatedPanelId === null}
           accessibilityLabel={t("settings.files.askAgainFor", { label })}
diff --git a/packages/app/src/screens/settings/general/sending-section.tsx b/packages/app/src/screens/settings/general/sending-section.tsx
index c5d5f01760..bc1712f4a1 100644
--- a/packages/app/src/screens/settings/general/sending-section.tsx
+++ b/packages/app/src/screens/settings/general/sending-section.tsx
@@ -2,7 +2,7 @@ import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { SettingsCard, SettingsSection, SettingsSelect } from "@/components/settings";
 import { useAppSettings, type SendShortcut, type SendBehavior } from "@/hooks/use-settings";
-import { useKeyboardShortcutsAvailable } from "@/keyboard/availability";
+import { useHardwareKeyboardPresent, supportsConfigurableComposerSendKeys } from "@/keyboard";
 import { getShortcutOs } from "@/utils/shortcut-platform";
 
 const SEND_BEHAVIORS: readonly SendBehavior[] = ["interrupt", "steer", "queue"];
@@ -10,7 +10,7 @@ const SEND_BEHAVIORS: readonly SendBehavior[] = ["interrupt", "steer", "queue"];
 export function SendingSection() {
   const { t } = useTranslation();
   const { settings, updateSettings } = useAppSettings();
-  const shortcutsAvailable = useKeyboardShortcutsAvailable();
+  const shortcutsAvailable = useHardwareKeyboardPresent() && supportsConfigurableComposerSendKeys;
   const modifier = getShortcutOs() === "mac" ? "⌘" : "Ctrl";
   const options = useMemo(
     () =>
diff --git a/packages/app/src/screens/settings/host-page.tsx b/packages/app/src/screens/settings/host-page.tsx
index 879ef2fe95..9c0c952488 100644
--- a/packages/app/src/screens/settings/host-page.tsx
+++ b/packages/app/src/screens/settings/host-page.tsx
@@ -65,6 +65,7 @@ import { ICON_SIZE } from "@/styles/theme";
 import type { Theme } from "@/styles/theme";
 import { useProviderIcon } from "@/components/provider-icons";
 import { BrowserToolsOptInCard } from "./browser-tools-card";
+import { PaseoToolsCard } from "./paseo-tools-card";
 import { RestartRecoveryCard } from "./restart-recovery-card";
 import { IdleRuntimeCleanupCard } from "./idle-runtime-cleanup-card";
 import { restartDaemonFromSettings, updateDaemonFromSettings } from "./daemon-lifecycle";
@@ -290,7 +291,7 @@ export function HostAgentsPage({ serverId }: { serverId: string }) {
     <View>
       {isConnected ? (
         <SettingsSection title={t("settings.hostSections.agents")}>
-          <InjectPaseoToolsCard serverId={serverId} />
+          <PaseoToolsCard serverId={serverId} />
           <BrowserToolsOptInCard serverId={serverId} />
           <AppendSystemPromptCard serverId={serverId} />
           <RestartRecoveryCard serverId={serverId} />
@@ -473,7 +474,6 @@ function ConnectionsSection({ host }: { host: HostProfile }) {
           <View style={styles.confirmActions}>
             <Button
               variant="secondary"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleCancelConfirm}
               disabled={isRemovingConnection}
@@ -482,7 +482,6 @@ function ConnectionsSection({ host }: { host: HostProfile }) {
             </Button>
             <Button
               variant="destructive"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleConfirmRemove}
               disabled={isRemovingConnection}
@@ -549,12 +548,7 @@ function ConnectionRow({
         </Text>
       </View>
       <Text style={latencyTextStyle}>{latencyText}</Text>
-      <Button
-        variant="ghost"
-        size="sm"
-        textStyle={destructiveTextStyle}
-        onPress={handlePressRemove}
-      >
+      <Button variant="ghost" textStyle={destructiveTextStyle} onPress={handlePressRemove}>
         {t("settings.host.connections.removeAction")}
       </Button>
     </View>
@@ -672,7 +666,6 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
         </View>
         <Button
           variant="outline"
-          size="sm"
           leftIcon={restartIcon}
           onPress={handleRestart}
           disabled={isRestarting || !daemonClient || !isConnected}
@@ -692,7 +685,6 @@ function RestartDaemonCard({ host }: { host: HostProfile }) {
           </View>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleRestartAndCloseTerminals}
             disabled={isRestarting || !daemonClient || !isConnected}
             testID="host-page-restart-close-terminals-button"
@@ -876,7 +868,6 @@ function UpdateDaemonCard({ host }: { host: HostProfile }) {
         </View>
         <Button
           variant="outline"
-          size="sm"
           leftIcon={updateIcon}
           onPress={handleUpdate}
           disabled={desktopManaged || isUpdating || !daemonClient || !isConnected}
@@ -910,45 +901,6 @@ function UpdateDaemonCard({ host }: { host: HostProfile }) {
   );
 }
 
-function InjectPaseoToolsCard({ serverId }: { serverId: string }) {
-  const { t } = useTranslation();
-  const isConnected = useHostRuntimeIsConnected(serverId);
-  const { config, patchConfig } = useDaemonConfig(serverId);
-
-  const handleValueChange = useCallback(
-    (next: boolean) => {
-      void patchConfig({
-        mcp: {
-          injectIntoAgents: next,
-        },
-      });
-    },
-    [patchConfig],
-  );
-
-  if (!isConnected) return null;
-
-  return (
-    <View style={settingsStyles.card} testID="host-page-inject-mcp-card">
-      <View style={settingsStyles.row}>
-        <View style={settingsStyles.rowContent}>
-          <Text style={settingsStyles.rowTitle}>
-            {t("settings.host.orchestration.enableTools.title")}
-          </Text>
-          <Text style={settingsStyles.rowHint}>
-            {t("settings.host.orchestration.enableTools.hint")}
-          </Text>
-        </View>
-        <Switch
-          value={config?.mcp.injectIntoAgents !== false}
-          onValueChange={handleValueChange}
-          accessibilityLabel={t("settings.host.orchestration.enableTools.accessibilityLabel")}
-        />
-      </View>
-    </View>
-  );
-}
-
 function AutoArchiveMergedWorkspacesCard({ serverId }: { serverId: string }) {
   const isConnected = useHostRuntimeIsConnected(serverId);
   const { config, patchConfig } = useDaemonConfig(serverId);
@@ -1091,7 +1043,6 @@ function AppendSystemPromptCard({ serverId }: { serverId: string }) {
           </View>
           <Button
             variant="outline"
-            size="sm"
             onPress={handleOpen}
             testID="host-page-append-system-prompt-edit"
           >
@@ -1118,7 +1069,6 @@ function AppendSystemPromptCard({ serverId }: { serverId: string }) {
           <View style={styles.appendPromptActions}>
             <Button
               variant="ghost"
-              size="sm"
               onPress={handleReset}
               disabled={!hasChanges || isSaving}
               testID="host-page-append-system-prompt-reset"
@@ -1127,7 +1077,6 @@ function AppendSystemPromptCard({ serverId }: { serverId: string }) {
             </Button>
             <Button
               variant="default"
-              size="sm"
               onPress={handleSave}
               disabled={!hasChanges || isSaving}
               testID="host-page-append-system-prompt-save"
@@ -1308,7 +1257,6 @@ function RemoveHostSection({
           </View>
           <Button
             variant="outline"
-            size="sm"
             leftIcon={removeIcon}
             textStyle={destructiveTextStyle}
             onPress={handleOpenConfirm}
@@ -1334,7 +1282,6 @@ function RemoveHostSection({
           <View style={styles.confirmActions}>
             <Button
               variant="secondary"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleCancel}
               disabled={isRemoving}
@@ -1343,7 +1290,6 @@ function RemoveHostSection({
             </Button>
             <Button
               variant="destructive"
-              size="sm"
               style={FLEX_1_STYLE}
               onPress={handleConfirmRemove}
               disabled={isRemoving}
@@ -1439,7 +1385,6 @@ function TerminalProfileRow({
       <View style={terminalProfileStyles.rowActions}>
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveUpIcon}
           onPress={handleMoveUp}
           disabled={isFirst}
@@ -1448,7 +1393,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveDownIcon}
           onPress={handleMoveDown}
           disabled={isLast}
@@ -1457,7 +1401,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={editProfileIcon}
           onPress={handleEdit}
           accessibilityLabel={t("settings.host.terminalProfiles.editProfile")}
@@ -1465,7 +1408,6 @@ function TerminalProfileRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={removeProfileIcon}
           onPress={handleRemove}
           accessibilityLabel={t("settings.host.terminalProfiles.remove")}
@@ -1631,7 +1573,6 @@ function TerminalProfilesSection({ serverId }: { serverId: string }) {
     () => (
       <Button
         variant="ghost"
-        size="sm"
         leftIcon={addProfileIcon}
         onPress={handleAddOpen}
         disabled={!isConnected || !profiles}
diff --git a/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx b/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx
index e00045e957..c8dc67b5ca 100644
--- a/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx
+++ b/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx
@@ -1,3 +1,8 @@
+import {
+  usesDesktopBindings,
+  useHardwareKeyboardPresent,
+  useOverlayRegistration,
+} from "@/keyboard";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { View, Text, type PressableStateCallbackType } from "react-native";
@@ -33,8 +38,6 @@ import {
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { getShortcutOs } from "@/utils/shortcut-platform";
-import { getIsElectronRuntime } from "@/constants/layout";
-import { isNative } from "@/constants/platform";
 import { getDesktopHost } from "@/desktop/host";
 
 const EMPTY_CAPTURED_COMBOS: string[] = [];
@@ -298,12 +301,12 @@ function ShortcutRow({
         {isCapturing ? (
           <>
             {showDone && (
-              <Button variant="ghost" size="sm" disabled={!captureComplete} onPress={onDone}>
+              <Button variant="ghost" disabled={!captureComplete} onPress={onDone}>
                 {t("settings.shortcuts.actions.done")}
               </Button>
             )}
             {isBindable && (
-              <Button variant="ghost" size="sm" onPress={onCancel}>
+              <Button variant="ghost" onPress={onCancel}>
                 {t("settings.shortcuts.actions.cancel")}
               </Button>
             )}
@@ -332,6 +335,7 @@ function ShortcutRow({
 
 export function KeyboardShortcutsSection() {
   const { t } = useTranslation();
+  const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   const [capturingBindingId, setCapturingBindingId] = useState<string | null>(null);
   const [capturedCombos, setCapturedCombos] = useState<string[]>([]);
   const [heldModifiers, setHeldModifiers] = useState<string | null>(null);
@@ -342,8 +346,7 @@ export function KeyboardShortcutsSection() {
 
   const isFocused = useIsFocused();
   const isMac = getShortcutOs() === "mac";
-  const isDesktopApp = getIsElectronRuntime();
-  const sections = buildKeyboardShortcutHelpSections({ isMac, isDesktop: isDesktopApp });
+  const sections = buildKeyboardShortcutHelpSections({ isMac, usesDesktopBindings });
 
   const cancelCapture = useCallback(() => {
     setCapturedCombos([]);
@@ -379,35 +382,29 @@ export function KeyboardShortcutsSection() {
     }
   }, [isFocused, capturingBindingId, cancelCapture]);
 
-  useEffect(() => {
-    if (isNative) return;
-    if (capturingBindingId === null) return;
-
-    function handleKeyDown(event: KeyboardEvent) {
+  useOverlayRegistration({
+    active: capturingBindingId !== null,
+    layer: 0,
+    keys: [],
+    manageFocus: false,
+    onKeyDown(event) {
+      if (capturingBindingId === null) return false;
       event.preventDefault();
-      event.stopPropagation();
-
       if (event.code === "Backspace" && heldModifiersFromEvent(event) === null) {
-        setCapturedCombos((current) => (current.length > 0 ? current.slice(0, -1) : current));
-        return;
+        setCapturedCombos((current) => current.slice(0, -1));
+        return true;
       }
-
       const comboString = keyboardEventToComboString(event);
       if (comboString === null) {
         setHeldModifiers(heldModifiersFromEvent(event));
-        return;
+        return true;
       }
-
       setHeldModifiers(null);
-      const capturedCombo = normalizeCapturedShortcutCombo(capturingBindingId!, comboString);
+      const capturedCombo = normalizeCapturedShortcutCombo(capturingBindingId, comboString);
       setCapturedCombos((current) => [...current, capturedCombo]);
-    }
-
-    window.addEventListener("keydown", handleKeyDown, true);
-    return () => {
-      window.removeEventListener("keydown", handleKeyDown, true);
-    };
-  }, [capturingBindingId]);
+      return true;
+    },
+  });
 
   useEffect(() => {
     return () => {
@@ -418,7 +415,7 @@ export function KeyboardShortcutsSection() {
   // Suppress desktop zoom accelerators while capturing so combos like Cmd+- are
   // recorded instead of zooming the window. No-op outside Electron.
   useEffect(() => {
-    if (isNative || !capturing) return;
+    if (!capturing) return;
     const menu = getDesktopHost()?.menu;
     void menu?.setCapturingShortcut?.(true);
     return () => {
@@ -436,18 +433,10 @@ export function KeyboardShortcutsSection() {
     [removeOverride],
   );
 
-  if (isNative) {
-    return (
-      <SettingsSection title={t("settings.sections.shortcuts")}>
-        <View style={[settingsStyles.card, styles.mobileCard]}>
-          <Text style={styles.mobileText}>{t("settings.shortcuts.unavailableOnMobile")}</Text>
-        </View>
-      </SettingsSection>
-    );
-  }
+  if (!hardwareKeyboardPresent) return null;
 
   const resetAllButton = hasOverrides ? (
-    <Button variant="ghost" size="sm" onPress={handleResetAll}>
+    <Button variant="ghost" onPress={handleResetAll}>
       {t("settings.shortcuts.actions.resetAll")}
     </Button>
   ) : undefined;
@@ -463,7 +452,7 @@ export function KeyboardShortcutsSection() {
           >
             <View style={settingsStyles.card}>
               {section.rows.map(function (row, index) {
-                const platform = { isMac, isDesktop: isDesktopApp };
+                const platform = { isMac, usesDesktopBindings };
                 const bindingId = getBindingIdForAction(row.id, platform);
                 const displayChord = resolveShortcutKeysForAction(row.id, overrides, platform);
                 // `in`, not a truthiness check: an unassigned shortcut stores
@@ -556,11 +545,4 @@ const styles = StyleSheet.create((theme) => ({
     height: 1,
     backgroundColor: theme.colors.border,
   },
-  mobileCard: {
-    padding: theme.spacing[4],
-  },
-  mobileText: {
-    fontSize: theme.fontSize.base,
-    color: theme.colors.foregroundMuted,
-  },
 }));
diff --git a/packages/app/src/screens/settings/metadata-generation-page.tsx b/packages/app/src/screens/settings/metadata-generation-page.tsx
index c9a04e9b3e..0e8d895228 100644
--- a/packages/app/src/screens/settings/metadata-generation-page.tsx
+++ b/packages/app/src/screens/settings/metadata-generation-page.tsx
@@ -4,7 +4,6 @@ import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
 import type { AgentProvider } from "@getpaseo/protocol/agent-types";
 import { CombinedModelSelector } from "@/components/combined-model-selector";
-import { ExternalLink } from "@/components/ui/external-link";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { SegmentedControl } from "@/components/ui/segmented-control";
 import { useDaemonConfig } from "@/hooks/use-daemon-config";
@@ -90,12 +89,7 @@ export function MetadataGenerationPage({ serverId }: { serverId: string }) {
     [snapshot],
   );
   const docsLink = useMemo(
-    () => (
-      <ExternalLink
-        href={METADATA_GENERATION_DOCS_URL}
-        label={t("settings.metadataGeneration.docs")}
-      />
-    ),
+    () => ({ href: METADATA_GENERATION_DOCS_URL, label: t("settings.metadataGeneration.docs") }),
     [t],
   );
 
@@ -111,7 +105,7 @@ export function MetadataGenerationPage({ serverId }: { serverId: string }) {
     <SettingsSection
       title={t("settings.metadataGeneration.title")}
       info={t("settings.metadataGeneration.description")}
-      trailing={docsLink}
+      link={docsLink}
       testID="metadata-generation-settings"
     >
       <View style={settingsStyles.card}>
@@ -130,7 +124,6 @@ export function MetadataGenerationPage({ serverId }: { serverId: string }) {
             options={modeOptions}
             value={mode}
             onValueChange={handleModeChange}
-            size="sm"
             testID="metadata-generation-mode"
           />
         </View>
diff --git a/packages/app/src/screens/settings/paseo-tools-card.tsx b/packages/app/src/screens/settings/paseo-tools-card.tsx
new file mode 100644
index 0000000000..df36bac97b
--- /dev/null
+++ b/packages/app/src/screens/settings/paseo-tools-card.tsx
@@ -0,0 +1,56 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { SettingsCard, SettingsRow } from "@/components/settings";
+import { Switch } from "@/components/ui/switch";
+import { useDaemonConfig } from "@/hooks/use-daemon-config";
+import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+
+/** The host's "give agents Paseo tools" switch, bound to the host's config. */
+export function PaseoToolsCard({ serverId }: { serverId: string }) {
+  const isConnected = useHostRuntimeIsConnected(serverId);
+  const { config, patchConfig } = useDaemonConfig(serverId);
+
+  const handleValueChange = useCallback(
+    (next: boolean) => {
+      void patchConfig({ mcp: { injectIntoAgents: next } });
+    },
+    [patchConfig],
+  );
+
+  if (!isConnected) return null;
+
+  return (
+    <SettingsCard testID="host-page-inject-mcp-card">
+      <PaseoToolsRow
+        value={config?.mcp.injectIntoAgents !== false}
+        onValueChange={handleValueChange}
+      />
+    </SettingsCard>
+  );
+}
+
+/** The Paseo tools row on its own, for a caller that decides what the switch is bound to. */
+export function PaseoToolsRow({
+  value,
+  onValueChange,
+  disabled,
+}: {
+  value: boolean;
+  onValueChange: (next: boolean) => void;
+  disabled?: boolean;
+}) {
+  const { t } = useTranslation();
+  return (
+    <SettingsRow
+      label={t("settings.host.orchestration.enableTools.title")}
+      hint={t("settings.host.orchestration.enableTools.hint")}
+    >
+      <Switch
+        value={value}
+        onValueChange={onValueChange}
+        disabled={disabled}
+        accessibilityLabel={t("settings.host.orchestration.enableTools.accessibilityLabel")}
+      />
+    </SettingsRow>
+  );
+}
diff --git a/packages/app/src/screens/settings/plugins-page.test.tsx b/packages/app/src/screens/settings/plugins-page.test.tsx
index 8a502749db..dfb16ccfa7 100644
--- a/packages/app/src/screens/settings/plugins-page.test.tsx
+++ b/packages/app/src/screens/settings/plugins-page.test.tsx
@@ -20,7 +20,8 @@ const runtime = vi.hoisted(() => ({
   client: null as DaemonClient | null,
 }));
 
-vi.mock("@/runtime/host-runtime", () => ({
+vi.mock("@/runtime/host-runtime", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@/runtime/host-runtime")>()),
   useHostRuntimeClient: () => runtime.client,
   useHostRuntimeIsConnected: () => runtime.connected,
 }));
diff --git a/packages/app/src/screens/settings/plugins-page.tsx b/packages/app/src/screens/settings/plugins-page.tsx
index f3bdab3fad..fdaf260f8d 100644
--- a/packages/app/src/screens/settings/plugins-page.tsx
+++ b/packages/app/src/screens/settings/plugins-page.tsx
@@ -1,5 +1,5 @@
 import { formatPluginInstallation } from "@getpaseo/protocol/plugin-source-reference";
-import { PluginSettingsMenuItems } from "@/plugins/settings";
+import { PluginSettingsButton } from "@/plugins/settings";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
@@ -29,10 +29,10 @@ import { SettingsSection } from "@/components/settings/headings/settings-section
 import { resolvePluginPageState } from "@/screens/settings/plugins-page-state";
 import { openPluginInstallForm } from "@/screens/settings/plugin-install-form-model";
 import { pluginRegistry, useInstalledPlugins } from "@/plugins/registry";
+import { pluginDisplayName, usePluginList } from "@/plugins/plugin-list";
 import { settingsStyles } from "@/styles/settings";
 import { confirmDialog } from "@/utils/confirm-dialog";
 
-const pluginQueryKey = (serverId: string) => ["plugins", serverId] as const;
 const PLUGIN_SOURCE_DOCS_URL = "https://paseo.sh/docs/plugins/reference#plugin-sources";
 type PluginRowAction = "reload" | "enable" | "disable" | "remove";
 
@@ -49,7 +49,6 @@ function pluginRowAction(action: string | undefined): PluginRowAction | undefine
 
 function PluginActionsMenu({
   plugin,
-  serverId,
   pending,
   pendingAction,
   onAction,
@@ -57,19 +56,18 @@ function PluginActionsMenu({
   supportsLogs,
 }: {
   plugin: PluginListItem;
-  serverId: string;
   pending: boolean;
   pendingAction?: PluginRowAction;
   onAction(action: PluginRowAction, plugin: PluginListItem): void;
-  onOpenLogs(pluginId: string): void;
+  onOpenLogs(plugin: PluginListItem): void;
   supportsLogs: boolean;
 }) {
   const { t } = useTranslation();
   const reload = useCallback(() => onAction("reload", plugin), [onAction, plugin]);
   const remove = useCallback(() => onAction("remove", plugin), [onAction, plugin]);
-  const openLogs = useCallback(() => onOpenLogs(plugin.id), [onOpenLogs, plugin.id]);
+  const openLogs = useCallback(() => onOpenLogs(plugin), [onOpenLogs, plugin]);
   const removeIcon = useMemo(() => <Trash2 size={16} color={styles.dangerIcon.color} />, []);
-  const menuLabel = t("settings.plugins.actions.menu", { id: plugin.id });
+  const menuLabel = t("settings.plugins.actions.menu", { name: pluginDisplayName(plugin) });
 
   return (
     <DropdownMenu compactMode="sheet">
@@ -83,7 +81,6 @@ function PluginActionsMenu({
         <MoreHorizontal size={18} color={styles.menuIcon.color} />
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" width={220} sheetTitle={menuLabel}>
-        <PluginSettingsMenuItems serverId={serverId} pluginId={plugin.id} disabled={pending} />
         {supportsLogs ? (
           <DropdownMenuItem onSelect={openLogs} disabled={pending}>
             {t("settings.plugins.logs.action")}
@@ -128,7 +125,7 @@ function PluginRow({
   pending: boolean;
   pendingAction?: PluginRowAction;
   onAction(action: PluginRowAction, plugin: PluginListItem): void;
-  onOpenLogs(pluginId: string): void;
+  onOpenLogs(plugin: PluginListItem): void;
   supportsLogs: boolean;
 }) {
   const { t } = useTranslation();
@@ -145,10 +142,14 @@ function PluginRow({
     () => <StatusBadge label={statusLabel} variant={badgeVariant} />,
     [badgeVariant, statusLabel],
   );
+  const name = pluginDisplayName(plugin);
+  // A display name hides the id that the CLI and plugin routes use, so show it beneath.
+  const shownId = name === plugin.id ? null : plugin.id;
   const hint = useMemo(
     () =>
-      plugin.description || plugin.installation ? (
+      shownId || plugin.description || plugin.installation ? (
         <View>
+          {shownId ? <Text style={styles.pluginSource}>{shownId}</Text> : null}
           {plugin.description ? (
             <Text style={styles.pluginDescription}>{plugin.description}</Text>
           ) : null}
@@ -157,20 +158,21 @@ function PluginRow({
           ) : null}
         </View>
       ) : undefined,
-    [plugin.description, plugin.installation],
+    [shownId, plugin.description, plugin.installation],
   );
-  const toggleLabel = `${plugin.id}: ${t(
+  const toggleLabel = `${name}: ${t(
     plugin.enabled ? "settings.plugins.actions.disable" : "settings.plugins.actions.enable",
   )}`;
   return (
     <SettingsRow
-      label={plugin.id}
+      label={name}
       labelAccessory={statusBadge}
       hint={hint}
       error={clientError ?? plugin.error}
       testID={`plugin-row-${plugin.id}`}
     >
-      <View style={styles.pluginControls} accessibilityLabel={`${plugin.id} ${statusLabel}`}>
+      <View style={styles.pluginControls} accessibilityLabel={`${name} ${statusLabel}`}>
+        <PluginSettingsButton serverId={serverId} pluginId={plugin.id} />
         <Switch
           value={plugin.enabled}
           onValueChange={toggle}
@@ -179,7 +181,6 @@ function PluginRow({
         />
         <PluginActionsMenu
           plugin={plugin}
-          serverId={serverId}
           pending={pending}
           pendingAction={pendingAction}
           onAction={onAction}
@@ -193,15 +194,16 @@ function PluginRow({
 
 function PluginLogsSheet({
   client,
-  pluginId,
+  plugin,
   serverId,
   onClose,
 }: {
   client: NonNullable<ReturnType<typeof useHostRuntimeClient>>;
-  pluginId: string;
+  plugin: PluginListItem;
   serverId: string;
   onClose(): void;
 }) {
+  const pluginId = plugin.id;
   const { t } = useTranslation();
   const logs = useFetchQuery({
     queryKey: ["plugin-logs", serverId, pluginId],
@@ -214,16 +216,16 @@ function PluginLogsSheet({
   }, [logs]);
   const header = useMemo<SheetHeader>(
     () => ({
-      title: t("settings.plugins.logs.title", { id: pluginId }),
+      title: t("settings.plugins.logs.title", { name: pluginDisplayName(plugin) }),
       actions: (
-        <Button variant="outline" size="sm" onPress={refresh} disabled={logs.isFetching}>
+        <Button variant="outline" onPress={refresh} disabled={logs.isFetching}>
           {logs.isFetching
             ? t("settings.plugins.logs.refreshing")
             : t("settings.plugins.logs.refresh")}
         </Button>
       ),
     }),
-    [logs.isFetching, pluginId, refresh, t],
+    [logs.isFetching, plugin, refresh, t],
   );
 
   let content = <Text style={styles.logsState}>{t("settings.plugins.logs.loading")}</Text>;
@@ -235,7 +237,7 @@ function PluginLogsSheet({
         title={t("settings.plugins.logs.errorTitle")}
         description={errorMessage(logs.error)}
       >
-        <Button variant="outline" size="sm" onPress={refresh}>
+        <Button variant="outline" onPress={refresh}>
           {t("settings.plugins.logs.refresh")}
         </Button>
       </Alert>
@@ -276,7 +278,6 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
   const { config, patchConfig } = useDaemonConfig(serverId);
   const refreshQueue = useRef(Promise.resolve());
   useInstalledPlugins();
-  const queryKey = useMemo(() => pluginQueryKey(serverId), [serverId]);
   const [installForm] = useState(openPluginInstallForm);
   const installState = useSyncExternalStore(
     installForm.subscribe,
@@ -293,20 +294,11 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
     ),
     [t],
   );
-  const [logsPluginId, setLogsPluginId] = useState<string | null>(null);
+  const [logsPlugin, setLogsPlugin] = useState<PluginListItem | null>(null);
   const [feedback, setFeedback] = useState<{ kind: "success" | "error"; message: string } | null>(
     null,
   );
-  const plugins = useFetchQuery({
-    queryKey,
-    queryFn: async () => {
-      if (!client) throw new Error("Plugin host is offline");
-      return client.listPlugins();
-    },
-    enabled: Boolean(client && connected && supported),
-    dataShape: "list",
-    staleTimeMs: 1_000,
-  });
+  const plugins = usePluginList(serverId);
   const refetchPlugins = plugins.refetch;
   const refresh = useCallback(async () => {
     if (!client) return;
@@ -356,27 +348,28 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
       run: async () => {
         const installed = await client.installPluginSource(input);
         installForm.reset();
-        return t("settings.plugins.feedback.installed", { id: installed.id });
+        return t("settings.plugins.feedback.installed", { name: pluginDisplayName(installed) });
       },
     });
   }, [client, installForm, installState.canSubmit, mutation, sourceInstallSupported, t]);
   const action = useCallback(
     (name: PluginRowAction, plugin: PluginListItem) => {
       if (!client) return;
+      const pluginName = pluginDisplayName(plugin);
       const run = async () => {
         if (name === "remove") {
           const confirmed = await confirmDialog({
-            title: t("settings.plugins.removeConfirmTitle", { id: plugin.id }),
+            title: t("settings.plugins.removeConfirmTitle", { name: pluginName }),
             message: t("settings.plugins.removeConfirmMessage"),
             confirmLabel: t("settings.plugins.actions.remove"),
             destructive: true,
           });
-          if (!confirmed) return t("settings.plugins.feedback.kept", { id: plugin.id });
+          if (!confirmed) return t("settings.plugins.feedback.kept", { name: pluginName });
           await client.removePlugin(plugin.id);
         } else {
           await client[`${name}Plugin`](plugin.id);
         }
-        return t(`settings.plugins.feedback.${name}`, { id: plugin.id });
+        return t(`settings.plugins.feedback.${name}`, { name: pluginName });
       };
       setFeedback(null);
       mutation.mutate({ action: name, pluginId: plugin.id, run });
@@ -408,7 +401,7 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
   const retry = useCallback(() => {
     void refetchPlugins();
   }, [refetchPlugins]);
-  const closeLogs = useCallback(() => setLogsPluginId(null), []);
+  const closeLogs = useCallback(() => setLogsPlugin(null), []);
 
   if (pageState === "offline") {
     return (
@@ -433,7 +426,7 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
         title={t("settings.plugins.states.errorTitle")}
         description={errorMessage(plugins.error)}
       >
-        <Button variant="outline" size="sm" onPress={retry}>
+        <Button variant="outline" onPress={retry}>
           {t("settings.plugins.states.retry")}
         </Button>
       </Alert>
@@ -454,7 +447,7 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
                 pending={mutation.isPending}
                 pendingAction={pending ? pluginRowAction(mutation.variables?.action) : undefined}
                 onAction={action}
-                onOpenLogs={setLogsPluginId}
+                onOpenLogs={setLogsPlugin}
                 supportsLogs={logsSupported}
               />
             );
@@ -528,10 +521,10 @@ export function HostPluginsPage({ serverId }: { serverId: string }) {
         ) : null}
         {catalogContent}
       </SettingsSection>
-      {client && logsPluginId ? (
+      {client && logsPlugin ? (
         <PluginLogsSheet
           client={client}
-          pluginId={logsPluginId}
+          plugin={logsPlugin}
           serverId={serverId}
           onClose={closeLogs}
         />
diff --git a/packages/app/src/screens/settings/providers-section.test.tsx b/packages/app/src/screens/settings/providers-section.test.tsx
index 0a702ae641..86c55be4e8 100644
--- a/packages/app/src/screens/settings/providers-section.test.tsx
+++ b/packages/app/src/screens/settings/providers-section.test.tsx
@@ -171,6 +171,11 @@ vi.mock("@/components/settings/headings/settings-info-tip", () => ({
   SettingsInfoTip: () => null,
 }));
 
+vi.mock("@/components/ui/external-link", () => ({
+  ExternalLink: () => null,
+  ExternalLinkLabel: () => null,
+}));
+
 vi.mock("@/components/ui/dropdown-menu", () => ({
   DropdownMenu: ({ children }: { children?: React.ReactNode }) =>
     React.createElement("div", null, children),
diff --git a/packages/app/src/screens/settings/providers-section.tsx b/packages/app/src/screens/settings/providers-section.tsx
index 72234b7602..078cf086f5 100644
--- a/packages/app/src/screens/settings/providers-section.tsx
+++ b/packages/app/src/screens/settings/providers-section.tsx
@@ -14,7 +14,8 @@ import { useIsCompactFormFactor } from "@/constants/layout";
 import { useToast } from "@/contexts/toast-api-context";
 import { settingsStyles } from "@/styles/settings";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import { useHostFeature } from "@/runtime/host-features";
+import { selectHostFeature, useHostFeature } from "@/runtime/host-features";
+import { useSessionStore } from "@/stores/session-store";
 import { useProvidersSnapshot } from "@/hooks/use-providers-snapshot";
 import { useDaemonConfig } from "@/hooks/use-daemon-config";
 import { buildProviderDefinitions } from "@/utils/provider-definitions";
@@ -26,6 +27,7 @@ import {
 import { ProviderCatalogList } from "@/components/provider-catalog-list";
 import { useProviderIcon } from "@/components/provider-icons";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
+import { SkeletonPulse, useSkeletonPulse } from "@/components/ui/skeleton";
 import { Switch } from "@/components/ui/switch";
 import {
   DropdownMenu,
@@ -169,6 +171,33 @@ function ProviderActionsMenu({
   );
 }
 
+const SKELETON_ROW_KEYS = [0, 1, 2, 3].map((index) => `provider-skeleton-row-${index}`);
+
+function ProviderRowsSkeleton() {
+  const { t } = useTranslation();
+  const pulse = useSkeletonPulse();
+  return (
+    <View
+      style={settingsStyles.card}
+      accessibilityLabel={t("settings.providers.loading")}
+      testID="providers-skeleton"
+    >
+      {SKELETON_ROW_KEYS.map((key, index) => (
+        <View
+          key={key}
+          style={[settingsStyles.row, index > 0 && settingsStyles.rowBorder, styles.row]}
+        >
+          <View style={styles.rowContent}>
+            <SkeletonPulse pulse={pulse} style={styles.skeletonIcon} />
+            <SkeletonPulse pulse={pulse} style={styles.skeletonTitle} />
+          </View>
+          <SkeletonPulse pulse={pulse} style={styles.skeletonSwitch} />
+        </View>
+      ))}
+    </View>
+  );
+}
+
 function ProviderRow({
   serverId,
   def,
@@ -246,27 +275,27 @@ function ProviderRow({
               ) : null}
             </View>
           </View>
+          {/* The menu leads the switch, so every switch sits on the row's right edge without
+              rows that have no menu reserving room for one. */}
           <View style={styles.trailingControls}>
+            {canRemove ? (
+              <ProviderActionsMenu
+                providerId={def.id}
+                providerLabel={def.label}
+                isRemoving={isRemoving}
+                iconSize={theme.iconSize.sm}
+                foregroundColor={theme.colors.foreground}
+                foregroundMutedColor={theme.colors.foregroundMuted}
+                dangerColor={theme.colors.statusDanger}
+                onRemove={onRemove}
+              />
+            ) : null}
             <Switch
               value={enabled}
               onValueChange={handleToggleValueChange}
               disabled={isToggling || isRemoving}
               accessibilityLabel={t("settings.providers.enableProvider", { name: def.label })}
             />
-            <View style={styles.menuSlot}>
-              {canRemove ? (
-                <ProviderActionsMenu
-                  providerId={def.id}
-                  providerLabel={def.label}
-                  isRemoving={isRemoving}
-                  iconSize={theme.iconSize.sm}
-                  foregroundColor={theme.colors.foreground}
-                  foregroundMutedColor={theme.colors.foregroundMuted}
-                  dangerColor={theme.colors.statusDanger}
-                  onRemove={onRemove}
-                />
-              ) : null}
-            </View>
           </View>
         </>
       )}
@@ -329,7 +358,6 @@ export function ProvidersSection({ serverId }: ProvidersSectionProps) {
   const { t } = useTranslation();
   const toast = useToast();
   const isConnected = useHostRuntimeIsConnected(serverId);
-  const supportsHopliteProvider = useHostFeature(serverId, "hopliteProvider");
   const supportsProviderRemoval = useHostFeature(serverId, "providerRemoval");
   const { entries, isLoading, refresh } = useProvidersSnapshot(serverId);
   const { config, patchConfig } = useDaemonConfig(serverId);
@@ -416,7 +444,11 @@ export function ProvidersSection({ serverId }: ProvidersSectionProps) {
       if (installingProviderId) return;
       setInstallingProviderId(entry.id);
       try {
-        await patchConfig(buildAcpProviderConfigPatch(entry, supportsHopliteProvider));
+        await patchConfig(
+          buildAcpProviderConfigPatch(entry, (feature) =>
+            selectHostFeature(useSessionStore.getState(), serverId, feature),
+          ),
+        );
         await refresh([entry.id]);
       } catch (error) {
         toast.error(error instanceof Error ? error.message : String(error));
@@ -424,7 +456,7 @@ export function ProvidersSection({ serverId }: ProvidersSectionProps) {
         setInstallingProviderId((current) => (current === entry.id ? null : current));
       }
     },
-    [installingProviderId, patchConfig, refresh, supportsHopliteProvider, toast],
+    [installingProviderId, patchConfig, refresh, serverId, toast],
   );
 
   return (
@@ -439,11 +471,7 @@ export function ProvidersSection({ serverId }: ProvidersSectionProps) {
             <Text style={styles.emptyText}>{t("settings.providers.unavailable")}</Text>
           </View>
         ) : null}
-        {hasServer && isConnected && isLoading ? (
-          <View style={[settingsStyles.card, styles.emptyCard]}>
-            <Text style={styles.emptyText}>{t("settings.providers.loading")}</Text>
-          </View>
-        ) : null}
+        {hasServer && isConnected && isLoading ? <ProviderRowsSkeleton /> : null}
         {hasServer && isConnected && !isLoading && providerDefinitions.length > 0 ? (
           <View style={settingsStyles.card}>
             {providerDefinitions.map((def, index) => {
@@ -513,6 +541,25 @@ const styles = StyleSheet.create((theme) => ({
   rowHovered: {
     backgroundColor: theme.colors.surface2,
   },
+  skeletonIcon: {
+    width: 20,
+    height: 20,
+    marginLeft: theme.spacing[6],
+    borderRadius: theme.borderRadius.md,
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonTitle: {
+    width: 160,
+    height: 12,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+  },
+  skeletonSwitch: {
+    width: 36,
+    height: 20,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.surface2,
+  },
   rowPressed: {
     backgroundColor: theme.colors.surface3,
   },
@@ -566,10 +613,6 @@ const styles = StyleSheet.create((theme) => ({
     alignItems: "center",
     justifyContent: "center",
   },
-  menuSlot: {
-    width: 32,
-    height: 32,
-  },
   menuButtonHovered: {
     backgroundColor: theme.colors.surface2,
   },
diff --git a/packages/app/src/screens/settings/restart-recovery-card.tsx b/packages/app/src/screens/settings/restart-recovery-card.tsx
index 9fa8a872b0..9c6d7a6d7a 100644
--- a/packages/app/src/screens/settings/restart-recovery-card.tsx
+++ b/packages/app/src/screens/settings/restart-recovery-card.tsx
@@ -59,7 +59,7 @@ export function RestartRecoveryCard({ serverId }: { serverId: string }) {
 
   if (!isConnected || !isSupported || !config) return null;
 
-  const isEnabled = config.resumeOnStartup !== false;
+  const isEnabled = config.resumeOnStartup === true;
 
   return (
     <>
@@ -87,7 +87,6 @@ export function RestartRecoveryCard({ serverId }: { serverId: string }) {
           <View style={styles.trailing}>
             <Button
               variant="outline"
-              size="sm"
               onPress={handleOpen}
               disabled={!isEnabled || mutation.isPending}
               accessibilityLabel={t("settings.host.agents.resumeOnStartup.editAccessibilityLabel")}
@@ -163,12 +162,11 @@ function ResumePromptSheet({
         </Text>
       ) : null}
       <View style={styles.sheetActions}>
-        <Button variant="ghost" size="sm" onPress={onClose} disabled={isSaving}>
+        <Button variant="ghost" onPress={onClose} disabled={isSaving}>
           {t("common.actions.cancel")}
         </Button>
         <Button
           variant="default"
-          size="sm"
           onPress={handleSave}
           disabled={!canSave}
           testID="host-page-restart-recovery-save"
diff --git a/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx b/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx
index 21633e7a10..94f336fdea 100644
--- a/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx
+++ b/packages/app/src/screens/settings/sidebar/sidebar-nav-section.tsx
@@ -1,3 +1,4 @@
+import { SidebarViewPicker } from "@/plugins/sidebar-view";
 import { useCallback, useMemo, type ComponentType, type ReactElement } from "react";
 import { Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
@@ -117,7 +118,6 @@ function SidebarNavRow({
       <View style={styles.rowActions}>
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveUpIcon}
           onPress={handleMoveUp}
           disabled={isFirst}
@@ -126,7 +126,6 @@ function SidebarNavRow({
         />
         <Button
           variant="ghost"
-          size="sm"
           leftIcon={moveDownIcon}
           onPress={handleMoveDown}
           disabled={isLast}
@@ -185,6 +184,7 @@ function SidebarItemsCard({ section }: { section: SidebarSection }): ReactElemen
 export function SidebarNavSection(): ReactElement {
   return (
     <>
+      <SidebarViewPicker />
       <SidebarItemsCard section="header" />
       <SidebarItemsCard section="footer" />
     </>
diff --git a/packages/app/src/screens/settings/terminal/terminal-section.tsx b/packages/app/src/screens/settings/terminal/terminal-section.tsx
index 4193e2e874..89fbe6795e 100644
--- a/packages/app/src/screens/settings/terminal/terminal-section.tsx
+++ b/packages/app/src/screens/settings/terminal/terminal-section.tsx
@@ -42,7 +42,6 @@ export function TerminalSection() {
             </Text>
           </View>
           <FormTextInput
-            size="sm"
             initialValue={scrollbackValue}
             onChangeText={handleChangeText}
             onBlur={commitScrollback}
diff --git a/packages/app/src/screens/settings/voice/speech-provider-sheet.tsx b/packages/app/src/screens/settings/voice/speech-provider-sheet.tsx
index 7c842053b3..386fcb5578 100644
--- a/packages/app/src/screens/settings/voice/speech-provider-sheet.tsx
+++ b/packages/app/src/screens/settings/voice/speech-provider-sheet.tsx
@@ -21,7 +21,7 @@ import {
   SettingsSelect,
 } from "@/components/settings";
 import { Button } from "@/components/ui/button";
-import { buttonControlHeight } from "@/components/ui/control-geometry";
+import { controlHeightForLayout } from "@/components/ui/control-geometry";
 import { useContainedControlSize } from "@/components/ui/control-size";
 import { foregroundIconColorMapping } from "@/components/ui/icon-color";
 import { PressHighlight } from "@/components/ui/press-highlight";
@@ -532,8 +532,12 @@ function LocalModelRow({
 // Every catalog row is as tall as one holding a button, so a row does not shrink when its
 // download finishes and the button goes away.
 function TrailingControls({ children }: { children: ReactNode }) {
-  const size = useContainedControlSize() ?? "sm";
-  const style = useMemo(() => [styles.trailing, { minHeight: buttonControlHeight[size] }], [size]);
+  const size = useContainedControlSize() ?? "md";
+  const isCompact = useIsCompactFormFactor();
+  const style = useMemo(
+    () => [styles.trailing, { minHeight: controlHeightForLayout(size, isCompact) }],
+    [size, isCompact],
+  );
   return <View style={style}>{children}</View>;
 }
 
diff --git a/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx b/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx
new file mode 100644
index 0000000000..220e8dff2e
--- /dev/null
+++ b/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx
@@ -0,0 +1,52 @@
+import { useCallback, useState, type ReactNode } from "react";
+import { View, type LayoutChangeEvent } from "react-native";
+import { selectWorkspaceChrome } from "./workspace-tab-layout";
+import { WorkspaceTabMeasurementScope } from "./workspace-desktop-tabs-row";
+import type { WorkspaceTabDescriptor } from "./workspace-tabs-types";
+
+/**
+ * Shows `children` (full header and tab rail) or `compactHeader` below the compact width.
+ * Without a compact header it always shows `children`, keeping the same tree so they never remount.
+ */
+export function AdaptiveWorkspaceChrome({
+  compactHeader,
+  children,
+}: {
+  compactHeader: ReactNode | null;
+  children: ReactNode;
+}) {
+  const [width, setWidth] = useState<number | null>(null);
+  const measure = useCallback((event: LayoutChangeEvent) => {
+    const measured = event.nativeEvent.layout.width;
+    if (measured > 0) setWidth(measured);
+  }, []);
+  return (
+    <WorkspaceTabMeasurementScope>
+      <View onLayout={measure}>
+        {compactHeader === null
+          ? children
+          : selectWorkspaceChrome({ width, compact: compactHeader, full: children })}
+      </View>
+    </WorkspaceTabMeasurementScope>
+  );
+}
+
+/** One pane's tabs, as its compact tab switcher and pane menu need them. */
+export interface WorkspaceCompactHeaderTabs {
+  tabs: WorkspaceTabDescriptor[];
+  activeTabKey: string;
+  actions: WorkspaceCompactHeaderActions;
+}
+
+export interface WorkspaceCompactHeaderActions {
+  pane?: {
+    id: string;
+    splitRight?: () => void;
+    splitDown?: () => void;
+    toggleMaximized?: () => void;
+    maximized: boolean;
+  };
+  closeAbove: (key: string) => Promise<void> | void;
+  closeBelow: (key: string) => Promise<void> | void;
+  closeOthers: (key: string) => Promise<void> | void;
+}
diff --git a/packages/app/src/screens/workspace/compact-workspace-header/index.tsx b/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
index 2a7c4a6a57..1865bc5c93 100644
--- a/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
+++ b/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
@@ -1,4 +1,4 @@
-import { useMemo, type ReactNode } from "react";
+import { Fragment, useMemo, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
 import { CompactHeader } from "@/components/headers/compact-header";
 import {
@@ -6,6 +6,13 @@ import {
   WorkspaceExplorerToggle,
 } from "@/screens/workspace/workspace-explorer-toggle";
 import { WorkspaceHeaderProjectRow } from "@/screens/workspace/workspace-header-project-row";
+import {
+  useWindowLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+  WindowLayoutActions,
+} from "@/window-layout";
+import { IconButtonChromeProvider } from "@/components/ui/icon-button-chrome";
 
 export { MobileWorkspaceTabSwitcher } from "./tab-switcher";
 
@@ -18,8 +25,11 @@ interface CompactWorkspaceHeaderProps {
   onToggleExplorer: () => void;
   explorerToggleLabel: string;
   explorerToggleAccessibilityState: { expanded: boolean };
-  /** Tab switcher and workspace menu, before the explorer toggle. */
+  tabSwitcher: ReactNode;
+  /** Workspace overflow menu. */
   children: ReactNode;
+  headerVariant: "compact" | "full";
+  actionsActive: boolean;
 }
 
 /** The compact header with the workspace's project row and controls. */
@@ -32,9 +42,13 @@ export function CompactWorkspaceHeader({
   explorerToggleLabel,
   explorerToggleAccessibilityState,
   children,
+  tabSwitcher,
   serverId,
+  headerVariant,
+  actionsActive,
 }: CompactWorkspaceHeaderProps) {
   const { t } = useTranslation();
+  const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   const projectRow = useMemo(
     () => (
       <WorkspaceHeaderProjectRow
@@ -45,9 +59,10 @@ export function CompactWorkspaceHeader({
     ),
     [subtitle, isSubtitleDistinct, serverId],
   );
-  const actions = (
-    <>
-      {children}
+  const symbols = {
+    "tab-count": tabSwitcher,
+    overflow: children,
+    explorer: (
       <WorkspaceExplorerToggle
         onPress={onToggleExplorer}
         label={explorerToggleLabel}
@@ -56,17 +71,25 @@ export function CompactWorkspaceHeader({
         accessibilityState={explorerToggleAccessibilityState}
         mobile
       />
-    </>
-  );
+    ),
+  };
+  const actions = resolveWorkspaceBarActions(headerVariant).map((symbol) => (
+    <Fragment key={symbol}>{symbols[symbol]}</Fragment>
+  ));
 
   return (
-    <CompactHeader
-      navigation="menu"
-      title={title}
-      titleTestID="workspace-header-title"
-      subtitle={projectRow}
-      loading={isLoading}
-      actions={actions}
-    />
+    <IconButtonChromeProvider value="header-island">
+      {headerVariant === "compact" ? (
+        <CompactHeader
+          navigation="menu"
+          title={title}
+          titleTestID="workspace-header-title"
+          subtitle={projectRow}
+          loading={isLoading}
+          actions={actionsInBar ? undefined : actions}
+        />
+      ) : null}
+      <WindowLayoutActions active={actionsActive}>{actions}</WindowLayoutActions>
+    </IconButtonChromeProvider>
   );
 }
diff --git a/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx b/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
index 737e92b4c2..334a166aef 100644
--- a/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
+++ b/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
@@ -1,3 +1,4 @@
+import { workspaceTabSwitcherPopoverLayout } from "../workspace-tab-layout";
 import { memo, useCallback, useMemo, useRef, useState } from "react";
 import { Keyboard, Pressable, Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
@@ -123,14 +124,15 @@ function getFallbackTabOptionDescription(
 }
 
 interface MobileWorkspaceTabSwitcherProps {
+  paneId?: string;
   tabs: WorkspaceTabDescriptor[];
   activeTabKey: string;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
   onSelectSwitcherTab: (key: string) => void;
   createTerminalDisabled: boolean;
-  onCreateDraftTab: () => void;
-  onCreateTerminal: () => void;
+  onCreateDraftTab: (input?: { paneId?: string }) => void;
+  onCreateTerminal: (input?: { paneId?: string }) => void;
   onCopyResumeCommand: (agentId: string) => Promise<void> | void;
   onCopyAgentId: (agentId: string) => Promise<void> | void;
   onCopyTerminalId: (terminalId: string) => Promise<void> | void;
@@ -285,6 +287,7 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
   createTerminalDisabled,
   onCreateDraftTab,
   onCreateTerminal,
+  paneId,
   onCopyResumeCommand,
   onCopyAgentId,
   onCopyTerminalId,
@@ -342,13 +345,13 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
 
   const handleNewAgent = useCallback(() => {
     setIsOpen(false);
-    onCreateDraftTab();
-  }, [onCreateDraftTab]);
+    onCreateDraftTab({ paneId });
+  }, [onCreateDraftTab, paneId]);
 
   const handleNewTerminal = useCallback(() => {
     setIsOpen(false);
-    onCreateTerminal();
-  }, [onCreateTerminal]);
+    onCreateTerminal({ paneId });
+  }, [onCreateTerminal, paneId]);
 
   const footer = useMemo(
     () => (
@@ -456,6 +459,7 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
       </Pressable>
 
       <Combobox
+        {...workspaceTabSwitcherPopoverLayout}
         options={tabSwitcherOptions}
         value={activeTabKey}
         onSelect={onSelectSwitcherTab}
diff --git a/packages/app/src/screens/workspace/explorer-sidebar.tsx b/packages/app/src/screens/workspace/explorer-sidebar.tsx
index e39106b65b..c43e87c45b 100644
--- a/packages/app/src/screens/workspace/explorer-sidebar.tsx
+++ b/packages/app/src/screens/workspace/explorer-sidebar.tsx
@@ -38,6 +38,7 @@ interface ExplorerSidebarDockProps extends Pick<
   normalizedServerId: string;
   normalizedWorkspaceId: string;
   isWorkspaceFocused: boolean;
+  paneFocusSuspended: boolean;
   closingTabIds: Set<string>;
   onSelectTab: (paneId: string, tabId: string) => void;
   onCloseTab: (tabId: string) => Promise<void> | void;
@@ -56,6 +57,7 @@ export function ExplorerSidebarDock({
   normalizedServerId,
   normalizedWorkspaceId,
   isWorkspaceFocused,
+  paneFocusSuspended,
   closingTabIds,
   onSelectTab,
   onCloseTab,
@@ -167,7 +169,7 @@ export function ExplorerSidebarDock({
               normalizedServerId={normalizedServerId}
               normalizedWorkspaceId={normalizedWorkspaceId}
               isWorkspaceFocused={isWorkspaceFocused}
-              isPaneFocused
+              isPaneFocused={!paneFocusSuspended}
               buildPaneContentModel={buildPaneContentModel}
             />
           </View>
diff --git a/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx b/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
index 4714467985..d2ece171f7 100644
--- a/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
+++ b/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
@@ -1,6 +1,11 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { Gesture } from "react-native-gesture-handler";
-import { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
+import {
+  runOnJS,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+} from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { HEADER_TOP_PADDING_MOBILE } from "@/constants/layout";
@@ -9,7 +14,14 @@ import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
 } from "@/components/sidebar-resize-handle-layout";
-import { resolveExplorerSidebarWidth } from "@/components/explorer-sidebar-layout";
+import {
+  beginExplorerSidebarResize,
+  finishExplorerSidebarResize,
+  reconcileExplorerSidebarResize,
+  resolveExplorerSidebarFrameWidth,
+  resolveExplorerSidebarWidth,
+  type ExplorerSidebarResize,
+} from "@/components/explorer-sidebar-layout";
 import type { ExplorerGeometryInput, ExplorerGeometry } from "./geometry-types";
 export function useExplorerGeometry({
   width,
@@ -21,10 +33,16 @@ export function useExplorerGeometry({
   const insets = useSafeAreaInsets();
   const resizeWidth = useSharedValue(width);
   const startWidth = useSharedValue(width);
+  const resize = useSharedValue<ExplorerSidebarResize | null>(null);
   const [resizePressed, setResizePressed] = useState(false);
-  useEffect(() => {
-    resizeWidth.value = width;
-  }, [resizeWidth, width]);
+  useAnimatedReaction(
+    () => ({ resize: resize.value, width, containerWidth, overlay, resizeEnabled }),
+    ({ resize: currentResize, ...allocation }) => {
+      const nextResize = reconcileExplorerSidebarResize(currentResize, allocation);
+      if (nextResize !== currentResize) resize.value = nextResize;
+    },
+    [containerWidth, overlay, resize, resizeEnabled, width],
+  );
 
   const showResizeGrip = useCallback(() => setResizePressed(true), []);
   const hideResizeGrip = useCallback(() => setResizePressed(false), []);
@@ -37,22 +55,50 @@ export function useExplorerGeometry({
         .activeOffsetX([-SIDEBAR_RESIZE_ACTIVATION_OFFSET, SIDEBAR_RESIZE_ACTIVATION_OFFSET])
         .failOffsetY([-SIDEBAR_RESIZE_FAIL_OFFSET, SIDEBAR_RESIZE_FAIL_OFFSET])
         .onStart((event) => {
-          startWidth.value = width + event.translationX;
-          resizeWidth.value = width;
+          const currentWidth = resolveExplorerSidebarFrameWidth({
+            width,
+            containerWidth,
+            overlay,
+            resizeEnabled,
+            resize: resize.value,
+            resizeWidth: resizeWidth.value,
+          });
+          resize.value = beginExplorerSidebarResize(resize.value, {
+            width,
+            containerWidth,
+            overlay,
+            resizeEnabled,
+          });
+          startWidth.value = currentWidth + event.translationX;
+          resizeWidth.value = currentWidth;
         })
         .onUpdate((event) => {
+          if (!resize.value) return;
           resizeWidth.value = resolveExplorerSidebarWidth({
             requestedWidth: startWidth.value - event.translationX,
             containerWidth,
           });
         })
-        .onEnd(() => runOnJS(onResize)(resizeWidth.value))
-        .onFinalize(() => scheduleOnRN(hideResizeGrip)),
+        .onEnd((_event, success) => {
+          {
+            resize.value = finishExplorerSidebarResize(resize.value, resizeWidth.value, success);
+            if (!success || !resize.value) return;
+          }
+          runOnJS(onResize)(resizeWidth.value);
+        })
+        .onFinalize((_event, success) => {
+          if (!success) {
+            resize.value = finishExplorerSidebarResize(resize.value, resizeWidth.value, false);
+          }
+          scheduleOnRN(hideResizeGrip);
+        }),
     [
       resizeEnabled,
       onResize,
       containerWidth,
       hideResizeGrip,
+      overlay,
+      resize,
       resizeWidth,
       showResizeGrip,
       startWidth,
@@ -61,12 +107,21 @@ export function useExplorerGeometry({
   );
   // Reanimated retains the last animated value when its style is removed. Keep this
   // style attached across folding and explicitly size overlays to the workspace viewport.
-  const animatedWidthStyle = useAnimatedStyle(
-    () => ({
-      width: overlay ? containerWidth : resizeWidth.value,
-    }),
-    [containerWidth, overlay],
-  );
+  const animatedWidthStyle = useAnimatedStyle(() => {
+    if (overlay) return { width: containerWidth };
+    {
+      return {
+        width: resolveExplorerSidebarFrameWidth({
+          width,
+          containerWidth,
+          overlay,
+          resizeEnabled,
+          resize: resize.value,
+          resizeWidth: resizeWidth.value,
+        }),
+      };
+    }
+  }, [containerWidth, overlay, resizeEnabled, width]);
   return {
     frameStyle: animatedWidthStyle,
     panelStyle: {
diff --git a/packages/app/src/screens/workspace/scripts/index.ts b/packages/app/src/screens/workspace/scripts/index.ts
index efff482e80..bbe223f520 100644
--- a/packages/app/src/screens/workspace/scripts/index.ts
+++ b/packages/app/src/screens/workspace/scripts/index.ts
@@ -8,3 +8,5 @@ export {
   type UseWorkspaceScriptsMenuPagesInput,
   type WorkspaceScriptsMenuPages,
 } from "./workspace-scripts-menu-pages";
+
+export { useWorkspaceScriptActions } from "./use-workspace-script-actions";
diff --git a/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts b/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
index fb7809990f..6752f02719 100644
--- a/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
+++ b/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
@@ -3,9 +3,9 @@ import * as Clipboard from "expo-clipboard";
 import { useMutation } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import type { WorkspaceDescriptor } from "@/stores/session-store";
-import { useSessionStore } from "@/stores/session-store";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { useHostRuntimeSnapshot } from "@/runtime/host-runtime";
-import { useToast } from "@/contexts/toast-context";
+import { useToast } from "@/contexts/toast-api-context";
 import {
   resolveWorkspaceScriptLink,
   type WorkspaceScriptLinkKind,
@@ -34,6 +34,7 @@ export interface WorkspaceScriptActions {
 }
 
 export interface UseWorkspaceScriptActionsInput {
+  client: Pick<DaemonClient, "startWorkspaceScript" | "killTerminal"> | null;
   serverId: string;
   workspaceId: string;
   scripts: WorkspaceDescriptor["scripts"];
@@ -45,10 +46,11 @@ export interface UseWorkspaceScriptActionsInput {
  * lists them.
  *
  * A restart outlives the press that asked for it — the second half waits for the daemon to
- * report the script stopped — so mount this with whatever owns the menu, not inside a menu page
- * that unmounts when the menu closes.
+ * report the script stopped — so mount this once with the workspace screen and pass its actions to
+ * each menu surface. Header placement and menu lifetime must not own pending restarts.
  */
 export function useWorkspaceScriptActions({
+  client,
   serverId,
   workspaceId,
   scripts,
@@ -56,7 +58,6 @@ export function useWorkspaceScriptActions({
 }: UseWorkspaceScriptActionsInput): WorkspaceScriptActions {
   const { t } = useTranslation();
   const toast = useToast();
-  const client = useSessionStore((state) => state.sessions[serverId]?.client ?? null);
   const activeConnection = useHostRuntimeSnapshot(serverId)?.activeConnection ?? null;
   const preferredRouteKind = useWorkspaceServiceRoutePreferencesStore(
     (state) => state.byServerId[serverId] ?? null,
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
index 290f424e97..dbe4b1ab92 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
@@ -8,6 +8,8 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { WorkspaceScriptPayload } from "@getpaseo/protocol/messages";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createRoot } from "react-dom/client";
+import { ToastApiProvider } from "@/contexts/toast-api-context";
+import { useWorkspaceScriptActions } from "./use-workspace-script-actions";
 import { WorkspaceScriptsButton } from "./workspace-scripts-button";
 
 void testI18n;
@@ -50,7 +52,13 @@ const {
 
   return {
     theme: hoistedTheme,
-    startWorkspaceScriptMock: vi.fn(async () => ({ terminalId: "terminal-script-1" })),
+    startWorkspaceScriptMock: vi.fn(async () => ({
+      terminalId: "terminal-script-1",
+      requestId: "start-1",
+      workspaceId: "workspace-1",
+      scriptName: "dev",
+      error: null,
+    })),
     killTerminalMock: vi.fn(async () => ({
       terminalId: "terminal-script-1",
       success: true,
@@ -113,20 +121,6 @@ vi.mock("@/workspace-service-routes/store", async () => {
   };
 });
 
-vi.mock("@/stores/session-store", () => ({
-  useSessionStore: (selector: (state: unknown) => unknown) =>
-    selector({
-      sessions: {
-        "test-server": {
-          client: {
-            startWorkspaceScript: startWorkspaceScriptMock,
-            killTerminal: killTerminalMock,
-          },
-        },
-      },
-    }),
-}));
-
 vi.mock("@/contexts/toast-context", () => ({
   useToast: () => ({ show: vi.fn(), error: vi.fn(), copied: copiedToastMock }),
 }));
@@ -237,6 +231,34 @@ interface RenderScriptsOptions {
   hideLabels?: boolean;
 }
 
+const testToast = { show: () => () => {}, error: () => {}, copied: copiedToastMock };
+const scriptClient = {
+  startWorkspaceScript: startWorkspaceScriptMock,
+  killTerminal: killTerminalMock,
+};
+function ScriptsOwner({
+  scripts,
+  hideLabels,
+}: {
+  scripts: WorkspaceScriptPayload[];
+  hideLabels?: boolean;
+}) {
+  const actions = useWorkspaceScriptActions({
+    client: scriptClient,
+    serverId: "test-server",
+    workspaceId: "workspace-1",
+    scripts,
+  });
+  return (
+    <WorkspaceScriptsButton
+      actions={actions}
+      scripts={scripts}
+      liveTerminalIds={LIVE_TERMINAL_IDS}
+      hideLabels={hideLabels}
+    />
+  );
+}
+
 function renderScripts(
   scripts: WorkspaceScriptPayload[],
   options: RenderScriptsOptions = {},
@@ -257,13 +279,9 @@ function renderScripts(
   function element(nextScripts: WorkspaceScriptPayload[]): ReactElement {
     return (
       <QueryClientProvider client={queryClient}>
-        <WorkspaceScriptsButton
-          serverId="test-server"
-          workspaceId="workspace-1"
-          scripts={nextScripts}
-          liveTerminalIds={LIVE_TERMINAL_IDS}
-          hideLabels={options.hideLabels}
-        />
+        <ToastApiProvider api={testToast}>
+          <ScriptsOwner scripts={nextScripts} hideLabels={options.hideLabels} />
+        </ToastApiProvider>
       </QueryClientProvider>
     );
   }
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
index 3a1c472518..8e922ee2ab 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
@@ -28,23 +28,18 @@ import type {
   WorkspaceScriptLinkTarget,
 } from "@/utils/workspace-script-links";
 import type { Theme } from "@/styles/theme";
-import { buttonControlHeight, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { extraMutedIconColorMapping } from "@/components/ui/icon-color";
 import { ExitCodeBadge, routeLabelKey, ScriptIcon } from "./script-marks";
 import { scriptToneColorMapping } from "./script-status";
-import {
-  useWorkspaceScriptActions,
-  type WorkspaceScriptActions,
-} from "./use-workspace-script-actions";
+import type { WorkspaceScriptActions } from "./use-workspace-script-actions";
 
 type RowActionIcon = "copy" | "open" | "restart" | "start" | "stop" | "terminal";
 
 interface WorkspaceScriptsButtonProps {
-  serverId: string;
-  workspaceId: string;
+  actions: WorkspaceScriptActions;
   scripts: WorkspaceDescriptor["scripts"];
   liveTerminalIds?: readonly string[];
-  onScriptTerminalStarted?: (terminalId: string) => void;
   onViewTerminal?: (terminalId: string) => void;
   onOpenUrlInBrowserTab?: (url: string) => void;
   hideLabels?: boolean;
@@ -448,22 +443,14 @@ function ScriptRow({
 }
 
 export function WorkspaceScriptsButton({
-  serverId,
-  workspaceId,
+  actions,
   scripts,
   liveTerminalIds = [],
-  onScriptTerminalStarted,
   onViewTerminal,
   onOpenUrlInBrowserTab,
   hideLabels,
 }: WorkspaceScriptsButtonProps): ReactElement | null {
   const { t } = useTranslation();
-  const actions = useWorkspaceScriptActions({
-    serverId,
-    workspaceId,
-    scripts,
-    onScriptTerminalStarted,
-  });
   const liveTerminalIdSet = useMemo(() => new Set(liveTerminalIds), [liveTerminalIds]);
 
   const triggerStyle = useCallback(
@@ -531,10 +518,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
index 3d14d9faff..0dd6fe5400 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
@@ -18,10 +18,7 @@ import type {
 } from "@/utils/workspace-script-links";
 import { ExitCodeBadge, routeLabelKey, ScriptIcon } from "./script-marks";
 import { scriptToneColorMapping, summarizeScripts, type ScriptsSummary } from "./script-status";
-import {
-  useWorkspaceScriptActions,
-  type WorkspaceScriptActions,
-} from "./use-workspace-script-actions";
+import type { WorkspaceScriptActions } from "./use-workspace-script-actions";
 
 type WorkspaceScript = WorkspaceDescriptor["scripts"][number];
 
@@ -56,11 +53,9 @@ function scriptPageId(scriptName: string): string {
 }
 
 export interface UseWorkspaceScriptsMenuPagesInput {
-  serverId: string;
-  workspaceId: string;
+  actions: WorkspaceScriptActions;
   scripts: WorkspaceDescriptor["scripts"];
   liveTerminalIds: readonly string[];
-  onScriptTerminalStarted: (terminalId: string) => void;
   onViewTerminal: (terminalId: string) => void;
   onOpenUrlInBrowserTab: (url: string) => void;
 }
@@ -80,25 +75,16 @@ export interface WorkspaceScriptsMenuPages {
  * Every script gets a page whether or not it runs, so stopping one from its own page flips that
  * page to its stopped state instead of pulling it out from under the user.
  *
- * The actions live here rather than in a page, so call this from whatever owns the menu: a restart
- * finishes after the sheet has closed.
+ * The workspace screen owns the actions so a restart finishes across menu and header changes.
  */
 export function useWorkspaceScriptsMenuPages({
-  serverId,
-  workspaceId,
+  actions,
   scripts,
   liveTerminalIds,
-  onScriptTerminalStarted,
   onViewTerminal,
   onOpenUrlInBrowserTab,
 }: UseWorkspaceScriptsMenuPagesInput): WorkspaceScriptsMenuPages {
   const { t } = useTranslation();
-  const actions = useWorkspaceScriptActions({
-    serverId,
-    workspaceId,
-    scripts,
-    onScriptTerminalStarted,
-  });
   const summary = useMemo(() => summarizeScripts(scripts), [scripts]);
 
   const trigger = useMemo(
diff --git a/packages/app/src/screens/workspace/sheet-pane/host.tsx b/packages/app/src/screens/workspace/sheet-pane/host.tsx
index 3f8e60783a..74f5079fba 100644
--- a/packages/app/src/screens/workspace/sheet-pane/host.tsx
+++ b/packages/app/src/screens/workspace/sheet-pane/host.tsx
@@ -2,6 +2,7 @@ import React, { createContext, useCallback, useContext, type ReactNode } from "r
 import invariant from "tiny-invariant";
 import { NavigationContext, NavigationRouteContext } from "expo-router/react-navigation";
 import { useAssistantFileLinkEnvironmentBridge } from "@/assistant-file-links";
+import { useForgeShorthandBridge } from "@/git/forge-shorthand";
 import { useComposerEditingEnvironmentBridge } from "@/composer/editing-session";
 import { RetainedPanelActivity, useRetainedPanelActive } from "@/components/retained-panel";
 import type { ContextBridge } from "@/components/ui/isolated-bottom-sheet-modal";
@@ -56,13 +57,14 @@ export function useSheetPaneBridge(): ContextBridge {
   const editing = useComposerEditingEnvironmentBridge();
   const cache = useDiffDocumentWorkspaceCacheBridge();
   const files = useAssistantFileLinkEnvironmentBridge();
+  const forgeShorthand = useForgeShorthandBridge();
   const active = useRetainedPanelActive();
   const serverId = useHostRouteServerId();
   const navigation = useContext(NavigationContext);
   const route = useContext(NavigationRouteContext);
   return useCallback(
     (children) => {
-      const content = editing(cache(files(children)));
+      const content = editing(cache(files(forgeShorthand(children))));
       return (
         <SheetPaneHostContext.Provider value={host}>
           <NavigationContext.Provider value={navigation}>
@@ -79,6 +81,6 @@ export function useSheetPaneBridge(): ContextBridge {
         </SheetPaneHostContext.Provider>
       );
     },
-    [host, editing, cache, files, active, serverId, navigation, route],
+    [host, editing, cache, files, forgeShorthand, active, serverId, navigation, route],
   );
 }
diff --git a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
index f7645ac168..3c138087c0 100644
--- a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
+++ b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
@@ -1,6 +1,8 @@
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import React, {
   Fragment,
+  createContext,
+  useContext,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -47,7 +49,7 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuItem } from "@/component
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
 import { WORKSPACE_SECONDARY_HEADER_HEIGHT, useIsCompactFormFactor } from "@/constants/layout";
-import { buttonControlHeight } from "@/components/ui/control-geometry";
+import { CONTROL_HEIGHTS } from "@/components/ui/control-geometry";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { Shortcut } from "@/components/ui/shortcut";
 import { useWorkspaceTabLayout } from "@/screens/workspace/use-workspace-tab-layout";
@@ -82,6 +84,7 @@ import { buildWorkspaceKeyboardHandlerId } from "@/keyboard/handler-id";
 import type { KeyboardActionDefinition } from "@/keyboard/keyboard-action-dispatcher";
 import { WorkspaceNewTabMenuContent } from "@/screens/workspace/workspace-new-tab-menu";
 import {
+  paneContentToolbarIconSize,
   paneContentToolbarTrailingPadding,
   ToolbarButton,
   ToolbarControls,
@@ -115,6 +118,8 @@ const TAB_ICON_WIDTH = 14;
 const TAB_CONTENT_GAP = 4;
 const TAB_DROP_INDICATOR_WIDTH = 4;
 const TAB_MODIFIED_DOT_SIZE = 8;
+// The tab rail only renders in the wide layout, so the device alone picks its glyph size.
+const TAB_RAIL_GLYPH_SIZE = paneContentToolbarIconSize(false);
 const TAB_MIN_WIDTH = 64;
 const TAB_MAX_WIDTH = 160;
 const TAB_CLOSE_BUTTON_RESERVED_WIDTH = 0;
@@ -249,7 +254,7 @@ function WorkspaceNewTabButton({
         testID="workspace-new-tab-button"
         style={placement === "inline" ? styles.inlineNewTabButton : undefined}
       >
-        <ThemedPlus size={14} uniProps={extraMutedColorMapping} />
+        <ThemedPlus size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
       </ToolbarButton>
       <WorkspaceNewTabMenuContent
         serverId={serverId}
@@ -298,11 +303,11 @@ function WorkspacePaneToolbarActions({
   const splitDownKeys = useShortcutKeys("workspace-pane-split-down");
   const splitActionsVisible = showSplitActions && Boolean(onSplitRight && onSplitDown);
   const splitRightLeading = useMemo(
-    () => <ThemedColumns2 size={14} uniProps={extraMutedColorMapping} />,
+    () => <ThemedColumns2 size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />,
     [],
   );
   const splitDownLeading = useMemo(
-    () => <ThemedRows2 size={14} uniProps={extraMutedColorMapping} />,
+    () => <ThemedRows2 size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />,
     [],
   );
   const splitRightTrailing = useMemo(
@@ -341,9 +346,9 @@ function WorkspacePaneToolbarActions({
           onPress={onTogglePaneMaximized}
         >
           {paneMaximized ? (
-            <ThemedMinimize size={14} uniProps={extraMutedColorMapping} />
+            <ThemedMinimize size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           ) : (
-            <ThemedMaximize size={14} uniProps={extraMutedColorMapping} />
+            <ThemedMaximize size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           )}
         </ToolbarButton>
       ) : null}
@@ -354,7 +359,7 @@ function WorkspacePaneToolbarActions({
             label={t("workspace.git.actions.moreActions")}
             testID="workspace-split-pane-menu"
           >
-            <ThemedEllipsis size={14} uniProps={extraMutedColorMapping} />
+            <ThemedEllipsis size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           </ToolbarButton>
           <DropdownMenuContent
             side="bottom"
@@ -409,7 +414,7 @@ function WorkspaceExitFocusModeButton({
         testID="workspace-exit-focus-mode"
         onPress={onPress}
       >
-        <ThemedX size={14} uniProps={mutedColorMapping} />
+        <ThemedX size={TAB_RAIL_GLYPH_SIZE} uniProps={mutedColorMapping} />
       </ToolbarButton>
     </View>
   );
@@ -485,6 +490,13 @@ interface WorkspaceTabLabelMeasurement {
   width: number;
 }
 
+const TabMeasurementCache = createContext<Map<string, WorkspaceTabLabelMeasurement> | null>(null);
+
+export function WorkspaceTabMeasurementScope({ children }: { children: React.ReactNode }) {
+  const cache = useMemo(() => new Map<string, WorkspaceTabLabelMeasurement>(), []);
+  return <TabMeasurementCache.Provider value={cache}>{children}</TabMeasurementCache.Provider>;
+}
+
 interface WorkspaceTabTrackSnapshot {
   signature: string;
   tabs: ResolvedWorkspaceDesktopTabRowItem[];
@@ -958,6 +970,47 @@ function TabChip({
   );
 }
 
+export function useWorkspaceNewTabKeyboardAction({
+  handlerName = "workspace-new-tab",
+  ownsKeyboardShortcuts,
+  normalizedServerId,
+  normalizedWorkspaceId,
+  paneId,
+  createNewTab,
+}: {
+  handlerName?: string;
+  ownsKeyboardShortcuts: boolean;
+  normalizedServerId: string;
+  normalizedWorkspaceId: string;
+  paneId?: string;
+  createNewTab: () => void;
+}) {
+  const handleNewTabKeyboardAction = useCallback(
+    (action: KeyboardActionDefinition): boolean => {
+      if (!ownsKeyboardShortcuts) return false;
+      if (action.id === "workspace.tab.menu.open") {
+        createNewTab();
+        return true;
+      }
+      return false;
+    },
+    [createNewTab, ownsKeyboardShortcuts],
+  );
+
+  useKeyboardActionHandler({
+    handlerId: buildWorkspaceKeyboardHandlerId({
+      name: handlerName,
+      serverId: normalizedServerId,
+      workspaceId: normalizedWorkspaceId,
+      paneId,
+    }),
+    actions: ["workspace.tab.menu.open"],
+    enabled: ownsKeyboardShortcuts,
+    priority: 200,
+    handle: handleNewTabKeyboardAction,
+  });
+}
+
 export function WorkspaceDesktopTabsRow(props: WorkspaceDesktopTabsRowProps) {
   const [presentations, setPresentations] = useState(
     () => new Map<string, WorkspaceTabPresentation>(),
@@ -1059,9 +1112,13 @@ function ResolvedWorkspaceDesktopTabsRow({
   const tabsScrollRef = useRef<ScrollView>(null);
   const [exitFocusModeWidth, setExitFocusModeWidth] = useState<number>(0);
   const tabScrollBoundary = useHorizontalScrollBoundary();
-  const [labelMeasurements, setLabelMeasurements] = useState(
-    () => new Map<string, WorkspaceTabLabelMeasurement>(),
-  );
+  const measurementCache = useContext(TabMeasurementCache);
+  const [labelMeasurements, setLabelMeasurements] = useState(() => new Map(measurementCache ?? []));
+  useLayoutEffect(() => {
+    if (!measurementCache) return;
+    measurementCache.clear();
+    for (const [key, value] of labelMeasurements) measurementCache.set(key, value);
+  }, [measurementCache, labelMeasurements]);
   const [trackSnapshot, setTrackSnapshot] = useState<WorkspaceTabTrackSnapshot | null>(null);
 
   const handleTabsContainerLayout = useCallback((event: LayoutChangeEvent) => {
@@ -1246,29 +1303,12 @@ function ResolvedWorkspaceDesktopTabsRow({
 
   const createNewTab = useCallback(() => onCreateNewTab({ paneId }), [onCreateNewTab, paneId]);
 
-  const handleNewTabKeyboardAction = useCallback(
-    (action: KeyboardActionDefinition): boolean => {
-      if (!ownsKeyboardShortcuts) return false;
-      if (action.id === "workspace.tab.menu.open") {
-        createNewTab();
-        return true;
-      }
-      return false;
-    },
-    [createNewTab, ownsKeyboardShortcuts],
-  );
-
-  useKeyboardActionHandler({
-    handlerId: buildWorkspaceKeyboardHandlerId({
-      name: "workspace-new-tab",
-      serverId: normalizedServerId,
-      workspaceId: normalizedWorkspaceId,
-      paneId,
-    }),
-    actions: ["workspace.tab.menu.open"],
-    enabled: ownsKeyboardShortcuts,
-    priority: 200,
-    handle: handleNewTabKeyboardAction,
+  useWorkspaceNewTabKeyboardAction({
+    ownsKeyboardShortcuts,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId,
+    createNewTab,
   });
 
   const rail: WorkspaceTabRailSurface = host === "explorer" ? "sidebar" : "surface";
@@ -1639,15 +1679,15 @@ const styles = StyleSheet.create((theme) => ({
     paddingHorizontal: theme.spacing[1],
   },
   inlineNewTabButton: {
-    width: buttonControlHeight.xs,
-    height: buttonControlHeight.xs,
+    width: CONTROL_HEIGHTS.sm,
+    height: CONTROL_HEIGHTS.sm,
   },
   paneSplitActions: {
     paddingHorizontal: PANE_SPLIT_ACTIONS_HORIZONTAL_PADDING,
     marginRight: PANE_SPLIT_ACTIONS_OUTER_MARGIN,
   },
   tab: {
-    height: buttonControlHeight.xs,
+    height: CONTROL_HEIGHTS.sm,
     paddingHorizontal: TAB_CHIP_HORIZONTAL_PADDING,
     borderRadius: theme.borderRadius.md,
     flexDirection: "row",
diff --git a/packages/app/src/screens/workspace/workspace-draft-agent-config.ts b/packages/app/src/screens/workspace/workspace-draft-agent-config.ts
index cf122ee566..38b97fc159 100644
--- a/packages/app/src/screens/workspace/workspace-draft-agent-config.ts
+++ b/packages/app/src/screens/workspace/workspace-draft-agent-config.ts
@@ -6,7 +6,7 @@ export function buildWorkspaceDraftAgentConfig(input: {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
 }): AgentSessionConfig {
   return {
     provider: input.provider,
@@ -14,6 +14,6 @@ export function buildWorkspaceDraftAgentConfig(input: {
     ...(input.modeId ? { modeId: input.modeId } : {}),
     ...(input.model ? { model: input.model } : {}),
     ...(input.thinkingOptionId ? { thinkingOptionId: input.thinkingOptionId } : {}),
-    ...(input.featureValues ? { featureValues: input.featureValues } : {}),
+    ...(input.providerOptions ? { providerOptions: input.providerOptions } : {}),
   };
 }
diff --git a/packages/app/src/screens/workspace/workspace-header-menu.tsx b/packages/app/src/screens/workspace/workspace-header-menu.tsx
index b8f4739cfb..cca5dd2e10 100644
--- a/packages/app/src/screens/workspace/workspace-header-menu.tsx
+++ b/packages/app/src/screens/workspace/workspace-header-menu.tsx
@@ -1,3 +1,4 @@
+import type { WorkspaceCompactHeaderActions } from "./adaptive-workspace-chrome";
 import React, { useCallback, useMemo } from "react";
 import { View } from "react-native";
 import { useRouter, type Href } from "expo-router";
@@ -206,13 +207,15 @@ function HeaderMenuProfileItem({
 }
 
 export interface WorkspaceHeaderMenuMobileProps extends WorkspaceHeaderWorkspaceActions {
+  pane?: WorkspaceCompactHeaderActions["pane"];
+  onExitFocusMode?: () => void;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
   scripts: UseWorkspaceScriptsMenuPagesInput;
   showCreateBrowserTab: boolean;
   createTerminalDisabled: boolean;
-  onCreateTerminalWithProfile: (profile: TerminalProfile) => void;
-  onCreateBrowser: () => void;
+  onCreateTerminalWithProfile: (profile: TerminalProfile, paneId?: string) => void;
+  onCreateBrowser: (input?: { paneId?: string }) => void;
 }
 
 /**
@@ -231,8 +234,19 @@ export function WorkspaceHeaderMenuMobile({
   createTerminalDisabled,
   onCreateTerminalWithProfile,
   onCreateBrowser,
+  pane,
+  onExitFocusMode,
   ...workspaceActions
 }: WorkspaceHeaderMenuMobileProps) {
+  const paneId = pane?.id;
+  const handleCreateBrowser = useCallback(
+    () => onCreateBrowser({ paneId }),
+    [onCreateBrowser, paneId],
+  );
+  const handleCreateTerminalWithProfile = useCallback(
+    (profile: TerminalProfile) => onCreateTerminalWithProfile(profile, paneId),
+    [onCreateTerminalWithProfile, paneId],
+  );
   const { t } = useTranslation();
   const router = useRouter();
   const triggerStyle = useIconButtonChromeStyle({ size: "large" });
@@ -278,6 +292,30 @@ export function WorkspaceHeaderMenuMobile({
         pages={pages}
         sheetTitle={t("workspace.header.actions.workspaceActions")}
       >
+        {onExitFocusMode ? (
+          <DropdownMenuItem onSelect={onExitFocusMode}>
+            {t("workspace.tabs.actions.exitFocusMode")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.splitRight ? (
+          <DropdownMenuItem onSelect={pane.splitRight}>
+            {t("workspace.tabs.actions.splitRight")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.splitDown ? (
+          <DropdownMenuItem onSelect={pane.splitDown}>
+            {t("workspace.tabs.actions.splitDown")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.toggleMaximized ? (
+          <DropdownMenuItem onSelect={pane.toggleMaximized}>
+            {t(
+              pane.maximized
+                ? "workspace.tabs.actions.restorePane"
+                : "workspace.tabs.actions.maximizePane",
+            )}
+          </DropdownMenuItem>
+        ) : null}
         {scriptsMenu.trigger}
         {pluginMenu.rows}
         {pluginMenu.rows.length > 0 ? <DropdownMenuSeparator /> : null}
@@ -285,7 +323,7 @@ export function WorkspaceHeaderMenuMobile({
           <DropdownMenuItem
             testID="workspace-header-new-browser"
             leading={MENU_NEW_BROWSER_ICON}
-            onSelect={onCreateBrowser}
+            onSelect={handleCreateBrowser}
           >
             {t("workspace.header.actions.newBrowser")}
           </DropdownMenuItem>
@@ -298,7 +336,7 @@ export function WorkspaceHeaderMenuMobile({
             key={profile.id}
             profile={profile}
             disabled={createTerminalDisabled}
-            onCreateTerminalWithProfile={onCreateTerminalWithProfile}
+            onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
           />
         ))}
         <DropdownMenuSeparator />
diff --git a/packages/app/src/screens/workspace/workspace-route-state-views.tsx b/packages/app/src/screens/workspace/workspace-route-state-views.tsx
index f5f8c5e096..4073ea2dbf 100644
--- a/packages/app/src/screens/workspace/workspace-route-state-views.tsx
+++ b/packages/app/src/screens/workspace/workspace-route-state-views.tsx
@@ -162,7 +162,6 @@ function ArchivedWorkspaceRecovery({
       </View>
       <View style={styles.actions}>
         <Button
-          size="sm"
           variant="default"
           leftIcon={isRestoring ? undefined : RotateCw}
           onPress={onRecover}
@@ -193,10 +192,10 @@ function WorkspaceRecoveryInspectionFailed({
         <Text style={styles.error}>{state.error}</Text>
       </View>
       <View style={styles.actions}>
-        <Button size="sm" variant="default" leftIcon={RotateCw} onPress={onRetry}>
+        <Button variant="default" leftIcon={RotateCw} onPress={onRetry}>
           {t("common.actions.retry")}
         </Button>
-        <Button size="sm" variant="outline" leftIcon={ArrowLeftToLine} onPress={onDismiss}>
+        <Button variant="outline" leftIcon={ArrowLeftToLine} onPress={onDismiss}>
           {t("common.actions.back")}
         </Button>
       </View>
@@ -245,10 +244,10 @@ function WorkspaceUnreachable({
       </View>
       {canRetry ? (
         <View style={styles.actions}>
-          <Button size="sm" variant="default" leftIcon={RotateCw} onPress={onRetry}>
+          <Button variant="default" leftIcon={RotateCw} onPress={onRetry}>
             {t("common.actions.retry")}
           </Button>
-          <Button size="sm" variant="outline" leftIcon={Settings} onPress={onManageHost}>
+          <Button variant="outline" leftIcon={Settings} onPress={onManageHost}>
             {t("workspace.route.manageHost")}
           </Button>
         </View>
@@ -277,7 +276,7 @@ function WorkspaceEmptyState({
         <Text style={styles.description}>{description ?? hostName}</Text>
       </View>
       <View style={styles.actions}>
-        <Button size="sm" variant="default" leftIcon={ArrowLeftToLine} onPress={onDismiss}>
+        <Button variant="default" leftIcon={ArrowLeftToLine} onPress={onDismiss}>
           {t("common.actions.back")}
         </Button>
       </View>
diff --git a/packages/app/src/screens/workspace/workspace-screen.tsx b/packages/app/src/screens/workspace/workspace-screen.tsx
index 508156222b..addd132b59 100644
--- a/packages/app/src/screens/workspace/workspace-screen.tsx
+++ b/packages/app/src/screens/workspace/workspace-screen.tsx
@@ -1,14 +1,21 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderTabs,
+} from "./adaptive-workspace-chrome";
 import { planTimelineTailFetch } from "@/timeline/timeline-sync-plan";
 import { useHostFeature } from "@/runtime/host-features";
 import {
   AssistantFileLinkResolverProvider,
   createInlinePathOpener,
+  type AssistantFileLinkResolverProviderProps,
   type InlinePathTarget,
 } from "@/assistant-file-links";
 import { useFileExplorerActions } from "@/hooks/use-file-explorer-actions";
+import { useWindowLayout, resolveWorkspaceActionPlacement } from "@/window-layout";
 import { revealWorkspaceTab } from "@/workspace-tabs/navigation";
 import type { LayoutChangeEvent } from "react-native";
 import { ExplorerSidebarDock } from "@/screens/workspace/explorer-sidebar";
+import { ForgeShorthandProvider } from "@/git/forge-shorthand";
 import { ExplorerFrame } from "./explorer-sidebar/frame";
 import { WorkspaceTabDragScope } from "@/components/workspace-tab-drag-scope";
 import {
@@ -60,7 +67,7 @@ import { SplitContainer } from "@/components/split-container";
 import { RetainedPanel } from "@/components/retained-panel";
 import { WorkspaceActions } from "@/git/workspace-actions";
 import { WorkspaceOpenInEditorButton } from "@/workspace/open-in-editor/button";
-import { WorkspaceScriptsButton } from "@/screens/workspace/scripts";
+import { WorkspaceScriptsButton, useWorkspaceScriptActions } from "@/screens/workspace/scripts";
 import { ImportSessionSheet } from "@/components/import-session-sheet";
 import { useNavigateToImportedAgent } from "@/hooks/use-import-session";
 import { useToast } from "@/contexts/toast-context";
@@ -130,6 +137,7 @@ import { useWorkspace } from "@/stores/session-store-hooks";
 import type { CheckoutStatusPayload } from "@/git/use-status-query";
 import { confirmDialog } from "@/utils/confirm-dialog";
 import { useArchiveAgent } from "@/hooks/use-archive-agent";
+import { useWorkspaceArchiveUndoRunning } from "@/workspace/archive-undo";
 import { useStableEvent } from "@/hooks/use-stable-event";
 import { removeResidentBrowserWebview } from "@/desktop/browser/resident-webviews";
 import { createWorkspaceBrowser, useBrowserStore } from "@/desktop/browser/store";
@@ -145,6 +153,7 @@ import {
 } from "@/screens/workspace/use-workspace-tab-rename";
 import {
   WorkspaceDesktopTabsRow,
+  useWorkspaceNewTabKeyboardAction,
   type WorkspaceDesktopTabRowItem,
 } from "@/screens/workspace/workspace-desktop-tabs-row";
 import { useDesktopBrowserNewTabRequests } from "@/desktop/browser/new-tab-requests";
@@ -155,7 +164,11 @@ import {
   WorkspaceExplorerSidebarToggle,
   WorkspaceHeaderExplorerToggle,
 } from "@/screens/workspace/workspace-explorer-toggle";
-import { useHasWindowChromeObstruction } from "@/utils/desktop-window";
+import {
+  useHasWindowChromeObstruction,
+  WindowChromeRegion,
+  WindowChromeSafeArea,
+} from "@/utils/desktop-window";
 import {
   resolveWorkspaceHeaderRenderState,
   type WorkspaceHeaderCheckoutState,
@@ -371,9 +384,9 @@ const MobileMountedTabSlot = memo(function MobileMountedTabSlot({
     [buildPaneContentModel, paneId, tabDescriptor],
   );
   const handleTouch = useCallback(() => {
-    if (!isPaneFocused && paneId) onFocusPane(paneId);
+    if (paneId) onFocusPane(paneId);
     return false;
-  }, [isPaneFocused, onFocusPane, paneId]);
+  }, [onFocusPane, paneId]);
 
   return (
     <RenderProfile id={`MobileMountedTabSlot:${tabDescriptor.kind}:${tabDescriptor.tabId}`}>
@@ -500,6 +513,7 @@ function WorkspaceHeaderTitleBar({
   onCopyBranchName,
   onOpenSetupTab,
 }: WorkspaceHeaderTitleBarProps) {
+  const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   return (
     <View style={styles.headerTitleContainer}>
       {isLoading ? (
@@ -516,18 +530,20 @@ function WorkspaceHeaderTitleBar({
           />
         </View>
       )}
-      <View style={styles.compactHeaderMenuCluster}>
-        <WorkspaceHeaderMenuDesktop
-          currentBranchName={currentBranchName}
-          showWorkspaceSetup={showWorkspaceSetup}
-          importAgentDisabled={importAgentDisabled}
-          copyPathDisabled={copyPathDisabled}
-          onOpenImportSheet={onOpenImportSheet}
-          onCopyWorkspacePath={onCopyWorkspacePath}
-          onCopyBranchName={onCopyBranchName}
-          onOpenSetupTab={onOpenSetupTab}
-        />
-      </View>
+      {actionsInBar ? null : (
+        <View style={styles.compactHeaderMenuCluster}>
+          <WorkspaceHeaderMenuDesktop
+            currentBranchName={currentBranchName}
+            showWorkspaceSetup={showWorkspaceSetup}
+            importAgentDisabled={importAgentDisabled}
+            copyPathDisabled={copyPathDisabled}
+            onOpenImportSheet={onOpenImportSheet}
+            onCopyWorkspacePath={onCopyWorkspacePath}
+            onCopyBranchName={onCopyBranchName}
+            onOpenSetupTab={onOpenSetupTab}
+          />
+        </View>
+      )}
     </View>
   );
 }
@@ -859,8 +875,12 @@ function WorkspaceDocumentTitleEffectSlot({
   );
 }
 
+/**
+ * The header floats over a conversation's timeline. A draft and the agent it creates share one
+ * timeline, so their surfaces match and the timeline does not move when the tab retargets.
+ */
 function floatsHeaderOverContent(activeTab: WorkspaceTabDescriptor | null): boolean {
-  return supportsStreamTopOverlay && activeTab?.kind === "agent";
+  return supportsStreamTopOverlay && (activeTab?.kind === "agent" || activeTab?.kind === "draft");
 }
 
 /** A fullscreen composer covers the compact header; the column lays out without it. */
@@ -1013,6 +1033,23 @@ function useLastMainPane(input: {
   return lastMainPaneRef;
 }
 
+/** The docked explorer beside the center column takes the top-right window-chrome corner. */
+function DesktopCenterColumnChrome({
+  explorerOpen,
+  focusModeEnabled,
+  children,
+}: {
+  explorerOpen: boolean;
+  focusModeEnabled: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <WindowChromeRegion corners={explorerOpen && !focusModeEnabled ? "top-left" : "both"}>
+      <View style={styles.centerColumn}>{children}</View>
+    </WindowChromeRegion>
+  );
+}
+
 function WorkspaceScreenContent({
   serverId,
   workspaceId,
@@ -1020,8 +1057,11 @@ function WorkspaceScreenContent({
 }: WorkspaceScreenContentProps) {
   const { t } = useTranslation();
   const _insets = useSafeAreaInsets();
+  const workspaceActionsInBar =
+    resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   const toast = useToast();
   const isMobile = useIsCompactFormFactor();
+  const workspacePanelActive = usePanelStore((state) => state.mobilePanel.target === "agent");
   const canRenderDesktopPaneSplits = supportsDesktopPaneSplits();
   const layoutMode = useWorkspaceLayoutStore((state) => state.layoutMode);
   const hasMacTrafficLights = useHasWindowChromeObstruction("top-left");
@@ -1211,6 +1251,13 @@ function WorkspaceScreenContent({
     onTerminalCreateQueued: handleTerminalCreateQueued,
     onTerminalCreateFailed: handleTerminalCreateFailed,
   });
+  const scriptActions = useWorkspaceScriptActions({
+    client,
+    serverId: normalizedServerId,
+    workspaceId: normalizedWorkspaceId,
+    scripts: workspaceScripts,
+    onScriptTerminalStarted: handleScriptTerminalStarted,
+  });
   const { archiveAgent } = useArchiveAgent();
 
   const { checkoutQuery, isCheckoutStatusLoading } = useWorkspaceCheckoutStatus({
@@ -1224,6 +1271,11 @@ function WorkspaceScreenContent({
   const hasHydratedAgents = useSessionStore(
     (state) => state.sessions[normalizedServerId]?.hasHydratedAgents ?? false,
   );
+  // An undo puts the row back before the host restores its agents. Their tabs stay until it settles.
+  const isArchiveUndoRunning = useWorkspaceArchiveUndoRunning({
+    serverId: normalizedServerId,
+    workspaceId: normalizedWorkspaceId,
+  });
   const workspaceRouteState = useResolvedWorkspaceRouteState({
     serverId: normalizedServerId,
     workspace: workspaceDescriptor,
@@ -1524,7 +1576,7 @@ function WorkspaceScreenContent({
       persistenceKey,
       buildWorkspaceTabSnapshot({
         agentVisibility: workspaceAgentVisibility,
-        agentsHydrated: hasHydratedAgents,
+        agentsHydrated: hasHydratedAgents && !isArchiveUndoRunning,
         terminalsHydrated: terminalsQuery.isSuccess,
         knownTerminalIds,
         standaloneTerminalIds,
@@ -1535,6 +1587,7 @@ function WorkspaceScreenContent({
     );
   }, [
     hasHydratedAgents,
+    isArchiveUndoRunning,
     hasHydratedWorkspaceLayoutStore,
     pendingTerminalCreateInput,
     createTerminalMutation.isPending,
@@ -1792,8 +1845,8 @@ function WorkspaceScreenContent({
   });
 
   const handleCreateTerminalWithProfile = useCallback(
-    (profile: TerminalProfile) => {
-      createTerminal({ profile, destination: { kind: "open" } });
+    (profile: TerminalProfile, paneId?: string) => {
+      createTerminal({ profile, destination: { kind: "open", paneId } });
     },
     [createTerminal],
   );
@@ -3192,11 +3245,9 @@ function WorkspaceScreenContent({
         <PluginHeaderButtons serverId={normalizedServerId} workspaceId={normalizedWorkspaceId} />
         {workspaceDescriptor && workspaceDescriptor.scripts.length > 0 ? (
           <WorkspaceScriptsButton
-            serverId={normalizedServerId}
-            workspaceId={normalizedWorkspaceId}
+            actions={scriptActions}
             scripts={workspaceDescriptor.scripts}
             liveTerminalIds={liveTerminalIds}
-            onScriptTerminalStarted={handleScriptTerminalStarted}
             onViewTerminal={handleViewScriptTerminal}
             onOpenUrlInBrowserTab={handleOpenUrlInBrowserTab}
             hideLabels
@@ -3214,15 +3265,17 @@ function WorkspaceScreenContent({
         {workspaceDirectory ? (
           <>
             <WorkspaceActions serverId={normalizedServerId} cwd={workspaceDirectory} />
-            <WorkspaceHeaderExplorerToggle
-              owner={explorerToggleOwner}
-              onPress={handleToggleExplorerSidebar}
-              label={explorerSidebarToggleLabel}
-              tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
-              tooltipKeys={EXPLORER_TOGGLE_KEYS}
-              style={styles.compactHeaderActionButton}
-              accessibilityState={explorerSidebarToggleAccessibilityState}
-            />
+            {workspaceActionsInBar ? null : (
+              <WorkspaceHeaderExplorerToggle
+                owner={explorerToggleOwner}
+                onPress={handleToggleExplorerSidebar}
+                label={explorerSidebarToggleLabel}
+                tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
+                tooltipKeys={EXPLORER_TOGGLE_KEYS}
+                style={styles.compactHeaderActionButton}
+                accessibilityState={explorerSidebarToggleAccessibilityState}
+              />
+            )}
           </>
         ) : null}
       </View>
@@ -3234,13 +3287,14 @@ function WorkspaceScreenContent({
       workspaceDirectory,
       activeFileLocation,
       liveTerminalIds,
-      handleScriptTerminalStarted,
+      scriptActions,
       handleViewScriptTerminal,
       handleOpenUrlInBrowserTab,
       handleToggleExplorerSidebar,
       explorerSidebarToggleLabel,
       explorerSidebarToggleAccessibilityState,
       explorerToggleOwner,
+      workspaceActionsInBar,
       t,
     ],
   );
@@ -3346,28 +3400,76 @@ function WorkspaceScreenContent({
   );
   const compactHeaderScripts = useMemo(
     () => ({
-      serverId: normalizedServerId,
-      workspaceId: normalizedWorkspaceId,
+      actions: scriptActions,
       scripts: workspaceScripts,
       liveTerminalIds,
-      onScriptTerminalStarted: handleScriptTerminalStarted,
       onViewTerminal: handleViewScriptTerminal,
       onOpenUrlInBrowserTab: handleOpenUrlInBrowserTab,
     }),
     [
-      normalizedServerId,
-      normalizedWorkspaceId,
       workspaceScripts,
       liveTerminalIds,
-      handleScriptTerminalStarted,
+      scriptActions,
       handleViewScriptTerminal,
       handleOpenUrlInBrowserTab,
     ],
   );
-  const compactWorkspaceHeader = useMemo(
-    () =>
-      isMobile ? (
+  const renderWorkspaceTabSwitcher = useCallback(
+    ({
+      tabs: headerTabs,
+      activeTabKey: headerActiveTabKey,
+      actions,
+    }: WorkspaceCompactHeaderTabs) => {
+      return (
+        <MobileWorkspaceTabSwitcher
+          paneId={actions.pane?.id}
+          tabs={headerTabs}
+          activeTabKey={headerActiveTabKey}
+          normalizedServerId={normalizedServerId}
+          normalizedWorkspaceId={normalizedWorkspaceId}
+          onSelectSwitcherTab={handleSelectSwitcherTab}
+          createTerminalDisabled={createTerminalDisabled}
+          onCreateDraftTab={handleCreateDraftTab}
+          onCreateTerminal={handleCreateTerminal}
+          onCopyResumeCommand={handleCopyResumeCommand}
+          onCopyAgentId={handleCopyAgentId}
+          onCopyTerminalId={handleCopyTerminalId}
+          onCopyFilePath={handleCopyFilePath}
+          onReloadAgent={handleReloadAgent}
+          onRenameTab={handleRenameTab}
+          onCloseTab={handleCloseTabById}
+          onCloseTabsAbove={actions.closeAbove}
+          onCloseTabsBelow={actions.closeBelow}
+          onCloseOtherTabs={actions.closeOthers}
+        />
+      );
+    },
+    [
+      normalizedServerId,
+      normalizedWorkspaceId,
+      handleSelectSwitcherTab,
+      createTerminalDisabled,
+      handleCreateDraftTab,
+      handleCreateTerminal,
+      handleCopyResumeCommand,
+      handleCopyAgentId,
+      handleCopyTerminalId,
+      handleCopyFilePath,
+      handleReloadAgent,
+      handleRenameTab,
+      handleCloseTabById,
+    ],
+  );
+  // Without a pane's tabs (above a split) the header carries workspace controls only: split panes
+  // keep their tab rails.
+  const renderCompactWorkspaceHeader = useCallback(
+    (paneTabs: WorkspaceCompactHeaderTabs | null, actionsOnly = false) => {
+      const tabSwitcher = paneTabs ? renderWorkspaceTabSwitcher(paneTabs) : null;
+      return (
         <CompactWorkspaceHeader
+          headerVariant={actionsOnly ? "full" : "compact"}
+          actionsActive={isRouteFocused && (!isMobile || workspacePanelActive)}
+          tabSwitcher={tabSwitcher}
           isLoading={isWorkspaceHeaderLoading}
           title={workspaceHeaderTitle}
           subtitle={workspaceHeaderSubtitle}
@@ -3377,27 +3479,9 @@ function WorkspaceScreenContent({
           explorerToggleLabel={explorerSidebarToggleLabel}
           explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
         >
-          <MobileWorkspaceTabSwitcher
-            tabs={tabs}
-            activeTabKey={activeTabKey}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            onSelectSwitcherTab={handleSelectSwitcherTab}
-            createTerminalDisabled={createTerminalDisabled}
-            onCreateDraftTab={handleCreateDraftTab}
-            onCreateTerminal={handleCreateTerminal}
-            onCopyResumeCommand={handleCopyResumeCommand}
-            onCopyAgentId={handleCopyAgentId}
-            onCopyTerminalId={handleCopyTerminalId}
-            onCopyFilePath={handleCopyFilePath}
-            onReloadAgent={handleReloadAgent}
-            onRenameTab={handleRenameTab}
-            onCloseTab={handleCloseTabById}
-            onCloseTabsAbove={handleCloseTabsToLeft}
-            onCloseTabsBelow={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-          />
           <WorkspaceHeaderMenuMobile
+            pane={paneTabs?.actions.pane}
+            onExitFocusMode={isFocusModeEnabled ? toggleFocusMode : undefined}
             normalizedServerId={normalizedServerId}
             normalizedWorkspaceId={normalizedWorkspaceId}
             scripts={compactHeaderScripts}
@@ -3415,35 +3499,26 @@ function WorkspaceScreenContent({
             onOpenSetupTab={handleOpenSetupTab}
           />
         </CompactWorkspaceHeader>
-      ) : null,
+      );
+    },
     [
-      activeTabKey,
+      renderWorkspaceTabSwitcher,
+      isFocusModeEnabled,
+      toggleFocusMode,
       canOpenImportSheet,
       compactHeaderScripts,
       createTerminalDisabled,
       currentBranchName,
       explorerSidebarToggleAccessibilityState,
       explorerSidebarToggleLabel,
-      handleCloseOtherTabs,
-      handleCloseTabById,
-      handleCloseTabsToLeft,
-      handleCloseTabsToRight,
-      handleCopyAgentId,
       handleCopyBranchName,
-      handleCopyFilePath,
-      handleCopyResumeCommand,
-      handleCopyTerminalId,
       handleCopyWorkspacePath,
       handleCreateBrowserTab,
-      handleCreateDraftTab,
-      handleCreateTerminal,
       handleCreateTerminalWithProfile,
       handleOpenSetupTab,
-      handleReloadAgent,
-      handleRenameTab,
-      handleSelectSwitcherTab,
       handleToggleExplorerSidebar,
       isMobile,
+      isRouteFocused,
       isWorkspaceHeaderLoading,
       isWorkspaceHeaderSubtitleDistinct,
       normalizedServerId,
@@ -3451,12 +3526,28 @@ function WorkspaceScreenContent({
       openImportSheet,
       showCreateBrowserTab,
       showWorkspaceSetup,
-      tabs,
       workspaceDirectory,
       workspaceHeaderSubtitle,
       workspaceHeaderTitle,
+      workspacePanelActive,
     ],
   );
+  const workspaceCompactHeaderTabs = {
+    tabs,
+    activeTabKey,
+    actions: {
+      closeAbove: handleCloseTabsToLeft,
+      closeBelow: handleCloseTabsToRight,
+      closeOthers: handleCloseOtherTabs,
+    },
+  };
+  const compactWorkspaceHeader = renderCompactWorkspaceHeader(workspaceCompactHeaderTabs);
+  // SplitContainer reserves the corner around its own compact headers; this is the column's.
+  const centerColumnCompactHeader = useMemo(
+    () => <WindowChromeSafeArea placement="inline">{compactWorkspaceHeader}</WindowChromeSafeArea>,
+    [compactWorkspaceHeader],
+  );
+  const fullWorkspaceActions = renderCompactWorkspaceHeader(workspaceCompactHeaderTabs, true);
   const desktopSplitContent = useMemo(() => {
     if (!canRenderDesktopPaneSplits || !workspaceLayout || !persistenceKey) {
       return null;
@@ -3465,6 +3556,7 @@ function WorkspaceScreenContent({
       <SplitContainer
         layout={workspaceLayout}
         renderMainHeader={renderWorkspaceScreenHeader}
+        renderCompactHeader={renderCompactWorkspaceHeader}
         focusModeEnabled={desktopFocusModeEnabled}
         onExitFocusMode={toggleFocusMode}
         workspaceKey={persistenceKey}
@@ -3501,6 +3593,7 @@ function WorkspaceScreenContent({
     canRenderDesktopPaneSplits,
     workspaceLayout,
     renderWorkspaceScreenHeader,
+    renderCompactWorkspaceHeader,
     persistenceKey,
     desktopFocusModeEnabled,
     toggleFocusMode,
@@ -3539,6 +3632,22 @@ function WorkspaceScreenContent({
     [uiTabs, sheets],
   );
   const workspacePanelKey = `${normalizedServerId}:${normalizedWorkspaceId}`;
+  const createFallbackTab = useCallback(
+    () => handleCreateNewTab({ paneId: focusedPaneIdOrUndefined }),
+    [handleCreateNewTab, focusedPaneIdOrUndefined],
+  );
+  const ownsFallbackKeyboardShortcuts = useMemo(
+    () => shouldRenderDesktopPaneFallback && isRouteFocused,
+    [shouldRenderDesktopPaneFallback, isRouteFocused],
+  );
+  useWorkspaceNewTabKeyboardAction({
+    handlerName: "workspace-chrome-new-tab",
+    ownsKeyboardShortcuts: ownsFallbackKeyboardShortcuts,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId: focusedPaneIdOrUndefined,
+    createNewTab: createFallbackTab,
+  });
   const compactHeaderLayout = resolveCompactHeaderLayout({
     header: compactWorkspaceHeader,
     activeTab: activeTabDescriptor,
@@ -3561,41 +3670,49 @@ function WorkspaceScreenContent({
       <SheetTabs onCloseTab={handleCloseTabById} />
     </View>
   ) : (
-    <View style={styles.centerColumn}>
-      {rendersDesktopSplitContent ? null : renderWorkspaceScreenHeader()}
-
-      {shouldRenderDesktopPaneFallback ? (
-        <NewTabLauncherProvider value={newTabLauncher}>
-          <WorkspaceDesktopTabsRow
-            paneId={focusedPaneIdOrUndefined}
-            isFocused={isRouteFocused}
-            tabs={desktopTabRowItems}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            setHoveredCloseTabKey={setHoveredCloseTabKey}
-            onNavigateTab={navigateToTabId}
-            onCloseTab={handleCloseTabById}
-            onCopyResumeCommand={handleCopyResumeCommand}
-            onCopyAgentId={handleCopyAgentId}
-            onCopyTerminalId={handleCopyTerminalId}
-            onCopyFilePath={handleCopyFilePath}
-            onReloadAgent={handleReloadAgent}
-            onRenameTab={handleRenameTab}
-            onCloseTabsToLeft={handleCloseTabsToLeft}
-            onCloseTabsToRight={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-            onCreateNewTab={handleCreateNewTab}
-            onReorderTabs={handleReorderTabsInFocusedPane}
-            focusModeEnabled={desktopFocusModeEnabled}
-            onExitFocusMode={toggleFocusMode}
-          />
-        </NewTabLauncherProvider>
-      ) : null}
+    <DesktopCenterColumnChrome
+      explorerOpen={isExplorerSidebarShowing}
+      focusModeEnabled={desktopFocusModeEnabled}
+    >
+      {rendersDesktopSplitContent ? null : (
+        <AdaptiveWorkspaceChrome compactHeader={centerColumnCompactHeader}>
+          {fullWorkspaceActions}
+          {renderWorkspaceScreenHeader()}
 
+          {shouldRenderDesktopPaneFallback ? (
+            <NewTabLauncherProvider value={newTabLauncher}>
+              <WorkspaceDesktopTabsRow
+                paneId={focusedPaneIdOrUndefined}
+                ownsKeyboardShortcuts={false}
+                isFocused={isRouteFocused}
+                tabs={desktopTabRowItems}
+                normalizedServerId={normalizedServerId}
+                normalizedWorkspaceId={normalizedWorkspaceId}
+                setHoveredCloseTabKey={setHoveredCloseTabKey}
+                onNavigateTab={navigateToTabId}
+                onCloseTab={handleCloseTabById}
+                onCopyResumeCommand={handleCopyResumeCommand}
+                onCopyAgentId={handleCopyAgentId}
+                onCopyTerminalId={handleCopyTerminalId}
+                onCopyFilePath={handleCopyFilePath}
+                onReloadAgent={handleReloadAgent}
+                onRenameTab={handleRenameTab}
+                onCloseTabsToLeft={handleCloseTabsToLeft}
+                onCloseTabsToRight={handleCloseTabsToRight}
+                onCloseOtherTabs={handleCloseOtherTabs}
+                onCreateNewTab={handleCreateNewTab}
+                onReorderTabs={handleReorderTabsInFocusedPane}
+                focusModeEnabled={desktopFocusModeEnabled}
+                onExitFocusMode={toggleFocusMode}
+              />
+            </NewTabLauncherProvider>
+          ) : null}
+        </AdaptiveWorkspaceChrome>
+      )}
       <View style={styles.centerContent}>
         <View style={styles.content}>{desktopContent}</View>
       </View>
-    </View>
+    </DesktopCenterColumnChrome>
   );
 
   const [workspaceViewportWidth, setWorkspaceViewportWidth] = useState(0);
@@ -3614,6 +3731,7 @@ function WorkspaceScreenContent({
         normalizedServerId={normalizedServerId}
         normalizedWorkspaceId={normalizedWorkspaceId}
         isWorkspaceFocused={isRouteFocused}
+        paneFocusSuspended={paneFocusSuspended}
         closingTabIds={closingTabIds}
         hoveredCloseTabKey={hoveredCloseTabKey}
         setHoveredCloseTabKey={setHoveredCloseTabKey}
@@ -3655,6 +3773,7 @@ function WorkspaceScreenContent({
     normalizedServerId,
     normalizedWorkspaceId,
     isRouteFocused,
+    paneFocusSuspended,
     isExplorerSidebarShowing,
     closingTabIds,
     hoveredCloseTabKey,
@@ -3783,7 +3902,8 @@ function WorkspaceScreenContent({
       workspaceKey={persistenceKey}
       sheetPaneHost={sheetPaneHost}
     >
-      <AssistantFileLinkResolverProvider
+      <WorkspaceMarkdownLinks
+        workspace={workspaceDescriptor}
         client={client}
         serverId={normalizedServerId}
         workspaceRoot={workspaceDirectory ?? undefined}
@@ -3791,11 +3911,26 @@ function WorkspaceScreenContent({
         toast={toast}
       >
         {renderedWorkspaceScreen}
-      </AssistantFileLinkResolverProvider>
+      </WorkspaceMarkdownLinks>
     </WorkspaceContentProviders>
   );
 }
 
+/** File links and forge references for every Markdown surface in the workspace. */
+function WorkspaceMarkdownLinks({
+  workspace,
+  children,
+  ...fileLinks
+}: AssistantFileLinkResolverProviderProps & { workspace: WorkspaceDescriptor | null | undefined }) {
+  return (
+    <AssistantFileLinkResolverProvider {...fileLinks}>
+      <ForgeShorthandProvider forge={workspace?.forge} remoteUrl={workspace?.gitRuntime?.remoteUrl}>
+        {children}
+      </ForgeShorthandProvider>
+    </AssistantFileLinkResolverProvider>
+  );
+}
+
 const styles = StyleSheet.create((theme) => ({
   container: {
     flex: 1,
diff --git a/packages/app/src/screens/workspace/workspace-tab-layout.test.ts b/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
index 7c7b98cee0..9b428bc0bc 100644
--- a/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
+++ b/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
@@ -1,3 +1,4 @@
+import { buildDesktopFrameStyle } from "@/components/ui/combobox-frame-style";
 import {
   WorkspaceHeaderExplorerToggle,
   WorkspaceExplorerSidebarToggle,
@@ -7,6 +8,8 @@ import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
 import { resolveWorkspaceTabChipBackdrop } from "@/screens/workspace/workspace-tab-chip-backdrop";
 import { darkPureBlackTheme, darkTheme, lightTheme } from "@/styles/theme";
 import {
+  workspaceTabSwitcherPopoverLayout,
+  selectWorkspaceChrome,
   computeWorkspaceTabLayout,
   retainWorkspaceTabMeasuredWidth,
 } from "@/screens/workspace/workspace-tab-layout";
@@ -256,3 +259,37 @@ describe("resolveWorkspaceTabChipBackdrop", () => {
     ).toBe("surface0");
   });
 });
+
+import { shouldUseCompactWorkspaceHeader } from "./workspace-tab-layout";
+it.each([
+  [349, true],
+  [499, true],
+  [500, false],
+  [800, false],
+])("workspace width %s selects compact=%s", (width, compact) => {
+  expect(shouldUseCompactWorkspaceHeader(width)).toBe(compact);
+});
+
+describe("desktop pane chrome", () => {
+  it("replaces the pane header and rail together at the pane width boundary", () => {
+    const full = ["workspace header", "pane tab rail"];
+    expect(selectWorkspaceChrome({ width: 440, compact: "pane dropdown", full })).toBe(
+      "pane dropdown",
+    );
+    expect(selectWorkspaceChrome({ width: 500, compact: "pane dropdown", full })).toBe(full);
+    expect(selectWorkspaceChrome({ width: null, compact: "pane dropdown", full })).toBe(full);
+  });
+});
+
+it("gives the tab switcher a readable popover width independent of its 16pt count badge", () => {
+  const frame = buildDesktopFrameStyle({
+    desktopMinWidth: workspaceTabSwitcherPopoverLayout.desktopMinWidth,
+    desktopLockWidth: false,
+    referenceWidth: 16,
+    desktopFixedHeight: undefined,
+    desktopPositionStyle: {},
+    shouldHideDesktopContent: false,
+    availableHeight: 600,
+  }) as Array<{ minWidth?: number }>;
+  expect(frame[0].minWidth).toBeGreaterThanOrEqual(320);
+});
diff --git a/packages/app/src/screens/workspace/workspace-tab-layout.ts b/packages/app/src/screens/workspace/workspace-tab-layout.ts
index cb89d9c54c..2a9ec47837 100644
--- a/packages/app/src/screens/workspace/workspace-tab-layout.ts
+++ b/packages/app/src/screens/workspace/workspace-tab-layout.ts
@@ -1,3 +1,9 @@
+import { COMPACT_CONTENT_WIDTH } from "@/constants/layout";
+
+export function shouldUseCompactWorkspaceHeader(width: number): boolean {
+  return width < COMPACT_CONTENT_WIDTH;
+}
+
 export type WorkspaceTabCloseButtonPolicy = "all" | "none";
 
 export interface WorkspaceTabLayoutMetrics {
@@ -120,3 +126,16 @@ export function computeWorkspaceTabLayout(
     requiresHorizontalScrollFallback,
   };
 }
+
+export function selectWorkspaceChrome<Compact, Full>(input: {
+  width: number | null;
+  compact: Compact;
+  full: Full;
+}): Compact | Full {
+  const compact = input.width !== null && shouldUseCompactWorkspaceHeader(input.width);
+  return compact ? input.compact : input.full;
+}
+
+// A count badge is only 16pt wide. Native popovers need a content width floor
+// because their scrolling tab list does not contribute an intrinsic width.
+export const workspaceTabSwitcherPopoverLayout = { desktopMinWidth: 320 } as const;
diff --git a/packages/app/src/stores/draft-store/index.ts b/packages/app/src/stores/draft-store/index.ts
index 9836d3dfec..c0085bba82 100644
--- a/packages/app/src/stores/draft-store/index.ts
+++ b/packages/app/src/stores/draft-store/index.ts
@@ -36,6 +36,9 @@ import {
 } from "./migration";
 import { createDraftPersistStorage } from "./persistence";
 import { createValidatedPersistStorage } from "@/storage/validated-persist-storage";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import { applyMetadataPatch } from "@/composer/draft/metadata";
+import { hasDraftContent } from "@/composer/draft/input-draft-core";
 
 export type { DraftInput, DraftLifecycleState } from "./state";
 
@@ -43,12 +46,25 @@ interface DraftStoreActions {
   getDraftInput: (draftKey: string) => DraftInput | undefined;
   hydrateDraftInput: (input: { draftKey: string }) => Promise<DraftInput | undefined>;
   saveDraftInput: (input: { draftKey: string; draft: DraftInput }) => void;
+  /** Saves what `update` makes of the current input; an emptied input abandons the draft. */
+  updateDraftInput: (input: {
+    draftKey: string;
+    update: (current: DraftInput) => DraftInput;
+  }) => void;
   editDraftText: (input: { draftKey: string; text: string }) => void;
+  /**
+   * Sets the text on behalf of something other than the input, which then shows it. Use
+   * `editDraftText` for the input's own edits.
+   */
+  replaceDraftText: (input: { draftKey: string; text: string }) => void;
   markDraftLifecycle: (input: { draftKey: string; lifecycle: DraftLifecycleState }) => void;
   clearDraftInput: (input: {
     draftKey: string;
     lifecycle?: Exclude<DraftLifecycleState, "active">;
   }) => void;
+  /** Plugin metadata the draft will create its agent with; see `composer/draft/metadata`. */
+  patchDraftMetadata: (input: { draftKey: string; patch: Record<string, JsonValue> }) => void;
+  clearDraftMetadata: (input: { draftKey: string }) => void;
   attachWorkspaceFile: (input: {
     draftKey: string;
     attachment: WorkspaceFileComposerAttachment;
@@ -60,6 +76,13 @@ interface DraftStoreActions {
 
 interface DraftStoreRuntimeState {
   attachmentFocusRequestByDraftKey: Record<string, number>;
+  /** Counts `replaceDraftText`, so a mounted input knows to show text it did not type. */
+  textReplacementRequestByDraftKey: Record<string, number>;
+  /**
+   * Kept beside the prompt so a composer that remounts finds it. Not persisted, and not cleared
+   * with an emptied prompt: a plugin's choice outlives the text until the draft is sent.
+   */
+  metadataByDraftKey: Record<string, Record<string, JsonValue>>;
 }
 
 type DraftStore = DraftStoreState & DraftStoreRuntimeState & DraftStoreActions;
@@ -256,6 +279,8 @@ export const useDraftStore = create<DraftStore>()(
       drafts: {},
       createModalDraft: null,
       attachmentFocusRequestByDraftKey: {},
+      textReplacementRequestByDraftKey: {},
+      metadataByDraftKey: {},
 
       getDraftInput: (draftKey) => {
         const record = get().drafts[draftKey];
@@ -318,6 +343,12 @@ export const useDraftStore = create<DraftStore>()(
         scheduleAttachmentGc();
       },
 
+      updateDraftInput: ({ draftKey, update }) => {
+        const next = update(get().getDraftInput(draftKey) ?? { text: "", attachments: [] });
+        if (hasDraftContent(next)) get().saveDraftInput({ draftKey, draft: next });
+        else get().clearDraftInput({ draftKey, lifecycle: "abandoned" });
+      },
+
       editDraftText: ({ draftKey, text }) => {
         set((state) => {
           const previous = state.drafts[draftKey];
@@ -326,6 +357,16 @@ export const useDraftStore = create<DraftStore>()(
         });
       },
 
+      replaceDraftText: ({ draftKey, text }) => {
+        get().editDraftText({ draftKey, text });
+        set((state) => ({
+          textReplacementRequestByDraftKey: {
+            ...state.textReplacementRequestByDraftKey,
+            [draftKey]: (state.textReplacementRequestByDraftKey[draftKey] ?? 0) + 1,
+          },
+        }));
+      },
+
       markDraftLifecycle: ({ draftKey, lifecycle }) => {
         set((state) => {
           const existing = state.drafts[draftKey];
@@ -374,6 +415,25 @@ export const useDraftStore = create<DraftStore>()(
         scheduleAttachmentGc();
       },
 
+      patchDraftMetadata: ({ draftKey, patch }) => {
+        set((state) => {
+          const next = applyMetadataPatch(state.metadataByDraftKey[draftKey] ?? {}, patch);
+          const { [draftKey]: _previous, ...others } = state.metadataByDraftKey;
+          return {
+            metadataByDraftKey:
+              Object.keys(next).length > 0 ? { ...others, [draftKey]: next } : others,
+          };
+        });
+      },
+
+      clearDraftMetadata: ({ draftKey }) => {
+        set((state) => {
+          if (!(draftKey in state.metadataByDraftKey)) return state;
+          const { [draftKey]: _removed, ...others } = state.metadataByDraftKey;
+          return { metadataByDraftKey: others };
+        });
+      },
+
       attachWorkspaceFile: async ({ draftKey, attachment }) => {
         await get().hydrateDraftInput({ draftKey });
         set((state) => {
diff --git a/packages/app/src/stores/draft-store/metadata.test.ts b/packages/app/src/stores/draft-store/metadata.test.ts
new file mode 100644
index 0000000000..7f2f7a52d6
--- /dev/null
+++ b/packages/app/src/stores/draft-store/metadata.test.ts
@@ -0,0 +1,35 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { useDraftStore } from "./index";
+
+const draftKey = "draft:metadata";
+
+describe("a draft's plugin metadata", () => {
+  beforeEach(() => {
+    useDraftStore.setState({ drafts: {}, metadataByDraftKey: {} });
+  });
+
+  it("is there when the draft's composer mounts again", () => {
+    const store = useDraftStore.getState();
+    store.editDraftText({ draftKey, text: "review this" });
+    store.patchDraftMetadata({ draftKey, patch: { "plugin.review": true, "plugin.tag": "a" } });
+    store.patchDraftMetadata({ draftKey, patch: { "plugin.tag": null } });
+
+    // A remount reads the store again; nothing from the unmounted composer is kept.
+    const remounted = useDraftStore.getState();
+    expect(remounted.getDraftInput(draftKey)?.text).toBe("review this");
+    expect(remounted.metadataByDraftKey[draftKey]).toEqual({ "plugin.review": true });
+  });
+
+  it("is dropped with the prompt once the draft is sent, and not before", () => {
+    const store = useDraftStore.getState();
+    store.patchDraftMetadata({ draftKey, patch: { "plugin.review": true } });
+
+    store.clearDraftInput({ draftKey, lifecycle: "abandoned" });
+    expect(useDraftStore.getState().metadataByDraftKey[draftKey]).toEqual({
+      "plugin.review": true,
+    });
+
+    store.clearDraftMetadata({ draftKey });
+    expect(useDraftStore.getState().metadataByDraftKey[draftKey]).toBeUndefined();
+  });
+});
diff --git a/packages/app/src/stores/navigation-active-workspace-store/index.ts b/packages/app/src/stores/navigation-active-workspace-store/index.ts
index 16f3a23f0b..2b6fbff11f 100644
--- a/packages/app/src/stores/navigation-active-workspace-store/index.ts
+++ b/packages/app/src/stores/navigation-active-workspace-store/index.ts
@@ -37,14 +37,11 @@ const lastWorkspaceSelectionStore = createLastWorkspaceSelectionStore(
 function navigateDeps(): NavigateToWorkspaceDeps {
   return {
     revealTab: revealWorkspaceTab,
-    revealWorkspace: () => {
-      if (useWorkspaceLayoutStore.getState().layoutMode === "compact") {
-        usePanelStore.getState().showMobileAgent();
-      }
+    revealWorkspace: (workspaceKey) => {
+      useWorkspaceLayoutStore.getState().focusWorkspace(workspaceKey);
+      usePanelStore.getState().showMobileAgent();
     },
     getSessionWorkspaces: (serverId) => useSessionStore.getState().sessions[serverId]?.workspaces,
-    getSessionAgents: (serverId) =>
-      useSessionStore.getState().sessions[serverId]?.agents.values() ?? [],
     isWorkspaceLayoutHydrated: () => useWorkspaceLayoutStore.persist.hasHydrated(),
     deferOpenTab: (input) => useWorkspaceLayoutStore.getState().deferOpenTab(input),
     openTab: (input) => useWorkspaceLayoutStore.getState().openTab(input),
diff --git a/packages/app/src/stores/navigation-active-workspace-store/navigation.test.ts b/packages/app/src/stores/navigation-active-workspace-store/navigation.test.ts
index a3bb69821a..5dbc292524 100644
--- a/packages/app/src/stores/navigation-active-workspace-store/navigation.test.ts
+++ b/packages/app/src/stores/navigation-active-workspace-store/navigation.test.ts
@@ -9,7 +9,7 @@ import {
   type NavigateToLastWorkspaceDeps,
   type NavigateToWorkspaceDeps,
 } from "./navigation";
-import type { Agent, WorkspaceDescriptor } from "@/stores/session-store";
+import type { WorkspaceDescriptor } from "@/stores/session-store";
 
 interface RecordedTab {
   workspaceKey: string;
@@ -35,7 +35,6 @@ function createFakeDeps(overrides: Partial<NavigateToWorkspaceDeps> = {}) {
       return null;
     },
     getSessionWorkspaces: () => null,
-    getSessionAgents: () => [] as Agent[],
     isWorkspaceLayoutHydrated: () => true,
     openTab: ({ workspaceKey, target, pin = false }) => {
       openedTabs.push({ workspaceKey, target, pin });
@@ -105,49 +104,27 @@ describe("workspace navigation", () => {
     expect(remembered).toEqual([{ serverId: "server-1", workspaceId: "workspace-a" }]);
   });
 
-  it("focuses the attention agent's tab when a workspace has one", () => {
+  it("reveals the workspace without choosing a different tab", () => {
     const workspace = {
       id: "workspace-a",
       workspaceDirectory: "/repo/workspace-a",
     } as WorkspaceDescriptor;
-    const agent = {
-      id: "agent-1",
-      cwd: "/repo/workspace-a",
-      workspaceId: "workspace-a",
-      requiresAttention: true,
-      attentionReason: "permission",
-    } as unknown as Agent;
     const { deps, openedTabs } = createFakeDeps({
       getSessionWorkspaces: () => new Map([[workspace.id, workspace]]),
-      getSessionAgents: () => [agent],
     });
 
     navigateToWorkspace({ serverId: "server-1", workspaceId: "workspace-a" }, deps);
 
-    expect(openedTabs).toEqual([
-      {
-        workspaceKey: "server-1:workspace-a",
-        target: { kind: "agent", agentId: "agent-1" },
-        pin: false,
-      },
-    ]);
+    expect(openedTabs).toEqual([]);
   });
 
-  it("keeps an explicit tab authoritative over an attention agent", () => {
+  it("opens an explicitly requested tab", () => {
     const workspace = {
       id: "workspace-a",
       workspaceDirectory: "/repo/workspace-a",
     } as WorkspaceDescriptor;
-    const agent = {
-      id: "agent-1",
-      cwd: "/repo/workspace-a",
-      workspaceId: "workspace-a",
-      requiresAttention: true,
-      attentionReason: "permission",
-    } as unknown as Agent;
     const { deps, openedTabs } = createFakeDeps({
       getSessionWorkspaces: () => new Map([[workspace.id, workspace]]),
-      getSessionAgents: () => [agent],
     });
 
     navigateToWorkspace(
@@ -168,6 +145,22 @@ describe("workspace navigation", () => {
     ]);
   });
 
+  it("carries a request for a tab through a deferred open", () => {
+    const { deps, deferredTabs } = createFakeDeps({ getSessionWorkspaces: () => new Map() });
+
+    navigateToWorkspace(
+      {
+        serverId: "server-1",
+        workspaceId: "workspace-a",
+        target: { kind: "agent", agentId: "agent-1" },
+        asTab: true,
+      },
+      deps,
+    );
+
+    expect(deferredTabs[0]).toMatchObject({ asTab: true });
+  });
+
   it("defers an agent tab until a missing workspace is recovered", () => {
     const { deps, navigations, openedTabs, deferredTabs } = createFakeDeps({
       getSessionWorkspaces: () => new Map(),
diff --git a/packages/app/src/stores/navigation-active-workspace-store/navigation.ts b/packages/app/src/stores/navigation-active-workspace-store/navigation.ts
index d856a9bb36..bbc55701d6 100644
--- a/packages/app/src/stores/navigation-active-workspace-store/navigation.ts
+++ b/packages/app/src/stores/navigation-active-workspace-store/navigation.ts
@@ -1,14 +1,10 @@
-import type { Agent, WorkspaceDescriptor } from "@/stores/session-store";
-import { pickAttentionAgent } from "@/utils/agent-attention";
+import type { WorkspaceDescriptor } from "@/stores/session-store";
 import {
   buildHostWorkspaceRoute,
   decodeWorkspaceIdFromPathSegment,
   parseHostWorkspaceRouteFromPathname,
 } from "@/utils/host-routes";
-import {
-  normalizeWorkspaceOpaqueId,
-  resolveWorkspaceMapKeyByIdentity,
-} from "@/utils/workspace-identity";
+import { resolveWorkspaceMapKeyByIdentity } from "@/utils/workspace-identity";
 import type { ActiveWorkspaceSelection } from "@/stores/last-workspace-selection";
 import type { WorkspaceTabTarget } from "@/workspace-tabs/model";
 import { prepareWorkspaceTab, type PrepareWorkspaceTabDeps } from "@/utils/prepare-workspace-tab";
@@ -29,17 +25,17 @@ export interface NavigateToWorkspaceInput {
   target?: WorkspaceTabTarget;
   pin?: boolean;
   placement?: WorkspaceTabPlacement;
+  asTab?: boolean;
 }
 
 export interface NavigateToWorkspaceDeps extends PrepareWorkspaceTabDeps {
   getSessionWorkspaces: (serverId: string) => Map<string, WorkspaceDescriptor> | null | undefined;
-  getSessionAgents: (serverId: string) => Iterable<Agent>;
   isWorkspaceLayoutHydrated: () => boolean;
   deferOpenTab: (input: OpenWorkspaceTabInput) => null;
   rememberLastWorkspace: (selection: ActiveWorkspaceSelection) => void;
   navigateToRoute: (route: string) => void;
   revealTab: (workspaceKey: string, tabId: string | null) => void;
-  revealWorkspace: () => void;
+  revealWorkspace: (workspaceKey: string) => void;
 }
 
 export interface NavigateToLastWorkspaceDeps extends NavigateToWorkspaceDeps {
@@ -104,21 +100,7 @@ export function navigateToWorkspace(
   if (input.target) {
     prepareWorkspaceTab({ ...input, target: input.target }, { openTab });
   } else {
-    const workspaceAgents = resolvedWorkspaceId
-      ? Array.from(deps.getSessionAgents(input.serverId)).filter(
-          (agent) => normalizeWorkspaceOpaqueId(agent.workspaceId) === resolvedWorkspaceId,
-        )
-      : [];
-    const attentionAgentId = pickAttentionAgent(workspaceAgents);
-    if (attentionAgentId && resolvedWorkspaceId) {
-      openTab({
-        workspaceKey: `${input.serverId}:${resolvedWorkspaceId}`,
-        target: { kind: "agent", agentId: attentionAgentId },
-        intent: "reveal",
-      });
-    } else {
-      deps.revealWorkspace();
-    }
+    deps.revealWorkspace(`${input.serverId}:${resolvedWorkspaceId ?? input.workspaceId}`);
   }
 
   const route = buildHostWorkspaceRoute(input.serverId, input.workspaceId);
diff --git a/packages/app/src/stores/panel-store/index.ts b/packages/app/src/stores/panel-store/index.ts
index 8af964f181..660f2d1b62 100644
--- a/packages/app/src/stores/panel-store/index.ts
+++ b/packages/app/src/stores/panel-store/index.ts
@@ -5,6 +5,7 @@ import {
   clampTreeRailWidth,
   clampSidebarWidth,
   DEFAULT_TREE_RAIL_WIDTH,
+  dropOverlayAgentList,
   DEFAULT_SIDEBAR_WIDTH,
   MAX_TREE_RAIL_WIDTH,
   MAX_SIDEBAR_WIDTH,
@@ -15,9 +16,11 @@ import {
   selectIsAgentListOpen,
   selectIsCompactFileExplorerOpen,
   setMobilePanelTarget,
+  reconcileMobilePanel,
   type DesktopSidebarState,
   type MobilePanelView,
   type MobilePanelSelection,
+  type PanelLayout,
   type PanelLayoutInput,
   type SortOption,
 } from "./state";
@@ -25,8 +28,10 @@ import { isWeb } from "@/constants/platform";
 import { createValidatedPersistStorage } from "@/storage/validated-persist-storage";
 export type {
   DesktopSidebarState,
+  LeftSidebarPresentation,
   MobilePanelView,
   MobilePanelSelection,
+  PanelLayout,
   PanelLayoutInput,
   SortOption,
 } from "./state";
@@ -80,6 +85,7 @@ export interface PanelState {
   openAgentListForLayout: (input: PanelLayoutInput) => void;
   closeAgentListForLayout: (input: PanelLayoutInput) => void;
   toggleAgentListForLayout: (input: PanelLayoutInput) => void;
+  applyPanelLayout: (layout: PanelLayout) => void;
 
   // File explorer settings actions
   setExpandedPathsForWorkspace: (workspaceKey: string, paths: ExpandedPathsUpdate) => void;
@@ -102,6 +108,13 @@ function setMobilePanelTargetPatch(
   return mobilePanel === state.mobilePanel ? state : { mobilePanel };
 }
 
+function dockAgentListPatch(state: PanelState): Pick<PanelState, "desktop" | "mobilePanel"> {
+  return {
+    desktop: { ...state.desktop, agentListOpen: true },
+    mobilePanel: dropOverlayAgentList(state.mobilePanel),
+  };
+}
+
 export const usePanelStore = create<PanelState>()(
   persist(
     (set) => ({
@@ -151,12 +164,7 @@ export const usePanelStore = create<PanelState>()(
         ),
 
       openDesktopAgentList: () =>
-        set((state) => {
-          if (state.desktop.agentListOpen) {
-            return state;
-          }
-          return { desktop: { ...state.desktop, agentListOpen: true } };
-        }),
+        set((state) => (state.desktop.agentListOpen ? state : dockAgentListPatch(state))),
 
       closeDesktopAgentList: () =>
         set((state) => {
@@ -167,18 +175,18 @@ export const usePanelStore = create<PanelState>()(
         }),
 
       toggleDesktopAgentList: () =>
-        set((state) => ({
-          desktop: { ...state.desktop, agentListOpen: !state.desktop.agentListOpen },
-        })),
+        set((state) =>
+          state.desktop.agentListOpen
+            ? { desktop: { ...state.desktop, agentListOpen: false } }
+            : dockAgentListPatch(state),
+        ),
 
       openAgentListForLayout: ({ isCompact }) =>
         set((state) => {
           if (isCompact) {
             return setMobilePanelTargetPatch(state, "agent-list");
           }
-          return state.desktop.agentListOpen
-            ? state
-            : { desktop: { ...state.desktop, agentListOpen: true } };
+          return state.desktop.agentListOpen ? state : dockAgentListPatch(state);
         }),
 
       closeAgentListForLayout: ({ isCompact }) =>
@@ -199,9 +207,15 @@ export const usePanelStore = create<PanelState>()(
               state.mobilePanel.target === "agent-list" ? "agent" : "agent-list",
             );
           }
-          return {
-            desktop: { ...state.desktop, agentListOpen: !state.desktop.agentListOpen },
-          };
+          return state.desktop.agentListOpen
+            ? { desktop: { ...state.desktop, agentListOpen: false } }
+            : dockAgentListPatch(state);
+        }),
+
+      applyPanelLayout: (layout) =>
+        set((state) => {
+          const mobilePanel = reconcileMobilePanel(state.mobilePanel, layout);
+          return mobilePanel === state.mobilePanel ? state : { mobilePanel };
         }),
 
       setExpandedPathsForWorkspace: (workspaceKey, paths) =>
diff --git a/packages/app/src/stores/panel-store/state.test.ts b/packages/app/src/stores/panel-store/state.test.ts
index ad52b8a8c4..317d4fd9a8 100644
--- a/packages/app/src/stores/panel-store/state.test.ts
+++ b/packages/app/src/stores/panel-store/state.test.ts
@@ -1,4 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { subscribeMobilePanelSelection } from "@/mobile-panels/selection";
+import { beforeEach, describe, expect, it } from "vitest";
+import { usePanelStore } from ".";
 import {
   DEFAULT_TREE_RAIL_WIDTH,
   migratePanelState,
@@ -122,3 +124,101 @@ it("discards obsolete checkout selection while preserving other panel preference
   expect(state).not.toHaveProperty("explorerTabByCheckout");
   expect(state.sidebarWidth).toBe(400);
 });
+
+describe("panel-store wide navigation overlay", () => {
+  it("subscribes with the current selection and observes future commands until unsubscribe", () => {
+    usePanelStore.getState().showMobileAgent();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "hidden" });
+    const published = usePanelStore.getState().mobilePanel;
+    const received: (typeof published)[] = [];
+    const unsubscribe = subscribeMobilePanelSelection((selection) => received.push(selection));
+    try {
+      expect(received).toEqual([published]);
+      usePanelStore.getState().showMobileAgentList();
+      expect(received).toEqual([published, usePanelStore.getState().mobilePanel]);
+      unsubscribe();
+      const before = [...received];
+      usePanelStore.getState().showMobileAgent();
+      expect(received).toEqual(before);
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  beforeEach(() => {
+    const panels = usePanelStore.getState();
+    panels.showMobileAgent();
+    panels.closeDesktopAgentList();
+  });
+
+  it.each([
+    ["openDesktopAgentList", () => usePanelStore.getState().openDesktopAgentList()],
+    ["toggleDesktopAgentList", () => usePanelStore.getState().toggleDesktopAgentList()],
+    [
+      "openAgentListForLayout",
+      () => usePanelStore.getState().openAgentListForLayout({ isCompact: false }),
+    ],
+    [
+      "toggleAgentListForLayout",
+      () => usePanelStore.getState().toggleAgentListForLayout({ isCompact: false }),
+    ],
+  ])("drops the overlay target when %s docks the sidebar", (_name, dock) => {
+    usePanelStore.getState().showMobileAgentList();
+
+    dock();
+
+    expect(usePanelStore.getState().desktop.agentListOpen).toBe(true);
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+  });
+
+  it("drops the overlay target once the sidebar is no longer presented as an overlay", () => {
+    usePanelStore.getState().showMobileAgentList();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "overlay" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent-list");
+
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "dock" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+
+    usePanelStore.getState().showMobileAgentList();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "hidden" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+  });
+
+  it.each(["dock", "hidden"] as const)(
+    "invalidates an opening swipe when presentation becomes %s before its target commits",
+    (presentation) => {
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "overlay" });
+      const startedRevision = usePanelStore.getState().mobilePanel.revision;
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: presentation });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+      expect(usePanelStore.getState().mobilePanel.revision).toBeGreaterThan(startedRevision);
+    },
+  );
+
+  it.each(["overlay", "hidden"] as const)(
+    "keeps the compact explorer target when the compact sidebar becomes %s",
+    (leftSidebar) => {
+      usePanelStore.getState().showMobileFileExplorer();
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: true, leftSidebar });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("file-explorer");
+    },
+  );
+
+  it.each(["overlay", "dock", "hidden"] as const)(
+    "drops the compact explorer target when the layout widens with a %s sidebar",
+    (leftSidebar) => {
+      usePanelStore.getState().showMobileFileExplorer();
+      const openedRevision = usePanelStore.getState().mobilePanel.revision;
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+      expect(usePanelStore.getState().mobilePanel.revision).toBeGreaterThan(openedRevision);
+    },
+  );
+});
diff --git a/packages/app/src/stores/panel-store/state.ts b/packages/app/src/stores/panel-store/state.ts
index cbbead4161..a9971fa458 100644
--- a/packages/app/src/stores/panel-store/state.ts
+++ b/packages/app/src/stores/panel-store/state.ts
@@ -26,6 +26,14 @@ export interface PanelLayoutInput {
   isCompact: boolean;
 }
 
+/** How app chrome presents the left sidebar: over the workspace, beside it, or not at all. */
+export type LeftSidebarPresentation = "overlay" | "dock" | "hidden";
+
+/** The panels app chrome presents, which decide the mobile panel targets that can stay selected. */
+export interface PanelLayout extends PanelLayoutInput {
+  leftSidebar: LeftSidebarPresentation;
+}
+
 export interface PanelCoreState {
   mobilePanel: MobilePanelSelection;
   desktop: DesktopSidebarState;
@@ -68,6 +76,35 @@ export function setMobilePanelTarget(
   return { target, revision: selection.revision + 1 };
 }
 
+/**
+ * Only an overlay sidebar shows the `agent-list` target. A docked or hidden sidebar drops it, so
+ * a stale target cannot resurface the overlay on the next collapse. Always invalidate in-flight
+ * gestures, even when an opening swipe has not committed `agent-list` yet.
+ */
+export function dropOverlayAgentList(selection: MobilePanelSelection): MobilePanelSelection {
+  return {
+    target: selection.target === "agent-list" ? "agent" : selection.target,
+    revision: selection.revision + 1,
+  };
+}
+
+/**
+ * Keeps only the targets the layout presents. The `file-explorer` target exists on compact layouts
+ * only; a wide layout docks the Explorer instead, and a stale target there would block the
+ * navigation swipe, which begins only from `agent`.
+ */
+export function reconcileMobilePanel(
+  selection: MobilePanelSelection,
+  layout: PanelLayout,
+): MobilePanelSelection {
+  const sidebarReconciled =
+    layout.leftSidebar === "overlay" ? selection : dropOverlayAgentList(selection);
+  if (!layout.isCompact && sidebarReconciled.target === "file-explorer") {
+    return setMobilePanelTarget(sidebarReconciled, "agent");
+  }
+  return sidebarReconciled;
+}
+
 const ExplorerTabSchema = z.enum(["changes", "files", "pr"]);
 const DesktopSidebarStorageSchema = z.strictObject({
   agentListOpen: z.boolean().optional(),
diff --git a/packages/app/src/stores/session-store-hooks/index.ts b/packages/app/src/stores/session-store-hooks/index.ts
index 3dba13bc80..d6d4a188c1 100644
--- a/packages/app/src/stores/session-store-hooks/index.ts
+++ b/packages/app/src/stores/session-store-hooks/index.ts
@@ -10,6 +10,7 @@ import {
   selectWorkspaceDirectoryServerIds,
   selectHasWorkspaces,
   selectProjectOrder,
+  selectProjectRootPaths,
   selectRecommendedProjectPaths,
   selectWorkspace,
   selectWorkspaceDirectory,
@@ -147,6 +148,14 @@ export function useRecommendedProjectPaths(serverId: string | null): string[] {
   );
 }
 
+export function useProjectRootPaths(serverId: string | null): string[] {
+  return useStoreWithEqualityFn(
+    useSessionStore,
+    (state) => selectProjectRootPaths(state, serverId),
+    workspaceEqualityFns.deep,
+  );
+}
+
 export function useHasWorkspaces(serverId: string | null): boolean {
   return useStoreWithEqualityFn(
     useSessionStore,
diff --git a/packages/app/src/stores/session-store-hooks/selectors.ts b/packages/app/src/stores/session-store-hooks/selectors.ts
index c131fa7a3a..85169b6f4a 100644
--- a/packages/app/src/stores/session-store-hooks/selectors.ts
+++ b/packages/app/src/stores/session-store-hooks/selectors.ts
@@ -307,6 +307,14 @@ export function selectRecommendedProjectPaths(
     .filter((path) => path.length > 0);
 }
 
+export function selectProjectRootPaths(state: SessionsSnapshot, serverId: string | null): string[] {
+  const projects = serverId ? state.sessions[serverId]?.projects : undefined;
+  if (!projects || projects.size === 0) {
+    return EMPTY_WORKSPACE_KEYS;
+  }
+  return Array.from(projects.values(), (project) => project.projectRootPath);
+}
+
 export function selectHasWorkspaces(state: SessionsSnapshot, serverId: string | null): boolean {
   if (!serverId) {
     return false;
diff --git a/packages/app/src/stores/session-store.test.ts b/packages/app/src/stores/session-store.test.ts
index fb38605220..1b9052c4c1 100644
--- a/packages/app/src/stores/session-store.test.ts
+++ b/packages/app/src/stores/session-store.test.ts
@@ -557,6 +557,33 @@ describe("normalizeWorkspaceDescriptor", () => {
     expect(blank.workspaceDirectory).toBe("");
   });
 
+  it("preserves informational workspace parentage", () => {
+    const payload = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "1",
+      projectDisplayName: "Project 1",
+      projectRootPath: "/repo",
+      workspaceDirectory: "/repo",
+      projectKind: "git",
+      workspaceKind: "checkout",
+      name: "main",
+      archivingAt: null,
+      status: "done",
+      statusEnteredAt: null,
+      activityAt: null,
+      diffStat: null,
+      scripts: [],
+    } as WorkspaceDescriptorPayload;
+
+    const workspace = normalizeWorkspaceDescriptor(payload);
+
+    expect(workspace.parentWorkspaceId).toBe("parent");
+    expect(
+      normalizeWorkspaceDescriptor({ ...payload, parentWorkspaceId: undefined }).parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   it("defaults missing scripts to an empty array", () => {
     const payload = {
       id: "1",
diff --git a/packages/app/src/stores/session-store.ts b/packages/app/src/stores/session-store.ts
index 911573762f..625c3d8c2f 100644
--- a/packages/app/src/stores/session-store.ts
+++ b/packages/app/src/stores/session-store.ts
@@ -26,7 +26,9 @@ import type { ComposerAttachment } from "@/attachments/types";
 import type { AgentLifecycleStatus } from "@getpaseo/protocol/agent-lifecycle";
 import type {
   AgentPermissionRequest,
-  AgentFeature,
+  AgentOptionControl,
+  JsonValue,
+  ProviderOptions,
   AgentProvider,
   AgentMode,
   AgentCapabilityFlags,
@@ -54,10 +56,12 @@ import {
   type WorkspaceAgentActivity,
 } from "@/utils/workspace-agent-activity";
 import {
+  resolveTimelineTurnPresentation,
   resolveTurnPresentation,
   TURN_LIVENESS_IDLE,
   type TurnLiveness,
   type TurnPresentation,
+  type UnsettledTurn,
 } from "@/timeline/turn-liveness";
 
 export interface AgentRuntimeInfo {
@@ -74,6 +78,7 @@ export interface Agent {
   id: string;
   provider: AgentProvider;
   status: AgentLifecycleStatus;
+  backgroundWork?: { count: number };
   turn: TurnLiveness;
   createdAt: Date;
   updatedAt: Date;
@@ -85,24 +90,30 @@ export interface Agent {
   pendingPermissions: AgentPermissionRequest[];
   persistence: AgentPersistenceHandle | null;
   runtimeInfo?: AgentRuntimeInfo;
+  usageScopeKey?: string;
   lastUsage?: AgentUsage;
   lastError?: string | null;
   title: string | null;
   cwd: string;
   workspaceId?: string;
   model: string | null;
-  features?: AgentFeature[];
+  options?: ProviderOptions;
+  controls?: AgentOptionControl[];
   thinkingOptionId?: string | null;
   requiresAttention?: boolean;
   attentionReason?: "finished" | "error" | "permission" | null;
   attentionTimestamp?: Date | null;
   archivedAt?: Date | null;
+  /** Background agents stay out of tabs, the subagent track and agent lists. Open them by id. */
+  background?: boolean;
   parentAgentId: string | null;
   labels: Record<string, string>;
+  metadata?: Record<string, JsonValue>;
   projectPlacement?: ProjectPlacementPayload | null;
 }
 
 export interface WorkspaceDescriptor {
+  parentWorkspaceId?: string;
   createdAt: Date | null;
   lastUserMessageAt: Date | null;
   id: string;
@@ -160,6 +171,7 @@ export function normalizeWorkspaceDescriptor(
     projectKind: payload.projectKind,
     workspaceKind: payload.workspaceKind,
     background: payload.background ?? false,
+    parentWorkspaceId: payload.parentWorkspaceId,
     name: payload.name,
     title: payload.title ?? null,
     pinnedAt: payload.pinnedAt ?? null,
@@ -260,6 +272,7 @@ interface ExplorerRequestState {
 }
 
 export interface AgentFileExplorerState {
+  listingGeneration: number;
   directories: Map<string, ExplorerDirectory>;
   isLoading: boolean;
   lastError: string | null;
@@ -364,6 +377,64 @@ export function selectAgentTurnPresentation(
   );
 }
 
+/** Turn state for the chat's own timeline. Every other surface reads the true status above. */
+export function selectAgentTimelineTurnPresentation(
+  session: SessionState | undefined,
+  agentId: string,
+): TurnPresentation {
+  return resolveTimelineTurnPresentation(
+    selectAgentTurnPresentation(session, agentId),
+    session?.agentTimelineUnsettledTurn.get(agentId),
+  );
+}
+
+/** The unsettled turn a chat's messages carry: the one open right now, or the one it holds. */
+export function selectAgentUnsettledTurn(
+  session: SessionState | undefined,
+  agentId: string,
+): UnsettledTurn | undefined {
+  const turn = session?.agents.get(agentId)?.turn ?? session?.agentDetails.get(agentId)?.turn;
+  if (turn?.phase === "open") return { turnId: turn.turnId, startedAt: turn.startedAt };
+  return session?.agentTimelineUnsettledTurn.get(agentId);
+}
+
+function withUnsettledTurn(
+  current: Map<string, UnsettledTurn>,
+  agentId: string,
+  turn: UnsettledTurn,
+): Map<string, UnsettledTurn> {
+  const held = current.get(agentId);
+  // COMPAT(agentTurnIdentity): added in v0.2.6, remove after 2027-01-31 once daemon floor >= v0.2.6.
+  // Hosts without turn ids report null for every turn, so only the start time tells two turns apart.
+  if (held?.turnId === turn.turnId && held?.startedAt?.getTime() === turn.startedAt?.getTime()) {
+    return current;
+  }
+  const next = new Map(current);
+  next.set(agentId, turn);
+  return next;
+}
+
+function withoutUnsettledTurn(
+  current: Map<string, UnsettledTurn>,
+  agentId: string,
+): Map<string, UnsettledTurn> {
+  if (!current.has(agentId)) return current;
+  const next = new Map(current);
+  next.delete(agentId);
+  return next;
+}
+
+// The messages that bring a chat current settle its turn in this same commit.
+function commitUnsettledTurn(
+  current: Map<string, UnsettledTurn>,
+  agentId: string,
+  commit: { synchronized: boolean; unsettledTurn?: UnsettledTurn },
+): Map<string, UnsettledTurn> {
+  if (commit.synchronized) return withoutUnsettledTurn(current, agentId);
+  if (commit.unsettledTurn) return withUnsettledTurn(current, agentId, commit.unsettledTurn);
+  return current;
+}
+
 function latestTasksFromStream(items: readonly StreamItem[]): TodoEntry[] {
   for (let index = items.length - 1; index >= 0; index -= 1) {
     const item = items[index];
@@ -416,6 +487,7 @@ export interface SessionState {
   agentTasks: Map<string, TodoEntry[]>;
   messageSubmissions: Map<string, MessageSubmissionRecord[]>;
   agentTimelineCursor: Map<string, AgentTimelineCursorState>;
+  agentTimelineUnsettledTurn: Map<string, UnsettledTurn>;
   agentTimelineHasOlder: Map<string, boolean>;
   agentTimelineHasNewer: Map<string, boolean>;
   agentTimelineOlderFetchInFlight: Map<string, boolean>;
@@ -559,8 +631,14 @@ interface SessionStoreActions {
       newer: boolean;
       synchronized: boolean;
       acknowledgedClientMessageIds: string[];
+      unsettledTurn?: UnsettledTurn;
     },
   ) => void;
+  setAgentTimelineUnsettledTurn: (
+    serverId: string,
+    agentId: string,
+    turn: UnsettledTurn | null,
+  ) => void;
 
   // Initializing agents
   setInitializingAgents: (
@@ -664,6 +742,7 @@ function createInitialSessionState(
     agentTasks: new Map(),
     messageSubmissions: new Map(),
     agentTimelineCursor: new Map(),
+    agentTimelineUnsettledTurn: new Map(),
     agentTimelineHasOlder: new Map(),
     agentTimelineHasNewer: new Map(),
     agentTimelineOlderFetchInFlight: new Map(),
@@ -1445,6 +1524,11 @@ export const useSessionStore = create<SessionStore>()(
             nextAuthoritative.set(agentId, true);
             nextSyncGeneration.set(agentId, session.historySyncGeneration);
           }
+          const agentTimelineUnsettledTurn = commitUnsettledTurn(
+            session.agentTimelineUnsettledTurn,
+            agentId,
+            state,
+          );
           const tasks = latestTasksFromStream([...state.items, ...state.head]);
           const agentTasks = new Map(session.agentTasks);
           if (tasks.length > 0) agentTasks.set(agentId, tasks);
@@ -1462,6 +1546,7 @@ export const useSessionStore = create<SessionStore>()(
                 agentTimelineCursor: nextCursor,
                 agentTimelineHasOlder: nextHasOlder,
                 agentTimelineHasNewer: nextHasNewer,
+                agentTimelineUnsettledTurn,
                 agentAuthoritativeHistoryApplied: nextAuthoritative,
                 agentHistorySyncGeneration: nextSyncGeneration,
                 messageSubmissions,
@@ -1471,6 +1556,25 @@ export const useSessionStore = create<SessionStore>()(
         });
       },
 
+      setAgentTimelineUnsettledTurn: (serverId, agentId, turn) => {
+        set((prev) => {
+          const session = prev.sessions[serverId];
+          if (!session) return prev;
+          const current = session.agentTimelineUnsettledTurn;
+          const next = turn
+            ? withUnsettledTurn(current, agentId, turn)
+            : withoutUnsettledTurn(current, agentId);
+          if (next === current) return prev;
+          return {
+            ...prev,
+            sessions: {
+              ...prev.sessions,
+              [serverId]: { ...session, agentTimelineUnsettledTurn: next },
+            },
+          };
+        });
+      },
+
       // Initializing agents
       setInitializingAgents: (serverId, state) => {
         set((prev) => {
diff --git a/packages/app/src/stores/workspace-draft-submission-store.ts b/packages/app/src/stores/workspace-draft-submission-store.ts
index 639701d740..4a7d3ceaf3 100644
--- a/packages/app/src/stores/workspace-draft-submission-store.ts
+++ b/packages/app/src/stores/workspace-draft-submission-store.ts
@@ -23,7 +23,7 @@ export interface PendingWorkspaceDraftSubmission {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
+  providerOptions?: Record<string, unknown>;
   allowEmptyText?: boolean;
 }
 
diff --git a/packages/app/src/stores/workspace-layout-persistence.test.ts b/packages/app/src/stores/workspace-layout-persistence.test.ts
index 3398199ae4..47c4ab81da 100644
--- a/packages/app/src/stores/workspace-layout-persistence.test.ts
+++ b/packages/app/src/stores/workspace-layout-persistence.test.ts
@@ -95,6 +95,53 @@ it("keeps the saved layout when the shell publishes its layout mode before hydra
   );
 });
 
+it("keeps every saved layout when a draft tab's setup carries a nested provider option", async () => {
+  const values = new Map<string, string>();
+  const storage: StateStorage = {
+    getItem: (name) => values.get(name) ?? null,
+    setItem: (name, value) => {
+      values.set(name, value);
+    },
+    removeItem: (name) => {
+      values.delete(name);
+    },
+  };
+  const store = createWorkspaceLayoutStore(undefined, storage);
+  await store.persist.rehydrate();
+  store.getState().openTab({
+    workspaceKey: "server:kept",
+    target: { kind: "agent", agentId: "agent-1" },
+    intent: "reveal",
+  });
+  store.getState().openTab({
+    workspaceKey: "server:forked",
+    target: {
+      kind: "draft",
+      draftId: "draft-1",
+      setup: {
+        provider: "codex",
+        cwd: "/repo",
+        modeId: null,
+        model: null,
+        thinkingOptionId: null,
+        providerOptions: { sandbox_workspace_write: { network_access: true }, max_turns: 3 },
+      },
+    },
+    intent: "reveal",
+  });
+
+  const restored = createWorkspaceLayoutStore(undefined, storage);
+  await restored.persist.rehydrate();
+
+  expect(Object.keys(restored.getState().layoutByWorkspace).sort()).toEqual([
+    "server:forked",
+    "server:kept",
+  ]);
+  expect(JSON.stringify(restored.getState().layoutByWorkspace["server:forked"])).toContain(
+    "network_access",
+  );
+});
+
 it.each([1, 2])(
   "restores the agent pane after parked focus in storage version %i",
   async (version) => {
diff --git a/packages/app/src/stores/workspace-layout-storage.ts b/packages/app/src/stores/workspace-layout-storage.ts
index c105d40a06..1dfa9e82db 100644
--- a/packages/app/src/stores/workspace-layout-storage.ts
+++ b/packages/app/src/stores/workspace-layout-storage.ts
@@ -1,14 +1,25 @@
 import { z } from "zod";
 import type { SplitNode, WorkspaceLayout } from "./workspace-layout-actions";
 
-const WorkspaceDraftTabSetupStorageSchema = z.strictObject({
-  provider: z.string(),
-  cwd: z.string(),
-  modeId: z.string().nullable(),
-  model: z.string().nullable(),
-  thinkingOptionId: z.string().nullable(),
-  featureValues: z.record(z.string(), z.union([z.boolean(), z.string(), z.null()])),
-});
+// COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01. Layouts saved before
+// the rename stored the same record as `featureValues`.
+function renameLegacyFeatureValues(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || !("featureValues" in value)) return value;
+  const { featureValues, ...rest } = value as { featureValues: unknown } & Record<string, unknown>;
+  return "providerOptions" in rest ? rest : { ...rest, providerOptions: featureValues };
+}
+
+const WorkspaceDraftTabSetupStorageSchema = z.preprocess(
+  renameLegacyFeatureValues,
+  z.strictObject({
+    provider: z.string(),
+    cwd: z.string(),
+    modeId: z.string().nullable(),
+    model: z.string().nullable(),
+    thinkingOptionId: z.string().nullable(),
+    providerOptions: z.record(z.string(), z.json()),
+  }),
+);
 const WorkspaceTabTargetStorageSchema = z.discriminatedUnion("kind", [
   z.strictObject({ kind: z.literal("new_tab") }),
   z.strictObject({
diff --git a/packages/app/src/stores/workspace-layout-store.test.ts b/packages/app/src/stores/workspace-layout-store.test.ts
index 8b478b7d27..6bb930334a 100644
--- a/packages/app/src/stores/workspace-layout-store.test.ts
+++ b/packages/app/src/stores/workspace-layout-store.test.ts
@@ -165,6 +165,8 @@ it("feeds restored layout to timeline sync as a release signal, not a subscripti
   const sync = createViewedTimelineSync({
     replaceDemandedAgentIds: () => undefined,
     prepare: async () => undefined,
+    canCheckFreshness: () => false,
+    applyCurrentTimeline: () => undefined,
     observe: (agentIds) => {
       observed.push(agentIds);
       return { ready: Promise.resolve(), release: async () => undefined };
@@ -174,6 +176,8 @@ it("feeds restored layout to timeline sync as a release signal, not a subscripti
     fetchLatestTail: async () => ({ hasNewer: false, endCursor: null }),
     onCatchUpEnded: () => undefined,
     reportError: () => undefined,
+    onCatchUpOwed: () => undefined,
+    onCatchUpSettled: () => undefined,
   });
   // The edge session-context.tsx owns. Pointing it at subscription instead would resume every
   // agent behind a restored tab on the daemon.
@@ -4551,7 +4555,6 @@ describe("compact workspace sheet", () => {
             title: agent.id,
             cwd: "/repo",
             model: null,
-            features: undefined,
             thinkingOptionId: undefined,
             requiresAttention: false,
             attentionReason: null,
@@ -4566,6 +4569,24 @@ describe("compact workspace sheet", () => {
     );
   }
 
+  it("opens a subagent as a tab when a deferred request asks for one", () => {
+    const store = createCompactStore();
+    seedAgents([
+      { id: "parent", parentAgentId: null, workspaceId: "sheet-ws" },
+      { id: "child", parentAgentId: "parent", workspaceId: "sheet-ws" },
+    ]);
+
+    store.getState().deferOpenTab({
+      workspaceKey,
+      target: { kind: "agent", agentId: "child" },
+      intent: "reveal",
+      asTab: true,
+    });
+    store.getState().consumePendingOpen(workspaceKey);
+
+    expect(topSheet(store)).toBeUndefined();
+    expect(tabKinds(store)).toContain("agent");
+  });
   it("reveals a file in the sheet and leaves the tab strip unchanged", () => {
     const store = createCompactStore();
     const before = tabKinds(store);
@@ -5244,3 +5265,36 @@ describe("pending workspace opens", () => {
     expect(store.getState().pendingOpenByWorkspace).toEqual({});
   });
 });
+
+it("records repeated deliberate focus even when the selected pane and tab do not change", () => {
+  const store = createWorkspaceLayoutStore(workspaceLayoutIds);
+  const workspaceKey = "server:focus";
+  const tabId = store
+    .getState()
+    .openTab({ workspaceKey, target: { kind: "agent", agentId: "agent" }, intent: "reveal" })!;
+  const paneId = store.getState().layoutByWorkspace[workspaceKey]!.focusedPaneId!;
+  for (const focus of [
+    () => store.getState().focusPane(workspaceKey, paneId),
+    () => store.getState().focusTab(workspaceKey, tabId),
+    () => store.getState().selectTabInPane(workspaceKey, paneId, tabId),
+  ]) {
+    focus();
+    const first = store.getState().focusRequest;
+    focus();
+    expect(store.getState().focusRequest).toEqual({ workspaceKey, tabId });
+    expect(store.getState().focusRequest).not.toBe(first);
+  }
+});
+
+it("reentering a workspace restores its suspended pane without choosing another tab", () => {
+  const store = createWorkspaceLayoutStore(workspaceLayoutIds);
+  const workspaceKey = "server:resume";
+  const tabId = store
+    .getState()
+    .openTab({ workspaceKey, target: { kind: "agent", agentId: "agent" }, intent: "reveal" })!;
+  const paneId = store.getState().layoutByWorkspace[workspaceKey]!.focusedPaneId;
+  store.getState().unfocusPane(workspaceKey);
+  store.getState().focusWorkspace(workspaceKey);
+  expect(store.getState().layoutByWorkspace[workspaceKey]!.focusedPaneId).toBe(paneId);
+  expect(store.getState().focusRequest).toEqual({ workspaceKey, tabId });
+});
diff --git a/packages/app/src/stores/workspace-layout-store.ts b/packages/app/src/stores/workspace-layout-store.ts
index 43387bc743..3e0d14ba6b 100644
--- a/packages/app/src/stores/workspace-layout-store.ts
+++ b/packages/app/src/stores/workspace-layout-store.ts
@@ -105,6 +105,8 @@ export interface OpenWorkspaceTabInput {
   /** Keeps an explicitly opened agent visible even when it is archived. */
   pin?: boolean;
   placement?: WorkspaceTabPlacement;
+  /** Opens a tab where a compact layout would otherwise use a sheet. */
+  asTab?: boolean;
   insertionPosition?: WorkspaceTabInsertionPosition;
   parentTabId?: string;
   state?: JsonValue;
@@ -128,6 +130,8 @@ export type WorkspaceTabDestination =
   | { kind: "sheet"; tabId: string };
 
 interface WorkspaceLayoutStore {
+  /** Deliberate focus, including reselecting the current tab. Never persisted. */
+  focusRequest: { workspaceKey: string; tabId: string } | null;
   panelRevisionByWorkspace: Record<string, Record<string, number>>;
   /** Published once by the app shell; callers never pass a form factor to open a tab. */
   layoutMode: WorkspaceLayoutMode;
@@ -210,6 +214,7 @@ interface WorkspaceLayoutStore {
    * (archiving agents, killing terminals) first. No-ops on the last visible pane.
    */
   closePane: (workspaceKey: string, paneId: string) => void;
+  focusWorkspace: (workspaceKey: string) => void;
   focusPane: (workspaceKey: string, paneId: string) => void;
   unfocusPane: (workspaceKey: string) => string | null;
   restorePaneFocus: (workspaceKey: string, token: string) => void;
@@ -1083,6 +1088,7 @@ export function createWorkspaceLayoutStore(
         },
         layoutMode: "split-panes",
         sheetsByWorkspace: {},
+        focusRequest: null,
         layoutByWorkspace: {},
         splitSizesByWorkspace: {},
         explorerSidebarWidthByWorkspace: {},
@@ -1104,7 +1110,7 @@ export function createWorkspaceLayoutStore(
             input.parentTabId,
           );
           const sheetPlacement =
-            input.placement?.mode === "pane"
+            input.placement?.mode === "pane" || input.asTab
               ? null
               : resolveSheetPlacement(
                   get(),
@@ -1135,6 +1141,7 @@ export function createWorkspaceLayoutStore(
                   });
             set((state) => ({
               ...withSheets(state, normalizedWorkspaceKey, next),
+              focusRequest: { workspaceKey: normalizedWorkspaceKey, tabId: sheet.tab.tabId },
               ...advancePanelRevision(
                 state,
                 normalizedWorkspaceKey,
@@ -1198,6 +1205,9 @@ export function createWorkspaceLayoutStore(
           set((state) => ({
             ...withoutFocusRestoration(state, normalizedWorkspaceKey),
             ...advancePanelRevision(state, normalizedWorkspaceKey, result.tabId, normalizedTarget),
+            ...(input.intent === "background"
+              ? {}
+              : { focusRequest: { workspaceKey: normalizedWorkspaceKey, tabId: result.tabId } }),
             // A tab brought to the front dismisses the sheet over it.
             ...(input.intent === "background" ? {} : dismissSheets(state, normalizedWorkspaceKey)),
             hiddenAgentIdsByWorkspace:
@@ -1506,18 +1516,16 @@ export function createWorkspaceLayoutStore(
             } else {
               nextLayout = focusTabInLayout({ layout, tabId: normalizedTabId });
             }
-            if (!nextLayout) {
-              return state;
-            }
+            if (!tabPane) return state;
 
             return {
+              focusRequest: { workspaceKey: normalizedWorkspaceKey, tabId: normalizedTabId },
               ...withoutFocusRestoration(state, normalizedWorkspaceKey),
               // Choosing a tab dismisses the sheets that cover it.
               ...dismissSheets(state, normalizedWorkspaceKey),
-              layoutByWorkspace: {
-                ...state.layoutByWorkspace,
-                [normalizedWorkspaceKey]: nextLayout,
-              },
+              layoutByWorkspace: nextLayout
+                ? { ...state.layoutByWorkspace, [normalizedWorkspaceKey]: nextLayout }
+                : state.layoutByWorkspace,
             };
           });
         },
@@ -1535,13 +1543,15 @@ export function createWorkspaceLayoutStore(
               paneId: normalizedPaneId,
               tabId: normalizedTabId,
             });
-            return nextLayout
+            const pane = findPaneById(layout.root, normalizedPaneId);
+            return pane?.tabIds.includes(normalizedTabId)
               ? {
+                  focusRequest: { workspaceKey: normalizedWorkspaceKey, tabId: normalizedTabId },
                   // Choosing a tab dismisses the sheets that cover it.
                   ...dismissSheets(state, normalizedWorkspaceKey),
                   layoutByWorkspace: {
                     ...state.layoutByWorkspace,
-                    [normalizedWorkspaceKey]: nextLayout,
+                    [normalizedWorkspaceKey]: nextLayout ?? layout,
                   },
                 }
               : state;
@@ -1971,6 +1981,13 @@ export function createWorkspaceLayoutStore(
             };
           });
         },
+        focusWorkspace: (workspaceKey) => {
+          const state = get();
+          const paneId =
+            state.layoutByWorkspace[workspaceKey]?.focusedPaneId ??
+            state.focusRestorationByWorkspace[workspaceKey]?.restorePaneId;
+          if (paneId) state.focusPane(workspaceKey, paneId);
+        },
         focusPane: (workspaceKey, paneId) => {
           const normalizedWorkspaceKey = trimNonEmpty(workspaceKey);
           const normalizedPaneId = trimNonEmpty(paneId);
@@ -1991,16 +2008,17 @@ export function createWorkspaceLayoutStore(
               layout,
               paneId: normalizedPaneId,
             });
-            if (!nextLayout) {
-              return state;
-            }
+            const pane = findPaneById(layout.root, normalizedPaneId);
+            if (!pane) return state;
 
             return {
+              focusRequest: pane.focusedTabId
+                ? { workspaceKey: normalizedWorkspaceKey, tabId: pane.focusedTabId }
+                : null,
               ...withoutFocusRestoration(state, normalizedWorkspaceKey),
-              layoutByWorkspace: {
-                ...state.layoutByWorkspace,
-                [normalizedWorkspaceKey]: nextLayout,
-              },
+              layoutByWorkspace: nextLayout
+                ? { ...state.layoutByWorkspace, [normalizedWorkspaceKey]: nextLayout }
+                : state.layoutByWorkspace,
             };
           });
         },
diff --git a/packages/app/src/stores/workspace-subagents-integration.test.ts b/packages/app/src/stores/workspace-subagents-integration.test.ts
index ff2c8b2f4b..13fe6cfa81 100644
--- a/packages/app/src/stores/workspace-subagents-integration.test.ts
+++ b/packages/app/src/stores/workspace-subagents-integration.test.ts
@@ -63,7 +63,6 @@ const AGENT_DEFAULTS: Agent = {
   cwd: WORKSPACE_DIRECTORY,
   workspaceId: WORKSPACE_ID,
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,
diff --git a/packages/app/src/styles/density.ts b/packages/app/src/styles/density.ts
index d29547ee88..1e66a555c0 100644
--- a/packages/app/src/styles/density.ts
+++ b/packages/app/src/styles/density.ts
@@ -1,33 +1,36 @@
+import {
+  bySizing,
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOUCH_TARGET,
+  type IconSize,
+} from "@/components/ui/control-geometry";
 import { isCompactBreakpoint } from "@/constants/layout";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
+import type { Theme } from "@/styles/theme";
 
 /**
- * Density sizes for surfaces that opt into touch sizing: rows and icons grow on compact
- * layouts and keep their desktop sizes from the `md` breakpoint up. Plain theme tokens stay
- * desktop-sized everywhere, so a surface migrates by swapping its sizes for these.
+ * Density sizes for surfaces that opt into touch sizing: rows and icons take their touch sizes
+ * where controls do (see `resolveControlSizing`) and their pointer sizes elsewhere. Plain theme
+ * tokens stay pointer-sized everywhere, so a surface migrates by swapping its sizes for these.
  *
  * Style values are Unistyles breakpoint values, resolved inside `StyleSheet.create`. Icon sizes
  * are props, so icons take them through `DensityIcon` or a `densityIconProps` mapping.
  */
 
-export type DensityIconSize = keyof typeof ICON_SIZE;
-
-const COMPACT_ICON_SIZE: Record<DensityIconSize, number> = { xs: 14, sm: 18, md: 20, lg: 24 };
-
-// Compact layouts end where `md` begins; see `isCompactBreakpoint`.
-function byLayout<T>(compact: T, desktop: T) {
-  return { xs: compact, md: desktop };
-}
+export type DensityIconSize = IconSize;
 
 export const density = {
   /** A list row such as a sidebar entry. */
-  rowHeight: byLayout(44, 36),
-  /** A row in a tight group, such as the sidebar's navigation rows. */
-  tightRowHeight: byLayout(36, 28),
+  rowHeight: bySizing({ touch: TOUCH_TARGET, pointer: 36 }),
+  /** A row in a tight group, such as the sidebar's navigation rows. Touch-sized it is a full row. */
+  tightRowHeight: bySizing({ touch: TOUCH_TARGET, pointer: 28 }),
   /** A square icon-only button that sits in a row or toolbar. */
-  iconButton: byLayout(44, 28),
-  /** The space between two blocks of rich text, such as Markdown paragraphs, code and images. */
-  blockGap: byLayout(12, 16),
+  iconButton: TOOLBAR_CONTROL_HEIGHT,
+  /**
+   * The space between two blocks of rich text, such as Markdown paragraphs, code and images.
+   * Reading rhythm, not a touch target, so it follows the layout alone.
+   */
+  blockGap: { xs: 12, md: 16 },
 };
 
 /** Resolves a density value for a prop, which Unistyles cannot resolve on its own. */
@@ -37,7 +40,7 @@ export function resolveDensity<T>(rt: { breakpoint?: string }, value: { xs: T; m
 
 /** The width or height of a slot that holds an icon of `size`. */
 export function densityIconBox(size: DensityIconSize) {
-  return byLayout(COMPACT_ICON_SIZE[size], ICON_SIZE[size]);
+  return bySizing(iconSizeFor(size));
 }
 
 export function densityIconSize(rt: { breakpoint?: string }, size: DensityIconSize): number {
diff --git a/packages/app/src/styles/settings.ts b/packages/app/src/styles/settings.ts
index 4f6d377b38..4fa4dcd22d 100644
--- a/packages/app/src/styles/settings.ts
+++ b/packages/app/src/styles/settings.ts
@@ -21,10 +21,6 @@ export const settingsStyles = StyleSheet.create((theme) => ({
     flexDirection: "row",
     gap: theme.spacing[1],
   },
-  sectionHeaderLinkText: {
-    color: theme.colors.foregroundMuted,
-    fontSize: theme.fontSize.sm,
-  },
   card: {
     backgroundColor: theme.colors.surface1,
     borderRadius: theme.borderRadius.lg,
diff --git a/packages/app/src/styles/theme.ts b/packages/app/src/styles/theme.ts
index 977a382c41..9b941543fe 100644
--- a/packages/app/src/styles/theme.ts
+++ b/packages/app/src/styles/theme.ts
@@ -550,7 +550,7 @@ const ghosttyDarkColors = buildDarkSemanticColors({
   foregroundExtraMuted: "#a0a4b2",
   border: "#353a47",
   borderAccent: "#3f4454",
-  accent: "#89b4fa",
+  accent: "#3570e0", // dark enough to carry white text on filled buttons
   accentBright: "#b4d0fc",
   destructive: "#c44a55", // red with slight cool lean against the slate-blue surfaces
   terminalBlack: "#21252d",
@@ -564,8 +564,10 @@ export const SPACING = {
   1.5: 6,
   2: 8,
   3: 12,
+  3.5: 14,
   4: 16,
   6: 24,
+  7: 28,
   8: 32,
   12: 48,
   16: 64,
diff --git a/packages/app/src/subagents/archive-finished.test.ts b/packages/app/src/subagents/archive-finished.test.ts
index 8ad93f990f..62190a2c22 100644
--- a/packages/app/src/subagents/archive-finished.test.ts
+++ b/packages/app/src/subagents/archive-finished.test.ts
@@ -431,3 +431,32 @@ describe("createArchiveFinishedSubagents", () => {
     expect(descriptors.get("running")).toBe(running);
   });
 });
+
+it("excludes live background work and rechecks it before each archive", async () => {
+  const first = deferred<void>();
+  const active = { ...paseo("active"), backgroundWork: { count: 1 } };
+  const current = new Map([
+    ["first", managed("first")],
+    ["later", managed("later")],
+    ["active", managed("active", "idle", { backgroundWork: { count: 1 } })],
+  ]);
+  const calls: string[] = [];
+  const archive = createArchiveFinishedSubagents([paseo("first"), paseo("later"), active], {
+    parentAgentId: "parent",
+    getManagedSubagent: ({ agentId }) => current.get(agentId),
+    archiveManagedSubagent: ({ agentId }) => {
+      calls.push(agentId);
+      return first.promise;
+    },
+    dismissProviderSubagents: () => undefined,
+  });
+  expect(archive.getState().eligibleCount).toBe(2);
+  const operation = archive.archiveFinished();
+  current.set("later", managed("later", "idle", { backgroundWork: { count: 1 } }));
+  first.resolve();
+  expect(await operation).toMatchObject({
+    archivedPaseoIds: ["first"],
+    skippedPaseoIds: ["later"],
+  });
+  expect(calls).toEqual(["first"]);
+});
diff --git a/packages/app/src/subagents/archive-finished.ts b/packages/app/src/subagents/archive-finished.ts
index c79c3af6f9..1ad7a1bacd 100644
--- a/packages/app/src/subagents/archive-finished.ts
+++ b/packages/app/src/subagents/archive-finished.ts
@@ -19,7 +19,10 @@ export interface ArchiveFinishedOutcome {
   failures: Array<{ id: string; error: unknown }>;
 }
 
-export type ManagedSubagentSnapshot = Pick<Agent, "id" | "status" | "parentAgentId" | "archivedAt">;
+export type ManagedSubagentSnapshot = Pick<
+  Agent,
+  "id" | "status" | "parentAgentId" | "archivedAt" | "backgroundWork"
+>;
 
 export interface ArchiveFinishedSubagentsDeps {
   parentAgentId: string;
@@ -36,7 +39,10 @@ export interface ArchiveFinishedSubagents {
 }
 
 export function isFinishedSubagent(row: SubagentRow): boolean {
-  if (row.kind === "paseo") return row.status === "idle" || row.status === "error";
+  if (row.kind === "paseo")
+    return (
+      (row.status === "idle" || row.status === "error") && (row.backgroundWork?.count ?? 0) === 0
+    );
   return row.status === "completed" || row.status === "failed" || row.status === "canceled";
 }
 
@@ -48,6 +54,7 @@ function canArchiveManagedSubagent(
     agent &&
     !agent.archivedAt &&
     agent.parentAgentId === parentAgentId &&
+    (agent.backgroundWork?.count ?? 0) === 0 &&
     (agent.status === "idle" || agent.status === "error"),
   );
 }
diff --git a/packages/app/src/subagents/archive-subagent.test.ts b/packages/app/src/subagents/archive-subagent.test.ts
index 9314961b16..78a9463fea 100644
--- a/packages/app/src/subagents/archive-subagent.test.ts
+++ b/packages/app/src/subagents/archive-subagent.test.ts
@@ -203,3 +203,19 @@ describe("requestArchiveSubagent", () => {
     expect(env.recordedErrors).toEqual([error]);
   });
 });
+
+it("warns before archiving an idle subagent with live background work", async () => {
+  const env = createFakeEnv({
+    initialSubagents: [
+      {
+        id: "child",
+        snapshot: { title: "Review branch", status: "idle", backgroundWork: { count: 1 } },
+      },
+    ],
+  });
+  await requestArchiveSubagent({ serverId: "server-1", subagentId: "child" }, env.deps);
+  expect(env.recordedConfirmInputs[0]).toMatchObject({
+    title: "Archive running subagent?",
+    message: expect.stringContaining("will stop"),
+  });
+});
diff --git a/packages/app/src/subagents/archive-subagent.ts b/packages/app/src/subagents/archive-subagent.ts
index 653dcb1cb2..aead4a41b7 100644
--- a/packages/app/src/subagents/archive-subagent.ts
+++ b/packages/app/src/subagents/archive-subagent.ts
@@ -4,6 +4,7 @@ import type { ConfirmDialogInput } from "@/utils/confirm-dialog";
 export interface ResolveArchiveSubagentDialogInput {
   title: Agent["title"] | null | undefined;
   status: Agent["status"] | null | undefined;
+  backgroundWork?: Agent["backgroundWork"];
 }
 
 function resolveSubagentLabel(title: Agent["title"] | null | undefined): string | null {
@@ -24,7 +25,7 @@ export function resolveArchiveSubagentDialog(
   input: ResolveArchiveSubagentDialogInput,
 ): ConfirmDialogInput {
   const subagentLabel = resolveSubagentLabel(input.title) ?? "this subagent";
-  const isRunning = input.status === "running";
+  const isRunning = input.status === "running" || (input.backgroundWork?.count ?? 0) > 0;
 
   return {
     title: isRunning ? "Archive running subagent?" : "Archive subagent?",
@@ -58,6 +59,7 @@ export async function requestArchiveSubagent(
     resolveArchiveSubagentDialog({
       title: subagent?.title,
       status: subagent?.status,
+      backgroundWork: subagent?.backgroundWork,
     }),
   );
   if (!confirmed) {
diff --git a/packages/app/src/subagents/index.ts b/packages/app/src/subagents/index.ts
index 0b72ccfcf5..cd8ee753fb 100644
--- a/packages/app/src/subagents/index.ts
+++ b/packages/app/src/subagents/index.ts
@@ -10,3 +10,4 @@ export {
   type UseArchiveFinishedSubagentsInput,
 } from "./use-archive-finished";
 export { useSubagentSheetTab } from "./sheet-tab";
+export { deriveSubagentStatusBucket } from "./track-presentation";
diff --git a/packages/app/src/subagents/parent/callout.tsx b/packages/app/src/subagents/parent/callout.tsx
index 7665c0d12a..d1bb31204a 100644
--- a/packages/app/src/subagents/parent/callout.tsx
+++ b/packages/app/src/subagents/parent/callout.tsx
@@ -46,7 +46,6 @@ export function ParentAgentCallout({
           {parent.label ?? t("subagents.parent.parentAgent")}
         </Text>
         <Button
-          size="sm"
           variant="secondary"
           leftIcon={CornerUpLeft}
           onPress={parent.open}
diff --git a/packages/app/src/subagents/provider-store.test.ts b/packages/app/src/subagents/provider-store.test.ts
index 01d6880d5b..a28e9b00fd 100644
--- a/packages/app/src/subagents/provider-store.test.ts
+++ b/packages/app/src/subagents/provider-store.test.ts
@@ -1,7 +1,9 @@
+import { createHistoryStartPagination } from "@/agent-stream/history-start-pagination";
 import { DaemonConnectionError } from "@getpaseo/client/internal/daemon-client";
-import { afterEach, describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 import type { ProviderSubagentDescriptorPayload } from "@getpaseo/protocol/messages";
 import {
+  loadOlderProviderSubagentTimeline,
   observeProviderSubagentTimeline,
   providerSubagentKey,
   refreshProviderSubagents,
@@ -565,6 +567,95 @@ describe("projected child history", () => {
       .getState()
       .replaceTimeline(SERVER_ID, response(value, seqStart, seqEnd, direction));
   }
+  test("older child history completes only after the delayed page is applied", async () => {
+    const tail = { ...response("B", 2, 2), hasOlder: true };
+    useProviderSubagentStore.getState().replaceTimeline(SERVER_ID, tail);
+    let deliver!: (payload: Payload) => void;
+    const client = {
+      fetchProviderSubagentTimeline: () =>
+        new Promise<Payload>((resolve) => {
+          deliver = resolve;
+        }),
+    };
+    let completed = false;
+    const request = loadOlderProviderSubagentTimeline({
+      client,
+      serverId: SERVER_ID,
+      parentAgentId: PARENT_ID,
+      subagentId: SUBAGENT_ID,
+      limit: 100,
+    }).then((result) => {
+      completed = true;
+      return result;
+    });
+    await Promise.resolve();
+    expect(completed).toBe(false);
+    deliver({ ...response("A", 1, 1), direction: "before" });
+    expect(await request).toBe(true);
+    expect(current().cursor?.startSeq).toBe(1);
+  });
+  test("bounds an older child request so a timeout permits another attempt", async () => {
+    vi.useFakeTimers();
+    try {
+      useProviderSubagentStore
+        .getState()
+        .replaceTimeline(SERVER_ID, { ...response("B", 2, 2), hasOlder: true });
+      const timeouts: Array<number | undefined> = [];
+      const client = {
+        fetchProviderSubagentTimeline: (
+          _parent: string,
+          _child: string,
+          options: { timeout?: number },
+        ) => {
+          timeouts.push(options.timeout);
+          return new Promise<Payload>((_resolve, reject) =>
+            setTimeout(() => reject(new Error("timeout")), options.timeout ?? 60_000),
+          );
+        },
+      };
+      let loading = false;
+      const pagination = createHistoryStartPagination({
+        initiallyVisible: true,
+        read: () => ({
+          distanceFromHistoryStart: 0,
+          isUnderfilled: true,
+          hasOlderHistory: true,
+          isLoadingOlderHistory: loading,
+          isReady: true,
+          progressKey: "e:2",
+        }),
+        load: async () => {
+          loading = true;
+          try {
+            return await loadOlderProviderSubagentTimeline({
+              client,
+              serverId: SERVER_ID,
+              parentAgentId: PARENT_ID,
+              subagentId: SUBAGENT_ID,
+              limit: 100,
+            });
+          } catch {
+            return false;
+          } finally {
+            loading = false;
+          }
+        },
+        changed: () => {},
+        scheduleSettle: () => {},
+      });
+      pagination.update();
+      expect(timeouts).toEqual([10_000]);
+      await vi.advanceTimersByTimeAsync(10_000);
+      expect(pagination.state.status).toBe("failed");
+      pagination.rearm();
+      expect(timeouts).toEqual([10_000, 10_000]);
+      expect(pagination.state.status).toBe("loading");
+      pagination.dispose();
+      await vi.advanceTimersByTimeAsync(10_000);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
   test("replaces overlapping fetched text and continues live streaming", () => {
     page("AB", 1, 2);
     stream(3, "C");
diff --git a/packages/app/src/subagents/provider-store.ts b/packages/app/src/subagents/provider-store.ts
index fd44dae8d2..48010aa0be 100644
--- a/packages/app/src/subagents/provider-store.ts
+++ b/packages/app/src/subagents/provider-store.ts
@@ -355,6 +355,35 @@ export const useProviderSubagentStore = create<ProviderSubagentState>((set) => (
 }));
 
 /** Owns child history bootstrap and recovery while a pane observes the child. */
+export async function loadOlderProviderSubagentTimeline({
+  client,
+  serverId,
+  parentAgentId,
+  subagentId,
+  limit,
+}: {
+  client: Pick<DaemonClient, "fetchProviderSubagentTimeline">;
+  serverId: string;
+  parentAgentId: string;
+  subagentId: string;
+  limit: number;
+}): Promise<boolean> {
+  const timeline = useProviderSubagentStore
+    .getState()
+    .timelines.get(providerSubagentKey(serverId, parentAgentId, subagentId));
+  const seq = timeline?.cursor?.startSeq;
+  if (!timeline?.hasOlder || !timeline.epoch || seq == null) return false;
+  const payload = await client.fetchProviderSubagentTimeline(parentAgentId, subagentId, {
+    direction: "before",
+    cursor: { epoch: timeline.epoch, seq },
+    limit,
+    timeout: 10_000,
+  });
+  if (payload.error) return false;
+  useProviderSubagentStore.getState().replaceTimeline(serverId, payload);
+  return true;
+}
+
 export function observeProviderSubagentTimeline({
   client,
   serverId,
diff --git a/packages/app/src/subagents/select.test.ts b/packages/app/src/subagents/select.test.ts
index c9d7ca4096..05d0fe2698 100644
--- a/packages/app/src/subagents/select.test.ts
+++ b/packages/app/src/subagents/select.test.ts
@@ -41,7 +41,6 @@ const AGENT_DEFAULTS: Agent = {
   title: "Agent",
   cwd: "/tmp/project",
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,
@@ -246,6 +245,22 @@ describe("selectSubagentsForParent", () => {
     expect(rows.map((row) => row.id)).toEqual(["child-a"]);
   });
 
+  it("excludes background children from the track", () => {
+    setAgents([
+      makeAgent({ id: "parent-a" }),
+      makeAgent({ id: "child-a", parentAgentId: "parent-a" }),
+      makeAgent({ id: "background-child", parentAgentId: "parent-a", background: true }),
+    ]);
+
+    const rows = selectSubagentsForParent(
+      useSessionStore.getState(),
+      { serverId: SERVER_ID, parentAgentId: "parent-a" },
+      EMPTY_PENDING_ARCHIVE_IDS,
+    );
+
+    expect(rows.map((row) => row.id)).toEqual(["child-a"]);
+  });
+
   it("excludes siblings, unrelated agents, and grandchildren", () => {
     setAgents([
       makeAgent({ id: "parent-a" }),
@@ -338,6 +353,7 @@ describe("selectSubagentsForParent", () => {
         provider: "claude",
         title: "Review child",
         status: "running",
+        backgroundWork: { count: 1 },
         requiresAttention: true,
         createdAt,
         model: "should-not-leak",
@@ -364,6 +380,7 @@ describe("selectSubagentsForParent", () => {
         description: null,
         subtitle: null,
         status: "running",
+        backgroundWork: { count: 1 },
         turn: { phase: "idle", cancellationRequestId: null },
         requiresAttention: true,
         createdAt,
@@ -371,6 +388,7 @@ describe("selectSubagentsForParent", () => {
     ]);
     expect(Object.keys(rows[0] ?? {}).sort()).toEqual([
       "address",
+      "backgroundWork",
       "createdAt",
       "description",
       "id",
diff --git a/packages/app/src/subagents/select.ts b/packages/app/src/subagents/select.ts
index 29f76e34d4..33255e2e4e 100644
--- a/packages/app/src/subagents/select.ts
+++ b/packages/app/src/subagents/select.ts
@@ -18,6 +18,7 @@ export interface PaseoSubagentRow {
   description: null;
   subtitle: null;
   status: Agent["status"];
+  backgroundWork?: Agent["backgroundWork"];
   turn: Agent["turn"];
   requiresAttention: Agent["requiresAttention"];
   createdAt: Agent["createdAt"];
@@ -65,6 +66,7 @@ function toSubagentRow(agent: Agent): SubagentRow {
     description: null,
     subtitle: null,
     status: agent.status,
+    backgroundWork: agent.backgroundWork,
     turn: agent.turn,
     requiresAttention: agent.requiresAttention,
     createdAt: agent.createdAt,
@@ -82,6 +84,7 @@ export function selectSubagentsForParent(
       const parent = getParentAddressFromLabels(agent.labels, serverId);
       if (
         agent.archivedAt ||
+        agent.background ||
         pendingArchiveIds.has(`${serverId}:${agent.id}`) ||
         parent?.serverId !== params.serverId ||
         parent.agentId !== params.parentAgentId
diff --git a/packages/app/src/subagents/sheet-tab.test.tsx b/packages/app/src/subagents/sheet-tab.test.tsx
index e295f7b7c7..c8e0ab7f13 100644
--- a/packages/app/src/subagents/sheet-tab.test.tsx
+++ b/packages/app/src/subagents/sheet-tab.test.tsx
@@ -60,7 +60,6 @@ const AGENT_DEFAULTS: Agent = {
   cwd: "/repo/worktree",
   workspaceId: WORKSPACE_ID,
   model: null,
-  features: undefined,
   thinkingOptionId: undefined,
   requiresAttention: false,
   attentionReason: null,
diff --git a/packages/app/src/subagents/track-presentation.test.ts b/packages/app/src/subagents/track-presentation.test.ts
index 0397795541..7f1ae379df 100644
--- a/packages/app/src/subagents/track-presentation.test.ts
+++ b/packages/app/src/subagents/track-presentation.test.ts
@@ -26,6 +26,7 @@ function row(
         ? { phase: "open", turnId: null, startedAt: null, cancellationRequestId: null }
         : { phase: "idle", cancellationRequestId: null }),
     requiresAttention: overrides.requiresAttention ?? false,
+    backgroundWork: overrides.backgroundWork,
     createdAt: overrides.createdAt ?? new Date("2026-04-20T00:00:00.000Z"),
   };
 }
@@ -193,6 +194,22 @@ describe("buildSubagentRowPresentationData", () => {
     );
   });
 
+  it("shows a child with background work as running after its foreground turn ends", () => {
+    expect(
+      buildSubagentRowPresentationData(
+        row({ id: "a", status: "idle", backgroundWork: { count: 1 } }),
+      ).statusBucket,
+    ).toBe("running");
+  });
+
+  it("keeps a failed child marked failed while it has background work", () => {
+    expect(
+      buildSubagentRowPresentationData(
+        row({ id: "a", status: "error", backgroundWork: { count: 1 } }),
+      ).statusBucket,
+    ).toBe("failed");
+  });
+
   it("maps an idle row to the done status bucket so callers render the static provider icon", () => {
     expect(buildSubagentRowPresentationData(row({ id: "a", status: "idle" })).statusBucket).toBe(
       "done",
diff --git a/packages/app/src/subagents/track-presentation.ts b/packages/app/src/subagents/track-presentation.ts
index d95082ca39..0bb5ef8dd5 100644
--- a/packages/app/src/subagents/track-presentation.ts
+++ b/packages/app/src/subagents/track-presentation.ts
@@ -1,7 +1,8 @@
 import type { TFunction } from "i18next";
 import type { ComposerTrackPillSegment } from "@/composer/tracks";
 import type { SidebarStateBucket } from "@/utils/sidebar-agent-state";
-import { deriveSidebarStateBucket, STATUS_BUCKET_ORDER } from "@/utils/sidebar-agent-state";
+import type { AgentLifecycleStatus } from "@getpaseo/protocol/agent-lifecycle";
+import { STATUS_BUCKET_ORDER } from "@/utils/sidebar-agent-state";
 import type { SubagentRow } from "./select";
 import { isFinishedSubagent } from "./archive-finished";
 import { providerSubagentLifecycleStatus } from "./provider-store";
@@ -14,6 +15,19 @@ function presentationStatus(row: SubagentRow) {
   return providerSubagentLifecycleStatus(row.status);
 }
 
+/**
+ * A child's mark reports what it is doing, not whether anyone read it: the track is where a
+ * failed child stays visible after the parent's own attention is cleared.
+ */
+export function deriveSubagentStatusBucket(
+  status: AgentLifecycleStatus,
+  backgroundWork?: { count: number } | null,
+): SidebarStateBucket {
+  if (status === "error") return "failed";
+  if (status === "running" || (backgroundWork?.count ?? 0) > 0) return "running";
+  return "done";
+}
+
 export interface SubagentRowPresentationData {
   key: string;
   kind: "agent";
@@ -38,10 +52,10 @@ export function buildSubagentRowPresentationData(row: SubagentRow): SubagentRowP
     label: label ?? "",
     subtitle: subtitle ?? "",
     titleState: label ? "ready" : "loading",
-    statusBucket: deriveSidebarStateBucket({
+    statusBucket: deriveSubagentStatusBucket(
       status,
-      requiresAttention: false,
-    }),
+      row.kind === "paseo" ? row.backgroundWork : undefined,
+    ),
   };
 }
 
diff --git a/packages/app/src/terminal/character-widths.ts b/packages/app/src/terminal/character-widths.ts
new file mode 100644
index 0000000000..efb64da6d8
--- /dev/null
+++ b/packages/app/src/terminal/character-widths.ts
@@ -0,0 +1,9 @@
+/**
+ * The table a terminal buffer measures characters with.
+ *
+ * The daemon answers cursor reports and replays the screen from its own buffer,
+ * so the app measures with the table the host advertises. `graphemes` gives each
+ * emoji cluster one two-column cell. `legacy` is what each renderer used before
+ * hosts advertised grapheme widths. See docs/terminal-rendering.md.
+ */
+export type TerminalCharacterWidths = "graphemes" | "legacy";
diff --git a/packages/app/src/terminal/file-paste/index.test.ts b/packages/app/src/terminal/file-paste/index.test.ts
index 63a1e5e73d..1934b311d2 100644
--- a/packages/app/src/terminal/file-paste/index.test.ts
+++ b/packages/app/src/terminal/file-paste/index.test.ts
@@ -74,7 +74,8 @@ describe("terminal file paste queue", () => {
 
     firstUpload.resolve("/host/uploads/a.png");
     await settle();
-    expect(host.pasted).toEqual(["'/host/uploads/a.png'", "'/host/uploads/b.png'"]);
+    expect(host.pasted).toEqual(["'/host/uploads/a.png' ", "'/host/uploads/b.png' "]);
+    expect(host.pasted.join("")).toBe("'/host/uploads/a.png' '/host/uploads/b.png' ");
     expect(events).toEqual({ uploading: [true, false, true, false], uploaded: 2, failures: [] });
   });
 
@@ -85,7 +86,7 @@ describe("terminal file paste queue", () => {
     queue.add(Promise.resolve(file("shot.png")), host);
     await settle();
 
-    expect(host.pasted).toEqual(['"C:\\Users\\Jo Doe\\.paseo\\uploads\\upload_1\\shot.png"']);
+    expect(host.pasted).toEqual(['"C:\\Users\\Jo Doe\\.paseo\\uploads\\upload_1\\shot.png" ']);
   });
 
   it("uploads under a file name that needs no shell quoting", async () => {
@@ -120,7 +121,7 @@ describe("terminal file paste queue", () => {
 
     expect(events.failures).toEqual(["disk full"]);
     expect(events.uploaded).toBe(1);
-    expect(host.pasted).toEqual(["'/host/uploads/b.png'"]);
+    expect(host.pasted).toEqual(["'/host/uploads/b.png' "]);
   });
 
   it("reports unreadable and oversized files without uploading them", async () => {
@@ -166,7 +167,7 @@ describe("terminal file paste queue", () => {
     queue.add(Promise.resolve(file("next.png")), host);
     await settle();
 
-    expect(host.pasted).toEqual(["'/host/uploads/next.png'"]);
+    expect(host.pasted).toEqual(["'/host/uploads/next.png' "]);
     expect(events.uploading).toEqual([true, false, true, false]);
     expect(queue.cancel()).toBe(false);
   });
diff --git a/packages/app/src/terminal/file-paste/index.ts b/packages/app/src/terminal/file-paste/index.ts
index bc96b17c5d..f793edb643 100644
--- a/packages/app/src/terminal/file-paste/index.ts
+++ b/packages/app/src/terminal/file-paste/index.ts
@@ -75,7 +75,7 @@ export class TerminalFilePasteQueue {
       this.setUploading(true);
       const path = await target.upload({ ...file, fileName: toShellSafeFileName(file.fileName) });
       if (isCurrent()) {
-        target.paste(prepareTerminalPath(path));
+        target.paste(`${prepareTerminalPath(path)} `);
         this.events.onUploaded();
       }
     } catch (error) {
diff --git a/packages/app/src/terminal/find/index.tsx b/packages/app/src/terminal/find/index.tsx
index c8ecab5a04..8b744fbc51 100644
--- a/packages/app/src/terminal/find/index.tsx
+++ b/packages/app/src/terminal/find/index.tsx
@@ -12,7 +12,7 @@ import { StyleSheet } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
 import { PaneFind, findShortcutPlatform, isFindShortcut, type PaneFindHandle } from "@/pane-find";
 import { isWeb } from "@/constants/platform";
-import { hasActiveWebOverlay } from "@/lib/overlay-root";
+import { hasActiveOverlay } from "@/keyboard";
 import { isImeComposingKeyboardEvent } from "@/utils/keyboard-ime";
 import type { TerminalEmulatorHandle } from "@/components/terminal-emulator-contract";
 import type { TerminalFindResult } from "../runtime/terminal-emulator-runtime";
@@ -62,7 +62,7 @@ export const TerminalFind = forwardRef<
   useEffect(() => {
     if (!isWeb || !active) return;
     function onKeyDown(event: KeyboardEvent) {
-      if (event.defaultPrevented || hasActiveWebOverlay() || isImeComposingKeyboardEvent(event))
+      if (event.defaultPrevented || hasActiveOverlay() || isImeComposingKeyboardEvent(event))
         return;
       if (isFindShortcut(event, findShortcutPlatform()) && terminal.current?.find) {
         event.preventDefault();
diff --git a/packages/app/src/terminal/native-renderer/headless-terminal-state.test.ts b/packages/app/src/terminal/native-renderer/headless-terminal-state.test.ts
index c1025568c9..546982906f 100644
--- a/packages/app/src/terminal/native-renderer/headless-terminal-state.test.ts
+++ b/packages/app/src/terminal/native-renderer/headless-terminal-state.test.ts
@@ -159,4 +159,52 @@ describe("native headless terminal state", () => {
       { char: "B", width: 1 },
     ]);
   });
+
+  // Apple Color Emoji and Noto Color Emoji are two cells wide. The native
+  // renderer scales a cluster to its column slot, so a one-column emoji
+  // renders at half size. Each emoji cluster must occupy one wide cell.
+  test.each([
+    ["presentation emoji", "😀"],
+    ["thumbs up", "👍"],
+    ["check mark", "✅"],
+    ["VS16 heart", "❤️"],
+    ["skin-tone modifier", "👋🏽"],
+    ["regional-indicator flag", "🇰🇷"],
+    ["ZWJ family", "👨‍👩‍👧"],
+    ["ZWJ technologist", "👩‍💻"],
+  ])("gives a %s cluster one two-column cell", async (_name, cluster) => {
+    const terminal = createNativeHeadlessTerminal({ rows: 2, cols: 12 });
+
+    await terminal.write(`A${cluster}B`);
+    const [row] = terminal.getBufferWindow({ startRow: 0, rowCount: 1 }).rows;
+
+    expect(row.slice(0, 4).map((cell) => ({ char: cell.char, width: cell.width }))).toEqual([
+      { char: "A", width: 1 },
+      { char: cluster, width: 2 },
+      { char: " ", width: 0 },
+      { char: "B", width: 1 },
+    ]);
+    expect(terminal.getViewportState().cursor.col).toBe(4);
+  });
+
+  // A host without grapheme widths answers cursor reports and replays with
+  // xterm's default table. The native buffer matches it so the cursor lands
+  // where the host put it.
+  test("measures with xterm's default table for hosts without grapheme widths", async () => {
+    const terminal = createNativeHeadlessTerminal({
+      rows: 2,
+      cols: 12,
+      characterWidths: "legacy",
+    });
+
+    await terminal.write("A😀B");
+    const [row] = terminal.getBufferWindow({ startRow: 0, rowCount: 1 }).rows;
+
+    expect(row.slice(0, 3).map((cell) => ({ char: cell.char, width: cell.width }))).toEqual([
+      { char: "A", width: 1 },
+      { char: "😀", width: 1 },
+      { char: "B", width: 1 },
+    ]);
+    expect(terminal.getViewportState().cursor.col).toBe(3);
+  });
 });
diff --git a/packages/app/src/terminal/native-renderer/headless-terminal-state.ts b/packages/app/src/terminal/native-renderer/headless-terminal-state.ts
index 5fd87f7315..4347588861 100644
--- a/packages/app/src/terminal/native-renderer/headless-terminal-state.ts
+++ b/packages/app/src/terminal/native-renderer/headless-terminal-state.ts
@@ -1,3 +1,5 @@
+import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
+import type { TerminalCharacterWidths } from "../character-widths";
 import {
   Terminal as HeadlessTerminal,
   type IBufferCell,
@@ -17,6 +19,8 @@ export interface NativeHeadlessTerminalOptions {
   rows: number;
   cols: number;
   scrollbackLines?: number;
+  /** Defaults to `graphemes`, the table current daemons use. */
+  characterWidths?: TerminalCharacterWidths;
 }
 
 export interface NativeHeadlessTerminal {
@@ -297,6 +301,12 @@ export function createNativeHeadlessTerminal(
     scrollback: options.scrollbackLines ?? 1000,
     allowProposedApi: true,
   });
+  // Grapheme widths give each emoji cluster one two-column cell, the width the
+  // native renderer draws it at. Legacy hosts measure with xterm's default
+  // table, so their cursor reports and replay stay consistent with it.
+  if ((options.characterWidths ?? "graphemes") === "graphemes") {
+    terminal.loadAddon(new UnicodeGraphemesAddon());
+  }
   const decoder = new TextDecoder();
   let coordinateEpoch = 0;
   const coordinateStorage = new Map<object, TerminalCoordinateStorage>();
diff --git a/packages/app/src/terminal/native-renderer/terminal-frame.test.ts b/packages/app/src/terminal/native-renderer/terminal-frame.test.ts
index ea8b7a0cf3..850fd4d183 100644
--- a/packages/app/src/terminal/native-renderer/terminal-frame.test.ts
+++ b/packages/app/src/terminal/native-renderer/terminal-frame.test.ts
@@ -90,18 +90,16 @@ describe("native terminal frame", () => {
   test("keeps combining marks and joiners inside the cell xterm assigned them", async () => {
     const { frame } = await frameFor("éx̸ 각 क्ष 👩‍💻");
 
-    expect(cellLayout(frame.rows[0]).slice(0, 11)).toEqual([
+    expect(cellLayout(frame.rows[0]).slice(0, 9)).toEqual([
       { text: "é", col: 0, span: 1 },
       { text: "x̸", col: 1, span: 1 },
       { text: " ", col: 2, span: 1 },
       { text: "각", col: 3, span: 2 },
       { text: " ", col: 5, span: 1 },
-      { text: "क्", col: 6, span: 1 },
-      { text: "ष", col: 7, span: 1 },
-      { text: " ", col: 8, span: 1 },
-      { text: "👩‍", col: 9, span: 1 },
-      { text: "💻", col: 10, span: 1 },
-      { text: " ", col: 11, span: 1 },
+      { text: "क्ष", col: 6, span: 1 },
+      { text: " ", col: 7, span: 1 },
+      { text: "👩‍💻", col: 8, span: 2 },
+      { text: " ", col: 10, span: 1 },
     ]);
   });
 
@@ -237,7 +235,7 @@ test("builds native frames after replay commits at captured geometry and the lat
     expect(frame.columns).toBe(50);
     expect(frame.rows).toHaveLength(10);
     expect(frame.rows[0].text.trimEnd()).toBe("LIVE-界🙂");
-    expect(frame.rows[0].styles.slice(0, 4)).toEqual([8, RED, 0, 0]);
+    expect(frame.rows[0].styles.slice(0, 4)).toEqual([9, RED, 0, 0]);
     expect(encodeTerminalFrame(frame).rows[0]).toContain("LIVE-界🙂");
   } finally {
     drain.dispose();
diff --git a/packages/app/src/terminal/runtime/terminal-emulator-runtime.browser.test.ts b/packages/app/src/terminal/runtime/terminal-emulator-runtime.browser.test.ts
index 7f54361265..bf044237b0 100644
--- a/packages/app/src/terminal/runtime/terminal-emulator-runtime.browser.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-emulator-runtime.browser.test.ts
@@ -717,11 +717,13 @@ describe("terminal emulator runtime in a real browser", () => {
     { name: "DA1-zero", bytes: "\x1b[0c" },
     { name: "DA2", bytes: "\x1b[>c" },
     { name: "DA3", bytes: "\x1b[=c" },
+    { name: "XTVERSION", bytes: "\x1b[>q" },
     { name: "DSR-5", bytes: "\x1b[5n" },
     { name: "DSR-6", bytes: "\x1b[6n" },
     { name: "DSR-?6", bytes: "\x1b[?6n" },
     { name: "DECRQM", bytes: "\x1b[1$p" },
     { name: "DECRQM-?", bytes: "\x1b[?1$p" },
+    { name: "DECRQSS", bytes: "\x1bP$qm\x1b\\" },
     { name: "OSC-10-foreground-color", bytes: "\x1b]10;?\x07" },
     { name: "OSC-11-background-color", bytes: "\x1b]11;?\x07" },
     { name: "OSC-12-cursor-color", bytes: "\x1b]12;?\x07" },
@@ -821,6 +823,67 @@ describe("incremental replay lifecycle", () => {
     expect(mounted.inputs).toHaveLength(1);
     expect(mounted.inputs[0]?.startsWith("\x1b]4;1;rgb:")).toBe(true);
   });
+
+  it("measures emoji clusters with the daemon's grapheme widths and copies them intact", async () => {
+    const mounted = createTerminalHost({ width: 720, height: 360 });
+    const text = "A😀B❤️C👋🏽D👨‍👩‍👧E";
+    await new Promise<void>((resolve) =>
+      mounted.runtime.write({ data: terminalOutput(text), onCommitted: resolve }),
+    );
+
+    const terminal = window.__paseoTerminal;
+    if (!terminal) {
+      throw new Error("Expected the browser terminal to be mounted");
+    }
+    const line = terminal.buffer.active.getLine(terminal.buffer.active.cursorY);
+    const cells = Array.from({ length: 13 }, (_, col) => {
+      const cell = line?.getCell(col);
+      return { chars: cell?.getChars(), width: cell?.getWidth() };
+    });
+
+    expect(cells).toEqual([
+      { chars: "A", width: 1 },
+      { chars: "😀", width: 2 },
+      { chars: "", width: 0 },
+      { chars: "B", width: 1 },
+      { chars: "❤️", width: 2 },
+      { chars: "", width: 0 },
+      { chars: "C", width: 1 },
+      { chars: "👋🏽", width: 2 },
+      { chars: "", width: 0 },
+      { chars: "D", width: 1 },
+      { chars: "👨‍👩‍👧", width: 2 },
+      { chars: "", width: 0 },
+      { chars: "E", width: 1 },
+    ]);
+    expect(terminal.buffer.active.cursorX).toBe(13);
+
+    terminal.select(0, terminal.buffer.active.cursorY, 13);
+    expect(terminal.getSelection()).toBe(text);
+  });
+
+  // A host without grapheme widths answers cursor reports and replays with its
+  // own table. The web client keeps the Unicode 11 table it used before.
+  it("measures with the legacy table for hosts without grapheme widths", async () => {
+    const mounted = createTerminalHost({ width: 720, height: 360 });
+    const terminal = window.__paseoTerminal;
+    if (!terminal) {
+      throw new Error("Expected the browser terminal to be mounted");
+    }
+    const buffer = terminal.buffer;
+    async function cursorAfter(text: string): Promise<number> {
+      await new Promise<void>((resolve) =>
+        mounted.runtime.write({ data: terminalOutput(`\r\n${text}`), onCommitted: resolve }),
+      );
+      return buffer.active.cursorX;
+    }
+
+    mounted.runtime.setCharacterWidths({ widths: "legacy" });
+    expect([await cursorAfter("A😀B"), await cursorAfter("A❤️B")]).toEqual([4, 3]);
+
+    mounted.runtime.setCharacterWidths({ widths: "graphemes" });
+    expect([await cursorAfter("A😀B"), await cursorAfter("A❤️B")]).toEqual([4, 4]);
+  });
 });
 
 it("restores fitted web geometry after replay before live output", async () => {
diff --git a/packages/app/src/terminal/runtime/terminal-emulator-runtime.test.ts b/packages/app/src/terminal/runtime/terminal-emulator-runtime.test.ts
index a6939aaecb..7b1568b60e 100644
--- a/packages/app/src/terminal/runtime/terminal-emulator-runtime.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-emulator-runtime.test.ts
@@ -36,6 +36,12 @@ vi.mock("@xterm/addon-unicode11", () => ({
   },
 }));
 
+vi.mock("@xterm/addon-unicode-graphemes", () => ({
+  UnicodeGraphemesAddon: class UnicodeGraphemesAddon {
+    dispose(): void {}
+  },
+}));
+
 vi.mock("@xterm/addon-web-links", () => ({
   WebLinksAddon: class WebLinksAddon {
     dispose(): void {}
@@ -82,6 +88,7 @@ import {
   createTerminalResizeEvent,
   encodeTerminalOutput,
   TerminalEmulatorRuntime,
+  type TerminalClipboard,
 } from "./terminal-emulator-runtime";
 
 interface StubTerminal {
@@ -638,3 +645,97 @@ describe("terminal-emulator-runtime", () => {
     expect(fitAndEmitResize).not.toHaveBeenCalled();
   });
 });
+
+describe("terminal-emulator-runtime clipboard shortcuts", () => {
+  type KeyHandler = (event: KeyboardEvent) => boolean;
+
+  function createClipboard(available: boolean) {
+    return {
+      isAvailable: () => available,
+      readText: vi.fn(async () => "clipboard text"),
+      read: vi.fn(async () => []),
+      writeText: vi.fn(async (_text: string) => undefined),
+    } satisfies TerminalClipboard;
+  }
+
+  function attachKeyHandler(input: { clipboard: TerminalClipboard; selection: string }) {
+    const runtime = new TerminalEmulatorRuntime({ isMac: false }, input.clipboard);
+    let handler: KeyHandler | null = null;
+    const paste = vi.fn();
+    runtime.attachKeyEventHandler({
+      attachCustomKeyEventHandler: (next: KeyHandler) => {
+        handler = next;
+      },
+      hasSelection: () => input.selection.length > 0,
+      getSelection: () => input.selection,
+      paste,
+      input: vi.fn(),
+      scrollToBottom: vi.fn(),
+    });
+    if (!handler) throw new Error("key handler was not attached");
+    return { handler: handler as KeyHandler, paste };
+  }
+
+  function ctrlKey(key: string) {
+    const preventDefault = vi.fn();
+    const event = {
+      type: "keydown",
+      key,
+      isComposing: false,
+      ctrlKey: true,
+      shiftKey: false,
+      altKey: false,
+      metaKey: false,
+      preventDefault,
+      stopPropagation: vi.fn(),
+    } as unknown as KeyboardEvent;
+    return { event, preventDefault };
+  }
+
+  it("leaves Ctrl+C with a selection to the native copy event without the Clipboard API", () => {
+    const clipboard = createClipboard(false);
+    const { handler } = attachKeyHandler({ clipboard, selection: "selected text" });
+    const { event, preventDefault } = ctrlKey("c");
+
+    expect(handler(event)).toBe(false);
+    expect(clipboard.writeText).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("leaves Ctrl+V to the native paste event without the Clipboard API", () => {
+    const clipboard = createClipboard(false);
+    const { handler, paste } = attachKeyHandler({ clipboard, selection: "" });
+    const { event, preventDefault } = ctrlKey("v");
+
+    expect(handler(event)).toBe(false);
+    expect(clipboard.readText).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+    expect(paste).not.toHaveBeenCalled();
+  });
+
+  it("lets xterm send ^C for Ctrl+C without a selection when the Clipboard API is missing", () => {
+    const clipboard = createClipboard(false);
+    const { handler } = attachKeyHandler({ clipboard, selection: "" });
+    const { event, preventDefault } = ctrlKey("c");
+
+    expect(handler(event)).toBe(true);
+    expect(clipboard.writeText).not.toHaveBeenCalled();
+    expect(preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("copies and pastes through the Clipboard API when it is available", async () => {
+    const clipboard = createClipboard(true);
+    const { handler, paste } = attachKeyHandler({ clipboard, selection: "selected text" });
+
+    const copy = ctrlKey("c");
+    expect(handler(copy.event)).toBe(false);
+    expect(clipboard.writeText).toHaveBeenCalledWith("selected text");
+    expect(copy.preventDefault).not.toHaveBeenCalled();
+
+    const pasteKey = ctrlKey("v");
+    expect(handler(pasteKey.event)).toBe(false);
+    expect(pasteKey.preventDefault).toHaveBeenCalledTimes(1);
+    expect(clipboard.readText).toHaveBeenCalledTimes(1);
+    await vi.waitFor(() => expect(paste).toHaveBeenCalledWith("clipboard text"));
+  });
+});
diff --git a/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts b/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
index a7460f7f80..ae74a4945f 100644
--- a/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
+++ b/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
@@ -3,10 +3,12 @@ import { FitAddon } from "@xterm/addon-fit";
 import { ImageAddon } from "@xterm/addon-image";
 import { SearchAddon } from "@xterm/addon-search";
 import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
 import { WebLinksAddon } from "@xterm/addon-web-links";
 import { WebglAddon } from "@xterm/addon-webgl";
 import { LigaturesAddon } from "@xterm/addon-ligatures/lib/addon-ligatures.mjs";
 import { Terminal, type ITheme, type IMarker } from "@xterm/xterm";
+import type { TerminalCharacterWidths } from "../character-widths";
 import {
   type TerminalInputModeState,
   TerminalInputModeTracker,
@@ -121,7 +123,6 @@ interface TerminalEmulatorRuntimeDisposables {
   removeVisualViewportResize: () => void;
   clearFitTimeouts: () => void;
   removeFontListeners: () => void;
-  removeTouchListeners: () => void;
   removeFilePasteListener: () => void;
   restoreDocumentStyles: () => void;
   restoreViewportStyles: () => void;
@@ -153,7 +154,6 @@ const isAppleHandheld =
     maxTouchPoints: navigator.maxTouchPoints,
   });
 
-const DEFAULT_TOUCH_SCROLL_LINE_HEIGHT_PX = 18;
 const FIT_TIMEOUT_DELAYS_MS = [0, 16, 48, 120, 250, 500, 1_000, 2_000];
 const OUTPUT_OPERATION_TIMEOUT_MS = 5_000;
 const EMPTY_TERMINAL_OUTPUT = new Uint8Array(0);
@@ -182,15 +182,26 @@ function withOverviewRulerBorderHidden(theme: ITheme): ITheme {
 }
 
 export interface TerminalClipboard {
+  /** Whether the async Clipboard API is usable. Browsers omit it outside secure contexts. */
+  isAvailable?(): boolean;
   readText(): Promise<string>;
   read(): Promise<readonly Pick<ClipboardItem, "types" | "getType">[]>;
   writeText(text: string): Promise<void>;
 }
 
+function getBrowserClipboard(): Clipboard | undefined {
+  return typeof navigator !== "undefined" ? navigator.clipboard : undefined;
+}
+
+function rejectUnavailableClipboard(): Promise<never> {
+  return Promise.reject(new Error("Clipboard API is unavailable"));
+}
+
 const browserClipboard: TerminalClipboard = {
-  readText: () => navigator.clipboard.readText(),
-  read: () => navigator.clipboard.read(),
-  writeText: (text) => navigator.clipboard.writeText(text),
+  isAvailable: () => !!getBrowserClipboard(),
+  readText: () => getBrowserClipboard()?.readText() ?? rejectUnavailableClipboard(),
+  read: () => getBrowserClipboard()?.read() ?? rejectUnavailableClipboard(),
+  writeText: (text) => getBrowserClipboard()?.writeText(text) ?? rejectUnavailableClipboard(),
 };
 
 async function readClipboardImage(clipboard: TerminalClipboard): Promise<TerminalFile | null> {
@@ -221,6 +232,12 @@ function findFileOnlyPaste(transfer: DataTransfer | null): File | null {
   return null;
 }
 
+// Grapheme widths match the daemon and native buffers. Legacy hosts keep the
+// Unicode 11 table web used before. See docs/terminal-rendering.md.
+function applyCharacterWidths(terminal: Terminal, widths: TerminalCharacterWidths): void {
+  terminal.unicode.activeVersion = widths === "graphemes" ? "15-graphemes" : "11";
+}
+
 export class TerminalEmulatorRuntime {
   constructor(
     private readonly options: FindShortcutPlatform = { isMac: isMacUserAgent() },
@@ -233,6 +250,7 @@ export class TerminalEmulatorRuntime {
     shift: false,
     alt: false,
   };
+  private characterWidths: TerminalCharacterWidths = "graphemes";
   private terminal: Terminal | null = null;
   private fitAddon: FitAddon | null = null;
   private searchAddon: SearchAddon | null = null;
@@ -320,6 +338,16 @@ export class TerminalEmulatorRuntime {
     this.pendingModifiers = input.pendingModifiers;
   }
 
+  setCharacterWidths(input: { widths: TerminalCharacterWidths }): void {
+    this.characterWidths = input.widths;
+    const terminal = this.terminal;
+    if (!terminal) {
+      return;
+    }
+    applyCharacterWidths(terminal, input.widths);
+    this.refreshVisibleRows();
+  }
+
   private loadSearchAddon(terminal: Terminal): void {
     const searchAddon = new SearchAddon({ highlightLimit: FIND_HIGHLIGHT_LIMIT });
     terminal.loadAddon(searchAddon);
@@ -368,22 +396,7 @@ export class TerminalEmulatorRuntime {
         !event.altKey &&
         !event.metaKey
       ) {
-        const key = event.key.toLowerCase();
-
-        // Ctrl+C: copy selection to clipboard if text is selected, otherwise let xterm send SIGINT
-        if (key === "c" && terminal.hasSelection()) {
-          void this.clipboard.writeText(terminal.getSelection());
-          return false;
-        }
-
-        // Ctrl+V: paste clipboard text, or the clipboard image when there is no text
-        if (key === "v") {
-          event.preventDefault();
-          this.pasteClipboard(terminal);
-          return false;
-        }
-
-        return true;
+        return !this.handleCtrlClipboardShortcut(terminal, event);
       }
 
       if (this.maybeSendMacEditingShortcut(terminal, event)) {
@@ -432,6 +445,36 @@ export class TerminalEmulatorRuntime {
     });
   }
 
+  /** Returns true when a non-Mac Ctrl+C / Ctrl+V clipboard shortcut was handled. */
+  private handleCtrlClipboardShortcut(
+    terminal: Pick<Terminal, "hasSelection" | "getSelection" | "paste">,
+    event: KeyboardEvent,
+  ): boolean {
+    const key = event.key.toLowerCase();
+    // Without the Clipboard API (e.g. plain http on a LAN address), the browser's native
+    // copy/paste events still fire and xterm handles them, so leave the default action.
+    const clipboardAvailable = this.clipboard.isAvailable?.() ?? true;
+
+    // Ctrl+C: copy selection to clipboard if text is selected, otherwise let xterm send SIGINT
+    if (key === "c" && terminal.hasSelection()) {
+      if (clipboardAvailable) {
+        void this.clipboard.writeText(terminal.getSelection());
+      }
+      return true;
+    }
+
+    // Ctrl+V: paste clipboard text, or the clipboard image when there is no text
+    if (key === "v") {
+      if (clipboardAvailable) {
+        event.preventDefault();
+        this.pasteClipboard(terminal);
+      }
+      return true;
+    }
+
+    return false;
+  }
+
   private handleFindShortcut(event: KeyboardEvent): boolean {
     if (!isFindShortcut(event, this.options) || !this.callbacks.onFindRequest) return false;
     event.preventDefault();
@@ -529,11 +572,12 @@ export class TerminalEmulatorRuntime {
       theme: withOverviewRulerBorderHidden(input.theme),
     });
     const fitAddon = new FitAddon();
-    const unicode11Addon = new Unicode11Addon();
     let webglAddon: WebglAddon | null = null;
     let imageAddon: ImageAddon | null = null;
     terminal.loadAddon(fitAddon);
-    terminal.loadAddon(unicode11Addon);
+    terminal.loadAddon(new Unicode11Addon());
+    terminal.loadAddon(new UnicodeGraphemesAddon());
+    applyCharacterWidths(terminal, this.characterWidths);
     terminal.loadAddon(new WebLinksAddon(openExternalLink));
     const localFileLinkProvider = terminal.registerLinkProvider(
       createTerminalLocalFileLinkProvider(terminal, {
@@ -568,11 +612,6 @@ export class TerminalEmulatorRuntime {
     terminal.open(input.host);
     this.themeBackgroundElements = this.collectThemeBackgroundElements(input);
     this.applyThemeBackground(input.theme);
-    try {
-      terminal.unicode.activeVersion = "11";
-    } catch {
-      // Ignore if unicode API isn't available in this build/runtime.
-    }
 
     const disposeImageAddon = (): void => {
       try {
@@ -606,6 +645,7 @@ export class TerminalEmulatorRuntime {
       terminal.parser.registerCsiHandler({ final: "c" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: ">", final: "c" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: "=", final: "c" }, () => true);
+      terminal.parser.registerCsiHandler({ prefix: ">", final: "q" }, () => true);
       terminal.parser.registerCsiHandler({ final: "n" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: "?", final: "n" }, () => true);
       terminal.parser.registerCsiHandler({ final: "R" }, () => true);
@@ -614,6 +654,7 @@ export class TerminalEmulatorRuntime {
         { prefix: "?", intermediates: "$", final: "p" },
         () => true,
       );
+      terminal.parser.registerDcsHandler({ intermediates: "$", final: "q" }, () => true);
       for (const code of [10, 11, 12]) {
         terminal.parser.registerOscHandler(code, (data) => data.trim() === "?");
       }
@@ -721,11 +762,6 @@ export class TerminalEmulatorRuntime {
     };
     input.host.addEventListener("paste", filePasteHandler, true);
 
-    const removeTouchListeners = this.setupTouchScrollHandlers({
-      root: input.root,
-      host: input.host,
-      terminal,
-    });
     const resizeObserver = new ResizeObserver(() => {
       fitAndEmitResize({ shouldClaim: false });
     });
@@ -805,7 +841,6 @@ export class TerminalEmulatorRuntime {
       removeFontListeners: () => {
         fontSet?.removeEventListener?.("loadingdone", fontReadyHandler);
       },
-      removeTouchListeners,
       removeFilePasteListener: () => {
         input.host.removeEventListener("paste", filePasteHandler, true);
       },
@@ -837,7 +872,6 @@ export class TerminalEmulatorRuntime {
       disposables.removeVisualViewportResize();
       disposables.clearFitTimeouts();
       disposables.removeFontListeners();
-      disposables.removeTouchListeners();
       disposables.removeFilePasteListener();
       disposables.disposeFitAddon();
       disposables.disposeWebglAddon();
@@ -1377,120 +1411,4 @@ export class TerminalEmulatorRuntime {
       }
     };
   }
-
-  private setupTouchScrollHandlers(input: {
-    root: HTMLDivElement;
-    host: HTMLDivElement;
-    terminal: Terminal;
-  }): () => void {
-    let touchScrollRemainderPx = 0;
-    const measuredLineHeight =
-      input.host.querySelector<HTMLElement>(".xterm-rows > div")?.getBoundingClientRect().height ??
-      0;
-    const touchScrollLineHeightPx =
-      measuredLineHeight > 0 ? measuredLineHeight : DEFAULT_TOUCH_SCROLL_LINE_HEIGHT_PX;
-
-    const activeTouch = {
-      identifier: -1,
-      startX: 0,
-      startY: 0,
-      lastX: 0,
-      lastY: 0,
-      mode: null as "vertical" | "horizontal" | null,
-    };
-
-    const touchStartHandler = (event: TouchEvent) => {
-      if (event.touches.length !== 1) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-        return;
-      }
-
-      const touch = event.touches[0];
-      if (!touch) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-        return;
-      }
-
-      activeTouch.identifier = touch.identifier;
-      activeTouch.startX = touch.clientX;
-      activeTouch.startY = touch.clientY;
-      activeTouch.lastX = touch.clientX;
-      activeTouch.lastY = touch.clientY;
-      activeTouch.mode = null;
-      touchScrollRemainderPx = 0;
-    };
-
-    const touchMoveHandler = (event: TouchEvent) => {
-      if (event.touches.length !== 1) {
-        return;
-      }
-
-      const touch = Array.from(event.touches).find(
-        (candidate) => candidate.identifier === activeTouch.identifier,
-      );
-      if (!touch) {
-        return;
-      }
-
-      const totalDeltaX = touch.clientX - activeTouch.startX;
-      const totalDeltaY = touch.clientY - activeTouch.startY;
-      if (activeTouch.mode === null) {
-        const absX = Math.abs(totalDeltaX);
-        const absY = Math.abs(totalDeltaY);
-        if (absX > 8 || absY > 8) {
-          activeTouch.mode = absY >= absX ? "vertical" : "horizontal";
-        }
-      }
-
-      const deltaY = touch.clientY - activeTouch.lastY;
-      activeTouch.lastX = touch.clientX;
-      activeTouch.lastY = touch.clientY;
-
-      if (activeTouch.mode !== "vertical") {
-        return;
-      }
-
-      touchScrollRemainderPx += deltaY;
-      const lineDelta = Math.trunc(touchScrollRemainderPx / touchScrollLineHeightPx);
-      if (lineDelta !== 0) {
-        input.terminal.scrollLines(-lineDelta);
-        touchScrollRemainderPx -= lineDelta * touchScrollLineHeightPx;
-      }
-
-      event.preventDefault();
-    };
-
-    const touchEndHandler = (event: TouchEvent) => {
-      const activeTouchEnded = Array.from(event.changedTouches).some(
-        (touch) => touch.identifier === activeTouch.identifier,
-      );
-      if (activeTouchEnded || event.touches.length === 0) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-      }
-    };
-
-    const touchCancelHandler = () => {
-      touchScrollRemainderPx = 0;
-      activeTouch.identifier = -1;
-      activeTouch.mode = null;
-    };
-
-    input.root.addEventListener("touchstart", touchStartHandler, { passive: true });
-    input.root.addEventListener("touchmove", touchMoveHandler, { passive: false });
-    input.root.addEventListener("touchend", touchEndHandler, { passive: true });
-    input.root.addEventListener("touchcancel", touchCancelHandler, { passive: true });
-
-    return () => {
-      input.root.removeEventListener("touchstart", touchStartHandler);
-      input.root.removeEventListener("touchmove", touchMoveHandler);
-      input.root.removeEventListener("touchend", touchEndHandler);
-      input.root.removeEventListener("touchcancel", touchCancelHandler);
-    };
-  }
 }
diff --git a/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts b/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
index 62a65c6878..5b1e875b44 100644
--- a/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
@@ -160,6 +160,8 @@ it("preserves another terminal's glyph pixels when a shared atlas is cleared", a
   expectSamePixels({ expected: before, actual: after, label: "sibling after atlas clear" });
 });
 
+// Software WebGL can take over 30 seconds for this corpus on a contended runner.
+// Each capture still has its own two-second render deadline.
 it("preserves both headers while ordinary output grows the shared glyph atlas", async () => {
   const { active, sibling } = await mountPair();
   const cells = active.terminal.cols * (active.terminal.rows - 2);
@@ -199,4 +201,4 @@ it("preserves both headers while ordinary output grows the shared glyph atlas",
       label: `sibling frame ${batch}`,
     });
   }
-}, 30000);
+}, 60_000);
diff --git a/packages/app/src/timeline/replica.test.ts b/packages/app/src/timeline/replica.test.ts
index dbb42a97b0..d0b4b78777 100644
--- a/packages/app/src/timeline/replica.test.ts
+++ b/packages/app/src/timeline/replica.test.ts
@@ -8,14 +8,23 @@ import {
 import { afterEach, describe, expect, it } from "vitest";
 import type { AgentStreamEventPayload } from "@getpaseo/protocol/messages";
 import type { CachedTimeline } from "@/runtime/replica-cache";
-import { selectAgentTimelineState, useSessionStore } from "@/stores/session-store";
+import {
+  selectAgentTimelineState,
+  selectAgentTimelineTurnPresentation,
+  selectAgentTurnPresentation,
+  useSessionStore,
+  type Agent,
+} from "@/stores/session-store";
 import { useCreateFlowStore, type PendingCreateAttempt } from "@/stores/create-flow-store";
 import type { StreamItem } from "@/types/stream";
+import { reduceTurnLiveness, type TurnLivenessTransition } from "./turn-liveness";
 import {
   createTimelineReplica,
   createViewedTimelineOwner,
   type TimelineReplicaStorage,
+  type TimelineResponsePayload,
   type ViewedTimelineOwner,
+  type ViewedTimelineOwnerPorts,
 } from "./viewed-timeline-sync";
 
 const SERVER_ID = "timeline-replica-host";
@@ -40,7 +49,22 @@ function cachedTimeline(): CachedTimeline {
   };
 }
 
-function createOwner(storage: TimelineReplicaStorage): ViewedTimelineOwner {
+function createOwner(
+  storage: TimelineReplicaStorage,
+  applyTurnLiveness: (
+    agentId: string,
+    transitions: readonly TurnLivenessTransition[],
+  ) => void = () => undefined,
+  fetchPage: ViewedTimelineOwnerPorts["fetchPage"] = async () => ({
+    hasNewer: false,
+    endCursor: null,
+  }),
+  observe: ViewedTimelineOwnerPorts["observe"] = () => ({
+    ready: Promise.resolve(),
+    release: async () => undefined,
+  }),
+  checksFreshness = false,
+): ViewedTimelineOwner {
   const replica = createTimelineReplica({
     serverId: SERVER_ID,
     storage,
@@ -51,10 +75,19 @@ function createOwner(storage: TimelineReplicaStorage): ViewedTimelineOwner {
     replica,
     replaceDemandedAgentIds: () => undefined,
     drainQueuedAgentMessage: () => undefined,
+    applyTurnLiveness,
     ports: {
-      observe: () => ({ ready: Promise.resolve(), release: async () => undefined }),
-      readCursor: () => undefined,
-      fetchPage: async () => ({ hasNewer: false, endCursor: null }),
+      canCheckFreshness: () => checksFreshness,
+      observe,
+      readCursor: () => {
+        if (!checksFreshness) return undefined;
+        const session = useSessionStore.getState().sessions[SERVER_ID];
+        const timeline = selectAgentTimelineState(session, AGENT_ID);
+        return timeline.status === "synced" && timeline.range
+          ? { epoch: timeline.range.epoch, endSeq: timeline.range.endSeq }
+          : undefined;
+      },
+      fetchPage,
       fetchLatestTail: async () => ({ hasNewer: false, endCursor: null }),
       reportError: () => undefined,
     },
@@ -98,7 +131,7 @@ describe("viewed timeline persistence", () => {
               .status,
         )
         .toBe("painted");
-      owner.enqueueStreamEvent(AGENT_ID, {
+      owner.applyStreamEvent(AGENT_ID, {
         event: {
           type: "timeline",
           provider: "codex",
@@ -147,7 +180,7 @@ describe("viewed timeline persistence", () => {
           .map((entry) => entry.text);
       };
       expect.soft(replyTexts()).toEqual([complete]);
-      owner.enqueueStreamEvent(AGENT_ID, {
+      owner.applyStreamEvent(AGENT_ID, {
         event: { type: "turn_completed", provider: "codex" } as AgentStreamEventPayload,
         seq: 7,
         epoch: "epoch-1",
@@ -281,7 +314,7 @@ describe("viewed timeline persistence", () => {
       )
       .toMatchObject({ status: "painted" });
 
-    first.enqueueStreamEvent(AGENT_ID, {
+    first.applyStreamEvent(AGENT_ID, {
       event: {
         type: "timeline",
         provider: "codex",
@@ -460,7 +493,7 @@ describe("viewed timeline persistence", () => {
       readTimeline: async () => undefined,
       commitTimeline: (_serverId, _agentId, timeline) => commits.push(timeline),
     });
-    owner.enqueueStreamEvent(AGENT_ID, {
+    owner.applyStreamEvent(AGENT_ID, {
       event: {
         type: "timeline",
         provider: "codex",
@@ -525,7 +558,7 @@ describe("viewed timeline persistence", () => {
       [AGENT_ID, 9],
       ["agent-2", 4],
     ] as const) {
-      owner.enqueueStreamEvent(agentId, {
+      owner.applyStreamEvent(agentId, {
         event: {
           type: "timeline",
           provider: "codex",
@@ -604,13 +637,13 @@ describe("conversation rewind through the owner", () => {
       ],
     });
 
-    owner.enqueueStreamEvent(AGENT_ID, {
+    owner.applyStreamEvent(AGENT_ID, {
       event: { type: "rewind", retireFromSeq: 3 },
       seq: 5,
       epoch: "epoch-1",
       timestamp: new Date("2026-08-26T10:00:05.000Z"),
     });
-    owner.enqueueStreamEvent(AGENT_ID, {
+    owner.applyStreamEvent(AGENT_ID, {
       event: {
         type: "timeline",
         provider: "codex",
@@ -650,13 +683,13 @@ describe("conversation rewind through the owner", () => {
   });
 
   function liveRewindOfB(owner: ViewedTimelineOwner, retirement: { seq: number }): void {
-    owner.enqueueStreamEvent(AGENT_ID, {
+    owner.applyStreamEvent(AGENT_ID, {
       event: { type: "rewind", retireFromSeq: 3 },
       seq: retirement.seq,
       epoch: "epoch-1",
       timestamp: new Date("2026-08-26T10:00:06.000Z"),
     });
-    owner.enqueueStreamEvent(AGENT_ID, {
+    owner.applyStreamEvent(AGENT_ID, {
       event: {
         type: "timeline",
         provider: "codex",
@@ -766,6 +799,695 @@ describe("conversation rewind through the owner", () => {
   });
 });
 
+describe("turn boundaries", () => {
+  it("commits a turn's final reply before the turn stops running", () => {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    applySynced(AGENT_ID, 8);
+    const committedKinds = () => {
+      const session = useSessionStore.getState().sessions[SERVER_ID];
+      return [
+        ...(session?.agentStreamTail.get(AGENT_ID) ?? []),
+        ...(session?.agentStreamHead.get(AGENT_ID) ?? []),
+      ]
+        .filter((entry) => entry.id !== `network-${AGENT_ID}`)
+        .map((entry) => entry.kind);
+    };
+    const livenessChanges: { type: string; committed: string[] }[] = [];
+    const owner = createOwner(
+      { readTimeline: async () => undefined, commitTimeline: () => undefined },
+      (_agentId, transitions) => {
+        for (const transition of transitions) {
+          livenessChanges.push({ type: transition.type, committed: committedKinds() });
+        }
+      },
+    );
+    const at = (second: number) => new Date(`2026-08-26T10:00:0${second}.000Z`);
+
+    // One frame's worth of live events: the frame flush that would commit them never runs.
+    owner.applyStreamEvent(AGENT_ID, {
+      event: { type: "turn_started", provider: "codex", turnId: "turn-1" },
+      seq: undefined,
+      epoch: undefined,
+      timestamp: at(1),
+    });
+    owner.applyStreamEvent(AGENT_ID, {
+      event: {
+        type: "timeline",
+        provider: "codex",
+        turnId: "turn-1",
+        item: {
+          type: "tool_call",
+          callId: "call-1",
+          name: "Bash",
+          status: "completed",
+          error: null,
+          detail: { type: "shell", command: "ls" },
+        },
+      } as AgentStreamEventPayload,
+      seq: 9,
+      epoch: "epoch-1",
+      timestamp: at(2),
+    });
+    owner.applyStreamEvent(AGENT_ID, {
+      event: {
+        type: "timeline",
+        provider: "codex",
+        turnId: "turn-1",
+        item: { type: "assistant_message", text: "Done.", messageId: "reply-1" },
+      } as AgentStreamEventPayload,
+      seq: 10,
+      epoch: "epoch-1",
+      timestamp: at(3),
+    });
+    owner.applyStreamEvent(AGENT_ID, {
+      event: { type: "turn_completed", provider: "codex", turnId: "turn-1" },
+      seq: undefined,
+      epoch: undefined,
+      timestamp: at(4),
+    });
+
+    expect(livenessChanges.at(-1)).toEqual({
+      type: "stream_close",
+      committed: ["tool_call", "assistant_message"],
+    });
+    owner.dispose();
+  });
+});
+
+describe("the turn footer changes together with its messages", () => {
+  const OPEN_TURN = { turnId: "turn-1", startedAt: new Date("2026-08-26T09:59:00.000Z") };
+
+  function setTurn(transition: TurnLivenessTransition): void {
+    useSessionStore.getState().setAgents(SERVER_ID, (agents) => {
+      const agent =
+        agents.get(AGENT_ID) ??
+        ({
+          id: AGENT_ID,
+          turn: { phase: "idle", cancellationRequestId: null },
+        } as Agent);
+      const next = new Map(agents);
+      next.set(AGENT_ID, { ...agent, turn: reduceTurnLiveness(agent.turn, transition) });
+      return next;
+    });
+  }
+  const agentIsRunning = () => setTurn({ type: "snapshot", activeTurn: OPEN_TURN });
+  const idleSnapshotArrives = () => setTurn({ type: "snapshot", activeTurn: null });
+
+  type Footer = "running" | "settled";
+  function footer(): Footer {
+    const session = useSessionStore.getState().sessions[SERVER_ID];
+    const turn = selectAgentTimelineTurnPresentation(session, AGENT_ID);
+    return turn.isActive ? "running" : "settled";
+  }
+  function timerStart(): Date | null {
+    const session = useSessionStore.getState().sessions[SERVER_ID];
+    return selectAgentTimelineTurnPresentation(session, AGENT_ID).startedAt;
+  }
+  function replies(): string[] {
+    const session = useSessionStore.getState().sessions[SERVER_ID];
+    return [
+      ...(session?.agentStreamTail.get(AGENT_ID) ?? []),
+      ...(session?.agentStreamHead.get(AGENT_ID) ?? []),
+    ]
+      .filter((entry) => entry.kind === "assistant_message")
+      .map((entry) => entry.text);
+  }
+
+  // A chat that was current when the connection dropped, holding `cachedReply` if given.
+  function createChat(
+    cachedReply: string | null,
+    fetchPage?: ViewedTimelineOwnerPorts["fetchPage"],
+  ): ViewedTimelineOwner {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    useSessionStore.getState().applyAgentTimelineResponseState(SERVER_ID, AGENT_ID, {
+      items: cachedReply ? [item("reply-1", cachedReply, 4)] : [],
+      head: [],
+      range: { epoch: "epoch-1", startSeq: 1, endSeq: 4 },
+      older: "none",
+      newer: false,
+      synchronized: true,
+      acknowledgedClientMessageIds: [],
+    });
+    return createOwner(
+      { readTimeline: async () => undefined, commitTimeline: () => undefined },
+      undefined,
+      fetchPage,
+    );
+  }
+
+  async function connectAndCatchUp(owner: ViewedTimelineOwner): Promise<void> {
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    owner.setConnected(true);
+    await expect.poll(() => owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+  }
+
+  function catchUpPage(input: {
+    replyThroughSeq: number | null;
+    reply?: string;
+  }): TimelineResponsePayload {
+    const end = input.replyThroughSeq ?? 4;
+    return {
+      requestId: "catch-up",
+      agentId: AGENT_ID,
+      agent: null,
+      direction: "after",
+      projection: "projected",
+      reset: false,
+      epoch: "epoch-1",
+      window: { minSeq: 1, maxSeq: end, nextSeq: end + 1 },
+      startCursor: input.reply ? { epoch: "epoch-1", seq: 5 } : null,
+      endCursor: input.reply ? { epoch: "epoch-1", seq: end } : null,
+      entries: input.reply
+        ? [
+            {
+              provider: "mock",
+              item: { type: "assistant_message", text: input.reply },
+              timestamp: "2026-08-26T10:00:02.000Z",
+              seqStart: 5,
+              seqEnd: end,
+              sourceSeqRanges: [{ startSeq: 5, endSeq: end }],
+              collapsed: [],
+            },
+          ]
+        : [],
+      error: null,
+      hasNewer: false,
+      hasOlder: false,
+      staleCursor: false,
+      gap: false,
+    };
+  }
+
+  function recordCommits(): { commits: { footer: Footer; replies: string[] }[]; stop(): void } {
+    const commits: { footer: Footer; replies: string[] }[] = [
+      { footer: footer(), replies: replies() },
+    ];
+    const stop = useSessionStore.subscribe(() => {
+      commits.push({ footer: footer(), replies: replies() });
+    });
+    return { commits, stop };
+  }
+
+  it.each([
+    ["only the prompt cached", null, ["Done."]],
+    ["a partial reply cached", "Half", ["HalfDone."]],
+  ])("snapshot before messages, %s: running until messages land", async (_name, cached, final) => {
+    const owner = createChat(cached);
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    expect(footer()).toBe("running");
+
+    owner.setConnected(false);
+    expect(footer()).toBe("running");
+    owner.setConnected(true);
+    const recorder = recordCommits();
+
+    idleSnapshotArrives();
+    expect(footer()).toBe("running");
+
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 8, reply: "Done." }));
+    recorder.stop();
+
+    expect(footer()).toBe("settled");
+    expect(replies()).toEqual(final);
+    // The messages and the settled footer arrive in one commit, with no state between.
+    const previous = recorder.commits.at(-2);
+    expect(previous?.footer).toBe("running");
+    expect(previous?.replies).not.toEqual(final);
+    expect(
+      recorder.commits.filter(
+        (commit) => commit.footer === "settled" && commit.replies.join() !== final.join(),
+      ),
+    ).toEqual([]);
+    owner.dispose();
+  });
+
+  it("messages before snapshot: running stays until the idle snapshot, then completes", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    owner.setConnected(true);
+
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 8, reply: "Done." }));
+    expect(replies()).toEqual(["HalfDone."]);
+    expect(footer()).toBe("running");
+
+    idleSnapshotArrives();
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("a turn that ended with no new messages settles when the empty catch-up lands", async () => {
+    const owner = createChat("Done.");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    owner.setConnected(true);
+    idleSnapshotArrives();
+    expect(footer()).toBe("running");
+
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: null }));
+
+    expect(footer()).toBe("settled");
+    expect(replies()).toEqual(["Done."]);
+    owner.dispose();
+  });
+
+  it("keeps the true idle status for every surface outside the timeline", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    owner.setConnected(true);
+    idleSnapshotArrives();
+
+    expect(footer()).toBe("running");
+    const session = useSessionStore.getState().sessions[SERVER_ID];
+    expect(selectAgentTurnPresentation(session, AGENT_ID).isActive).toBe(false);
+    owner.dispose();
+  });
+
+  it("keeps the running turn's identity and timer start when the idle status arrives", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    owner.setConnected(true);
+    idleSnapshotArrives();
+
+    const session = useSessionStore.getState().sessions[SERVER_ID];
+    expect(selectAgentTimelineTurnPresentation(session, AGENT_ID)).toEqual({
+      isActive: true,
+      isCancelling: false,
+      startedAt: OPEN_TURN.startedAt,
+      turnId: "turn-1",
+    });
+    owner.dispose();
+  });
+
+  it("an agent still running on return keeps its running footer", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    owner.setConnected(true);
+    agentIsRunning();
+
+    expect(footer()).toBe("running");
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 6, reply: " more" }));
+    expect(footer()).toBe("running");
+    owner.dispose();
+  });
+
+  it("applies a snapshot at once when the chat is current", async () => {
+    const owner = createChat("Done.");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+
+    idleSnapshotArrives();
+
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("a reconnect that finds nothing changed never leaves the settled footer", async () => {
+    const owner = createChat("Done.");
+    await connectAndCatchUp(owner);
+    const recorder = recordCommits();
+
+    owner.setConnected(false);
+    owner.setConnected(true);
+    idleSnapshotArrives();
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: null }));
+    recorder.stop();
+
+    expect(recorder.commits.map((commit) => commit.footer)).not.toContain("running");
+    owner.dispose();
+  });
+
+  type Answer = "current" | "behind";
+
+  // A chat whose subscribes wait for the test to answer them, and whose fetches are recorded.
+  function createCheckedChat(cachedReply: string | null) {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    useSessionStore.getState().applyAgentTimelineResponseState(SERVER_ID, AGENT_ID, {
+      items: cachedReply ? [item("reply-1", cachedReply, 4)] : [],
+      head: [],
+      range: { epoch: "epoch-1", startSeq: 1, endSeq: 4 },
+      older: "none",
+      newer: false,
+      synchronized: true,
+      acknowledgedClientMessageIds: [],
+    });
+    const unanswered: ((answer: Answer, beforeAnswer?: () => void) => void)[] = [];
+    let fetches = 0;
+    let finishFetch = () => {};
+    const owner = createOwner(
+      { readTimeline: async () => undefined, commitTimeline: () => undefined },
+      undefined,
+      () => {
+        fetches += 1;
+        return new Promise((resolve) => {
+          finishFetch = () => resolve({ hasNewer: false, endCursor: null });
+        });
+      },
+      () => ({
+        // The host runtime keeps the answer's agent rows in this same continuation.
+        ready: new Promise((resolve) => {
+          unanswered.push((answer, beforeAnswer) => {
+            beforeAnswer?.();
+            resolve({ timelines: { [AGENT_ID]: answer } });
+          });
+        }),
+        release: async () => undefined,
+      }),
+      true,
+    );
+    const answer = async (value: Answer, beforeAnswer?: () => void) => {
+      await expect.poll(() => unanswered.length).toBeGreaterThan(0);
+      unanswered.shift()?.(value, beforeAnswer);
+    };
+    const open = async () => {
+      owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+      owner.setConnected(true);
+      await answer("current");
+      await expect.poll(() => owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+    };
+    return { owner, answer, open, fetchCount: () => fetches, finishFetch: () => finishFetch() };
+  }
+
+  function leaveAndReturn(owner: ViewedTimelineOwner, way: "reconnect" | "foreground"): void {
+    if (way === "reconnect") {
+      owner.setConnected(false);
+      owner.setConnected(true);
+      return;
+    }
+    owner.setActive(false);
+    owner.setActive(true);
+  }
+
+  it.each([
+    ["reconnect", "reattaching"],
+    ["foreground", "checking"],
+  ] as const)(
+    "freshness check on %s: the held turn stays through the check and current settles it",
+    async (way, status) => {
+      const chat = createCheckedChat("Done.");
+      agentIsRunning();
+      await chat.open();
+
+      leaveAndReturn(chat.owner, way);
+      idleSnapshotArrives();
+      expect(chat.owner.getAgentTimelineStatus(AGENT_ID)).toBe(status);
+      expect(footer()).toBe("running");
+
+      const recorder = recordCommits();
+      await chat.answer("current");
+      await expect.poll(() => chat.owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+      recorder.stop();
+
+      expect(footer()).toBe("settled");
+      expect(replies()).toEqual(["Done."]);
+      expect(chat.fetchCount()).toBe(0);
+      expect(recorder.commits.map((commit) => commit.footer).slice(0, 2)).toEqual([
+        "running",
+        "settled",
+      ]);
+      chat.owner.dispose();
+    },
+  );
+
+  it("freshness check: an idle row carried by the current answer settles the footer in the same step", async () => {
+    const chat = createCheckedChat("Done.");
+    agentIsRunning();
+    await chat.open();
+    leaveAndReturn(chat.owner, "reconnect");
+
+    let footerAfterRow: Footer | null = null;
+    await chat.answer("current", () => {
+      idleSnapshotArrives();
+      footerAfterRow = footer();
+    });
+    await expect.poll(() => chat.owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+
+    expect(footerAfterRow).toBe("running");
+    expect(footer()).toBe("settled");
+    chat.owner.dispose();
+  });
+
+  it("freshness check: an agent still running keeps its footer after current", async () => {
+    const chat = createCheckedChat("Half");
+    agentIsRunning();
+    await chat.open();
+    leaveAndReturn(chat.owner, "reconnect");
+
+    await chat.answer("current");
+    await expect.poll(() => chat.owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+
+    expect(footer()).toBe("running");
+    idleSnapshotArrives();
+    expect(footer()).toBe("settled");
+    chat.owner.dispose();
+  });
+
+  it("freshness check: behind holds the turn until the fetched rows land with the completed footer", async () => {
+    const chat = createCheckedChat("Half");
+    agentIsRunning();
+    await chat.open();
+    leaveAndReturn(chat.owner, "reconnect");
+    idleSnapshotArrives();
+
+    await chat.answer("behind");
+    await expect.poll(() => chat.fetchCount()).toBe(1);
+    expect(footer()).toBe("running");
+
+    const recorder = recordCommits();
+    chat.owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 8, reply: "Done." }));
+    recorder.stop();
+
+    expect(footer()).toBe("settled");
+    expect(replies()).toEqual(["HalfDone."]);
+    expect(recorder.commits.at(-2)).toMatchObject({ footer: "running", replies: ["Half"] });
+    expect(recorder.commits.at(-1)).toMatchObject({ footer: "settled", replies: ["HalfDone."] });
+    chat.finishFetch();
+    await expect.poll(() => chat.owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+    chat.owner.dispose();
+  });
+
+  it("catch-up failure gives the footer the true status", async () => {
+    let failNext = false;
+    const owner = createChat("Half", async () => {
+      if (failNext) throw new Error("catch-up failed");
+      return { hasNewer: false, endCursor: null };
+    });
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    failNext = true;
+    owner.setConnected(false);
+    owner.setConnected(true);
+    idleSnapshotArrives();
+
+    await expect.poll(() => owner.getAgentTimelineStatus(AGENT_ID)).toBe("error");
+
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("a catch-up that completes without a page still releases the footer", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.setConnected(false);
+    idleSnapshotArrives();
+    expect(footer()).toBe("running");
+
+    owner.setConnected(true);
+
+    await expect.poll(() => owner.getAgentTimelineStatus(AGENT_ID)).toBe("ready");
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("a chat closed while running and reopened after it finished keeps the running footer", async () => {
+    const owner = createChat("Half");
+    agentIsRunning();
+    await connectAndCatchUp(owner);
+    owner.replaceVisibleAgentIds("test", []);
+    owner.replaceOpenTabAgentIds([]);
+    idleSnapshotArrives();
+
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    expect(footer()).toBe("running");
+
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 8, reply: "Done." }));
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it.each([
+    { host: "that reports turn ids", olderTurnId: "turn-1", newerTurnId: "turn-2" },
+    { host: "without turn ids", olderTurnId: null, newerTurnId: null },
+  ])("on a host $host, a newer turn replaces the held one so the timer follows it", async (ids) => {
+    const newerTurn = { turnId: ids.newerTurnId, startedAt: new Date("2026-08-26T09:59:30.000Z") };
+    const owner = createChat("Half");
+    setTurn({
+      type: "snapshot",
+      activeTurn: { turnId: ids.olderTurnId, startedAt: OPEN_TURN.startedAt },
+    });
+    await connectAndCatchUp(owner);
+    owner.replaceVisibleAgentIds("test", []);
+    owner.replaceOpenTabAgentIds([]);
+    idleSnapshotArrives();
+
+    setTurn({ type: "snapshot", activeTurn: newerTurn });
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    idleSnapshotArrives();
+
+    expect(footer()).toBe("running");
+    expect(timerStart()).toEqual(newerTurn.startedAt);
+    owner.dispose();
+  });
+
+  function paintChat(unsettledTurn: CachedTimeline["unsettledTurn"]): ViewedTimelineOwner {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    idleSnapshotArrives();
+    return createOwner({
+      readTimeline: async () => ({
+        agentId: AGENT_ID,
+        items: [item("reply-1", "Half", 4)],
+        range: { epoch: "epoch-1", startSeq: 1, endSeq: 4 },
+        hasOlder: false,
+        ...(unsettledTurn ? { unsettledTurn } : {}),
+      }),
+      commitTimeline: () => undefined,
+    });
+  }
+
+  it("first paint from cache: shows the running footer in the first frame when the cached messages were from an open turn", async () => {
+    const owner = paintChat({ turnId: "turn-1", startedAt: OPEN_TURN.startedAt });
+    const recorder = recordCommits();
+
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    await expect.poll(() => replies()).toEqual(["Half"]);
+    recorder.stop();
+
+    expect(recorder.commits.find((commit) => commit.replies.length > 0)?.footer).toBe("running");
+    expect(timerStart()).toEqual(OPEN_TURN.startedAt);
+    owner.applyTimelineResponse(catchUpPage({ replyThroughSeq: 8, reply: "Done." }));
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  async function subscriptionRefusedDuringCacheRead(): Promise<{
+    owner: ViewedTimelineOwner;
+    finishCacheRead(): void;
+  }> {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    idleSnapshotArrives();
+    let resolveRead: (timeline: CachedTimeline) => void = () => undefined;
+    const owner = createOwner(
+      {
+        readTimeline: () => new Promise((resolve) => (resolveRead = resolve)),
+        commitTimeline: () => undefined,
+      },
+      undefined,
+      undefined,
+      () => ({
+        ready: Promise.reject(new Error("subscription refused")),
+        release: async () => undefined,
+      }),
+    );
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    owner.setConnected(true);
+    await expect.poll(() => owner.getAgentTimelineStatus(AGENT_ID)).toBe("error");
+    return {
+      owner,
+      finishCacheRead: () =>
+        resolveRead({
+          agentId: AGENT_ID,
+          items: [item("reply-1", "Half", 4)],
+          range: { epoch: "epoch-1", startSeq: 1, endSeq: 4 },
+          hasOlder: false,
+          unsettledTurn: { turnId: "turn-1", startedAt: OPEN_TURN.startedAt },
+        }),
+    };
+  }
+
+  it("first paint from cache: a catch-up that failed during the cache read keeps the true status", async () => {
+    const { owner, finishCacheRead } = await subscriptionRefusedDuringCacheRead();
+
+    finishCacheRead();
+    await expect.poll(() => replies()).toEqual(["Half"]);
+
+    expect(owner.getAgentTimelineStatus(AGENT_ID)).toBe("error");
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("first paint from cache: a catch-up owed again during the cache read keeps the running footer", async () => {
+    const { owner, finishCacheRead } = await subscriptionRefusedDuringCacheRead();
+    owner.setConnected(false);
+
+    finishCacheRead();
+    await expect.poll(() => replies()).toEqual(["Half"]);
+
+    expect(footer()).toBe("running");
+    owner.dispose();
+  });
+
+  it("first paint from cache: shows the settled footer at once when the cached messages were from a finished turn", async () => {
+    const owner = paintChat(undefined);
+
+    owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+    await expect.poll(() => replies()).toEqual(["Half"]);
+
+    expect(footer()).toBe("settled");
+    owner.dispose();
+  });
+
+  it("first paint from cache: records the open turn with the messages and drops it once the turn ends", async () => {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    applySynced(AGENT_ID, 8);
+    agentIsRunning();
+    const commits: CachedTimeline[] = [];
+    const owner = createOwner(
+      {
+        readTimeline: async () => undefined,
+        commitTimeline: (_serverId, _agentId, timeline) => commits.push(timeline),
+      },
+      (_agentId, transitions) => {
+        for (const transition of transitions) setTurn(transition);
+      },
+    );
+    owner.applyStreamEvent(AGENT_ID, {
+      event: {
+        type: "timeline",
+        provider: "codex",
+        item: { type: "assistant_message", text: "Working" },
+      } as AgentStreamEventPayload,
+      seq: 9,
+      epoch: "epoch-1",
+      timestamp: new Date("2026-08-26T10:00:01.000Z"),
+    });
+    owner.flushStreamAgent(AGENT_ID);
+    expect(commits.at(-1)?.unsettledTurn).toEqual({
+      turnId: "turn-1",
+      startedAt: expect.any(Date),
+    });
+
+    owner.applyStreamEvent(AGENT_ID, {
+      event: { type: "turn_completed", provider: "codex", turnId: "turn-1" },
+      seq: undefined,
+      epoch: undefined,
+      timestamp: new Date("2026-08-26T10:00:02.000Z"),
+    });
+
+    expect(commits.at(-1)?.unsettledTurn).toBeUndefined();
+    owner.dispose();
+  });
+});
+
 describe("create handoff lifetime", () => {
   const DRAFT_ID = "draft-1";
 
@@ -829,7 +1551,9 @@ describe("create handoff lifetime", () => {
       replica,
       replaceDemandedAgentIds: () => undefined,
       drainQueuedAgentMessage: () => undefined,
+      applyTurnLiveness: () => undefined,
       ports: {
+        canCheckFreshness: () => false,
         observe: () => ({ ready: Promise.resolve(), release: async () => undefined }),
         readCursor: () => undefined,
         fetchPage: async () => {
diff --git a/packages/app/src/timeline/turn-liveness.ts b/packages/app/src/timeline/turn-liveness.ts
index deadee830e..6502f6580a 100644
--- a/packages/app/src/timeline/turn-liveness.ts
+++ b/packages/app/src/timeline/turn-liveness.ts
@@ -54,6 +54,16 @@ export interface TurnPresentation {
   turnId: string | null;
 }
 
+/**
+ * The turn a chat's messages were captured during, kept until the chat has caught up past it.
+ * While it is held and the agent reads idle, the messages on screen may be older than the turn's
+ * end, so the chat cannot claim the turn is finished yet.
+ */
+export interface UnsettledTurn {
+  turnId: string | null;
+  startedAt: Date | null;
+}
+
 export function resolveTurnPresentation(
   liveness: TurnLiveness,
   hasActiveSubmission: boolean,
@@ -74,6 +84,24 @@ export function resolveTurnPresentation(
   };
 }
 
+/**
+ * What a chat shows for its turn. It differs from the true status only while the agent has
+ * finished and the chat's messages have not caught up: the chat keeps showing the running turn, so
+ * the completed footer can land with the messages it belongs to.
+ */
+export function resolveTimelineTurnPresentation(
+  turn: TurnPresentation,
+  unsettledTurn: UnsettledTurn | undefined,
+): TurnPresentation {
+  if (turn.isActive || !unsettledTurn) return turn;
+  return {
+    isActive: true,
+    isCancelling: false,
+    startedAt: unsettledTurn.startedAt,
+    turnId: unsettledTurn.turnId,
+  };
+}
+
 function closeTurn(current: TurnLiveness, turnId: string | null): TurnLiveness {
   // COMPAT(agentTurnIdentity): added in v0.2.6, remove after 2027-01-31 once daemon floor >= v0.2.6.
   const targetsDifferentIdentifiedTurn =
diff --git a/packages/app/src/timeline/viewed-timeline-sync.test.ts b/packages/app/src/timeline/viewed-timeline-sync.test.ts
index e556da612f..d61581cc73 100644
--- a/packages/app/src/timeline/viewed-timeline-sync.test.ts
+++ b/packages/app/src/timeline/viewed-timeline-sync.test.ts
@@ -5,6 +5,7 @@ import type { ProjectedTimelineForwardFetchPlan } from "./timeline-sync-plan";
 import {
   consumeForcedTimelineTailReplacement,
   createViewedTimelineSync,
+  FRESHNESS_CHECK_QUIET_MS,
   type TimelineResponsePayload,
   type ViewedTimelineStatus,
   type ViewedTimelineSyncPorts,
@@ -28,7 +29,8 @@ function deferred<T>(): Deferred<T> {
 
 interface MembershipRequest {
   agentIds: string[];
-  succeed(): void;
+  cursors: Record<string, { epoch: string; seq: number }> | undefined;
+  succeed(timelines?: Record<string, "current" | "behind">): void;
   fail(message: string): void;
 }
 
@@ -126,8 +128,12 @@ test("switching chats promotes the newly visible catch-up while another visible
 });
 
 class TimelineWorld {
-  constructor(private readonly observeMembership?: ViewedTimelineSyncPorts["observe"]) {}
+  constructor(
+    private readonly observeMembership?: ViewedTimelineSyncPorts["observe"],
+    private readonly checksFreshness = false,
+  ) {}
   readonly errors: string[] = [];
+  readonly appliedCurrent: string[] = [];
   readonly releasedMemberships: string[][] = [];
   readonly cursors = new Map<string, { epoch: string; endSeq: number }>();
   readonly cacheRequests: string[] = [];
@@ -142,17 +148,24 @@ class TimelineWorld {
         status: this.sync.getAgentTimelineStatus(agentId),
       });
     },
+    onCatchUpOwed: () => undefined,
+    onCatchUpSettled: () => undefined,
     prepare: async (agentId) => {
       this.cacheRequests.push(agentId);
       this.cacheRequestWaiters.shift()?.(agentId);
       await this.cacheGate?.promise;
     },
-    observe: (agentIds) => {
-      if (this.observeMembership) return this.observeMembership(agentIds);
-      const result = deferred<void>();
+    canCheckFreshness: () => this.checksFreshness,
+    applyCurrentTimeline: (agentId) => {
+      this.appliedCurrent.push(agentId);
+    },
+    observe: (agentIds, cursors) => {
+      if (this.observeMembership) return this.observeMembership(agentIds, cursors);
+      const result = deferred<{ timelines?: Record<string, "current" | "behind"> }>();
       this.memberships.push({
         agentIds,
-        succeed: () => result.resolve(),
+        cursors,
+        succeed: (timelines) => result.resolve({ timelines }),
         fail: (message) => result.reject(new Error(message)),
       });
       this.releaseMembershipWaiter();
@@ -160,6 +173,7 @@ class TimelineWorld {
         ready: result.promise,
         release: async () => {
           this.releasedMemberships.push(agentIds);
+          result.reject(new Error("Subscription released"));
         },
       };
     },
@@ -1198,3 +1212,384 @@ test("disposing a view releases its pending observation before bootstrap complet
   await Promise.resolve();
   world.expectNoPendingFetch();
 });
+
+function freshnessWorld(): TimelineWorld {
+  return new TimelineWorld(undefined, true);
+}
+
+test("a chat the daemon reports current finishes catching up without a fetch", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.sync.setConnected(true);
+  world.show("pane", ["agent-a"]);
+
+  const membership = await world.nextMembership();
+  expect(membership.cursors).toEqual({ "agent-a": { epoch: "epoch-a", seq: 42 } });
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+  membership.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  expect(world.appliedCurrent).toEqual(["agent-a"]);
+  expect(world.reportedCurrent).toEqual([{ agentId: "agent-a", status: "ready" }]);
+  world.expectNoPendingFetch();
+  world.sync.dispose();
+});
+
+test("a chat the daemon reports behind fetches from its cursor and reports pending", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+
+  (await world.nextMembership()).succeed({ "agent-a": "behind" });
+
+  const fetch = await world.nextFetch("agent-a");
+  expect(fetch.request).toMatchObject({
+    direction: "after",
+    cursor: { epoch: "epoch-a", seq: 42 },
+  });
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+  expect(world.appliedCurrent).toEqual([]);
+  fetch.respond({ hasNewer: false });
+  world.sync.dispose();
+});
+
+test("a chat with no cached cursor is not checked and fetches its tail", async () => {
+  const world = freshnessWorld();
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+
+  const membership = await world.nextMembership();
+  expect(membership.cursors).toEqual({});
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+  membership.succeed();
+
+  expect((await world.nextFetch("agent-a")).request.direction).toBe("tail");
+  world.sync.dispose();
+});
+
+test("an answer without an entry for a chat falls back to the fetch", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+
+  (await world.nextMembership()).succeed({});
+
+  expect((await world.nextFetch("agent-a")).request.direction).toBe("after");
+  world.sync.dispose();
+});
+
+test("a chat being opened waits for its cache before the daemon compares its cursor", async () => {
+  const world = freshnessWorld();
+  world.cacheGate = deferred<void>();
+  world.sync.setConnected(true);
+  world.show("pane", ["agent-a"]);
+  await world.nextCacheRequest();
+
+  world.expectNoPendingMembership();
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+  world.cursors.set("agent-a", { epoch: "cached", endSeq: 9 });
+  world.cacheGate.resolve();
+
+  const membership = await world.nextMembership();
+  expect(membership.cursors).toEqual({ "agent-a": { epoch: "cached", seq: 9 } });
+  membership.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.expectNoPendingFetch();
+  world.sync.dispose();
+});
+
+test("an unanswered check starts reporting pending after the delay and resolves on the answer", async () => {
+  vi.useFakeTimers();
+  try {
+    const world = freshnessWorld();
+    world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+    world.sync.setConnected(true);
+    world.show("pane", ["agent-a"]);
+    const membership = await world.nextMembership();
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+    await vi.advanceTimersByTimeAsync(FRESHNESS_CHECK_QUIET_MS - 1);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+    await vi.advanceTimersByTimeAsync(1);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+    world.expectNoPendingFetch();
+
+    membership.succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+    world.expectNoPendingFetch();
+    world.sync.dispose();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("a slow cache read does not use up the delay for the daemon's answer", async () => {
+  vi.useFakeTimers();
+  try {
+    const world = freshnessWorld();
+    world.cacheGate = deferred<void>();
+    world.sync.setConnected(true);
+    world.show("pane", ["agent-a"]);
+    await world.nextCacheRequest();
+
+    await vi.advanceTimersByTimeAsync(FRESHNESS_CHECK_QUIET_MS * 4);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+    world.cursors.set("agent-a", { epoch: "cached", endSeq: 9 });
+    world.cacheGate.resolve();
+    const membership = await world.nextMembership();
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+    await vi.advanceTimersByTimeAsync(FRESHNESS_CHECK_QUIET_MS);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+
+    membership.succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+    world.sync.dispose();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("foregrounding a current chat checks over the subscription instead of fetching", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  const first = await world.nextMembership();
+  first.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+  const check = await world.nextMembership();
+  expect(check.agentIds).toEqual(["agent-a"]);
+  expect(check.cursors).toEqual({ "agent-a": { epoch: "epoch-a", seq: 42 } });
+
+  check.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.expectNoPendingFetch();
+  world.sync.dispose();
+});
+
+test("a slow answer to the foreground check stays silent while the socket stayed connected", async () => {
+  vi.useFakeTimers();
+  try {
+    const world = freshnessWorld();
+    world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+    world.show("pane", ["agent-a"]);
+    world.sync.setConnected(true);
+    (await world.nextMembership()).succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+
+    world.sync.setActive(false);
+    world.sync.setActive(true);
+    const check = await world.nextMembership();
+
+    await vi.advanceTimersByTimeAsync(FRESHNESS_CHECK_QUIET_MS * 4);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("checking");
+
+    check.succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+    world.expectNoPendingFetch();
+    world.sync.dispose();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("a foreground check answered behind reports pending until the fetch lands", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  (await world.nextMembership()).succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+  (await world.nextMembership()).succeed({ "agent-a": "behind" });
+
+  const fetch = await world.nextFetch("agent-a");
+  expect(fetch.request).toMatchObject({ direction: "after", cursor: { seq: 42 } });
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+  fetch.respond({ hasNewer: false });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.sync.dispose();
+});
+
+test("the old subscription keeps delivering until the daemon accepts its replacement", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 1 });
+  world.cursors.set("agent-b", { epoch: "epoch-b", endSeq: 2 });
+  world.openedEarlier(["agent-b"]);
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  (await world.nextMembership()).succeed({ "agent-a": "current", "agent-b": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-b")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+  const check = await world.nextMembership();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  expect(world.releasedMemberships).toEqual([]);
+
+  check.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.releasedMemberships).toEqual([["agent-a", "agent-b"]]));
+  world.sync.dispose();
+});
+
+test("losing the connection during a check releases both the check and what it replaced", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 1 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  (await world.nextMembership()).succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+  await world.nextMembership();
+  world.sync.setConnected(false);
+
+  await vi.waitFor(() => expect(world.releasedMemberships).toEqual([["agent-a"], ["agent-a"]]));
+  world.sync.dispose();
+});
+
+test("a replacement the daemon refuses still releases the subscription it replaced", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 1 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  (await world.nextMembership()).succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+  const check = await world.nextMembership();
+  check.fail("refused");
+
+  await vi.waitFor(() => expect(world.releasedMemberships).toEqual([["agent-a"]]));
+  world.sync.dispose();
+});
+
+test("foregrounding asks only about visible chats; hidden chats stay caught up", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 1 });
+  world.cursors.set("agent-b", { epoch: "epoch-b", endSeq: 2 });
+  world.openedEarlier(["agent-b"]);
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  (await world.nextMembership()).succeed({ "agent-a": "current", "agent-b": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-b")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+
+  const check = await world.nextMembership();
+  expect(check.agentIds).toEqual(["agent-a", "agent-b"]);
+  expect(check.cursors).toEqual({ "agent-a": { epoch: "epoch-a", seq: 1 } });
+  expect(world.sync.getAgentTimelineStatus("agent-b")).toBe("ready");
+  check.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.expectNoPendingFetch();
+  world.sync.dispose();
+});
+
+test("a gap found while the check is outstanding wins over a current answer", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+  const membership = await world.nextMembership();
+
+  world.sync.recoverGap("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.expectNoPendingFetch();
+  membership.succeed({ "agent-a": "current" });
+
+  const fetch = await world.nextFetch("agent-a");
+  expect(fetch.request).toMatchObject({ direction: "after", cursor: { seq: 42 } });
+  expect(world.appliedCurrent).toEqual([]);
+  fetch.respond({ hasNewer: false });
+  world.sync.dispose();
+});
+
+test("a failed check reports the error and retries through membership", async () => {
+  const world = freshnessWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+
+  (await world.nextMembership()).fail("subscribe failed");
+
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("error"));
+  world.sync.retryVisibleAgentTimeline("agent-a");
+  const retry = await world.nextMembership();
+  expect(retry.cursors).toEqual({ "agent-a": { epoch: "epoch-a", seq: 42 } });
+  retry.succeed({ "agent-a": "current" });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+  world.sync.dispose();
+});
+
+test("reconnecting reports reattaching instead of pending until the check answers", async () => {
+  vi.useFakeTimers();
+  try {
+    const world = freshnessWorld();
+    world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+    world.show("pane", ["agent-a"]);
+    world.sync.setConnected(true);
+    (await world.nextMembership()).succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+
+    world.sync.setConnected(false);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("reattaching");
+    world.sync.setConnected(true);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("reattaching");
+
+    const check = await world.nextMembership();
+    await vi.advanceTimersByTimeAsync(FRESHNESS_CHECK_QUIET_MS * 4);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("reattaching");
+
+    check.succeed({ "agent-a": "current" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready");
+    world.expectNoPendingFetch();
+    world.sync.dispose();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("without the daemon capability nothing changes: no cursors, no checking, fetch on foreground", async () => {
+  const world = new TimelineWorld();
+  world.cursors.set("agent-a", { epoch: "epoch-a", endSeq: 42 });
+  world.show("pane", ["agent-a"]);
+  world.sync.setConnected(true);
+
+  const membership = await world.nextMembership();
+  expect(membership.cursors).toBeUndefined();
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+  membership.succeed();
+  const first = await world.nextFetch("agent-a");
+  expect(first.request.direction).toBe("after");
+  first.respond({ hasNewer: false });
+  await vi.waitFor(() => expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("ready"));
+
+  world.sync.setActive(false);
+  world.sync.setActive(true);
+
+  expect(world.sync.getAgentTimelineStatus("agent-a")).toBe("pending");
+  expect((await world.nextFetch("agent-a")).request.direction).toBe("after");
+  world.expectNoPendingMembership();
+  world.sync.dispose();
+});
diff --git a/packages/app/src/timeline/viewed-timeline-sync.ts b/packages/app/src/timeline/viewed-timeline-sync.ts
index 58142c918c..ab8fe896ca 100644
--- a/packages/app/src/timeline/viewed-timeline-sync.ts
+++ b/packages/app/src/timeline/viewed-timeline-sync.ts
@@ -6,12 +6,13 @@ import {
 import type { CachedTimeline } from "@/runtime/replica-cache";
 import {
   selectAgentTimelineState,
+  selectAgentUnsettledTurn,
   useSessionStore,
   type AgentTimelineCursorState,
   type AgentTimelineState,
 } from "@/stores/session-store";
 import { useCreateFlowStore } from "@/stores/create-flow-store";
-import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import type { AgentSnapshotPayload, SessionOutboundMessage } from "@getpaseo/protocol/messages";
 import { getSendingClientMessageIds } from "@/composer/submission/model";
 import {
   getInitDeferred,
@@ -21,12 +22,14 @@ import {
 } from "@/utils/agent-initialization";
 import {
   createSessionAgentStreamReducerQueue,
+  deriveAgentStreamTurnLiveness,
   type AgentStreamReducerEvent,
   type ProcessTimelineResponseOutput,
   processTimelineResponse,
 } from "./session-stream-reducers";
 import { isTimelineResumeSnapshotAuthoritative } from "./timeline-sync-plan";
 import { replaceWithCanonicalStream } from "@/types/stream";
+import type { TurnLivenessTransition } from "./turn-liveness";
 
 export interface TimelineReplicaStorage {
   readTimeline(serverId: string, agentId: string): Promise<CachedTimeline | undefined>;
@@ -38,6 +41,7 @@ async function prepareCachedTimeline(input: {
   agentId: string;
   storage: TimelineReplicaStorage;
   prepareAgent: (agentId: string) => Promise<void>;
+  isTurnSettled: () => boolean;
 }): Promise<CachedTimeline | undefined> {
   const before = useSessionStore.getState().sessions[input.serverId];
   const beforeTimeline = selectAgentTimelineState(before, input.agentId);
@@ -85,6 +89,7 @@ async function prepareCachedTimeline(input: {
     newer: false,
     synchronized: false,
     acknowledgedClientMessageIds: replacement.acknowledgedClientMessageIds,
+    unsettledTurn: input.isTurnSettled() ? undefined : stored.unsettledTurn,
   });
   return stored;
 }
@@ -94,11 +99,16 @@ export interface TimelineReplica {
   readCursor(agentId: string): { epoch: string; endSeq: number } | undefined;
   readRange(agentId: string): AgentTimelineCursorState | undefined;
   timelineUpdated(agentId: string): void;
+  catchUpOwed(agentId: string): void;
+  catchUpSettled(agentId: string): void;
 }
 
 class TimelineReplicaOwner implements TimelineReplica {
   private readonly cachedRanges = new Map<string, AgentTimelineCursorState>();
   private readonly preparations = new Map<string, Promise<void>>();
+  // A cache read in flight still carries the turn as it was saved. Once the catch-up has
+  // settled, that turn must not come back with the cached messages.
+  private readonly settledDuringPreparation = new Set<string>();
 
   constructor(
     private readonly serverId: string,
@@ -121,6 +131,7 @@ class TimelineReplicaOwner implements TimelineReplica {
     const preparation = this.load(agentId).finally(() => {
       if (this.preparations.get(agentId) === preparation) {
         this.preparations.delete(agentId);
+        this.settledDuringPreparation.delete(agentId);
       }
     });
     this.preparations.set(agentId, preparation);
@@ -133,6 +144,7 @@ class TimelineReplicaOwner implements TimelineReplica {
       agentId,
       storage: this.storage,
       prepareAgent: this.prepareAgent,
+      isTurnSettled: () => this.settledDuringPreparation.has(agentId),
     });
     if (!stored) return;
     if (stored.range) {
@@ -159,8 +171,21 @@ class TimelineReplicaOwner implements TimelineReplica {
       items: [...timeline.items, ...(session?.agentStreamHead.get(agentId) ?? [])],
       range: timeline.status === "synced" ? timeline.range : null,
       hasOlder: timeline.status === "synced" && timeline.older === "available",
+      unsettledTurn: selectAgentUnsettledTurn(session, agentId),
     });
   }
+
+  catchUpOwed(agentId: string): void {
+    this.settledDuringPreparation.delete(agentId);
+    const store = useSessionStore.getState();
+    const openTurn = selectAgentUnsettledTurn(store.sessions[this.serverId], agentId);
+    if (openTurn) store.setAgentTimelineUnsettledTurn(this.serverId, agentId, openTurn);
+  }
+
+  catchUpSettled(agentId: string): void {
+    if (this.preparations.has(agentId)) this.settledDuringPreparation.add(agentId);
+    useSessionStore.getState().setAgentTimelineUnsettledTurn(this.serverId, agentId, null);
+  }
 }
 
 export function createTimelineReplica(input: {
@@ -238,6 +263,7 @@ function commitProcessedTimeline(input: {
     });
   }
   store.markAgentHistorySynchronized(serverId, agentId);
+  if (synchronized) store.setAgentTimelineUnsettledTurn(serverId, agentId, null);
 }
 
 function finalizeProcessedTimeline(input: {
@@ -313,10 +339,56 @@ function applyAuthoritativeTimelineResponse(input: {
   return true;
 }
 
+/**
+ * Measured on a dev daemon: set_subscription answers in a mean of 1.4 ms, p99 per-window max
+ * 107 ms, max 227 ms. A check slower than this is slow enough to say so on screen.
+ */
+export const FRESHNESS_CHECK_QUIET_MS = 500;
+
+export type TimelineFreshness = "current" | "behind";
+
+/** The empty after page the daemon would have returned for a cursor already at the head. */
+function buildCurrentTimelinePage(
+  agentId: string,
+  cursor: { epoch: string; endSeq: number },
+): TimelineResponsePayload {
+  return {
+    requestId: "",
+    agentId,
+    agent: null,
+    direction: "after",
+    projection: "projected",
+    epoch: cursor.epoch,
+    reset: false,
+    staleCursor: false,
+    gap: false,
+    window: { minSeq: 0, maxSeq: cursor.endSeq, nextSeq: cursor.endSeq + 1 },
+    startCursor: null,
+    endCursor: null,
+    hasOlder: false,
+    hasNewer: false,
+    entries: [],
+    error: null,
+  };
+}
+
 export interface ViewedTimelineSyncPorts {
   prepare(agentId: string): Promise<void>;
   replaceDemandedAgentIds(agentIds: string[]): void;
-  observe(agentIds: string[]): { ready: Promise<unknown>; release(): Promise<void> };
+  /** Whether the daemon answers with each cursor's freshness in the subscribe response. */
+  canCheckFreshness(): boolean;
+  observe(
+    agentIds: string[],
+    cursors?: Record<string, { epoch: string; seq: number }>,
+  ): {
+    ready: Promise<{
+      timelines?: Record<string, TimelineFreshness>;
+      agents?: Record<string, AgentSnapshotPayload>;
+    } | void>;
+    release(): Promise<void>;
+  };
+  /** The daemon confirmed the cached timeline is at its head, as a zero-row after page would. */
+  applyCurrentTimeline(agentId: string): void;
   readCursor(agentId: string): { epoch: string; endSeq: number } | undefined;
   fetchPage(
     agentId: string,
@@ -328,10 +400,30 @@ export interface ViewedTimelineSyncPorts {
    * demanded set. Disconnect and backgrounding keep the obligation and do not report here.
    */
   onCatchUpEnded(agentId: string): void;
+  /** The chat stopped receiving every row, so a catch-up is owed before it is current again. */
+  onCatchUpOwed(agentId: string): void;
+  /** The owed catch-up reached current or failed. The chat can take the true turn status. */
+  onCatchUpSettled(agentId: string): void;
   reportError(error: unknown): void;
 }
 
-export type ViewedTimelineStatus = "ready" | "pending" | "error" | "retrying";
+/**
+ * Why a freshness check was asked: opening a chat, the socket coming back, or the app
+ * returning to the foreground on a socket that stayed connected.
+ */
+type FreshnessCheckReason = "open" | "reconnect" | "resume";
+
+/**
+ * "checking": the daemon has not said whether this chat is current; nothing to report yet.
+ * "reattaching": the same question right after a reconnect, so the chat is still not back.
+ */
+export type ViewedTimelineStatus =
+  | "ready"
+  | "checking"
+  | "reattaching"
+  | "pending"
+  | "error"
+  | "retrying";
 
 export interface ViewedTimelineUiBridge {
   replaceVisibleAgentIds(sourceId: string, agentIds: string[]): void;
@@ -356,7 +448,12 @@ export interface ViewedTimelineSync extends ViewedTimelineUiBridge {
 
 export type ViewedTimelineOwnerPorts = Omit<
   ViewedTimelineSyncPorts,
-  "prepare" | "replaceDemandedAgentIds" | "onCatchUpEnded"
+  | "prepare"
+  | "replaceDemandedAgentIds"
+  | "onCatchUpEnded"
+  | "onCatchUpOwed"
+  | "onCatchUpSettled"
+  | "applyCurrentTimeline"
 >;
 
 /**
@@ -367,7 +464,12 @@ export type TimelineResponseOutcome = "applied" | "stale";
 
 export interface ViewedTimelineOwner extends ViewedTimelineSync {
   applyTimelineResponse(payload: TimelineResponsePayload): TimelineResponseOutcome;
-  enqueueStreamEvent(agentId: string, event: AgentStreamReducerEvent): void;
+  /**
+   * Accepts one live stream event. Content is coalesced to the next frame; a turn boundary
+   * commits the turn's queued content before its liveness changes, so the view never shows
+   * a finished turn without its final reply.
+   */
+  applyStreamEvent(agentId: string, event: AgentStreamReducerEvent): void;
   flushStreamAgent(agentId: string): void;
 }
 
@@ -407,6 +509,7 @@ export function createViewedTimelineOwner(input: {
   replica: TimelineReplica;
   replaceDemandedAgentIds: (agentIds: string[]) => void;
   drainQueuedAgentMessage: (agentId: string) => void;
+  applyTurnLiveness: (agentId: string, transitions: readonly TurnLivenessTransition[]) => void;
   ports: ViewedTimelineOwnerPorts;
 }): ViewedTimelineOwner {
   const forcedTailReplacements = new Set<string>();
@@ -424,8 +527,22 @@ export function createViewedTimelineOwner(input: {
     prepare: (agentId) => input.replica.prepare(agentId),
     readCursor: (agentId) => input.replica.readCursor(agentId) ?? input.ports.readCursor(agentId),
     replaceDemandedAgentIds: input.replaceDemandedAgentIds,
+    applyCurrentTimeline: (agentId) => {
+      const cursor = input.replica.readCursor(agentId) ?? input.ports.readCursor(agentId);
+      if (!cursor) return;
+      const accepted = applyAuthoritativeTimelineResponse({
+        serverId: input.serverId,
+        payload: buildCurrentTimelinePage(agentId, cursor),
+        cachedCursor: input.replica.readRange(agentId),
+        recoverGap: (id, gapCursor) => sync.recoverGap(id, gapCursor),
+        drainQueuedAgentMessage: input.drainQueuedAgentMessage,
+      });
+      if (accepted) input.replica.timelineUpdated(agentId);
+    },
     onCatchUpEnded: (agentId) =>
       useCreateFlowStore.getState().clearByAgent({ serverId: input.serverId, agentId }),
+    onCatchUpOwed: (agentId) => input.replica.catchUpOwed(agentId),
+    onCatchUpSettled: (agentId) => input.replica.catchUpSettled(agentId),
   });
   const streamQueue = createSessionAgentStreamReducerQueue({
     serverId: input.serverId,
@@ -450,11 +567,16 @@ export function createViewedTimelineOwner(input: {
       if (accepted) input.replica.timelineUpdated(payload.agentId);
       return "applied";
     },
-    enqueueStreamEvent(agentId, event) {
+    applyStreamEvent(agentId, event) {
       if (event.event.type === "rewind" && event.epoch !== undefined && event.seq !== undefined) {
         retirements.note(agentId, { epoch: event.epoch, seq: event.seq });
       }
       streamQueue.enqueue(agentId, event);
+      const turnLiveness = deriveAgentStreamTurnLiveness([event]);
+      if (turnLiveness.length === 0) return;
+      streamQueue.flushAgent(agentId);
+      input.applyTurnLiveness(agentId, turnLiveness);
+      input.replica.timelineUpdated(agentId);
     },
     flushStreamAgent(agentId) {
       streamQueue.flushAgent(agentId);
@@ -527,6 +649,16 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
   const manualRetries = new Set<string>();
   const loadedCache = new Set<string>();
   const cacheLoads = new Map<string, Promise<void>>();
+  // Chats whose freshness answer is outstanding. No catch-up starts for them until it arrives.
+  // An "open" check stays `quiet`, short of "pending", until FRESHNESS_CHECK_QUIET_MS elapses.
+  const freshnessChecks = new Map<
+    string,
+    {
+      reason: FreshnessCheckReason;
+      quiet: boolean;
+      timer: ReturnType<typeof setTimeout> | null;
+    }
+  >();
   const listeners = new Set<() => void>();
   let active = true;
   let connected = false;
@@ -539,6 +671,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
   let acknowledged: string[] = [];
   let membershipGeneration = 0;
   let membershipNeedsRetry = false;
+  let freshnessCheckOwed = false;
   // Chats this session has opened. Visibility is the only way in, so an agent is never
   // subscribed — and never resumed on the daemon — until the user actually opens it.
   // Membership then survives hiding, workspace switches, backgrounding and reconnect;
@@ -569,6 +702,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     const wasPending = visibilityCatchUpPending.delete(agentId);
     const hadError = visibilityCatchUpErrors.delete(agentId);
     const wasRetrying = manualRetries.delete(agentId);
+    ports.onCatchUpSettled(agentId);
     ports.onCatchUpEnded(agentId);
     if (wasPending || hadError || wasRetrying) notifyListeners();
   };
@@ -577,6 +711,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     const message = error instanceof Error ? error.message : String(error);
     let changed = false;
     for (const agentId of agentIds) {
+      ports.onCatchUpSettled(agentId);
       if (manualRetries.delete(agentId)) changed = true;
       if (visibilityCatchUpPending.delete(agentId)) changed = true;
       if (visibilityCatchUpErrors.get(agentId) !== message) {
@@ -587,6 +722,41 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     if (changed) notifyListeners();
   };
 
+  const markCatchUpOwed = (agentId: string) => {
+    visibilityCatchUpPending.add(agentId);
+    ports.onCatchUpOwed(agentId);
+  };
+
+  const startFreshnessCheck = (agentId: string, reason: FreshnessCheckReason = "open") => {
+    if (freshnessChecks.has(agentId)) return;
+    freshnessChecks.set(agentId, { reason, quiet: true, timer: null });
+  };
+
+  // The delay measures the daemon's answer, so it starts when the question is sent. On a cold
+  // start the cache read that precedes the question can outlast it on its own. Only opening a
+  // chat escalates. A reconnect already shows Reconnecting to host until the answer. A resume
+  // kept its socket subscribed, so a slow answer is no reason to doubt the chat; a socket that
+  // died quietly is caught by the foreground liveness probe and becomes a reconnect.
+  const startFreshnessCheckDelay = (agentId: string) => {
+    const check = freshnessChecks.get(agentId);
+    if (!check || check.timer || check.reason !== "open") return;
+    check.timer = setTimeout(() => {
+      check.quiet = false;
+      notifyListeners();
+    }, FRESHNESS_CHECK_QUIET_MS);
+  };
+
+  const endFreshnessCheck = (agentId: string) => {
+    const check = freshnessChecks.get(agentId);
+    if (!check) return;
+    if (check.timer) clearTimeout(check.timer);
+    freshnessChecks.delete(agentId);
+  };
+
+  const endAllFreshnessChecks = () => {
+    for (const agentId of freshnessChecks.keys()) endFreshnessCheck(agentId);
+  };
+
   const cancelCatchUp = (agentId: string) => {
     catchUpGenerations.set(agentId, (catchUpGenerations.get(agentId) ?? 0) + 1);
     catchUps.delete(agentId);
@@ -676,6 +846,10 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     } = {},
   ) => {
     const { request, supersede = false } = options;
+    if (freshnessChecks.has(agentId)) {
+      if (request) pendingCatchUps.set(agentId, request);
+      return;
+    }
     if (!canCatchUp(agentId)) {
       if (request) pendingCatchUps.set(agentId, request);
       return;
@@ -730,30 +904,98 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     }
   };
 
+  const membershipIsSettled = (requested: string[]) =>
+    !membershipNeedsRetry &&
+    !freshnessCheckOwed &&
+    sameAgentIds(requested, observation?.agentIds ?? acknowledged);
+
+  // A chat with no fetch running and a cursor to compare; the daemon can answer without a fetch.
+  const collectFreshnessCursors = (requested: string[]) => {
+    const cursors: Record<string, { epoch: string; seq: number }> = {};
+    for (const agentId of requested) {
+      if (catchUps.has(agentId) || pendingCatchUps.has(agentId)) continue;
+      const cursor = ports.readCursor(agentId);
+      if (cursor) cursors[agentId] = { epoch: cursor.epoch, seq: cursor.endSeq };
+    }
+    return cursors;
+  };
+
+  const completeCurrentCatchUp = (agentId: string) => {
+    const generation = (catchUpGenerations.get(agentId) ?? 0) + 1;
+    catchUpGenerations.set(agentId, generation);
+    catchUps.set(agentId, { generation, status: "complete" });
+    ports.applyCurrentTimeline(agentId);
+    setVisibilityCatchUpReady(agentId);
+  };
+
+  const applyFreshnessAnswer = (
+    checked: string[],
+    timelines: Record<string, TimelineFreshness> | undefined,
+  ) => {
+    for (const agentId of checked) {
+      endFreshnessCheck(agentId);
+      // A gap found during the check still needs its fetch; "current" only speaks for the cursor.
+      if (timelines?.[agentId] === "current" && !pendingCatchUps.has(agentId)) {
+        completeCurrentCatchUp(agentId);
+      }
+    }
+    if (checked.length > 0) notifyListeners();
+  };
+
+  const isReconcileSuperseded = (generation: number) =>
+    disposed || !connected || generation !== membershipGeneration;
+
+  const askDaemonAboutFreshness = (checked: string[]) => {
+    for (const agentId of checked) {
+      startFreshnessCheck(agentId);
+      startFreshnessCheckDelay(agentId);
+    }
+    for (const agentId of freshnessChecks.keys()) {
+      if (!checked.includes(agentId)) endFreshnessCheck(agentId);
+    }
+  };
+
   const reconcileMembership = async (): Promise<void> => {
     if (disposed || !connected) return;
     const generation = membershipGeneration;
     const requested = desired;
-    if (!membershipNeedsRetry && sameAgentIds(requested, observation?.agentIds ?? acknowledged))
-      return;
+    if (membershipIsSettled(requested)) return;
+    const canCheck = ports.canCheckFreshness();
+    if (canCheck) {
+      // The cursor sent to the daemon must include whatever the cache restores.
+      await Promise.all(requested.map((agentId) => cacheLoads.get(agentId)));
+      if (isReconcileSuperseded(generation)) return;
+      if (membershipIsSettled(requested)) return;
+    }
     membershipNeedsRetry = false;
+    freshnessCheckOwed = false;
+    const cursors = canCheck ? collectFreshnessCursors(requested) : undefined;
+    const checked = Object.keys(cursors ?? {});
+    askDaemonAboutFreshness(checked);
+    notifyListeners();
+    let timelines: Record<string, TimelineFreshness> | undefined;
     try {
       const previous = observation;
-      const handle = ports.observe(requested);
+      const handle = ports.observe(requested, cursors);
       observation = { handle, agentIds: requested };
-      void previous?.handle.release().catch(ports.reportError);
-      await handle.ready;
+      // A subscription routes events only once the daemon accepts it, so the old one delivers until then.
+      const answer = await handle.ready.finally(() => {
+        void previous?.handle.release().catch(ports.reportError);
+      });
+      timelines = answer ? answer.timelines : undefined;
     } catch (error) {
-      if (disposed || !connected || generation !== membershipGeneration) return;
+      if (isReconcileSuperseded(generation)) return;
       membershipNeedsRetry = true;
       acknowledged = [];
+      for (const agentId of checked) endFreshnessCheck(agentId);
       for (const agentId of requested) cancelCatchUp(agentId);
       setVisibilityCatchUpError(requested, error);
       ports.reportError(error);
       return;
     }
-    if (disposed || !connected || generation !== membershipGeneration) return;
+    if (isReconcileSuperseded(generation)) return;
     acknowledged = requested;
+    applyFreshnessAnswer(checked, timelines);
     startAcknowledgedCatchUps();
   };
 
@@ -781,7 +1023,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     if (options.resetCatchUpStatus) {
       for (const agentId of nextDesired) {
         if (!visibilityCatchUpPending.has(agentId)) {
-          visibilityCatchUpPending.add(agentId);
+          markCatchUpOwed(agentId);
           statusChanged = true;
         }
         if (visibilityCatchUpErrors.delete(agentId)) statusChanged = true;
@@ -797,17 +1039,20 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     for (const agentId of desired) {
       if (!nextDesired.includes(agentId)) {
         cancelCatchUp(agentId);
+        endFreshnessCheck(agentId);
         visibilityCatchUpPending.delete(agentId);
         visibilityCatchUpErrors.delete(agentId);
         manualRetries.delete(agentId);
+        ports.onCatchUpOwed(agentId);
         released.push(agentId);
       }
     }
     for (const agentId of nextDesired) {
       if (!desired.includes(agentId)) {
-        visibilityCatchUpPending.add(agentId);
+        markCatchUpOwed(agentId);
         visibilityCatchUpErrors.delete(agentId);
         manualRetries.delete(agentId);
+        if (connected && ports.canCheckFreshness()) startFreshnessCheck(agentId);
         ensureCacheLoaded(agentId);
       }
     }
@@ -819,6 +1064,19 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     void reconcileMembership();
   };
 
+  // A render can see the connection return, or a chat become visible, before this owner hears
+  // about it, so those two states answer as if the check had already started.
+  const getUnconfirmedStatus = (agentId: string): ViewedTimelineStatus => {
+    const check = freshnessChecks.get(agentId);
+    if (check) {
+      if (check.reason === "reconnect") return "reattaching";
+      return check.quiet ? "checking" : "pending";
+    }
+    if (!ports.canCheckFreshness()) return "pending";
+    if (!connected) return "reattaching";
+    return isDesired(agentId) ? "pending" : "checking";
+  };
+
   const publishVisibleMembership = () => {
     commitDesiredMembership(normalizeAgentIds([...openedAgentIds, ...visibleAgentIds()]));
   };
@@ -831,8 +1089,8 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
     getAgentTimelineStatus(agentId) {
       if (manualRetries.has(agentId)) return "retrying";
       if (visibilityCatchUpErrors.has(agentId)) return "error";
-      if (!isDesired(agentId) || visibilityCatchUpPending.has(agentId)) return "pending";
-      return "ready";
+      if (isDesired(agentId) && !visibilityCatchUpPending.has(agentId)) return "ready";
+      return getUnconfirmedStatus(agentId);
     },
     getAgentTimelineError(agentId) {
       return visibilityCatchUpErrors.get(agentId) ?? null;
@@ -860,12 +1118,27 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
         startAcknowledgedCatchUps();
         return;
       }
+      const canCheck = connected && ports.canCheckFreshness();
       for (const agentId of visibleAgentIds()) {
         if (visibilityCatchUpErrors.has(agentId)) continue;
-        visibilityCatchUpPending.add(agentId);
-        visibilityCatchUpErrors.delete(agentId);
+        markCatchUpOwed(agentId);
+        if (
+          canCheck &&
+          catchUps.get(agentId)?.status === "complete" &&
+          !pendingCatchUps.has(agentId) &&
+          ports.readCursor(agentId)
+        ) {
+          catchUps.delete(agentId);
+          startFreshnessCheck(agentId, "resume");
+          freshnessCheckOwed = true;
+          continue;
+        }
         startCatchUp(agentId, { supersede: true });
       }
+      if (freshnessCheckOwed) {
+        membershipGeneration += 1;
+        void reconcileMembership();
+      }
       notifyListeners();
     },
     setConnected(nextConnected) {
@@ -877,10 +1150,18 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
         observation = null;
         acknowledged = [];
         membershipGeneration += 1;
+        freshnessCheckOwed = false;
+        endAllFreshnessChecks();
         for (const agentId of desired) cancelCatchUp(agentId);
         return;
       }
+      if (ports.canCheckFreshness()) {
+        for (const agentId of desired) {
+          if (visibilityCatchUpPending.has(agentId)) startFreshnessCheck(agentId, "reconnect");
+        }
+      }
       membershipGeneration += 1;
+      notifyListeners();
       void reconcileMembership();
     },
     recoverGap(agentId, cursor) {
@@ -907,6 +1188,7 @@ export function createViewedTimelineSync(ports: ViewedTimelineSyncPorts): Viewed
       visibilityCatchUpPending.clear();
       visibilityCatchUpErrors.clear();
       manualRetries.clear();
+      endAllFreshnessChecks();
       notifyListeners();
       listeners.clear();
     },
diff --git a/packages/app/src/tool-calls/detail-level/overview/view.tsx b/packages/app/src/tool-calls/detail-level/overview/view.tsx
index b11e82e4f7..b05fbe1edd 100644
--- a/packages/app/src/tool-calls/detail-level/overview/view.tsx
+++ b/packages/app/src/tool-calls/detail-level/overview/view.tsx
@@ -2,6 +2,7 @@ import React, { memo, useCallback, useRef, type ReactNode } from "react";
 import { ScrollView } from "react-native";
 import { Wrench } from "lucide-react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { IndentRail } from "@/components/indent-rail";
 import { ExpandableBadge } from "@/components/message";
 import { useIsCompactFormFactor } from "@/constants/layout";
@@ -32,9 +33,13 @@ export const OverviewToolCallGroupView = memo(function OverviewToolCallGroupView
   const scrollToLatest = useCallback(() => {
     scrollRef.current?.scrollToEnd({ animated: false });
   }, []);
+  const hold = useDisclosureHold();
   const toggle = useCallback(() => {
-    onExpandedChange(group.run.id, !expanded);
-  }, [expanded, group.run.id, onExpandedChange]);
+    const apply = () => onExpandedChange(group.run.id, !expanded);
+    // Compact opens a sheet; nothing in the timeline moves.
+    if (isCompact) apply();
+    else hold(apply);
+  }, [expanded, group.run.id, hold, isCompact, onExpandedChange]);
   const close = useCallback(() => {
     onExpandedChange(group.run.id, false);
   }, [group.run.id, onExpandedChange]);
diff --git a/packages/app/src/tool-calls/presentation.test.ts b/packages/app/src/tool-calls/presentation.test.ts
index fc609ee8f6..7fb26cdcc8 100644
--- a/packages/app/src/tool-calls/presentation.test.ts
+++ b/packages/app/src/tool-calls/presentation.test.ts
@@ -58,6 +58,24 @@ describe("tool-call presentation", () => {
     });
   });
 
+  it("shows a shell call awaiting its command as Shell, loading its details", () => {
+    const presentation = buildToolCallPresentation({
+      toolName: "Bash",
+      status: "running",
+      error: null,
+      detail: { type: "shell", command: "" },
+      resolveIcon: fakeResolveIcon,
+    });
+
+    expect(presentation).toMatchObject({
+      displayName: "Shell",
+      summary: undefined,
+      isLoadingDetails: true,
+      hasDetails: false,
+      canOpenDetails: true,
+    });
+  });
+
   it("marks running calls without meaningful detail as loading details", () => {
     const presentation = buildToolCallPresentation({
       toolName: "exec_command",
diff --git a/packages/app/src/types/agent-directory.ts b/packages/app/src/types/agent-directory.ts
index 8ac1870a6f..9021c10786 100644
--- a/packages/app/src/types/agent-directory.ts
+++ b/packages/app/src/types/agent-directory.ts
@@ -6,6 +6,7 @@ export type AgentDirectoryEntry = Pick<
   | "serverId"
   | "title"
   | "status"
+  | "backgroundWork"
   | "turn"
   | "lastActivityAt"
   | "cwd"
diff --git a/packages/app/src/types/stream.ts b/packages/app/src/types/stream.ts
index e8597ccabc..db8e6955b2 100644
--- a/packages/app/src/types/stream.ts
+++ b/packages/app/src/types/stream.ts
@@ -8,6 +8,7 @@ import type {
 import { timelineItemIdentity } from "@getpaseo/protocol/timeline-identity";
 import type { AgentAttachment, AgentStreamEventPayload } from "@getpaseo/protocol/messages";
 import type { AttachmentMetadata } from "@/attachments/types";
+import type { OverviewSummary } from "@/tool-calls/detail-level/overview/model";
 import { extractTaskEntriesFromToolCall } from "../utils/tool-call-parsers";
 
 /**
@@ -86,7 +87,8 @@ export type StreamItem =
   | TodoListItem
   | NotificationItem
   | CompactionItem
-  | PluginTimelineStreamItem;
+  | PluginTimelineStreamItem
+  | TurnSummaryItem;
 
 export type UserMessageImageAttachment = AttachmentMetadata;
 
@@ -845,6 +847,8 @@ export interface PluginTimelineStreamItem {
   id: string;
   /** The id of the stream item a timeline transformer replaced; set only by projection. */
   sourceId?: string;
+  /** The original row kind, retained by projection for turn folding. */
+  sourceKind?: StreamItem["kind"];
   timelineCursor?: TimelinePosition;
   turnId?: string;
   timestamp: Date;
@@ -855,6 +859,25 @@ export interface PluginTimelineStreamItem {
   data: JsonValue;
 }
 
+/**
+ * The row a folded turn leaves between its host and its reply, standing in for the work it
+ * hides. Turn collapse produces it from the loaded rows; it is never stored.
+ */
+export interface TurnSummaryItem {
+  kind: "turn_summary";
+  id: string;
+  timelineCursor?: TimelinePosition;
+  turnId?: string;
+  timestamp: Date;
+  /**
+   * The prompt the turn folds under, or its first loaded tool call when the prompt is above the
+   * loaded history. Keys the reader's expanded turns.
+   */
+  hostId: string;
+  expanded: boolean;
+  tools: OverviewSummary;
+}
+
 export interface TodoEntry {
   text: string;
   completed: boolean;
diff --git a/packages/app/src/types/turndown-plugin-gfm.d.ts b/packages/app/src/types/turndown-plugin-gfm.d.ts
index a6c0855cf9..3562d8bfbd 100644
--- a/packages/app/src/types/turndown-plugin-gfm.d.ts
+++ b/packages/app/src/types/turndown-plugin-gfm.d.ts
@@ -1,5 +1,6 @@
 declare module "turndown-plugin-gfm" {
   import type TurndownService from "turndown";
 
+  export const tables: TurndownService.Plugin;
   export const gfm: TurndownService.Plugin;
 }
diff --git a/packages/app/src/usage/options.tsx b/packages/app/src/usage/options.tsx
index 44205fbddd..cc674cb90f 100644
--- a/packages/app/src/usage/options.tsx
+++ b/packages/app/src/usage/options.tsx
@@ -79,7 +79,6 @@ export function UsageOptions({ serverId }: { serverId: string | null }) {
                 options={displayAsOptions}
                 value={display.displayAs}
                 onValueChange={display.setDisplayAs}
-                size="sm"
                 testID="usage-display-as"
               />
             </SettingsRow>
diff --git a/packages/app/src/usage/queries.ts b/packages/app/src/usage/queries.ts
index 524972a010..26a7fa62ea 100644
--- a/packages/app/src/usage/queries.ts
+++ b/packages/app/src/usage/queries.ts
@@ -33,9 +33,10 @@ import {
 } from "./model";
 import type { UsageReportEntry, UsageView } from "./types";
 
-// The daemon caches each report for five minutes, so re-reading it is cheap. Only
-// an explicit refresh passes `forceRefresh` and reaches the source's API.
+// The daemon caches each report for five minutes, so re-reading it is cheap.
+// An explicit refresh passes `forceRefresh` to bypass that cache.
 const REPORTS_STALE_TIME_MS = 60_000;
+const REPORTS_REFETCH_INTERVAL_MS = 5 * 60_000;
 
 /** Every report list of a host: its own and each agent's. */
 function hostUsageQueryKey(serverId: string) {
@@ -46,8 +47,16 @@ function usageReportsQueryKey(serverId: string) {
   return [...hostUsageQueryKey(serverId), "reports"] as const;
 }
 
-function agentUsageQueryKey(serverId: string, agentId: string) {
-  return [...hostUsageQueryKey(serverId), "agent", agentId] as const;
+function agentUsageQueryKey(serverId: string, agentId: string, usageScopeKey: string | undefined) {
+  return [...hostUsageQueryKey(serverId), "agent", agentId, usageScopeKey ?? null] as const;
+}
+
+function useAgentUsageScopeKey(serverId: string, agentId: string | undefined) {
+  return useSessionStore((state) =>
+    agentId === undefined
+      ? undefined
+      : state.sessions[serverId]?.agents.get(agentId)?.usageScopeKey,
+  );
 }
 
 function requireClient(serverId: string) {
@@ -164,11 +173,16 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =
 
 const NO_REPORTS: UsageReportEntry[] = [];
 
-/**
- * The reports of the sidebar's usage host, which is connected and reports usage; none until they
- * load, or without a host.
- */
-export function useUsageHostReports(serverId: string | null): UsageReportEntry[] {
+interface UsageHostReportsInput {
+  serverId: string | null;
+  shouldPoll?: boolean;
+}
+
+/** A host's reports, with periodic refresh enabled only by the visible sidebar summary. */
+export function useUsageHostReports({
+  serverId,
+  shouldPoll = false,
+}: UsageHostReportsInput): UsageReportEntry[] {
   const setting = useUsageSetting(serverId);
   const queryClient = useQueryClient();
   const query = useFetchQuery({
@@ -177,30 +191,32 @@ export function useUsageHostReports(serverId: string | null): UsageReportEntry[]
     queryFn: serverId ? () => listReports(queryClient, serverId) : skipToken,
     dataShape: "list",
     staleTimeMs: REPORTS_STALE_TIME_MS,
+    refetchInterval: shouldPoll ? REPORTS_REFETCH_INTERVAL_MS : false,
   });
   return setting.enabled ? (query.data ?? NO_REPORTS) : NO_REPORTS;
 }
 
 /**
  * The reports of the account an agent runs under, as its meter's tooltip or sheet shows them.
- * Fetched while either is mounted, so only while it is open.
+ * Fetched while either is mounted, so only while it is open. Kept in the cache between opens, so
+ * the first frame of a reopen shows them while its own request refreshes them.
  */
 export function useAgentUsage(serverId: string, agentId: string): AgentUsageView {
   const queryClient = useQueryClient();
   const canReport = useHostReportsUsage(serverId);
-  const queryKey = agentUsageQueryKey(serverId, agentId);
+  const usageScopeKey = useAgentUsageScopeKey(serverId, agentId);
+  const queryKey = agentUsageQueryKey(serverId, agentId, usageScopeKey);
   const query = useFetchQuery({
     queryKey,
-    // Consuming the signal cancels the request when the details close, so a reopen sends a new
-    // request instead of joining one scoped to the login the agent ran under before.
+    // Consuming the signal cancels the request when the details close, so a report still on its
+    // way cannot land under a scope the agent has since left.
     queryFn: ({ signal }) => streamReports({ queryClient, queryKey, serverId, agentId, signal }),
     enabled: canReport,
     // Another agent's reports never stand in while this one's load.
     dataShape: "value",
-    // Dropped as soon as the details close: an agent resumed under another login keeps its ID, so
-    // reports kept from an earlier open could show the old login. The daemon's cache keeps each
-    // open's request cheap.
-    gcTime: 0,
+    // COMPAT(agentUsageScopeKey): added in v0.15.4, remove after 2027-05-09. Without the key,
+    // an agent resumed under another login keeps its query, so its reports die with the details.
+    gcTime: usageScopeKey === undefined ? 0 : Infinity,
     // The daemon's errors (an unknown agent) do not heal on retry, and reopening the details
     // fetches again; retrying would hold the loading sentence for seconds instead.
     retry: false,
@@ -248,13 +264,14 @@ export function useReportRefresh(
   agentId?: string,
 ): { refresh: () => void; refreshState: UsageRefresh } {
   const queryClient = useQueryClient();
+  const usageScopeKey = useAgentUsageScopeKey(serverId, agentId);
   const mutation = useMutation({
     mutationFn: () => getReport(serverId, reportId, true, agentId),
     onSuccess: (report) => {
       queryClient.setQueryData<UsageReportEntry[]>(
         agentId === undefined
           ? usageReportsQueryKey(serverId)
-          : agentUsageQueryKey(serverId, agentId),
+          : agentUsageQueryKey(serverId, agentId, usageScopeKey),
         (reports) => (reports ? replaceReport(reports, reportId, report) : reports),
       );
     },
diff --git a/packages/app/src/usage/sidebar-item.tsx b/packages/app/src/usage/sidebar-item.tsx
index 437c0a929c..bd4dfeb65e 100644
--- a/packages/app/src/usage/sidebar-item.tsx
+++ b/packages/app/src/usage/sidebar-item.tsx
@@ -16,6 +16,8 @@ import {
   type PressableStateCallbackType,
 } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+import { useAppVisible } from "@/hooks/use-app-visible";
 import { builtinSidebarNavLabelKey } from "@/sidebar-nav/model";
 import { useUsageDisplay } from "./display";
 import { useUsageInSidebar } from "./in-sidebar";
@@ -36,9 +38,14 @@ import { UsageModal } from "./usage-modal";
 /** Each summary window with data on the usage host, under its source; empty while none has. */
 export function useUsageSummary(): readonly PinnedUsageSource[] {
   const { t } = useTranslation();
+  const active = useRetainedPanelActive();
+  const isAppVisible = useAppVisible();
   const { inSidebar } = useUsageInSidebar();
   const serverId = useUsageHostId();
-  const reports = useUsageHostReports(inSidebar ? serverId : null);
+  const reports = useUsageHostReports({
+    serverId: inSidebar ? serverId : null,
+    shouldPoll: active && inSidebar && isAppVisible,
+  });
   const { preferences } = useUsageDisplay(reports);
   return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }
diff --git a/packages/app/src/usage/usage-section.tsx b/packages/app/src/usage/usage-section.tsx
index 9c1e9354c1..1eae545f39 100644
--- a/packages/app/src/usage/usage-section.tsx
+++ b/packages/app/src/usage/usage-section.tsx
@@ -77,7 +77,7 @@ export function UsageBody({
         title={t("providerUsage.errorTitle")}
         description={view.message}
       >
-        <Button variant="outline" size="sm" onPress={onRefresh}>
+        <Button variant="outline" onPress={onRefresh}>
           {t("providerUsage.retry")}
         </Button>
       </Alert>
diff --git a/packages/app/src/utils/agent-attention.test.ts b/packages/app/src/utils/agent-attention.test.ts
index ac5a6f84f3..dcc8d6e197 100644
--- a/packages/app/src/utils/agent-attention.test.ts
+++ b/packages/app/src/utils/agent-attention.test.ts
@@ -1,269 +1,117 @@
 import { describe, expect, it } from "vitest";
-import type { Agent } from "@/stores/session-store";
-import { pickAttentionAgent, shouldClearAgentAttention } from "@/utils/agent-attention";
+import { createAgentAttentionController } from "./agent-attention";
 
-function createAgent(input: Partial<Agent> & Pick<Agent, "id">): Agent {
-  const { id, ...rest } = input;
-  return {
-    serverId: "server-1",
-    id,
-    provider: "codex",
-    status: "idle",
-    createdAt: new Date("2026-01-01T00:00:00.000Z"),
-    updatedAt: new Date("2026-01-01T00:00:00.000Z"),
-    lastUserMessageAt: null,
-    lastActivityAt: new Date("2026-01-01T00:00:00.000Z"),
-    capabilities: {
-      supportsStreaming: true,
-      supportsSessionPersistence: true,
-      supportsDynamicModes: true,
-      supportsMcpServers: true,
-      supportsReasoningStream: true,
-      supportsToolInvocations: true,
-    },
-    currentModeId: null,
-    availableModes: [],
-    pendingPermissions: [],
-    persistence: null,
-    title: null,
-    cwd: "/repo/worktree",
-    model: null,
-    parentAgentId: null,
-    labels: {},
-    requiresAttention: false,
-    attentionReason: null,
-    attentionTimestamp: null,
-    ...rest,
-    turn: rest.turn ?? { phase: "idle", cancellationRequestId: null },
-  };
-}
+describe("agent attention acknowledgement", () => {
+  function setup() {
+    const calls: string[] = [];
+    const errors: unknown[] = [];
+    const controller = createAgentAttentionController({
+      clear: async () => {
+        calls.push("clear");
+      },
+      onError: (failure) => errors.push(failure),
+    });
+    const state = {
+      focused: true,
+      ready: true,
+      requiresAttention: false,
+      attentionReason: "finished" as const,
+      focusRequest: null as object | null,
+    };
+    return { controller, state, calls, errors };
+  }
 
-describe("shouldClearAgentAttention", () => {
-  it("returns true only when the agent is connected and requires attention", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-      }),
-    ).toBe(true);
+  it("acknowledges entry, but keeps attention arriving while focused until another focus action", async () => {
+    const { controller, state, calls } = setup();
+    controller.update(state);
+    state.requiresAttention = true;
+    controller.update(state);
+    expect(calls).toEqual([]);
+    controller.update({ ...state, focusRequest: {} });
+    expect(calls).toEqual(["clear"]);
+    await Promise.resolve();
+    controller.update({ ...state, focusRequest: {} });
+    expect(calls).toEqual(["clear", "clear"]);
   });
 
-  it("returns false when the app is disconnected", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: false,
-        requiresAttention: true,
-        attentionReason: "finished",
-      }),
-    ).toBe(false);
+  it("clears on entry and never clears on leaving", async () => {
+    const { controller, state, calls } = setup();
+    controller.update({ ...state, requiresAttention: true });
+    expect(calls).toEqual(["clear"]);
+    await Promise.resolve();
+    controller.update({ ...state, focused: false, requiresAttention: true });
+    expect(calls).toEqual(["clear"]);
+    controller.update({ ...state, requiresAttention: true });
+    expect(calls).toEqual(["clear", "clear"]);
   });
 
-  it("returns false when attention is already clear", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: false,
-        attentionReason: null,
-      }),
-    ).toBe(false);
+  it("waits for connection and agent data before consuming entry", () => {
+    const { controller, state, calls } = setup();
+    controller.update({ ...state, ready: false });
+    controller.update({ ...state, requiresAttention: true });
+    expect(calls).toEqual(["clear"]);
   });
 
-  it("returns false for empty agent ids", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-      }),
-    ).toBe(false);
+  it("does not treat reconnecting as another focus action", () => {
+    const { controller, state, calls } = setup();
+    controller.update(state);
+    controller.update({ ...state, requiresAttention: true });
+    controller.update({ ...state, requiresAttention: true, ready: false });
+    controller.update({ ...state, requiresAttention: true });
+    expect(calls).toEqual([]);
+    controller.focus();
+    expect(calls).toEqual(["clear"]);
   });
 
-  it("returns false for permission-shaped attention", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "permission",
-      }),
-    ).toBe(false);
+  it("holds a repeat focus while cached data is waiting for synchronization", () => {
+    const { controller, state, calls } = setup();
+    controller.update(state);
+    controller.update({ ...state, ready: false });
+    controller.focus();
+    controller.update({ ...state, ready: false, requiresAttention: true });
+    expect(calls).toEqual([]);
+    controller.update({ ...state, requiresAttention: true });
+    expect(calls).toEqual(["clear"]);
   });
 
-  it("returns false for focus entry when clear was deferred while already focused", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-        trigger: "focus-entry",
-        hasDeferredFocusEntryClear: true,
-      }),
-    ).toBe(false);
+  it("drops a pending focus when the user leaves before fresh data arrives", () => {
+    const { controller, state, calls } = setup();
+    controller.update({ ...state, ready: false });
+    controller.update({ ...state, focused: false, requiresAttention: true });
+    expect(calls).toEqual([]);
   });
 
-  it("returns true for explicit follow-up entrypoints after deferred focus clear", () => {
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-        trigger: "input-focus",
-        hasDeferredFocusEntryClear: true,
-      }),
-    ).toBe(true);
+  it("keeps permission attention and deduplicates an in-flight acknowledgement", () => {
+    const { controller, state, calls } = setup();
+    controller.update({ ...state, requiresAttention: true, attentionReason: "permission" });
+    controller.focus();
+    expect(calls).toEqual([]);
+    controller.update({ ...state, requiresAttention: true });
+    controller.focus();
+    controller.focus();
+    expect(calls).toEqual(["clear"]);
+  });
 
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-        trigger: "prompt-send",
-        hasDeferredFocusEntryClear: true,
-      }),
-    ).toBe(true);
-
-    expect(
-      shouldClearAgentAttention({
-        agentId: "agent-1",
-        isConnected: true,
-        requiresAttention: true,
-        attentionReason: "finished",
-        trigger: "agent-blur",
-        hasDeferredFocusEntryClear: true,
-      }),
-    ).toBe(true);
-  });
-});
-
-describe("pickAttentionAgent", () => {
-  it("returns null for empty input", () => {
-    expect(pickAttentionAgent([])).toBeNull();
-  });
-
-  it("returns null when no agent requires attention", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({ id: "agent-1", requiresAttention: false, attentionReason: "permission" }),
-        createAgent({ id: "agent-2", requiresAttention: false, attentionReason: null }),
-      ]),
-    ).toBeNull();
-  });
-
-  it("returns the single permission agent", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "agent-1",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-03T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBe("agent-1");
-  });
-
-  it("prioritizes permission over error over finished", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "finished-agent",
-          requiresAttention: true,
-          attentionReason: "finished",
-          attentionTimestamp: new Date("2026-01-01T00:00:00.000Z"),
-        }),
-        createAgent({
-          id: "error-agent",
-          requiresAttention: true,
-          attentionReason: "error",
-          attentionTimestamp: new Date("2026-01-02T00:00:00.000Z"),
-        }),
-        createAgent({
-          id: "permission-agent",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-03T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBe("permission-agent");
-  });
-
-  it("breaks ties by oldest attention timestamp", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "newer-permission-agent",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-03T00:00:00.000Z"),
-        }),
-        createAgent({
-          id: "older-permission-agent",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-01T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBe("older-permission-agent");
-  });
-
-  it("ignores subagents even when they require attention", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "subagent",
-          parentAgentId: "parent-agent",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-01T00:00:00.000Z"),
-        }),
-        createAgent({
-          id: "top-level-agent",
-          requiresAttention: true,
-          attentionReason: "finished",
-          attentionTimestamp: new Date("2026-01-02T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBe("top-level-agent");
-  });
-
-  it("returns null when only subagents require attention", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "subagent",
-          parentAgentId: "parent-agent",
-          requiresAttention: true,
-          attentionReason: "permission",
-          attentionTimestamp: new Date("2026-01-01T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBeNull();
-  });
-
-  it("ignores agents with requiresAttention true but null reason", () => {
-    expect(
-      pickAttentionAgent([
-        createAgent({
-          id: "ignored-agent",
-          requiresAttention: true,
-          attentionReason: null,
-          attentionTimestamp: new Date("2026-01-01T00:00:00.000Z"),
-        }),
-        createAgent({
-          id: "error-agent",
-          requiresAttention: true,
-          attentionReason: "error",
-          attentionTimestamp: new Date("2026-01-02T00:00:00.000Z"),
-        }),
-      ]),
-    ).toBe("error-agent");
+  it("reports failure and allows the next interaction to retry", async () => {
+    const errors: unknown[] = [];
+    let calls = 0;
+    const error = new Error("Disconnected");
+    const controller = createAgentAttentionController({
+      clear: async () => {
+        if (++calls === 1) throw error;
+      },
+      onError: (failure) => errors.push(failure),
+    });
+    controller.update({
+      focused: true,
+      ready: true,
+      requiresAttention: true,
+      attentionReason: "finished",
+      focusRequest: null,
+    });
+    await Promise.resolve();
+    expect(errors).toEqual([error]);
+    controller.focus();
+    expect(calls).toBe(2);
   });
 });
diff --git a/packages/app/src/utils/agent-attention.ts b/packages/app/src/utils/agent-attention.ts
index a3e5df6279..c90e3d94a6 100644
--- a/packages/app/src/utils/agent-attention.ts
+++ b/packages/app/src/utils/agent-attention.ts
@@ -1,81 +1,49 @@
-import type { Agent } from "@/stores/session-store";
-
-interface ShouldClearAgentAttentionInput {
-  agentId: string | null | undefined;
-  isConnected: boolean;
-  requiresAttention: boolean | null | undefined;
-  attentionReason?: "finished" | "error" | "permission" | null | undefined;
-  trigger?: AgentAttentionClearTrigger;
-  hasDeferredFocusEntryClear?: boolean;
+interface AttentionState {
+  focused: boolean;
+  ready: boolean;
+  requiresAttention: boolean;
+  attentionReason: "finished" | "error" | "permission" | null | undefined;
+  focusRequest: object | null;
 }
 
-export type AgentAttentionClearTrigger =
-  | "focus-entry"
-  | "input-focus"
-  | "prompt-send"
-  | "agent-blur";
+export function createAgentAttentionController(deps: {
+  clear: () => Promise<void>;
+  onError: (error: unknown) => void;
+}) {
+  let state: AttentionState | null = null;
+  let inFlight = false;
+  let pendingFocus = false;
 
-const ATTENTION_REASON_PRIORITY = {
-  permission: 0,
-  error: 1,
-  finished: 2,
-} as const;
-
-function getAttentionPriority(reason: Agent["attentionReason"]): number | null {
-  if (!reason) {
-    return null;
+  function acknowledgeFocus() {
+    if (!pendingFocus || !state?.focused || !state.ready) return;
+    pendingFocus = false;
+    if (!state.requiresAttention || state.attentionReason === "permission" || inFlight) return;
+    inFlight = true;
+    void deps.clear().then(
+      () => {
+        inFlight = false;
+        return undefined;
+      },
+      (error: unknown) => {
+        inFlight = false;
+        deps.onError(error);
+      },
+    );
   }
-  return ATTENTION_REASON_PRIORITY[reason];
-}
 
-export function pickAttentionAgent(agents: Agent[]): string | null {
-  let selectedAgentId: string | null = null;
-  let selectedPriority = Number.POSITIVE_INFINITY;
-  let selectedTimestamp = Number.POSITIVE_INFINITY;
-
-  for (const agent of agents) {
-    if (agent.requiresAttention !== true) {
-      continue;
-    }
-
-    if (agent.parentAgentId) {
-      continue;
-    }
-
-    const priority = getAttentionPriority(agent.attentionReason);
-    if (priority === null) {
-      continue;
-    }
-
-    const timestamp = agent.attentionTimestamp?.getTime() ?? Number.POSITIVE_INFINITY;
-    const isHigherPriority = priority < selectedPriority;
-    const isOlderAtSamePriority = priority === selectedPriority && timestamp < selectedTimestamp;
-    if (isHigherPriority || isOlderAtSamePriority) {
-      selectedAgentId = agent.id;
-      selectedPriority = priority;
-      selectedTimestamp = timestamp;
-    }
-  }
-
-  return selectedAgentId;
-}
-
-export function shouldClearAgentAttention(input: ShouldClearAgentAttentionInput): boolean {
-  const agentId = input.agentId?.trim();
-  if (!agentId) {
-    return false;
-  }
-  if (!input.isConnected) {
-    return false;
-  }
-  if (!input.requiresAttention) {
-    return false;
-  }
-  if (input.attentionReason === "permission") {
-    return false;
-  }
-  if (input.trigger === "focus-entry" && input.hasDeferredFocusEntryClear === true) {
-    return false;
-  }
-  return true;
+  return {
+    focus() {
+      if (!state?.focused) return;
+      pendingFocus = true;
+      acknowledgeFocus();
+    },
+    update(next: AttentionState) {
+      const entered = next.focused && !state?.focused;
+      const requested = next.focusRequest !== null && next.focusRequest !== state?.focusRequest;
+      state = { ...next };
+      if (!next.focused) pendingFocus = false;
+      else if (entered || requested) pendingFocus = true;
+      acknowledgeFocus();
+    },
+  };
 }
diff --git a/packages/app/src/utils/agent-command-autocomplete.test.ts b/packages/app/src/utils/agent-command-autocomplete.test.ts
index 9d0067a02c..8443c0688b 100644
--- a/packages/app/src/utils/agent-command-autocomplete.test.ts
+++ b/packages/app/src/utils/agent-command-autocomplete.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
 
+import {
+  getAutocompleteFallbackIndex,
+  orderAutocompleteOptions,
+} from "@/components/ui/autocomplete-utils";
 import {
   applySlashCommandReplacement,
   filterAndRankCommandAutocompleteEntries,
@@ -33,6 +37,53 @@ describe("filterAndRankCommandAutocompleteEntries", () => {
   });
 });
 
+describe("filterAndRankCommandAutocompleteEntries on an empty query", () => {
+  const rootEntries = [
+    { source: "client" as const, command: { name: "exit", aliases: ["quit", "q"] } },
+    { source: "client" as const, command: { name: "clear", aliases: ["new"] } },
+    { source: "plugin" as const, command: { name: "handoff" } },
+    { source: "provider" as const, command: { name: "compact" } },
+    { source: "provider" as const, command: { name: "review" } },
+  ];
+
+  function selectedOnEnter(query: string) {
+    const listed = orderAutocompleteOptions(
+      filterAndRankCommandAutocompleteEntries(rootEntries, query),
+    );
+    return listed[getAutocompleteFallbackIndex(listed.length)]?.command.name;
+  }
+
+  it("selects a provider command, never an immediate Paseo action", () => {
+    expect(selectedOnEnter("")).toBe("compact");
+  });
+
+  it("lists Paseo actions farthest from the input", () => {
+    const listed = orderAutocompleteOptions(
+      filterAndRankCommandAutocompleteEntries(rootEntries, ""),
+    );
+    expect(listed.map((entry) => entry.command.name)).toEqual([
+      "clear",
+      "exit",
+      "handoff",
+      "review",
+      "compact",
+    ]);
+  });
+
+  it("still selects a typed Paseo action", () => {
+    expect(selectedOnEnter("exit")).toBe("exit");
+  });
+
+  it("waits for a search when Paseo actions are all there is", () => {
+    const clientOnly = rootEntries.filter((entry) => entry.source === "client");
+
+    expect(filterAndRankCommandAutocompleteEntries(clientOnly, "")).toEqual([]);
+    expect(
+      filterAndRankCommandAutocompleteEntries(clientOnly, "ex").map((entry) => entry.command.name),
+    ).toEqual(["exit"]);
+  });
+});
+
 describe("findActiveSlashCommand", () => {
   it("detects a slash command token in the middle of the prompt", () => {
     const text = "use /tas before implementation";
diff --git a/packages/app/src/utils/agent-command-autocomplete.ts b/packages/app/src/utils/agent-command-autocomplete.ts
index 39ee7f94d1..ffc5810b94 100644
--- a/packages/app/src/utils/agent-command-autocomplete.ts
+++ b/packages/app/src/utils/agent-command-autocomplete.ts
@@ -4,7 +4,10 @@ import {
   scoreTextFields,
 } from "@getpaseo/protocol/search/text-match";
 
+type CommandAutocompleteSource = "provider" | "plugin" | "client";
+
 interface CommandAutocompleteEntry {
+  source: CommandAutocompleteSource;
   command: {
     name: string;
     aliases?: readonly string[];
@@ -12,9 +15,14 @@ interface CommandAutocompleteEntry {
   };
 }
 
-interface InlineSkillCommandEntry extends CommandAutocompleteEntry {
-  source: "provider" | "client";
-}
+// The list renders reversed above the input with the first entry selected. Paseo's own actions
+// run at once (`/exit` archives), so an empty query never selects one: they sort farthest from
+// the input, and with nothing else to list the menu waits for a search.
+const EMPTY_QUERY_SOURCE_ORDER: Record<CommandAutocompleteSource, number> = {
+  provider: 0,
+  plugin: 1,
+  client: 2,
+};
 
 export type SlashCommandPosition = "start" | "inline";
 
@@ -54,7 +62,11 @@ export function filterAndRankCommandAutocompleteEntries<TEntry extends CommandAu
 ): TEntry[] {
   const normalizedQuery = query.trim().toLowerCase();
   if (normalizedQuery.length === 0) {
-    return [...entries];
+    if (entries.every((entry) => entry.source === "client")) return [];
+    // Hermes has no `toSorted`.
+    return [...entries].sort(
+      (a, b) => EMPTY_QUERY_SOURCE_ORDER[a.source] - EMPTY_QUERY_SOURCE_ORDER[b.source],
+    );
   }
 
   const scoredEntries: ScoredCommandAutocompleteEntry<TEntry>[] = [];
@@ -76,7 +88,7 @@ export function filterAndRankCommandAutocompleteEntries<TEntry extends CommandAu
   return scoredEntries.map((scored) => scored.entry);
 }
 
-export function filterInlineSkillCommandEntries<TEntry extends InlineSkillCommandEntry>(
+export function filterInlineSkillCommandEntries<TEntry extends CommandAutocompleteEntry>(
   entries: readonly TEntry[],
 ): TEntry[] {
   return entries.filter((entry) => entry.source === "provider" && entry.command.kind === "skill");
diff --git a/packages/app/src/utils/agent-directory-reconciliation.test.ts b/packages/app/src/utils/agent-directory-reconciliation.test.ts
index 85e311345b..35feb27cd2 100644
--- a/packages/app/src/utils/agent-directory-reconciliation.test.ts
+++ b/packages/app/src/utils/agent-directory-reconciliation.test.ts
@@ -126,6 +126,23 @@ describe("agent directory reconciliation", () => {
     }).toEqual({ title: "newer page", status: "running", projectName: "repo" });
   });
 
+  it("takes the project of a newer buffered upsert", () => {
+    const snapshotEntry = entry("agent", "idle");
+    const newerProject = { ...snapshotEntry.project, projectName: "renamed project" };
+    const result = reconcileAgentDirectory({
+      snapshot: [snapshotEntry],
+      deltas: [
+        {
+          kind: "upsert",
+          agent: { ...snapshot("agent", "idle"), updatedAt: "2026-07-12T11:00:00.000Z" },
+          project: newerProject,
+        },
+      ],
+    });
+
+    expect(result[0]?.project.projectName).toBe("renamed project");
+  });
+
   it("clears a snapshot stop when a newer buffered upsert is running", () => {
     const result = reconcileAgentDirectory({
       snapshot: [entry("agent", "idle")],
diff --git a/packages/app/src/utils/agent-grouping.test.ts b/packages/app/src/utils/agent-grouping.test.ts
index f380dc1118..fdda9f2fda 100644
--- a/packages/app/src/utils/agent-grouping.test.ts
+++ b/packages/app/src/utils/agent-grouping.test.ts
@@ -10,6 +10,7 @@ function makeAgent(overrides: Partial<AggregatedAgent> = {}): AggregatedAgent {
     serverLabel: (overrides as { serverLabel?: string }).serverLabel ?? "server",
     title: overrides.title ?? null,
     status: overrides.status ?? ("running" as AggregatedAgent["status"]),
+    backgroundWork: overrides.backgroundWork,
     turn:
       overrides.turn ??
       ({
@@ -71,6 +72,19 @@ describe("deriveProjectDisplayName", () => {
 });
 
 describe("groupAgents", () => {
+  it("keeps an idle agent with long-running background work in the active group", () => {
+    const agent = makeAgent({
+      status: "idle",
+      turn: { phase: "idle", cancellationRequestId: null },
+      lastActivityAt: new Date("2020-01-01T00:00:00.000Z"),
+      backgroundWork: { count: 1 },
+    });
+    expect(
+      groupAgents([agent])
+        .activeGroups.flatMap((group) => group.agents)
+        .map((item) => item.id),
+    ).toEqual([agent.id]);
+  });
   it("uses turn liveness instead of protocol status for active grouping", () => {
     const old = new Date("2020-01-01T00:00:00.000Z");
     const open = makeAgent({ id: "open", status: "idle", lastActivityAt: old });
diff --git a/packages/app/src/utils/agent-grouping.ts b/packages/app/src/utils/agent-grouping.ts
index eaca2d1511..698ab6b5a4 100644
--- a/packages/app/src/utils/agent-grouping.ts
+++ b/packages/app/src/utils/agent-grouping.ts
@@ -1,4 +1,5 @@
 import type { AggregatedAgent } from "@/hooks/use-aggregated-agents";
+import { isSidebarActiveAgent } from "@/utils/sidebar-agent-state";
 
 /**
  * Derives the project key for grouping agents.
@@ -262,12 +263,19 @@ const MAX_INACTIVE_PER_PROJECT = 5;
  * - All truly active agents (running/needs input/requires attention) are always shown
  * - Recently active (within grace period but not truly active) are limited to MAX_INACTIVE_PER_PROJECT
  */
+function activityStatus(agent: AggregatedAgent): AggregatedAgent["status"] {
+  if (agent.turn.phase === "open") return "running";
+  return agent.status === "running" ? "idle" : agent.status;
+}
+
 function isAgentTrulyActive(agent: AggregatedAgent): boolean {
-  return (
-    agent.turn.phase === "open" ||
-    agent.requiresAttention ||
-    (agent.pendingPermissionCount ?? 0) > 0
-  );
+  return isSidebarActiveAgent({
+    status: activityStatus(agent),
+    backgroundWork: agent.backgroundWork,
+    requiresAttention: agent.requiresAttention,
+    attentionReason: agent.attentionReason,
+    pendingPermissionCount: agent.pendingPermissionCount,
+  });
 }
 
 function partitionAgentsByActivity(
diff --git a/packages/app/src/utils/agent-snapshots.test.ts b/packages/app/src/utils/agent-snapshots.test.ts
index e1be8c5a0c..49c4bcb983 100644
--- a/packages/app/src/utils/agent-snapshots.test.ts
+++ b/packages/app/src/utils/agent-snapshots.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import { isControlActive, readSelectOption } from "@/agent-controls/option-controls";
 import { normalizeAgentSnapshot, projectAgentSnapshot } from "./agent-snapshots";
 
 function createSnapshot(
@@ -32,10 +33,39 @@ function createSnapshot(
     persistence: input.persistence ?? null,
     title: input.title ?? null,
     labels: (input.labels ?? {}) as AgentSnapshotPayload["labels"],
+    ...(input.controls ? { controls: input.controls } : {}),
+    ...(input.options ? { options: input.options } : {}),
   };
 }
 
 describe("normalizeAgentSnapshot", () => {
+  it("keeps a closed agent's stored options and controls, so its Fast control draws", () => {
+    const speed = {
+      type: "select" as const,
+      key: "service_tier",
+      label: "Speed",
+      defaultValue: "default",
+      choices: [
+        { value: "default", label: "Normal" },
+        { value: "priority", label: "Fast" },
+      ],
+    };
+    const agent = normalizeAgentSnapshot(
+      createSnapshot({
+        status: "closed",
+        controls: [speed],
+        options: { service_tier: "priority", sandbox_mode: "read-only" },
+      }),
+      "server-1",
+    );
+
+    expect(agent.status).toBe("closed");
+    expect(agent.controls).toEqual([speed]);
+    expect(agent.options).toEqual({ service_tier: "priority", sandbox_mode: "read-only" });
+    expect(readSelectOption(speed, agent.options ?? {})).toBe("priority");
+    expect(isControlActive(speed, agent.options ?? {})).toBe(true);
+  });
+
   it("round-trips identified active turns through the canonical snapshot boundary", () => {
     const snapshot = createSnapshot({
       status: "running",
diff --git a/packages/app/src/utils/agent-snapshots.ts b/packages/app/src/utils/agent-snapshots.ts
index 13a7bcd14b..86da628bdf 100644
--- a/packages/app/src/utils/agent-snapshots.ts
+++ b/packages/app/src/utils/agent-snapshots.ts
@@ -64,12 +64,14 @@ export function projectAgentSnapshot(agent: Agent): AgentSnapshotPayload {
     cwd: agent.cwd,
     ...(agent.workspaceId ? { workspaceId: agent.workspaceId } : {}),
     model: agent.model,
-    ...(agent.features ? { features: agent.features } : {}),
+    ...(agent.options ? { options: agent.options } : {}),
+    ...(agent.controls ? { controls: agent.controls } : {}),
     thinkingOptionId: agent.thinkingOptionId ?? null,
     createdAt: agent.createdAt.toISOString(),
     updatedAt: agent.updatedAt.toISOString(),
     lastUserMessageAt: agent.lastUserMessageAt?.toISOString() ?? null,
     status: agent.status,
+    backgroundWork: agent.backgroundWork,
     ...projectActiveTurn(agent),
     capabilities: agent.capabilities,
     currentModeId: agent.currentModeId,
@@ -77,14 +79,17 @@ export function projectAgentSnapshot(agent: Agent): AgentSnapshotPayload {
     pendingPermissions: agent.pendingPermissions,
     persistence: agent.persistence,
     ...(agent.runtimeInfo ? { runtimeInfo: agent.runtimeInfo } : {}),
+    ...(agent.usageScopeKey ? { usageScopeKey: agent.usageScopeKey } : {}),
     ...(agent.lastUsage ? { lastUsage: agent.lastUsage } : {}),
     ...(agent.lastError ? { lastError: agent.lastError } : {}),
     title: agent.title,
     labels: agent.labels,
+    ...(agent.metadata ? { metadata: agent.metadata } : {}),
     requiresAttention: agent.requiresAttention ?? false,
     attentionReason: agent.attentionReason ?? null,
     attentionTimestamp: agent.attentionTimestamp?.toISOString() ?? null,
     archivedAt: agent.archivedAt?.toISOString() ?? null,
+    ...(agent.background ? { background: true } : {}),
   };
 }
 
@@ -110,6 +115,7 @@ export function normalizeAgentSnapshot(snapshot: AgentSnapshotPayload, serverId:
     id: snapshot.id,
     provider: snapshot.provider,
     status: snapshot.status,
+    backgroundWork: snapshot.backgroundWork,
     turn,
     createdAt,
     updatedAt,
@@ -121,19 +127,23 @@ export function normalizeAgentSnapshot(snapshot: AgentSnapshotPayload, serverId:
     pendingPermissions: snapshot.pendingPermissions ?? [],
     persistence: snapshot.persistence ?? null,
     runtimeInfo: snapshot.runtimeInfo,
+    usageScopeKey: snapshot.usageScopeKey,
     lastUsage: snapshot.lastUsage,
     lastError: snapshot.lastError ?? null,
     title: snapshot.title ?? null,
     cwd: snapshot.cwd,
     workspaceId: snapshot.workspaceId,
     model: snapshot.model ?? null,
-    features: snapshot.features,
+    options: snapshot.options,
+    controls: snapshot.controls,
     thinkingOptionId: snapshot.thinkingOptionId ?? null,
     requiresAttention: snapshot.requiresAttention ?? false,
     attentionReason: snapshot.attentionReason ?? null,
     attentionTimestamp,
     archivedAt,
+    background: snapshot.background === true,
     parentAgentId,
     labels: snapshot.labels,
+    metadata: snapshot.metadata,
   };
 }
diff --git a/packages/app/src/utils/desktop-window.test.ts b/packages/app/src/utils/desktop-window.test.ts
index aa95a90dbf..fcc5bcea91 100644
--- a/packages/app/src/utils/desktop-window.test.ts
+++ b/packages/app/src/utils/desktop-window.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   intersectWindowChromeCorners,
+  resolveChildWindowChromeCorners,
   resolveHasOwnedWindowChromeObstruction,
   resolveWindowChromeObstruction,
   resolveWindowChromeSafeArea,
@@ -8,30 +9,61 @@ import {
 
 describe("window chrome", () => {
   it("has no corner obstruction outside Electron or in fullscreen", () => {
-    expect(resolveWindowChromeObstruction({ mode: null, isFullscreen: false })).toEqual({
+    expect(
+      resolveWindowChromeObstruction({ mode: null, isFullscreen: false, topBand: null }),
+    ).toEqual({
       topLeft: null,
       topRight: null,
     });
-    expect(resolveWindowChromeObstruction({ mode: "native-mac", isFullscreen: true })).toEqual({
+    expect(
+      resolveWindowChromeObstruction({ mode: "native-mac", isFullscreen: true, topBand: null }),
+    ).toEqual({
       topLeft: null,
       topRight: null,
     });
   });
 
   it("places native controls in their physical top corner", () => {
-    expect(resolveWindowChromeObstruction({ mode: "native-mac", isFullscreen: false })).toEqual({
+    expect(
+      resolveWindowChromeObstruction({ mode: "native-mac", isFullscreen: false, topBand: null }),
+    ).toEqual({
       topLeft: { width: 78, height: 45 },
       topRight: null,
     });
-    expect(resolveWindowChromeObstruction({ mode: "custom-windows", isFullscreen: false })).toEqual(
-      { topLeft: null, topRight: { width: 138, height: 36 } },
-    );
-    expect(resolveWindowChromeObstruction({ mode: "custom-linux", isFullscreen: false })).toEqual({
+    expect(
+      resolveWindowChromeObstruction({
+        mode: "custom-windows",
+        isFullscreen: false,
+        topBand: null,
+      }),
+    ).toEqual({ topLeft: null, topRight: { width: 138, height: 36 } });
+    expect(
+      resolveWindowChromeObstruction({ mode: "custom-linux", isFullscreen: false, topBand: null }),
+    ).toEqual({
       topLeft: null,
       topRight: { width: 108, height: 36 },
     });
   });
 
+  // Measured: iPhone Duo inner screen, portrait. The top bar ends at x 525, where the status
+  // region (0..82) starts; the band starts at y 26.
+  it("treats the status region beside a native top band as top-right window controls", () => {
+    expect(
+      resolveWindowChromeObstruction({
+        mode: null,
+        isFullscreen: false,
+        topBand: { top: 26, trailingObstruction: { width: 144, height: 56 } },
+      }),
+    ).toEqual({ topLeft: null, topRight: { width: 144, height: 56 } });
+    expect(
+      resolveWindowChromeObstruction({
+        mode: null,
+        isFullscreen: false,
+        topBand: { top: 26, trailingObstruction: null },
+      }),
+    ).toEqual({ topLeft: null, topRight: null });
+  });
+
   it("insets and reserves only claimed corners", () => {
     const obstruction = { topLeft: { width: 80, height: 28 }, topRight: { width: 48, height: 32 } };
     expect(
@@ -87,3 +119,54 @@ describe("window chrome", () => {
     ).toBe(false);
   });
 });
+
+it("assigns window buttons only to exposed split edges", () => {
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: true,
+      isLast: false,
+    }),
+  ).toBe("top-left");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: false,
+      isLast: true,
+    }),
+  ).toBe("top-right");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: false,
+      isLast: false,
+    }),
+  ).toBe("none");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "vertical",
+      isFirst: true,
+      isLast: false,
+    }),
+  ).toBe("both");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "vertical",
+      isFirst: false,
+      isLast: true,
+    }),
+  ).toBe("none");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "top-right",
+      direction: "horizontal",
+      isFirst: true,
+      isLast: true,
+    }),
+  ).toBe("top-right");
+});
diff --git a/packages/app/src/utils/desktop-window.tsx b/packages/app/src/utils/desktop-window.tsx
index adc3f7c9a1..5947764709 100644
--- a/packages/app/src/utils/desktop-window.tsx
+++ b/packages/app/src/utils/desktop-window.tsx
@@ -12,6 +12,7 @@ import {
   getDesktopWindowControlsWidth,
 } from "@/desktop/window-chrome-presentation";
 import { isNative } from "@/constants/platform";
+import { useTopBand, type TopBand } from "@/window-layout";
 
 export type WindowChromeCorners = "none" | "top-left" | "top-right" | "both";
 type WindowChromeSafeAreaPlacement = "inline" | "below";
@@ -83,6 +84,19 @@ export function intersectWindowChromeCorners(
   );
 }
 
+export function resolveChildWindowChromeCorners(input: {
+  corners: WindowChromeCorners;
+  direction: "horizontal" | "vertical";
+  isFirst: boolean;
+  isLast: boolean;
+}): WindowChromeCorners {
+  if (input.direction === "vertical") return input.isFirst ? input.corners : "none";
+  return intersectWindowChromeCorners(
+    input.corners,
+    windowChromeCornersFromFlags(input.isFirst, input.isLast),
+  );
+}
+
 export function removeWindowChromeCorner(
   corners: WindowChromeCorners,
   corner: WindowChromeCorner,
@@ -92,10 +106,15 @@ export function removeWindowChromeCorner(
   return corner === "top-left" ? "top-right" : "top-left";
 }
 
+/** Desktop window controls, or the system region a native top band gives way to. */
 export function resolveWindowChromeObstruction(input: {
   mode: DesktopWindowChromeMode | null;
   isFullscreen: boolean;
+  topBand: TopBand | null;
 }): WindowChromeObstruction {
+  if (input.topBand?.trailingObstruction) {
+    return { topLeft: null, topRight: input.topBand.trailingObstruction };
+  }
   if (!input.mode || input.isFullscreen) return EMPTY_OBSTRUCTION;
   if (input.mode === "native-mac") {
     return {
@@ -204,13 +223,15 @@ export function WindowChromeProvider({ children }: { children: ReactNode }) {
     };
   }, []);
 
+  const topBand = useTopBand();
   const obstruction = useMemo(
     () =>
       resolveWindowChromeObstruction({
         mode: isElectronReady ? getDesktopWindowChromeMode() : null,
         isFullscreen: windowState.isFullscreen,
+        topBand,
       }),
-    [isElectronReady, windowState.isFullscreen],
+    [isElectronReady, windowState.isFullscreen, topBand],
   );
   const desktopWindowChrome = useMemo(
     () => ({
diff --git a/packages/app/src/utils/host-routes.test.ts b/packages/app/src/utils/host-routes.test.ts
index 644139e92d..1687563603 100644
--- a/packages/app/src/utils/host-routes.test.ts
+++ b/packages/app/src/utils/host-routes.test.ts
@@ -8,7 +8,6 @@ import {
   buildOpenProjectRoute,
   resolveKnownHostRoute,
   buildSessionsRoute,
-  buildSettingsAddHostRoute,
   buildProjectSettingsRoute,
   buildProjectsSettingsRoute,
   decodeFilePathFromPathSegment,
@@ -185,14 +184,6 @@ describe("workspace route parsing", () => {
 });
 
 describe("projects settings routes", () => {
-  it("buildSettingsAddHostRoute opens settings with the add-host flag", () => {
-    expect(buildSettingsAddHostRoute()).toBe("/settings/general?addHost=1");
-  });
-
-  it("buildSettingsAddHostRoute accepts a repeatable intent id", () => {
-    expect(buildSettingsAddHostRoute("retry 1")).toBe("/settings/general?addHost=retry%201");
-  });
-
   it("buildProjectsSettingsRoute scopes the list to a host", () => {
     expect(buildProjectsSettingsRoute("host a")).toBe("/settings/hosts/host%20a/projects");
   });
diff --git a/packages/app/src/utils/host-routes.ts b/packages/app/src/utils/host-routes.ts
index c5913366d2..f258c6ba5b 100644
--- a/packages/app/src/utils/host-routes.ts
+++ b/packages/app/src/utils/host-routes.ts
@@ -553,10 +553,6 @@ export function buildSettingsSectionRoute(section: SettingsSectionSlug) {
   return `/settings/${section}` as const;
 }
 
-export function buildSettingsAddHostRoute(intentId: string | number = "1") {
-  return `/settings/general?addHost=${encodeURIComponent(String(intentId))}` as const;
-}
-
 export function buildSettingsHostRoute(serverId: string) {
   const normalized = trimNonEmpty(serverId);
   if (!normalized) {
diff --git a/packages/app/src/utils/navigate-to-agent/resolve.test.ts b/packages/app/src/utils/navigate-to-agent/resolve.test.ts
index f768edfce5..c06d20d096 100644
--- a/packages/app/src/utils/navigate-to-agent/resolve.test.ts
+++ b/packages/app/src/utils/navigate-to-agent/resolve.test.ts
@@ -40,6 +40,14 @@ function createFakeNavigators(target: AgentNavTarget): {
 }
 
 describe("resolveNavigateToAgent", () => {
+  it("carries a request for a tab to the workspace navigation", () => {
+    const { deps, tabNavigations } = createFakeNavigators({ agentWorkspaceId: WORKSPACE_ID });
+
+    resolveNavigateToAgent({ serverId: SERVER_ID, agentId: AGENT_ID, asTab: true }, deps);
+
+    expect(tabNavigations[0]).toMatchObject({ asTab: true });
+  });
+
   it("opens the workspace tab carried by the agent's workspaceId", () => {
     const { deps, hostNavigations, tabNavigations } = createFakeNavigators({
       agentWorkspaceId: WORKSPACE_ID,
diff --git a/packages/app/src/utils/navigate-to-agent/resolve.ts b/packages/app/src/utils/navigate-to-agent/resolve.ts
index 842760d793..4cd47ee14b 100644
--- a/packages/app/src/utils/navigate-to-agent/resolve.ts
+++ b/packages/app/src/utils/navigate-to-agent/resolve.ts
@@ -9,6 +9,8 @@ export interface NavigateToAgentInput {
   // (cold deep-links). Otherwise the workspace is read from the store.
   workspaceId?: string | null;
   pin?: boolean;
+  /** Opens the agent with its composer, where a compact layout would show a sheet without one. */
+  asTab?: boolean;
 }
 
 export interface AgentNavTarget {
@@ -41,5 +43,6 @@ export function resolveNavigateToAgent(
     workspaceId,
     target: { kind: "agent", agentId: input.agentId },
     pin: input.pin,
+    asTab: input.asTab,
   });
 }
diff --git a/packages/app/src/utils/prepare-workspace-tab.ts b/packages/app/src/utils/prepare-workspace-tab.ts
index 5d05bff60c..e2787a9806 100644
--- a/packages/app/src/utils/prepare-workspace-tab.ts
+++ b/packages/app/src/utils/prepare-workspace-tab.ts
@@ -8,6 +8,7 @@ export interface PrepareWorkspaceTabInput {
   target: WorkspaceTabTarget;
   pin?: boolean;
   placement?: WorkspaceTabPlacement;
+  asTab?: boolean;
 }
 
 export interface PrepareWorkspaceTabDeps {
@@ -17,6 +18,7 @@ export interface PrepareWorkspaceTabDeps {
     intent: "reveal";
     pin?: boolean;
     placement?: WorkspaceTabPlacement;
+    asTab?: boolean;
   }) => string | null;
 }
 
@@ -44,5 +46,6 @@ export function prepareWorkspaceTab(
     intent: "reveal",
     pin: input.pin === true && target.kind === "agent",
     placement: input.placement,
+    asTab: input.asTab,
   });
 }
diff --git a/packages/app/src/utils/test-daemon-connection.test.ts b/packages/app/src/utils/test-daemon-connection.test.ts
index 29382b5c89..88f36c6d0f 100644
--- a/packages/app/src/utils/test-daemon-connection.test.ts
+++ b/packages/app/src/utils/test-daemon-connection.test.ts
@@ -2,9 +2,11 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { DaemonClientConfig } from "@getpaseo/client/internal/daemon-client";
 import { DaemonAuthenticationError } from "@getpaseo/client/internal/daemon-client";
 import type { DaemonConnectionDependencies, DaemonProbeClient } from "./test-daemon-connection";
+import { createHostLogger } from "@/runtime/host-logger";
 
 class FakeDaemonClient implements DaemonProbeClient {
   readonly lastError: string | null;
+  private connected = false;
 
   constructor(
     private readonly probe: FakeDaemonProbe,
@@ -17,9 +19,11 @@ class FakeDaemonClient implements DaemonProbeClient {
     if (this.probe.nextConnectError) {
       throw this.probe.nextConnectError;
     }
+    this.connected = true;
   }
 
   getLastServerInfoMessage() {
+    if (!this.connected) return null;
     return {
       serverId: "srv_probe_test",
       hostname: "probe-host",
@@ -27,11 +31,13 @@ class FakeDaemonClient implements DaemonProbeClient {
   }
 
   async close(): Promise<void> {
+    this.connected = false;
     this.probe.closedClients.push(this);
   }
 }
 
 class FakeDaemonProbe {
+  diagnosticLines: string[] = [];
   createdClients: FakeDaemonClient[] = [];
   closedClients: FakeDaemonClient[] = [];
   clientIdsRequested = 0;
@@ -39,6 +45,12 @@ class FakeDaemonProbe {
   nextLastError: string | null = null;
 
   readonly deps: DaemonConnectionDependencies<FakeDaemonClient> = {
+    createLogger: (readServerId) => {
+      const capture = (...values: unknown[]) => {
+        this.diagnosticLines.push(values.map(String).join(" "));
+      };
+      return createHostLogger(readServerId, { log: capture, warn: capture, error: capture });
+    },
     getClientId: async () => {
       this.clientIdsRequested += 1;
       return "cid_shared_probe_test";
@@ -76,6 +88,34 @@ describe("test-daemon-connection connectToDaemon", () => {
     probe = new FakeDaemonProbe();
   });
 
+  it.each([undefined, "srv_probe_test"])(
+    "logs learned host identity on an adopted probe initially given %s",
+    async (serverId) => {
+      const { connectToDaemon } = await import("./test-daemon-connection");
+      const result = await connectToDaemon(
+        { id: "direct:test", type: "directTcp", endpoint: "localhost:6767" },
+        { serverId },
+        probe.deps,
+      );
+      try {
+        result.client.config.logger!.error({ err: new Error("socket closed") }, "connection_error");
+        const record = JSON.parse(probe.diagnosticLines[0]!.slice("connection_error ".length));
+        expect(record.serverId).toBe("srv_probe_test");
+        expect(record.err.message).toBe("socket closed");
+        await result.client.close();
+        expect(result.client.getLastServerInfoMessage()).toBeNull();
+        result.client.config.logger!.error({ err: new Error("disconnected") }, "connection_error");
+        const closedRecord = JSON.parse(
+          probe.diagnosticLines[1]!.slice("connection_error ".length),
+        );
+        expect(closedRecord.serverId).toBe("srv_probe_test");
+        expect(closedRecord.err.message).toBe("disconnected");
+      } finally {
+        await result.client.close();
+      }
+    },
+  );
+
   it.each([
     { id: "direct:lan:6767", type: "directTcp" as const, endpoint: "lan:6767" },
     {
diff --git a/packages/app/src/utils/test-daemon-connection.ts b/packages/app/src/utils/test-daemon-connection.ts
index 1d1605af62..96400b4878 100644
--- a/packages/app/src/utils/test-daemon-connection.ts
+++ b/packages/app/src/utils/test-daemon-connection.ts
@@ -7,6 +7,7 @@ import {
 import type { DaemonClientConfig } from "@getpaseo/client/internal/daemon-client";
 import type { HostConnection } from "@/types/host-connection";
 import { createAppWebSocketFactory } from "@/runtime/websocket-factory";
+import { createHostLogger } from "@/runtime/host-logger";
 import { getOrCreateClientId } from "./client-id";
 import { resolveAppVersion } from "./app-version";
 import {
@@ -29,6 +30,7 @@ export interface DaemonProbeClient {
 }
 
 export interface DaemonConnectionDependencies<TClient extends DaemonProbeClient> {
+  createLogger: typeof createHostLogger;
   getClientId(): Promise<string>;
   resolveAppVersion(): string | null;
   createDesktopTransportFactory(): DaemonClientConfig["transportFactory"] | null;
@@ -37,6 +39,7 @@ export interface DaemonConnectionDependencies<TClient extends DaemonProbeClient>
 }
 
 const defaultDaemonConnectionDependencies: DaemonConnectionDependencies<DaemonClient> = {
+  createLogger: createHostLogger,
   getClientId: getOrCreateClientId,
   resolveAppVersion,
   createDesktopTransportFactory: createDesktopDaemonTransportFactory,
@@ -317,5 +320,9 @@ export async function connectToDaemon(
   deps: DaemonConnectionDependencies<DaemonProbeClient> = defaultDaemonConnectionDependencies,
 ): Promise<{ client: DaemonProbeClient; serverId: string; hostname: string | null }> {
   const config = await buildClientConfig(connection, options?.serverId, options, deps);
-  return connectAndProbe(config, resolveTimeout(connection, options), deps);
+  let serverId = options?.serverId;
+  config.logger = deps.createLogger(() => serverId);
+  const result = await connectAndProbe(config, resolveTimeout(connection, options), deps);
+  serverId = result.serverId;
+  return result;
 }
diff --git a/packages/app/src/utils/tool-call-detail-state.ts b/packages/app/src/utils/tool-call-detail-state.ts
index b28848af8e..5aa7f298ae 100644
--- a/packages/app/src/utils/tool-call-detail-state.ts
+++ b/packages/app/src/utils/tool-call-detail-state.ts
@@ -57,7 +57,7 @@ export function hasMeaningfulToolCallDetail(detail: ToolCallDetail | undefined):
 
   switch (detail.type) {
     case "shell":
-      return true;
+      return Boolean(detail.command.trim() || detail.output);
     case "read":
       return hasMeaningfulReadLikeDetail(detail);
     case "edit":
diff --git a/packages/app/src/utils/tool-call-parsers.test.ts b/packages/app/src/utils/tool-call-parsers.test.ts
index c02f957a07..16c2f57f5b 100644
--- a/packages/app/src/utils/tool-call-parsers.test.ts
+++ b/packages/app/src/utils/tool-call-parsers.test.ts
@@ -21,6 +21,36 @@ describe("tool-call-parsers", () => {
     expect(parsed.find((entry) => entry.type === "add")?.content).toBe("+new");
   });
 
+  it("keeps file headers in multi-file diffs", () => {
+    const parsed = parseUnifiedDiff(
+      [
+        "diff --git a/alpha.txt b/alpha.txt",
+        "--- a/alpha.txt",
+        "+++ b/alpha.txt",
+        "@@ -1 +1 @@",
+        "-color = blue",
+        "+color = green",
+        "diff --git a/beta.txt b/beta.txt",
+        "--- a/beta.txt",
+        "+++ b/beta.txt",
+        "@@ -1 +1 @@",
+        "-size = small",
+        "+size = large",
+      ].join("\n"),
+    );
+
+    expect(parsed).toEqual([
+      { type: "header", content: "diff --git a/alpha.txt b/alpha.txt" },
+      { type: "header", content: "@@ -1 +1 @@" },
+      { type: "remove", content: "-color = blue" },
+      { type: "add", content: "+color = green" },
+      { type: "header", content: "diff --git a/beta.txt b/beta.txt" },
+      { type: "header", content: "@@ -1 +1 @@" },
+      { type: "remove", content: "-size = small" },
+      { type: "add", content: "+size = large" },
+    ]);
+  });
+
   it("extracts TodoWrite task entries", () => {
     const tasks = extractTaskEntriesFromToolCall("TodoWrite", {
       todos: [
diff --git a/packages/app/src/utils/tool-call-parsers.ts b/packages/app/src/utils/tool-call-parsers.ts
index 1e89e2b303..7980d3ee5f 100644
--- a/packages/app/src/utils/tool-call-parsers.ts
+++ b/packages/app/src/utils/tool-call-parsers.ts
@@ -210,6 +210,8 @@ export function parseUnifiedDiff(diffText?: string): DiffLine[] {
   }
 
   const lines = splitIntoLines(diffText);
+  const fileHeaders = lines.filter((line) => line.startsWith("diff --git "));
+  const hasMultipleFiles = fileHeaders.length > 1;
   const diff: DiffLine[] = [];
 
   for (const line of lines) {
@@ -218,7 +220,8 @@ export function parseUnifiedDiff(diffText?: string): DiffLine[] {
       continue;
     }
 
-    if (line.startsWith("@@")) {
+    const isFileHeader = hasMultipleFiles && line.startsWith("diff --git ");
+    if (line.startsWith("@@") || isFileHeader) {
       diff.push({ type: "header", content: line });
       continue;
     }
diff --git a/packages/app/src/utils/workspace-agent-activity.test.ts b/packages/app/src/utils/workspace-agent-activity.test.ts
index 7ccca095f1..a539a3881a 100644
--- a/packages/app/src/utils/workspace-agent-activity.test.ts
+++ b/packages/app/src/utils/workspace-agent-activity.test.ts
@@ -14,6 +14,7 @@ function agent(input: {
   pendingPermissionCount?: number;
   archivedAt?: string | null;
   parentAgentId?: string | null;
+  background?: boolean;
 }): Agent {
   return {
     serverId: "host-a",
@@ -61,6 +62,7 @@ function agent(input: {
     attentionTimestamp: input.attentionTimestamp ? new Date(input.attentionTimestamp) : null,
     archivedAt: input.archivedAt ? new Date(input.archivedAt) : null,
     parentAgentId: input.parentAgentId ?? null,
+    background: input.background ?? false,
     labels: {},
   };
 }
@@ -91,6 +93,8 @@ describe("workspace agent activity index", () => {
             workspaceId: "workspace-error",
             status: "error",
             turn: { phase: "idle", cancellationRequestId: null },
+            requiresAttention: true,
+            attentionReason: "error",
             updatedAt: "2026-01-01T00:00:00.000Z",
           }),
         ],
@@ -158,6 +162,33 @@ describe("workspace agent activity index", () => {
     );
   });
 
+  it("does not let a running background agent change root workspace activity", () => {
+    const index = buildWorkspaceAgentActivityIndex(
+      new Map([
+        [
+          "root",
+          agent({ id: "root", workspaceId: "workspace-a", updatedAt: "2026-06-01T10:00:00.000Z" }),
+        ],
+        [
+          "classifier",
+          agent({
+            id: "classifier",
+            workspaceId: "workspace-a",
+            status: "running",
+            updatedAt: "2026-06-01T10:05:00.000Z",
+            background: true,
+          }),
+        ],
+      ]),
+    );
+
+    expect(index.get("workspace-a")).toEqual({
+      agentId: "root",
+      status: "done",
+      enteredAt: new Date("2026-06-01T10:00:00.000Z"),
+    });
+  });
+
   it("does not let archived or child agents change root workspace activity", () => {
     const index = buildWorkspaceAgentActivityIndex(
       new Map([
diff --git a/packages/app/src/utils/workspace-agent-activity.ts b/packages/app/src/utils/workspace-agent-activity.ts
index 69f3c23da4..d3cfe77678 100644
--- a/packages/app/src/utils/workspace-agent-activity.ts
+++ b/packages/app/src/utils/workspace-agent-activity.ts
@@ -22,7 +22,12 @@ export function buildWorkspaceAgentActivityIndex(
 
   for (const agent of agents.values()) {
     const parentAgent = agent.parentAgentId ? agents.get(agent.parentAgentId) : undefined;
-    if (agent.archivedAt || !agent.workspaceId || !isWorkspaceRootAgent(agent, parentAgent)) {
+    if (
+      agent.archivedAt ||
+      agent.background ||
+      !agent.workspaceId ||
+      !isWorkspaceRootAgent(agent, parentAgent)
+    ) {
       continue;
     }
 
@@ -35,6 +40,7 @@ export function buildWorkspaceAgentActivityIndex(
 
     const status = deriveSidebarStateBucket({
       status: workspaceAgentStatus(agent),
+      backgroundWork: agent.backgroundWork,
       pendingPermissionCount: agent.pendingPermissions.length,
       requiresAttention: agent.requiresAttention,
       attentionReason: agent.attentionReason,
diff --git a/packages/app/src/window-layout/actions.browser.test.tsx b/packages/app/src/window-layout/actions.browser.test.tsx
new file mode 100644
index 0000000000..a7f3a4a75e
--- /dev/null
+++ b/packages/app/src/window-layout/actions.browser.test.tsx
@@ -0,0 +1,95 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { PortalProvider } from "@gorhom/portal";
+import { afterEach, expect, it, vi } from "vitest";
+import { Text } from "react-native";
+import { page } from "vitest/browser";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { HeaderToggleButton } from "@/components/headers/header-toggle-button";
+import type { WindowLayout } from "./model";
+import { WindowLayoutContext } from "./context";
+import { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+import { WindowLayoutDivisionGap } from "./surface";
+import { lightTheme } from "@/styles/theme";
+
+vi.stubGlobal("React", React);
+const layout = { sidebarWidth: 465, gap: 21, contentWidth: 381 };
+const geometry: WindowLayout = {
+  bounds: { x: 0, y: 0, width: window.innerWidth, height: window.innerHeight },
+  verticalBarEdge: "trailing",
+  verticalBar: { x: 20, y: 20, width: 44, height: 400 },
+  divisions: [],
+};
+const container = document.createElement("div");
+document.body.appendChild(container);
+const root = createRoot(container);
+afterEach(() => {
+  act(() => root.render(null));
+});
+
+it("paints the reserved division with the sidebar surface", () => {
+  act(() =>
+    root.render(<WindowLayoutDivisionGap layout={layout} sidebarVisible compact={false} />),
+  );
+  const gap = container.firstElementChild as HTMLElement;
+  const expected = document.createElement("div");
+  expected.style.backgroundColor = lightTheme.colors.surfaceSidebar;
+  expect(getComputedStyle(gap).backgroundColor).toBe(expected.style.backgroundColor);
+  expect(getComputedStyle(gap).borderRightWidth).toBe("1px");
+  expect(gap.getBoundingClientRect().width).toBe(21);
+});
+
+const explorerState = { expanded: false };
+const noKeys: [] = [];
+const noop = () => {};
+
+it("preserves circular explorer chrome and closes a portaled menu when actions become inactive", async () => {
+  async function renderActions(active: boolean) {
+    await act(async () =>
+      root.render(
+        <PortalProvider>
+          <WindowLayoutContext.Provider value={geometry}>
+            <WindowLayoutActionsHost />
+            <WindowLayoutActions active={active}>
+              <HeaderToggleButton
+                onPress={noop}
+                accessibilityRole="button"
+                accessibilityLabel="Explorer"
+                tooltipLabel="Explorer"
+                tooltipSide="left"
+                tooltipKeys={noKeys}
+                accessibilityState={explorerState}
+              >
+                <Text>Explorer</Text>
+              </HeaderToggleButton>
+              <DropdownMenu>
+                <DropdownMenuTrigger accessibilityRole="button" accessibilityLabel="Bar menu">
+                  <Text>Menu</Text>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <DropdownMenuItem onSelect={noop}>Bar menu item</DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </WindowLayoutActions>
+          </WindowLayoutContext.Provider>
+        </PortalProvider>,
+      ),
+    );
+  }
+  await renderActions(true);
+  const explorer = container.querySelector('[aria-label="Explorer"]') as HTMLElement;
+  expect(getComputedStyle(explorer).borderRadius).toBe(`${lightTheme.borderRadius.full}px`);
+  await page.getByRole("button", { name: "Bar menu", exact: true }).click();
+  await expect.element(page.getByRole("menuitem", { name: "Bar menu item" })).toBeVisible();
+  await renderActions(false);
+  await expect.poll(() => document.querySelectorAll('[role="menuitem"]').length).toBe(0);
+  expect(
+    container.querySelector('[data-testid="workspace-vertical-actions"]')?.getBoundingClientRect()
+      .height,
+  ).toBe(0);
+});
diff --git a/packages/app/src/window-layout/actions.tsx b/packages/app/src/window-layout/actions.tsx
new file mode 100644
index 0000000000..06fcf57633
--- /dev/null
+++ b/packages/app/src/window-layout/actions.tsx
@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+import { Portal, PortalHost } from "@gorhom/portal";
+import { StyleSheet, View } from "react-native";
+import { RetainedPanelActivity } from "@/components/retained-panel";
+import { IconButtonChromeProvider } from "@/components/ui/icon-button-chrome";
+import { useWindowLayout } from "./context";
+import { resolveWorkspaceActionPlacement } from "./model";
+
+const HOST = "window-layout-actions";
+
+export function WindowLayoutActionsHost() {
+  return <PortalHost name={HOST} />;
+}
+
+/** The native bar guide is in window coordinates, so the host lives at the window root. */
+export function WindowLayoutActions({
+  children,
+  active,
+}: {
+  children: ReactNode;
+  active: boolean;
+}) {
+  const layout = useWindowLayout();
+  if (resolveWorkspaceActionPlacement(layout) !== "vertical-bar" || !layout?.verticalBar) {
+    return null;
+  }
+  const bar = layout.verticalBar;
+  return (
+    <Portal hostName={HOST}>
+      <View
+        testID="workspace-vertical-actions"
+        style={[
+          styles.bar,
+          { left: bar.x, top: bar.y, width: bar.width, height: bar.height },
+          !active && styles.hidden,
+        ]}
+        pointerEvents="box-none"
+      >
+        <RetainedPanelActivity active={active}>
+          <IconButtonChromeProvider value="header-island">{children}</IconButtonChromeProvider>
+        </RetainedPanelActivity>
+      </View>
+    </Portal>
+  );
+}
+
+const styles = StyleSheet.create({
+  hidden: { display: "none" },
+  bar: { position: "absolute", alignItems: "center", gap: 8 },
+});
diff --git a/packages/app/src/window-layout/context.ts b/packages/app/src/window-layout/context.ts
new file mode 100644
index 0000000000..b1da8c58f8
--- /dev/null
+++ b/packages/app/src/window-layout/context.ts
@@ -0,0 +1,23 @@
+import { createContext, useContext } from "react";
+import { useWindowDimensions } from "react-native";
+import type { TopBand, WindowLayout } from "./model";
+
+export const WindowLayoutContext = createContext<WindowLayout | null>(null);
+
+/** Published by `WindowLayoutProvider` beside the safe-area insets it derives from it. */
+export const TopBandContext = createContext<TopBand | null>(null);
+
+export function useWindowLayout(): WindowLayout | null {
+  const layout = useContext(WindowLayoutContext);
+  const { width, height } = useWindowDimensions();
+  return layout &&
+    Math.abs(layout.bounds.width - width) <= 0.5 &&
+    Math.abs(layout.bounds.height - height) <= 0.5
+    ? layout
+    : null;
+}
+
+/** The top band beside the system's status region, or null where the window has none. */
+export function useTopBand(): TopBand | null {
+  return useContext(TopBandContext);
+}
diff --git a/packages/app/src/window-layout/index.ios.tsx b/packages/app/src/window-layout/index.ios.tsx
new file mode 100644
index 0000000000..47c985dace
--- /dev/null
+++ b/packages/app/src/window-layout/index.ios.tsx
@@ -0,0 +1,64 @@
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import { StyleSheet, View, type NativeSyntheticEvent, type ViewProps } from "react-native";
+import { requireNativeViewManager } from "expo-modules-core";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
+import { TopBandContext, WindowLayoutContext, useWindowLayout } from "./context";
+import { resolveSafeAreaInsets, resolveTopBand, type WindowLayout } from "./model";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export { useTopBand } from "./context";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, TopBand, WindowLayout, WindowLayoutRect } from "./model";
+
+const GeometryProbe = requireNativeViewManager<
+  ViewProps & {
+    onGeometryChange: (event: NativeSyntheticEvent<WindowLayout>) => void;
+  }
+>("PaseoWindowLayout");
+
+export function WindowLayoutProvider({ children }: { children: ReactNode }) {
+  const [geometry, setGeometry] = useState<WindowLayout | null>(null);
+  const onGeometryChange = useCallback(
+    (event: NativeSyntheticEvent<WindowLayout>) => setGeometry(event.nativeEvent),
+    [],
+  );
+  return (
+    <WindowLayoutContext.Provider value={geometry}>
+      <View style={styles.root}>
+        <GeometryProbe
+          pointerEvents="none"
+          style={StyleSheet.absoluteFill}
+          onGeometryChange={onGeometryChange}
+        />
+        <WindowSafeAreaInsets>{children}</WindowSafeAreaInsets>
+      </View>
+    </WindowLayoutContext.Provider>
+  );
+}
+
+/**
+ * The one top and bottom inset every descendant reads through `useSafeAreaInsets()`, and
+ * the top band that `WindowChromeProvider` reads through `useTopBand()`.
+ */
+function WindowSafeAreaInsets({ children }: { children: ReactNode }) {
+  const systemInsets = useSafeAreaInsets();
+  const layout = useWindowLayout();
+  const insets = useMemo(() => resolveSafeAreaInsets(systemInsets, layout), [systemInsets, layout]);
+  const topBand = useMemo(
+    () => resolveTopBand(systemInsets.top, layout),
+    [systemInsets.top, layout],
+  );
+  return (
+    <TopBandContext.Provider value={topBand}>
+      <SafeAreaInsetsContext.Provider value={insets}>{children}</SafeAreaInsetsContext.Provider>
+    </TopBandContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({ root: { flex: 1 } });
diff --git a/packages/app/src/window-layout/index.tsx b/packages/app/src/window-layout/index.tsx
new file mode 100644
index 0000000000..13a7c4c128
--- /dev/null
+++ b/packages/app/src/window-layout/index.tsx
@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export { useTopBand } from "./context";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, TopBand, WindowLayout, WindowLayoutRect } from "./model";
+
+export function WindowLayoutProvider({ children }: { children: ReactNode }) {
+  return children;
+}
diff --git a/packages/app/src/window-layout/model.test.ts b/packages/app/src/window-layout/model.test.ts
new file mode 100644
index 0000000000..ae54a26cc9
--- /dev/null
+++ b/packages/app/src/window-layout/model.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSafeAreaInsets,
+  resolveTopBand,
+  type WindowLayout,
+  type WindowLayoutRect,
+} from "./model";
+
+const systemInsets = { top: 59, right: 0, bottom: 34, left: 0 };
+
+function layout(input: Partial<WindowLayout> = {}): WindowLayout {
+  return {
+    bounds: { x: 0, y: 0, width: 402, height: 874 },
+    verticalBarEdge: "none",
+    verticalBar: null,
+    divisions: [],
+    ...input,
+  };
+}
+
+describe("resolveSafeAreaInsets", () => {
+  it("replaces only the bottom with the measured bar clearance", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout({ bottomClearance: 24 }))).toEqual({
+      ...systemInsets,
+      bottom: 24,
+    });
+  });
+
+  it("keeps a measured zero instead of falling back to the system inset", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout({ bottomClearance: 0 })).bottom).toBe(0);
+  });
+
+  it.each([null, undefined])("leaves system insets alone without a clearance (%s)", (value) => {
+    expect(resolveSafeAreaInsets(systemInsets, layout({ bottomClearance: value }))).toBe(
+      systemInsets,
+    );
+  });
+
+  it("leaves system insets alone before the native layout arrives", () => {
+    expect(resolveSafeAreaInsets(systemInsets, null)).toBe(systemInsets);
+  });
+
+  it("starts the top where the top bar rests when it sits above the system top", () => {
+    const insets = resolveSafeAreaInsets(
+      systemInsets,
+      layout({ topBar: { x: 0, y: 12, width: 402, height: 44 } }),
+    );
+    expect(insets).toEqual({ ...systemInsets, top: 12 });
+  });
+
+  it("keeps the system top when the top bar rests at or below it", () => {
+    const insets = resolveSafeAreaInsets(
+      systemInsets,
+      layout({ topBar: { x: 0, y: 59, width: 402, height: 44 } }),
+    );
+    expect(insets).toBe(systemInsets);
+  });
+});
+
+// Measured: iPhone Duo inner screen, portrait (669×951), iOS 27.1 simulator unfolded in
+// DeviceHub.
+const duo = {
+  systemTop: 82,
+  topBar: { x: 16, y: 26, width: 509, height: 44 },
+  statusRegion: { x: 525, y: 0, width: 144, height: 82 },
+};
+
+function duoLayout(occlusions: WindowLayoutRect[]): WindowLayout {
+  return layout({
+    bounds: { x: 0, y: 0, width: 669, height: 951 },
+    topBar: duo.topBar,
+    occlusions,
+  });
+}
+
+describe("resolveTopBand", () => {
+  it("publishes the top bar's start and the status region past its trailing end", () => {
+    expect(resolveTopBand(duo.systemTop, duoLayout([duo.statusRegion]))).toEqual({
+      top: 26,
+      trailingObstruction: { width: 144, height: 56 },
+    });
+  });
+
+  it("reaches as low as the deepest occlusion beside the bar", () => {
+    const deeper = { x: 600, y: 0, width: 69, height: 96 };
+    expect(
+      resolveTopBand(duo.systemTop, duoLayout([duo.statusRegion, deeper]))?.trailingObstruction,
+    ).toEqual({ width: 144, height: 70 });
+  });
+
+  it("rounds a fractional obstruction up so controls never touch the status region", () => {
+    const fractional = layout({
+      bounds: { x: 0, y: 0, width: 669, height: 951 },
+      topBar: { x: 16, y: 26, width: 509.25, height: 44 },
+      occlusions: [{ x: 525.25, y: 0, width: 143.75, height: 82.5 }],
+    });
+    expect(resolveTopBand(duo.systemTop, fractional)?.trailingObstruction).toEqual({
+      width: 144,
+      height: 57,
+    });
+  });
+
+  it("has no trailing obstruction when the bar reaches the window's trailing edge", () => {
+    const fullWidth = layout({
+      bounds: { x: 0, y: 0, width: 669, height: 951 },
+      topBar: { x: 0, y: 26, width: 669, height: 44 },
+    });
+    expect(resolveTopBand(duo.systemTop, fullWidth)).toEqual({
+      top: 26,
+      trailingObstruction: null,
+    });
+  });
+
+  it("ignores occlusions without a top bar guide (before iOS 27.1 or unresolved)", () => {
+    const withoutGuide = layout({ topBar: null, occlusions: [duo.statusRegion] });
+    expect(resolveTopBand(duo.systemTop, withoutGuide)).toBeNull();
+    expect(resolveTopBand(duo.systemTop, layout({ occlusions: [duo.statusRegion] }))).toBeNull();
+  });
+
+  it("ignores occlusions when the top bar guide sits below the status region", () => {
+    const below = layout({
+      topBar: { x: 16, y: 82, width: 637, height: 44 },
+      occlusions: [duo.statusRegion],
+    });
+    expect(resolveTopBand(duo.systemTop, below)).toBeNull();
+  });
+
+  // Measured: iPhone 17 Pro, iOS 27.2 simulator, portrait.
+  it("is null on a regular iPhone, whose top bar starts at the status bar's bottom", () => {
+    const iphone = layout({
+      topBar: { x: 18, y: 62, width: 366, height: 44 },
+      occlusions: [{ x: 0, y: 0, width: 402, height: 54 }],
+    });
+    expect(resolveTopBand(62, iphone)).toBeNull();
+  });
+
+  // Measured: iPhone Duo outer screen, iOS 27.1 simulator. The status region is a trailing
+  // column, which the vertical bar layout already owns.
+  it("is null on the Duo outer screen, whose top bar starts below a zero system top", () => {
+    const outer = layout({
+      bounds: { x: 0, y: 0, width: 466, height: 678 },
+      verticalBarEdge: "trailing",
+      topBar: { x: 7 / 3, y: 26, width: 1139 / 3, height: 44 },
+      occlusions: [
+        { x: 1199 / 3, y: 88 / 3, width: 37, height: 37 },
+        { x: 382, y: 0, width: 84, height: 174 },
+      ],
+    });
+    expect(resolveTopBand(0, outer)).toBeNull();
+  });
+
+  it("is null before the native layout arrives", () => {
+    expect(resolveTopBand(duo.systemTop, null)).toBeNull();
+  });
+});
diff --git a/packages/app/src/window-layout/model.ts b/packages/app/src/window-layout/model.ts
new file mode 100644
index 0000000000..0226d81bd5
--- /dev/null
+++ b/packages/app/src/window-layout/model.ts
@@ -0,0 +1,119 @@
+export interface WindowLayoutRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface WindowLayout {
+  bounds: WindowLayoutRect;
+  verticalBarEdge: "none" | "leading" | "trailing";
+  verticalBar: WindowLayoutRect | null;
+  /**
+   * Points from the window's bottom edge to where a bottom bar rests, or null where
+   * the system has no bottom bar guide. Zero is a measured value.
+   */
+  bottomClearance?: number | null;
+  /** Where a top bar rests, or null until the system resolves its top bar guide. */
+  topBar?: WindowLayoutRect | null;
+  /** Active system occlusions (status region, camera, Live Activities), margins included. */
+  occlusions?: WindowLayoutRect[];
+  divisions: WindowLayoutRect[];
+}
+
+/**
+ * The band above the rectangular safe area that a top bar may use because the system
+ * occupies only its trailing end, like window controls on a desktop title bar.
+ */
+export interface TopBand {
+  /** Where the top bar starts, in window points. */
+  top: number;
+  /**
+   * The system region past the bar's trailing end, measured from the band's top, or null
+   * when the bar reaches the window's trailing edge.
+   */
+  trailingObstruction: { width: number; height: number } | null;
+}
+
+/** Null unless the top bar guide starts above the system's rectangular safe area. */
+export function resolveTopBand(systemTop: number, layout: WindowLayout | null): TopBand | null {
+  const bar = layout?.topBar;
+  if (!layout || !bar || bar.y >= systemTop) return null;
+  const top = Math.max(0, bar.y);
+  const barEnd = bar.x + bar.width;
+  const width = Math.ceil(layout.bounds.width - barEnd);
+  if (width <= 0) return { top, trailingObstruction: null };
+  const beside = (layout.occlusions ?? []).filter(
+    (frame) => frame.x + frame.width > barEnd && frame.y < bar.y + bar.height,
+  );
+  const bottom = Math.max(bar.y + bar.height, ...beside.map((frame) => frame.y + frame.height));
+  return { top, trailingObstruction: { width, height: Math.ceil(bottom - top) } };
+}
+
+/**
+ * The window's measured bars replace the rectangular safe area: the bottom bar's clearance,
+ * and the top bar's start when it sits above the system top.
+ */
+export function resolveSafeAreaInsets<Insets extends { top: number; bottom: number }>(
+  systemInsets: Insets,
+  layout: WindowLayout | null,
+): Insets {
+  const clearance = layout?.bottomClearance;
+  const bottom = typeof clearance === "number" ? clearance : systemInsets.bottom;
+  const top = resolveTopBand(systemInsets.top, layout)?.top ?? systemInsets.top;
+  return top === systemInsets.top && bottom === systemInsets.bottom
+    ? systemInsets
+    : { ...systemInsets, top, bottom };
+}
+
+export interface DesktopDivisionLayout {
+  sidebarWidth: number;
+  gap: number;
+  contentWidth: number;
+}
+
+export function resolveWorkspaceActionPlacement(
+  layout: WindowLayout | null,
+): "header" | "vertical-bar" {
+  return layout?.verticalBarEdge === "trailing" && layout.verticalBar !== null
+    ? "vertical-bar"
+    : "header";
+}
+
+export function resolveWorkspaceBarActions(
+  headerVariant: "compact" | "full",
+): readonly ("tab-count" | "overflow" | "explorer")[] {
+  return headerVariant === "compact"
+    ? ["tab-count", "overflow", "explorer"]
+    : ["overflow", "explorer"];
+}
+
+/** One book-like partition owns allocation; horizontal folds retain the normal flow. */
+export function resolveDesktopDivisionLayout(input: {
+  geometry: WindowLayout | null;
+  windowWidth: number;
+  windowHeight: number;
+  leftInset: number;
+  rightInset: number;
+}): DesktopDivisionLayout | null {
+  const { geometry, windowWidth, windowHeight, leftInset, rightInset } = input;
+  if (
+    !geometry ||
+    Math.abs(geometry.bounds.width - windowWidth) > 0.5 ||
+    Math.abs(geometry.bounds.height - windowHeight) > 0.5
+  )
+    return null;
+  const divisions = geometry.divisions.filter(
+    (frame) =>
+      frame.width > 0 &&
+      frame.height > frame.width &&
+      frame.y < windowHeight &&
+      frame.y + frame.height > 0,
+  );
+  if (divisions.length !== 1) return null;
+  const division = divisions[0];
+  const sidebarWidth = division.x - leftInset;
+  const contentWidth = windowWidth - rightInset - division.x - division.width;
+  if (sidebarWidth <= 0 || contentWidth <= 0) return null;
+  return { sidebarWidth, gap: division.width, contentWidth };
+}
diff --git a/packages/app/src/window-layout/surface.tsx b/packages/app/src/window-layout/surface.tsx
new file mode 100644
index 0000000000..e9645c799e
--- /dev/null
+++ b/packages/app/src/window-layout/surface.tsx
@@ -0,0 +1,64 @@
+import { useMemo, type ReactNode } from "react";
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
+import { useWindowLayout } from "./context";
+import { resolveWorkspaceActionPlacement, type DesktopDivisionLayout } from "./model";
+
+/** Consume horizontal safe areas once, including compact content beside a vertical bar. */
+export function WindowLayoutSurface({
+  children,
+  compact,
+  style,
+}: {
+  children: ReactNode;
+  compact: boolean;
+  style: StyleProp<ViewStyle>;
+}) {
+  const insets = useSafeAreaInsets();
+  const usesBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
+  const surfaceStyle = useMemo(
+    () => [
+      style,
+      (!compact || usesBar) && { paddingLeft: insets.left, paddingRight: insets.right },
+    ],
+    [style, compact, usesBar, insets.left, insets.right],
+  );
+  const contentInsets = useMemo(
+    () => (compact && usesBar ? { ...insets, left: 0, right: 0 } : insets),
+    [compact, usesBar, insets],
+  );
+  return (
+    <View style={surfaceStyle}>
+      <SafeAreaInsetsContext.Provider value={contentInsets}>
+        {children}
+      </SafeAreaInsetsContext.Provider>
+    </View>
+  );
+}
+
+export function WindowLayoutDivisionGap({
+  layout,
+  sidebarVisible,
+  compact,
+}: {
+  layout: DesktopDivisionLayout | null;
+  sidebarVisible: boolean;
+  compact: boolean;
+}) {
+  const style = useMemo(
+    () => ({
+      width: layout ? layout.gap + (sidebarVisible ? 0 : layout.sidebarWidth) : 0,
+    }),
+    [layout, sidebarVisible],
+  );
+  return !compact && layout ? <View style={[styles.divisionGap, style]} /> : null;
+}
+
+const styles = StyleSheet.create((theme) => ({
+  divisionGap: {
+    backgroundColor: theme.colors.surfaceSidebar,
+    borderRightWidth: 1,
+    borderRightColor: theme.colors.border,
+  },
+}));
diff --git a/packages/app/src/workspace-labels/manager-modal.tsx b/packages/app/src/workspace-labels/manager-modal.tsx
index a23e7e0925..8b0905dd16 100644
--- a/packages/app/src/workspace-labels/manager-modal.tsx
+++ b/packages/app/src/workspace-labels/manager-modal.tsx
@@ -17,7 +17,7 @@ import {
 import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { HostFilter } from "@/components/hosts/host-filter";
 import { Button } from "@/components/ui/button";
-import type { FieldControlSize } from "@/components/ui/control-geometry";
+import type { ControlSize } from "@/components/ui/control-geometry";
 import { Field, FormTextInput } from "@/components/ui/form-field";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
@@ -146,7 +146,6 @@ export function WorkspaceLabelManagerModal({
           <Button
             // Red belongs to the confirm dialog, not to the surface that opens it — docs/design.md.
             variant="outline"
-            size="md"
             disabled={disabled}
             onPress={remove}
             testID="workspace-label-manager-delete"
@@ -154,7 +153,6 @@ export function WorkspaceLabelManagerModal({
             {t("workspaceLabels.manage.delete")}
           </Button>
           <Button
-            size="md"
             style={styles.saveButton}
             disabled={disabled || !state.dirty}
             loading={state.pending}
@@ -310,7 +308,7 @@ function WorkspaceLabelEditView({
   onSubmit: () => void;
 }): ReactElement {
   const { t } = useTranslation();
-  const size: FieldControlSize = useIsCompactFormFactor() ? "md" : "sm";
+  const size: ControlSize = "md";
   return (
     <>
       <Field label={t("workspaceLabels.manage.name")}>
diff --git a/packages/app/src/workspace-tabs/agent-visibility.test.ts b/packages/app/src/workspace-tabs/agent-visibility.test.ts
index cc5b8f6e04..1da4d8627d 100644
--- a/packages/app/src/workspace-tabs/agent-visibility.test.ts
+++ b/packages/app/src/workspace-tabs/agent-visibility.test.ts
@@ -18,6 +18,7 @@ function makeAgent(input: {
   archivedAt?: Date | null;
   createdAt?: Date;
   lastActivityAt?: Date;
+  background?: boolean;
 }): Agent {
   const createdAt = input.createdAt ?? new Date("2026-03-04T00:00:00.000Z");
   const lastActivityAt = input.lastActivityAt ?? createdAt;
@@ -58,6 +59,7 @@ function makeAgent(input: {
     attentionReason: null,
     attentionTimestamp: null,
     archivedAt: input.archivedAt ?? null,
+    background: input.background ?? false,
   };
 }
 
@@ -131,6 +133,33 @@ describe("workspace agent visibility", () => {
     expect(restored.getState().pinnedAgentIdsByWorkspace["srv:ws-b"]).toBeUndefined();
   });
 
+  it("keeps a background agent active without auto-opening its tab", () => {
+    const visible = makeAgent({ id: "visible", cwd: "/repo", workspaceId: WORKSPACE_ID });
+    const classifier = makeAgent({
+      id: "classifier",
+      cwd: "/repo",
+      workspaceId: WORKSPACE_ID,
+      background: true,
+    });
+    const result = deriveWorkspaceAgentVisibility({
+      workspaceId: WORKSPACE_ID,
+      sessionAgents: new Map([
+        [visible.id, visible],
+        [classifier.id, classifier],
+      ]),
+    });
+
+    expect(result.autoOpenAgentIds).toEqual(new Set([visible.id]));
+    expect(result.activeAgentIds).toEqual(new Set([visible.id, classifier.id]));
+    expect(
+      shouldPruneWorkspaceAgentTab({
+        agentId: classifier.id,
+        agentsHydrated: true,
+        activeAgentIds: result.activeAgentIds,
+      }),
+    ).toBe(false);
+  });
+
   it("uses directory ownership before historical details when identifying foreign agents", () => {
     const own = makeAgent({ id: "own", cwd: "/repo", workspaceId: WORKSPACE_ID });
     const foreign = makeAgent({ id: "foreign", cwd: "/repo", workspaceId: "ws-2" });
diff --git a/packages/app/src/workspace-tabs/agent-visibility.ts b/packages/app/src/workspace-tabs/agent-visibility.ts
index 99e127c872..8feda493c6 100644
--- a/packages/app/src/workspace-tabs/agent-visibility.ts
+++ b/packages/app/src/workspace-tabs/agent-visibility.ts
@@ -36,11 +36,9 @@ export function deriveWorkspaceAgentVisibility(input: {
       continue;
     }
     if (!agent.archivedAt) {
+      // A background agent stays active so a tab opened by id isn't pruned, but never auto-opens.
       activeAgentIds.add(agent.id);
-      const parentAgent = agent.parentAgentId
-        ? (sessionAgents?.get(agent.parentAgentId) ?? agentDetails?.get(agent.parentAgentId))
-        : undefined;
-      if (isWorkspaceRootAgent(agent, parentAgent)) {
+      if (shouldAutoOpenAgent({ agent, sessionAgents, agentDetails })) {
         autoOpenAgentIds.add(agent.id);
       }
     }
@@ -57,6 +55,21 @@ export function deriveWorkspaceAgentVisibility(input: {
   return { activeAgentIds, autoOpenAgentIds, foreignAgentIds };
 }
 
+function shouldAutoOpenAgent(input: {
+  agent: Agent;
+  sessionAgents: Map<string, Agent> | undefined;
+  agentDetails: Map<string, Agent> | undefined;
+}): boolean {
+  const { agent, sessionAgents, agentDetails } = input;
+  if (agent.background) {
+    return false;
+  }
+  const parentAgent = agent.parentAgentId
+    ? (sessionAgents?.get(agent.parentAgentId) ?? agentDetails?.get(agent.parentAgentId))
+    : undefined;
+  return isWorkspaceRootAgent(agent, parentAgent);
+}
+
 interface AgentMapsSnapshot {
   sessions: Record<
     string,
diff --git a/packages/app/src/workspace-tabs/identity.ts b/packages/app/src/workspace-tabs/identity.ts
index 6e15d506c2..ba6dcb52f5 100644
--- a/packages/app/src/workspace-tabs/identity.ts
+++ b/packages/app/src/workspace-tabs/identity.ts
@@ -92,7 +92,7 @@ export function normalizeWorkspaceDraftTabSetup(
     thinkingOptionId: trimOptionalString(
       typeof record.thinkingOptionId === "string" ? record.thinkingOptionId : null,
     ),
-    featureValues: isPlainRecord(record.featureValues) ? { ...record.featureValues } : {},
+    providerOptions: isPlainRecord(record.providerOptions) ? { ...record.providerOptions } : {},
   };
 }
 
@@ -171,7 +171,7 @@ function workspaceDraftTabSetupsEqual(
     left.modeId === right.modeId &&
     left.model === right.model &&
     left.thinkingOptionId === right.thinkingOptionId &&
-    recordsShallowEqual(left.featureValues, right.featureValues)
+    recordsShallowEqual(left.providerOptions, right.providerOptions)
   );
 }
 
diff --git a/packages/app/src/workspace-tabs/model.ts b/packages/app/src/workspace-tabs/model.ts
index fa0e155060..f1e17fb3a6 100644
--- a/packages/app/src/workspace-tabs/model.ts
+++ b/packages/app/src/workspace-tabs/model.ts
@@ -8,7 +8,7 @@ export interface WorkspaceDraftTabSetup {
   modeId: string | null;
   model: string | null;
   thinkingOptionId: string | null;
-  featureValues: Record<string, unknown>;
+  providerOptions: Record<string, unknown>;
 }
 
 export interface WorkspaceWorkingDiffTabTarget {
diff --git a/packages/app/src/workspace-tabs/navigation.test.ts b/packages/app/src/workspace-tabs/navigation.test.ts
index c32fc91cf9..de918e53d4 100644
--- a/packages/app/src/workspace-tabs/navigation.test.ts
+++ b/packages/app/src/workspace-tabs/navigation.test.ts
@@ -33,6 +33,28 @@ it("reveals an existing main file selected from compact Explorer", () => {
   expect(existing).toBe(tabId);
   expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
 });
+it.each(["single-pane", "split-panes"] as const)(
+  "dismisses floating navigation when revealing a %s tab without pinning its dock",
+  (layoutMode) => {
+    const store = useWorkspaceLayoutStore.getState();
+    store.setLayoutMode(layoutMode);
+    usePanelStore.getState().closeDesktopAgentList();
+    usePanelStore.getState().showMobileAgentList();
+    const tabId = store.openTab({
+      workspaceKey,
+      target: { kind: "agent", agentId: "root" },
+      intent: "reveal",
+    });
+    revealWorkspaceTab(workspaceKey, tabId);
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+    expect(usePanelStore.getState().desktop.agentListOpen).toBe(false);
+    expect(
+      useWorkspaceLayoutStore.getState().getTabDestination(workspaceKey, tabId!),
+    ).toMatchObject({
+      host: "main",
+    });
+  },
+);
 it("keeps Explorer beneath a new compact file sheet", () => {
   const store = useWorkspaceLayoutStore.getState();
   store.setLayoutMode("compact");
diff --git a/packages/app/src/workspace-tabs/navigation.ts b/packages/app/src/workspace-tabs/navigation.ts
index 5e36f65102..89e46994b8 100644
--- a/packages/app/src/workspace-tabs/navigation.ts
+++ b/packages/app/src/workspace-tabs/navigation.ts
@@ -10,10 +10,11 @@ export function revealWorkspaceTab(workspaceKey: string, tabId: string | null):
   if (!destination) return null;
   if (destination.kind === "sheet") return tabId;
   store.focusTab(workspaceKey, tabId);
-  if (store.layoutMode === "compact") {
-    const panels = usePanelStore.getState();
-    if (destination.host === "explorer") panels.showMobileFileExplorer();
-    else panels.showMobileAgent();
+  const panels = usePanelStore.getState();
+  if (store.layoutMode === "compact" && destination.host === "explorer") {
+    panels.showMobileFileExplorer();
+  } else {
+    panels.showMobileAgent();
   }
   return tabId;
 }
diff --git a/packages/app/src/workspace/archive-undo/index.ts b/packages/app/src/workspace/archive-undo/index.ts
new file mode 100644
index 0000000000..c6107367aa
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/index.ts
@@ -0,0 +1,8 @@
+export {
+  archiveWorkspaceWithUndo,
+  undoLatestWorkspaceArchive,
+  type UndoableWorkspaceArchiveClient,
+} from "./internal/undo-window";
+export { WorkspaceArchiveUndoShortcutHost } from "./internal/undo-shortcut-host";
+export { supportsWorkspaceArchiveUndo } from "./internal/capability";
+export { useWorkspaceArchiveUndoRunning } from "./internal/use-workspace-archive-undo-running";
diff --git a/packages/app/src/workspace/archive-undo/internal/capability.ts b/packages/app/src/workspace/archive-undo/internal/capability.ts
new file mode 100644
index 0000000000..5f5a4a7c20
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/capability.ts
@@ -0,0 +1,8 @@
+import { useSessionStore } from "@/stores/session-store";
+
+export function supportsWorkspaceArchiveUndo(serverId: string): boolean {
+  return (
+    useSessionStore.getState().sessions[serverId]?.serverInfo?.features?.workspaceArchiveUndo ===
+    true
+  );
+}
diff --git a/packages/app/src/workspace/archive-undo/internal/undo-shortcut-host.tsx b/packages/app/src/workspace/archive-undo/internal/undo-shortcut-host.tsx
new file mode 100644
index 0000000000..3d2ea9c4e4
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/undo-shortcut-host.tsx
@@ -0,0 +1,22 @@
+import { useKeyboardActionHandler } from "@/hooks/use-keyboard-action-handler";
+import type { KeyboardActionId } from "@/keyboard/keyboard-action-dispatcher";
+import { hasUndoableWorkspaceArchive, undoLatestWorkspaceArchive } from "./undo-window";
+
+const UNDO_ARCHIVE_ACTIONS: readonly KeyboardActionId[] = ["workspace.archive.undo"];
+
+/**
+ * Cmd/Ctrl+Z for the archive toast. Mounted once at the app root because the row that started
+ * the archive unmounts as soon as its workspace hides. It claims the key only while an archive
+ * can be undone, so the key falls through to text undo the rest of the time.
+ */
+export function WorkspaceArchiveUndoShortcutHost(): null {
+  useKeyboardActionHandler({
+    handlerId: "workspace-archive-undo-global",
+    actions: UNDO_ARCHIVE_ACTIONS,
+    enabled: true,
+    priority: 0,
+    isActive: hasUndoableWorkspaceArchive,
+    handle: undoLatestWorkspaceArchive,
+  });
+  return null;
+}
diff --git a/packages/app/src/workspace/archive-undo/internal/undo-window.test.ts b/packages/app/src/workspace/archive-undo/internal/undo-window.test.ts
new file mode 100644
index 0000000000..efa9a539ac
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/undo-window.test.ts
@@ -0,0 +1,301 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ToastApi, ToastShowOptions } from "@/components/toast-host";
+import { clearWorkspaceArchivePending } from "@/contexts/session-workspace-upserts";
+import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { useSessionStore, type WorkspaceDescriptor } from "@/stores/session-store";
+import { seedSessionHosts } from "@/test/seed-session";
+import {
+  archiveWorkspaceWithUndo,
+  undoLatestWorkspaceArchive,
+  type UndoableWorkspaceArchiveClient,
+} from "@/workspace/archive-undo";
+
+const SERVER_ID = "workspace-archive-undo-window";
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+}
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function workspace(id: string): WorkspaceDescriptor {
+  return {
+    createdAt: null,
+    lastUserMessageAt: null,
+    id,
+    projectId: "project",
+    projectDisplayName: "Project",
+    projectRootPath: "/repo/project",
+    workspaceDirectory: `/repo/project/${id}`,
+    projectKind: "git",
+    workspaceKind: "worktree",
+    name: id,
+    status: "done",
+    archivingAt: null,
+    statusEnteredAt: null,
+    diffStat: null,
+    scripts: [],
+  };
+}
+
+/** A toast host with one slot, like the app's: a new toast replaces the shown one. */
+function createToastHost() {
+  let shown: { content: ReactNode; options?: ToastShowOptions; dismiss: () => void } | null = null;
+  const errors: string[] = [];
+  const api: ToastApi = {
+    show: (content, options) => {
+      const previous = shown;
+      const entry = {
+        content,
+        options,
+        dismiss: () => {
+          if (shown !== entry) return;
+          shown = null;
+          options?.onDismiss?.();
+        },
+      };
+      shown = entry;
+      previous?.options?.onDismiss?.();
+      return entry.dismiss;
+    },
+    copied: () => {},
+    error: (message) => {
+      errors.push(message);
+      api.show(message);
+    },
+  };
+  return {
+    api,
+    errors,
+    get shownTestID() {
+      return shown?.options?.testID ?? null;
+    },
+    timeOut: () => shown?.dismiss(),
+  };
+}
+
+type ArchivePayload = Awaited<ReturnType<UndoableWorkspaceArchiveClient["archiveWorkspace"]>>;
+
+function createClient() {
+  const archives = new Map<string, Deferred<ArchivePayload>>();
+  const undos = new Map<string, Deferred<void>>();
+  const client: UndoableWorkspaceArchiveClient = {
+    archiveWorkspace: (workspaceId) => {
+      const response = deferred<ArchivePayload>();
+      archives.set(workspaceId, response);
+      return response.promise;
+    },
+    undoWorkspaceArchive: (workspaceId) => {
+      const response = deferred<void>();
+      undos.set(workspaceId, response);
+      return response.promise;
+    },
+  };
+  return {
+    client,
+    finishArchive: (workspaceId: string, payload: Partial<ArchivePayload> = {}) =>
+      archives.get(workspaceId)?.resolve({ error: null, ...payload }),
+    undoRequested: (workspaceId: string) => undos.has(workspaceId),
+    finishUndo: (workspaceId: string) => undos.get(workspaceId)?.resolve(),
+    failUndo: (workspaceId: string, error: Error) => undos.get(workspaceId)?.reject(error),
+  };
+}
+
+function storedWorkspace(id: string): WorkspaceDescriptor | undefined {
+  return useSessionStore.getState().sessions[SERVER_ID]?.workspaces.get(id);
+}
+
+function startArchive(input: {
+  host: ReturnType<typeof createClient>;
+  toast: ReturnType<typeof createToastHost>;
+  workspaceId: string;
+  committed: string[];
+}) {
+  return archiveWorkspaceWithUndo({
+    client: input.host.client,
+    workspace: { serverId: SERVER_ID, workspaceId: input.workspaceId },
+    toast: input.toast.api,
+    onArchiveCommitted: () => input.committed.push(input.workspaceId),
+  });
+}
+
+beforeEach(() => {
+  seedSessionHosts([SERVER_ID]);
+  useSessionStore.getState().initializeSession(SERVER_ID, {} as DaemonClient);
+  getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [workspace("a"), workspace("b")]);
+});
+
+afterEach(() => {
+  undoLatestWorkspaceArchive();
+  clearWorkspaceArchivePending({ serverId: SERVER_ID, workspaceId: "a" });
+  clearWorkspaceArchivePending({ serverId: SERVER_ID, workspaceId: "b" });
+  seedSessionHosts([]);
+  useSessionStore.setState((state) => ({ ...state, sessions: {} }));
+});
+
+describe("archiveWorkspaceWithUndo", () => {
+  it("commits the archive only once its toast is gone", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+    const committed: string[] = [];
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed });
+    expect(toast.shownTestID).toBe("workspace-archived-toast");
+    host.finishArchive("a");
+    await archive;
+    expect(committed).toEqual([]);
+
+    toast.timeOut();
+    expect({ committed, undone: undoLatestWorkspaceArchive() }).toEqual({
+      committed: ["a"],
+      undone: false,
+    });
+  });
+
+  it("keeps the layout when another client restores the workspace before the toast closes", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+    const committed: string[] = [];
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed });
+    host.finishArchive("a");
+    await archive;
+    clearWorkspaceArchivePending({ serverId: SERVER_ID, workspaceId: "a" });
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [workspace("a")]);
+    toast.timeOut();
+
+    expect({ committed, row: storedWorkspace("a") }).toEqual({
+      committed: [],
+      row: workspace("a"),
+    });
+  });
+
+  it("commits when the archive finishes after its toast already timed out", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+    const committed: string[] = [];
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed });
+    toast.timeOut();
+    expect(committed).toEqual([]);
+    host.finishArchive("a");
+    await archive;
+
+    expect(committed).toEqual(["a"]);
+  });
+
+  it("undo during a running archive brings the row back and never commits", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+    const committed: string[] = [];
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed });
+    expect(storedWorkspace("a")).toBeUndefined();
+
+    expect(undoLatestWorkspaceArchive()).toBe(true);
+    expect({
+      row: storedWorkspace("a"),
+      undoRequested: host.undoRequested("a"),
+      toast: toast.shownTestID,
+    }).toEqual({ row: workspace("a"), undoRequested: true, toast: null });
+
+    host.finishArchive("a", { canceled: true, error: "Workspace archive was undone" });
+    await archive;
+    host.finishUndo("a");
+    toast.timeOut();
+
+    expect({ committed, errors: toast.errors, row: storedWorkspace("a") }).toEqual({
+      committed: [],
+      errors: [],
+      row: workspace("a"),
+    });
+  });
+
+  it("does not claim Cmd+Z when no archive can be undone", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+
+    expect(undoLatestWorkspaceArchive()).toBe(false);
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed: [] });
+    host.finishArchive("a");
+    await archive;
+    toast.timeOut();
+
+    expect(undoLatestWorkspaceArchive()).toBe(false);
+    expect(host.undoRequested("a")).toBe(false);
+  });
+
+  it("a newer archive takes over undo and commits the older one", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+    const committed: string[] = [];
+
+    const first = startArchive({ host, toast, workspaceId: "a", committed });
+    host.finishArchive("a");
+    await first;
+    const second = startArchive({ host, toast, workspaceId: "b", committed });
+    expect(committed).toEqual(["a"]);
+
+    expect(undoLatestWorkspaceArchive()).toBe(true);
+    expect({ undoA: host.undoRequested("a"), undoB: host.undoRequested("b") }).toEqual({
+      undoA: false,
+      undoB: true,
+    });
+    host.finishArchive("b", { canceled: true });
+    await second;
+  });
+
+  it("reports a failed undo and hides the row again", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed: [] });
+    host.finishArchive("a");
+    await archive;
+    undoLatestWorkspaceArchive();
+    host.failUndo("a", new Error("Branch is gone"));
+    await expect.poll(() => toast.errors).toEqual(["Couldn't undo the archive"]);
+
+    expect(storedWorkspace("a")).toBeUndefined();
+  });
+
+  it("stays quiet about an archive that failed after the user undid it", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed: [] });
+    undoLatestWorkspaceArchive();
+    host.finishArchive("a", { error: "registry unavailable" });
+
+    await expect(archive).resolves.toBeUndefined();
+    expect(toast.errors).toEqual([]);
+  });
+
+  it("rejects a failed archive, closes its toast and puts the row back", async () => {
+    const host = createClient();
+    const toast = createToastHost();
+
+    const archive = startArchive({ host, toast, workspaceId: "a", committed: [] });
+    host.finishArchive("a", { error: "registry unavailable" });
+
+    await expect(archive).rejects.toThrow("registry unavailable");
+    expect({
+      toast: toast.shownTestID,
+      undone: undoLatestWorkspaceArchive(),
+      row: storedWorkspace("a"),
+    }).toEqual({ toast: null, undone: false, row: workspace("a") });
+  });
+});
diff --git a/packages/app/src/workspace/archive-undo/internal/undo-window.tsx b/packages/app/src/workspace/archive-undo/internal/undo-window.tsx
new file mode 100644
index 0000000000..5dc968124e
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/undo-window.tsx
@@ -0,0 +1,129 @@
+import type { DismissToast, ToastApi } from "@/components/toast-host";
+import { i18n } from "@/i18n/i18next";
+import type { WorkspaceDescriptor } from "@/stores/session-store";
+import {
+  beginOptimisticWorkspaceArchive,
+  isWorkspaceListed,
+  undoWorkspaceArchiveOptimistically,
+  type WorkspaceArchiveTarget,
+} from "@/workspace/workspace-archive";
+import { WorkspaceArchivedToast } from "./workspace-archived-toast";
+
+/** How long the archived toast, and with it the chance to undo, stays up. */
+export const WORKSPACE_ARCHIVE_UNDO_WINDOW_MS = 6000;
+
+export interface UndoableWorkspaceArchiveClient {
+  archiveWorkspace: (workspaceId: string) => Promise<{ error: string | null; canceled?: boolean }>;
+  undoWorkspaceArchive: (workspaceId: string) => Promise<void>;
+}
+
+interface UndoWindowInput {
+  client: UndoableWorkspaceArchiveClient;
+  workspace: WorkspaceArchiveTarget;
+  toast: ToastApi;
+  hidden: WorkspaceDescriptor | null;
+  onArchiveCommitted: () => void;
+}
+
+let latest: UndoWindow | null = null;
+
+/**
+ * One archive's chance to be undone. It opens when the row hides and closes when its toast
+ * leaves the screen (timeout, replaced by another toast, or undo).
+ *
+ * - `open`: undo is offered.
+ * - `closed`: undo is no longer offered; the archive stands.
+ * - `undone`: the user took the archive back.
+ */
+class UndoWindow {
+  phase: "open" | "closed" | "undone" = "open";
+  private archived = false;
+  private readonly dismissToast: DismissToast;
+
+  constructor(private readonly input: UndoWindowInput) {
+    this.dismissToast = input.toast.show(<WorkspaceArchivedToast onUndo={this.undo} />, {
+      durationMs: WORKSPACE_ARCHIVE_UNDO_WINDOW_MS,
+      testID: "workspace-archived-toast",
+      onDismiss: this.close,
+    });
+  }
+
+  /** The host finished the archive. It commits now if undo is no longer offered. */
+  archiveFinished(): void {
+    this.archived = true;
+    if (this.phase === "closed") this.commit();
+  }
+
+  /** The archive failed on the host, so there is nothing left to undo. */
+  archiveFailed(): void {
+    this.close();
+    this.dismissToast();
+  }
+
+  readonly close = (): void => {
+    if (this.phase !== "open") return;
+    this.phase = "closed";
+    this.release();
+    if (this.archived) this.commit();
+  };
+
+  /** Commits unless the workspace is back by now, for example restored from another client. */
+  private commit(): void {
+    if (isWorkspaceListed(this.input.workspace)) return;
+    this.input.onArchiveCommitted();
+  }
+
+  readonly undo = (): boolean => {
+    if (this.phase !== "open") return false;
+    this.phase = "undone";
+    this.release();
+    this.dismissToast();
+    void undoWorkspaceArchiveOptimistically(this.input).catch((error: unknown) => {
+      console.warn("[workspace-archive-undo] undo failed", error);
+      this.input.toast.error(i18n.t("sidebar.workspace.toasts.undoArchiveFailed"));
+    });
+    return true;
+  };
+
+  private release(): void {
+    if (latest === this) latest = null;
+  }
+}
+
+/**
+ * Archives a workspace and offers to undo it until the toast goes away.
+ *
+ * `onArchiveCommitted` runs once the archive both finished on the host and can no longer be
+ * undone, and only if the workspace is still gone then. Local state the undo would want back
+ * (tabs, layout) survives the window, and survives a restore from another client.
+ * Rejects when the archive fails and was not undone; the row is back by then.
+ */
+export async function archiveWorkspaceWithUndo(input: {
+  client: UndoableWorkspaceArchiveClient;
+  workspace: WorkspaceArchiveTarget;
+  toast: ToastApi;
+  onArchiveCommitted: () => void;
+}): Promise<void> {
+  const archive = beginOptimisticWorkspaceArchive(input);
+  const window = new UndoWindow({ ...input, hidden: archive.hidden });
+  latest = window;
+
+  let outcome: Awaited<typeof archive.done>;
+  try {
+    outcome = await archive.done;
+  } catch (error) {
+    if (window.phase === "undone") return;
+    window.archiveFailed();
+    throw error;
+  }
+  if (outcome === "archived") window.archiveFinished();
+}
+
+/** Undoes the most recent archive while its toast is up. Returns false when there is none. */
+export function undoLatestWorkspaceArchive(): boolean {
+  return latest ? latest.undo() : false;
+}
+
+export function hasUndoableWorkspaceArchive(): boolean {
+  return latest !== null;
+}
diff --git a/packages/app/src/workspace/archive-undo/internal/use-workspace-archive-undo-running.ts b/packages/app/src/workspace/archive-undo/internal/use-workspace-archive-undo-running.ts
new file mode 100644
index 0000000000..31e9dd54fd
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/use-workspace-archive-undo-running.ts
@@ -0,0 +1,21 @@
+import { useCallback, useSyncExternalStore } from "react";
+import {
+  isWorkspaceArchiveUndoPending,
+  subscribeWorkspaceArchiveIntents,
+} from "@/contexts/session-workspace-upserts";
+
+/**
+ * True while this client's undo of the workspace's archive is running on the host. Until it
+ * settles, the workspace's agents may still read as archived even though they are coming back.
+ */
+export function useWorkspaceArchiveUndoRunning(input: {
+  serverId: string;
+  workspaceId: string | null;
+}): boolean {
+  const { serverId, workspaceId } = input;
+  const read = useCallback(
+    () => isWorkspaceArchiveUndoPending({ serverId, workspaceId }),
+    [serverId, workspaceId],
+  );
+  return useSyncExternalStore(subscribeWorkspaceArchiveIntents, read, read);
+}
diff --git a/packages/app/src/workspace/archive-undo/internal/workspace-archived-toast.tsx b/packages/app/src/workspace/archive-undo/internal/workspace-archived-toast.tsx
new file mode 100644
index 0000000000..4cca52fd48
--- /dev/null
+++ b/packages/app/src/workspace/archive-undo/internal/workspace-archived-toast.tsx
@@ -0,0 +1,49 @@
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { Button } from "@/components/ui/button";
+import { Shortcut } from "@/components/ui/shortcut";
+import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
+
+export function WorkspaceArchivedToast({ onUndo }: { onUndo: () => void }) {
+  const { t } = useTranslation();
+  const undoKeys = useShortcutKeys("undo-archive-workspace");
+  const undoShortcut = useMemo(
+    () => (undoKeys ? <Shortcut chord={undoKeys} style={styles.shortcut} /> : null),
+    [undoKeys],
+  );
+
+  return (
+    <View style={styles.row}>
+      <Text style={styles.message}>{t("sidebar.workspace.toasts.archived")}</Text>
+      <Button
+        size="sm"
+        onPress={onUndo}
+        testID="workspace-archived-toast-undo"
+        trailing={undoShortcut}
+      >
+        {t("sidebar.workspace.toasts.undoArchive")}
+      </Button>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  row: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  // Cancels the badge's own inset, which would otherwise add to the button's gap.
+  shortcut: {
+    marginLeft: -theme.spacing[1],
+  },
+  message: {
+    flexShrink: 1,
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.base,
+    fontWeight: theme.fontWeight.normal,
+  },
+}));
diff --git a/packages/app/src/workspace/open-in-editor/button.tsx b/packages/app/src/workspace/open-in-editor/button.tsx
index fbcef49b83..5df614ec50 100644
--- a/packages/app/src/workspace/open-in-editor/button.tsx
+++ b/packages/app/src/workspace/open-in-editor/button.tsx
@@ -27,7 +27,7 @@ import { planWorkspaceOpenTargets } from "@/workspace/open-in-editor/planner";
 import type { Theme } from "@/styles/theme";
 import { ForgeBrandIcon } from "@/git/forge-icon";
 import { getForgePresentation } from "@/git/forge";
-import { buttonControlHeight, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { extraMutedIconColorMapping } from "@/components/ui/icon-button-chrome";
 
 interface WorkspaceOpenInEditorButtonProps {
@@ -297,10 +297,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
@@ -317,10 +314,7 @@ const styles = StyleSheet.create((theme) => ({
     position: "relative",
   },
   splitButtonPrimaryIconOnly: {
-    width: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     paddingHorizontal: 0,
     justifyContent: "center",
     position: "relative",
@@ -348,10 +342,7 @@ const styles = StyleSheet.create((theme) => ({
     transform: [{ scale: 0.8 }],
   },
   splitButtonCaret: {
-    width: {
-      xs: buttonControlHeight.xs,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderLeftWidth: theme.borderWidth[1],
diff --git a/packages/app/src/workspace/use-workspace-archive.ts b/packages/app/src/workspace/use-workspace-archive.ts
index 7dc86a61ae..9608cef0cd 100644
--- a/packages/app/src/workspace/use-workspace-archive.ts
+++ b/packages/app/src/workspace/use-workspace-archive.ts
@@ -10,6 +10,7 @@ import {
 import type { WorkspaceDescriptor } from "@/stores/session-store";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
 import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
+import { archiveWorkspaceWithUndo, supportsWorkspaceArchiveUndo } from "@/workspace/archive-undo";
 import { archiveWorkspaceOptimistically } from "@/workspace/workspace-archive";
 
 function purgeArchivedWorkspaceState(input: { serverId: string; workspaceId: string }): void {
@@ -58,17 +59,22 @@ export function useWorkspaceArchive(input: ArchiveWorkspaceInput): WorkspaceArch
       toast.error(t("sidebar.workspace.toasts.hostDisconnected"));
       return;
     }
+    const workspace = { serverId, workspaceId };
     onSetHiding?.(true);
     try {
       onArchiveStarted();
-      await archiveWorkspaceOptimistically({
-        client,
-        workspace: {
-          serverId,
-          workspaceId,
-        },
-      });
-      purgeArchivedWorkspaceState({ serverId, workspaceId });
+      if (supportsWorkspaceArchiveUndo(serverId)) {
+        await archiveWorkspaceWithUndo({
+          client,
+          workspace,
+          toast,
+          onArchiveCommitted: () => purgeArchivedWorkspaceState(workspace),
+        });
+      } else {
+        // COMPAT(workspaceArchiveUndo): hosts before v0.15.3 cannot undo; remove after 2027-05-06.
+        await archiveWorkspaceOptimistically({ client, workspace });
+        purgeArchivedWorkspaceState(workspace);
+      }
     } catch (error) {
       toast.error(
         error instanceof Error ? error.message : t("sidebar.workspace.toasts.archiveFailed"),
diff --git a/packages/app/src/workspace/workspace-archive.test.ts b/packages/app/src/workspace/workspace-archive.test.ts
index 3facdee34e..e519bcffb3 100644
--- a/packages/app/src/workspace/workspace-archive.test.ts
+++ b/packages/app/src/workspace/workspace-archive.test.ts
@@ -5,11 +5,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   clearWorkspaceArchivePending,
   isWorkspaceArchivePending,
+  isWorkspaceArchiveUndoPending,
 } from "@/contexts/session-workspace-upserts";
 import { useSessionStore, type WorkspaceDescriptor } from "@/stores/session-store";
 import {
   archiveWorkspaceOptimistically,
   archiveWorkspacesOptimistically,
+  beginOptimisticWorkspaceArchive,
+  undoWorkspaceArchiveOptimistically,
   type WorkspaceArchiveTarget,
 } from "@/workspace/workspace-archive";
 
@@ -21,12 +24,14 @@ type ArchiveWorkspacePayload = Awaited<ReturnType<DaemonClient["archiveWorkspace
 function archivePayload(input: {
   workspaceId: string;
   error?: string | null;
+  canceled?: boolean;
 }): ArchiveWorkspacePayload {
   return {
     requestId: "request",
     workspaceId: input.workspaceId,
     archivedAt: null,
     error: input.error ?? null,
+    ...(input.canceled ? { canceled: true } : {}),
   };
 }
 
@@ -224,3 +229,140 @@ describe("archiveWorkspacesOptimistically", () => {
     expect(storedWorkspaceOn(SECOND_SERVER_ID, second.id)).toBeUndefined();
   });
 });
+
+describe("undoWorkspaceArchiveOptimistically", () => {
+  it("brings the row back while the host undoes the archive it is still running", async () => {
+    const archived = workspace();
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [archived]);
+    const archiveResponse = deferred<ArchiveWorkspacePayload>();
+    const undoResponse = deferred<void>();
+    const archive = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => archiveResponse.promise),
+      workspace: target(),
+    });
+
+    const undo = undoWorkspaceArchiveOptimistically({
+      client: { undoWorkspaceArchive: async () => undoResponse.promise },
+      workspace: target(),
+      hidden: archive.hidden,
+    });
+    expect(storedWorkspace(archived.id)).toEqual(archived);
+
+    // The host answers the canceled archive before the undo.
+    archiveResponse.resolve(archivePayload({ workspaceId: archived.id, canceled: true }));
+    await expect(archive.done).resolves.toBe("canceled");
+    undoResponse.resolve();
+    await undo;
+
+    expect({
+      row: storedWorkspace(archived.id),
+      archivePending: isWorkspaceArchivePending(target()),
+      undoPending: isWorkspaceArchiveUndoPending(target()),
+    }).toEqual({ row: archived, archivePending: false, undoPending: false });
+  });
+
+  it("hides the row again when the host cannot undo the archive", async () => {
+    const archived = workspace();
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [archived]);
+    const archive = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => archivePayload({ workspaceId: archived.id })),
+      workspace: target(),
+    });
+    await archive.done;
+
+    await expect(
+      undoWorkspaceArchiveOptimistically({
+        client: {
+          undoWorkspaceArchive: async () => {
+            throw new Error("Branch is gone");
+          },
+        },
+        workspace: target(),
+        hidden: archive.hidden,
+      }),
+    ).rejects.toThrow("Branch is gone");
+
+    expect(storedWorkspace(archived.id)).toBeUndefined();
+    expect(isWorkspaceArchiveUndoPending(target())).toBe(false);
+  });
+
+  it("leaves a re-archived row hidden when the earlier undo settles", async () => {
+    const archived = workspace();
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [archived]);
+    const undoResponse = deferred<void>();
+    const first = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => archivePayload({ workspaceId: archived.id })),
+      workspace: target(),
+    });
+    await first.done;
+    const undo = undoWorkspaceArchiveOptimistically({
+      client: { undoWorkspaceArchive: async () => undoResponse.promise },
+      workspace: target(),
+      hidden: first.hidden,
+    });
+
+    const rearchive = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => new Promise<ArchiveWorkspacePayload>(() => {})),
+      workspace: target(),
+    });
+    undoResponse.resolve();
+    await undo;
+
+    expect(rearchive.hidden).toEqual(archived);
+    expect(storedWorkspace(archived.id)).toBeUndefined();
+    expect(isWorkspaceArchivePending(target())).toBe(true);
+  });
+  it("puts the row back when another client's undo cancels this archive", async () => {
+    const archived = workspace();
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [archived]);
+    const archive = beginOptimisticWorkspaceArchive({
+      client: createClient(async () =>
+        archivePayload({ workspaceId: archived.id, canceled: true, error: "undone" }),
+      ),
+      workspace: target(),
+    });
+
+    await expect(archive.done).resolves.toBe("canceled");
+
+    expect({
+      row: storedWorkspace(archived.id),
+      archivePending: isWorkspaceArchivePending(target()),
+    }).toEqual({ row: archived, archivePending: false });
+  });
+
+  it("an earlier undo settling keeps holding the row for a later undo", async () => {
+    const archived = workspace();
+    getHostRuntimeStore().acceptWorkspaceSnapshots(SERVER_ID, [archived]);
+    const firstUndoResponse = deferred<void>();
+    const secondUndoResponse = deferred<void>();
+    const first = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => archivePayload({ workspaceId: archived.id })),
+      workspace: target(),
+    });
+    await first.done;
+    const firstUndo = undoWorkspaceArchiveOptimistically({
+      client: { undoWorkspaceArchive: async () => firstUndoResponse.promise },
+      workspace: target(),
+      hidden: first.hidden,
+    });
+    const second = beginOptimisticWorkspaceArchive({
+      client: createClient(async () => new Promise<ArchiveWorkspacePayload>(() => {})),
+      workspace: target(),
+    });
+    const secondUndo = undoWorkspaceArchiveOptimistically({
+      client: { undoWorkspaceArchive: async () => secondUndoResponse.promise },
+      workspace: target(),
+      hidden: second.hidden,
+    });
+
+    firstUndoResponse.resolve();
+    await firstUndo;
+
+    expect({
+      row: storedWorkspace(archived.id),
+      undoPending: isWorkspaceArchiveUndoPending(target()),
+    }).toEqual({ row: archived, undoPending: true });
+    secondUndoResponse.resolve();
+    await secondUndo;
+  });
+});
diff --git a/packages/app/src/workspace/workspace-archive.ts b/packages/app/src/workspace/workspace-archive.ts
index a4e5a00e80..fd757934ef 100644
--- a/packages/app/src/workspace/workspace-archive.ts
+++ b/packages/app/src/workspace/workspace-archive.ts
@@ -1,7 +1,10 @@
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import {
-  clearWorkspaceArchivePending,
+  isWorkspaceArchiveIntentCurrent,
   markWorkspaceArchivePending,
+  markWorkspaceArchiveUndoPending,
+  settleWorkspaceArchiveIntent,
+  type WorkspaceArchiveIntent,
 } from "@/contexts/session-workspace-upserts";
 import { useSessionStore, type WorkspaceDescriptor } from "@/stores/session-store";
 import { resolveWorkspaceMapKeyByIdentity } from "@/utils/workspace-identity";
@@ -13,11 +16,25 @@ export interface WorkspaceArchiveTarget {
 }
 
 interface WorkspaceArchiveClient {
-  archiveWorkspace: (workspaceId: string) => Promise<{ error: string | null }>;
+  archiveWorkspace: (workspaceId: string) => Promise<{ error: string | null; canceled?: boolean }>;
+}
+
+interface WorkspaceArchiveUndoClient {
+  undoWorkspaceArchive: (workspaceId: string) => Promise<void>;
+}
+
+/** `canceled`: an undo stopped the archive on the host before it finished. */
+export type WorkspaceArchiveOutcome = "archived" | "canceled";
+
+export interface OptimisticWorkspaceArchive {
+  /** The row as it was before the archive hid it, for undo to put back. */
+  hidden: WorkspaceDescriptor | null;
+  done: Promise<WorkspaceArchiveOutcome>;
 }
 
 interface OptimisticWorkspaceArchiveSnapshot {
   workspace: WorkspaceDescriptor | null;
+  intent: WorkspaceArchiveIntent;
 }
 
 export interface WorkspaceArchiveFailure {
@@ -38,32 +55,42 @@ function isWorkspaceArchiveFailure(error: unknown): error is WorkspaceArchiveFai
   );
 }
 
-function hideWorkspaceOptimistically(
-  workspace: WorkspaceArchiveTarget,
-): OptimisticWorkspaceArchiveSnapshot {
+function findListedWorkspace(workspace: WorkspaceArchiveTarget): WorkspaceDescriptor | null {
   const workspaces = useSessionStore.getState().sessions[workspace.serverId]?.workspaces;
   const workspaceKey = resolveWorkspaceMapKeyByIdentity({
     workspaces,
     workspaceId: workspace.workspaceId,
   });
-  const snapshot = workspaceKey ? (workspaces?.get(workspaceKey) ?? null) : null;
-  markWorkspaceArchivePending({
+  return workspaceKey ? (workspaces?.get(workspaceKey) ?? null) : null;
+}
+
+/** True when the workspace is in this client's list, for example after another client restored it. */
+export function isWorkspaceListed(workspace: WorkspaceArchiveTarget): boolean {
+  return findListedWorkspace(workspace) !== null;
+}
+
+function hideWorkspaceOptimistically(
+  workspace: WorkspaceArchiveTarget,
+): OptimisticWorkspaceArchiveSnapshot {
+  const snapshot = findListedWorkspace(workspace);
+  const intent = markWorkspaceArchivePending({
     serverId: workspace.serverId,
     workspaceId: workspace.workspaceId,
   });
   getHostRuntimeStore().removeWorkspaceSnapshot(workspace.serverId, workspace.workspaceId);
-  return { workspace: snapshot };
+  return { workspace: snapshot, intent };
 }
 
+/**
+ * Puts back a row whose archive did not happen. Skipped when a newer request on this client
+ * (an undo, or another archive) owns the row by now.
+ */
 function restoreOptimisticallyHiddenWorkspace(input: {
   serverId: string;
-  workspaceId: string;
   snapshot: OptimisticWorkspaceArchiveSnapshot;
 }): void {
-  clearWorkspaceArchivePending({
-    serverId: input.serverId,
-    workspaceId: input.workspaceId,
-  });
+  if (!isWorkspaceArchiveIntentCurrent(input.snapshot.intent)) return;
+  settleWorkspaceArchiveIntent(input.snapshot.intent);
   if (input.snapshot.workspace) {
     getHostRuntimeStore().acceptWorkspaceSnapshots(input.serverId, [input.snapshot.workspace]);
   }
@@ -72,31 +99,75 @@ function restoreOptimisticallyHiddenWorkspace(input: {
 async function archiveWorkspaceOrThrow(input: {
   client: WorkspaceArchiveClient;
   workspaceId: string;
-}): Promise<void> {
+}): Promise<WorkspaceArchiveOutcome> {
   const payload = await input.client.archiveWorkspace(input.workspaceId);
+  if (payload.canceled) {
+    return "canceled";
+  }
   if (payload.error) {
     throw new Error(payload.error);
   }
+  return "archived";
+}
+
+/**
+ * Hides the row now and archives it on the host. A failed archive puts the row back, and so
+ * does a canceled one: an undo from another client stopped it, so the workspace stays.
+ */
+export function beginOptimisticWorkspaceArchive(input: {
+  client: WorkspaceArchiveClient;
+  workspace: WorkspaceArchiveTarget;
+}): OptimisticWorkspaceArchive {
+  const snapshot = hideWorkspaceOptimistically(input.workspace);
+  const done = (async () => {
+    try {
+      const outcome = await archiveWorkspaceOrThrow({
+        client: input.client,
+        workspaceId: input.workspace.workspaceId,
+      });
+      if (outcome === "canceled") {
+        restoreOptimisticallyHiddenWorkspace({ serverId: input.workspace.serverId, snapshot });
+      }
+      return outcome;
+    } catch (error) {
+      restoreOptimisticallyHiddenWorkspace({ serverId: input.workspace.serverId, snapshot });
+      throw error;
+    }
+  })();
+  return { hidden: snapshot.workspace, done };
 }
 
 export async function archiveWorkspaceOptimistically(input: {
   client: WorkspaceArchiveClient;
   workspace: WorkspaceArchiveTarget;
-}): Promise<void> {
-  const snapshot = hideWorkspaceOptimistically(input.workspace);
+}): Promise<WorkspaceArchiveOutcome> {
+  return beginOptimisticWorkspaceArchive(input).done;
+}
 
+/**
+ * Puts the archived row back now and asks the host to undo the archive, whether it is still
+ * running or already finished. A failed undo hides the row again, unless the user archived
+ * it again in the meantime.
+ */
+export async function undoWorkspaceArchiveOptimistically(input: {
+  client: WorkspaceArchiveUndoClient;
+  workspace: WorkspaceArchiveTarget;
+  hidden: WorkspaceDescriptor | null;
+}): Promise<void> {
+  const { serverId, workspaceId } = input.workspace;
+  const intent = markWorkspaceArchiveUndoPending({ serverId, workspaceId });
+  if (input.hidden) {
+    getHostRuntimeStore().acceptWorkspaceSnapshots(serverId, [input.hidden]);
+  }
   try {
-    await archiveWorkspaceOrThrow({
-      client: input.client,
-      workspaceId: input.workspace.workspaceId,
-    });
+    await input.client.undoWorkspaceArchive(workspaceId);
   } catch (error) {
-    restoreOptimisticallyHiddenWorkspace({
-      serverId: input.workspace.serverId,
-      workspaceId: input.workspace.workspaceId,
-      snapshot,
-    });
+    if (isWorkspaceArchiveIntentCurrent(intent)) {
+      getHostRuntimeStore().removeWorkspaceSnapshot(serverId, workspaceId);
+    }
     throw error;
+  } finally {
+    settleWorkspaceArchiveIntent(intent);
   }
 }
 
diff --git a/packages/app/test-stubs/lucide-react-native.ts b/packages/app/test-stubs/lucide-react-native.ts
index a85976e1bf..1cff249d47 100644
--- a/packages/app/test-stubs/lucide-react-native.ts
+++ b/packages/app/test-stubs/lucide-react-native.ts
@@ -11,6 +11,7 @@ const StubIcon: LucideIcon = () => null;
 export const Activity = StubIcon;
 export const AlertTriangle = StubIcon;
 export const Archive = StubIcon;
+export const ArrowDown = StubIcon;
 export const ArrowDownUp = StubIcon;
 export const ArrowLeft = StubIcon;
 export const ArrowLeftToLine = StubIcon;
@@ -116,3 +117,16 @@ export const Maximize2 = StubIcon;
 export const Workflow = StubIcon;
 export const ZoomIn = StubIcon;
 export const ZoomOut = StubIcon;
+export const ListTodo = StubIcon;
+export const Shield = StubIcon;
+export const ShieldEllipsis = StubIcon;
+export const ShieldPlus = StubIcon;
+export const Zap = StubIcon;
+export const CheckSquare = StubIcon;
+export const Circle = StubIcon;
+export const FileSymlink = StubIcon;
+export const MessageSquareCode = StubIcon;
+export const MicVocal = StubIcon;
+export const Scissors = StubIcon;
+export const Sparkles = StubIcon;
+export const TriangleAlertIcon = StubIcon;
diff --git a/packages/app/test-stubs/react-native-unistyles.ts b/packages/app/test-stubs/react-native-unistyles.ts
index adc8af93bf..04f61bc77e 100644
--- a/packages/app/test-stubs/react-native-unistyles.ts
+++ b/packages/app/test-stubs/react-native-unistyles.ts
@@ -1,4 +1,5 @@
 import { lightHighlightColors } from "@getpaseo/highlight";
+import { lightTheme } from "../src/styles/theme";
 
 const testTheme = {
   colorScheme: "light",
@@ -26,12 +27,15 @@ const testTheme = {
     surface1: "#fafafa",
     surface2: "#f4f4f5",
     surface3: "#e4e4e7",
+    surfaceSidebar: lightTheme.colors.surfaceSidebar,
     border: "#e4e4e7",
     borderAccent: "#a1a1aa",
     palette: {
       amber: { 500: "#f59e0b" },
-      blue: { 300: "#93c5fd" },
-      green: { 500: "#22c55e" },
+      blue: { 300: "#93c5fd", 400: "#60a5fa" },
+      green: { 400: "#4ade80", 500: "#22c55e" },
+      yellow: { 400: "#facc15" },
+      zinc: { 600: "#52525b" },
       red: { 300: "#fca5a5" },
       white: "#ffffff",
     },
@@ -88,9 +92,54 @@ function isStyleFactory<T>(styles: T | StyleFactory<T>): styles is StyleFactory<
   return typeof styles === "function";
 }
 
+// The app's breakpoints (src/styles/unistyles.ts), widest first.
+const BREAKPOINTS: [string, number][] = [
+  ["xl", 1200],
+  ["lg", 992],
+  ["md", 600],
+  ["sm", 576],
+  ["xs", 0],
+];
+const BREAKPOINT_NAMES = new Set(BREAKPOINTS.map(([name]) => name));
+
+function isBreakpointValue(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => BREAKPOINT_NAMES.has(key));
+}
+
+/** Picks a breakpoint value for the window's width, the way Unistyles does at runtime. */
+function resolveBreakpointValue(value: Record<string, unknown>): unknown {
+  const width = typeof window === "undefined" ? 0 : window.innerWidth;
+  for (const [name, minWidth] of BREAKPOINTS) {
+    if (width >= minWidth && name in value) return value[name];
+  }
+  return undefined;
+}
+
+function resolveStyle(style: unknown): unknown {
+  if (typeof style === "function") {
+    return (...args: unknown[]) => resolveStyle(style(...args));
+  }
+  if (typeof style !== "object" || style === null || Array.isArray(style)) return style;
+  return Object.fromEntries(
+    Object.entries(style).map(([key, value]) => [
+      key,
+      isBreakpointValue(value) ? resolveBreakpointValue(value) : value,
+    ]),
+  );
+}
+
+function resolveStyles<T>(styles: T): T {
+  if (typeof styles !== "object" || styles === null) return styles;
+  return Object.fromEntries(
+    Object.entries(styles).map(([name, style]) => [name, resolveStyle(style)]),
+  ) as T;
+}
+
 export const StyleSheet = {
   create: <T>(styles: T | StyleFactory<T>): T =>
-    isStyleFactory(styles) ? styles(testTheme) : styles,
+    resolveStyles(isStyleFactory(styles) ? styles(testTheme) : styles),
 };
 
 export const withUnistyles = <T>(Component: T): T => Component;
diff --git a/packages/app/test-stubs/react-native.mjs b/packages/app/test-stubs/react-native.mjs
new file mode 100644
index 0000000000..9c72575d62
--- /dev/null
+++ b/packages/app/test-stubs/react-native.mjs
@@ -0,0 +1,14 @@
+// react-native-web has no ToastAndroid. The toast host imports it by name for its Android
+// branch; Metro and Node tolerate the missing binding, but browser tests load native ESM,
+// which rejects the import and fails every module that reaches the toast context.
+export * from "react-native-web/dist/index.js";
+
+export const ToastAndroid = {
+  SHORT: 0,
+  LONG: 1,
+  TOP: 0,
+  BOTTOM: 1,
+  CENTER: 2,
+  show() {},
+  showWithGravity() {},
+};
diff --git a/packages/app/vitest.config.ts b/packages/app/vitest.config.ts
index ba4c0fc979..c13780d6b6 100644
--- a/packages/app/vitest.config.ts
+++ b/packages/app/vitest.config.ts
@@ -36,11 +36,15 @@ export default defineConfig({
       },
     },
     {
-      name: "compile-usage-components",
+      name: "compile-react-components",
       enforce: "pre",
       transform(source, id) {
-        // These labels must react to time and language in the compiled app too.
-        if (!id.includes("/src/usage/") || !id.endsWith(".tsx") || id.includes(".test.")) return;
+        // Exercise compiler-sensitive labels, overlay lifetime and timeline row revisions in the same
+        // form as Expo.
+        const usageComponent = id.includes("/src/usage/") && id.endsWith(".tsx");
+        const overlayLayer = id.endsWith("/src/lib/overlay-root.ts");
+        const streamRow = id.endsWith("/src/agent-stream/stream-row.tsx");
+        if ((!usageComponent && !overlayLayer && !streamRow) || id.includes(".test.")) return;
         const result = transformSync(source, {
           filename: id,
           babelrc: false,
@@ -93,6 +97,17 @@ export default defineConfig({
       },
       {
         extends: true,
+        resolve: {
+          alias: [
+            // The app renders LegendList on native only, from the patched native build. Browser
+            // tests render that build too, instead of the package's separate web build. Unit tests
+            // load it outside Vite, where its react-native import would miss the web alias.
+            {
+              find: /^@legendapp\/list\/react-native$/,
+              replacement: path.resolve(rootNodeModules, "@legendapp/list/react-native.mjs"),
+            },
+          ],
+        },
         test: {
           name: "browser",
           fileParallelism: false,
@@ -163,6 +178,8 @@ export default defineConfig({
       "expo-router/react-navigation",
       "@testing-library/react",
       "@tanstack/react-query",
+      "@tanstack/react-virtual",
+      "@legendapp/list/react-native",
       "react-i18next",
       "i18next",
       "@marijn/find-cluster-break",
@@ -236,12 +253,20 @@ export default defineConfig({
         find: /^react-native\/Libraries\/Renderer\/shims\/ReactFabric$/,
         replacement: path.resolve(__dirname, "test-stubs/react-native-fabric-shim.ts"),
       },
-      // Point to the ESM build so Vite can transform its imports and apply the
+      // The CJS entry requires the real react-native, whose Flow sources do not parse.
+      {
+        find: /^@floating-ui\/react-native$/,
+        replacement: path.resolve(
+          rootNodeModules,
+          "@floating-ui/react-native/dist/floating-ui.react-native.esm.js",
+        ),
+      },
+      // Point to react-native-web's ESM build so Vite can transform its imports and apply the
       // react alias below (the CJS build uses require('react') which bypasses
-      // Vite alias resolution).
+      // Vite alias resolution). The stub re-exports it and adds what web lacks.
       {
         find: "react-native",
-        replacement: path.resolve(rootNodeModules, "react-native-web/dist/index.js"),
+        replacement: path.resolve(__dirname, "test-stubs/react-native.mjs"),
       },
       { find: "react", replacement: resolvePackageEntry("react") },
       {
diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/cli/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 45113dd1bc..d6683fcbdb 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo CLI - control your AI coding agents from the command line",
+  "license": "Apache-2.0",
   "bin": {
     "paseo": "bin/paseo"
   },
@@ -28,9 +29,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.14.0",
-    "@getpaseo/protocol": "0.14.0",
-    "@getpaseo/server": "0.14.0",
+    "@getpaseo/client": "0.15.4",
+    "@getpaseo/protocol": "0.15.4",
+    "@getpaseo/server": "0.15.4",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",
diff --git a/packages/cli/src/commands/agent/logs-json.test.ts b/packages/cli/src/commands/agent/logs-json.test.ts
new file mode 100644
index 0000000000..bbb69f9bd7
--- /dev/null
+++ b/packages/cli/src/commands/agent/logs-json.test.ts
@@ -0,0 +1,50 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { resolve } from "node:path";
+import { connectToDaemon } from "../../utils/client.js";
+import { runPaseoCli, startTestDaemon } from "../../../tests/helpers/test-daemon.js";
+
+describe("paseo logs JSON output", () => {
+  let daemon: Awaited<ReturnType<typeof startTestDaemon>>;
+  let agentId: string;
+  let host: string;
+
+  beforeAll(async () => {
+    await mkdir(".artifacts", { recursive: true });
+    daemon = await startTestDaemon({
+      paseoHome: await mkdtemp(resolve(".artifacts/logs-json-home-")),
+      workDir: await mkdtemp(resolve(".artifacts/logs-json-work-")),
+    });
+    host = `127.0.0.1:${daemon.port}`;
+    const client = await connectToDaemon({ target: { kind: "endpoint", host } });
+    try {
+      // Creating an idle agent needs no inference or external provider connection.
+      const agent = await client.createAgent({
+        provider: "claude",
+        cwd: daemon.workDir,
+        title: "JSON logs",
+      });
+      agentId = agent.id;
+    } finally {
+      await client.close();
+    }
+  }, 60_000);
+
+  afterAll(async () => {
+    await daemon?.stop();
+  });
+
+  it.each([
+    { label: "top-level --json", args: ["logs", "--json"] },
+    { label: "agent logs --json", args: ["agent", "logs", "--json"] },
+    { label: "--format json alias", args: ["logs", "--format", "json"] },
+  ])(
+    "prints JSON through $label",
+    async ({ args }) => {
+      const result = await runPaseoCli(daemon, [...args, agentId, "--host", host]);
+      expect(result.exitCode, result.stderr).toBe(0);
+      expect(JSON.parse(result.stdout)).toEqual({ agentId, items: [] });
+    },
+    30_000,
+  );
+});
diff --git a/packages/cli/src/commands/agent/logs.test.ts b/packages/cli/src/commands/agent/logs.test.ts
index e551aa3791..afbf97acb6 100644
--- a/packages/cli/src/commands/agent/logs.test.ts
+++ b/packages/cli/src/commands/agent/logs.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 import type { AgentTimelineItem } from "@getpaseo/protocol/agent-types";
-import { createFollowTranscriptWriter, formatAgentActivityTranscript } from "./logs.js";
+import {
+  createFollowJsonWriter,
+  createFollowTranscriptWriter,
+  formatAgentActivityTranscript,
+} from "./logs.js";
 
 function collect(items: readonly AgentTimelineItem[], turnId?: string): string {
   let output = "";
@@ -149,3 +153,31 @@ describe("createFollowTranscriptWriter", () => {
     expect(output).toBe("# Title\n\nBody\n");
   });
 });
+
+describe("createFollowJsonWriter", () => {
+  it("writes one JSON item per line and honours the filter", () => {
+    let output = "";
+    const writer = createFollowJsonWriter("tools", (chunk) => {
+      output += chunk;
+    });
+    const toolCall = {
+      type: "tool_call",
+      callId: "call_1",
+      name: "shell",
+      status: "completed",
+      detail: { type: "unknown", input: null, output: null },
+      error: null,
+    } as AgentTimelineItem;
+
+    writer.push({ type: "assistant_message", text: "Running it.", messageId: "msg_1" });
+    writer.push(toolCall);
+    writer.end();
+
+    expect(
+      output
+        .trimEnd()
+        .split("\n")
+        .map((line) => JSON.parse(line)),
+    ).toEqual([toolCall]);
+  });
+});
diff --git a/packages/cli/src/commands/agent/logs.ts b/packages/cli/src/commands/agent/logs.ts
index 27b5cc0ecf..ed821049e4 100644
--- a/packages/cli/src/commands/agent/logs.ts
+++ b/packages/cli/src/commands/agent/logs.ts
@@ -70,6 +70,35 @@ export function formatAgentActivityTranscript(
   );
 }
 
+/**
+ * Picks the items `--tail` keeps, the same way the transcript does: the last n
+ * timeline items, before any of them are dropped from the curated view.
+ */
+function selectTailItems(
+  timelineItems: AgentTimelineItem[],
+  tailCount?: number,
+): AgentTimelineItem[] {
+  if (tailCount === undefined) {
+    return timelineItems;
+  }
+  if (tailCount === 0) {
+    return [];
+  }
+  return timelineItems.slice(-tailCount);
+}
+
+function formatAgentLogsJson(
+  agentId: string,
+  timelineItems: AgentTimelineItem[],
+  tailCount?: number,
+): string {
+  return JSON.stringify({ agentId, items: selectTailItems(timelineItems, tailCount) }, null, 2);
+}
+
+function usesJsonOutput(options: AgentLogsOptions): boolean {
+  return options.json === true || options.format?.trim().toLowerCase() === "json";
+}
+
 type StreamingTextType = "assistant_message" | "reasoning";
 
 const THOUGHT_PREFIX = "[Thought] ";
@@ -198,6 +227,21 @@ export function createFollowTranscriptWriter(
   };
 }
 
+/** Follow mode with `--json`: one JSON timeline item per line (NDJSON). */
+export function createFollowJsonWriter(
+  filter?: string,
+  write: (chunk: string) => void = (chunk) => void process.stdout.write(chunk),
+): FollowTranscriptWriter {
+  return {
+    push(item) {
+      if (matchesFilter(item, filter)) {
+        write(`${JSON.stringify(item)}\n`);
+      }
+    },
+    end() {},
+  };
+}
+
 function parseTailCount(raw: string | undefined): number | undefined {
   if (raw === undefined) return undefined;
   const parsed = Number.parseInt(raw, 10);
@@ -306,6 +350,11 @@ export async function runLogsCommand(
 
     await client.close();
 
+    if (usesJsonOutput(options)) {
+      console.log(formatAgentLogsJson(resolvedId, timelineItems, tailCount));
+      return;
+    }
+
     // Use curateAgentActivity to format the transcript
     if (tailCount === 0) {
       return;
@@ -331,85 +380,108 @@ async function runFollowMode({
   options,
   sinceTimestampMs,
 }: FollowModeInput): Promise<void> {
-  const DEFAULT_FOLLOW_TAIL = 10;
-  const tailCount = parseTailCount(options.tail) ?? DEFAULT_FOLLOW_TAIL;
-
-  // First, get existing timeline.
-  let existingItems: AgentTimelineItem[] = [];
+  // Observe shutdown before history writes can encounter a closed reader.
+  // Keep an early stop resolved while subscription setup is in flight.
+  const stopController = new AbortController();
+  const stopped = waitForStop(stopController.signal);
+  let unsubscribe: (() => void) | undefined;
+  const json = usesJsonOutput(options);
+  const writer = json
+    ? createFollowJsonWriter(options.filter)
+    : createFollowTranscriptWriter(undefined, options.filter);
   try {
-    existingItems = await fetchAgentTimelineItems(client, agentId, {
-      timeoutMs: LIVE_HISTORY_FETCH_TIMEOUT_MS,
-      sinceTimestampMs,
-    });
-  } catch (error) {
-    console.warn("Warning: failed to fetch existing timeline", error);
-  }
+    const DEFAULT_FOLLOW_TAIL = 10;
+    const tailCount = parseTailCount(options.tail) ?? DEFAULT_FOLLOW_TAIL;
 
-  // Apply filter to existing items
-  if (options.filter) {
-    existingItems = existingItems.filter((item) => matchesFilter(item, options.filter));
-  }
-
-  // Print existing transcript (tail-like behavior)
-  if (tailCount > 0) {
-    const existingTranscript = formatAgentActivityTranscript(existingItems, tailCount);
-    if (existingTranscript !== NO_ACTIVITY_MESSAGE) {
-      console.log(existingTranscript);
+    // First, get existing timeline.
+    let existingItems: AgentTimelineItem[] = [];
+    try {
+      const history = await Promise.race([
+        fetchAgentTimelineItems(client, agentId, {
+          timeoutMs: LIVE_HISTORY_FETCH_TIMEOUT_MS,
+          sinceTimestampMs,
+        }),
+        stopped,
+      ]);
+      if (!history) return;
+      existingItems = history;
+    } catch (error) {
+      console.warn("Warning: failed to fetch existing timeline", error);
     }
-  }
-
-  // Subscribe to new events
-  const tailLabel =
-    tailCount === 0 ? "no history" : `last ${tailCount} entr${tailCount === 1 ? "y" : "ies"}`;
-
-  const writer = createFollowTranscriptWriter(undefined, options.filter);
-
-  const unsubscribe = client.subscribeAgentTimeline(agentId, (message) => {
-    if (message.type === "agent.timeline.replacement") {
-      writer.end();
-      console.log("\n[Timeline replaced; earlier output is no longer current]");
-      return;
-    }
-    if (message.type === "agent.timeline.rewind") {
-      writer.end();
-      console.log(
-        "\n[Conversation rewound; output since the rewound message is no longer current]",
-      );
-      return;
+    // Apply filter to existing items
+    if (options.filter) {
+      existingItems = existingItems.filter((item) => matchesFilter(item, options.filter));
     }
 
-    if (message.type === "agent.timeline.error") {
-      writer.end();
-      console.error(`Timeline observation stopped: ${message.payload.error}`);
-      return;
+    // Print existing transcript (tail-like behavior)
+    if (json) {
+      for (const item of selectTailItems(existingItems, tailCount)) {
+        console.log(JSON.stringify(item));
+      }
+    } else if (tailCount > 0) {
+      const existingTranscript = formatAgentActivityTranscript(existingItems, tailCount);
+      if (existingTranscript !== NO_ACTIVITY_MESSAGE) {
+        console.log(existingTranscript);
+      }
     }
-    if (message.type === "agent.timeline.subscription_restored") {
-      writer.end();
-      console.log("\n[Reconnected; live output resumed. Events may have been missed.]");
-      return;
-    }
-    if (message.payload.event.type === "timeline") {
-      const matchesSince =
-        sinceTimestampMs === undefined || Date.parse(message.payload.timestamp) >= sinceTimestampMs;
-      if (!matchesSince) {
+
+    // Subscribe to new events
+    const tailLabel =
+      tailCount === 0 ? "no history" : `last ${tailCount} entr${tailCount === 1 ? "y" : "ies"}`;
+
+    // Keep stdout parseable in JSON mode: one timeline item per line, notices on stderr.
+    const notice = json ? console.error : console.log;
+
+    const subscription = client.subscribeAgentTimeline(agentId, (message) => {
+      if (message.type === "agent.timeline.replacement") {
+        writer.end();
+        notice("\n[Timeline replaced; earlier output is no longer current]");
+        return;
+      }
+      if (message.type === "agent.timeline.rewind") {
+        writer.end();
+        notice("\n[Conversation rewound; output since the rewound message is no longer current]");
         return;
       }
-      const item = message.payload.event.item;
-      writer.push(item, message.payload.event.turnId);
-    } else if (
-      message.payload.event.type === "turn_completed" ||
-      message.payload.event.type === "turn_failed" ||
-      message.payload.event.type === "turn_canceled"
-    ) {
-      writer.end();
-    }
-  });
 
-  await unsubscribe.ready;
-  console.log(`\n--- Following logs (${tailLabel}; Ctrl+C to stop) ---\n`);
+      if (message.type === "agent.timeline.error") {
+        writer.end();
+        console.error(`Timeline observation stopped: ${message.payload.error}`);
+        return;
+      }
+      if (message.type === "agent.timeline.subscription_restored") {
+        writer.end();
+        notice("\n[Reconnected; live output resumed. Events may have been missed.]");
+        return;
+      }
+      if (message.payload.event.type === "timeline") {
+        const matchesSince =
+          sinceTimestampMs === undefined ||
+          Date.parse(message.payload.timestamp) >= sinceTimestampMs;
+        if (!matchesSince) {
+          return;
+        }
+        const item = message.payload.event.item;
+        writer.push(item, message.payload.event.turnId);
+      } else if (
+        message.payload.event.type === "turn_completed" ||
+        message.payload.event.type === "turn_failed" ||
+        message.payload.event.type === "turn_canceled"
+      ) {
+        writer.end();
+      }
+    });
 
-  await waitForStop();
-  writer.end();
-  unsubscribe();
-  await client.close();
+    unsubscribe = subscription;
+    const ready = await Promise.race([subscription.ready.then(() => true), stopped]);
+    if (!ready) return;
+    notice(`\n--- Following logs (${tailLabel}; Ctrl+C to stop) ---\n`);
+
+    await stopped;
+  } finally {
+    stopController.abort();
+    writer.end();
+    unsubscribe?.();
+    await client.close();
+  }
 }
diff --git a/packages/cli/src/commands/agent/ls.test.ts b/packages/cli/src/commands/agent/ls.test.ts
index 76b1787ce3..82d6c09a61 100644
--- a/packages/cli/src/commands/agent/ls.test.ts
+++ b/packages/cli/src/commands/agent/ls.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
+import { render } from "../../output/index.js";
 import { buildAgentLsFetchOptions, listAgents } from "./ls.js";
 
 const daemonTarget = { kind: "endpoint" as const, host: "example.test:12345" };
@@ -130,4 +131,26 @@ describe("runLsCommand", () => {
 
     expect(result.data.map((item) => item.name)).toEqual(["agent 3", "agent 2", "agent 1"]);
   });
+
+  it("marks background agents in a BACKGROUND column only for inclusive listings", async () => {
+    const client = createPagingClient();
+    const fetchAgents: typeof client.fetchAgents = async (options) => {
+      const page = await client.fetchAgents(options);
+      return {
+        ...page,
+        entries: page.entries.map(({ agent }) => ({
+          agent: agent.title === "agent 2" ? { ...agent, background: true } : agent,
+        })),
+      };
+    };
+    const connect = async () => ({ ...client, fetchAgents });
+
+    const inclusive = await listAgents({ daemonTarget, all: true, global: true }, connect);
+    const rows = render(inclusive, { noColor: true }).split("\n");
+    expect(rows[0]).toMatch(/BACKGROUND\s*$/);
+    expect(rows.slice(1).map((row) => row.trim().split(/\s+/).at(-1))).toEqual(["-", "yes", "-"]);
+
+    const ordinary = await listAgents({ daemonTarget, global: true }, connect);
+    expect(render(ordinary, { noColor: true })).not.toContain("BACKGROUND");
+  });
 });
diff --git a/packages/cli/src/commands/agent/ls.ts b/packages/cli/src/commands/agent/ls.ts
index e0b6358a38..d60ad0ce97 100644
--- a/packages/cli/src/commands/agent/ls.ts
+++ b/packages/cli/src/commands/agent/ls.ts
@@ -15,7 +15,7 @@ export function addLsOptions(cmd: Command): Command {
     .description("List agents. By default excludes archived agents.")
     .option("-a, --all", "Include archived and background agents")
     .option("-g, --global", "List agents across all directories")
-    .option("--background", "Include background workspace agents")
+    .option("--background", "Include background agents and agents in background workspaces")
     .option(
       "--label <key=value>",
       "Filter by label (can be used multiple times)",
@@ -35,6 +35,7 @@ export interface AgentListItem {
   status: string;
   cwd: string;
   created: string;
+  background: boolean;
 }
 
 /** Helper to get relative time string */
@@ -89,6 +90,15 @@ export const agentLsSchema: OutputSchema<AgentListItem> = {
   ],
 };
 
+/** Inclusive listings mark background agents so they read apart from visible ones. */
+const agentLsInclusiveSchema: OutputSchema<AgentListItem> = {
+  ...agentLsSchema,
+  columns: [
+    ...agentLsSchema.columns,
+    { header: "BACKGROUND", field: (item) => (item.background ? "yes" : "-"), width: 10 },
+  ],
+};
+
 /** Transform agent snapshot to AgentListItem */
 function toListItem(agent: AgentSnapshotPayload): AgentListItem {
   const model = normalizeModelId(agent.runtimeInfo?.model) ?? normalizeModelId(agent.model);
@@ -101,6 +111,7 @@ function toListItem(agent: AgentSnapshotPayload): AgentListItem {
     status: agent.status,
     cwd: shortenPath(agent.cwd),
     created: relativeTime(agent.createdAt),
+    background: agent.background === true,
   };
 }
 
@@ -259,7 +270,7 @@ export async function listAgents(
     return {
       type: "list",
       data: items,
-      schema: agentLsSchema,
+      schema: options.all || options.background ? agentLsInclusiveSchema : agentLsSchema,
     };
   } catch (err) {
     await client.close().catch(() => {});
diff --git a/packages/cli/src/utils/wait-for-stop.ts b/packages/cli/src/utils/wait-for-stop.ts
index 8430c39726..7988d8f436 100644
--- a/packages/cli/src/utils/wait-for-stop.ts
+++ b/packages/cli/src/utils/wait-for-stop.ts
@@ -3,9 +3,10 @@
 // their output closes its end, as `| head` does. A closed reader shows up as
 // EPIPE on the next write to stdout, so the command stops at its next line of
 // output.
-export function waitForStop(): Promise<void> {
+export function waitForStop(signal?: AbortSignal): Promise<void> {
   return new Promise((resolve) => {
     const stop = () => {
+      signal?.removeEventListener("abort", stop);
       process.off("SIGINT", stop);
       process.off("SIGTERM", stop);
       process.stdout.off("error", stopOnClosedStdout);
@@ -20,5 +21,7 @@ export function waitForStop(): Promise<void> {
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
     process.stdout.on("error", stopOnClosedStdout);
+    signal?.addEventListener("abort", stop, { once: true });
+    if (signal?.aborted) stop();
   });
 }
diff --git a/packages/cli/tests/15-provider.test.ts b/packages/cli/tests/15-provider.test.ts
index 3a4f33031c..5037a65ad9 100644
--- a/packages/cli/tests/15-provider.test.ts
+++ b/packages/cli/tests/15-provider.test.ts
@@ -62,10 +62,15 @@ const EXPECTED_CLAUDE_MODELS = [
     model: "Opus 5",
     descriptionFragment: "Previous release",
   },
+  {
+    id: "claude-fable-5-2",
+    model: "Fable 5.2",
+    descriptionFragment: "Most powerful",
+  },
   {
     id: "claude-fable-5-1",
     model: "Fable 5.1",
-    descriptionFragment: "Most powerful",
+    descriptionFragment: "Previous release",
   },
   {
     id: "claude-fable-5",
@@ -199,11 +204,10 @@ function assertClaudeModels(data: ProviderModel[]): void {
     );
   }
 
-  const fable51Index = data.findIndex((model) => model.id === "claude-fable-5-1");
-  const fable5Index = data.findIndex((model) => model.id === "claude-fable-5");
-  assert.strictEqual(
-    fable5Index,
-    fable51Index + 1,
+  const fable52Index = data.findIndex((model) => model.id === "claude-fable-5-2");
+  assert.deepStrictEqual(
+    data.slice(fable52Index, fable52Index + 3).map((model) => model.id),
+    ["claude-fable-5-2", "claude-fable-5-1", "claude-fable-5"],
     "Fable models should stay adjacent and newest-first",
   );
   assert(
diff --git a/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts b/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts
index 9090456406..cb272cf54a 100644
--- a/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts
+++ b/packages/cli/tests/46-daemon-terminal-worker-upgrade.test.ts
@@ -49,7 +49,7 @@ const paseoHome = join(root, "home");
 const cliHome = join(root, "os-home");
 const workDir = join(root, "work");
 for (const dir of [paseoHome, cliHome, workDir]) mkdirSync(dir, { recursive: true });
-const currentProtocolVersion = 5;
+const currentProtocolVersion = 6;
 const zsh = ["/bin/zsh", "/usr/bin/zsh"].find((candidate) => existsSync(candidate)) ?? null;
 
 interface Installation {
@@ -456,8 +456,8 @@ try {
   });
   console.log(`Competing listener owns released port ${releasedPort}`);
 
-  // There is no supported previous wire at protocol 5. Future previous-version classification
-  // is covered by terminal-worker-protocol.test.ts; do not simulate an unreleased drain adapter.
+  // Protocols 0–4 have no draining adapter. Protocol 5 is now the supported previous wire;
+  // its classification is covered by terminal-worker-protocol.test.ts.
   for (const protocolVersion of [0, 1, 2, 3, 4]) {
     console.log(`Test 4: obsolete protocol ${protocolVersion} is closed before serving terminals`);
     const obsolete = await leaveWorkerWithProtocol(
diff --git a/packages/client/LICENSE b/packages/client/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/client/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/client/package.json b/packages/client/package.json
index 6e10c76089..ff75f79cfb 100644
--- a/packages/client/package.json
+++ b/packages/client/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo client SDK package",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -44,11 +45,12 @@
     "prepack": "npm run build:clean",
     "typecheck": "tsgo --noEmit",
     "typecheck:examples": "tsgo -p tsconfig.examples.json --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "measure:diff-materialization": "tsx scripts/measure-diff-materialization.ts"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.14.0",
-    "@getpaseo/relay": "0.14.0",
+    "@getpaseo/protocol": "0.15.4",
+    "@getpaseo/relay": "0.15.4",
     "ws": "^8.20.0",
     "zod": "^4.4.3"
   },
diff --git a/packages/client/scripts/measure-diff-materialization.ts b/packages/client/scripts/measure-diff-materialization.ts
new file mode 100644
index 0000000000..54f7b1f53a
--- /dev/null
+++ b/packages/client/scripts/measure-diff-materialization.ts
@@ -0,0 +1,38 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { decodeDiffFrame } from "@getpaseo/protocol/binary-frames/index";
+import { validateWSOutboundMessage } from "@getpaseo/protocol/validation/ws-outbound";
+import { DiffStream } from "../src/diff/stream.js";
+const artifacts = resolve(import.meta.dirname, "../../../.artifacts/diff-subscription");
+const results = [];
+for (const count of [1, 30]) {
+  const corpus = JSON.parse(await readFile(resolve(artifacts, `corpus-${count}.json`), "utf8")) as {
+    frames: string[];
+    legacy: string;
+  };
+  const frames = corpus.frames.map((value) => Buffer.from(value, "base64"));
+  const binary: number[] = [];
+  const json: number[] = [];
+  for (let iteration = 0; iteration < 15; iteration++) {
+    let files = 0;
+    const stream = new DiffStream((state) => {
+      if (state.phase === "ready") files = state.files.length;
+    });
+    let start = performance.now();
+    for (const frame of frames) stream.receive(decodeDiffFrame(frame));
+    binary.push(performance.now() - start);
+    start = performance.now();
+    validateWSOutboundMessage(JSON.parse(corpus.legacy));
+    json.push(performance.now() - start);
+    if (!files) throw new Error("No materialized files");
+  }
+  const median = (values: number[]) =>
+    values.slice(3).sort((a, b) => a - b)[Math.floor((values.length - 3) / 2)];
+  const result = { count, materializationMs: median(binary), jsonParseValidationMs: median(json) };
+  results.push(result);
+  console.log(JSON.stringify(result));
+}
+await writeFile(resolve(artifacts, "client-metrics.json"), JSON.stringify(results, null, 2));
+if (results.some((result) => result.materializationMs > result.jsonParseValidationMs))
+  process.exitCode = 1;
diff --git a/packages/client/src/compat/legacy-provider-options.ts b/packages/client/src/compat/legacy-provider-options.ts
new file mode 100644
index 0000000000..083232253c
--- /dev/null
+++ b/packages/client/src/compat/legacy-provider-options.ts
@@ -0,0 +1,252 @@
+import { controlsFromFeatures, optionsFromFeatures } from "@getpaseo/protocol/option-controls";
+import type { AgentOptionControl } from "@getpaseo/protocol/agent-types";
+import type {
+  AgentConfigApply,
+  AgentProfile,
+  AgentSnapshotPayload,
+  MutableDaemonConfig,
+  ListProviderFeaturesResponseMessage,
+  ProviderControlsListResponseMessage,
+  ServerInfoStatusPayload,
+  SessionInboundMessage,
+  SessionOutboundMessage,
+} from "@getpaseo/protocol/messages";
+
+/**
+ * COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01 once daemon floor >=
+ * v0.15.0.
+ *
+ * A daemon without `server_info.features.providerOptionControls` sends `features` (a control with
+ * its value attached) and takes composer values as `featureValues`. This is the one place that
+ * turns that into the shape everyone else uses: `controls` over `options`, written through
+ * `providerOptions`.
+ */
+export function usesLegacyProviderOptions(info: ServerInfoStatusPayload): boolean {
+  return info.features?.providerOptionControls !== true;
+}
+
+export class LegacyProviderOptions {
+  /** Gives agent snapshots `controls` and `options`, built from their `features`. */
+  normalize(message: SessionOutboundMessage): SessionOutboundMessage {
+    switch (message.type) {
+      case "agent_update":
+        if (message.payload.kind !== "upsert") return message;
+        return {
+          ...message,
+          payload: { ...message.payload, agent: this.snapshot(message.payload.agent) },
+        };
+      case "agent_status":
+        return {
+          ...message,
+          payload: { ...message.payload, info: this.snapshot(message.payload.info) },
+        };
+      case "fetch_agents_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            entries: message.payload.entries.map((entry) => ({
+              ...entry,
+              agent: this.snapshot(entry.agent),
+            })),
+          },
+        };
+      case "fetch_agent_response":
+      case "agent.create.response":
+      case "cancel_agent_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            agent: message.payload.agent && this.snapshot(message.payload.agent),
+          },
+        } as SessionOutboundMessage;
+      case "workspace.create.response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            ...(message.payload.agent ? { agent: this.snapshot(message.payload.agent) } : {}),
+          },
+        };
+      case "wait_for_finish_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            final: message.payload.final && this.snapshot(message.payload.final),
+          },
+        };
+      case "get_daemon_config_response":
+      case "set_daemon_config_response":
+        return {
+          ...message,
+          payload: { ...message.payload, config: this.daemonConfig(message.payload.config) },
+        };
+      case "fetch_agent_timeline_response":
+        return {
+          ...message,
+          payload: {
+            ...message.payload,
+            agent: message.payload.agent && this.snapshot(message.payload.agent),
+          },
+        };
+      case "status":
+        return this.status(message);
+      default:
+        return message;
+    }
+  }
+
+  private status(
+    message: Extract<SessionOutboundMessage, { type: "status" }>,
+  ): SessionOutboundMessage {
+    const { payload } = message;
+    if (payload.status === "agent_created" || payload.status === "agent_resumed") {
+      const { agent } = payload as unknown as { agent: AgentSnapshotPayload };
+      return { ...message, payload: { ...payload, agent: this.snapshot(agent) } };
+    }
+    if (payload.status === "daemon_config_changed") {
+      const config = payload.config as MutableDaemonConfig;
+      return { ...message, payload: { ...payload, config: this.daemonConfig(config) } };
+    }
+    return message;
+  }
+
+  /**
+   * Splits a create's options for a legacy daemon: the ids it lists as features for that very
+   * config go out as `featureValues`, which is where it reads them, and the rest stay
+   * `providerOptions`. Which options are features depends on the model, mode and thinking level
+   * as well as the provider, so the ids come from a listing for this config, never from memory.
+   */
+  routeCreateConfig<
+    T extends {
+      providerOptions?: Record<string, unknown>;
+      featureValues?: Record<string, unknown>;
+    },
+  >(config: T, featureIds: ReadonlySet<string>): T {
+    if (!config.providerOptions) return config;
+    const featureValues: Record<string, unknown> = {};
+    const providerOptions: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(config.providerOptions)) {
+      (featureIds.has(key) ? featureValues : providerOptions)[key] = value;
+    }
+    const { providerOptions: _options, ...rest } = config;
+    return {
+      ...(rest as T),
+      ...(Object.keys(providerOptions).length > 0 ? { providerOptions } : {}),
+      ...(Object.keys(featureValues).length > 0
+        ? { featureValues: { ...config.featureValues, ...featureValues } }
+        : {}),
+    };
+  }
+
+  /** Sends options as `featureValues`, which is where a legacy daemon reads them. */
+  prepare(message: SessionInboundMessage): SessionInboundMessage {
+    switch (message.type) {
+      case "list_commands_request": {
+        if (!message.draftConfig?.providerOptions) return message;
+        const { providerOptions, ...draftConfig } = message.draftConfig;
+        return {
+          ...message,
+          draftConfig: {
+            ...draftConfig,
+            featureValues: { ...draftConfig.featureValues, ...providerOptions },
+          },
+        };
+      }
+      case "set_daemon_config_request":
+        if (!message.config.agentProfiles) return message;
+        return {
+          ...message,
+          config: {
+            ...message.config,
+            agentProfiles: message.config.agentProfiles.map(profileWithFeatureValues),
+          },
+        };
+      default:
+        return message;
+    }
+  }
+
+  /**
+   * An options patch as feature writes. `null` removes an option, which the old API cannot say:
+   * its setters take a value, and the Codex one rejects anything but a choice id. A toggle goes
+   * off and a choice goes to its default; an option with no control to say what its default is
+   * cannot be reset, and nothing is written.
+   */
+  featureWrites(
+    patch: Record<string, unknown>,
+    controls: readonly AgentOptionControl[],
+  ): [string, unknown][] {
+    return Object.entries(patch).map(([key, value]) => {
+      if (value !== null) return [key, value];
+      const control = controls.find((candidate) => candidate.key === key);
+      if (control?.type === "toggle") return [key, false];
+      if (control?.type === "select" && control.defaultValue !== undefined) {
+        return [key, control.defaultValue];
+      }
+      throw new Error(`Update the host to reset ${key}.`);
+    });
+  }
+
+  /** A config apply with its `options` as `featureValues`, the way a daemon without them takes it. */
+  featureValuesConfig(
+    config: AgentConfigApply,
+    controls: readonly AgentOptionControl[],
+  ): AgentConfigApply {
+    const { options, ...rest } = config;
+    if (!options) return config;
+    return {
+      ...rest,
+      featureValues: {
+        ...rest.featureValues,
+        ...Object.fromEntries(this.featureWrites(options, controls)),
+      },
+    };
+  }
+
+  /** The legacy answer to a controls listing, in the shape of the current response. */
+  controlsResponse(
+    legacy: ListProviderFeaturesResponseMessage["payload"],
+  ): ProviderControlsListResponseMessage["payload"] {
+    const { features, ...rest } = legacy;
+    return {
+      ...rest,
+      ...(features
+        ? { controls: controlsFromFeatures(features), options: optionsFromFeatures(features) }
+        : {}),
+    };
+  }
+
+  private daemonConfig(config: MutableDaemonConfig): MutableDaemonConfig {
+    if (!config.agentProfiles) return config;
+    return { ...config, agentProfiles: config.agentProfiles.map(profileWithOptions) };
+  }
+
+  private readonly snapshot = (agent: AgentSnapshotPayload): AgentSnapshotPayload => {
+    if (agent.controls || !agent.features) return agent;
+    return {
+      ...agent,
+      controls: controlsFromFeatures(agent.features),
+      options: optionsFromFeatures(agent.features),
+    };
+  };
+}
+
+/**
+ * A legacy daemon stores a profile's options under `featureValues`, and keeps an `options` field
+ * a newer daemon left on it. Both are read, and an explicit `options` key wins, as it does on the
+ * daemon (`foldFeatureValues`).
+ */
+function profileWithOptions(profile: AgentProfile): AgentProfile {
+  if (!profile.featureValues) return profile;
+  const { featureValues, ...rest } = profile;
+  return { ...rest, options: { ...featureValues, ...profile.options } };
+}
+
+function profileWithFeatureValues(profile: AgentProfile): AgentProfile {
+  if (!profile.options) return profile;
+  const { options, ...rest } = profile;
+  return { ...rest, featureValues: options };
+}
diff --git a/packages/client/src/connection.test.ts b/packages/client/src/connection.test.ts
index 9a197af068..01ef32b5e3 100644
--- a/packages/client/src/connection.test.ts
+++ b/packages/client/src/connection.test.ts
@@ -11,6 +11,7 @@ function connection(
     broadcasts?: boolean;
     browserHost?: { hostKind: string; supportedCommands: string[] };
     acknowledgeTimelineReads?: boolean;
+    timelineFreshnessCheck?: boolean;
   } = {},
 ) {
   const sent: Array<{
@@ -47,6 +48,7 @@ function connection(
                   workspaceMultiplicity: options.workspaceMultiplicity ?? true,
                   selectiveAgentTimeline: !options.broadcasts,
                   explicitEventSubscriptions: !options.broadcasts,
+                  timelineFreshnessCheck: options.timelineFreshnessCheck === true,
                 },
               },
             },
@@ -918,6 +920,29 @@ test("old attention stream events reach the current notification interface", asy
   }
 });
 
+test("timeline cursors reach only hosts that answer freshness", async () => {
+  const cursors = { agent: { epoch: "epoch-1", seq: 9 } };
+  const sentCursors = async (timelineFreshnessCheck: boolean) => {
+    const h = connection({ timelineFreshnessCheck });
+    try {
+      const connected = h.client.connect();
+      h.open();
+      await connected;
+      const observation = h.client.observeTimeline(["agent"], { cursors });
+      await observation.ready;
+      await observation.release();
+      return h.sent.find(
+        (frame) => frame.message?.type === "agent.timeline.set_subscription.request",
+      )?.message;
+    } finally {
+      await h.client.close();
+    }
+  };
+
+  expect(await sentCursors(true)).toMatchObject({ cursors });
+  expect(await sentCursors(false)).not.toHaveProperty("cursors");
+});
+
 test("broadcast-only hosts expose local timeline readiness without sending an unsupported RPC", async () => {
   const h = connection({ ownedSubscriptions: false, broadcasts: true });
   try {
diff --git a/packages/client/src/connection/index.ts b/packages/client/src/connection/index.ts
index 398526cac9..57ff94819f 100644
--- a/packages/client/src/connection/index.ts
+++ b/packages/client/src/connection/index.ts
@@ -145,6 +145,8 @@ export const DEFAULT_CLIENT_CAPABILITIES = {
   [CLIENT_CAPS.pluginTimelineItems]: true,
   [CLIENT_CAPS.workspaceSetupBlocked]: true,
   [CLIENT_CAPS.workspaceSetupObservation]: true,
+  [CLIENT_CAPS.pluginBinaryPayloads]: true,
+  [CLIENT_CAPS.backgroundAgents]: true,
   [CLIENT_CAPS.explicitEventSubscriptions]: true,
 } satisfies Record<Exclude<ClientCapability, typeof CLIENT_CAPS.browserHost>, true>;
 
diff --git a/packages/client/src/connection/legacy-workspaces.ts b/packages/client/src/connection/legacy-workspaces.ts
index 2cf90423b5..ce83f145a1 100644
--- a/packages/client/src/connection/legacy-workspaces.ts
+++ b/packages/client/src/connection/legacy-workspaces.ts
@@ -111,6 +111,7 @@ export class LegacyWorkspaces {
         pendingPermissionCount: agent.pendingPermissions.length,
         requiresAttention: agent.requiresAttention,
         attentionReason: agent.attentionReason,
+        backgroundWork: agent.backgroundWork,
       });
       const existing = workspaces.get(id);
       if (
diff --git a/packages/client/src/connection/owned.test.ts b/packages/client/src/connection/owned.test.ts
index eca52f1749..7e5c2e7202 100644
--- a/packages/client/src/connection/owned.test.ts
+++ b/packages/client/src/connection/owned.test.ts
@@ -83,6 +83,26 @@ test("cancellation before the ID waits for bootstrap and releases exactly that I
   expect(c.released).toEqual(["cancelled"]);
 });
 
+test("a release right after the host accepts still reports the subscription as accepted", async () => {
+  const c = connection();
+  const handle = c.observe();
+  c.requests[0]!("closing");
+  const released = handle.release();
+  await expect(handle.ready).resolves.toMatchObject({ subscriptionId: "closing" });
+  await released;
+  expect(c.released).toEqual(["closing"]);
+});
+
+test("a release before the host accepts rejects ready", async () => {
+  const c = connection();
+  const handle = c.observe();
+  const released = handle.release();
+  await expect(handle.ready).rejects.toThrow("Subscription released");
+  c.requests[0]!("late");
+  await released;
+  expect(c.released).toEqual(["late"]);
+});
+
 test("surviving handles use new remote IDs after reconnect and released handles stay gone", async () => {
   const c = connection();
   const a = c.observe();
diff --git a/packages/client/src/connection/owned.ts b/packages/client/src/connection/owned.ts
index 56bf6b98f0..1c6290be7d 100644
--- a/packages/client/src/connection/owned.ts
+++ b/packages/client/src/connection/owned.ts
@@ -5,6 +5,8 @@ export type SubscriptionSnapshot<T> = T & { subscriptionId: string };
 export interface SubscriptionObserver<T> {
   snapshot(snapshot: T): void;
   update(message: SessionOutboundMessage): void;
+  /** A binary frame the host addressed to this subscription; the payload is a view. */
+  binary?(payload: Uint8Array): void;
   error?(error: unknown): void;
 }
 
@@ -20,9 +22,12 @@ interface Registration {
   start(): void;
   disconnected(): void;
   receive(message: SessionOutboundMessage): void;
+  receiveBinary(payload: Uint8Array): void;
   release(): Promise<void>;
 }
 
+type Update = { message: SessionOutboundMessage } | { binary: Uint8Array };
+
 export interface OwnedSubscriptionsHost {
   release(subscriptionId: string): Promise<void>;
   failed(error: unknown): void;
@@ -50,7 +55,7 @@ export class OwnedSubscriptions {
     let teardown: Promise<void> | null = null;
     let disposed = false;
     let overflow = false;
-    const buffered: SessionOutboundMessage[] = [];
+    const buffered: Update[] = [];
     const observers = new Set<SubscriptionObserver<SubscriptionSnapshot<T>>>();
     let resolve!: (snapshot: SubscriptionSnapshot<T>) => void;
     let reject!: (error: unknown) => void;
@@ -60,12 +65,10 @@ export class OwnedSubscriptions {
     });
     void ready.catch(() => {});
 
-    const deliver = (
-      observer: SubscriptionObserver<SubscriptionSnapshot<T>>,
-      message?: SessionOutboundMessage,
-    ) => {
+    const deliver = (observer: SubscriptionObserver<SubscriptionSnapshot<T>>, update?: Update) => {
       try {
-        if (message) observer.update(message);
+        if (update && "binary" in update) observer.binary?.(update.binary);
+        else if (update) observer.update(update.message);
         else if (snapshot) observer.snapshot(snapshot);
       } catch (error) {
         this.host.failed(error);
@@ -78,6 +81,13 @@ export class OwnedSubscriptions {
       this.routes.delete(released);
       await this.host.release(released);
     };
+    const buffer = (update: Update) => {
+      if (buffered.length < MAX_BOOTSTRAP_UPDATES && !overflow) buffered.push(update);
+      else {
+        buffered.length = 0;
+        overflow = true;
+      }
+    };
     const registration: Registration = {
       start: () => {
         if (disposed || pending || id || !this.connected) return;
@@ -128,12 +138,14 @@ export class OwnedSubscriptions {
       },
       receive: (message) => {
         if (disposed || ("payload" in message && Object.is(message.payload, snapshot))) return;
-        if (buffered.length < MAX_BOOTSTRAP_UPDATES && !overflow) buffered.push(message);
-        else {
-          buffered.length = 0;
-          overflow = true;
-        }
-        for (const observer of observers) deliver(observer, message);
+        buffer({ message });
+        for (const observer of observers) deliver(observer, { message });
+      },
+      receiveBinary: (payload) => {
+        if (disposed) return;
+        // Bytes wait only for the first observer; retaining them after would hold every frame.
+        if (observers.size === 0) buffer({ binary: payload });
+        for (const observer of observers) deliver(observer, { binary: payload });
       },
       release: () => {
         if (teardown) return teardown;
@@ -142,7 +154,9 @@ export class OwnedSubscriptions {
         observers.clear();
         buffered.length = 0;
         if (id) this.routes.delete(id);
-        reject(new Error("Subscription released"));
+        // A host that already accepted keeps `ready` resolved, even if released in the same tick.
+        if (snapshot) resolve(snapshot);
+        else reject(new Error("Subscription released"));
         teardown = (async () => {
           await pending;
           await releaseId();
@@ -174,7 +188,7 @@ export class OwnedSubscriptions {
             .catch(this.host.failed);
         } else {
           deliver(observer);
-          for (const message of buffered) deliver(observer, message);
+          for (const update of buffered) deliver(observer, update);
         }
         return () => {
           observers.delete(observer);
@@ -205,6 +219,10 @@ export class OwnedSubscriptions {
       this.routes.get(payload.subscriptionId)?.receive(message);
   }
 
+  receiveBinary(subscriptionId: string, payload: Uint8Array): void {
+    this.routes.get(subscriptionId)?.receiveBinary(payload);
+  }
+
   restore(): void {
     this.connected = true;
     for (const registration of this.registrations) registration.start();
diff --git a/packages/client/src/daemon-client-transport-types.ts b/packages/client/src/daemon-client-transport-types.ts
index 64f84cf8c1..e632e1e3bd 100644
--- a/packages/client/src/daemon-client-transport-types.ts
+++ b/packages/client/src/daemon-client-transport-types.ts
@@ -4,7 +4,7 @@ export interface DaemonTransport {
   maxFrameBytes?: number;
   send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
   close: (code?: number, reason?: string) => void;
-  onMessage: (handler: (data: unknown, isBinary: boolean) => void) => () => void;
+  onMessage: (handler: (data: unknown, isBinary: boolean) => void | Promise<void>) => () => void;
   onOpen: (handler: () => void) => () => void;
   onClose: (handler: (event?: unknown) => void) => () => void;
   onError: (handler: (event?: unknown) => void) => () => void;
diff --git a/packages/client/src/daemon-client-transport.test.ts b/packages/client/src/daemon-client-transport.test.ts
index c95c534129..b9ea5b0454 100644
--- a/packages/client/src/daemon-client-transport.test.ts
+++ b/packages/client/src/daemon-client-transport.test.ts
@@ -1,5 +1,9 @@
 import { EventEmitter } from "node:events";
 import { describe, expect, test, vi } from "vitest";
+import { WebSocketServer, type WebSocket as ServerSocket } from "ws";
+import { exportPublicKey, generateKeyPair } from "@getpaseo/relay/e2ee";
+import { DaemonClient } from "./daemon-client.js";
+import { defaultWebSocketFactory } from "./daemon-client-websocket-transport.js";
 import {
   createEncryptedTransport,
   createWebSocketTransportFactory,
@@ -190,3 +194,103 @@ test("native drain capability survives WebSocket and encryption wrappers", async
   });
   expect(encrypted.supportsDrain).toBe(false);
 });
+
+interface ObservedSocket {
+  closeFrame: { code: number; reason: string } | null;
+}
+
+/** A daemon endpoint that accepts sockets and never answers, so every attempt times out. */
+async function silentDaemon() {
+  const server = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await new Promise<void>((resolve) => server.once("listening", () => resolve()));
+  const sockets: ObservedSocket[] = [];
+  server.on("connection", (socket: ServerSocket) => {
+    const observed: ObservedSocket = { closeFrame: null };
+    sockets.push(observed);
+    socket.on("close", (code, reason) => {
+      observed.closeFrame = { code, reason: reason.toString() };
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Missing port");
+  return {
+    url: `ws://127.0.0.1:${address.port}/ws`,
+    sockets,
+    openSockets: () => sockets.filter((entry) => entry.closeFrame === null),
+    stop: () =>
+      new Promise<void>((resolve) => {
+        for (const client of server.clients) client.terminate();
+        server.close(() => resolve());
+      }),
+  };
+}
+
+// Node's global WebSocket applies the WHATWG close rules Chromium and Electron apply:
+// close() accepts only 1000 or 3000-4999 and a reason of at most 123 UTF-8 bytes.
+describe("abandoned connections close their WebSocket", () => {
+  test.each([
+    { name: "direct", e2ee: false },
+    { name: "relay E2EE", e2ee: true },
+  ])(
+    "$name: a timed-out attempt sends a close frame before the client reconnects",
+    async ({ e2ee }) => {
+      const daemon = await silentDaemon();
+      const client = new DaemonClient({
+        url: daemon.url,
+        clientId: "cid_abandoned_close_test",
+        webSocketFactory: defaultWebSocketFactory,
+        connectTimeoutMs: 1_500,
+        reconnect: { enabled: true, baseDelayMs: 50, maxDelayMs: 50 },
+        logger: { debug() {}, info() {}, warn() {}, error() {} },
+        ...(e2ee
+          ? {
+              e2ee: {
+                enabled: true,
+                daemonPublicKeyB64: exportPublicKey(generateKeyPair().publicKey),
+              },
+            }
+          : {}),
+      });
+      try {
+        void client.connect().catch(() => {});
+        await vi.waitFor(() => expect(daemon.sockets.length).toBeGreaterThanOrEqual(2), {
+          timeout: 4_000,
+        });
+        const [abandoned] = daemon.sockets;
+        await vi.waitFor(() => expect(abandoned?.closeFrame).not.toBeNull(), { timeout: 500 });
+        expect(abandoned?.closeFrame?.reason).toBe("Connection timed out");
+
+        // The newest attempt may still be connecting; aborting it closes without a frame.
+        await client.close();
+        await vi.waitFor(() => expect(daemon.openSockets()).toEqual([]), { timeout: 500 });
+      } finally {
+        await client.close();
+        await daemon.stop();
+      }
+    },
+    10_000,
+  );
+
+  test("a code or reason the WebSocket API rejects still closes the socket", async () => {
+    const daemon = await silentDaemon();
+    try {
+      const transport = createWebSocketTransportFactory(defaultWebSocketFactory)({
+        url: daemon.url,
+      });
+      await new Promise<void>((resolve) => transport.onOpen(() => resolve()));
+      const reason = `Decryption failed: ${"é".repeat(100)}`;
+
+      expect(() => transport.close(1011, reason)).not.toThrow();
+
+      await vi.waitFor(() => expect(daemon.sockets[0]?.closeFrame).not.toBeNull(), {
+        timeout: 500,
+      });
+      const frame = daemon.sockets[0]?.closeFrame;
+      expect(frame?.code).toBe(1000);
+      expect(reason.startsWith(frame?.reason ?? "")).toBe(true);
+      expect(Buffer.byteLength(frame?.reason ?? "")).toBe(123);
+    } finally {
+      await daemon.stop();
+    }
+  });
+});
diff --git a/packages/client/src/daemon-client-websocket-transport.ts b/packages/client/src/daemon-client-websocket-transport.ts
index c7ec87555d..5331aea9f4 100644
--- a/packages/client/src/daemon-client-websocket-transport.ts
+++ b/packages/client/src/daemon-client-websocket-transport.ts
@@ -82,7 +82,7 @@ export function createWebSocketTransportFactory(factory: WebSocketFactory): Daem
         // connect timeouts does not crash the CLI with an unhandled error event.
         const suppressEarlyCloseError = bindTemporaryEarlyCloseErrorHandler(ws);
         try {
-          ws.close(code, reason);
+          ws.close(toSendableCloseCode(code), toSendableCloseReason(reason));
         } finally {
           if (typeof ws.on !== "function" && typeof ws.addEventListener !== "function") {
             suppressEarlyCloseError();
@@ -97,6 +97,32 @@ export function createWebSocketTransportFactory(factory: WebSocketFactory): Daem
   };
 }
 
+// WHATWG WebSocket.close throws for a code other than 1000 or 3000-4999 and for a
+// reason over 123 UTF-8 bytes, and the throw leaves the socket open: the peer keeps
+// streaming into a connection nobody reads. Browsers, Electron and Node's global
+// WebSocket enforce this; Node's `ws` accepts more. Translate once here so callers
+// keep their reasons and every runtime sends the same close frame.
+const MAX_CLOSE_REASON_BYTES = 123;
+
+function toSendableCloseCode(code: number | undefined): number {
+  if (code === 1000 || (code !== undefined && code >= 3000 && code <= 4999)) return code;
+  return 1000;
+}
+
+function toSendableCloseReason(reason: string | undefined): string | undefined {
+  if (reason === undefined) return undefined;
+  const encoder = new TextEncoder();
+  if (encoder.encode(reason).byteLength <= MAX_CLOSE_REASON_BYTES) return reason;
+  let truncated = "";
+  let bytes = 0;
+  for (const character of reason) {
+    bytes += encoder.encode(character).byteLength;
+    if (bytes > MAX_CLOSE_REASON_BYTES) break;
+    truncated += character;
+  }
+  return truncated;
+}
+
 function bindWsMessageHandler(
   ws: WebSocketLike,
   handler: (data: unknown, isBinary: boolean) => void,
diff --git a/packages/client/src/daemon-client.test.ts b/packages/client/src/daemon-client.test.ts
index 4fa7d5723c..2ddef8cc61 100644
--- a/packages/client/src/daemon-client.test.ts
+++ b/packages/client/src/daemon-client.test.ts
@@ -657,6 +657,38 @@ class FakeDaemon {
     },
   };
 
+  finishTransfer(): void {
+    // Four MiB of JSON whitespace precedes this valid application message.
+    const bytes = new TextEncoder().encode(
+      JSON.stringify({
+        type: "session",
+        message: {
+          type: "status",
+          payload: {
+            status: "server_info",
+            serverId: "srv_heartbeat_test",
+            hostname: null,
+            version: null,
+            features: { binaryChunkingV1: true },
+          },
+        },
+      }),
+    );
+    const frame = new Uint8Array(bytes.length + 4);
+    frame.set([0x31, 1, 0, 2]);
+    frame.set(bytes, 4);
+    this.onMessage(frame);
+    this.onMessage(JSON.stringify({ type: "pong" }));
+    this.daemonAnswersPingsAfter("fast");
+  }
+
+  receiveChunk(start: boolean): void {
+    const frame = new Uint8Array(1024 * 1024 + 4);
+    frame.set([0x31, 1, 0, start ? 1 : 0]);
+    frame.fill(32, 4);
+    this.onMessage(frame);
+  }
+
   openConnection(): void {
     this.onOpen();
     this.onMessage(
@@ -667,6 +699,7 @@ class FakeDaemon {
           payload: {
             status: "server_info",
             serverId: "srv_heartbeat_test",
+            features: { binaryChunkingV1: true },
             hostname: null,
             version: null,
           },
@@ -695,6 +728,10 @@ class FakeDaemon {
     this.onClose({ reason });
   }
 
+  daemonSendsPong(): void {
+    this.onMessage(JSON.stringify({ type: "pong" }));
+  }
+
   triggerError(event?: unknown): void {
     this.onError(event);
   }
@@ -1106,9 +1143,11 @@ test("advertises client capabilities in hello", async () => {
       terminal_chunked_replay: true,
       timeline_notifications: true,
       plugin_timeline_items: true,
+      plugin_binary_payloads: true,
       workspace_setup_blocked: true,
       workspace_setup_observation: true,
       hello_rejection: true,
+      background_agents: true,
       browser_host: {
         supportedCommands: ["list_tabs"],
         hostKind: "desktop app",
@@ -2570,7 +2609,7 @@ test("keeps default connect timeout shorter than session RPC waiters", async ()
   }
 });
 
-test("foreground verification replaces a silently broken socket without waiting for heartbeats", async () => {
+test("foreground tears down a silently dead socket after two fresh five-second windows and reconnects at once", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2588,10 +2627,23 @@ test("foreground verification replaces a silently broken socket without waiting
   await connection;
 
   client.ensureConnected({ verify: true });
-  await vi.advanceTimersByTimeAsync(3_000);
+  expect(first.pingTimestamps()).toEqual(["0s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  // The first silent window is followed by a second check at once, not ten seconds later.
+  expect(first.closesFromClient()).toEqual([]);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s"]);
+  await vi.advanceTimersByTimeAsync(4_999);
+  expect(first.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  // The reconnect is immediate: no 1.5s backoff after a foreground liveness teardown.
   expect(attempts).toBe(2);
   second.openConnection();
   expect(client.getConnectionState()).toEqual({ status: "connected" });
+  // The replacement runs the normal heartbeat cadence.
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(second.pingTimestamps()).toEqual(["20s"]);
+  expect(second.closesFromClient()).toEqual([]);
 });
 
 test("foreground verification preserves a healthy socket and deduplicates simultaneous checks", async () => {
@@ -2616,7 +2668,503 @@ test("foreground verification preserves a healthy socket and deduplicates simult
   expect(daemon.closesFromClient()).toEqual([]);
 });
 
-test("an obsolete foreground probe cannot close a replacement connection", async () => {
+test("chunks prevent heartbeat misses until silence causes two misses", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "bulk-resume",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  let measurementError: unknown;
+  void client.measureLatency({ timeoutMs: 5_000 }).catch((error: unknown) => {
+    measurementError = error;
+  });
+  // Chunks complete every four seconds for the first 36 seconds; no pong ever arrives.
+  for (let index = 0; index < 9; index++) {
+    await vi.advanceTimersByTimeAsync(4_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  expect(measurementError).toEqual(
+    expect.objectContaining({
+      message: "Latency measurement timed out (5000ms)",
+    }),
+  );
+  // Progress inside the foreground window returned the heartbeat to its normal cadence.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "15s"]);
+  await vi.advanceTimersByTimeAsync(19_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(daemon.pingTimestamps()).toEqual(["0s", "15s", "40s"]);
+  await vi.advanceTimersByTimeAsync(24_999);
+  expect(daemon.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(daemon.pingTimestamps()).toEqual(["0s", "15s", "40s", "65s"]);
+  expect(daemon.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+});
+
+test("foreground preserves a multi-MB transfer with its pong queued behind chunks", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "bulk-resume",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(3_001);
+  expect(daemon.closesFromClient()).toEqual([]);
+  for (let index = 0; index < 5; index++) {
+    await vi.advanceTimersByTimeAsync(4_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  // The first chunk landed seven seconds after foreground: the first window was silent, the
+  // second saw progress, so the cycle ended without a teardown and the cadence is normal again.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "5s", "20s"]);
+  daemon.finishTransfer();
+  await vi.advanceTimersByTimeAsync(30_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+});
+
+test("chunk progress beyond the daemon lease keeps sending heartbeat pings", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "long-download",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  for (let index = 0; index < 12; index++) {
+    await vi.advanceTimersByTimeAsync(4_000);
+    daemon.receiveChunk(index === 0);
+    // Each completed window starts the next ping ten seconds later,
+    // even though the response and all queued pongs are still in flight.
+    const now = (index + 1) * 4;
+    const expected = ["0s"];
+    if (now >= 15) expected.push("15s");
+    if (now >= 40) expected.push("40s");
+    expect(daemon.pingTimestamps()).toEqual(expected);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  daemon.finishTransfer();
+  await vi.advanceTimersByTimeAsync(30_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+});
+
+function connectThroughReplacements(
+  clientId: string,
+  daemons: FakeDaemon[],
+  options?: { reconnect?: { enabled: boolean } },
+): { client: DaemonClient; attempts: () => number } {
+  let attempts = 0;
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId,
+    logger: noopLogger,
+    ...(options?.reconnect ? { reconnect: options.reconnect } : {}),
+    transportFactory: () => {
+      const daemon = daemons[Math.min(attempts, daemons.length - 1)]!;
+      attempts += 1;
+      return daemon.transport;
+    },
+  });
+  clients.push(client);
+  return { client, attempts: () => attempts };
+}
+
+test("foreground supersedes a heartbeat that straddled the suspension without counting a miss", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  const { client, attempts } = connectThroughReplacements("resume-before-expiry", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  first.daemonGoesSilent();
+  await vi.advanceTimersByTimeAsync(10_000); // heartbeat ping outstanding when the OS suspends JS
+  await vi.advanceTimersByTimeAsync(14_990); // resume: AppState lands before the stale timer
+  client.ensureConnected({ verify: true });
+  expect(first.pingTimestamps()).toEqual(["10s", "24.99s"]);
+  await vi.advanceTimersByTimeAsync(10); // the stale deadline passes without a miss
+  await vi.advanceTimersByTimeAsync(4_990);
+  expect(first.closesFromClient()).toEqual([]);
+  expect(first.pingTimestamps()).toEqual(["10s", "24.99s", "29.99s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+});
+
+test("foreground does not inherit a miss recorded before the app was suspended", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  const { client, attempts } = connectThroughReplacements("resume-after-expiry", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  first.daemonGoesSilent();
+  await vi.advanceTimersByTimeAsync(25_000); // ping at 10s missed at 25s, before or during suspension
+  client.ensureConnected({ verify: true });
+  expect(first.pingTimestamps()).toEqual(["10s", "25s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  // Two fresh windows: the old miss would have torn down here.
+  expect(first.closesFromClient()).toEqual([]);
+  expect(first.pingTimestamps()).toEqual(["10s", "25s", "30s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+});
+
+test("a slow but healthy socket survives foreground after a miss before the suspension", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  const { client, attempts } = connectThroughReplacements("resume-slow-pong", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  daemon.daemonGoesSilent();
+  await vi.advanceTimersByTimeAsync(25_000); // one miss
+  daemon.daemonAnswersPingsAfter("5.5s");
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(60_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(attempts()).toBe(1);
+});
+
+test("a pong that arrives after the first foreground window keeps the connection and restores the cadence", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonAnswersPingsAfter("5.5s");
+  const { client, attempts } = connectThroughReplacements("slow-pong", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(daemon.pingTimestamps()).toEqual(["0s", "5s"]);
+  await vi.advanceTimersByTimeAsync(55_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(attempts()).toBe(1);
+  // After the late pong the heartbeat runs ten seconds after each settled probe again.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "5s", "15.5s", "31s", "46.5s"]);
+});
+
+test("a latency measurement outstanding at foreground keeps its own deadline, then the cycle runs", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("latency-then-foreground", [
+    first,
+    second,
+  ]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  const measurement = client.measureLatency({ timeoutMs: 1_000 });
+  const measurementError = measurement.then(
+    () => null,
+    (error: unknown) => error,
+  );
+  client.ensureConnected({ verify: true });
+  expect(first.pingTimestamps()).toEqual(["0s"]);
+  await vi.advanceTimersByTimeAsync(1_000);
+  await expect(measurementError).resolves.toEqual(
+    expect.objectContaining({ message: "Latency measurement timed out (1000ms)" }),
+  );
+  expect(first.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.pingTimestamps()).toEqual(["0s", "1s", "6s"]);
+  expect(first.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+});
+
+test("a shared latency probe's activity from before foreground does not satisfy the fresh check", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("stale-activity", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  void client.measureLatency({ timeoutMs: 5_000 }).catch(() => {});
+  first.receiveChunk(true); // a frame arrived while the measurement was outstanding, then the socket died
+  client.ensureConnected({ verify: true });
+  expect(first.pingTimestamps()).toEqual(["0s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  // The measurement's own deadline passed; the foreground cycle starts its first fresh window now.
+  expect(first.closesFromClient()).toEqual([]);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s", "10s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+});
+
+test("a latency measurement that joined a heartbeat probe survives the foreground check", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonAnswersPingsAfter("2s");
+  const { client, attempts } = connectThroughReplacements("latency-joins-heartbeat", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  await vi.advanceTimersByTimeAsync(10_000); // the first heartbeat ping is outstanding
+  const measurement = client.measureLatency({ timeoutMs: 5_000 });
+  await vi.advanceTimersByTimeAsync(1_000);
+  client.ensureConnected({ verify: true });
+  expect(daemon.pingTimestamps()).toEqual(["10s", "11s"]);
+  // The heartbeat's pong lands at 12s and answers the measurement that joined it.
+  await vi.advanceTimersByTimeAsync(1_000);
+  await expect(measurement).resolves.toBe(2000);
+  await vi.advanceTimersByTimeAsync(19_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(attempts()).toBe(1);
+  expect(daemon.pingTimestamps()).toEqual(["10s", "11s", "22s"]);
+});
+
+test("a joined latency measurement outlives a silent foreground window until its own deadline", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonAnswersPingsAfter("7s");
+  const { client, attempts } = connectThroughReplacements("latency-outlives-window", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  await vi.advanceTimersByTimeAsync(10_000); // the first heartbeat ping is outstanding
+  const measurement = client.measureLatency({ timeoutMs: 10_000 });
+  await vi.advanceTimersByTimeAsync(1_000);
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000); // the first window closes silent at 16s
+  expect(daemon.pingTimestamps()).toEqual(["10s", "11s", "16s"]);
+  // The heartbeat's pong lands at 17s, inside the second window and before the 20s deadline.
+  await vi.advanceTimersByTimeAsync(1_000);
+  await expect(measurement).resolves.toBe(7000);
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(attempts()).toBe(1);
+  expect(daemon.pingTimestamps()).toEqual(["10s", "11s", "16s", "27s"]);
+});
+
+// Fake timers cannot suspend: a suspension is modelled as the wall clock jumping forward while
+// the pending window timer stays queued, then firing late on resume.
+async function suspendFor(ms: number): Promise<void> {
+  vi.setSystemTime(Date.now() + ms);
+}
+
+test("a foreground window that spanned a second suspension is discarded when the timer fires first", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("suspended-mid-cycle-timer", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000); // window 1 silent, window 2 outstanding
+  expect(daemon.pingTimestamps()).toEqual(["0s", "5s"]);
+  await suspendFor(60_000);
+  daemon.daemonAnswersPingsAfter("fast"); // the socket is healthy on resume
+  await vi.advanceTimersByTimeAsync(5_000); // window 2's timer fires late
+  client.ensureConnected({ verify: true }); // then AppState lands
+  await vi.advanceTimersByTimeAsync(1_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(attempts()).toBe(1);
+});
+
+test("a foreground window that spanned a second suspension is discarded when AppState fires first", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("suspended-mid-cycle-appstate", [daemon]);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(daemon.pingTimestamps()).toEqual(["0s", "5s"]);
+  await suspendFor(60_000);
+  daemon.daemonAnswersPingsAfter("fast");
+  client.ensureConnected({ verify: true }); // AppState lands before the queued timer
+  await vi.advanceTimersByTimeAsync(5_000); // window 2's timer fires late
+  await vi.advanceTimersByTimeAsync(1_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(attempts()).toBe(1);
+});
+
+test("a dead socket after a second suspension mid-cycle still gets two fresh windows", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("suspended-mid-cycle-dead", [
+    first,
+    second,
+  ]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000);
+  first.receiveChunk(true); // a frame before the second suspension is not evidence after it
+  await suspendFor(60_000);
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000); // the late timer discards window 2 and starts over
+  expect(first.pingTimestamps()).toEqual(["0s", "5s", "10s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([]);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s", "10s", "15s"]);
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+});
+
+test("repeated foreground events share one cycle and do not restart its windows", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("repeated-foreground", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  for (let elapsedSeconds = 1; elapsedSeconds <= 9; elapsedSeconds++) {
+    await vi.advanceTimersByTimeAsync(1_000);
+    client.ensureConnected({ verify: true });
+    expect(first.closesFromClient()).toEqual([]);
+  }
+  expect(first.pingTimestamps()).toEqual(["0s", "5s"]);
+  await vi.advanceTimersByTimeAsync(1_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(attempts()).toBe(2);
+  second.openConnection();
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+});
+
+test("a late pong from the replaced socket does not count for the replacement", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  second.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("late-pong", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(attempts()).toBe(2);
+  second.openConnection();
+  client.ensureConnected({ verify: true });
+  expect(second.pingTimestamps()).toEqual(["10s"]);
+  await vi.advanceTimersByTimeAsync(2_000);
+  first.daemonSendsPong();
+  await vi.advanceTimersByTimeAsync(8_000);
+  expect(second.pingTimestamps()).toEqual(["10s", "15s"]);
+  expect(second.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+});
+
+test("closing the client in the middle of a foreground cycle stops it", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("close-mid-cycle", [first, second]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s"]);
+  await client.close();
+  await vi.advanceTimersByTimeAsync(60_000);
+  expect(first.pingTimestamps()).toEqual(["0s", "5s"]);
+  expect(first.closesFromClient()).toEqual([{ code: 1000, reason: "Client closed" }]);
+  expect(attempts()).toBe(1);
+  expect(client.getConnectionState()).toEqual({ status: "disposed" });
+});
+
+test("a foreground teardown with reconnect disabled reports the timeout and stays down", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("no-reconnect", [daemon], {
+    reconnect: { enabled: false },
+  });
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(client.getConnectionState()).toEqual({
+    status: "disconnected",
+    reason: "Liveness check timed out (5000ms)",
+  });
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(attempts()).toBe(1);
+});
+
+test("the immediate reconnect after a foreground teardown backs off normally if it fails", async () => {
+  useHeartbeatClock();
+  const first = new FakeDaemon();
+  const second = new FakeDaemon();
+  const third = new FakeDaemon();
+  first.daemonGoesSilent();
+  const { client, attempts } = connectThroughReplacements("no-storm", [first, second, third]);
+  const connection = client.connect();
+  first.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(attempts()).toBe(2);
+  second.daemonClosesWith("connection refused");
+  await vi.advanceTimersByTimeAsync(1_499);
+  expect(attempts()).toBe(2);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(attempts()).toBe(3);
+  third.openConnection();
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+});
+
+test("an obsolete heartbeat cannot close a replacement connection", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2733,6 +3281,30 @@ test("sends only one ping while a slow pong is still outstanding", async () => {
   expect(session.pingTimestamps()).toEqual(["10s"]);
 });
 
+test("a heartbeat sharing a latency measurement still saves the RTT", async () => {
+  useHeartbeatClock();
+  const session = new DaemonClientSession();
+  session.daemonAnswersPingsAfter("2s");
+  await session.connect();
+  await session.advance(9_000);
+  const measurement = session.measureLatency({ timeoutMs: 5_000 });
+  await session.advance(2_000);
+  await expect(measurement).resolves.toBe(2000);
+  expect(session.lastLivenessRttMs()).toBe(2000);
+});
+
+test("a measurement that joins an in-flight ping reports that ping's round trip", async () => {
+  useHeartbeatClock();
+  const session = new DaemonClientSession();
+  session.daemonAnswersPingsAfter("2s");
+  await session.connect();
+  await session.advance(11_000); // the heartbeat ping sent at 10s is still outstanding
+  const measurement = session.measureLatency({ timeoutMs: 5_000 });
+  await session.advance(1_000);
+  await expect(measurement).resolves.toBe(2000);
+  expect(session.lastLivenessRttMs()).toBe(2000);
+});
+
 test("reports the round-trip time of the last successful heartbeat", async () => {
   useHeartbeatClock();
   const session = new DaemonClientSession();
@@ -3727,6 +4299,35 @@ test("rejects an internal create before sending when the host predates internal
   expect(mock.sent).toHaveLength(0);
 });
 
+test("metadata needs a host that advertises entityMetadata and sends nothing to one that does not", async () => {
+  const mock = createMockTransport();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "clsk_unit_test",
+    logger: createMockLogger(),
+    reconnect: { enabled: false },
+    transportFactory: () => mock.transport,
+  });
+  clients.push(client);
+  const connectPromise = client.connect();
+  mock.triggerOpen({ features: {} });
+  await connectPromise;
+
+  const update = "Update the host to use metadata.";
+  await expect(
+    client.createAgent({ provider: "codex", cwd: "/tmp/project", metadata: { key: "value" } }),
+  ).rejects.toThrow(update);
+  await expect(
+    client.createWorkspace({
+      source: { kind: "directory", path: "/tmp/project" },
+      metadata: { key: "value" },
+    }),
+  ).rejects.toThrow(update);
+  await expect(client.setAgentMetadata("agent-1", { key: null })).rejects.toThrow(update);
+  await expect(client.setWorkspaceMetadata("workspace-1", { key: null })).rejects.toThrow(update);
+  expect(mock.sent).toHaveLength(0);
+});
+
 test("sends internal workspace creation and internal listings only to hosts that support them", async () => {
   const logger = createMockLogger();
   const mock = createMockTransport();
@@ -4653,6 +5254,65 @@ test("logs configured runtime generation in connection transition events", async
   }
 });
 
+test("closing a client while subscription releases are in flight reports only the disposal", async () => {
+  const mock = createMockTransport();
+  let transportsCreated = 0;
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "clsk_unit_test",
+    logger: createMockLogger(),
+    reconnect: { enabled: true, baseDelayMs: 1, maxDelayMs: 1 },
+    transportFactory: () => {
+      transportsCreated += 1;
+      return mock.transport;
+    },
+  });
+  clients.push(client);
+
+  const connectPromise = client.connect();
+  mock.triggerOpen();
+  await connectPromise;
+
+  const subscriptions = ["/tmp/one", "/tmp/two"].map((cwd) =>
+    client.observeCheckoutDiff(cwd, { mode: "uncommitted" }),
+  );
+  await vi.waitFor(() => expect(mock.sent).toHaveLength(2));
+  for (const [index, frame] of [...mock.sent].entries()) {
+    const request = parseSentFrame(frame);
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "subscribe_checkout_diff_response",
+        payload: {
+          subscriptionId: `checkout-sub-${index}`,
+          cwd: request.cwd,
+          files: [],
+          error: null,
+          requestId: request.requestId,
+        },
+      }),
+    );
+  }
+  await Promise.all(subscriptions.map((subscription) => subscription.ready));
+
+  // The host runtime releases its handlers and closes the previous client without waiting.
+  const releases = subscriptions.map((subscription) =>
+    subscription.release().catch(() => undefined),
+  );
+  await vi.waitFor(() => expect(mock.sent).toHaveLength(4));
+
+  const statuses: string[] = [];
+  client.subscribeConnectionStatus((state) => statuses.push(state.status));
+  statuses.length = 0;
+
+  await client.close();
+  await Promise.all(releases);
+  await new Promise((resolve) => setTimeout(resolve, 20));
+
+  expect(statuses).toEqual(["disposed"]);
+  expect(client.lastError).toBeNull();
+  expect(transportsCreated).toBe(1);
+});
+
 test("subscribes to checkout diff updates via RPC handshake", async () => {
   const logger = createMockLogger();
   const mock = createMockTransport();
@@ -8924,3 +9584,552 @@ test("routed channels inherit an origin without drain support", async () => {
   expect(route.supportsDrain).toBe(false);
   route.close();
 });
+
+describe("provider options across daemon versions", () => {
+  const agentSnapshot = {
+    id: "agent-1",
+    provider: "codex",
+    cwd: "/repo",
+    model: null,
+    thinkingOptionId: null,
+    effectiveThinkingOptionId: null,
+    createdAt: "2026-04-30T00:00:00.000Z",
+    updatedAt: "2026-04-30T00:00:00.000Z",
+    lastUserMessageAt: null,
+    status: "idle",
+    capabilities: {
+      supportsStreaming: false,
+      supportsSessionPersistence: false,
+      supportsDynamicModes: false,
+      supportsMcpServers: false,
+      supportsReasoningStream: false,
+      supportsToolInvocations: false,
+    },
+    currentModeId: null,
+    availableModes: [],
+    pendingPermissions: [],
+    persistence: null,
+    title: null,
+    labels: {},
+    requiresAttention: false,
+    attentionReason: null,
+  };
+  const speedFeature = {
+    type: "select",
+    id: "service_tier",
+    label: "Speed",
+    value: "priority",
+    options: [
+      { id: "default", label: "Normal", isDefault: true },
+      { id: "priority", label: "Fast" },
+    ],
+  };
+
+  async function connect(features: Record<string, boolean>) {
+    const mock = createMockTransport();
+    const client = new DaemonClient({
+      url: "ws://test",
+      clientId: "provider_options",
+      transportFactory: () => mock.transport,
+      reconnect: { enabled: false },
+    });
+    clients.push(client);
+    const connecting = client.connect();
+    mock.triggerOpen({ features });
+    await connecting;
+    const sentMessages = () =>
+      mock.sent.map(
+        (frame) => (JSON.parse(frame as string) as { message: Record<string, unknown> }).message,
+      );
+    return { mock, client, sentMessages };
+  }
+
+  test("a legacy create and a timeline read return the agent with controls over options", async () => {
+    const { mock, client, sentMessages } = await connect({});
+    const legacyAgent = { ...agentSnapshot, features: [speedFeature] };
+    const answerLast = (reply: (requestId: string) => Record<string, unknown>) => {
+      const sent = sentMessages();
+      const requestId = String(sent[sent.length - 1].requestId);
+      mock.triggerMessage(wrapSessionMessage(reply(requestId) as never));
+    };
+
+    const creating = client.createAgent({ provider: "codex", cwd: "/repo" });
+    answerLast((requestId) => ({
+      type: "status",
+      payload: { status: "agent_created", requestId, agentId: "agent-1", agent: legacyAgent },
+    }));
+    const created = await creating;
+
+    const reading = client.fetchAgentTimeline("agent-1");
+    answerLast((requestId) => ({
+      type: "fetch_agent_timeline_response",
+      payload: {
+        requestId,
+        agentId: "agent-1",
+        agent: legacyAgent,
+        direction: "tail",
+        projection: "projected",
+        epoch: "epoch-1",
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window: { minSeq: 0, maxSeq: 0, nextSeq: 1 },
+        startCursor: null,
+        endCursor: null,
+        hasOlder: false,
+        hasNewer: false,
+        entries: [],
+        error: null,
+      },
+    }));
+    const timeline = await reading;
+
+    expect(created.options).toEqual({ service_tier: "priority" });
+    expect(created.controls).toEqual([expect.objectContaining({ key: "service_tier" })]);
+    expect(timeline.agent?.options).toEqual({ service_tier: "priority" });
+    expect(timeline.agent?.controls).toEqual([expect.objectContaining({ key: "service_tier" })]);
+  });
+
+  test("a legacy daemon's features arrive as controls over options", async () => {
+    const { mock, client } = await connect({});
+    const received: Array<{ controls?: unknown; options?: unknown }> = [];
+    client.on("agent_update", (message) => {
+      if (message.payload.kind === "upsert") received.push(message.payload.agent);
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: { kind: "upsert", agent: { ...agentSnapshot, features: [speedFeature] } },
+      }),
+    );
+    expect(received).toEqual([
+      expect.objectContaining({
+        options: { service_tier: "priority" },
+        controls: [
+          expect.objectContaining({
+            type: "select",
+            key: "service_tier",
+            defaultValue: "default",
+            choices: [
+              { value: "default", label: "Normal" },
+              { value: "priority", label: "Fast" },
+            ],
+          }),
+        ],
+      }),
+    ]);
+  });
+
+  test("a legacy daemon takes option writes as feature writes", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const write = client.setAgentOptions("agent-1", { service_tier: "default" });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "set_agent_feature_request",
+      agentId: "agent-1",
+      featureId: "service_tier",
+      value: "default",
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "set_agent_feature_response",
+        payload: { requestId: request.requestId, agentId: "agent-1", accepted: true, error: null },
+      }),
+    );
+    await write;
+  });
+
+  // The old Codex setter rejects a non-string `service_tier` and the old Claude setter reads
+  // `null` as off, so a reset is sent as the value the old API can represent.
+  async function resetOnLegacyDaemon(agent: Record<string, unknown>, patch: Record<string, null>) {
+    const { client, sentMessages, mock } = await connect({});
+    const reply = (message: Record<string, unknown>) =>
+      mock.triggerMessage(wrapSessionMessage(message as never));
+    const writing = client.setAgentOptions("agent-1", patch);
+    const [fetch] = sentMessages();
+    expect(fetch).toMatchObject({ type: "fetch_agent_request", agentId: "agent-1" });
+    reply({
+      type: "fetch_agent_response",
+      payload: { requestId: fetch.requestId, agent, project: null, error: null },
+    });
+    return { writing, sentMessages, reply };
+  }
+
+  test("a legacy daemon resets a choice to the default the old API names", async () => {
+    const { writing, sentMessages, reply } = await resetOnLegacyDaemon(
+      { ...agentSnapshot, provider: "codex", features: [speedFeature] },
+      { service_tier: null },
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    const write = sentMessages()[1];
+    expect(write).toMatchObject({
+      type: "set_agent_feature_request",
+      featureId: "service_tier",
+      value: "default",
+    });
+    reply({
+      type: "set_agent_feature_response",
+      payload: { requestId: write.requestId, agentId: "agent-1", accepted: true, error: null },
+    });
+    await writing;
+  });
+
+  test("a legacy daemon resets a toggle to off", async () => {
+    const { writing, sentMessages, reply } = await resetOnLegacyDaemon(
+      {
+        ...agentSnapshot,
+        features: [{ type: "toggle", id: "fast_mode", label: "Fast", value: true }],
+      },
+      { fast_mode: null },
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    const write = sentMessages()[1];
+    expect(write).toMatchObject({ featureId: "fast_mode", value: false });
+    reply({
+      type: "set_agent_feature_response",
+      payload: { requestId: write.requestId, agentId: "agent-1", accepted: true, error: null },
+    });
+    await writing;
+  });
+
+  test("a legacy daemon cannot reset an option no control draws, and writes nothing", async () => {
+    const { writing, sentMessages } = await resetOnLegacyDaemon(
+      { ...agentSnapshot, features: [speedFeature] },
+      { token_budget: null },
+    );
+    await expect(writing).rejects.toThrow("Update the host to reset token_budget.");
+    expect(sentMessages()).toHaveLength(1);
+  });
+
+  test("a legacy daemon applies a config reset as the default the old API names", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const reply = (message: Record<string, unknown>) =>
+      mock.triggerMessage(wrapSessionMessage(message as never));
+    const applying = client.applyAgentConfig("agent-1", {
+      modeId: "plan",
+      options: { service_tier: null, sandbox_mode: "read-only" },
+    });
+    const [fetch] = sentMessages();
+    expect(fetch).toMatchObject({ type: "fetch_agent_request", agentId: "agent-1" });
+    reply({
+      type: "fetch_agent_response",
+      payload: {
+        requestId: fetch.requestId,
+        agent: { ...agentSnapshot, provider: "codex", features: [speedFeature] },
+        project: null,
+        error: null,
+      },
+    });
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    const apply = sentMessages()[1];
+    expect(apply).toMatchObject({
+      type: "agent.config.apply.request",
+      config: {
+        modeId: "plan",
+        featureValues: { service_tier: "default", sandbox_mode: "read-only" },
+      },
+    });
+    expect(apply.config).not.toHaveProperty("options");
+    reply({
+      type: "agent.config.apply.response",
+      payload: { requestId: apply.requestId, agentId: "agent-1", accepted: true, error: null },
+    });
+    await applying;
+  });
+
+  test("a legacy daemon cannot apply a config reset it cannot name, and applies nothing", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const applying = client.applyAgentConfig("agent-1", { options: { token_budget: null } });
+    const [fetch] = sentMessages();
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "fetch_agent_response",
+        payload: {
+          requestId: fetch.requestId,
+          agent: { ...agentSnapshot, features: [speedFeature] },
+          project: null,
+          error: null,
+        },
+      } as never),
+    );
+    await expect(applying).rejects.toThrow("Update the host to reset token_budget.");
+    expect(sentMessages()).toHaveLength(1);
+  });
+
+  test("a current daemon takes option writes as one options patch", async () => {
+    const { client, sentMessages, mock } = await connect({ providerOptionControls: true });
+    const write = client.setAgentOptions("agent-1", { service_tier: null, sandbox_mode: "x" });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "agent.config.apply.request",
+      agentId: "agent-1",
+      config: { options: { service_tier: null, sandbox_mode: "x" } },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent.config.apply.response",
+        payload: { requestId: request.requestId, agentId: "agent-1", accepted: true, error: null },
+      }),
+    );
+    await write;
+  });
+
+  test("a legacy draft listing answers with controls and options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const listing = client.listProviderControls({
+      provider: "codex",
+      cwd: "/repo",
+      providerOptions: { service_tier: "default" },
+    });
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "codex", featureValues: { service_tier: "default" } },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "codex",
+          features: [{ ...speedFeature, value: "default" }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: request.requestId,
+        },
+      }),
+    );
+    await expect(listing).resolves.toMatchObject({
+      provider: "codex",
+      options: { service_tier: "default" },
+      controls: [expect.objectContaining({ key: "service_tier" })],
+    });
+  });
+
+  test("a legacy daemon's profiles are read and saved by their options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    const reading = client.getDaemonConfig();
+    const [read] = sentMessages();
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "get_daemon_config_response",
+        payload: {
+          requestId: read.requestId,
+          config: {
+            mcp: { injectIntoAgents: true },
+            agentProfiles: [
+              {
+                id: "p1",
+                name: "Fast",
+                provider: "codex",
+                featureValues: { service_tier: "fast" },
+              },
+            ],
+          },
+        },
+      }),
+    );
+    const { config } = await reading;
+    expect(config.agentProfiles?.[0]).toMatchObject({ options: { service_tier: "fast" } });
+    expect(config.agentProfiles?.[0]).not.toHaveProperty("featureValues");
+
+    void client.patchDaemonConfig({ agentProfiles: config.agentProfiles }).catch(() => {});
+    const written = sentMessages().find((message) => message.type === "set_daemon_config_request");
+    expect(written).toMatchObject({
+      config: { agentProfiles: [{ featureValues: { service_tier: "fast" } }] },
+    });
+    expect(written).not.toMatchObject({ config: { agentProfiles: [{ options: {} }] } });
+  });
+
+  test("a legacy daemon's profile with both featureValues and options keeps both when saved", async () => {
+    // `options` survives on a legacy daemon's passthrough profile after a downgrade, while its
+    // own app keeps editing `featureValues`.
+    const { client, sentMessages, mock } = await connect({});
+    const reading = client.getDaemonConfig();
+    const [read] = sentMessages();
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "get_daemon_config_response",
+        payload: {
+          requestId: read.requestId,
+          config: {
+            mcp: { injectIntoAgents: true },
+            agentProfiles: [
+              {
+                id: "p1",
+                name: "Mixed",
+                provider: "codex",
+                featureValues: { service_tier: "fast", sandbox_mode: "workspace-write" },
+                options: { sandbox_mode: "read-only" },
+              },
+            ],
+          },
+        },
+      }),
+    );
+    const { config } = await reading;
+    expect(config.agentProfiles?.[0]).toMatchObject({
+      options: { service_tier: "fast", sandbox_mode: "read-only" },
+    });
+    expect(config.agentProfiles?.[0]).not.toHaveProperty("featureValues");
+
+    void client.patchDaemonConfig({ agentProfiles: config.agentProfiles }).catch(() => {});
+    const written = sentMessages().find((message) => message.type === "set_daemon_config_request");
+    expect(written).toMatchObject({
+      config: {
+        agentProfiles: [{ featureValues: { service_tier: "fast", sandbox_mode: "read-only" } }],
+      },
+    });
+  });
+
+  test("a legacy daemon applies a profile's options as feature values", async () => {
+    const { client, sentMessages } = await connect({});
+    void client.applyAgentConfig("agent-1", { options: { service_tier: "fast" } }).catch(() => {});
+    const [request] = sentMessages();
+    expect(request).toMatchObject({
+      type: "agent.config.apply.request",
+      config: { featureValues: { service_tier: "fast" } },
+    });
+  });
+
+  test("a cold legacy create lists the provider's features before routing its options", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    void client
+      .createAgent({
+        config: {
+          provider: "claude",
+          cwd: "/repo",
+          providerOptions: { fast_mode: true, sandbox_mode: "read-only" },
+        },
+      })
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "claude", cwd: "/repo" },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "claude",
+          features: [{ type: "toggle", id: "fast_mode", label: "Fast", value: false }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    expect(sentMessages()[1].config).toMatchObject({
+      featureValues: { fast_mode: true },
+      providerOptions: { sandbox_mode: "read-only" },
+    });
+  });
+
+  test("a legacy workspace create routes its agent's options from its own model's controls", async () => {
+    const { client, sentMessages, mock } = await connect({ creationLifecycle: true });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: {
+          kind: "upsert",
+          agent: { ...agentSnapshot, provider: "codex", model: "mini", features: [] },
+        },
+      }),
+    );
+    void client
+      .createWorkspace({
+        source: { kind: "directory", path: "/repo" },
+        agent: {
+          config: {
+            provider: "codex",
+            cwd: "/repo",
+            model: "gpt-5.5",
+            providerOptions: { service_tier: "fast" },
+          },
+        },
+      } as never)
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: { provider: "codex", cwd: "/repo", model: "gpt-5.5" },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "codex",
+          features: [speedFeature],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    const sentTypes = () => sentMessages().map((message) => message.type);
+    await vi.waitFor(() => expect(sentTypes()).toContain("workspace.create.request"));
+    const created = sentMessages()[sentTypes().indexOf("workspace.create.request")];
+    expect(created).toMatchObject({
+      agent: { config: { featureValues: { service_tier: "fast" } } },
+    });
+  });
+
+  test("a legacy create lists the controls of its own model, whatever a snapshot showed", async () => {
+    const { client, sentMessages, mock } = await connect({});
+    // A Haiku agent has no Fast control; that says nothing about Opus.
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "agent_update",
+        payload: {
+          kind: "upsert",
+          agent: { ...agentSnapshot, provider: "claude", model: "haiku", features: [] },
+        },
+      }),
+    );
+    void client
+      .createAgent({
+        config: {
+          provider: "claude",
+          cwd: "/repo",
+          model: "opus",
+          modeId: "plan",
+          thinkingOptionId: "high",
+          providerOptions: { fast_mode: true, sandbox_mode: "read-only" },
+        },
+      })
+      .catch(() => {});
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(1));
+    const [listing] = sentMessages();
+    expect(listing).toMatchObject({
+      type: "list_provider_features_request",
+      draftConfig: {
+        provider: "claude",
+        cwd: "/repo",
+        model: "opus",
+        modeId: "plan",
+        thinkingOptionId: "high",
+      },
+    });
+    mock.triggerMessage(
+      wrapSessionMessage({
+        type: "list_provider_features_response",
+        payload: {
+          provider: "claude",
+          features: [{ type: "toggle", id: "fast_mode", label: "Fast", value: false }],
+          error: null,
+          fetchedAt: "2026-04-30T00:00:00.000Z",
+          requestId: listing.requestId,
+        },
+      }),
+    );
+    await vi.waitFor(() => expect(sentMessages()).toHaveLength(2));
+    expect(sentMessages()[1].config).toMatchObject({
+      model: "opus",
+      featureValues: { fast_mode: true },
+      providerOptions: { sandbox_mode: "read-only" },
+    });
+  });
+});
diff --git a/packages/client/src/daemon-client.ts b/packages/client/src/daemon-client.ts
index 3aa91f84c7..a401de273f 100644
--- a/packages/client/src/daemon-client.ts
+++ b/packages/client/src/daemon-client.ts
@@ -1,3 +1,9 @@
+import {
+  DiffStreamRouter,
+  DiffSubscriptionError,
+  type DiffCompare,
+  type DiffState,
+} from "./diff/index.js";
 import {
   ChunkedTransport,
   ChunkedTransportProtocolError,
@@ -21,6 +27,7 @@ import {
 } from "./connection/index.js";
 import { CreationClient } from "./creation/index.js";
 import type { CreationSnapshot } from "@getpaseo/protocol/messages";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { z } from "zod";
 import type { SessionEventSubscription } from "@getpaseo/protocol/messages";
 import type { LocalSpeechModel } from "@getpaseo/protocol/speech/rpc-schemas";
@@ -102,6 +109,7 @@ import type {
   WorkspaceSetupStatusResponseMessage,
   ListCommandsResponse,
   ListProviderFeaturesResponseMessage,
+  ProviderControlsListResponseMessage,
   ListProviderModelsResponseMessage,
   ListProviderModesResponseMessage,
   ListAvailableProvidersResponse,
@@ -143,6 +151,7 @@ import type {
   AgentSkillsSaveResult,
 } from "@getpaseo/protocol/messages";
 import type {
+  AgentOptionControl,
   AgentPermissionRequest,
   AgentPermissionResponse,
   AgentPersistenceHandle,
@@ -164,6 +173,11 @@ import {
   FileTransferOpcode,
   TerminalStreamOpcode,
   type FileTransferFrame,
+  assertPluginWireValue,
+  decodePluginFrame,
+  encodePluginInputFrame,
+  isPluginFrameOpcode,
+  PluginFrameOpcode,
 } from "@getpaseo/protocol/binary-frames/index";
 import {
   createRelayE2eeTransportFactory,
@@ -184,6 +198,10 @@ import {
   normalizeProviderSnapshotUpdateMessage,
   normalizeProvidersSnapshotPayload,
 } from "./compat/normalize-provider-models.js";
+import {
+  LegacyProviderOptions,
+  usesLegacyProviderOptions,
+} from "./compat/legacy-provider-options.js";
 import { TerminalStreamRouter, type TerminalStreamEvent } from "./terminal-stream-router.js";
 import type {
   BrowserAutomationExecuteRequest,
@@ -499,16 +517,21 @@ export interface CreateAgentRequestOptions extends AgentConfigOverrides {
   git?: GitSetupOptions;
   worktree?: CreateAgentRequestMessage["worktree"];
   autoArchive?: CreateAgentRequestMessage["autoArchive"];
+  /** Creates a background agent. A workspace this request creates inherits it. */
   background?: CreateAgentRequestMessage["background"];
   /** @deprecated Use createWorkspace({ source, agent, idempotencyKey }); rejected by createAgent. */
   worktreeName?: string;
   requestId?: string;
   labels?: Record<string, string>;
+  /** Plugin-owned data stored on the agent. Needs a host with `entityMetadata`. */
+  metadata?: CreateAgentRequestMessage["metadata"];
 }
 
 export interface CreateWorkspaceRequestOptions {
   source: WorkspaceCreateRequest["source"];
   title?: string;
+  /** Plugin-owned data stored on the workspace. Needs a host with `entityMetadata`. */
+  metadata?: WorkspaceCreateRequest["metadata"];
   /** Workspace discovery visibility; contents retain normal durability. */
   background?: boolean;
   callerAgentId?: string;
@@ -598,6 +621,7 @@ export interface FileUploadInput {
 export type FileUploadResult = FileUploadResponse["payload"];
 type FileDownloadTokenPayload = FileDownloadTokenResponse["payload"];
 type ListProviderFeaturesPayload = ListProviderFeaturesResponseMessage["payload"];
+export type ListProviderControlsPayload = ProviderControlsListResponseMessage["payload"];
 type ListProviderModelsPayload = ListProviderModelsResponseMessage["payload"];
 type ListProviderModesPayload = ListProviderModesResponseMessage["payload"];
 type ListAvailableProvidersPayload = ListAvailableProvidersResponse["payload"];
@@ -624,7 +648,7 @@ type WriteProjectConfigPayload = Extract<
 type ListCommandsPayload = ListCommandsResponse["payload"];
 type ListCommandsDraftConfig = Pick<
   AgentSessionConfig,
-  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "featureValues"
+  "provider" | "cwd" | "modeId" | "model" | "thinkingOptionId" | "featureValues" | "providerOptions"
 >;
 export interface WriteProjectConfigInput {
   repoRoot: string;
@@ -869,6 +893,14 @@ export type WorkspaceLabelDeleteInspectPayload = Extract<
   SessionOutboundMessage,
   { type: "workspace.label.delete.inspect.response" }
 >["payload"];
+export type ProjectSuggestionsPayload = Extract<
+  SessionOutboundMessage,
+  { type: "project.suggestions.response" }
+>["payload"];
+export type ProjectSuggestionsOptions = Omit<
+  Extract<SessionInboundMessage, { type: "project.suggestions.request" }>,
+  "type" | "requestId"
+> & { requestId?: string };
 export type ProjectListPayload = Extract<
   SessionOutboundMessage,
   { type: "project.list.response" }
@@ -1035,6 +1067,9 @@ type CorrelatedResponsePayloads = {
 };
 type CorrelatedResponsePayload<TType extends CorrelatedResponseType> =
   CorrelatedResponsePayloads[TType];
+export type AgentBackgroundWorkListPayload =
+  CorrelatedResponsePayload<"agent.background_work.list.response">;
+export type AgentBackgroundWorkItem = AgentBackgroundWorkListPayload["items"][number];
 
 type PluginCatalogResponseEntry =
   CorrelatedResponsePayload<"plugin.catalog.get.response">["plugins"][number];
@@ -1120,6 +1155,12 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_LIVENESS_TIMEOUT_MS = 5000;
 const LIVENESS_HEARTBEAT_INTERVAL_MS = 10_000;
 const LIVENESS_HEARTBEAT_TIMEOUT_MS = 15_000;
+// Window of each check after the app returns to the foreground. A socket that silently died
+// while the app was suspended stays OPEN and accepts sends, so only inbound frames prove it.
+const FOREGROUND_LIVENESS_TIMEOUT_MS = 5_000;
+// A foreground window whose timer fires this much later than scheduled (wall clock) spanned
+// another suspension or a blocked JS thread, so its silence is no evidence either way.
+const SUSPENDED_WINDOW_SLACK_MS = 2_000;
 const LIVENESS_FAILURE_RECONNECT_THRESHOLD = 2;
 
 /** Default timeout for waiting for connection before sending queued messages */
@@ -1282,12 +1323,27 @@ interface PingProbe {
   reject: (error: Error) => void;
   timeoutHandle: ReturnType<typeof setTimeout>;
   startedAt: number;
-  // Whether a timeout on this ping should be recorded as a liveness failure. Only the
-  // heartbeat sets this; a latency measurement never drives teardown, even when a
-  // heartbeat tick shares (dedupes onto) an in-flight measurement ping.
-  drivesLivenessFailure: boolean;
+  // Wall clock, which keeps running while the OS has JS suspended; perfNow may not.
+  startedAtWallMs: number;
+  receivedActivity: boolean;
+  role: PingProbeRole;
 }
 
+// A latency measurement waits for the next pong, not for a particular probe: the liveness
+// cycle may replace the probe the measurement joined, and a pong that answers an expired window
+// still proves the socket. It settles on a pong, a connection failure, or its own deadline.
+interface PongWaiter {
+  startedAt: number;
+  resolve: (rttMs: number) => void;
+  reject: (error: Error) => void;
+}
+
+// Who started the probe. A "latency" probe never drives teardown, even when a heartbeat
+// tick shares (dedupes onto) it. A "heartbeat" probe runs the regular cadence. A
+// "foreground" probe belongs to the verification cycle that ensureConnected({ verify })
+// runs after the app resumes: short window, immediate second check, reconnect at once.
+type PingProbeRole = "latency" | "heartbeat" | "foreground";
+
 // COMPAT(providerUsageList): added in v0.1.98, remove after 2027-03-26.
 export function supportsUsageReports(features: ServerInfoStatusPayload["features"]): boolean {
   return features?.usageSources === true || features?.providerUsageList === true;
@@ -1356,12 +1412,16 @@ export class DaemonClient {
       ),
     release: async (subscriptionId) => {
       if (!this.isConnected) return;
+      const transport = this.transport;
       try {
         await this.sendCorrelatedSessionRequest({
           message: { type: "subscription.release.request", subscriptionId },
           responseType: "subscription.release.response",
         });
       } catch (error) {
+        // close() rejects in-flight requests after dropping the transport. That failure says
+        // nothing about a live connection, and rethrowing it would abort close() midway.
+        if (this.transport !== transport) return;
         this.disposeTransport(1001, "Subscription release failed");
         this.scheduleReconnect({ reason: "Subscription release failed" });
         throw error;
@@ -1396,6 +1456,20 @@ export class DaemonClient {
   private connectionFailure: Error | undefined;
   private authFailureReasonValue: DaemonAuthFailureReason | null = null;
   private connectionState: ConnectionState = { status: "idle" };
+  private readonly diffStreams = new DiffStreamRouter({
+    modern: (compare) =>
+      this.observe(
+        "diff.subscribe.response",
+        { type: "diff.subscribe.request", ...compare },
+        {
+          validateSnapshot: (payload) => {
+            if (payload.error) throw new DiffSubscriptionError(payload.error);
+          },
+        },
+      ),
+    legacy: (cwd, compare) => this.observeCheckoutDiff(cwd, compare),
+    failed: (error) => this.logger.error({ err: error }, "Diff observer failed"),
+  });
   private readonly terminalStreams = new TerminalStreamRouter();
   private pendingBinaryFileReads = new Map<string, PendingBinaryFileRead>();
   private activeBinaryFileTransfers = new Map<string, BinaryFileTransferState>();
@@ -1425,7 +1499,7 @@ export class DaemonClient {
   private runtimeMetricsInterval: ReturnType<typeof setInterval> | null = null;
   private runtimeMetrics: DaemonClientRuntimeMetrics | null = null;
   private pingProbe: PingProbe | null = null;
-  private connectionVerification: DaemonTransport | null = null;
+  private readonly pongWaiters = new Set<PongWaiter>();
   private livenessHeartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   private lastLivenessRttMs: number | null = null;
   private consecutiveLivenessFailures = 0;
@@ -1575,6 +1649,7 @@ export class DaemonClient {
         send: (frame) => transport.send(frame),
         onFailure: () => transport.close(4003, "Transport send failed"),
         deliver: (frame) => this.handleTransportMessage(frame),
+        onActivity: () => this.recordTransportActivity(),
       });
       this.lastServerInfoMessage = null;
       this.authFailureReasonValue = null;
@@ -1745,10 +1820,12 @@ export class DaemonClient {
     this.disposeTransport(1000, "Client closed");
     this.providerSnapshotUpdates.clear();
     this.clearWaiters(new Error("Daemon client closed"));
+    await this.diffStreams.close();
     await this.owned.close();
     this.creations.close();
     this.rejectPendingSendQueue(new Error("Daemon client closed"));
     this.rejectPingProbe(new Error("Daemon client closed"));
+    this.rejectPongWaiters(new Error("Daemon client closed"));
     this.terminalStreams.clearSlots();
     this.lastServerInfoMessage = null;
     if (this.runtimeMetricsInterval) {
@@ -1771,7 +1848,7 @@ export class DaemonClient {
       this.shouldReconnect = true;
     }
     if (this.connectionState.status === "connected") {
-      if (options?.verify) this.verifyConnection();
+      if (options?.verify) this.verifyConnectionOnForeground();
       return;
     }
     if (this.connectionState.status === "connecting") return;
@@ -1784,26 +1861,9 @@ export class DaemonClient {
     );
   }
 
-  private verifyConnection(): void {
-    const transport = this.transport;
-    if (!transport || this.connectionVerification === transport) return;
-    this.connectionVerification = transport;
-    // A session probe has its own deadline, independent of a heartbeat that the OS
-    // may have suspended. A successful response also proves the session can serve RPCs.
-    void this.ping({ timeoutMs: 3_000 })
-      .catch((error: unknown) => {
-        if (this.transport !== transport || this.connectionState.status !== "connected") return;
-        this.disposeTransport(1001, "Connection verification failed");
-        this.scheduleReconnect({
-          reason: error instanceof Error ? error.message : String(error),
-          event: "CONNECTION_VERIFICATION_FAILED",
-          reasonCode: "liveness_timeout",
-        });
-        this.ensureConnected();
-      })
-      .finally(() => {
-        if (this.connectionVerification === transport) this.connectionVerification = null;
-      });
+  private recordTransportActivity(): void {
+    this.consecutiveLivenessFailures = 0;
+    if (this.pingProbe) this.pingProbe.receivedActivity = true;
   }
 
   requireConnectedHosts(): void {
@@ -1879,18 +1939,34 @@ export class DaemonClient {
       });
     }
   }
-  async openHostLink(channelId: string): Promise<string> {
+  openHostLink(channelId: string): Promise<string>;
+  openHostLink(
+    channelId: string,
+    options: { flowControl: true },
+  ): Promise<{ routeId: string; flowControl: boolean }>;
+  async openHostLink(
+    channelId: string,
+    options?: { flowControl: true },
+  ): Promise<string | { routeId: string; flowControl: boolean }> {
     this.requireConnectedHosts();
     if (this.getLastServerInfoMessage()?.features?.hostMultiplexing !== true)
       throw Object.assign(new Error("Update the destination daemon"), {
         code: "unsupported_capability",
       });
-    return (
-      await this.sendCorrelatedSessionRequest({
-        message: { type: "hosts.link.open.request", channelId },
-        responseType: "hosts.link.open.response",
-      })
-    ).routeId;
+    const response = await this.sendCorrelatedSessionRequest({
+      message: {
+        type: "hosts.link.open.request",
+        channelId,
+        ...(options?.flowControl ? { flowControl: true } : {}),
+      },
+      responseType: "hosts.link.open.response",
+    });
+    return options?.flowControl
+      ? { routeId: response.routeId, flowControl: response.flowControl === true }
+      : response.routeId;
+  }
+  acknowledgeHostLink(routeId: string, sequence: number): Promise<void> {
+    return this.sendSessionMessageStrict({ type: "hosts.link.ack.request", routeId, sequence });
   }
   sendHostFrame(routeId: string, data: string | Uint8Array): Promise<void> {
     if (typeof data === "string") {
@@ -2089,17 +2165,13 @@ export class DaemonClient {
   }
 
   private sendSessionPayload(payload: SessionInboundMessage): Promise<void> {
-    return this.sendJsonMessage(
-      "session",
-      payload.type,
-      { type: "session", message: payload },
-      () => {
-        if (!("requestId" in payload) || typeof payload.requestId !== "string") return;
-        for (const waiter of this.waiters) {
-          if (waiter.requestId === payload.requestId) waiter.submitted = true;
-        }
-      },
-    );
+    const wire = this.legacyProviderOptions()?.prepare(payload) ?? payload;
+    return this.sendJsonMessage("session", payload.type, { type: "session", message: wire }, () => {
+      if (!("requestId" in payload) || typeof payload.requestId !== "string") return;
+      for (const waiter of this.waiters) {
+        if (waiter.requestId === payload.requestId) waiter.submitted = true;
+      }
+    });
   }
 
   private sendTransportFrame(
@@ -2260,6 +2332,8 @@ export class DaemonClient {
     timeout?: number;
     select: (msg: SessionOutboundMessage) => T | null;
     options?: { skipQueue?: boolean };
+    /** Sends the request in another form, such as a binary frame; defaults to `message`. */
+    transmit?: () => Promise<void>;
   }): Promise<T> {
     const wire = this.owned.prepareRequest(params.message);
     const timeout = params.timeout ?? DEFAULT_SESSION_RPC_TIMEOUT_MS;
@@ -2290,7 +2364,9 @@ export class DaemonClient {
     // The response deadline still applies while the transport waits for drain.
     void promise.catch(() => undefined);
     try {
-      const sent = this.sendSessionMessageOrThrow(wire.message);
+      const sent = params.transmit
+        ? params.transmit()
+        : this.sendSessionMessageOrThrow(wire.message);
       const result = await Promise.race([promise, sent.then(() => promise)]);
       if (result.kind === "error") throw result.error;
       return result.value;
@@ -2313,12 +2389,14 @@ export class DaemonClient {
     responseType: TResponseType;
     options?: { skipQueue?: boolean };
     selectPayload?: (payload: CorrelatedResponsePayload<TResponseType>) => TResult | null;
+    transmit?: () => Promise<void>;
   }): Promise<TResult> {
     return this.sendRequest({
       requestId: params.requestId,
       message: params.message,
       timeout: params.timeout,
       options: params.options,
+      ...(params.transmit ? { transmit: params.transmit } : {}),
       select: (msg) => {
         const correlated = msg as CorrelatedResponseMessage;
         if (correlated.type !== params.responseType) {
@@ -2533,34 +2611,41 @@ export class DaemonClient {
 
   measureLatency(params?: { timeoutMs?: number }): Promise<number> {
     const timeoutMs = Math.max(1, params?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
-    return this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: false }).catch((error) => {
-      throw toTimeoutError(error, "Latency measurement", timeoutMs);
-    });
-  }
-
-  private async livenessPing(params?: { timeoutMs?: number }): Promise<number> {
-    const timeoutMs = Math.max(1, params?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
-    try {
-      const rttMs = await this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: true });
-      this.lastLivenessRttMs = rttMs;
-      return rttMs;
-    } catch (error) {
-      throw toTimeoutError(error, "Liveness check", timeoutMs);
-    }
-  }
-
-  private sendPingAwaitRtt(params: {
-    timeoutMs: number;
-    drivesLivenessFailure: boolean;
-  }): Promise<number> {
     if (this.connectionState.status !== "connected" || !this.transport) {
       return Promise.reject(
         new Error(`Transport not connected (status: ${this.connectionState.status})`),
       );
     }
+    const waiter: PongWaiter = { startedAt: perfNow(), resolve: () => {}, reject: () => {} };
+    const pong = new Promise<number>((resolve, reject) => {
+      waiter.resolve = resolve;
+      waiter.reject = reject;
+    });
+    let deadline: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      deadline = setTimeout(() => reject(new PingTimeoutError(timeoutMs)), timeoutMs);
+    });
+    this.pongWaiters.add(waiter);
+    // The probe only puts a ping on the wire; its own outcome is the heartbeat's concern. A
+    // measurement that joins an in-flight ping reports that ping's round trip, so the clock
+    // starts at the send, not at the join.
+    const probe = this.ensurePingProbe({ timeoutMs, role: "latency" });
+    void probe.promise.catch(() => {});
+    waiter.startedAt = probe.startedAt;
+    return Promise.race([pong, timeout])
+      .catch((error) => {
+        throw toTimeoutError(error, "Latency measurement", timeoutMs);
+      })
+      .finally(() => {
+        clearTimeout(deadline);
+        this.pongWaiters.delete(waiter);
+      });
+  }
 
+  // One ping is outstanding at a time; a caller that finds one shares it.
+  private ensurePingProbe(params: { timeoutMs: number; role: PingProbeRole }): PingProbe {
     if (this.pingProbe) {
-      return this.pingProbe.promise;
+      return this.pingProbe;
     }
 
     const startedAt = perfNow();
@@ -2571,23 +2656,36 @@ export class DaemonClient {
       resolveProbe = resolve;
       rejectProbe = reject;
     });
+    const expire = () => {
+      if (this.pingProbe !== probe) return;
+      this.pingProbe = null;
+      const error = new PingTimeoutError(timeoutMs);
+      probe.reject(error);
+      if (
+        probe.role === "foreground" &&
+        Date.now() - probe.startedAtWallMs > timeoutMs + SUSPENDED_WINDOW_SLACK_MS
+      ) {
+        // The app was suspended again inside this window. Discard it, any frame it saw and
+        // the misses before it; the heartbeat tick that owns this probe starts the cycle over.
+        probe.receivedActivity = false;
+        this.consecutiveLivenessFailures = 0;
+        return;
+      }
+      // Keep the deadline fixed so subsequent pings renew the daemon socket lease
+      // during a long download. Progress proves life even when its pong is queued.
+      if (probe.role !== "latency" && !probe.receivedActivity) {
+        this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs), probe.role);
+      }
+    };
     const probe: PingProbe = {
       promise,
       resolve: (value) => resolveProbe?.(value),
       reject: (error) => rejectProbe?.(error),
-      timeoutHandle: setTimeout(() => {
-        if (this.pingProbe !== probe) {
-          return;
-        }
-        this.pingProbe = null;
-        const error = new PingTimeoutError(timeoutMs);
-        probe.reject(error);
-        if (probe.drivesLivenessFailure) {
-          this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs));
-        }
-      }, timeoutMs),
+      timeoutHandle: setTimeout(expire, timeoutMs),
+      receivedActivity: false,
       startedAt,
-      drivesLivenessFailure: params.drivesLivenessFailure,
+      startedAtWallMs: Date.now(),
+      role: params.role,
     };
     this.pingProbe = probe;
 
@@ -2595,7 +2693,8 @@ export class DaemonClient {
       if (this.pingProbe !== probe) return;
       const sendError = error instanceof Error ? error : new Error(String(error));
       this.rejectPingProbe(sendError);
-      if (probe.drivesLivenessFailure) this.recordLivenessFailure(sendError);
+      this.rejectPongWaiters(sendError);
+      if (probe.role !== "latency") this.recordLivenessFailure(sendError, probe.role);
     };
     try {
       void this.sendJsonMessage("ping", "ping", { type: "ping" }).catch(rejectSend);
@@ -2603,7 +2702,7 @@ export class DaemonClient {
       rejectSend(error);
     }
 
-    return promise;
+    return probe;
   }
 
   private startLivenessHeartbeat(): void {
@@ -2626,14 +2725,62 @@ export class DaemonClient {
     }
     this.livenessHeartbeatTimer = setTimeout(() => {
       this.livenessHeartbeatTimer = null;
-      this.livenessPing({ timeoutMs: LIVENESS_HEARTBEAT_TIMEOUT_MS })
-        .catch(() => {})
-        .finally(() => {
-          this.scheduleNextLivenessHeartbeat();
-        });
+      this.tickLivenessHeartbeat();
     }, LIVENESS_HEARTBEAT_INTERVAL_MS);
   }
 
+  /**
+   * The app came back to the foreground. Start a fresh verification cycle: two
+   * FOREGROUND_LIVENESS_TIMEOUT_MS windows back to back, then teardown and an immediate
+   * reconnect. Misses recorded before the app was suspended do not count, and a heartbeat
+   * probe that straddled the suspension measured the suspension, not the socket, so it is
+   * dropped without a miss. Latency measurements wait for the next pong, so replacing the
+   * probe they joined does not fail them.
+   */
+  private verifyConnectionOnForeground(): void {
+    // A cycle already running keeps its deadline and its window count.
+    if (this.pingProbe?.role === "foreground") return;
+    if (this.pingProbe?.role === "heartbeat") {
+      this.rejectPingProbe(new Error("Heartbeat superseded by foreground check"));
+    }
+    // A shared latency probe keeps its deadline, but only frames that arrive from now on count
+    // for this check; a latency probe never reads this flag for itself.
+    if (this.pingProbe) this.pingProbe.receivedActivity = false;
+    this.consecutiveLivenessFailures = 0;
+    this.tickLivenessHeartbeat("foreground");
+  }
+
+  private tickLivenessHeartbeat(check: "heartbeat" | "foreground" = "heartbeat"): void {
+    this.stopLivenessHeartbeat();
+    const transport = this.transport;
+    if (this.connectionState.status !== "connected" || !transport) return;
+    const probe = this.ensurePingProbe({
+      timeoutMs:
+        check === "foreground" ? FOREGROUND_LIVENESS_TIMEOUT_MS : LIVENESS_HEARTBEAT_TIMEOUT_MS,
+      role: check,
+    });
+    void probe.promise
+      .then(
+        (rttMs) => {
+          this.lastLivenessRttMs = rttMs;
+          return true;
+        },
+        () => probe.receivedActivity,
+      )
+      .then((alive) => {
+        // A replaced transport, or a probe that superseded this one, owns the next step.
+        if (this.transport !== transport || this.pingProbe) return;
+        if (!alive && check === "foreground") {
+          // Zero inbound frames in a foreground window: check again now. The second silent
+          // window reaches the threshold inside recordLivenessFailure.
+          this.tickLivenessHeartbeat("foreground");
+          return;
+        }
+        this.scheduleNextLivenessHeartbeat();
+        return;
+      });
+  }
+
   // ============================================================================
   // Agent RPCs (requestId-correlated)
   // ============================================================================
@@ -2641,7 +2788,12 @@ export class DaemonClient {
   private observe<T extends CorrelatedResponseType>(
     responseType: T,
     message: { type: SessionInboundMessage["type"] } & Record<string, unknown>,
-    options?: { requestId?: string; timeout?: number; signal?: AbortSignal },
+    options?: {
+      requestId?: string;
+      timeout?: number;
+      signal?: AbortSignal;
+      validateSnapshot?: (payload: CorrelatedResponsePayload<T>) => void;
+    },
   ): OwnedSubscription<CorrelatedResponsePayload<T>> {
     let resetSource = false;
     return this.owned.observeRequest<CorrelatedResponsePayload<T>>(
@@ -2650,6 +2802,7 @@ export class DaemonClient {
         resetSource = false;
         if (query.type === "workspace.setup.subscribe.request")
           this.requireWorkspaceSetupObservation();
+        if (query.type === "plugin.rpc.subscribe.request") this.requirePluginSubscriptions();
         const requestId = this.createRequestId(options?.requestId);
         const request = SessionInboundMessageSchema.parse({ ...query, requestId });
         try {
@@ -2666,12 +2819,16 @@ export class DaemonClient {
                   requestType: message.type,
                   error: payload.error,
                 });
+              options?.validateSnapshot?.(payload);
               accept(payload);
               return payload;
             },
           });
         } catch (error) {
-          resetSource = !(error instanceof DaemonRpcError) && this.isConnected;
+          resetSource =
+            !(error instanceof DaemonRpcError) &&
+            !(error instanceof DiffSubscriptionError) &&
+            this.isConnected;
           throw error;
         }
       },
@@ -2871,6 +3028,28 @@ export class DaemonClient {
     });
   }
 
+  /** Finds one workspace by id across pages, background ones included when the host has them. */
+  async findWorkspace(
+    workspaceId: string,
+    options?: { requestId?: string },
+  ): Promise<FetchWorkspacesEntry | null> {
+    const filter = this.supportsBackgroundWorkspaces() ? { includeBackground: true } : {};
+    let cursor: string | undefined;
+    let requestId = options?.requestId;
+    do {
+      const result = await this.fetchWorkspaces({
+        requestId,
+        filter,
+        page: { limit: 200, ...(cursor ? { cursor } : {}) },
+      });
+      const match = result.entries.find((entry) => entry.id === workspaceId);
+      if (match) return match;
+      cursor = result.pageInfo.nextCursor ?? undefined;
+      requestId = undefined;
+    } while (cursor);
+    return null;
+  }
+
   listWorkspaceLabels(
     options: {
       sync?: { generation: string; afterSeq: number };
@@ -2976,6 +3155,19 @@ export class DaemonClient {
     });
   }
 
+  /** Repositories the user ran agent sessions in recently, grouped by main checkout. */
+  listProjectSuggestions(options?: ProjectSuggestionsOptions): Promise<ProjectSuggestionsPayload> {
+    return this.sendNamespacedCorrelatedSessionRequest<"project.suggestions.response">({
+      requestId: options?.requestId,
+      message: {
+        type: "project.suggestions.request",
+        ...(options?.providers ? { providers: options.providers } : {}),
+        ...(options?.since ? { since: options.since } : {}),
+        ...(options?.limit ? { limit: options.limit } : {}),
+      },
+    });
+  }
+
   async openProject(cwd: string, requestId?: string): Promise<OpenProjectPayload> {
     return this.sendCorrelatedSessionRequest({
       requestId,
@@ -3249,6 +3441,13 @@ export class DaemonClient {
     legacyWorkspace: (input) => this.createLegacyWorkspace(input, input.requestId),
   });
 
+  // Entity metadata is gated once at the transport boundary.
+  private requireEntityMetadata(): void {
+    if (this.lastServerInfoMessage?.features?.entityMetadata !== true) {
+      throw new Error("Update the host to use metadata.");
+    }
+  }
+
   // Background workspaces are gated once at the transport boundary.
   private requireBackgroundWorkspaces(): void {
     if (this.lastServerInfoMessage?.features?.backgroundWorkspaces !== true) {
@@ -3260,21 +3459,63 @@ export class DaemonClient {
     return this.lastServerInfoMessage?.features?.backgroundWorkspaces === true;
   }
 
+  // Background on a request that creates its workspace predates background agents: older hosts
+  // apply it to the new workspace. Placing a background agent in an existing workspace, or
+  // under a caller, needs a host that knows background agents.
+  private requireBackgroundCreation(options: CreateAgentRequestOptions): void {
+    if (options.workspaceId === undefined && options.callerAgentId === undefined) {
+      this.requireBackgroundWorkspaces();
+    } else if (this.lastServerInfoMessage?.features?.backgroundAgents !== true) {
+      throw new Error("Update the host to use background agents.");
+    }
+  }
+
   async createAgent(options: CreateAgentRequestOptions): Promise<AgentSnapshotPayload> {
     if (options.git !== undefined || options.worktreeName !== undefined) {
       throw new Error(
         "Legacy git/worktreeName agent placement was removed. Use createWorkspace({ source, agent, idempotencyKey }) or create a workspace first and pass workspaceId.",
       );
     }
-    if (options.background !== undefined) this.requireBackgroundWorkspaces();
+    if (options.background !== undefined) this.requireBackgroundCreation(options);
+    if (options.metadata !== undefined) this.requireEntityMetadata();
+    const config = resolveAgentConfig(options);
     const result = await this.creations.createAgent({
       ...options,
-      config: resolveAgentConfig(options),
+      config: this.carriesLegacyOptions(config)
+        ? await this.routeLegacyCreateConfig(config)
+        : config,
     });
     if (result.error || !result.agent) throw new Error(result.error ?? "Agent creation failed");
     return result.agent;
   }
 
+  /**
+   * A legacy daemon reads control options as `featureValues`, and which options are controls
+   * depends on the config (Claude's differ by model), so a create that carries options first lists
+   * the controls for its own config. Callers never prime anything.
+   */
+  private carriesLegacyOptions(config: AgentSessionConfig): boolean {
+    return (
+      this.legacyProviderOptions() !== null && Object.keys(config.providerOptions ?? {}).length > 0
+    );
+  }
+
+  private async routeLegacyCreateConfig(config: AgentSessionConfig): Promise<AgentSessionConfig> {
+    const payload = await this.listProviderFeatures({
+      provider: config.provider,
+      cwd: config.cwd || "~",
+      ...(config.modeId ? { modeId: config.modeId } : {}),
+      ...(config.model ? { model: config.model } : {}),
+      ...(config.thinkingOptionId ? { thinkingOptionId: config.thinkingOptionId } : {}),
+      featureValues: config.providerOptions,
+    });
+    if (payload.error) throw new Error(payload.error);
+    return this.legacyOptions.routeCreateConfig(
+      config,
+      new Set((payload.features ?? []).map((feature) => feature.id)),
+    );
+  }
+
   private async createLegacyAgent(
     options: CreateAgentRequestOptions,
   ): Promise<AgentSnapshotPayload> {
@@ -3473,6 +3714,42 @@ export class DaemonClient {
     return { removedWorkspaceIds: payload.removedWorkspaceIds };
   }
 
+  /** Top-level keys replace; `null` removes the key. Resolves to the agent's metadata afterwards. */
+  async setAgentMetadata(
+    agentId: string,
+    patch: Record<string, JsonValue>,
+    requestId?: string,
+  ): Promise<Record<string, JsonValue>> {
+    this.requireEntityMetadata();
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"agent.metadata.update.response">({
+        requestId,
+        message: { type: "agent.metadata.update.request", agentId, patch },
+      });
+    if (!payload.accepted || !payload.metadata) {
+      throw new Error(payload.error ?? "setAgentMetadata rejected");
+    }
+    return payload.metadata;
+  }
+
+  /** Top-level keys replace; `null` removes the key. Resolves to the workspace's metadata afterwards. */
+  async setWorkspaceMetadata(
+    workspaceId: string,
+    patch: Record<string, JsonValue>,
+    requestId?: string,
+  ): Promise<Record<string, JsonValue>> {
+    this.requireEntityMetadata();
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"workspace.metadata.update.response">({
+        requestId,
+        message: { type: "workspace.metadata.update.request", workspaceId, patch },
+      });
+    if (!payload.accepted || !payload.metadata) {
+      throw new Error(payload.error ?? "setWorkspaceMetadata rejected");
+    }
+    return payload.metadata;
+  }
+
   async setWorkspaceTitle(
     workspaceId: string,
     title: string | null,
@@ -3513,6 +3790,22 @@ export class DaemonClient {
     return { pinnedAt: payload.pinnedAt };
   }
 
+  async setWorkspaceBaseBranch(options: {
+    workspaceId: string;
+    baseRef: string;
+    requestId?: string;
+  }): Promise<{ baseRef: string | null }> {
+    const { requestId, workspaceId, baseRef } = options;
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"workspace.base_branch.set.response">({
+        requestId,
+        message: { type: "workspace.base_branch.set.request", workspaceId, baseRef },
+      });
+    if (!payload.accepted)
+      throw new Error(payload.error ?? "Changing the workspace base branch failed");
+    return { baseRef: payload.baseRef };
+  }
+
   async inspectWorkspaceRecovery(
     workspaceId: string,
     requestId?: string,
@@ -3543,6 +3836,23 @@ export class DaemonClient {
     }
   }
 
+  /** Rejects when the host could not put the workspace back; an old host has no such RPC. */
+  async undoWorkspaceArchive(workspaceId: string, requestId?: string): Promise<void> {
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"workspace.archive.undo.response">({
+        requestId,
+        message: {
+          type: "workspace.archive.undo.request",
+          workspaceId,
+        },
+        // Undoing a finished worktree archive recreates the worktree, like recovery does.
+        timeout: 150_000,
+      });
+    if (!payload.accepted) {
+      throw new Error(payload.error ?? "The host could not undo the workspace archive");
+    }
+  }
+
   async resumeAgent(
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
@@ -3767,6 +4077,58 @@ export class DaemonClient {
     return payload;
   }
 
+  async listAgentBackgroundWork(
+    agentId: string,
+    options: { requestId?: string; timeout?: number } = {},
+  ): Promise<AgentBackgroundWorkItem[]> {
+    this.assertAgentBackgroundWorkSupported();
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"agent.background_work.list.response">({
+        requestId: options.requestId,
+        timeout: options.timeout,
+        message: { type: "agent.background_work.list.request", agentId },
+      });
+    if (payload.error) throw new Error(payload.error);
+    return payload.items;
+  }
+
+  async stopAgentBackgroundWork(
+    agentId: string,
+    item: AgentBackgroundWorkItem,
+    options: { requestId?: string; timeout?: number } = {},
+  ): Promise<void> {
+    // COMPAT(agentBackgroundWorkStop): added after v0.15.0, remove after 2027-05-03.
+    if (this.lastServerInfoMessage?.features?.agentBackgroundWorkStop !== true)
+      throw new Error("Update the host to stop background work.");
+    if (!item.canStop || !item.stopToken) throw new Error("Background work cannot be stopped.");
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"agent.background_work.stop.response">({
+        requestId: options.requestId,
+        timeout: options.timeout ?? 30000,
+        message: {
+          type: "agent.background_work.stop.request",
+          agentId,
+          itemId: item.id,
+          stopToken: item.stopToken,
+        },
+      });
+    if (payload.error) throw new Error(payload.error);
+  }
+
+  observeAgentBackgroundWork(
+    options: { signal?: AbortSignal } = {},
+  ): OwnedSubscription<CorrelatedResponsePayload<"session.events.set_subscription.response">> {
+    this.assertAgentBackgroundWorkSupported();
+    return this.observeEvents(["agent.background_work.update"], options);
+  }
+
+  private assertAgentBackgroundWorkSupported(): void {
+    // COMPAT(agentBackgroundWork): added after v0.11.0-beta.5, remove gate after 2027-04-06.
+    if (this.lastServerInfoMessage?.features?.agentBackgroundWork !== true) {
+      throw new Error("Update the host to see an agent's background work.");
+    }
+  }
+
   async fetchProviderSubagentTimeline(
     parentAgentId: string,
     subagentId: string,
@@ -3805,11 +4167,23 @@ export class DaemonClient {
 
   observeTimeline(
     agentIds: string[],
-    options?: { signal?: AbortSignal },
+    options?: {
+      signal?: AbortSignal;
+      /** The caller's position per chat; the response answers whether each is at the head. */
+      cursors?: Record<string, { epoch: string; seq: number }>;
+    },
   ): OwnedSubscription<CorrelatedResponsePayload<"agent.timeline.set_subscription.response">> {
     return this.observe(
       "agent.timeline.set_subscription.response",
-      { type: "agent.timeline.set_subscription.request", agentIds },
+      {
+        type: "agent.timeline.set_subscription.request",
+        agentIds,
+        // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+        ...(options?.cursors &&
+        this.lastServerInfoMessage?.features?.timelineFreshnessCheck === true
+          ? { cursors: options.cursors }
+          : {}),
+      },
       options,
     );
   }
@@ -4065,6 +4439,41 @@ export class DaemonClient {
     }
   }
 
+  /**
+   * Changes the agent's own provider options: top-level keys replace, `null` removes the key.
+   * A daemon without `providerOptionControls` takes each key as a feature write.
+   */
+  async setAgentOptions(
+    agentId: string,
+    patch: Record<string, unknown>,
+  ): Promise<AgentProviderNotice | null> {
+    const legacy = this.legacyProviderOptions();
+    if (legacy) {
+      // COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01.
+      const pending = this.legacyResetControls(agentId, patch);
+      const controls = pending ? await pending : [];
+      for (const [featureId, value] of legacy.featureWrites(patch, controls)) {
+        await this.setAgentFeature(agentId, featureId, value);
+      }
+      return null;
+    }
+    return this.applyAgentConfig(agentId, { options: patch });
+  }
+
+  /**
+   * COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01.
+   * A reset (`null`) on a daemon without `providerOptionControls` is written as the value its
+   * control resets to, which takes the agent's controls. Without a reset nothing is fetched, so
+   * the write is not delayed.
+   */
+  private legacyResetControls(
+    agentId: string,
+    patch: Record<string, unknown>,
+  ): Promise<AgentOptionControl[]> | null {
+    if (!Object.values(patch).includes(null)) return null;
+    return this.fetchAgent(agentId).then((result) => result?.agent.controls ?? []);
+  }
+
   async setAgentThinkingOption(
     agentId: string,
     thinkingOptionId: string | null,
@@ -4107,11 +4516,18 @@ export class DaemonClient {
     agentId: string,
     config: AgentConfigApply,
   ): Promise<AgentProviderNotice | null> {
+    let wireConfig = config;
+    const legacy = this.legacyProviderOptions();
+    if (legacy && config.options) {
+      // COMPAT(providerOptionControls): added in v0.15.0, remove after 2027-05-01.
+      const pending = this.legacyResetControls(agentId, config.options);
+      wireConfig = legacy.featureValuesConfig(config, pending ? await pending : []);
+    }
     const requestId = this.createRequestId();
     const message = SessionInboundMessageSchema.parse({
       type: "agent.config.apply.request",
       agentId,
-      config,
+      config: wireConfig,
       requestId,
     });
     const payload = await this.sendRequest({
@@ -4575,6 +4991,26 @@ export class DaemonClient {
     });
   }
 
+  observeDiff(compare: DiffCompare): OwnedSubscription<DiffState> {
+    return this.diffStreams.observe(compare);
+  }
+
+  async readDiff(compare: DiffCompare): Promise<DiffState> {
+    const observation = this.observeDiff(compare);
+    try {
+      return await new Promise<DiffState>((resolve) => {
+        observation.subscribe({
+          snapshot: (state) => {
+            if (state.phase !== "loading") resolve(state);
+          },
+          update: () => {},
+        });
+      });
+    } finally {
+      await observation.release();
+    }
+  }
+
   observeCheckoutDiff(
     cwd: string,
     compare: { mode: "uncommitted" | "base" | "all"; baseRef?: string; ignoreWhitespace?: boolean },
@@ -5008,12 +5444,16 @@ export class DaemonClient {
     if (input.background !== undefined || input.callerAgentId) this.requireBackgroundWorkspaces();
     if (input.agent?.background !== undefined)
       throw new Error("Configure background on the workspace, not its initial agent.");
+    if (input.metadata !== undefined || input.agent?.metadata !== undefined)
+      this.requireEntityMetadata();
+    let agentConfig = input.agent ? resolveAgentConfig(input.agent) : undefined;
+    if (agentConfig && this.carriesLegacyOptions(agentConfig)) {
+      agentConfig = await this.routeLegacyCreateConfig(agentConfig);
+    }
     const result = await this.creations.createWorkspace({
       ...input,
       requestId: resolvedRequestId,
-      ...(input.agent
-        ? { agent: { ...input.agent, config: resolveAgentConfig(input.agent) } }
-        : {}),
+      ...(input.agent && agentConfig ? { agent: { ...input.agent, config: agentConfig } } : {}),
     });
     return {
       ...result,
@@ -5065,7 +5505,7 @@ export class DaemonClient {
   }
 
   async getBranchSuggestions(
-    options: { cwd: string; query?: string; limit?: number },
+    options: { cwd: string; query?: string; limit?: number; refMode?: "exact" },
     requestId?: string,
   ): Promise<BranchSuggestionsPayload> {
     return this.sendCorrelatedSessionRequest({
@@ -5075,6 +5515,7 @@ export class DaemonClient {
         cwd: options.cwd,
         query: options.query,
         limit: options.limit,
+        refMode: options.refMode,
       },
       responseType: "branch_suggestions_response",
     });
@@ -5494,6 +5935,36 @@ export class DaemonClient {
     });
   }
 
+  /**
+   * The controls a draft agent would show and the options it would run with: `config.json`
+   * defaults merged with the draft's own `providerOptions`, resolved by the daemon.
+   */
+  async listProviderControls(
+    draftConfig: ListCommandsDraftConfig,
+    options?: { requestId?: string },
+  ): Promise<ListProviderControlsPayload> {
+    const legacy = this.legacyProviderOptions();
+    if (legacy) {
+      const { providerOptions, ...rest } = draftConfig;
+      const payload = await this.listProviderFeatures(
+        {
+          ...rest,
+          // A legacy daemon reads the options it exposes as features, whatever the others are.
+          ...(providerOptions ? { featureValues: providerOptions } : {}),
+        },
+        options,
+      );
+      return legacy.controlsResponse(payload);
+    }
+    return this.sendCorrelatedSessionRequest({
+      requestId: options?.requestId,
+      message: { type: "provider.controls.list.request", draftConfig },
+      responseType: "provider.controls.list.response",
+      timeout: 90000,
+    });
+  }
+
+  /** @deprecated Use `listProviderControls`. */
   async listProviderFeatures(
     draftConfig: ListCommandsDraftConfig,
     options?: { requestId?: string },
@@ -6197,22 +6668,59 @@ export class DaemonClient {
     return payload.plugin;
   }
 
+  /**
+   * A `Uint8Array` input or output crosses the wire as a binary frame. Any other value is JSON and
+   * must not contain a `Uint8Array`.
+   */
   async invokePluginRpc(pluginId: string, method: string, input: unknown): Promise<unknown> {
+    assertPluginWireValue(input, "input");
     const requestId = this.createRequestId();
-    const payload = await this.sendCorrelatedSessionRequest({
-      requestId,
-      message: {
-        type: "plugin.rpc.invoke.request",
+    if (!(input instanceof Uint8Array)) {
+      const payload = await this.sendCorrelatedSessionRequest({
         requestId,
-        pluginId,
-        method,
-        input,
-      },
+        message: {
+          type: "plugin.rpc.invoke.request",
+          requestId,
+          pluginId,
+          method,
+          input,
+        },
+        responseType: "plugin.rpc.invoke.response",
+      });
+      return payload.output;
+    }
+    this.requirePluginSubscriptions();
+    const frame = encodePluginInputFrame({ requestId, pluginId, method, payload: input });
+    const payload = await this.sendCorrelatedRequest({
+      requestId,
+      message: { type: "plugin.rpc.invoke.request", requestId, pluginId, method, input: null },
       responseType: "plugin.rpc.invoke.response",
+      options: { skipQueue: true },
+      transmit: () => this.sendBinaryFrame(frame),
     });
     return payload.output;
   }
 
+  /** One subscription to a plugin subscription handler; events arrive as updates and binary. */
+  observePluginRpc(
+    pluginId: string,
+    method: string,
+    input: unknown,
+    options?: { signal?: AbortSignal },
+  ): OwnedSubscription<CorrelatedResponsePayload<"plugin.rpc.subscribe.response">> {
+    assertPluginWireValue(input, "input");
+    return this.observe(
+      "plugin.rpc.subscribe.response",
+      { type: "plugin.rpc.subscribe.request", pluginId, method, input },
+      options,
+    );
+  }
+
+  private requirePluginSubscriptions(): void {
+    if (this.lastServerInfoMessage?.features?.pluginSubscriptions !== true)
+      throw new Error("Update the host to use plugin subscriptions and binary plugin RPC");
+  }
+
   async respondToPermissionAndWait(
     agentId: string,
     requestId: string,
@@ -6383,10 +6891,16 @@ export class DaemonClient {
   // ============================================================================
 
   observeTerminals(input: {
-    cwd: string;
+    cwd?: string;
     workspaceId?: string;
     signal?: AbortSignal;
   }): OwnedSubscription<CorrelatedResponsePayload<"terminals_changed">> {
+    // COMPAT(terminalCollection): added in v0.16, remove after 2027-06.
+    if (
+      input.cwd === undefined &&
+      this.getLastServerInfoMessage()?.features?.terminalCollection !== true
+    )
+      throw new Error("Update the host to list terminals across workspaces.");
     const { signal, ...query } = input;
     return this.observe(
       "terminals_changed",
@@ -6747,6 +7261,14 @@ export class DaemonClient {
     return requestId ?? crypto.randomUUID();
   }
 
+  private readonly legacyOptions = new LegacyProviderOptions();
+
+  /** The translation for a daemon without `providerOptionControls`; null for a current one. */
+  private legacyProviderOptions(): LegacyProviderOptions | null {
+    const info = this.lastServerInfoMessage;
+    return info && usesLegacyProviderOptions(info) ? this.legacyOptions : null;
+  }
+
   getLastServerInfoMessage(): ServerInfoStatusPayload | null {
     return this.lastServerInfoMessage;
   }
@@ -6813,6 +7335,7 @@ export class DaemonClient {
     this.chunkedTransport?.close();
     this.chunkedTransport = null;
     this.owned.disconnected();
+    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
     this.stopLivenessHeartbeat();
     this.cleanupTransport();
@@ -6945,6 +7468,7 @@ export class DaemonClient {
         messageType: "pong",
       });
       this.resolvePingProbe();
+      this.resolvePongWaiters();
       this.runtimeMetrics?.recordMessage("pong", bytes, perfNow() - startMs);
       return;
     }
@@ -6975,6 +7499,23 @@ export class DaemonClient {
     }
   }
 
+  private handlePluginFrame(rawBytes: Uint8Array): void {
+    const frame = decodePluginFrame(rawBytes);
+    this.consecutiveLivenessFailures = 0;
+    this.runtimeMetrics?.recordBinaryFrame("plugin", rawBytes.byteLength, 0);
+    if (frame?.opcode === PluginFrameOpcode.Event) {
+      this.owned.receiveBinary(frame.subscriptionId, frame.payload);
+      return;
+    }
+    if (frame?.opcode === PluginFrameOpcode.Output) {
+      // The binary form of plugin.rpc.invoke.response.
+      this.resolveWaiters({
+        type: "plugin.rpc.invoke.response",
+        payload: { requestId: frame.requestId, output: frame.payload },
+      });
+    }
+  }
+
   private tryHandleBinaryFrame(rawBytes: Uint8Array): boolean {
     const hostFrame = decodeHostRouteFrame(rawBytes);
     if (rawBytes[0] === HOST_ROUTE_OPCODE && !hostFrame) {
@@ -6986,6 +7527,14 @@ export class DaemonClient {
       for (const handler of this.hostFrameListeners) handler(hostFrame);
       return true;
     }
+    if (rawBytes[0] >= 0x40 && rawBytes[0] <= 0x4f) {
+      this.diffStreams.receive(rawBytes);
+      return true;
+    }
+    if (isPluginFrameOpcode(rawBytes[0])) {
+      this.handlePluginFrame(rawBytes);
+      return true;
+    }
     const fileFrame = decodeFileTransferFrame(rawBytes);
     if (fileFrame) {
       this.traceInstant("paseo.ws.message.inbound", {
@@ -7169,6 +7718,8 @@ export class DaemonClient {
     reason?: string;
     event?: string;
     reasonCode?: string;
+    // Attempt now instead of after the backoff delay. Failures of that attempt back off as usual.
+    immediate?: boolean;
   }): void {
     if (this.reconnectTimeout) {
       clearTimeout(this.reconnectTimeout);
@@ -7182,6 +7733,7 @@ export class DaemonClient {
     }
 
     this.owned.disconnected();
+    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
 
     // Clear all pending waiters and queued sends since the connection was lost
@@ -7198,6 +7750,7 @@ export class DaemonClient {
     this.clearWaiters(connectionError, true);
     this.rejectPendingSendQueue(connectionError);
     this.rejectPingProbe(connectionError);
+    this.rejectPongWaiters(connectionError);
     this.terminalStreams.clearSlots();
     this.lastServerInfoMessage = null;
 
@@ -7217,6 +7770,10 @@ export class DaemonClient {
       return;
     }
 
+    if (input?.immediate) {
+      void this.attemptConnect();
+      return;
+    }
     this.armReconnectTimer();
   }
 
@@ -7291,7 +7848,18 @@ export class DaemonClient {
     probe.reject(error);
   }
 
-  private recordLivenessFailure(error: Error): void {
+  private resolvePongWaiters(): void {
+    const now = perfNow();
+    for (const waiter of this.pongWaiters) waiter.resolve(now - waiter.startedAt);
+    this.pongWaiters.clear();
+  }
+
+  private rejectPongWaiters(error: Error): void {
+    for (const waiter of this.pongWaiters) waiter.reject(error);
+    this.pongWaiters.clear();
+  }
+
+  private recordLivenessFailure(error: Error, role: PingProbeRole): void {
     this.consecutiveLivenessFailures += 1;
     if (this.consecutiveLivenessFailures < LIVENESS_FAILURE_RECONNECT_THRESHOLD) {
       return;
@@ -7303,11 +7871,14 @@ export class DaemonClient {
       reason: error.message,
       event: "LIVENESS_TIMEOUT",
       reasonCode: "liveness_timeout",
+      // The foreground cycle already waited two windows; the user is looking at the app.
+      immediate: role === "foreground",
     });
   }
 
   private handleSessionMessage(msg: SessionOutboundMessage): void {
     msg = this.owned.normalize(msg);
+    msg = this.legacyProviderOptions()?.normalize(msg) ?? msg;
     if (
       msg.type === "providers_snapshot_update" &&
       this.config.providerSnapshots !== "wire" &&
@@ -7341,6 +7912,7 @@ export class DaemonClient {
           this.reconnectAttempt = 0;
           this.updateConnectionState({ status: "connected" }, { event: "HELLO_SERVER_INFO" });
           this.startLivenessHeartbeat();
+          this.diffStreams.connected(serverInfo.features?.diffSubscription === true);
           this.owned.restore(serverInfo, {
             ...DEFAULT_CLIENT_CAPABILITIES,
             ...this.config.capabilities,
@@ -7596,6 +8168,7 @@ function resolveAgentConfig(options: CreateAgentRequestOptions): AgentSessionCon
     worktreeName: _worktreeName,
     requestId: _requestId,
     labels: _labels,
+    metadata: _metadata,
     ...overrides
   } = options;
 
@@ -7617,3 +8190,5 @@ function resolveAgentConfig(options: CreateAgentRequestOptions): AgentSessionCon
     cwd: merged.cwd,
   };
 }
+
+export type { DiffCompare, DiffState, DiffEntry, ResolvedShas } from "./diff/index.js";
diff --git a/packages/client/src/diff/client.test.ts b/packages/client/src/diff/client.test.ts
new file mode 100644
index 0000000000..04f06d227f
--- /dev/null
+++ b/packages/client/src/diff/client.test.ts
@@ -0,0 +1,210 @@
+import { expect, test } from "vitest";
+import { DaemonClient, type DaemonTransport } from "../daemon-client.js";
+import {
+  encodeDiffFrame,
+  DiffOpcode,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { DiffState } from "./index.js";
+function socket() {
+  let message: (data: unknown, binary?: boolean) => void = () => {};
+  let open: () => void = () => {};
+  let close: (event?: unknown) => void = () => {};
+  const sent: Record<string, unknown>[] = [];
+  const transport: DaemonTransport = {
+    send: (data) => {
+      if (typeof data === "string") {
+        const value = JSON.parse(data);
+        if (value.type === "session") {
+          sent.push(value.message);
+          if (value.message.type === "subscription.release.request")
+            queueMicrotask(() =>
+              receive({
+                type: "subscription.release.response",
+                payload: {
+                  requestId: value.message.requestId,
+                  subscriptionId: value.message.subscriptionId,
+                  released: true,
+                },
+              }),
+            );
+        }
+      }
+    },
+    close: () => {},
+    onMessage: (handler) => {
+      message = handler;
+      return () => {};
+    },
+    onOpen: (handler) => {
+      open = handler;
+      return () => {};
+    },
+    onClose: (handler) => {
+      close = handler;
+      return () => {};
+    },
+    onError: () => () => {},
+  };
+  const receive = (value: unknown) =>
+    message(JSON.stringify({ type: "session", message: value }), false);
+  return {
+    transport,
+    sent,
+    receive,
+    raw: (bytes: Uint8Array) => message(bytes, true),
+    frame: (frame: DiffFrame) => message(encodeDiffFrame(frame), true),
+    disconnect: () => close({ code: 1001 }),
+    open: (modern = true) => {
+      open();
+      receive({
+        type: "status",
+        payload: {
+          status: "server_info",
+          serverId: "srv_test",
+          hostname: null,
+          version: null,
+          features: { ownedSubscriptions: true, diffSubscription: modern, checkoutDiffAll: true },
+        },
+      });
+    },
+  };
+}
+const compare = {
+  cwd: "/repo",
+  base: { kind: "rev", rev: "HEAD" },
+  head: { kind: "worktree" },
+} as const;
+const begin: DiffFrame = {
+  opcode: DiffOpcode.Begin,
+  slot: 3,
+  revision: 1,
+  baseRevision: 0,
+  baseSha: "a",
+  headSha: "b",
+  mergeBaseSha: "",
+  entries: [],
+};
+const end: DiffFrame = {
+  opcode: DiffOpcode.End,
+  slot: 3,
+  revision: 1,
+  diffTooLarge: false,
+  omitted: [],
+  error: null,
+};
+async function setup(modern = true) {
+  const wire = socket();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "diff-test",
+    transportFactory: () => wire.transport,
+    reconnect: { enabled: false },
+  });
+  const connecting = client.connect();
+  wire.open(modern);
+  await connecting;
+  return { wire, client };
+}
+function acknowledge(wire: ReturnType<typeof socket>, ordinal = 1) {
+  const request = wire.sent.findLast((value) => value.type === "diff.subscribe.request");
+  wire.receive({
+    type: "diff.subscribe.response",
+    payload: {
+      requestId: request?.requestId,
+      subscriptionId: `diff-${ordinal}`,
+      slot: 3,
+      error: null,
+    },
+  });
+}
+test("attaches binary routing during handshake and resubscribes with a full state on reconnect", async () => {
+  const { wire, client } = await setup();
+  try {
+    const states: DiffState[] = [];
+    const observation = client.observeDiff(compare);
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    acknowledge(wire);
+    wire.frame(begin);
+    wire.frame(end);
+    expect(states.map((state) => state.phase)).toEqual(["loading", "ready"]);
+    wire.disconnect();
+    const connected = client.connect();
+    wire.open();
+    await connected;
+    acknowledge(wire, 2);
+    wire.frame(begin);
+    wire.frame(end);
+    expect(states.map((state) => state.phase)).toEqual(["loading", "ready", "loading", "ready"]);
+    await observation.release();
+  } finally {
+    await client.close();
+  }
+});
+test("an unknown version fails only its subscription and readDiff resolves typed subscribe errors", async () => {
+  const { wire, client } = await setup();
+  try {
+    const observation = client.observeDiff(compare);
+    const states: DiffState[] = [];
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    acknowledge(wire);
+    const malformed = { ...begin, slot: 3 };
+    const bytes = encodeDiffFrame(malformed);
+    bytes[2] = 255;
+    wire.raw(bytes);
+    expect(states.at(-1)).toMatchObject({ phase: "error", error: { code: "UNKNOWN" } });
+    const next = client.readDiff(compare);
+    const request = wire.sent.findLast((value) => value.type === "diff.subscribe.request");
+    wire.receive({
+      type: "diff.subscribe.response",
+      payload: {
+        requestId: request?.requestId,
+        subscriptionId: "",
+        slot: 0,
+        error: { code: "INVALID_COMPARE", message: "invalid" },
+      },
+    });
+    expect(await next).toMatchObject({ phase: "error", error: { code: "INVALID_COMPARE" } });
+    expect(client.isConnected).toBe(true);
+    await observation.release();
+  } finally {
+    await client.close();
+  }
+});
+test.each(["uncommitted", "base", "all"] as const)(
+  "old hosts serve the %s comparison through the tagged compatibility route",
+  async (mode) => {
+    const { wire, client } = await setup(false);
+    try {
+      const comparison =
+        mode === "uncommitted"
+          ? compare
+          : {
+              ...compare,
+              base: { kind: "rev", rev: "refs/tags/v1" } as const,
+              head: mode === "base" ? ({ kind: "rev", rev: "HEAD" } as const) : compare.head,
+              mergeBase: true,
+            };
+      const result = client.readDiff(comparison);
+      const request = wire.sent.find((value) => value.type === "subscribe_checkout_diff_request");
+      expect(request?.compare).toMatchObject({ mode });
+      wire.receive({
+        type: "subscribe_checkout_diff_response",
+        payload: {
+          requestId: request?.requestId,
+          subscriptionId: "legacy",
+          cwd: "/repo",
+          files: [],
+          error: null,
+        },
+      });
+      wire.receive({
+        type: "checkout_diff_update",
+        payload: { subscriptionId: "legacy", cwd: "/repo", files: [], error: null },
+      });
+      expect(await result).toMatchObject({ phase: "ready", files: [] });
+    } finally {
+      await client.close();
+    }
+  },
+);
diff --git a/packages/client/src/diff/index.ts b/packages/client/src/diff/index.ts
new file mode 100644
index 0000000000..31fe4394a6
--- /dev/null
+++ b/packages/client/src/diff/index.ts
@@ -0,0 +1,246 @@
+import {
+  decodeDiffFrame,
+  type DiffEntry as WireEntry,
+  type DiffBegin,
+} from "@getpaseo/protocol/binary-frames/index";
+import type {
+  DiffSubscribeRequest,
+  SubscribeCheckoutDiffRequest,
+  DiffError,
+  DiffSubscribeResponse,
+  SubscribeCheckoutDiffResponse,
+  ParsedDiffFile,
+} from "@getpaseo/protocol/messages";
+import type { OwnedSubscription, SubscriptionObserver } from "../connection/index.js";
+import { DiffStream } from "./stream.js";
+export type { DiffEndpoint } from "@getpaseo/protocol/messages";
+export type DiffCompare = Omit<DiffSubscribeRequest, "type" | "requestId">;
+
+export type DiffEntry = Omit<WireEntry, "body">;
+export type ResolvedShas = Pick<DiffBegin, "baseSha" | "headSha" | "mergeBaseSha">;
+
+export type DiffState =
+  | { phase: "loading"; revision: number; entries: DiffEntry[] }
+  | {
+      phase: "ready";
+      revision: number;
+      resolved: ResolvedShas;
+      diffTooLarge: boolean;
+      files: ParsedDiffFile[];
+    }
+  | { phase: "error"; revision: number; error: DiffError };
+type LegacyCompare = SubscribeCheckoutDiffRequest["compare"];
+
+interface Port {
+  modern(compare: DiffCompare): OwnedSubscription<DiffSubscribeResponse["payload"]>;
+  legacy(
+    cwd: string,
+    compare: LegacyCompare,
+  ): OwnedSubscription<SubscribeCheckoutDiffResponse["payload"]>;
+  failed(error: unknown): void;
+}
+export class DiffSubscriptionError extends Error {
+  constructor(readonly detail: DiffError) {
+    super(detail.message);
+  }
+}
+interface Registration {
+  start(modern: boolean): void;
+  disconnected(): void;
+  release(): Promise<void>;
+}
+/** Capability selection, slot ownership and reconnect belong to this domain. */
+export class DiffStreamRouter {
+  private registrations = new Set<Registration>();
+  private slots = new Map<number, { receive(bytes: Uint8Array): void }>();
+  private mode: boolean | null = null;
+  constructor(private port: Port) {}
+  connected(modern: boolean): void {
+    this.mode = modern;
+    for (const registration of this.registrations) registration.start(modern);
+  }
+  disconnected(): void {
+    this.mode = null;
+    this.slots.clear();
+    for (const registration of this.registrations) registration.disconnected();
+  }
+  async close(): Promise<void> {
+    await Promise.all([...this.registrations].map((registration) => registration.release()));
+  }
+  receive(bytes: Uint8Array): void {
+    const owner = this.slots.get(bytes[1]);
+    owner?.receive(bytes);
+  }
+  private releaseBackend(backend: OwnedSubscription<unknown> | null): void {
+    void backend?.release().catch(this.port.failed);
+  }
+  observe(compare: DiffCompare): OwnedSubscription<DiffState> {
+    let backend: OwnedSubscription<unknown> | null = null;
+    let state: (DiffState & { subscriptionId: string }) | null = null;
+    let slot: number | null = null;
+    let released = false;
+    let generation = 0;
+    let stream: DiffStream;
+    const observers = new Set<SubscriptionObserver<DiffState & { subscriptionId: string }>>();
+    let resolve!: (state: DiffState & { subscriptionId: string }) => void;
+    const ready = new Promise<DiffState & { subscriptionId: string }>((accept) => {
+      resolve = accept;
+    });
+    const publish = (value: DiffState) => {
+      if (released) return;
+      state = { ...value, subscriptionId: backend?.subscriptionId ?? "" };
+      resolve(state);
+      for (const observer of observers) {
+        try {
+          observer.snapshot(state);
+        } catch (error) {
+          this.port.failed(error);
+        }
+      }
+    };
+    const detach = () => {
+      if (slot !== null) this.slots.delete(slot);
+      slot = null;
+    };
+    const fail = (error: unknown) => {
+      detach();
+      publish({
+        phase: "error",
+        revision: 0,
+        error:
+          error instanceof DiffSubscriptionError
+            ? error.detail
+            : { code: "UNKNOWN", message: error instanceof Error ? error.message : String(error) },
+      });
+      this.releaseBackend(backend);
+    };
+    const registration: Registration = {
+      start: (modern) => {
+        if (released || backend) return;
+        const current = ++generation;
+        const failed = (error: unknown) => {
+          if (current === generation) fail(error);
+        };
+        stream = new DiffStream(publish);
+        if (modern) {
+          const observation = this.port.modern(compare);
+          backend = observation;
+          observation.subscribe({
+            snapshot: (payload) => {
+              if (current !== generation) return;
+              detach();
+              if (payload.error) {
+                fail(new DiffSubscriptionError(payload.error));
+                return;
+              }
+              slot = payload.slot;
+              const owner = {
+                receive: (bytes: Uint8Array) => {
+                  try {
+                    stream.receive(decodeDiffFrame(bytes));
+                  } catch (error) {
+                    fail(error);
+                  }
+                },
+              };
+              this.slots.set(slot, owner);
+            },
+            update: () => {},
+            error: failed,
+          });
+          void observation.ready.catch(failed);
+        } else {
+          // COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+          const legacy = legacyCompare(compare);
+          if (!legacy) {
+            fail(
+              new DiffSubscriptionError({
+                code: "INVALID_COMPARE",
+                message: "Update the host to use this comparison",
+              }),
+            );
+            return;
+          }
+          const observation = this.port.legacy(compare.cwd, legacy);
+          backend = observation;
+          const apply = (
+            payload: Pick<
+              SubscribeCheckoutDiffResponse["payload"],
+              "files" | "error" | "diffTooLarge"
+            >,
+          ) => {
+            if (current !== generation) return;
+            if (payload.error)
+              publish({
+                phase: "error",
+                revision: 0,
+                error: {
+                  code: payload.error.code === "NOT_GIT_REPO" ? "NOT_GIT_REPO" : "UNKNOWN",
+                  message: payload.error.message,
+                },
+              });
+            else
+              publish({
+                phase: "ready",
+                revision: (state?.revision ?? 0) + 1,
+                resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                diffTooLarge: payload.diffTooLarge === true,
+                files: payload.files,
+              });
+          };
+          observation.subscribe({
+            snapshot: apply,
+            update: (message) => {
+              if (message.type === "checkout_diff_update") apply(message.payload);
+            },
+            error: failed,
+          });
+          void observation.ready.catch(failed);
+        }
+      },
+      disconnected: () => {
+        generation++;
+        detach();
+        state = null;
+        const old = backend;
+        backend = null;
+        void old?.release().catch(this.port.failed);
+      },
+      release: async () => {
+        if (released) return;
+        released = true;
+        generation++;
+        detach();
+        this.registrations.delete(registration);
+        await backend?.release();
+        observers.clear();
+      },
+    };
+    this.registrations.add(registration);
+    if (this.mode !== null) registration.start(this.mode);
+    return {
+      get subscriptionId() {
+        return backend?.subscriptionId ?? null;
+      },
+      ready,
+      subscribe: (observer) => {
+        observers.add(observer);
+        if (state) observer.snapshot(state);
+        return () => observers.delete(observer);
+      },
+      release: () => registration.release(),
+    };
+  }
+}
+function legacyCompare(compare: DiffCompare): LegacyCompare | null {
+  if (compare.highlight === false) return null;
+  const { base, head } = compare;
+  if (base.kind !== "rev") return null;
+  if (base.rev === "HEAD" && head.kind === "worktree")
+    return { mode: "uncommitted", ignoreWhitespace: compare.ignoreWhitespace };
+  if (compare.mergeBase && head.kind === "rev" && head.rev === "HEAD")
+    return { mode: "base", baseRef: base.rev, ignoreWhitespace: compare.ignoreWhitespace };
+  if (compare.mergeBase && head.kind === "worktree")
+    return { mode: "all", baseRef: base.rev, ignoreWhitespace: compare.ignoreWhitespace };
+  return null;
+}
diff --git a/packages/client/src/diff/stream.test.ts b/packages/client/src/diff/stream.test.ts
new file mode 100644
index 0000000000..b740469029
--- /dev/null
+++ b/packages/client/src/diff/stream.test.ts
@@ -0,0 +1,86 @@
+import { expect, test } from "vitest";
+import { DiffStream } from "./stream.js";
+import { DiffOpcode, type DiffBegin } from "@getpaseo/protocol/binary-frames/index";
+import type { DiffState } from "./index.js";
+const entry = {
+  path: "a.ts",
+  oldPath: null,
+  change: "modified" as const,
+  content: "text" as const,
+  additions: 1,
+  deletions: 0,
+  body: true,
+};
+const begin = (revision: number, baseRevision = 0): DiffBegin => ({
+  opcode: DiffOpcode.Begin,
+  slot: 0,
+  revision,
+  baseRevision,
+  baseSha: "a",
+  headSha: "b",
+  mergeBaseSha: "",
+  entries: [entry],
+});
+const end = (revision: number) =>
+  ({
+    opcode: DiffOpcode.End,
+    slot: 0,
+    revision,
+    diffTooLarge: false,
+    omitted: [],
+    error: null,
+  }) as const;
+test("publishes the initial tree, commits on End and buffers refreshes with stable equal files", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((state) => states.push(state));
+  stream.receive(begin(1));
+  expect(states[0]).toMatchObject({ phase: "loading", entries: [{ path: "a.ts" }] });
+  stream.receive({
+    opcode: DiffOpcode.Bodies,
+    slot: 0,
+    revision: 1,
+    files: [{ path: "a.ts", hunks: [] }],
+  });
+  expect(states).toHaveLength(1);
+  stream.receive(end(1));
+  const ready = states[1];
+  if (ready.phase !== "ready") throw new Error("Expected ready");
+  stream.receive(begin(2, 1));
+  stream.receive({
+    opcode: DiffOpcode.Bodies,
+    slot: 0,
+    revision: 2,
+    files: [{ path: "a.ts", hunks: [] }],
+  });
+  expect(states).toHaveLength(2);
+  stream.receive(end(2));
+  const refreshed = states[2];
+  if (refreshed.phase !== "ready") throw new Error("Expected ready");
+  expect(refreshed.files[0]).toBe(ready.files[0]);
+});
+test("superseded and stale frames cannot leave the client loading; End is authoritative", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((s) => states.push(s));
+  stream.receive(begin(1));
+  stream.receive(begin(2));
+  stream.receive(end(1));
+  expect(() => stream.receive(end(2))).toThrow(/Missing/);
+  stream.receive(begin(3));
+  stream.receive({ ...end(3), error: { code: "REF_NOT_FOUND", message: "gone" } });
+  expect(states.at(-1)).toMatchObject({ phase: "error", error: { code: "REF_NOT_FOUND" } });
+  stream.receive({ ...begin(4), entries: [] });
+  stream.receive(end(4));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [] });
+});
+test("unchanged entries retain hunks, omissions override cache, removed paths disappear", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((s) => states.push(s));
+  stream.receive(begin(1));
+  stream.receive({ ...end(1), omitted: ["a.ts"], diffTooLarge: true });
+  stream.receive({ ...begin(2, 1), entries: [{ ...entry, body: false }] });
+  stream.receive(end(2));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [{ status: "too_large" }] });
+  stream.receive({ ...begin(3, 2), entries: [] });
+  stream.receive(end(3));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [] });
+});
diff --git a/packages/client/src/diff/stream.ts b/packages/client/src/diff/stream.ts
new file mode 100644
index 0000000000..ac55f681ec
--- /dev/null
+++ b/packages/client/src/diff/stream.ts
@@ -0,0 +1,94 @@
+import {
+  DiffOpcode,
+  materializeDiffFile,
+  type DiffBegin,
+  type DiffBody,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import type { DiffState } from "./index.js";
+
+/** Owns revision assembly. End, rather than a local body count, commits the snapshot. */
+export class DiffStream {
+  private pending: { begin: DiffBegin; bodies: Map<string, DiffBody> } | null = null;
+  private committed: Extract<DiffState, { phase: "ready" }> | null = null;
+  constructor(private publish: (state: DiffState) => void) {}
+  receive(frame: DiffFrame): void {
+    if (frame.opcode === DiffOpcode.Begin) {
+      if (frame.baseRevision !== 0 && frame.baseRevision !== this.committed?.revision)
+        throw new Error("Unknown diff base revision");
+      if (new Set(frame.entries.map((entry) => entry.path)).size !== frame.entries.length)
+        throw new Error("Duplicate diff entry");
+      this.pending = { begin: frame, bodies: new Map() };
+      if (!this.committed)
+        this.publish({
+          phase: "loading",
+          revision: frame.revision,
+          entries: frame.entries.map(({ body: _body, ...entry }) => entry),
+        });
+      return;
+    }
+    const pending = this.pending;
+    if (!pending || frame.revision !== pending.begin.revision) return;
+    if (frame.opcode === DiffOpcode.Bodies) {
+      for (const body of frame.files) {
+        if (pending.bodies.has(body.path)) throw new Error("Duplicate diff body");
+        const entry = pending.begin.entries.find((candidate) => candidate.path === body.path);
+        if (!entry?.body) throw new Error("Unexpected diff body");
+        pending.bodies.set(body.path, body);
+      }
+      return;
+    }
+    this.pending = null;
+    if (frame.error) {
+      this.committed = null;
+      this.publish({ phase: "error", revision: frame.revision, error: frame.error });
+      return;
+    }
+    const previous = new Map(this.committed?.files.map((file) => [file.path, file]));
+    const omitted = new Set(frame.omitted);
+    for (const path of omitted)
+      if (!pending.begin.entries.some((entry) => entry.path === path))
+        throw new Error("Unknown omitted diff path");
+    const files = pending.begin.entries.map((entry) => {
+      const old = previous.get(entry.path);
+      const body = pending.bodies.get(entry.path);
+      if (entry.content === "text" && !omitted.has(entry.path) && entry.body && !body)
+        throw new Error(`Missing diff body: ${entry.path}`);
+      if (
+        entry.content === "text" &&
+        !entry.body &&
+        !omitted.has(entry.path) &&
+        (!old || pending.begin.baseRevision === 0)
+      )
+        throw new Error(`Missing inherited diff: ${entry.path}`);
+      let file = materializeDiffFile(entry, body ?? null, omitted.has(entry.path));
+      if (entry.content === "text" && !entry.body && !omitted.has(entry.path) && old)
+        file = { ...file, hunks: old.hunks, status: old.status };
+      return old && sameFile(old, file) ? old : file;
+    });
+    const { revision, baseSha, headSha, mergeBaseSha } = pending.begin;
+    this.committed = {
+      phase: "ready",
+      revision,
+      resolved: { baseSha, headSha, mergeBaseSha },
+      files,
+      diffTooLarge: frame.diffTooLarge,
+    };
+    this.publish(this.committed);
+  }
+}
+function sameFile(a: ParsedDiffFile, b: ParsedDiffFile): boolean {
+  if (
+    a.path !== b.path ||
+    a.oldPath !== b.oldPath ||
+    a.isNew !== b.isNew ||
+    a.isDeleted !== b.isDeleted ||
+    a.additions !== b.additions ||
+    a.deletions !== b.deletions ||
+    a.status !== b.status
+  )
+    return false;
+  if (a.hunks === b.hunks) return true;
+  return JSON.stringify(a.hunks) === JSON.stringify(b.hunks);
+}
diff --git a/packages/client/src/hosts/index.ts b/packages/client/src/hosts/index.ts
index aa5c910158..150cf48071 100644
--- a/packages/client/src/hosts/index.ts
+++ b/packages/client/src/hosts/index.ts
@@ -26,11 +26,13 @@ export function createHostChannelTransport(
   return () => {
     const opens = new Set<() => void>();
     const closes = new Set<(event?: unknown) => void>();
-    const messages = new Set<(data: unknown, binary: boolean) => void>();
+    const messages = new Set<(data: unknown, binary: boolean) => void | Promise<void>>();
     const errors = new Set<(error: unknown) => void>();
     let routeId: string | null = null;
     let closed = false;
     const cleanups: (() => void)[] = [];
+    let flowControl = false;
+    let receivedFrames = 0;
     const close = (error?: unknown) => {
       if (closed) return;
       closed = true;
@@ -45,10 +47,28 @@ export function createHostChannelTransport(
       if (error) for (const handler of errors) handler(error);
       for (const handler of closes) handler(error);
     };
+    const deliver = (data: unknown, binary: boolean) => {
+      if (closed) return;
+      const sequence = ++receivedFrames;
+      try {
+        const deliveries = [...messages].map(async (handler) => {
+          await handler(data, binary);
+        });
+        void Promise.all(deliveries)
+          .then(async () => {
+            if (flowControl && !closed && routeId)
+              await origin.acknowledgeHostLink(routeId, sequence);
+            return undefined;
+          })
+          .catch(close);
+      } catch (error) {
+        close(error);
+      }
+    };
     cleanups.push(
       origin.subscribeRawMessages((message) => {
         if (message.type === "hosts.route.frame" && message.payload.subscriptionId === routeId) {
-          for (const handler of messages) handler(message.payload.data, false);
+          deliver(message.payload.data, false);
         }
         if (message.type === "hosts.route.closed" && message.payload.subscriptionId === routeId)
           close(
@@ -61,7 +81,7 @@ export function createHostChannelTransport(
     );
     cleanups.push(
       origin.subscribeHostFrames((frame) => {
-        if (frame.routeId === routeId) for (const handler of messages) handler(frame.payload, true);
+        if (frame.routeId === routeId) deliver(frame.payload, true);
       }),
     );
     cleanups.push(
@@ -71,7 +91,15 @@ export function createHostChannelTransport(
     );
     let opening: Promise<string>;
     if (first) opening = Promise.resolve(first);
-    else opening = link ? origin.openHostLink(scopeId) : origin.openHostRoute(serverId, scopeId);
+    else if (link) {
+      opening = origin.openHostLink(scopeId, { flowControl: true }).then((opened) => {
+        // COMPAT(hostLinkFlowControl): added after v0.15.3 (#9109); remove after
+        // 2027-05-08 once the daemon floor supports forwarding acknowledgments.
+        // Older destinations omit flowControl and receive no acknowledgment messages.
+        flowControl = opened.flowControl;
+        return opened.routeId;
+      });
+    } else opening = origin.openHostRoute(serverId, scopeId);
     first = null;
     void opening
       .then((id) => {
diff --git a/packages/client/src/index.test.ts b/packages/client/src/index.test.ts
index 1b11a3032f..6a49405a4a 100644
--- a/packages/client/src/index.test.ts
+++ b/packages/client/src/index.test.ts
@@ -607,6 +607,29 @@ test("workspace handles keep identity and refresh snapshots through existing dri
     }),
   );
   await expect(titlePromise).resolves.toEqual({ title: "SDK review" });
+  const basePromise = workspace.setBaseBranch({
+    baseRef: "refs/heads/release",
+    requestId: "workspace-base-request",
+  });
+  expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+    type: "workspace.base_branch.set.request",
+    workspaceId: "workspace_sdk",
+    baseRef: "refs/heads/release",
+    requestId: "workspace-base-request",
+  });
+  ws.message(
+    sessionMessage({
+      type: "workspace.base_branch.set.response",
+      payload: {
+        requestId: "workspace-base-request",
+        workspaceId: "workspace_sdk",
+        accepted: true,
+        baseRef: "refs/heads/release",
+        error: null,
+      },
+    }),
+  );
+  await expect(basePromise).resolves.toEqual({ baseRef: "refs/heads/release" });
 
   unsubscribe();
   ws.message(
@@ -747,6 +770,88 @@ test("agents.create with internal fails before sending on a host without interna
   await client.close();
 });
 
+async function createWorkspaceHandle(features: Record<string, boolean>) {
+  const { client, ws } = await connectClient(features);
+  const creating = client.workspaces.create({
+    source: { kind: "directory", path: "/repo/sdk" },
+  });
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  ws.message(
+    sessionMessage({
+      type: "workspace.create.response",
+      payload: {
+        requestId: request.requestId,
+        workspace: createWorkspace({ id: "workspace_open" }),
+        setupTerminalId: null,
+        error: null,
+      },
+    }),
+  );
+  return { client, ws, workspace: await creating };
+}
+
+test("a background agent in an existing workspace fails before sending on a host without background agents", async () => {
+  const { client, ws, workspace } = await createWorkspaceHandle({
+    providerUsageList: true,
+    providersSnapshotCwd: true,
+    ownedSubscriptions: true,
+    backgroundWorkspaces: true,
+  });
+  const sentBefore = ws.sent.length;
+
+  await expect(
+    workspace.agents.create({ config: { provider: "codex/gpt-5.4" }, background: true }),
+  ).rejects.toThrow("Update the host to use background agents.");
+  expect(ws.sent).toHaveLength(sentBefore);
+
+  const creating = client.agents.create({
+    config: { provider: "codex/gpt-5.4" },
+    cwd: "/repo/sdk",
+    background: true,
+  });
+  expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+    type: "create_agent_request",
+    background: true,
+  });
+  expect(parseSentSessionMessage(ws.sent.at(-1))).not.toHaveProperty("workspaceId");
+  creating.catch(() => {});
+  await client.close();
+});
+
+test("a background agent in an existing workspace is sent to a host with background agents", async () => {
+  const { client, ws, workspace } = await createWorkspaceHandle({
+    providerUsageList: true,
+    providersSnapshotCwd: true,
+    ownedSubscriptions: true,
+    backgroundWorkspaces: true,
+    backgroundAgents: true,
+  });
+
+  const creating = workspace.agents.create({
+    config: { provider: "codex/gpt-5.4" },
+    background: true,
+  });
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  expect(request).toMatchObject({
+    type: "create_agent_request",
+    workspaceId: "workspace_open",
+    background: true,
+  });
+  ws.message(
+    sessionMessage({
+      type: "status",
+      payload: {
+        status: "agent_created",
+        requestId: request.requestId,
+        agentId: "agent_background",
+        agent: createAgent({ id: "agent_background", workspaceId: "workspace_open" }),
+      },
+    }),
+  );
+  expect((await creating).id).toBe("agent_background");
+  await client.close();
+});
+
 test("agent handles delegate create, send, timeline refetch, archive, and local updates", async () => {
   const { client, ws } = await connectClient();
   const createdAgent = createAgent();
@@ -1601,7 +1706,12 @@ test("config actions delegate to existing daemon config RPCs", async () => {
 });
 
 test("agent config maps provider/model and provider-native options to the daemon", async () => {
-  const { client, ws } = await connectClient();
+  const { client, ws } = await connectClient({
+    providerUsageList: true,
+    providersSnapshotCwd: true,
+    ownedSubscriptions: true,
+    providerOptionControls: true,
+  });
   const createdAgent = createAgent({
     model: "gpt-5.4",
     currentModeId: "full-access",
@@ -1633,8 +1743,8 @@ test("agent config maps provider/model and provider-native options to the daemon
       model: "gpt-5.4",
       modeId: "full-access",
       thinkingOptionId: "high",
-      featureValues: { webSearch: true },
       providerOptions: {
+        webSearch: true,
         approval_policy: "never",
         sandbox_mode: "workspace-write",
         sandbox_workspace_write: {
@@ -1833,3 +1943,256 @@ test("agent reload reopens through the daemon RPC then returns the observed snap
     await client.close();
   }
 });
+
+const BACKGROUND_WORK_FEATURES = { ownedSubscriptions: true, agentBackgroundWork: true };
+const SHELL_ITEM = {
+  id: "bash-1",
+  kind: "shell",
+  description: "sleep 20",
+  startedAt: "2026-10-06T10:00:00.000Z",
+};
+
+function answerBackgroundWorkList(ws: FakeWebSocket, items: unknown[]): void {
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  expect(request).toMatchObject({ type: "agent.background_work.list.request", agentId: "agent-a" });
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.list.response",
+      payload: { requestId: request.requestId, agentId: "agent-a", items, error: null },
+    }),
+  );
+}
+
+test("agent handles list background work", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+
+  const pending = client.agents.ref("agent-a").backgroundWork.list();
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  expect(request).toMatchObject({ type: "agent.background_work.list.request", agentId: "agent-a" });
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.list.response",
+      payload: {
+        requestId: request.requestId,
+        agentId: "agent-a",
+        items: [SHELL_ITEM],
+        error: null,
+      },
+    }),
+  );
+
+  await expect(pending).resolves.toEqual([SHELL_ITEM]);
+  await client.close();
+});
+
+test("agent handles follow only their own background work", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+  const received: unknown[] = [];
+
+  const unsubscribe = client.agents
+    .ref("agent-a")
+    .backgroundWork.subscribe((items) => received.push(items));
+  expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+    type: "session.events.set_subscription.request",
+    events: ["agent.background_work.update"],
+  });
+  acknowledgeObservation(ws, "background-work-sdk");
+  answerBackgroundWorkList(ws, []);
+  await vi.waitFor(() => expect(received).toEqual([[]]));
+
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.update",
+      payload: { subscriptionId: "background-work-sdk", agentId: "agent-b", items: [SHELL_ITEM] },
+    }),
+  );
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.update",
+      payload: { subscriptionId: "background-work-sdk", agentId: "agent-a", items: [SHELL_ITEM] },
+    }),
+  );
+  await vi.waitFor(() => expect(received).toEqual([[], [SHELL_ITEM]]));
+
+  unsubscribe();
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.update",
+      payload: { subscriptionId: "background-work-sdk", agentId: "agent-a", items: [] },
+    }),
+  );
+  expect(received).toEqual([[], [SHELL_ITEM]]);
+  await client.close();
+});
+
+test("background work subscriptions list the current work again after a reconnect", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+  const received: unknown[] = [];
+
+  client.agents.ref("agent-a").backgroundWork.subscribe((items) => received.push(items));
+  acknowledgeObservation(ws, "background-work-first");
+  answerBackgroundWorkList(ws, [SHELL_ITEM]);
+  await vi.waitFor(() => expect(received).toEqual([[SHELL_ITEM]]));
+
+  ws.readyState = 3;
+  ws.onclose?.({ code: 1006, reason: "Connection lost" });
+  const reconnecting = client.connect();
+  const next = FakeWebSocket.instances[1];
+  next.open();
+  next.message(
+    sessionMessage({
+      type: "status",
+      payload: {
+        status: "server_info",
+        serverId: "srv_sdk_test",
+        hostname: null,
+        version: null,
+        features: BACKGROUND_WORK_FEATURES,
+      },
+    }),
+  );
+  await reconnecting;
+  await vi.waitFor(() =>
+    expect(parseSentSessionMessage(next.sent.at(-1))).toMatchObject({
+      type: "session.events.set_subscription.request",
+    }),
+  );
+  acknowledgeObservation(next, "background-work-second");
+  answerBackgroundWorkList(next, []);
+
+  await vi.waitFor(() => expect(received).toEqual([[SHELL_ITEM], []]));
+  await client.close();
+});
+
+test("background work subscriptions keep an update that overtakes their list", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+  const received: unknown[] = [];
+
+  client.agents.ref("agent-a").backgroundWork.subscribe((items) => received.push(items));
+  acknowledgeObservation(ws, "background-work-sdk");
+  await vi.waitFor(() =>
+    expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+      type: "agent.background_work.list.request",
+    }),
+  );
+  const listRequest = parseSentSessionMessage(ws.sent.at(-1));
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.update",
+      payload: { subscriptionId: "background-work-sdk", agentId: "agent-a", items: [] },
+    }),
+  );
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.list.response",
+      payload: {
+        requestId: listRequest.requestId,
+        agentId: "agent-a",
+        items: [SHELL_ITEM],
+        error: null,
+      },
+    }),
+  );
+
+  await vi.waitFor(() => expect(received).toEqual([[]]));
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  expect(received).toEqual([[]]);
+  await client.close();
+});
+
+test("background work subscriptions report a failed setup to onError", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+  const received: unknown[] = [];
+  const errors: unknown[] = [];
+  client.agents.ref("agent-a").backgroundWork.subscribe((items) => received.push(items), {
+    onError: (error) => errors.push(error),
+  });
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  ws.message(
+    sessionMessage({
+      type: "session.events.set_subscription.response",
+      payload: { requestId: request.requestId },
+    }),
+  );
+  await vi.waitFor(() => expect(errors).toHaveLength(1));
+  expect((errors[0] as Error).message).toContain("subscription ID");
+  expect(received).toEqual([]);
+  await client.close();
+});
+
+test("background work subscriptions report a failed list to onError", async () => {
+  const { client, ws } = await connectClient(BACKGROUND_WORK_FEATURES);
+  const received: unknown[] = [];
+  const errors: unknown[] = [];
+
+  client.agents.ref("agent-a").backgroundWork.subscribe((items) => received.push(items), {
+    onError: (error) => errors.push(error),
+  });
+  acknowledgeObservation(ws, "background-work-sdk");
+  await vi.waitFor(() =>
+    expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+      type: "agent.background_work.list.request",
+    }),
+  );
+  const listRequest = parseSentSessionMessage(ws.sent.at(-1));
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.list.response",
+      payload: { requestId: listRequest.requestId, agentId: "agent-a", items: [], error: "boom" },
+    }),
+  );
+
+  await vi.waitFor(() => expect(errors).toHaveLength(1));
+  expect(errors[0]).toBeInstanceOf(Error);
+  expect((errors[0] as Error).message).toContain("boom");
+  expect(received).toEqual([]);
+  await client.close();
+});
+
+test("background work asks for a host update when the daemon lacks it", async () => {
+  const { client } = await connectClient({ ownedSubscriptions: true });
+  const handle = client.agents.ref("agent-a");
+
+  await expect(handle.backgroundWork.list()).rejects.toThrow("Update the host");
+  expect(() => handle.backgroundWork.subscribe(() => {})).toThrow("Update the host");
+  await client.close();
+});
+
+test("background stop sends the live item token and waits for the response", async () => {
+  const { client, ws } = await connectClient({
+    ...BACKGROUND_WORK_FEATURES,
+    agentBackgroundWorkStop: true,
+  });
+  const item = { ...SHELL_ITEM, canStop: true, stopToken: "generation-1" };
+  const pending = client.agents.ref("agent-a").backgroundWork.stop(item);
+  const request = parseSentSessionMessage(ws.sent.at(-1));
+  expect(request).toMatchObject({
+    type: "agent.background_work.stop.request",
+    agentId: "agent-a",
+    itemId: item.id,
+    stopToken: item.stopToken,
+  });
+  ws.message(
+    sessionMessage({
+      type: "agent.background_work.stop.response",
+      payload: {
+        requestId: request.requestId,
+        agentId: "agent-a",
+        itemId: item.id,
+        error: "rejected",
+      },
+    }),
+  );
+  await expect(pending).rejects.toThrow("rejected");
+  await client.close();
+});
+
+test("background stop rejects when the host does not advertise the operation", async () => {
+  const { client } = await connectClient(BACKGROUND_WORK_FEATURES);
+  await expect(
+    client.agents
+      .ref("agent-a")
+      .backgroundWork.stop({ ...SHELL_ITEM, canStop: true, stopToken: "generation" }),
+  ).rejects.toThrow("Update the host");
+  await client.close();
+});
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 246c5169e8..87f980c478 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -1,3 +1,4 @@
+import { workspaceLabelKey } from "@getpaseo/protocol/workspace-labels";
 export type { TerminalReplayEvent, TerminalStreamEvent } from "./terminal-stream-router.js";
 import type { AgentAddress } from "@getpaseo/protocol/addresses";
 import { parentAddressLabels } from "@getpaseo/protocol/agent-labels";
@@ -8,7 +9,7 @@ export type { HostAdd, HostUpdate, HostSummary, HostDirectory } from "@getpaseo/
 import type { OwnedSubscription } from "./connection/index.js";
 export type { OwnedSubscription, SubscriptionObserver } from "./connection/index.js";
 import type { DaemonClientConfig } from "./daemon-client.js";
-import type { AgentPermissionResponse } from "@getpaseo/protocol/agent-types";
+import type { AgentPermissionResponse, JsonValue } from "@getpaseo/protocol/agent-types";
 import type {
   AgentSnapshotPayload,
   CreationSnapshot,
@@ -20,6 +21,8 @@ import type {
   ListCommandsResponse,
   ListProviderFeaturesRequestMessage,
   ListProviderFeaturesResponseMessage,
+  ProviderControlsListRequestMessage,
+  ProviderControlsListResponseMessage,
   ListProviderModelsResponseMessage,
   ProjectListRequestMessage,
   ProjectListResponseMessage,
@@ -54,6 +57,7 @@ export type {
 } from "./terminals/index.js";
 import type { PluginTimelineItem } from "@getpaseo/protocol/agent-types";
 import type {
+  AgentBackgroundWorkItem,
   FetchAgentsEntry,
   FetchAgentsOptions,
   FetchAgentsPageInfo,
@@ -182,6 +186,8 @@ export interface PaseoWorkspaceHandle {
   readonly directory: string | null;
   readonly name: string | null;
   readonly status: PaseoWorkspace["status"] | null;
+  /** Data plugins stored on the workspace. Paseo never reads a key. */
+  readonly metadata: NonNullable<PaseoWorkspace["metadata"]> | null;
   readonly agents: {
     create(options: PaseoWorkspaceAgentCreateOptions): Promise<PaseoAgentHandle>;
   };
@@ -189,6 +195,14 @@ export interface PaseoWorkspaceHandle {
   current(): PaseoWorkspace | null;
   refresh(options?: { requestId?: string }): Promise<PaseoWorkspace | null>;
   setTitle(title: string | null, requestId?: string): Promise<{ title: string | null }>;
+  /** Top-level keys replace; `null` removes the key. Needs a host with `entityMetadata`. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+  setPinned(pinned: boolean): Promise<{ pinnedAt: string | null }>;
+  setLabel(name: string, options: { assigned: boolean }): Promise<{ labels: string[] }>;
+  setBaseBranch(options: {
+    baseRef: string;
+    requestId?: string;
+  }): Promise<{ baseRef: string | null }>;
   archive(requestId?: string): Promise<PaseoWorkspaceArchiveResult>;
   /**
    * Subscribes to already-emitted daemon workspace_update events for this id.
@@ -239,8 +253,12 @@ export interface PaseoAgentConfig {
   provider: string;
   modeId?: PaseoAgentSessionConfig["modeId"];
   thinkingOptionId?: PaseoAgentSessionConfig["thinkingOptionId"];
+  /** @deprecated Put these in `options`; they are folded into it on send. */
   featureValues?: PaseoProviderFeatureValues;
-  /** JSON-safe provider-native settings, validated by the selected provider. */
+  /**
+   * JSON-safe provider settings, validated by the selected provider. They include the settings the
+   * provider offers a composer control for, such as `service_tier` or `fast_mode`.
+   */
   options?: PaseoAgentSessionConfig["providerOptions"];
   systemPrompt?: PaseoAgentSessionConfig["systemPrompt"];
   toolPolicy?: PaseoAgentSessionConfig["toolPolicy"];
@@ -264,10 +282,16 @@ export interface PaseoAgentCreateOptions {
   git?: CreateAgentRequestMessage["git"];
   worktree?: CreateAgentRequestMessage["worktree"];
   autoArchive?: CreateAgentRequestMessage["autoArchive"];
-  /** Visibility intent for a NEW workspace. Existing targets reject this option. */
+  /**
+   * Creates a background agent: hidden from default lists, tabs, the parent's subagent track
+   * and notifications, and still addressable by id. A workspace this call creates is
+   * background too. With a parent and no value, the parent's own background applies.
+   */
   background?: CreateAgentRequestMessage["background"];
   requestId?: string;
   labels?: Record<string, string>;
+  /** Data plugins store on the agent: JSON values under keys such as `"linear.issue"`. */
+  metadata?: CreateAgentRequestMessage["metadata"];
 }
 
 export type PaseoWorkspaceAgentCreateOptions = Omit<PaseoAgentCreateOptions, "cwd">;
@@ -355,6 +379,36 @@ export interface PaseoAgentTimelineHandle {
   subscribe(handler: (event: PaseoAgentTimelineEvent) => void): PaseoAgentTimelineSubscription;
 }
 
+export type PaseoAgentBackgroundWorkItem = AgentBackgroundWorkItem;
+
+export interface PaseoAgentBackgroundWorkHandle {
+  /** Stop one item and wait for provider confirmation. */
+  stop(
+    item: PaseoAgentBackgroundWorkItem,
+    options?: { requestId?: string; timeout?: number },
+  ): Promise<void>;
+  /** Reads the agent's current background work once. */
+  list(options?: { requestId?: string; timeout?: number }): Promise<PaseoAgentBackgroundWorkItem[]>;
+  /**
+   * Calls `listener` with the agent's current list once the subscription is established, again
+   * after each reconnect, then with the full list each time it changes. Returns the unsubscribe
+   * function.
+   *
+   * When reading the current list fails, `options.onError` receives the error and `listener` is
+   * not called; without `onError` the error is logged. The read is not retried: the next
+   * reconnect reads the list again.
+   */
+  subscribe(
+    listener: (items: PaseoAgentBackgroundWorkItem[]) => void,
+    options?: PaseoAgentBackgroundWorkSubscribeOptions,
+  ): () => void;
+}
+
+export interface PaseoAgentBackgroundWorkSubscribeOptions {
+  /** Receives the error when reading the agent's current list fails. */
+  onError?: (error: unknown) => void;
+}
+
 export interface PaseoAgentHandle {
   readonly id: string;
   readonly address: AgentAddress;
@@ -374,10 +428,18 @@ export interface PaseoAgentHandle {
   readonly activeTurn: NonNullable<PaseoAgent["activeTurn"]> | null;
   readonly lastUsage: NonNullable<PaseoAgent["lastUsage"]> | null;
   readonly lastError: NonNullable<PaseoAgent["lastError"]> | null;
+  /** @deprecated Use `controls` and `options`. */
   readonly features: NonNullable<PaseoAgent["features"]> | null;
+  /** The provider options the agent runs with: `config.json` defaults merged with its own. */
+  readonly options: NonNullable<PaseoAgent["options"]> | null;
+  /** How the provider wants its options drawn. Controls hold no value; read `options`. */
+  readonly controls: NonNullable<PaseoAgent["controls"]> | null;
+  /** Data plugins stored on the agent. Paseo never reads a key. */
+  readonly metadata: NonNullable<PaseoAgent["metadata"]> | null;
   readonly runtimeInfo: NonNullable<PaseoAgent["runtimeInfo"]> | null;
   readonly archivedAt: NonNullable<PaseoAgent["archivedAt"]> | null;
   readonly timeline: PaseoAgentTimelineHandle;
+  readonly backgroundWork: PaseoAgentBackgroundWorkHandle;
   current(): PaseoAgent | null;
   refresh(requestId?: string): Promise<PaseoAgentRefetchResult | null>;
   /**
@@ -387,6 +449,14 @@ export interface PaseoAgentHandle {
   reload(options?: { requestId?: string }): Promise<PaseoAgentRefetchResult | null>;
   send(text: string, options?: PaseoAgentSendOptions): Promise<void>;
   respondToPermission(options: PaseoAgentRespondToPermissionOptions): Promise<void>;
+  /**
+   * Changes the agent's own options: top-level keys replace, `null` removes the key so the
+   * `config.json` default (or the provider's own default) applies again. Resolves once the
+   * provider has applied the patch; a provider that cannot apply a key live rejects it.
+   */
+  setOptions(patch: Record<string, unknown>): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. Needs a host with `entityMetadata`. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
   /** Sends a prompt and resolves when that turn finishes or needs attention. */
   run(text: string, options?: PaseoAgentRunOptions): Promise<PaseoAgentRunResult>;
   /** Waits for the current turn, including one started with `prompt`. */
@@ -423,14 +493,21 @@ export interface PaseoAgentActions {
 
 export type PaseoProviderModelsResult = ListProviderModelsResponseMessage["payload"];
 export type PaseoProviderModesResult = ListProviderModesResponseMessage["payload"];
-type PaseoProviderFeaturesDraft = ListProviderFeaturesRequestMessage["draftConfig"];
-export interface PaseoProviderFeaturesInput extends Omit<
-  PaseoProviderFeaturesDraft,
+type PaseoProviderControlsDraft = ProviderControlsListRequestMessage["draftConfig"];
+export interface PaseoProviderControlsInput extends Omit<
+  PaseoProviderControlsDraft,
   "provider" | "model"
 > {
   /** Provider and model in `provider/model` format. */
   provider: string;
 }
+export type PaseoProviderControlsResult = ProviderControlsListResponseMessage["payload"];
+/** @deprecated Use `PaseoProviderControlsInput`. */
+export type PaseoProviderFeaturesInput = Omit<
+  ListProviderFeaturesRequestMessage["draftConfig"],
+  "provider" | "model"
+> & { provider: string };
+/** @deprecated Use `PaseoProviderControlsResult`. */
 export type PaseoProviderFeaturesResult = ListProviderFeaturesResponseMessage["payload"];
 export type PaseoProviderAvailabilityResult = ListAvailableProvidersResponse["payload"];
 export type PaseoProviderSnapshotResult = GetProvidersSnapshotResponseMessage["payload"];
@@ -469,6 +546,15 @@ export interface PaseoProviderActions {
     provider: PaseoAgentProvider,
     options?: PaseoProviderListOptions,
   ): Promise<PaseoProviderModesResult>;
+  /**
+   * The controls a draft agent would show and the options it would run with, resolved by the
+   * daemon from `config.json` defaults and the draft's own `providerOptions`.
+   */
+  listControls(
+    draftConfig: PaseoProviderControlsInput,
+    options?: { requestId?: string },
+  ): Promise<PaseoProviderControlsResult>;
+  /** @deprecated Use `listControls`. */
   listFeatures(
     draftConfig: PaseoProviderFeaturesInput,
     options?: { requestId?: string },
@@ -553,7 +639,14 @@ function toDaemonAgentCreateOptions(
   serverId?: string,
 ): CreateAgentRequestOptions {
   const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
-  const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
+  const {
+    provider: providerModel,
+    options: ownOptions,
+    featureValues,
+    ...runtimeConfig
+  } = agentConfig;
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. An explicit option wins.
+  const providerOptions = featureValues ? { ...featureValues, ...ownOptions } : ownOptions;
   const { provider, model } = parseProviderModel(providerModel);
   const relationship = parent ? encodeParent(parent, serverId) : {};
   return {
@@ -614,17 +707,20 @@ export function createPaseoApi(
     daemonClient,
     listenAgents,
     (agentId, handler) => own(() => daemonClient.subscribeAgentTimeline(agentId, handler)),
+    () => own(() => daemonClient.observeAgentBackgroundWork()),
   );
   const createAgent = async (
     options: PaseoAgentCreateOptions,
     placement?: { workspaceId: string; cwd: string },
   ) => {
+    const serverId = daemonClient.getLastServerInfoMessage()?.serverId;
+    const foreignParent =
+      options.background === undefined ? foreignParentHandle(options.parent, serverId) : null;
+    const resolved = foreignParent
+      ? await inheritParentBackground(options, foreignParent)
+      : options;
     const agent = await daemonClient.createAgent(
-      toDaemonAgentCreateOptions(
-        options,
-        placement,
-        daemonClient.getLastServerInfoMessage()?.serverId,
-      ),
+      toDaemonAgentCreateOptions(resolved, placement, serverId),
     );
     return createAgentHandle(agent);
   };
@@ -786,6 +882,10 @@ export function createPaseoApi(
         const { provider, model } = parseProviderModel(providerModel);
         return daemonClient.listProviderFeatures({ ...draftConfig, provider, model }, options);
       },
+      listControls: ({ provider: providerModel, ...draftConfig }, options) => {
+        const { provider, model } = parseProviderModel(providerModel);
+        return daemonClient.listProviderControls({ ...draftConfig, provider, model }, options);
+      },
       listAvailable: (options) => daemonClient.listAvailableProviders(options),
       snapshot: (options) => daemonClient.getProvidersSnapshot(options),
       waitForReady: (options) =>
@@ -829,25 +929,7 @@ function createWorkspaceHandleFactory(
     let current = typeof workspace === "string" ? null : workspace;
 
     const refresh = async (options?: { requestId?: string }) => {
-      let cursor: string | undefined;
-      let requestId = options?.requestId;
-      // A ref addresses one workspace by id, so a background one resolves too.
-      const filter = daemonClient.supportsBackgroundWorkspaces() ? { includeBackground: true } : {};
-      do {
-        const result = await daemonClient.fetchWorkspaces({
-          requestId,
-          filter,
-          page: { limit: 200, ...(cursor ? { cursor } : {}) },
-        });
-        const match = result.entries.find((entry) => entry.id === id);
-        if (match) {
-          current = match;
-          return current;
-        }
-        cursor = result.pageInfo.nextCursor ?? undefined;
-        requestId = undefined;
-      } while (cursor);
-      current = null;
+      current = await daemonClient.findWorkspace(id, options);
       return current;
     };
 
@@ -865,6 +947,9 @@ function createWorkspaceHandleFactory(
       get status() {
         return current?.status ?? null;
       },
+      get metadata() {
+        return current?.metadata ?? null;
+      },
       agents: {
         create: async (options) => {
           const snapshot = current ?? (await refresh());
@@ -884,6 +969,20 @@ function createWorkspaceHandleFactory(
       current: () => current,
       refresh,
       setTitle: (title, requestId) => daemonClient.setWorkspaceTitle(id, title, requestId),
+      setMetadata: async (patch) => {
+        const metadata = await daemonClient.setWorkspaceMetadata(id, patch);
+        if (current) current = { ...current, metadata };
+      },
+      setPinned: (pinned) => daemonClient.setWorkspacePinned(id, pinned),
+      setLabel: (name, options) =>
+        assignWorkspaceLabel({
+          client: daemonClient,
+          workspaceId: id,
+          name,
+          assigned: options.assigned,
+        }),
+      setBaseBranch: (options) =>
+        daemonClient.setWorkspaceBaseBranch({ ...options, workspaceId: id }),
       archive: async (requestId) => {
         const result = await daemonClient.archiveWorkspace(id, requestId);
         if (current) {
@@ -909,6 +1008,7 @@ function createAgentHandleFactory(
   daemonClient: DaemonClient,
   listen: (handler: PaseoAgentUpdateHandler) => () => void,
   subscribeTimeline: DaemonClient["subscribeAgentTimeline"],
+  observeBackgroundWork: () => ReturnType<DaemonClient["observeAgentBackgroundWork"]>,
 ): AgentHandleFactory {
   return (agent) => {
     const id = typeof agent === "string" ? agent : agent.id;
@@ -965,6 +1065,48 @@ function createAgentHandleFactory(
             }
           }),
       },
+      backgroundWork: {
+        stop: (item, options) => daemonClient.stopAgentBackgroundWork(id, item, options),
+        list: (options) => daemonClient.listAgentBackgroundWork(id, options),
+        subscribe: (listener, options) => {
+          const observation = observeBackgroundWork();
+          // Bumped by every delivery so a list answered after a newer update is dropped.
+          let sequence = 0;
+          let released = false;
+          const reportError = (error: unknown) => {
+            if (released) return;
+            if (options?.onError) options.onError(error);
+            else console.error("Background work subscription failed", error);
+          };
+          observation.subscribe({
+            error: reportError,
+            snapshot: () => {
+              const listed = ++sequence;
+              void daemonClient
+                .listAgentBackgroundWork(id)
+                .then((items) => {
+                  if (!released && listed === sequence) listener(items);
+                  return undefined;
+                })
+                .catch(reportError);
+            },
+            update: (message) => {
+              if (message.type !== "agent.background_work.update") return;
+              if (message.payload.agentId !== id) return;
+              sequence++;
+              listener(message.payload.items);
+            },
+          });
+          return () => {
+            released = true;
+            void observation
+              .release()
+              .catch((error) =>
+                console.error("Background work subscription cleanup failed", error),
+              );
+          };
+        },
+      },
       get workspaceId() {
         return current?.workspaceId ?? null;
       },
@@ -995,6 +1137,15 @@ function createAgentHandleFactory(
       get features() {
         return current?.features ?? null;
       },
+      get options() {
+        return current?.options ?? null;
+      },
+      get controls() {
+        return current?.controls ?? null;
+      },
+      get metadata() {
+        return current?.metadata ?? null;
+      },
       get runtimeInfo() {
         return current?.runtimeInfo ?? null;
       },
@@ -1016,6 +1167,13 @@ function createAgentHandleFactory(
       send: async (text, options) => {
         await daemonClient.sendAgentMessage(id, text, options);
       },
+      setOptions: async (patch) => {
+        await daemonClient.setAgentOptions(id, patch);
+      },
+      setMetadata: async (patch) => {
+        const metadata = await daemonClient.setAgentMetadata(id, patch);
+        if (current) current = { ...current, metadata };
+      },
       respondToPermission: async ({ requestId, response }) => {
         await daemonClient.respondToPermission(id, requestId, response);
       },
@@ -1086,6 +1244,24 @@ function resolveWorkspaceId(workspace: string | PaseoWorkspaceHandle): string {
   return typeof workspace === "string" ? workspace : workspace.id;
 }
 
+function foreignParentHandle(
+  parent: PaseoAgentCreateOptions["parent"],
+  serverId: string | undefined,
+): PaseoAgentHandle | null {
+  if (!parent || typeof parent === "string" || !("address" in parent)) return null;
+  return parent.address.serverId === serverId ? null : parent;
+}
+
+// A host inherits background from a caller it can see. A parent on another host is invisible to
+// it, so a handle passes its own value on. A bare foreign address can't; pass background then.
+async function inheritParentBackground(
+  options: PaseoAgentCreateOptions,
+  parent: PaseoAgentHandle,
+): Promise<PaseoAgentCreateOptions> {
+  const snapshot = parent.current() ?? (await parent.refresh())?.agent;
+  return snapshot?.background ? { ...options, background: true } : options;
+}
+
 function encodeParent(
   parent: string | AgentAddress | PaseoAgentHandle,
   serverId?: string,
@@ -1220,3 +1396,30 @@ function createGeneratedClientId(): string {
       : Math.random().toString(36).slice(2);
   return `paseo-sdk-${randomId}`;
 }
+
+export type { DiffCompare, DiffState, DiffEntry, ResolvedShas } from "./diff/index.js";
+
+interface WorkspaceLabelAssignment {
+  client: DaemonClient;
+  workspaceId: string;
+  name: string;
+  assigned: boolean;
+}
+async function assignWorkspaceLabel(
+  input: WorkspaceLabelAssignment,
+): Promise<{ labels: string[] }> {
+  input.client.ensureConnected();
+  // COMPAT(workspaceLabels): added in v0.5.0, remove gate after 2027-08-14.
+  if (input.client.getLastServerInfoMessage()?.features?.workspaceLabels !== true)
+    throw new Error("Update the host to assign workspace labels.");
+  const catalog = await input.client.listWorkspaceLabels();
+  const key = workspaceLabelKey(input.name);
+  const existing = catalog.labels.find((label) => workspaceLabelKey(label.name) === key);
+  const label = existing ?? { name: input.name, color: "violet" as const };
+  const result = await input.client.setWorkspaceLabel({
+    workspaceId: input.workspaceId,
+    label,
+    assigned: input.assigned,
+  });
+  return { labels: result.workspaceLabels };
+}
diff --git a/packages/client/src/node/index.ts b/packages/client/src/node/index.ts
index 30d2b8744f..464d16332d 100644
--- a/packages/client/src/node/index.ts
+++ b/packages/client/src/node/index.ts
@@ -204,15 +204,16 @@ export function createHostTransportFactory(
 }
 export function createHostClient(
   connection: string,
-  config: Omit<DaemonClientConfig, "url" | "transportFactory"> & HostTransportOptions,
+  config: Omit<DaemonClientConfig, "url"> & HostTransportOptions,
   budget?: HostTransportBudget,
 ): DaemonClient {
   const target = parseHostTarget(connection);
-  const { webSocketAgent, ...clientConfig } = config;
+  const { webSocketAgent, transportFactory, ...clientConfig } = config;
   return new DaemonClient({
     ...clientConfig,
     url: "ws://host-connector/ws",
     ...(target.password ? { password: target.password } : {}),
-    transportFactory: createHostTransportFactory(connection, budget, { webSocketAgent }),
+    transportFactory:
+      transportFactory ?? createHostTransportFactory(connection, budget, { webSocketAgent }),
   });
 }
diff --git a/packages/desktop/e2e/appearance-font-size.electron.mjs b/packages/desktop/e2e/appearance-font-size.electron.mjs
index 3b92c6f8d1..af21ca1891 100644
--- a/packages/desktop/e2e/appearance-font-size.electron.mjs
+++ b/packages/desktop/e2e/appearance-font-size.electron.mjs
@@ -12,8 +12,7 @@ export async function runAppearanceFontSizeRegression(page) {
   await page.getByRole("button", { name: "Settings", exact: true }).click();
   await page.getByRole("button", { name: "Appearance", exact: true }).click();
 
-  await page.getByLabel("Theme: System", { exact: true }).click();
-  await page.getByText("Pure black", { exact: true }).click();
+  await page.getByRole("radio", { name: "Pure black", exact: true }).click();
 
   const interfaceSizeInput = page.getByRole("textbox", { name: "Interface font size" });
   const contentSizeInput = page.getByRole("textbox", { name: "Content font size" });
diff --git a/packages/desktop/e2e/browser-fill.electron.mjs b/packages/desktop/e2e/browser-fill.electron.mjs
new file mode 100644
index 0000000000..78ce935012
--- /dev/null
+++ b/packages/desktop/e2e/browser-fill.electron.mjs
@@ -0,0 +1,108 @@
+import { build } from "esbuild";
+import { fileURLToPath } from "node:url";
+import { expect } from "@playwright/test";
+
+export async function buildFillFixture() {
+  const { outputFiles } = await build({
+    stdin: {
+      resolveDir: fileURLToPath(new URL("../../app", import.meta.url)),
+      contents: `
+        import { createElement as e, useState } from 'react';
+        import { createRoot } from 'react-dom/client';
+        function Form() {
+          const [title, setTitle] = useState('');
+          const [notes, setNotes] = useState('');
+          const [submitted, setSubmitted] = useState(null);
+          return e('form', { onSubmit: ev => {
+            ev.preventDefault(); setSubmitted({ title, notes });
+          } },
+            e('input', { 'aria-label': 'React title', value: title,
+              onChange: ev => setTitle(ev.target.value) }),
+            e('textarea', { 'aria-label': 'React notes', value: notes,
+              onChange: ev => setNotes(ev.target.value) }),
+            e('p', null, 'React state: ' + JSON.stringify({ title, notes })),
+            e('button', { type: 'submit' }, 'Submit'),
+            e('p', null, 'Submitted: ' + JSON.stringify(submitted)));
+        }
+        createRoot(document.getElementById('root')).render(e(Form));
+        document.getElementById('plain').addEventListener('input', ev => {
+          document.getElementById('plain-state').textContent = 'Plain state: ' + ev.target.value;
+        });
+      `,
+    },
+    bundle: true,
+    write: false,
+    format: "iife",
+    platform: "browser",
+    define: { "process.env.NODE_ENV": '"production"' },
+  });
+  return `<!doctype html><title>React fill fixture</title><div id="root"></div>
+    <input aria-label="Plain input" id="plain"><p id="plain-state"></p>
+    <div role="textbox" aria-label="Editable text" contenteditable="true"></div>
+    <script>${outputFiles[0].text}</script>`;
+}
+
+async function findRef(call, browserId, role, name) {
+  const { snapshot } = await call("browser_snapshot", { browserId });
+  const line = snapshot.split("\n").find((candidate) => candidate.includes(`${role} "${name}"`));
+  const ref = line?.match(/\[ref=([^\]]+)\]/)?.[1];
+  expect(ref, `Snapshot must expose ${role} ${name}: ${snapshot}`).toBeTruthy();
+  return ref;
+}
+
+async function fillField(call, browserId, name, value) {
+  const ref = await findRef(call, browserId, "textbox", name);
+  await call("browser_fill", { browserId, ref, value });
+}
+
+async function submitForm(call, browserId) {
+  const ref = await findRef(call, browserId, "button", "Submit");
+  await call("browser_click", { browserId, ref });
+}
+
+async function expectPageText(call, browserId, text) {
+  await expect
+    .poll(async () => {
+      const result = await call("browser_evaluate", {
+        browserId,
+        function: "() => document.body.innerText",
+      });
+      return JSON.parse(result.resultJson);
+    })
+    .toContain(text);
+}
+
+export async function verifyReactFormFill(call, targetUrl) {
+  const { browserId } = await call("browser_new_tab", {
+    url: new URL("/react-fill", targetUrl).href,
+  });
+  try {
+    await call("browser_wait", { browserId, text: "React state:", timeoutMs: 15_000 });
+    await fillField(call, browserId, "Plain input", "plain value");
+    await expectPageText(call, browserId, "Plain state: plain value");
+    await fillField(call, browserId, "Editable text", "editable value");
+    await expectPageText(call, browserId, "editable value");
+    await fillField(call, browserId, "React title", "Hello from browser_fill");
+    await fillField(call, browserId, "React notes", "First line\nSecond line");
+    await expectPageText(
+      call,
+      browserId,
+      'React state: {"title":"Hello from browser_fill","notes":"First line\\nSecond line"}',
+    );
+    await submitForm(call, browserId);
+    await expectPageText(
+      call,
+      browserId,
+      'Submitted: {"title":"Hello from browser_fill","notes":"First line\\nSecond line"}',
+    );
+    await fillField(call, browserId, "React title", "replacement");
+    await fillField(call, browserId, "React notes", "");
+    await submitForm(call, browserId);
+    await expectPageText(call, browserId, 'Submitted: {"title":"replacement","notes":""}');
+    await fillField(call, browserId, "React title", "");
+    await submitForm(call, browserId);
+    await expectPageText(call, browserId, 'Submitted: {"title":"","notes":""}');
+  } finally {
+    await call("browser_close_tab", { browserId });
+  }
+}
diff --git a/packages/desktop/e2e/browser-tabs.e2e.mjs b/packages/desktop/e2e/browser-tabs.e2e.mjs
index 28afbab94f..668d884b80 100644
--- a/packages/desktop/e2e/browser-tabs.e2e.mjs
+++ b/packages/desktop/e2e/browser-tabs.e2e.mjs
@@ -12,10 +12,12 @@ import { fileURLToPath } from "node:url";
 import { experimental_createMCPClient } from "ai";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { chromium } from "playwright";
+import { expect } from "@playwright/test";
 import { hideDeveloperToasts } from "../../app/e2e/support/developer-ui.mjs";
 import { runAppearanceFontSizeRegression } from "./appearance-font-size.electron.mjs";
 import { runAdaptiveThemeRegression } from "./appearance-theme.electron.mjs";
 import { runSettingsScrollRegression } from "./settings-scroll.electron.mjs";
+import { buildFillFixture, verifyReactFormFill } from "./browser-fill.electron.mjs";
 import { runSettingsMemoryRegression } from "./settings-memory.electron.mjs";
 
 import { seedPluginLinks, runPluginLinksRegression } from "./plugin-links.electron.mjs";
@@ -198,8 +200,38 @@ async function waitForDesktopStatus(page) {
   );
 }
 
+async function settleDesktopStartup(page) {
+  await expect(
+    page.getByRole("button", { name: "Desktop browser workspace 1", exact: true }),
+  ).toBeVisible({ timeout: timeoutMs });
+  // The dev launcher supplies its package directory as an open-project request.
+  // Before the local host connects, that request opens the connection prompt.
+  // Finish startup before exercising the unrelated Settings/browser workflows.
+  const connectionPrompt = page.getByTestId("add-host-method-modal");
+  if (await connectionPrompt.isVisible()) {
+    await connectionPrompt.getByRole("button", { name: "Close", exact: true }).click();
+    await expect(connectionPrompt).toBeHidden();
+  }
+}
+
+const CSP_PAGE_PATH = "/csp-no-eval";
+
 async function startTargetPage() {
-  const server = createServer((_request, response) => {
+  const fillFixture = await buildFillFixture();
+  const server = createServer((request, response) => {
+    if (request.url === "/react-fill") {
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      response.end(fillFixture);
+      return;
+    }
+    if (request.url === CSP_PAGE_PATH) {
+      response.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "content-security-policy": "default-src 'self'; script-src 'self'",
+      });
+      response.end("<!doctype html><title>CSP page</title><h1>CSP page heading</h1>");
+      return;
+    }
     response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
     response.end(`<!doctype html>
       <html>
@@ -231,6 +263,67 @@ async function closeServer(server) {
   await new Promise((resolve) => server.close(resolve));
 }
 
+// browser_logs must report what the server answered: a 404 may not look like a 200.
+async function verifyNetworkLogsReportStatus(client) {
+  const server = createServer((request, response) => {
+    response.writeHead(request.url === "/missing" ? 404 : 200, {
+      "content-type": "text/html; charset=utf-8",
+    });
+    response.end("<!doctype html><title>Status page</title><h1>Status page heading</h1>");
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  assert(address && typeof address !== "string", "Status page did not bind a TCP port");
+  let browserId = null;
+  try {
+    const created = await callBrowserTool(client, "browser_new_tab", {
+      url: `http://127.0.0.1:${address.port}/`,
+    });
+    browserId = created.browserId;
+    assert(
+      typeof browserId === "string",
+      "browser_new_tab returned no browserId for the status page",
+    );
+    await callBrowserTool(client, "browser_wait", {
+      browserId,
+      text: "Status page heading",
+      timeoutMs: 15_000,
+    });
+    const fetched = await callBrowserTool(client, "browser_evaluate", {
+      browserId,
+      function:
+        "async () => { const response = await fetch('/missing'); await response.text(); return response.status; }",
+    });
+    assert(
+      JSON.parse(fetched.resultJson) === 404,
+      `The status page did not answer 404: ${fetched.resultJson}`,
+    );
+    // The browser records a request's timing entry a moment after the response completes.
+    const deadline = Date.now() + 5_000;
+    let seen = [];
+    while (Date.now() < deadline) {
+      const logs = await callBrowserTool(client, "browser_logs", { browserId });
+      seen = logs.network.map((entry) => ({
+        pathname: new URL(entry.url).pathname,
+        status: entry.status ?? null,
+      }));
+      const reported = (pathname, status) =>
+        seen.some((entry) => entry.pathname === pathname && entry.status === status);
+      if (reported("/missing", 404) && reported("/", 200)) return;
+      await delay(100);
+    }
+    throw new Error(
+      `browser_logs did not report 404 for /missing and 200 for the page: ${JSON.stringify(seen)}`,
+    );
+  } finally {
+    if (browserId) await callBrowserTool(client, "browser_close_tab", { browserId });
+    await closeServer(server);
+  }
+}
+
 function mcpPayload(result, command) {
   const payload = result.structuredContent;
   assert(
@@ -275,6 +368,42 @@ async function waitForGuestActiveElement(client, browserId, elementId) {
   return false;
 }
 
+// A page whose Content Security Policy omits 'unsafe-eval' refuses eval(); the tools must still work.
+async function verifyEvaluateOnPageWithoutUnsafeEval(client, targetUrl) {
+  const created = await callBrowserTool(client, "browser_new_tab", {
+    url: new URL(CSP_PAGE_PATH, targetUrl).href,
+  });
+  const browserId = created.browserId;
+  assert(typeof browserId === "string", "browser_new_tab returned no browserId for the CSP page");
+  try {
+    await callBrowserTool(client, "browser_wait", {
+      browserId,
+      text: "CSP page heading",
+      timeoutMs: 15_000,
+    });
+    const title = await callBrowserTool(client, "browser_evaluate", {
+      browserId,
+      function: "() => document.title",
+    });
+    assert(
+      JSON.parse(title.resultJson) === "CSP page",
+      `browser_evaluate on a page without 'unsafe-eval' returned ${title.resultJson}`,
+    );
+    // The control: the page itself really does refuse eval().
+    const probe = await callBrowserTool(client, "browser_evaluate", {
+      browserId,
+      function:
+        '() => { try { (0, eval)("1"); return "eval allowed"; } catch (error) { return error.message; } }',
+    });
+    assert(
+      /Content Security Policy/.test(JSON.parse(probe.resultJson)),
+      `The CSP page did not refuse eval(): ${probe.resultJson}`,
+    );
+  } finally {
+    await callBrowserTool(client, "browser_close_tab", { browserId });
+  }
+}
+
 async function createCallerAgent(daemonPort, workspaceId = workspaceIds[0]) {
   const transport = new StreamableHTTPClientTransport(
     new URL(`http://127.0.0.1:${daemonPort}/mcp/agents`),
@@ -660,6 +789,9 @@ async function runRegression({
     document.body.appendChild(overlayRoot);
   });
 
+  await verifyReactFormFill((name, args) => callBrowserTool(client, name, args), targetUrl);
+  await verifyEvaluateOnPageWithoutUnsafeEval(client, targetUrl);
+
   const created = await callBrowserTool(client, "browser_new_tab", { url: targetUrl });
   const browserId = created.browserId;
   assert(typeof browserId === "string", "browser_new_tab returned no browserId");
@@ -1005,6 +1137,7 @@ async function runRegression({
     JSON.parse(readyStateResult.resultJson) === "complete",
     "Local browser document did not finish loading",
   );
+  await verifyNetworkLogsReportStatus(client);
   // Reproduce the report's mismatch: the guest is complete, but the pane's
   // last loading signal says it is not ready.
   await page.evaluate((id) => {
@@ -1041,6 +1174,10 @@ async function runRegression({
   await page.screenshot({ path: path.join(artifactDir, "local-page-screenshot-selector.png") });
   await originalDeck.getByRole("button", { name: "Cancel element selector" }).click();
 
+  // This journey selects tabs from both pane rails. Keep both columns above the compact-header
+  // breakpoint; narrow panes deliberately replace their rail with a tab dropdown.
+  await resizeDesktopWindow(inspectorPort, { width: 1920, height: 1080 });
+  await page.waitForFunction(() => innerWidth >= 1920, null, { timeout: timeoutMs });
   await originalDeck.getByTestId(`workspace-tab-agent_${callerAgentId}`).click();
   await page.getByTestId("sidebar-search").click();
   await page.getByTestId("command-center-input").fill("Split pane right");
@@ -1087,6 +1224,7 @@ async function runRegression({
     snapshot: "passed",
     click: "passed",
     localPageSelectors: "passed",
+    evaluateWithoutUnsafeEval: "passed",
   };
 }
 
@@ -1208,6 +1346,7 @@ async function main() {
     const page = await waitForAppPage(browser, expoPort);
     await hideDeveloperToasts(page);
     const status = await waitForDesktopStatus(page);
+    await settleDesktopStartup(page);
 
     const checkPluginLinks = () =>
       runPluginLinksRegression({
diff --git a/packages/desktop/e2e/packaged-app-smoke.js b/packages/desktop/e2e/packaged-app-smoke.js
index f1310e287f..1d0cfeb4d8 100644
--- a/packages/desktop/e2e/packaged-app-smoke.js
+++ b/packages/desktop/e2e/packaged-app-smoke.js
@@ -804,6 +804,11 @@ async function openSmokeWorkspace({ appPath, env, page, daemonHome }) {
     ],
     label: "Create packaged smoke workspace",
   });
+  // The fresh daemon had no projects at launch, so first-run setup is open over the sidebar.
+  await page.evaluate(() =>
+    localStorage.setItem("@paseo:onboarding", JSON.stringify({ completedAt: "1970-01-01" })),
+  );
+  await page.reload();
   await page.getByRole("button", { name: "Sandbox smoke workspace", exact: true }).click();
   await page.waitForURL((url) => url.pathname.endsWith(`/workspace/${workspace.workspaceId}`));
   await page.getByRole("button", { name: "Agent", exact: true }).click();
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 074e79b64d..13915279ec 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "private": true,
   "description": "Paseo desktop app (Electron wrapper)",
   "homepage": "https://paseo.sh",
@@ -41,7 +41,6 @@
     "@types/node": "24.6.0",
     "@types/ws": "^8.5.14",
     "electron": "44.2.0",
-    "electron-builder": "26.8.1",
     "typescript": "5.9.3",
     "unzip-crx-3": "^0.2.0",
     "vitest": "^4.1.6",
diff --git a/packages/desktop/src/daemon/daemon-manager.ts b/packages/desktop/src/daemon/daemon-manager.ts
index 769b5513f5..98d5287932 100644
--- a/packages/desktop/src/daemon/daemon-manager.ts
+++ b/packages/desktop/src/daemon/daemon-manager.ts
@@ -30,6 +30,7 @@ import {
   getBundledCliShimPath,
   getCliInstallStatus,
   installCli,
+  uninstallCli,
 } from "../integrations/cli-install/index.js";
 import {
   openLocalTransportSession,
@@ -538,6 +539,7 @@ export function createDaemonCommandHandlers(): Record<string, DesktopCommandHand
     },
     get_local_daemon_version: () => getLocalDaemonVersion(),
     install_cli: () => installCli(),
+    uninstall_cli: () => uninstallCli(),
     get_cli_install_status: () => getCliInstallStatus(),
     read_legacy_skill_selection: () => readLegacySkillSelection(),
     delete_legacy_skill_selection: () => deleteLegacySkillSelection(),
diff --git a/packages/desktop/src/features/browser-automation/service.test.ts b/packages/desktop/src/features/browser-automation/service.test.ts
index 6bc054c6a5..d793e138b7 100644
--- a/packages/desktop/src/features/browser-automation/service.test.ts
+++ b/packages/desktop/src/features/browser-automation/service.test.ts
@@ -1,4 +1,5 @@
 import { resolve as resolvePath } from "node:path";
+import { createContext, runInContext } from "node:vm";
 
 import { describe, expect, test, vi } from "vitest";
 import type {
@@ -434,6 +435,54 @@ function containsScript(tab: FakeTab, ...parts: string[]): boolean {
   return tab.scripts.some((script) => parts.every((part) => script.includes(part)));
 }
 
+/**
+ * A browser whose tab runs the network script the host injects against `performance`, the way a
+ * page runs it, so the test sees what the script reads from Chromium's timing entries.
+ */
+function browserWithTimingEntries(entries: { resource: unknown[]; navigation: unknown[] }) {
+  const browser = new BrowserAutomationHarness();
+  const fakeAnswer = browser.tab.executeJavaScript.bind(browser.tab);
+  const page = createContext({
+    performance: {
+      getEntriesByType: (type: string) =>
+        type === "navigation" ? entries.navigation : entries.resource,
+    },
+  });
+  browser.tab.executeJavaScript = async (script: string) =>
+    script.includes("performance.getEntriesByType")
+      ? runInContext(script, page)
+      : fakeAnswer(script);
+  return browser;
+}
+
+/**
+ * Runs the script the host injects into a page the way Chromium runs it on a page whose Content
+ * Security Policy omits 'unsafe-eval': injected code runs, but code in the page cannot turn a
+ * string into code (eval, new Function). Node's vm refuses string code generation the same way.
+ */
+function pageRunningInjectedScripts(input: {
+  allowEval: boolean;
+  globals?: Record<string, unknown>;
+}) {
+  const page = createContext(
+    { document: { title: "Fixture" }, ...input.globals },
+    { codeGeneration: { strings: input.allowEval, wasm: input.allowEval } },
+  );
+  return (script: string): unknown => runInContext(script, page);
+}
+
+/** A browser whose tab runs the evaluate script in `page`; its other scripts keep the fake answers. */
+function browserEvaluatingIn(page: (script: string) => unknown) {
+  const browser = new BrowserAutomationHarness();
+  const fakeAnswer = browser.tab.executeJavaScript.bind(browser.tab);
+  browser.tab.executeJavaScript = async (script: string) => {
+    if (!script.includes("__PASEO_BROWSER_EVALUATE__")) return fakeAnswer(script);
+    browser.tab.scripts.push(script);
+    return page(script);
+  };
+  return browser;
+}
+
 function requireSnapshotRefs(result: Awaited<ReturnType<BrowserAutomationHarness["snapshot"]>>) {
   expect(result).toEqual({
     requestId: "req-snapshot",
@@ -1406,6 +1455,72 @@ describe("executeAutomationCommand", () => {
     });
   });
 
+  test("logs reports the HTTP status the browser recorded, and none it did not", async () => {
+    const timing = (name: string, initiatorType: string, responseStatus?: number) => ({
+      name,
+      initiatorType,
+      startTime: 1,
+      duration: 2,
+      transferSize: 3,
+      ...(responseStatus === undefined ? {} : { responseStatus }),
+    });
+    const browser = browserWithTimingEntries({
+      resource: [
+        timing("https://a.test/api/orders", "fetch", 404),
+        // Chromium reports 0 for a cross-origin response that sends no Timing-Allow-Origin.
+        timing("https://cdn.test/lib.js", "script", 0),
+        // A browser without the field.
+        timing("https://a.test/old.css", "css"),
+      ],
+      navigation: [timing("https://a.test/form", "navigation", 200)],
+    });
+
+    const result = await browser.execute({ command: "logs", args: { browserId: BROWSER_A } });
+
+    expect(result).toEqual({
+      requestId: "req-logs",
+      ok: true,
+      result: {
+        command: "logs",
+        browserId: BROWSER_A,
+        console: [],
+        network: [
+          {
+            url: "https://a.test/api/orders",
+            type: "fetch",
+            status: 404,
+            startTime: 1,
+            duration: 2,
+            transferSize: 3,
+          },
+          {
+            url: "https://cdn.test/lib.js",
+            type: "script",
+            startTime: 1,
+            duration: 2,
+            transferSize: 3,
+          },
+          {
+            url: "https://a.test/old.css",
+            type: "css",
+            startTime: 1,
+            duration: 2,
+            transferSize: 3,
+          },
+          {
+            url: "https://a.test/form",
+            method: "GET",
+            type: "navigation",
+            status: 200,
+            startTime: 1,
+            duration: 2,
+            transferSize: 3,
+          },
+        ],
+      },
+    });
+  });
+
   test("evaluate returns primitive JSON from the page context", async () => {
     const browser = new BrowserAutomationHarness();
     browser.tab.evaluateScriptResult = { ok: true, resultJson: "42" };
@@ -1558,6 +1673,99 @@ describe("executeAutomationCommand", () => {
     expect(containsScript(browser.tab, "resultJson.slice(0, 79000)")).toBe(true);
   });
 
+  describe.each([
+    { page: "allows eval", allowEval: true },
+    { page: "forbids eval (its Content Security Policy omits 'unsafe-eval')", allowEval: false },
+  ])("evaluate on a page that $page", ({ allowEval }) => {
+    const evaluate = (browser: BrowserAutomationHarness, source: string) =>
+      browser.execute({
+        command: "evaluate",
+        args: { browserId: BROWSER_A, function: source },
+      });
+
+    test("runs the function and returns its result as JSON", async () => {
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval }));
+
+      expect(await evaluate(browser, "() => document.title")).toEqual({
+        requestId: "req-evaluate",
+        ok: true,
+        result: {
+          command: "evaluate",
+          browserId: BROWSER_A,
+          resultJson: '"Fixture"',
+          truncated: false,
+        },
+      });
+    });
+
+    test("awaits an async function", async () => {
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval }));
+
+      const result = await evaluate(
+        browser,
+        "async () => { await Promise.resolve(); return 6 * 7; }",
+      );
+
+      expect(result).toMatchObject({ ok: true, result: { resultJson: "42" } });
+    });
+
+    test("resolves names against the page's globals, never the wrapper's own", async () => {
+      const globals = {
+        element: "page element",
+        args: "page args",
+        value: "page value",
+        resultJson: "page json",
+        userFunction: "page function",
+        __paseoEvaluate: "page wrapper",
+        readFunction: "page reader",
+      };
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval, globals }));
+
+      const result = await evaluate(
+        browser,
+        "() => [element, args, value, resultJson, userFunction, __paseoEvaluate, readFunction]",
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        result: { resultJson: JSON.stringify(Object.values(globals)) },
+      });
+    });
+
+    test("reports what the function throws", async () => {
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval }));
+
+      expect(await evaluate(browser, "() => { throw new Error('boom'); }")).toMatchObject({
+        ok: false,
+        error: { code: "browser_unknown_error", message: "boom" },
+      });
+    });
+
+    test("reports an expression that is not a function", async () => {
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval }));
+
+      expect(await evaluate(browser, "document.title")).toMatchObject({
+        ok: false,
+        error: {
+          code: "browser_unknown_error",
+          message: "browser_evaluate input must evaluate to a function.",
+        },
+      });
+    });
+
+    test("reports a syntax error with the compiler's own message, without touching the page", async () => {
+      const browser = browserEvaluatingIn(pageRunningInjectedScripts({ allowEval }));
+
+      const result = await evaluate(browser, "() => {");
+
+      expect(result).toMatchObject({
+        ok: false,
+        error: { code: "browser_unknown_error", message: expect.stringMatching(/^Unexpected /) },
+      });
+      expect(containsScript(browser.tab, "__PASEO_BROWSER_EVALUATE__")).toBe(false);
+    });
+  });
+
   test("screenshot captures the painted viewport", async () => {
     const browser = new BrowserAutomationHarness();
 
diff --git a/packages/desktop/src/features/browser-automation/service.ts b/packages/desktop/src/features/browser-automation/service.ts
index fe07adecd3..34a01ed074 100644
--- a/packages/desktop/src/features/browser-automation/service.ts
+++ b/packages/desktop/src/features/browser-automation/service.ts
@@ -1,4 +1,5 @@
 import { isAbsolute, relative, resolve as resolvePath } from "node:path";
+import { Script } from "node:vm";
 
 import type {
   BrowserAutomationCommand,
@@ -849,6 +850,11 @@ async function executeEvaluate(
       elementExpression = expression;
     }
 
+    const syntaxError = functionSyntaxError(functionSource);
+    if (syntaxError !== null) {
+      return fail(requestId, "browser_unknown_error", capEvaluateErrorMessage(syntaxError));
+    }
+
     let rawResult: unknown;
     try {
       rawResult = await target.contents.executeJavaScript(
@@ -1550,14 +1556,36 @@ function capEvaluateErrorMessage(message: string): string {
     : message.slice(0, MAX_EVALUATE_ERROR_MESSAGE_LENGTH);
 }
 
+/**
+ * The syntax error in the agent's function, or null. It is compiled here because a script that
+ * fails to compile in the page only reports "Script failed to execute", and a typo deserves the
+ * compiler's own message. Compiling runs nothing.
+ */
+function functionSyntaxError(functionSource: string): string | null {
+  try {
+    void new Script(`(${functionSource})`);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+/**
+ * The page script that runs the agent's function and returns its result as bounded JSON.
+ *
+ * The function goes into the script as code, not as a string for the page to eval(): a page whose
+ * Content Security Policy omits 'unsafe-eval' refuses eval() but still runs what the host injects.
+ * The function-producing thunk is an argument defined outside the wrapper, so its names resolve
+ * against the page's globals without capturing any wrapper parameters or locals.
+ */
 function buildEvaluateScript(
   functionSource: string,
   elementExpression: string | undefined,
 ): string {
-  return String.raw`(async () => {
+  return String.raw`(async (readFunction) => {
     const __PASEO_BROWSER_EVALUATE__ = true;
     try {
-      const userFunction = (0, eval)(${JSON.stringify(`(${functionSource})`)});
+      const userFunction = readFunction();
       if (typeof userFunction !== 'function') {
         throw new Error('browser_evaluate input must evaluate to a function.');
       }
@@ -1582,7 +1610,7 @@ function buildEvaluateScript(
 	    } catch (error) {
 	      return { error: error instanceof Error ? error.message : String(error) };
 	    }
-	  })()`;
+	  })(() => (${functionSource}))`;
 }
 
 async function focusKeypressTarget(
@@ -1628,6 +1656,8 @@ const NETWORK_PERFORMANCE_SCRIPT = String.raw`(() => {
       url: entry.name,
       method: entry.initiatorType === 'navigation' ? 'GET' : undefined,
       type: entry.initiatorType,
+      // 0 when the browser does not say (a cross-origin response without Timing-Allow-Origin).
+      status: typeof entry.responseStatus === 'number' && entry.responseStatus > 0 ? entry.responseStatus : undefined,
       startTime: entry.startTime,
       duration: entry.duration,
       transferSize: typeof entry.transferSize === 'number' ? entry.transferSize : undefined,
diff --git a/packages/desktop/src/features/browser-automation/snapshot-engine.ts b/packages/desktop/src/features/browser-automation/snapshot-engine.ts
index 2ee1a68a5e..e6fc74a3c9 100644
--- a/packages/desktop/src/features/browser-automation/snapshot-engine.ts
+++ b/packages/desktop/src/features/browser-automation/snapshot-engine.ts
@@ -316,7 +316,16 @@ function buildFillScript(metadata: BrowserRefMetadata, value: string): string {
     element.focus();
     const nextValue = ${JSON.stringify(value)};
     if ('value' in element) {
-      element.value = nextValue;
+      const view = element.ownerDocument.defaultView;
+      let prototype = null;
+      if (element.tagName === 'INPUT') {
+        prototype = view.HTMLInputElement.prototype;
+      } else if (element.tagName === 'TEXTAREA') {
+        prototype = view.HTMLTextAreaElement.prototype;
+      }
+      // Bypass instance setters so framework value trackers observe the input event as a change.
+      if (prototype) Object.getOwnPropertyDescriptor(prototype, 'value').set.call(element, nextValue);
+      else element.value = nextValue;
       element.dispatchEvent(new Event('input', { bubbles: true }));
       element.dispatchEvent(new Event('change', { bubbles: true }));
       return { ok: true };
diff --git a/packages/desktop/src/integrations/cli-install/index.ts b/packages/desktop/src/integrations/cli-install/index.ts
index 46c5d5f3f7..195e11dcb0 100644
--- a/packages/desktop/src/integrations/cli-install/index.ts
+++ b/packages/desktop/src/integrations/cli-install/index.ts
@@ -1,2 +1,2 @@
-export { getCliInstallStatus, installCli } from "./install.js";
+export { getCliInstallStatus, installCli, uninstallCli } from "./install.js";
 export { getBundledCliShimPath } from "./paths.js";
diff --git a/packages/desktop/src/integrations/cli-install/install.ts b/packages/desktop/src/integrations/cli-install/install.ts
index cc113daea4..ac5aac7156 100644
--- a/packages/desktop/src/integrations/cli-install/install.ts
+++ b/packages/desktop/src/integrations/cli-install/install.ts
@@ -18,43 +18,44 @@ async function pathOrSymlinkExists(p: string): Promise<boolean> {
   }
 }
 
-export async function installCli(): Promise<InstallStatus> {
-  const targetPath = getCliTargetPath();
-  const shimPath = getBundledCliShimPath();
-  const installSourcePath = resolveCliInstallSourcePath({
+function resolveInstallSourcePath(shimPath: string): string {
+  return resolveCliInstallSourcePath({
     platform: process.platform,
     isPackaged: app.isPackaged,
     executablePath: app.getPath("exe"),
     shimPath,
     appImagePath: process.env.APPIMAGE,
   });
-  const binDir = getLocalBinDir();
+}
 
-  await fs.mkdir(binDir, { recursive: true });
+// A thin .cmd trampoline that delegates to the bundled shim. Only the app install path is baked
+// in — internal details (asar layout, entrypoint scripts) live in the bundled shim and update with
+// the app.
+function buildCmdTrampoline(shimPath: string): string {
+  return [
+    "@echo off",
+    `set "BUNDLED_CLI=${shimPath}"`,
+    `if not exist "%BUNDLED_CLI%" (`,
+    `  echo Paseo CLI not found at %BUNDLED_CLI% — is Paseo installed? 1>&2`,
+    `  exit /b 1`,
+    `)`,
+    `call "%BUNDLED_CLI%" %*`,
+    `exit /b %errorlevel%`,
+  ].join("\r\n");
+}
 
+export async function installCli(): Promise<InstallStatus> {
+  const targetPath = getCliTargetPath();
+  const shimPath = getBundledCliShimPath();
+
+  await fs.mkdir(getLocalBinDir(), { recursive: true });
+  if (await pathOrSymlinkExists(targetPath)) {
+    await fs.unlink(targetPath);
+  }
   if (process.platform === "win32") {
-    if (await pathOrSymlinkExists(targetPath)) {
-      await fs.unlink(targetPath);
-    }
-    // Generate a thin .cmd trampoline that delegates to the bundled shim.
-    // Only the app install path is baked in — internal details (asar layout,
-    // entrypoint scripts) live in the bundled shim and update with the app.
-    const cmdContent = [
-      "@echo off",
-      `set "BUNDLED_CLI=${shimPath}"`,
-      `if not exist "%BUNDLED_CLI%" (`,
-      `  echo Paseo CLI not found at %BUNDLED_CLI% — is Paseo installed? 1>&2`,
-      `  exit /b 1`,
-      `)`,
-      `call "%BUNDLED_CLI%" %*`,
-      `exit /b %errorlevel%`,
-    ].join("\r\n");
-    await fs.writeFile(targetPath, cmdContent, "utf-8");
+    await fs.writeFile(targetPath, buildCmdTrampoline(shimPath), "utf-8");
   } else {
-    if (await pathOrSymlinkExists(targetPath)) {
-      await fs.unlink(targetPath);
-    }
-    await fs.symlink(installSourcePath, targetPath);
+    await fs.symlink(resolveInstallSourcePath(shimPath), targetPath);
   }
 
   const { shellUpdated } = await ensurePathInShellRc();
@@ -65,6 +66,33 @@ export async function installCli(): Promise<InstallStatus> {
   return getCliInstallStatus();
 }
 
+/**
+ * Removes the CLI only when the file at the target is the one this app installs, so a `paseo` the
+ * user put there some other way survives. The shell rc PATH line stays: it is harmless and other
+ * tools in ~/.local/bin rely on it.
+ */
+export async function uninstallCli(): Promise<InstallStatus> {
+  const targetPath = getCliTargetPath();
+  if (await isOwnInstall(targetPath)) {
+    await fs.unlink(targetPath);
+  } else if (await pathOrSymlinkExists(targetPath)) {
+    log.warn("[integrations] Left a paseo CLI this app did not install", { targetPath });
+  }
+  return getCliInstallStatus();
+}
+
+async function isOwnInstall(targetPath: string): Promise<boolean> {
+  const shimPath = getBundledCliShimPath();
+  try {
+    if (process.platform === "win32") {
+      return (await fs.readFile(targetPath, "utf-8")) === buildCmdTrampoline(shimPath);
+    }
+    return (await fs.readlink(targetPath)) === resolveInstallSourcePath(shimPath);
+  } catch {
+    return false;
+  }
+}
+
 export async function getCliInstallStatus(): Promise<InstallStatus> {
   const targetPath = getCliTargetPath();
   return { installed: await pathOrSymlinkExists(targetPath) };
diff --git a/packages/expo-two-way-audio/package.json b/packages/expo-two-way-audio/package.json
index aa86be129b..4e802aa9c1 100644
--- a/packages/expo-two-way-audio/package.json
+++ b/packages/expo-two-way-audio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/expo-two-way-audio",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Native module for two way audio streaming",
   "keywords": [
     "ExpoTwoWayAudio",
diff --git a/packages/highlight/LICENSE b/packages/highlight/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/highlight/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/highlight/package.json b/packages/highlight/package.json
index 6b1d924e05..3bbf84c211 100644
--- a/packages/highlight/package.json
+++ b/packages/highlight/package.json
@@ -1,10 +1,12 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.14.0",
+  "version": "0.15.4",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
-    "src/astro/LICENSE"
+    "src/astro/LICENSE",
+    "src/hcl/LICENSE"
   ],
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/highlight/src/__tests__/highlighter.test.ts b/packages/highlight/src/__tests__/highlighter.test.ts
index 095f9689a8..2a277d0391 100644
--- a/packages/highlight/src/__tests__/highlighter.test.ts
+++ b/packages/highlight/src/__tests__/highlighter.test.ts
@@ -3,6 +3,7 @@ import { setImmediate } from "node:timers/promises";
 import { highlightCodeWithBudget, HIGHLIGHT_MAX_SOURCE_BYTES } from "../budgeted-highlighter.js";
 import type { HighlightToken } from "../types.js";
 import { highlightCode, highlightCodeInSteps, highlightLine } from "../highlighter.js";
+import { getParserForFile } from "../parsers.js";
 
 describe("highlightCode", () => {
   it("highlights JavaScript code with correct token styles", () => {
@@ -344,6 +345,137 @@ const title = "Hello";
   });
 });
 
+describe("Terraform", () => {
+  function styleOf(line: HighlightToken[], text: string) {
+    return line.find((token) => token.text === text)?.style;
+  }
+
+  it("highlights blocks, labels, attributes, and values", () => {
+    const code = [
+      "# The web server",
+      'resource "aws_instance" "web" {',
+      "  count   = 2",
+      "  enabled = true",
+      '  tags    = merge(var.labels, { Name = "web" })',
+      "}",
+    ].join("\n");
+    const result = highlightCode(code, "main.tf");
+
+    expect(result[0][0]).toEqual({ text: "# The web server", style: "comment" });
+    expect(styleOf(result[1], "resource")).toBe("type");
+    expect(styleOf(result[1], '"aws_instance"')).toBe("string");
+    expect(styleOf(result[1], '"web"')).toBe("string");
+    expect(styleOf(result[2], "count")).toBe("definition");
+    expect(styleOf(result[2], "2")).toBe("number");
+    expect(styleOf(result[3], "true")).toBe("literal");
+    expect(styleOf(result[4], "merge")).toBe("function");
+    expect(styleOf(result[4], "var")).toBe("variable");
+    expect(styleOf(result[4], "labels")).toBe("property");
+  });
+
+  it("highlights expressions interpolated inside strings", () => {
+    const result = highlightCode('name = "app-${var.env}-web"', "main.tf");
+
+    expect(result[0].map((token) => [token.text, token.style])).toEqual([
+      ["name", "definition"],
+      [" ", null],
+      ["=", "operator"],
+      [" ", null],
+      ['"app-', "string"],
+      ["${", "punctuation"],
+      ["var", "variable"],
+      [".", "operator"],
+      ["env", "property"],
+      ["}", "punctuation"],
+      ['-web"', "string"],
+    ]);
+  });
+
+  it("highlights heredoc bodies as strings and resumes after the terminator", () => {
+    const code = ["policy = <<-EOT", '  { "Version": "2012" }', "  EOT", "retries = 3"].join("\n");
+    const result = highlightCode(code, "main.tf");
+
+    expect(styleOf(result[0], "EOT")).toBe("keyword");
+    expect(result[1].map((token) => token.style)).toEqual(["string"]);
+    expect(styleOf(result[3], "retries")).toBe("definition");
+    expect(styleOf(result[3], "3")).toBe("number");
+  });
+
+  it("ends a heredoc with a Unicode delimiter", () => {
+    const result = highlightCode("x = <<ÉOF\nfoo\nÉOF\ny = 1", "main.tf");
+
+    expect(styleOf(result[3], "y")).toBe("definition");
+    expect(styleOf(result[3], "1")).toBe("number");
+  });
+
+  it.each([
+    ['x = "$$${var.name}"', "$"],
+    ['x = "%%%{ if true }"', "%"],
+  ])("keeps escaped template text in %s as a string", (code) => {
+    const line = highlightCode(code, "main.tf")[0];
+
+    expect(line[line.length - 1]).toEqual({ text: code.slice(4), style: "string" });
+  });
+
+  it("parses a real configuration without error nodes", () => {
+    const code = [
+      "terraform {",
+      '  required_version = ">= 1.5"',
+      '  backend "s3" {}',
+      "}",
+      "",
+      'variable "subnets" {',
+      "  type    = map(object({ cidr = string }))",
+      "  default = {}",
+      "}",
+      "",
+      "locals {",
+      "  names = [for key, subnet in var.subnets : upper(key) if subnet.cidr != null]",
+      '  first = length(local.names) > 0 ? local.names[0] : "none"',
+      "  arns  = aws_instance.web[*].arn",
+      "  /* block comment */",
+      "  path  = provider::time::rfc3339_parse(timestamp()) // trailing",
+      "}",
+      "",
+      'data "aws_iam_policy_document" "assume" {',
+      '  dynamic "statement" {',
+      "    for_each = var.subnets",
+      "    content {",
+      '      sid = "${statement.key}-%{ if statement.value.cidr != "" }set%{ else }unset%{ endif }"',
+      "    }",
+      "  }",
+      "}",
+      "",
+      'output "script" {',
+      "  value = <<EOT",
+      "#!/bin/sh",
+      "echo ${local.first}",
+      "EOT",
+      "}",
+    ].join("\n");
+
+    const parser = getParserForFile("main.tf");
+    if (!parser) throw new Error("Expected a parser for .tf files");
+    const errors: number[] = [];
+    parser.parse(code).iterate({
+      enter(node) {
+        if (node.type.isError) errors.push(node.from);
+      },
+    });
+
+    expect(errors.map((from) => code.slice(from, from + 30))).toEqual([]);
+  });
+
+  it("uses the same grammar for tfvars and hcl files", () => {
+    expect(highlightCode('region = "eu-west-1"', "prod.tfvars")).toEqual(
+      highlightCode('region = "eu-west-1"', "terragrunt.hcl"),
+    );
+    expect(styleOf(highlightLine('region = "eu-west-1"', "prod.tfvars"), "region")).toBe(
+      "definition",
+    );
+  });
+});
+
 describe("highlightCodeInSteps", () => {
   it("splits a large file into many bounded steps with the same result", () => {
     const code = Array.from(
diff --git a/packages/highlight/src/__tests__/parsers.test.ts b/packages/highlight/src/__tests__/parsers.test.ts
index b24872eb94..b546d889c8 100644
--- a/packages/highlight/src/__tests__/parsers.test.ts
+++ b/packages/highlight/src/__tests__/parsers.test.ts
@@ -22,6 +22,9 @@ describe("isLanguageSupported", () => {
     expect(isLanguageSupported("test.dart")).toBe(true);
     expect(isLanguageSupported("test.cs")).toBe(true);
     expect(isLanguageSupported("test.nix")).toBe(true);
+    expect(isLanguageSupported("main.tf")).toBe(true);
+    expect(isLanguageSupported("prod.tfvars")).toBe(true);
+    expect(isLanguageSupported("terragrunt.hcl")).toBe(true);
     expect(isLanguageSupported("test.ex")).toBe(true);
     expect(isLanguageSupported("Counter.svelte")).toBe(true);
     expect(isLanguageSupported("Page.astro")).toBe(true);
@@ -65,6 +68,9 @@ describe("getSupportedExtensions", () => {
     expect(extensions).toContain("dart");
     expect(extensions).toContain("cs");
     expect(extensions).toContain("nix");
+    expect(extensions).toContain("tf");
+    expect(extensions).toContain("tfvars");
+    expect(extensions).toContain("hcl");
     expect(extensions).toContain("json");
     expect(extensions).toContain("svelte");
     expect(extensions).toContain("astro");
diff --git a/packages/highlight/src/hcl/LICENSE b/packages/highlight/src/hcl/LICENSE
new file mode 100644
index 0000000000..57650a9daf
--- /dev/null
+++ b/packages/highlight/src/hcl/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2021 by Marijn Haverbeke <marijnh@gmail.com> and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/packages/highlight/src/hcl/highlight.ts b/packages/highlight/src/hcl/highlight.ts
new file mode 100644
index 0000000000..9a73b6b7b5
--- /dev/null
+++ b/packages/highlight/src/hcl/highlight.ts
@@ -0,0 +1,41 @@
+import { styleTags, tags as t } from "@lezer/highlight";
+
+export const hclHighlighting = styleTags({
+  "for in if else endfor endif": t.controlKeyword,
+  "Attribute/Identifier": t.definition(t.propertyName),
+  "ObjectKey/Expression/VariableExpr/Identifier": t.definition(t.propertyName),
+  "ObjectKey/Expression/LiteralValue/StringLit!": t.definition(t.propertyName),
+  "ForIntro/Identifier TemplateForStart/Identifier": t.definition(t.variableName),
+  "BlockType!": t.typeName,
+  // Paseo themes have no role for labelName; labels render as the strings they are.
+  "BlockLabel!": t.string,
+  "FunctionNamespace/Identifier": t.namespace,
+  "FunctionName/Identifier": t.function(t.variableName),
+  "VariableExpr/Identifier": t.variableName,
+  "GetAttr/Identifier": t.propertyName,
+  Identifier: t.name,
+  "QuotedTemplateStart QuotedTemplateEnd TemplateLiteral": t.string,
+  NumericLit: t.number,
+  "true false": t.bool,
+  null: t.null,
+  LineComment: t.lineComment,
+  BlockComment: t.blockComment,
+  "( )": t.paren,
+  "{ }": t.brace,
+  "[ ]": t.squareBracket,
+  ArithOp: t.arithmeticOperator,
+  LogicOp: t.logicOperator,
+  CompareOp: t.compareOperator,
+  ControlOp: t.controlOperator,
+  "ControlOp/Colon": t.controlOperator,
+  AssignOp: t.definitionOperator,
+  DerefOp: t.derefOperator,
+  HeredocIdentifier: t.special(t.controlKeyword),
+  HeredocStart: t.operator,
+  "TemplateInterpolationStart TemplateInterpolationEnd": t.special(t.brace),
+  "TemplateDirectiveStart TemplateDirectiveEnd": t.special(t.brace),
+  StripMarker: t.special(t.brace),
+  "AttrSplat FullSplat LegacyIndex": t.derefOperator,
+  "Arrow Ellipsis": t.punctuation,
+  "ObjectElem/Colon ForIntro/Colon Comma NamespaceSeparator": t.separator,
+});
diff --git a/packages/highlight/src/hcl/language.ts b/packages/highlight/src/hcl/language.ts
new file mode 100644
index 0000000000..77722490b8
--- /dev/null
+++ b/packages/highlight/src/hcl/language.ts
@@ -0,0 +1,61 @@
+import {
+  delimitedIndent,
+  foldInside,
+  foldNodeProp,
+  indentNodeProp,
+  LRLanguage,
+} from "@codemirror/language";
+import type { SyntaxNode } from "@lezer/common";
+import { parser } from "./parser.js";
+
+export const hclLanguage = LRLanguage.define({
+  name: "HCL",
+  parser: parser.configure({
+    props: [
+      indentNodeProp.add({
+        Block: delimitedIndent({ closing: "}", align: false }),
+      }),
+      foldNodeProp.add({
+        "Object Tuple TemplateFor TemplateIf": foldInside,
+        BlockComment: (tree: SyntaxNode) => {
+          return { from: tree.from + 2, to: tree.to - 2 };
+        },
+        HeredocTemplate(tree: SyntaxNode) {
+          const start = tree.getChild("HeredocIdentifier");
+          if (!start) {
+            return null;
+          }
+          return {
+            from: start.to,
+            to: tree.to,
+          };
+        },
+        FunctionCall(tree: SyntaxNode) {
+          const start = tree.getChild("(");
+          const end = tree.getChild(")");
+          if (!start || !end) {
+            return null;
+          }
+          return {
+            from: start.from + 1,
+            to: end.to - 1,
+          };
+        },
+        Block(tree: SyntaxNode) {
+          const start = tree.getChild("{");
+          const end = tree.getChild("}");
+          if (!start || !end) {
+            return null;
+          }
+          return {
+            from: start.from + 1,
+            to: end.to - 1,
+          };
+        },
+      }),
+    ],
+  }),
+  languageData: {
+    commentTokens: { line: "#", block: { open: "/*", close: "*/" } },
+  },
+});
diff --git a/packages/highlight/src/hcl/parser.ts b/packages/highlight/src/hcl/parser.ts
new file mode 100644
index 0000000000..fce1a5ffdb
--- /dev/null
+++ b/packages/highlight/src/hcl/parser.ts
@@ -0,0 +1,64 @@
+// Generated by lezer-generator, taken from codemirror-lang-hcl@0.2.0 (MIT, see LICENSE).
+// Vendored for the same reason as packages/highlight/src/nix: only Lezer primitives load here.
+import { LRParser } from "@lezer/lr";
+import { hclHighlighting } from "./highlight.js";
+import {
+  scanQuotedTemplateStart,
+  scanQuotedTemplateEnd,
+  scanTemplateInterpolationStart,
+  scanTemplateInterpolationEnd,
+  scanTemplateDirectiveStart,
+  scanTemplateDirectiveEnd,
+  scanHeredocIdentifier,
+  scanTemplateLiteralChunk,
+  trackTemplate,
+} from "./tokens.js";
+
+const spec_Identifier = new Map<string, number>([
+  ["true", 41],
+  ["false", 43],
+  ["null", 47],
+  ["for", 66],
+  ["in", 70],
+  ["endfor", 74],
+  ["if", 80],
+  ["else", 84],
+  ["endif", 88],
+]);
+export const parser = LRParser.deserialize({
+  version: 14,
+  states:
+    "GxQ]Q&jOOPeO&jOOOmQ&kO'#DcO!kQ&kO'#E_O!yQ&kO'#E^OOQO'#Ea'#EaO#UQ&jO'#ChQOQ&jOOPOOO'#Cd'#CdPOOO)C@`)C@`OOQy'#Co'#CoOOQy'#Cr'#CrO#aQ)vO'#CwOOQy'#Cm'#CmOOQ!b'#D['#D[O#oQ'|O'#DZOOQy'#Cv'#CvO$rQ&kO'#D`O$yQ&jO'#DeO%UQ&jO'#DdO&XQ&kO'#EqO&cQ&kO'#DcOOQy,59},59}O&jQ&jO,59}OOQy'#D]'#D]O(YQ'dO'#DgOOQO'#Ee'#EeO)PQ&jO'#DiO)UQ&jO'#DiOOQy'#Dp'#DpOOQP'#Dx'#DxOOQP'#Dy'#DyO%^Q&kO'#DwO*nQ'dO'#ClOOQy'#Dv'#DvOOQy'#El'#ElO%^Q&kO'#ElOOQy'#Cl'#ClO%^Q&kO,59TO#jQ)`O'#CtOOQP'#E`'#E`OOQP'#Eg'#EgO+eQ&kO,5:xO+pQ&jO,5:xOOQO-E8_-E8_O+xQ+YO'#CuO,ZQ)vO,59`O,iQ&sO'#CxO,sQ)tO'#C{O-OQ)tO'#DSOOQ%n'#Cz'#CzOOQ%n'#Eb'#EbO-ZQ)vO,59cOOQy,59c,59cO-iQ&jO'#DTO-tQ+WO,59uO.SQ&jO'#EpOOQy,59z,59zO._Q&jO,59zO%^Q&kO,5:]O.dQ&jO'#DrOOQP'#E['#E[O%^Q&kO,5:uO.iQ&kO,5:OOOQP'#Ed'#EdO/dQ&kO,5;]O/kQ&kO,5;]O/uQ&kO,5:`OOQy1G/i1G/iOOQO'#Dk'#DkOOQO,5:U,5:UO0pQ&jO'#DlOOQO-E8c-E8cO0xQ&jO,5:TO0}Q&kO,5:TOOQy,5:c,5:cOOQP'#D{'#D{OOQP'#D|'#D|OOQP'#D}'#D}OOQP'#EO'#EOOOQP'#EP'#EPOOQP'#EQ'#EQO%^Q&kO,5:fO%^Q&kO,5:fO%^Q&kO,5:fO%^Q&kO,5:fO%^Q&kO,5:fO%^Q&kO,5:fO%^Q&kO'#ESOOQy'#ER'#ERO1UQ&jO'#EUOOQy'#EX'#EXOOQy'#EY'#EYOOQy'#EW'#EWOOQy,5;W,5;WO1ZQ&jO,5;WO1cQ&jO1G.oO1qQ&lO,59`OOQP-E8e-E8eO1vQ&jO1G0dOOQO1G0d1G0dO1yQ&jO1G0dO+xQ+YO'#EmOOQ%n,59a,59aOOQy1G.z1G.zOOQ%n,59d,59dO2OQ&sO,59dO2YQ&rO,59dOOQ%n,59g,59gO,sQ)tO,59gO2eQ&jO'#DQOOQ%n,59n,59nO2sQ)tO,59nO-OQ)tO,59nO3OQ&jO'#DVOOQ%n-E8`-E8`OOQy1G.}1G.}O3aQ&jO,59hO3fQ&jO,59oO%^Q&kO,59oO3nQ+WO1G/aOOQy1G/a1G/aO3|Q&kO,5;[O4TQ&jO,5;[OOQy1G/f1G/fO4]Q&jO1G/wO4hQ&jO,5:^O4pQ&jO1G0aO4xQ&kO1G/jOOQP,5;O,5;OO5|Q&kO1G0wOOQP-E8b-E8bO7eQ,UO'#DgO7oQ,UO1G/zO9RQ,UO'#ClP9]Q&jO'#DjO9bQ&kO1G/oO9iQ&jO'#DnOOQy1G/o1G/oO9wQ&jO1G/oOOQy1G0Q1G0QO;|Q'dO1G0QO<WQ'dO1G0QO>bQ'dO1G0QO>lQ'dO1G0QO@^Q'dO1G0QOAQQ&jO,5:nOOQy,5:p,5:pPOQy'#Ef'#EfPOQy,5:s,5:sPOQy,5:t,5:tOOQy1G0r1G0rOOQO7+&O7+&OOAYQ&jO7+&OOOQ%n,5;X,5;XOOQ%n1G/O1G/OOA_Q&rO1G/OOAdQ&rO1G/OOOQ%n1G/R1G/ROAoQ&jO,59lOAzQ'[O,59lOOQ%n1G/Y1G/YO2sQ)tO1G/YOBSQ&jO'#DXO2sQ)tO1G/YOBbQ&jO,59qOBpQ'[O,59qOBxQ'[O,59sOCQQ&jO1G/SOCYQ&jO1G/SO%^Q&kO1G/ZOC_Q'[O1G/ZOOQy7+${7+${OCjQ&jO,5:}OC{Q&kO1G0vOOQO-E8a-E8aOOQy7+%c7+%cODSQ&jO7+%cO%^Q&kO'#DsO%^Q&kO1G/xODXQ&jO1G/xOOQP'#E]'#E]O%^Q&kO7+%{P%^Q&kO'#EdO%^Q&kO7+%fOOQy7+%Z7+%ZOD^Q&jO7+%ZODcQ&kO,5:YODjQ&jO,5:YOOQO,5:Y,5:YOOQy1G0Y1G0YPOQy-E8d-E8dOOQO<<Ij<<IjOOQ%n7+$j7+$jODuQ&rO7+$jODzQ'[O1G/WOOQ%n1G/W1G/WOESQ'[O1G/WOOQ%n7+$t7+$tOEXQ&jO,59sO2sQ)tO7+$tOEdQ'[O1G/]OElQ'[O1G/_OOQ$Y1G/]1G/]OEtQ'[O1G/]OOQ%n1G/_1G/_OEyQ'[O1G/_O%^Q&kO7+$nOFOQ&jO7+$nOFTQ&jO7+$nOF]Q'[O7+$uOOQ$Y7+$u7+$uOFhQ'[O7+$uP%^Q&kO'#EcOOQy<<H}<<H}OFmQ&jO,5:_OFxQ&jO7+%dOGQQ&jO7+%dOOQy<<Ig<<IgOGVQ&jO<<IQOHrQ,UO1G0QOJWQ,UO1G0QOKlQ,UO1G0QOMQQ,UO1G0QOMXQ,UO1G0QOOQy<<Hu<<HuOM`Q&kO1G/tOOQO1G/t1G/tOOQ%n<<HU<<HUOOQ%n7+$r7+$rOMgQ'[O7+$rOOQ%n<<H`<<H`OOQ$Y7+$w7+$wOMlQ'[O7+$wOOQ%n7+$y7+$yOMqQ'[O7+$yOMvQ'[O<<HYONRQ&jO<<HYO%^Q&kO<<HYONWQ&jO<<HYOOQ$Y<<Ha<<HaON]Q'[O<<HaOOQP<<IO<<IOO%^Q&kO<<IOOOQyAN>lAN>lONbQ&jOAN>lONgQ&jOAN>lOOQ%n<<H^<<H^OOQ$Y<<Hc<<HcOOQ%n<<He<<HeOOQ$YAN=tAN=tONoQ'[OAN=tO%^Q&kOAN=tONtQ'[OAN=tO! PQ&jOAN=tOOQ$YAN={AN={O! UQ&jOAN>jOOQyG24WG24WO! ^Q&jOG24WOOQ$YG23`G23`O! cQ'[OG23`O! nQ'[OG23`O%^Q&kOG23`OOQPG24UG24UOOQyLD)rLD)rOOQ$YLD(zLD(zO! sQ'[OLD(zO! xQ'[OLD(zOOQ$Y!$'Lf!$'LfO!!TQ'[O!$'LfOOQ$Y!)9BQ!)9BQO!!YQ&kO'#DgO.iQ&kO'#DwO/uQ&kO'#DwO!!|Q&kO'#ClO.iQ&kO,5:fO/uQ&kO,5:fO.iQ&kO,5:fO/uQ&kO,5:fO.iQ&kO,5:fO/uQ&kO,5:fO.iQ&kO,5:fO/uQ&kO,5:fO.iQ&kO,5:fO/uQ&kO,5:fO.iQ&kO,5:fO/uQ&kO,5:fO!#sQ&kO1G0QO!$pQ&kO1G0QO!%mQ&kO1G0QO!(mQ&kO1G0QO!(tQ&kO1G0QO.iQ&kO7+%{O/uQ&kO7+%{O4pQ&jO1G0aO4pQ&jO1G0aO%^Q&kO,5:uO%^Q&kO,5:u",
+  stateData:
+    "!)T~O#_OSXPQYPQ~O^RO!UQO~OXWOYWO~OP[O^iOb]OdYOeYOgZO!RaO!TfO!UeO!atO#b^O#c^O#gnO#hoO~O_vOP#RX^#RX!U#RX~OPwO^xO!U{O~O^RO#[[X!T[X~OQ!VOR!POT!WO#]}O~OV!XO~OP[O^iOb]OdYOeYOgZOq!^O!RaO!UeO!atO#b^O#c^O#gnO#hoO~O!Q!ZO~P#tO#w!_O_!XX!Y!XX~O_!aO!Y!aO~OP[O^iOb]OdYOeYOgZO!RaO!UeO!atO#b^O#c^O#gnO#hoO~Or!cO!T#eX~P%^Oq!^O~PmO!T!fO~O#f!gO!R!ZX!w!ZX!y!ZX#g!ZX#i!ZX#j!ZX#k!ZX#l!ZX#m!ZX#n!ZX#o!ZX#p!ZX#q!ZX#r!ZX#s!ZX#t!ZX#u!ZX#v!ZX#w!ZXr!ZX^!ZX!T!ZX~O_!ZX!Y!ZX!a!`X!Q!ZX![!ZX#[!ZXS!ZXm!ZXx!ZX!c!ZXU!ZX~P&oO^!iO~O!a!lO~O!w!{O!y!|O#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO#q!qO#r!qO#s!rO#t!sO#u!}O#v#OO#w`Xr`X^`X!T`X~O!R!zO_`X!Y`X!Q`X![`X#[`XS`Xm`Xx`X!c`XU`X~P)ZOPwO^xO!U#VO~O^RO!T#WO~O#]#YOQ#aPR#aPT#aPV#aP~OQ#[OR#UXT#UX#]#UX~OS#]Om#^O~P%^OR!POT#bO#]}O~OR!POT#fO#]}O~OQ#hOR!POT!WO#]}O~Om#jOq#iOx#kO~OR!POT!WOV#mO#]}O~Or#nO#w!_O!Q#dX~O!Q#pO~O^#rO~OP[O^&yOb]OdYOeYOgZO!RaO!UeO!atO#b^O#c^O#gnO#hoO~O!T#ea~P%^Or#vO!T#ea~P%^OP[O^#xOb]OdYOeYOgZO!RaO!UeO!atO#b^O#c^O#gnO#hoO~O#f!gO!a!`X~O!a#|O~O![$OO~P%^O^$XO~O![$]O#w!_O~O#w!_O^]i#[]i!T]i~OQ#[O~O^RO!T$^O~OS$aOm$bO~P%^OS$aOm$bO#w!_O~Om$eOq#iOu$fOx#kO~OR!POT$iO#]}O~Om$kOq#iOx#kOz$lO|$mO~O^$nO~Oq$oOx$pO~OR!POT!WOV$rO#]}O~O!Q#da~P%^Or$tO!Q#da~Ox$xO!Q$vO#w!_O~Or$zOs$yO~O!Y${O#w!_O~O#w!_OP!Wi^!Wib!Wid!Wie!Wig!Wir!Wi!R!Wi!T!Wi!U!Wi!a!Wi#b!Wi#c!Wi#g!Wi#h!Wi~O!T#ei~P%^O#f!gO!R!ZX!w!ZX!y!ZX#g!ZX#i!ZX#j!ZX#k!ZX#l!ZX#m!ZX#n!ZX#o!ZX#p!ZX#q!ZX#r!ZX#s!ZX#t!ZX#u!ZX#v!ZX#w!ZX~O!a!`X!i!ZX~P6TO!i%OO#w!_O~O!w!{O!y!|O#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO#q!qO#r!qO#s!rO#t!sO#u!}O#v#OO#w`X~O!R!zO!i`X~P7wO#f!gO~O![%PO~P%^Or%RO!c%TO#w!_O![!bX~O![%PO~O#i!nO#j!nO#k!nO_!ni!R!ni!Y!ni!w!ni!y!ni#m!ni#n!ni#o!ni#p!ni#q!ni#r!ni#s!ni#t!ni#u!ni#v!ni#w!nir!ni!Q!ni![!ni^!ni#[!niS!nim!nix!ni!c!niU!ni!T!ni~O#g!ni#l!ni~P9|O#g!oO#l!oO~P9|O#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO_!ni!R!ni!Y!ni!w!ni!y!ni#s!ni#t!ni#u!ni#v!ni#w!nir!ni!Q!ni![!ni^!ni#[!niS!nim!nix!ni!c!niU!ni!T!ni~O#q!ni#r!ni~P<bO#q!qO#r!qO~P<bO#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO#q!qO#r!qO#s!rO!R!ni!w!ni!y!ni#t!ni#u!ni#v!ni#w!nir!ni^!ni!T!ni~O_!ni!Y!ni!Q!ni![!ni#[!niS!nim!nix!ni!c!niU!ni~P>vO!Q%UO#w!_O~O!T%WO~OS%XO~OS%XOm%YO#w!_O~Oq$oOu%ZOx$pO~OU%[Om%]O~Om%_Oq#iOx#kO|$mO~Oq$oOx$pOz%aO|%bO~OU%cOm%dO~OU%eOm%fO~Or%hOs%gO~O^%iO~OU%kOm%lO#w!_O~O#w!_Or#Va!Q#Va![#Va!c#Va~O!Q#di~P%^O!Q%nO~O^%qO~O![%yO~O![!ba~P%^Or%zO!c%{O![!ba~OS%|O~OU%}Om&OO~OU%}O~Oq$oOx$pO|%bO~OU&QOm&RO~OU&SOm&TO~OU&QO~OU&SO~O^&VO~Or&XOs&WO~OU&YOm&ZO#w!_O~OU&YO~O#w!_O!Q!ga!T!ga~O!Y&[O#w!_O~Os&]O~Ox$xO!T&^O!c&`O#w!_O~O#i!nO#j!nO#k!nO!R!ni!w!ni!y!ni#g!ni#l!ni#m!ni#n!ni#o!ni#p!ni#q!ni#r!ni#s!ni#t!ni#u!ni#v!ni#w!ni~O!i!ni~PGeO#g!oO#i!nO#j!nO#k!nO#l!oO!R!ni!w!ni!y!ni#m!ni#n!ni#o!ni#p!ni#q!ni#r!ni#s!ni#t!ni#u!ni#v!ni#w!ni~O!i!ni~PHyO#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO!R!ni!w!ni!y!ni#q!ni#r!ni#s!ni#t!ni#u!ni#v!ni#w!ni~O!i!ni~PJ_O#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO#q!qO#r!qO!R!ni!i!ni!w!ni!y!ni#t!ni#u!ni#v!ni#w!ni~O#s!ni~PKsO#s!rO~PKsO![!bi~P%^OU&aO~OU&bO~OU&cO~OU&dOm&eO#w!_O~Os&fO~O^&hO~OU&iO~O!T&kO~Ox$xO!T&kO~OU&mO~OU&mOm&oO#w!_O~Os&pO~O!Y&qO#w!_O~O!T&rO~OU&sOm&tO#w!_O~OU&sO~OU&vO~OU&vOm&wO#w!_O~OU&xO~OP!ZXb!ZXd!ZXe!ZXg!ZX!U!ZX!a!ZX#b!ZX#c!ZX#h!ZX~P&oOP`Xb`Xd`Xe`Xg`X!R`X!U`X!a`X#b`X#c`X#h`X~P)ZOP!ni^!nib!nid!nie!nig!nir!ni!T!ni!U!ni!a!ni#b!ni#c!ni#h!ni~PGeOP!ni^!nib!nid!nie!nig!nir!ni!T!ni!U!ni!a!ni#b!ni#c!ni#h!ni~PHyOP!ni^!nib!nid!nie!nig!nir!ni!T!ni!U!ni!a!ni#b!ni#c!ni#h!ni~PJ_O#g!oO#i!nO#j!nO#k!nO#l!oO#m!pO#n!pO#o!pO#p!pO#q!qO#r!qOP!ni^!nib!nid!nie!nig!nir!ni!R!ni!T!ni!U!ni!a!ni!w!ni!y!ni#b!ni#c!ni#h!ni#t!ni#u!ni#v!ni#w!ni~O#s!ni~P!&jO#s!rO~P!&jOb!w!y^X#j^~",
+  goto: "CW#fPPPPPPPP#gPPP#j#sPP#y%xP'YPP'YP(j*O%x*c+sP+s,R,aPPP,oP,R,uP-TP-ZP*c-i%xPP.yPP0Z1n1{P%xP%x2U3g3nP5RP%x5X6i6o5XP%x6x8Y8Y6x9n:W:m;P;`;l;u;zP;uP;u<O<O<T=O=o#s=x>O>S>[>v?Q?WP@kPPPP@qByPPCPCSRXPQVOQ#X{R$_#VXTOU{#V^bQde!c!d#v$}Q!YaQ#RtQ#SvQ#_!PQ#q!]Q#s!`Q#t!aQ#y!eS#}!l#|Q$W!zQ$c#^Q$q#kY$s#n$t%R%m%zQ%j$pQ%o$xQ%p$yU%r$|'`'aQ%s%OQ&U%gQ&g&WQ&j&]Q&n&fQ&u&pQ'b'dR'c'e#msQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'e#m]Qadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'e#l]Qadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eTxSzQ!O[f!T!Q!R!U!X#a#d#e#l$h$j%`R#Tw#m`Qadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'ei!T[!Q!R!U!X#a#d#e#l$h$j%`i!S[!Q!R!U!X#a#d#e#l$h$j%`i!Q[!Q!R!U!X#a#d#e#l$h$j%`Q#`!QR$d#ai!R[!Q!R!U!X#a#d#e#l$h$j%`Q#d!RR$j#eQ#c!RS$g#d#eS%^$h$jR&P%`#m_Qadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'e#mhQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eQVO#mhQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eSdQeS!bd!dV#u!c#v$}_cQde!c!d#v$}#ojQadekptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eZ!hi!i#x#{&y#llQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eR!kkQ$P!lR%Q#|#mmQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eQ!]aR!eeQ$w#qQ&_%sR&l&`#mrQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'e!vpQadeptv!P!]!`!c!d!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p'd'eb&z!a&z&}'P'R'T'V'X'`c&{!e&{'O'Q'S'U'W'Y'a[!tq$R$S$T$U$V[&}&|'Z'[']'^'_]'O#z%t%u%v%w%xY!uq$S$T$U$VY'P&|'[']'^'_Z'Q#z%u%v%w%xW!vq$T$U$VW'R&|']'^'_X'S#z%v%w%xU!wq$U$VU'T&|'^'_V'U#z%w%xS!xq$VS'V&|'_T'W#z%xQ!yqQ'X&|R'Y#zV#Qq#z&|T!{q#zV#Pq#z&|!quQadetv!P!]!`!a!c!d!e!l!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p'`'a'd'e!O!`b!Y#R#S#_#q#s#}$W$c$q$s%j%o%p%s&U&g&j&n&u'b'cQ'd#tR'e#yQ$|#sQ'`'bR'a'cXSOU{#VTySzUUO{#VR|UQ!U[Q#a!QQ#e!R[#g!U#a#e#l$h%`Q#l!XQ$h#dR%`$jQ#o!YS$u#o%SR%S#}Q!ddR#w!d#lkQadeptv!P!]!`!a!c!d!e!l!t!u!v!w!x!y!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p&z&{&}'O'P'Q'R'S'T'U'V'W'X'Y'`'a'd'eR!jkQzSR#Uz!hqQadetv!P!]!`!c!d!l!z#^#k#n#v#|$p$t$x$y$|$}%O%R%g%m%z&W&]&f&p'd'eU!mp&z&{S#z!e'aU$Q!t&}'OQ$R!uQ$S!vQ$T!wQ$U!xQ$V!yQ%t'QQ%u'SQ%v'UQ%w'WQ%x'YS&|!a'`Q'Z'PQ'['RQ']'TQ'^'VR'_'XQ#Z}R$`#YR![aTgQe",
+  nodeNames:
+    "⚠ QuotedTemplateStart QuotedTemplateEnd TemplateInterpolationStart TemplateInterpolationEnd TemplateDirectiveStart TemplateDirectiveEnd HeredocIdentifier Comment LineComment BlockComment ConfigFile Body Attribute Identifier AssignOp Expression LiteralValue NumericLit BoolLit true false NullLit null StringLit TemplateLiteral TemplateExpr QuotedTemplate TemplateInterpolation StripMarker TemplateDirective TemplateFor TemplateForStart for Comma in TemplateForEnd endfor TemplateIf TemplateIfIntro if TemplateElseIntro else TemplateIfEnd endif HeredocTemplate HeredocStart CollectionValue ] [ Tuple } { Object ObjectElem ObjectKey Colon VariableExpr ) FunctionCall FunctionNamespace NamespaceSeparator FunctionName ( FunctionArguments Ellipsis ForExpr ForTupleExpr ForIntro ForCond ForObjectExpr Arrow Operation UnaryOperation ArithOp LogicOp BinaryOperation ArithOp ArithOp CompareOp CompareOp LogicOp LogicOp Index NewIndex LegacyIndex GetAttr DerefOp Splat AttrSplat FullSplat Conditional ControlOp ControlOp Block BlockType BlockLabel",
+  maxTerm: 131,
+  context: trackTemplate,
+  nodeProps: [
+    ["openedBy", 48, "[", 51, "{"],
+    ["closedBy", 49, "]", 52, "}"],
+  ],
+  skippedNodes: [0, 8, 9, 10],
+  repeatNodeCount: 7,
+  tokenData:
+    "-p~RvX^#ipq#iqr$^st$kuv%Svw%Xxy%dyz%iz{%n{|%s|}%x}!O%}!O!P&S!P!Q&z!Q!R(^!R![)l![!]*c!^!_*p!_!`+_!`!a+t!a!b,R!c!},W!}#O,l#P#Q-P#R#S,W#T#o,W#o#p-U#p#q-Z#q#r-f#r#s-k#y#z#i$f$g#i#BY#BZ#i$IS$I_#i$I|$JO#i$JT$JU#i$KV$KW#i&FU&FV#i~#nY#_~X^#ipq#i#y#z#i$f$g#i#BY#BZ#i$IS$I_#i$I|$JO#i$JT$JU#i$KV$KW#i&FU&FV#i~$cP#h~!_!`$f~$kO#r~~$pSX~OY$kZ;'S$k;'S;=`$|<%lO$k~%PP;=`<%l$k~%XO#k~~%[Pvw%_~%dO#s~~%iO!a~~%nO![~~%sO#i~~%xO#l~~%}Or~~&SO#g~~&XR!y~z{&b!O!P&g!Q![&r~&gO#u~~&jP!O!P&m~&rO!c~~&wP!w~!Q![&r~'PQ#j~z{'V!P!Q$k~'YTOz'Vz{'i{;'S'V;'S;=`(W<%lO'V~'lVOz'Vz{'i{!P'V!P!Q(R!Q;'S'V;'S;=`(W<%lO'V~(WOY~~(ZP;=`<%l'V~(cRb~!O!P(l!Q![)l#l#m)w~(oP!Q![(r~(wRb~!Q![(r!g!h)Q#X#Y)Q~)TR{|)^}!O)^!Q![)d~)aP!Q![)d~)iPb~!Q![)d~)qQb~!O!P(l!Q![)l~)zR!Q![*T!c!i*T#T#Z*T~*YRb~!Q![*T!c!i*T#T#Z*T~*hP!Y~![!]*k~*pO#f~~*uQ#o~!^!_*{!_!`+Y~+QP#b~}!O+T~+YO#c~~+_O#p~~+dQ_P!_!`+j!`!a+o~+oO#q~Q+tO!iQ~+yP#m~!_!`+|~,RO#n~~,WO#w~~,]T^~}!O,W!Q![,W!c!},W#R#S,W#T#o,W~,qP!R~z{,t~,wP#P#Q,z~-PO#v~~-UO!Q~~-ZO!U~~-^P#p#q-a~-fO#t~~-kO!T~~-pOm~",
+  tokenizers: [
+    scanQuotedTemplateStart,
+    scanQuotedTemplateEnd,
+    scanTemplateInterpolationStart,
+    scanTemplateInterpolationEnd,
+    scanTemplateDirectiveStart,
+    scanTemplateDirectiveEnd,
+    scanHeredocIdentifier,
+    scanTemplateLiteralChunk,
+    0,
+    1,
+  ],
+  topRules: { ConfigFile: [0, 11] },
+  dynamicPrecedences: { "19": 1, "22": 1 },
+  specialized: [{ term: 14, get: (value: string) => spec_Identifier.get(value) ?? -1 }],
+  propSources: [hclHighlighting],
+  tokenPrec: 2481,
+});
diff --git a/packages/highlight/src/hcl/terms.ts b/packages/highlight/src/hcl/terms.ts
new file mode 100644
index 0000000000..e4fc0621f7
--- /dev/null
+++ b/packages/highlight/src/hcl/terms.ts
@@ -0,0 +1,10 @@
+// Generated by lezer-generator, taken from codemirror-lang-hcl@0.2.0 (MIT, see LICENSE).
+// Vendored for the same reason as packages/highlight/src/nix: only Lezer primitives load here.
+export const QuotedTemplateStart = 1;
+export const QuotedTemplateEnd = 2;
+export const TemplateInterpolationStart = 3;
+export const TemplateInterpolationEnd = 4;
+export const TemplateDirectiveStart = 5;
+export const TemplateDirectiveEnd = 6;
+export const HeredocIdentifier = 7;
+export const templateLiteralChunk = 105;
diff --git a/packages/highlight/src/hcl/tokens.ts b/packages/highlight/src/hcl/tokens.ts
new file mode 100644
index 0000000000..d88d45e7fb
--- /dev/null
+++ b/packages/highlight/src/hcl/tokens.ts
@@ -0,0 +1,317 @@
+// Taken from codemirror-lang-hcl@0.2.0 (MIT, see LICENSE).
+// Vendored for the same reason as packages/highlight/src/nix: only Lezer primitives load here.
+import { ContextTracker, ExternalTokenizer, type InputStream } from "@lezer/lr";
+import {
+  QuotedTemplateStart,
+  QuotedTemplateEnd,
+  TemplateInterpolationStart,
+  TemplateInterpolationEnd,
+  TemplateDirectiveStart,
+  TemplateDirectiveEnd,
+  HeredocIdentifier,
+  templateLiteralChunk,
+} from "./terms.js";
+
+const ContextType = {
+  QUOTED_TEMPLATE: 1,
+  TEMPLATE_INTERPOLATION: 2,
+  TEMPLATE_DIRECTIVE: 4,
+  HEREDOC_TEMPLATE: 8,
+};
+
+const hashStr = function (str: string) {
+  var hash = 0,
+    i,
+    chr;
+  if (str.length === 0) return hash;
+  for (i = 0; i < str.length; i++) {
+    chr = str.charCodeAt(i);
+    hash = (hash << 5) - hash + chr;
+    hash |= 0; // Convert to 32bit integer
+  }
+  return hash;
+};
+
+class Context {
+  readonly parent: Context | null;
+  readonly type: number;
+  readonly heredoc_identifier: string;
+  readonly hash: number;
+
+  constructor(parent: Context | null, type: number, heredoc_identifier: string) {
+    this.parent = parent;
+    this.type = type;
+    this.heredoc_identifier = heredoc_identifier;
+    this.hash =
+      (parent ? (parent.hash + parent.hash) << 8 : 0) +
+      (type << 4) +
+      (this.heredoc_identifier === "" ? 0 : hashStr(this.heredoc_identifier));
+  }
+}
+
+function readTokenText(input: InputStream, end: number): string {
+  let text = "";
+  for (let offset = 0; offset < end - input.pos; offset++) {
+    text += String.fromCharCode(input.peek(offset));
+  }
+  return text;
+}
+
+const topCtx = new Context(null, 0, "");
+
+export const trackTemplate = new ContextTracker({
+  start: topCtx,
+  shift(context, term, stack, input) {
+    if (term === QuotedTemplateStart) {
+      return new Context(context, ContextType.QUOTED_TEMPLATE, "");
+    }
+    if (term === TemplateInterpolationStart) {
+      return new Context(context, ContextType.TEMPLATE_INTERPOLATION, "");
+    }
+    if (term === TemplateDirectiveStart) {
+      return new Context(context, ContextType.TEMPLATE_DIRECTIVE, "");
+    }
+    if (term === HeredocIdentifier && context.type !== ContextType.HEREDOC_TEMPLATE) {
+      const ctx = new Context(
+        context,
+        ContextType.HEREDOC_TEMPLATE,
+        readTokenText(input, stack.pos),
+      );
+      return ctx;
+    }
+
+    if (term === HeredocIdentifier && context.type === ContextType.HEREDOC_TEMPLATE) {
+      return context.parent ?? context;
+    }
+    switch (term) {
+      case QuotedTemplateEnd:
+      case TemplateInterpolationEnd:
+      case TemplateDirectiveEnd:
+        return context.parent ?? context;
+    }
+
+    return context;
+  },
+  hash(context) {
+    return context.hash;
+  },
+});
+
+const HEX_DIGIT = /[0-9a-fA-F]/;
+
+function scanEscapeSequence(input: InputStream): void {
+  input.advance();
+  const kind = String.fromCharCode(input.next);
+  if (kind === "u" || kind === "U") {
+    const digits = kind === "u" ? 4 : 8;
+    for (let i = 0; i < digits; i++) {
+      input.advance();
+      if (!HEX_DIGIT.test(String.fromCharCode(input.next))) return;
+    }
+  } else if (!'"nrt\\'.includes(kind)) {
+    return;
+  }
+  input.advance();
+  input.acceptToken(templateLiteralChunk);
+}
+
+function scanHeredocBody(input: InputStream, expected: string): void {
+  let has_leading_whitespace_with_newline = false;
+  let has_leading_whitespace = false;
+  let next = String.fromCharCode(input.next);
+  while (/\s/.test(next)) {
+    has_leading_whitespace = true;
+    if (next === "\n") {
+      has_leading_whitespace_with_newline = true;
+    }
+    input.advance();
+    next = String.fromCharCode(input.next);
+  }
+  if (has_leading_whitespace) {
+    input.acceptToken(templateLiteralChunk);
+  }
+
+  if (!has_leading_whitespace_with_newline) {
+    return;
+  }
+
+  let advance = 0;
+  for (let i = 0; i < expected.length; i++) {
+    if (String.fromCharCode(input.next) === expected[i]) {
+      input.advance();
+      advance++;
+    } else {
+      if (advance) {
+        input.acceptToken(templateLiteralChunk);
+      }
+      return;
+    }
+  }
+
+  // check if the identifier is on a line of its own
+  let i = 0;
+  while (true) {
+    const ch = input.peek(i);
+    if (ch == -1 || String.fromCharCode(ch) === "\n") {
+      return input.acceptToken(HeredocIdentifier);
+    }
+
+    if (!/\s/.test(String.fromCharCode(ch))) {
+      return input.acceptToken(templateLiteralChunk);
+    }
+
+    i++;
+  }
+}
+
+// `$${` and `%%{` are escapes. The doubled marker counts only when `{` follows it, so in `$$${`
+// the first `$` is literal text and the rest is the escape.
+function scanTemplateMarker(input: InputStream, marker: string, startToken: number): void {
+  input.advance();
+  if (String.fromCharCode(input.next) === "{") {
+    input.advance();
+    return input.acceptToken(startToken);
+  }
+  if (String.fromCharCode(input.next) === marker && String.fromCharCode(input.peek(1)) === "{") {
+    input.advance();
+    input.advance();
+  }
+  input.acceptToken(templateLiteralChunk);
+}
+
+export const scanQuotedTemplateStart = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(QuotedTemplateStart) &&
+      !(stack.context && stack.context.type === ContextType.QUOTED_TEMPLATE) &&
+      String.fromCharCode(input.next) === '"'
+    ) {
+      input.advance();
+      return input.acceptToken(QuotedTemplateStart);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+export const scanQuotedTemplateEnd = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(QuotedTemplateEnd) &&
+      stack.context &&
+      stack.context.type === ContextType.QUOTED_TEMPLATE &&
+      String.fromCharCode(input.next) === '"'
+    ) {
+      input.advance();
+      return input.acceptToken(QuotedTemplateEnd);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+
+export const scanTemplateLiteralChunk = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(templateLiteralChunk) &&
+      stack.context &&
+      stack.context.type === ContextType.QUOTED_TEMPLATE
+    ) {
+      if (String.fromCharCode(input.next) === "\\") {
+        return scanEscapeSequence(input);
+      }
+    }
+
+    if (
+      stack.canShift(templateLiteralChunk) &&
+      stack.context &&
+      (stack.context.type === ContextType.QUOTED_TEMPLATE ||
+        stack.context.type === ContextType.HEREDOC_TEMPLATE) &&
+      input.next !== -1
+    ) {
+      input.advance();
+      return input.acceptToken(templateLiteralChunk);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+export const scanTemplateInterpolationStart = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(TemplateInterpolationStart) &&
+      stack.canShift(templateLiteralChunk) &&
+      !(stack.context && stack.context.type === ContextType.TEMPLATE_INTERPOLATION) &&
+      String.fromCharCode(input.next) === "$"
+    ) {
+      return scanTemplateMarker(input, "$", TemplateInterpolationStart);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+export const scanTemplateInterpolationEnd = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(TemplateInterpolationEnd) &&
+      stack.context &&
+      stack.context.type === ContextType.TEMPLATE_INTERPOLATION &&
+      String.fromCharCode(input.next) === "}"
+    ) {
+      input.advance();
+      return input.acceptToken(TemplateInterpolationEnd);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+export const scanTemplateDirectiveStart = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(TemplateDirectiveStart) &&
+      stack.canShift(templateLiteralChunk) &&
+      !(stack.context && stack.context.type === ContextType.TEMPLATE_DIRECTIVE) &&
+      String.fromCharCode(input.next) === "%"
+    ) {
+      return scanTemplateMarker(input, "%", TemplateDirectiveStart);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+export const scanTemplateDirectiveEnd = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(TemplateDirectiveEnd) &&
+      stack.context &&
+      stack.context.type === ContextType.TEMPLATE_DIRECTIVE &&
+      String.fromCharCode(input.next) === "}"
+    ) {
+      input.advance();
+      return input.acceptToken(TemplateDirectiveEnd);
+    }
+  },
+  { contextual: true, fallback: true },
+);
+
+export const scanHeredocIdentifier = new ExternalTokenizer(
+  (input, stack) => {
+    if (
+      stack.canShift(HeredocIdentifier) &&
+      !(stack.context && stack.context.type === ContextType.HEREDOC_TEMPLATE) &&
+      input.next !== -1
+    ) {
+      let next = String.fromCharCode(input.next);
+      while (/[\p{L}\p{N}_-]/u.test(next)) {
+        input.advance();
+        next = String.fromCharCode(input.next);
+      }
+
+      return input.acceptToken(HeredocIdentifier);
+    }
+
+    if (
+      stack.canShift(HeredocIdentifier) &&
+      stack.canShift(templateLiteralChunk) &&
+      stack.context &&
+      stack.context.type === ContextType.HEREDOC_TEMPLATE &&
+      input.next != -1
+    ) {
+      return scanHeredocBody(input, stack.context.heredoc_identifier);
+    }
+  },
+  { contextual: true, fallback: true },
+);
diff --git a/packages/highlight/src/parsers.ts b/packages/highlight/src/parsers.ts
index 06c3129733..1f1d2b037d 100644
--- a/packages/highlight/src/parsers.ts
+++ b/packages/highlight/src/parsers.ts
@@ -20,6 +20,7 @@ import { csharpLanguage } from "./csharp/language.js";
 import { astroParser } from "./astro/parser.js";
 import { vueParser } from "./vue/parser.js";
 import { nixLanguage } from "./nix/language.js";
+import { hclLanguage } from "./hcl/language.js";
 import { parser as svelteBaseParser } from "./svelte/parser.js";
 import { configureNesting, defaultNesting } from "./svelte/nesting.js";
 
@@ -82,6 +83,10 @@ const languagesByExtension: Record<string, Language> = {
   cs: csharpLanguage,
   // Nix
   nix: nixLanguage,
+  // Terraform / HCL
+  tf: hclLanguage,
+  tfvars: hclLanguage,
+  hcl: hclLanguage,
   // Elixir
   ex: language(elixirParser),
   exs: language(elixirParser),
diff --git a/packages/plugin/LICENSE b/packages/plugin/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/plugin/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/plugin/package.json b/packages/plugin/package.json
index 32cb48e026..0a4002927e 100644
--- a/packages/plugin/package.json
+++ b/packages/plugin/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo plugin SDK package",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map"
@@ -77,8 +78,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.14.0",
-    "@getpaseo/protocol": "0.14.0",
+    "@getpaseo/client": "0.15.4",
+    "@getpaseo/protocol": "0.15.4",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.2.3",
@@ -88,8 +89,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@getpaseo/client": "0.14.0",
-    "@getpaseo/protocol": "0.14.0",
+    "@getpaseo/client": "0.15.4",
+    "@getpaseo/protocol": "0.15.4",
     "react": ">=19.1.0 <20",
     "react-native": ">=0.81.5",
     "zod": "^4.4.3"
diff --git a/packages/plugin/src/boundaries.test.ts b/packages/plugin/src/boundaries.test.ts
index b0834956d6..2a1ddae8f7 100644
--- a/packages/plugin/src/boundaries.test.ts
+++ b/packages/plugin/src/boundaries.test.ts
@@ -213,6 +213,134 @@ describe("plugin panel SDK boundary", () => {
   });
 });
 
+describe("plugin composer SDK boundary", () => {
+  it("lets a composer item read and change the composer through typed commands and controls", () => {
+    expect(
+      typeErrors(`
+      import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+      import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+      function Item() {
+        const composer = useComposer();
+        const context: "agent" | "draft" | "new-workspace" = composer.context;
+        const provider: string | null = composer.agent.provider;
+        const flag: boolean = composer.agent.metadata.flag === true;
+        // @ts-expect-error reads are not writable
+        composer.agent.model = "other";
+        composer.setProvider("codex").then(() => composer.setModel("gpt"));
+        composer.setOptions({ effort: null });
+        composer.setMetadata({ flag: true, stale: null });
+        composer.insertText("text");
+        composer.focus({ selection: { start: 0, end: composer.prompt.length } }).then(() => composer.focus());
+        composer.addAttachment({ sourceId: "issues", item: { id: "1", identifier: "1", title: "t", url: "https://e.com", text: "t", resourceType: "issue" } });
+        // @ts-expect-error commands take JSON values
+        composer.setMetadata({ fn: () => {} });
+        return (
+          <>
+            <Toggle title="Flag" icon="Flag" value={flag} onValueChange={({ value }: { value: boolean }) => composer.setMetadata({ flag: value })} />
+            <Select title="Size" icon="Gauge" value="a" options={[{ value: "a", label: "A" }, { value: "b", label: "B" }]} onValueChange={({ value }: { value: "a" | "b" }) => {}} />
+            <Action title="Insert" icon="Plus" onPress={() => composer.setPrompt("")} />
+          </>
+        );
+      }
+      export default function contribute(client: PluginClientContext) {
+        client.addComposerItem({ id: "item", Component: Item });
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
+describe("plugin composers by reference SDK boundary", () => {
+  it("reaches a running agent's composer from any component and from every command context", () => {
+    expect(
+      typeErrors(`
+      import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
+      function Button() {
+        const [focused] = useComposers({ focused: true });
+        const byId = useComposers({ agentId: "agent-1" });
+        if (!focused) return null;
+        const first: string = byId[0]?.prompt ?? "";
+        focused.insertText("text");
+        focused.setMetadata({ flag: true });
+        // @ts-expect-error a selector names an agent or the focused agent
+        useComposers({ active: true });
+        // @ts-expect-error focused is true or absent
+        useComposers({ focused: false });
+        return null;
+      }
+      export default function contribute(client: PluginClientContext) {
+        client.addWorkspacePanel({ id: "panel", title: "P", icon: "File", context: "workspace", Component: Button });
+        client.addCommandCenterItem({
+          id: "mark",
+          title: "Mark",
+          icon: "Flag",
+          context: "agent",
+          async onSelect(context) {
+            for (const composer of context.composers({ agentId: context.agent.id })) {
+              await composer.setMetadata({ review: true });
+            }
+          },
+        });
+        client.addCommandCenterItem({
+          id: "global",
+          title: "Global",
+          icon: "Flag",
+          context: "global",
+          onSelect: ({ composers }) => composers({ focused: true })[0]?.insertText("x"),
+        });
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
+describe("plugin New workspace SDK boundary", () => {
+  it("lets a New workspace item read the setup and change it through typed commands and a Combobox", () => {
+    expect(
+      typeErrors(`
+      import { useNewWorkspace, type PluginClientContext } from "@getpaseo/plugin/client";
+      import { Combobox } from "@getpaseo/plugin/client/ui";
+      interface Issue { id: string; label: string; branch: string }
+      function Item() {
+        const newWorkspace = useNewWorkspace();
+        const isolation: "local" | "worktree" = newWorkspace.isolation;
+        const branch: string | null = newWorkspace.branch;
+        const project: string | undefined = newWorkspace.project?.name;
+        const host: string = newWorkspace.host.label;
+        const base = newWorkspace.baseRef;
+        if (base?.type === "branch") { const name: string = base.name; }
+        // @ts-expect-error project is read-only
+        newWorkspace.project = null;
+        // @ts-expect-error host is read-only
+        newWorkspace.setHost("other");
+        // @ts-expect-error metadata reads are not writable
+        newWorkspace.metadata.key = "x";
+        newWorkspace.setIsolation("worktree").then(() => newWorkspace.setBaseRef({ type: "branch", name: "main" }));
+        newWorkspace.setBranch(null);
+        newWorkspace.setMetadata({ issue: "1", stale: null });
+        // @ts-expect-error commands take JSON values
+        newWorkspace.setMetadata({ fn: () => {} });
+        return (
+          <Combobox<Issue>
+            title="Issue"
+            icon="CircleDot"
+            value={{ id: "1", label: "One" }}
+            search={async ({ query }: { query: string }) => [{ id: query, label: query, branch: "b" }]}
+            onSelect={({ item }) => newWorkspace.setBranch(item.branch)}
+          />
+        );
+      }
+      export default function contribute(client: PluginClientContext) {
+        client.addNewWorkspaceItem({ id: "item", Component: Item });
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
 describe("plugin agent tools SDK boundary", () => {
   it("lets a session hook attach typed tools without exposing their transport", () => {
     expect(
@@ -283,6 +411,10 @@ describe("lifecycle hook SDK types", () => {
         server.addHook("workspace.create.before", async ({ request }) => ({ ...request, title: "Changed" }));
         server.addHook("workspace.create.before", async () => {});
         server.addHook("agent.open.before", async () => {});
+        server.addHook("agent.open.before", async ({ request }) => {
+          const { metadata, ...withoutMetadata } = request;
+          return withoutMetadata;
+        });
         server.addHook("agent.turn.after", async ({ agent, outcome, timeline }, { paseo, signal }) => {
           const kind: "completed" | "failed" | "canceled" = outcome.kind;
           // @ts-expect-error Notification payloads have no creation request.
@@ -323,3 +455,110 @@ describe("agent session reload SDK boundary", () => {
     ).toEqual([]);
   });
 });
+
+describe("plugin subscription SDK boundary", () => {
+  it("types contracts, overloaded handlers, the client hook, and the client entry handle", () => {
+    expect(
+      typeErrors(`
+      import { defineRpc, defineSubscription, type SubscriptionEvent, type SubscriptionInput } from "@getpaseo/plugin";
+      import type { PluginClientContext } from "@getpaseo/plugin/client";
+      import { useRpc, useSubscription } from "@getpaseo/plugin/client";
+      import type { PluginServerContext, PluginSubscriptionContext } from "@getpaseo/plugin/server";
+      import { z } from "zod";
+      const diffWatch = defineSubscription({
+        name: "diff.watch",
+        input: z.object({ a: z.string(), b: z.string() }),
+        event: z.object({ path: z.string(), status: z.enum(["added", "modified", "deleted"]) }),
+      });
+      const frames = defineSubscription({
+        name: "screen.capture",
+        input: z.object({ display: z.number() }),
+        event: z.union([z.instanceof(Uint8Array), z.object({ type: z.literal("resized"), width: z.number() })]),
+      });
+      const thumbnail = defineRpc({ name: "thumbnail.render", input: z.object({ path: z.string() }), output: z.instanceof(Uint8Array) });
+      const input: SubscriptionInput<typeof diffWatch> = { a: "main", b: "HEAD" };
+      const event: SubscriptionEvent<typeof diffWatch> = { path: "a.ts", status: "added" };
+      function server(server: PluginServerContext) {
+        server.handle(diffWatch, ({ a, b }, { push, signal, paseo }: PluginSubscriptionContext<SubscriptionEvent<typeof diffWatch>>) => {
+          const pushed: Promise<void> = push({ path: a + b, status: "modified" });
+          // @ts-expect-error events follow the contract
+          void push({ path: 1, status: "modified" });
+          signal.addEventListener("abort", () => undefined, { once: true });
+        });
+        server.handle(frames, async (_input, { push }) => {
+          await push(new Uint8Array(4));
+          await push({ type: "resized", width: 2 });
+        });
+        server.handle(thumbnail, ({ path }) => new Uint8Array(path.length));
+        // @ts-expect-error subscription handlers receive push, not an output
+        server.handle(diffWatch, () => ({ path: "a", status: "added" as const }) as unknown as number);
+      }
+      function Panel() {
+        const state = useSubscription(diffWatch, { a: "main", b: "HEAD" }, (change) => {
+          const status: "added" | "modified" | "deleted" = change.status;
+        });
+        if (state.status === "error") state.error.message;
+        // @ts-expect-error the hook has no ready state, only live
+        if (state.status === "ready") return null;
+        useSubscription(frames, { display: 1 }, (event) => {
+          if (event instanceof Uint8Array) event.byteLength;
+          else event.width;
+        });
+        const render = useRpc(thumbnail);
+        void render({ path: "x" }).then((png: Uint8Array) => png.byteLength);
+        return null;
+      }
+      function client(client: PluginClientContext) {
+        const controller = new AbortController();
+        const remover = client.subscribe(diffWatch, { a: "main", b: "HEAD" }, (change) => change.path, { signal: controller.signal });
+        const ready: Promise<void> = remover.ready;
+        const released: Promise<void> = remover.release();
+        remover();
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
+describe("sidebar data SDK boundary", () => {
+  it("accepts references and preserves string-id panel consumers", () => {
+    expect(
+      typeErrors(`
+      import { useWorkspace, useAgent, usePaseo, type PluginClientContext, type PluginSidebarViewProps, type WorkspaceRef, type AgentRef, useProject, useTerminal, useWorkspaces, useAgents, useProjects, useTerminals, type ProjectRef, type TerminalRef, type Query, type Group } from "@getpaseo/plugin/client";
+      import type { PluginWorkspaceSnapshot } from "@getpaseo/plugin";
+      function Panel({ workspace, agent }: { workspace: WorkspaceRef; agent: AgentRef }) {
+        const snapshot: PluginWorkspaceSnapshot | null = useWorkspace(workspace);
+        const title: string | null = useWorkspace("workspace", item => item.name);
+        const status = useAgent(agent, item => ({ status: item.status }), (a, b) => a?.status === b?.status);
+        const agentSnapshot = useAgent(agent);
+        const custom = useWorkspace(workspace, undefined, (a, b) => a?.name === b?.name);
+        const workspaces: readonly WorkspaceRef[] = useWorkspaces({ orderBy: "name" });
+        const groups: readonly Group<AgentRef>[] = useAgents({ groupBy: item => item.status });
+        const projects: readonly ProjectRef[] = useProjects({ hosts: [workspace.hostId] });
+        const terminals: readonly TerminalRef[] = useTerminals();
+        const paseo = usePaseo();
+        void paseo.workspaces.ref(workspace).setPinned(true);
+        void paseo.workspaces.ref(workspace).setLabel("Later", { assigned: true });
+        void paseo.workspaces.ref("old-id").setTitle("Title");
+        if (projects[0]) { paseo.projects.ref(projects[0]).open(); void paseo.projects.ref(projects[0]).createWorkspace(); }
+        if (terminals[0]) { paseo.terminals.ref(terminals[0]).focus(); void paseo.terminals.ref(terminals[0]).kill(); }
+        void paseo.agents.ref(agent);
+        if (projects[0]) useProject(projects[0], item => item.displayName);
+        if (terminals[0]) useTerminal(terminals[0]);
+        function View(props: PluginSidebarViewProps) {
+          props.navigation.openWorkspace(workspace);
+          props.navigation.openAgent(agent);
+          props.dismiss();
+          return null;
+        }
+        function contribute(client: PluginClientContext) {
+          client.addSidebarView({ id: "workspaces", title: "Workspaces", Component: View });
+        }
+        const query: Query<PluginWorkspaceSnapshot> = { hosts: [workspace.hostId], orderBy: ["name", "desc"] };
+        return null;
+      }
+    `),
+    ).toEqual([]);
+  });
+});
diff --git a/packages/plugin/src/client/client-state.tsx b/packages/plugin/src/client/client-state.tsx
index b1c853ecec..db2a6b5f5a 100644
--- a/packages/plugin/src/client/client-state.tsx
+++ b/packages/plugin/src/client/client-state.tsx
@@ -1,12 +1,30 @@
-import { createContext, useContext, type ReactNode } from "react";
+import { createContext, useContext, useMemo, type ReactNode } from "react";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
-import type { PluginAgentSnapshot, PluginWorkspaceSnapshot } from "../contracts.js";
+import type { AgentRef, WorkspaceRef, ProjectRef, TerminalRef } from "../refs.js";
+import type {
+  PluginAgentSnapshot,
+  PluginWorkspaceSnapshot,
+  PluginProjectSnapshot,
+  PluginTerminalSnapshot,
+} from "../contracts.js";
+import { createCollectionQuery, type Query, type Group } from "./query.js";
 import { shallowEqual } from "./shallow.js";
 
 export interface PluginClientStateSource {
-  subscribe(listener: () => void): () => void;
-  getWorkspace(id: string): PluginWorkspaceSnapshot | null;
-  getAgent(id: string): PluginAgentSnapshot | null;
+  subscribe(listener: () => void, options?: { terminals?: boolean }): () => void;
+  getWorkspace(id: string | WorkspaceRef): PluginWorkspaceSnapshot | null;
+  getAgent(id: string | AgentRef): PluginAgentSnapshot | null;
+  getProject(ref: ProjectRef): PluginProjectSnapshot | null;
+  getTerminal(ref: TerminalRef): PluginTerminalSnapshot | null;
+  getSnapshot(): PluginClientSnapshot;
+}
+
+export interface PluginClientSnapshot {
+  readonly workspaces: readonly PluginWorkspaceSnapshot[];
+  readonly agents: readonly PluginAgentSnapshot[];
+  readonly projects: readonly PluginProjectSnapshot[];
+  readonly terminals: readonly PluginTerminalSnapshot[];
+  readonly terminalErrors?: ReadonlyMap<string, Error>;
 }
 
 const PluginClientStateContext = createContext<PluginClientStateSource | null>(null);
@@ -15,44 +33,113 @@ export function usePluginClientStateSource(): PluginClientStateSource | null {
   return useContext(PluginClientStateContext);
 }
 
-function usePluginEntity<Entity, Selection>(input: {
-  id: string;
-  read(source: PluginClientStateSource, id: string): Entity | null;
-  selector(entity: Entity): Selection;
-}): Selection | null {
+/** Shared selection semantics for host surfaces and plugin entities. */
+export function usePaseoSelector<Entity, Selection>(
+  source: { subscribe(listener: () => void): () => void },
+  read: () => Entity,
+  selector: (entity: Entity) => Selection,
+  equals: (left: Selection, right: Selection) => boolean = shallowEqual,
+): Selection {
+  return useSyncExternalStoreWithSelector(source.subscribe, read, read, selector, equals);
+}
+
+type Equality<T> = { equals(left: T, right: T): boolean }["equals"];
+
+function useStateSource(terminals: boolean) {
   const source = usePluginClientStateSource();
-  if (!source) throw new Error("Plugin state hooks must run inside a workspace panel");
-  return useSyncExternalStoreWithSelector(
-    source.subscribe,
-    () => input.read(source, input.id),
-    () => input.read(source, input.id),
-    (entity) => (entity ? input.selector(entity) : null),
-    shallowEqual,
+  if (!source) throw new Error("Plugin state hooks must run inside a plugin host");
+  return useMemo(
+    () =>
+      terminals
+        ? {
+            ...source,
+            subscribe: (listener: () => void) => source.subscribe(listener, { terminals: true }),
+          }
+        : source,
+    [source, terminals],
   );
 }
 
-export function useWorkspace<Selection>(
-  workspaceId: string,
-  selector: (workspace: PluginWorkspaceSnapshot) => Selection,
-): Selection | null {
-  return usePluginEntity({
-    id: workspaceId,
-    read: (source, id) => source.getWorkspace(id),
-    selector,
-  });
+function createEntityHook<Ref, Entity>(
+  read: (source: PluginClientStateSource, ref: Ref) => Entity | null,
+  terminals = false,
+) {
+  function useEntity(
+    ref: Ref,
+    selector?: undefined,
+    equals?: Equality<Entity | null>,
+  ): Entity | null;
+  function useEntity<Selection>(
+    ref: Ref,
+    selector: (entity: Entity) => Selection,
+    equals?: Equality<Selection | null>,
+  ): Selection | null;
+  function useEntity<Selection>(
+    ref: Ref,
+    selector?: (entity: Entity) => Selection,
+    equals?: Equality<Entity | Selection | null>,
+  ): Entity | Selection | null {
+    const source = useStateSource(terminals);
+    function select(entity: Entity | null): Entity | Selection | null {
+      return entity !== null && selector ? selector(entity) : entity;
+    }
+    const equality = equals ?? (selector ? shallowEqual : Object.is);
+    return usePaseoSelector(source, () => read(source, ref), select, equality);
+  }
+  return useEntity;
 }
 
-export function useAgent<Selection>(
-  agentId: string,
-  selector: (agent: PluginAgentSnapshot) => Selection,
-): Selection | null {
-  return usePluginEntity({
-    id: agentId,
-    read: (source, id) => source.getAgent(id),
-    selector,
-  });
+// COMPAT(plugin-entity-id): string ids accepted since 0.16; remove after 2027-03.
+export const useWorkspace = createEntityHook((source, ref: WorkspaceRef | string) =>
+  source.getWorkspace(ref),
+);
+// COMPAT(plugin-entity-id): string ids accepted since 0.16; remove after 2027-03.
+export const useAgent = createEntityHook((source, ref: AgentRef | string) => source.getAgent(ref));
+export const useProject = createEntityHook((source, ref: ProjectRef) => source.getProject(ref));
+export const useTerminal = createEntityHook(
+  (source, ref: TerminalRef) => source.getTerminal(ref),
+  true,
+);
+
+function createCollectionHook<Snapshot extends { readonly ref: unknown; readonly hostId: string }>(
+  read: (source: PluginClientStateSource, query: Query<Snapshot>) => readonly Snapshot[],
+  terminals = false,
+) {
+  function useCollection(
+    query: Query<Snapshot> & { groupBy: NonNullable<Query<Snapshot>["groupBy"]> },
+  ): readonly Group<Snapshot["ref"]>[];
+  function useCollection(
+    query?: Query<Snapshot> & { groupBy?: undefined },
+  ): readonly Snapshot["ref"][];
+  function useCollection(
+    query: Query<Snapshot>,
+  ): readonly Snapshot["ref"][] | readonly Group<Snapshot["ref"]>[];
+  function useCollection(
+    query: Query<Snapshot> = {},
+  ): readonly Snapshot["ref"][] | readonly Group<Snapshot["ref"]>[] {
+    const source = useStateSource(terminals);
+    const project = useMemo(() => createCollectionQuery<Snapshot>(), []);
+    return usePaseoSelector(
+      source,
+      () => read(source, query),
+      (snapshots) => project(snapshots, query),
+      Object.is,
+    );
+  }
+  return useCollection;
 }
 
+export const useWorkspaces = createCollectionHook((source) => source.getSnapshot().workspaces);
+export const useAgents = createCollectionHook((source) => source.getSnapshot().agents);
+export const useProjects = createCollectionHook((source) => source.getSnapshot().projects);
+export const useTerminals = createCollectionHook<PluginTerminalSnapshot>((source, query) => {
+  const snapshot = source.getSnapshot();
+  for (const [hostId, error] of snapshot.terminalErrors ?? []) {
+    if (!query.hosts || query.hosts.includes(hostId)) throw error;
+  }
+  return snapshot.terminals;
+}, true);
+
 export function PluginClientStateProvider({
   children,
   source,
diff --git a/packages/plugin/src/client/composer.tsx b/packages/plugin/src/client/composer.tsx
new file mode 100644
index 0000000000..c3c33ddeca
--- /dev/null
+++ b/packages/plugin/src/client/composer.tsx
@@ -0,0 +1,150 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginAttachmentItem } from "../attachments.js";
+import type { PluginHostProps } from "./contracts.js";
+
+/** One item the user attached from a source this plugin registered with `addAttachmentSource`. */
+export interface PluginComposerAttachment {
+  readonly sourceId: string;
+  readonly item: PluginAttachmentItem;
+}
+
+/** Where the cursor goes when a composer takes focus. */
+export interface PluginComposerFocusOptions {
+  /** Offsets into `prompt`, clamped to its length. Equal offsets place the cursor. Omit to keep the cursor where it is. */
+  selection?: { start: number; end: number };
+}
+
+/**
+ * The composer the item sits in: the prompt, the attachments and the agent being configured.
+ * The commands behave the same in every composer. `context` says where the composer is; it does
+ * not change what a command does, except that a running agent keeps its provider.
+ */
+export interface PluginComposer {
+  /** `"agent"`: a running agent. `"draft"`: a new agent in a workspace. `"new-workspace"`: the New workspace screen. */
+  readonly context: "agent" | "draft" | "new-workspace";
+  readonly prompt: string;
+  /** This plugin's attachments only. */
+  readonly attachments: readonly PluginComposerAttachment[];
+  readonly agent: {
+    readonly provider: string | null;
+    readonly model: string | null;
+    readonly mode: string | null;
+    readonly thinking: string | null;
+    /** The options the agent runs with, including provider defaults. */
+    readonly options: Readonly<Record<string, JsonValue>>;
+    readonly metadata: Readonly<Record<string, JsonValue>>;
+  };
+  setPrompt(text: string): void;
+  /** Inserts at the cursor, replacing the selection. */
+  insertText(text: string): void;
+  /**
+   * Puts the cursor in this composer, ready to type. Paseo opens the agent's tab or workspace when
+   * it is not on screen. Resolves once the input has focus; rejects when it could not get there.
+   */
+  focus(options?: PluginComposerFocusOptions): Promise<void>;
+  addAttachment(input: { sourceId: string; item: PluginAttachmentItem }): void;
+  removeAttachment(input: { sourceId: string; itemId: string }): void;
+  /** Resets the model like the built-in control. Rejects on a running agent, which keeps its provider. */
+  setProvider(provider: string): Promise<void>;
+  /** On a running agent, rejects with the provider's message when it refuses the model. */
+  setModel(modelId: string): Promise<void>;
+  setMode(modeId: string): Promise<void>;
+  setThinking(thinkingOptionId: string): Promise<void>;
+  /** Top-level keys replace; `null` removes the agent's own value. */
+  setOptions(patch: Record<string, JsonValue>): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+export interface PluginComposerItemProps extends PluginHostProps {}
+
+export interface PluginComposerItemContribution {
+  id: string;
+  Component: ComponentType<PluginComposerItemProps>;
+}
+
+const PluginComposerContext = createContext<PluginComposer | null>(null);
+
+export function PluginComposerProvider({
+  composer,
+  children,
+}: {
+  composer: PluginComposer;
+  children: ReactNode;
+}) {
+  return (
+    <PluginComposerContext.Provider value={composer}>{children}</PluginComposerContext.Provider>
+  );
+}
+
+export function usePluginComposerValue(): PluginComposer | null {
+  return useContext(PluginComposerContext);
+}
+
+/** The composer this item sits in. Call it from a component registered with `addComposerItem`. */
+export function useComposer(): PluginComposer {
+  const composer = usePluginComposerValue();
+  if (!composer) throw new Error("useComposer must run inside a composer item");
+  return composer;
+}
+
+/**
+ * Names the running agent whose composer a plugin wants. Both forms resolve to the same
+ * `PluginComposer` an item of that agent's composer gets from `useComposer()`.
+ */
+export type PluginComposerSelector = { agentId: string } | { focused: true };
+
+/** What `useComposers` and `composers(selector)` read. Paseo implements it per installed plugin. */
+export interface PluginComposersSource {
+  /** Tells `listener` when the composers `selector` names change, and keeps them live meanwhile. */
+  subscribe(selector: PluginComposerSelector, listener: () => void): () => void;
+  /** The composers `selector` names now: one for a known running agent, none otherwise. */
+  resolve(selector: PluginComposerSelector): readonly PluginComposer[];
+}
+
+const PluginComposersContext = createContext<PluginComposersSource | null>(null);
+
+export function PluginComposersProvider({
+  source,
+  children,
+}: {
+  source: PluginComposersSource;
+  children: ReactNode;
+}) {
+  return (
+    <PluginComposersContext.Provider value={source}>{children}</PluginComposersContext.Provider>
+  );
+}
+
+export function usePluginComposersSource(): PluginComposersSource | null {
+  return useContext(PluginComposersContext);
+}
+
+/**
+ * The composers `selector` names, whether or not their tabs are open. Runs in any plugin
+ * component. Empty for an unknown agent, or for `{ focused: true }` when no agent is focused.
+ */
+export function useComposers(selector: PluginComposerSelector): readonly PluginComposer[] {
+  const source = useContext(PluginComposersContext);
+  if (!source) throw new Error("useComposers must run inside a plugin component");
+  // The selector is usually an inline literal; its content is what the subscription depends on.
+  const selection = "agentId" in selector ? selector.agentId : null;
+  const subscribe = useMemo(
+    () => (listener: () => void) =>
+      source.subscribe(selection === null ? { focused: true } : { agentId: selection }, listener),
+    [source, selection],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => source.resolve(selector),
+    () => source.resolve(selector),
+  );
+}
diff --git a/packages/plugin/src/client/contracts.ts b/packages/plugin/src/client/contracts.ts
index 7675a655ff..1949e5506e 100644
--- a/packages/plugin/src/client/contracts.ts
+++ b/packages/plugin/src/client/contracts.ts
@@ -1,10 +1,23 @@
+import type { WorkspaceRef, AgentRef, ProjectRef, TerminalRef } from "../refs.js";
 import type { PluginText } from "../text.js";
 import type { ComponentType } from "react";
-import type { PaseoApi } from "@getpaseo/client";
+import type { PluginPaseoApi } from "./reference-api.js";
 import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-types";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
 import type { PluginFile } from "./file.js";
-import type { PluginRpcContract } from "../rpc.js";
+import type {
+  PluginComposer,
+  PluginComposerItemContribution,
+  PluginComposerSelector,
+} from "./composer.js";
+import type { PluginNewWorkspaceItemContribution } from "./new-workspace.js";
+import type {
+  PluginRpcContract,
+  PluginSubscribeOptions,
+  PluginSubscriptionContract,
+  PluginSubscriptionHandle,
+  PluginWireInput,
+} from "../rpc.js";
 import type {
   PluginButtonRegistration,
   PluginHeaderButtonContribution,
@@ -90,6 +103,24 @@ export interface PluginSidebarItemContribution<Text extends PluginText = string>
   Component: ComponentType<PluginSidebarItemProps>;
 }
 
+export interface PluginSidebarViewProps extends Pick<PluginHostProps, "theme" | "layout"> {
+  active: { workspace: WorkspaceRef | null; agent: AgentRef | null };
+  navigation: {
+    openWorkspace(ref: WorkspaceRef): void;
+    openAgent(ref: AgentRef): void;
+    openTerminal(ref: TerminalRef): void;
+    openProject(ref: ProjectRef): void;
+  };
+  dismiss(): void;
+}
+
+export interface PluginSidebarViewContribution<Text extends PluginText = string> {
+  id: string;
+  title: Text;
+  description?: Text;
+  Component: ComponentType<PluginSidebarViewProps>;
+}
+
 /**
  * A Lucide icon name, inline SVG markup, or a component. Components receive the surface's size
  * and color; buttons widen the props with their host and target context.
@@ -179,6 +210,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
   playAudio(source: { base64: string; mimeType: string }): Promise<void>;
   addSettingsScreen(contribution: PluginSettingsScreenContribution<PluginText>): PluginCleanup;
   addScreen(contribution: PluginScreenContribution<PluginText>): PluginCleanup;
+  addSidebarView(contribution: PluginSidebarViewContribution<PluginText>): PluginCleanup;
   addSidebarHeaderItem(contribution: PluginSidebarItemContribution<PluginText>): PluginCleanup;
   addSidebarFooterItem(contribution: PluginSidebarItemContribution<PluginText>): PluginCleanup;
   addAgentPanel(contribution: PluginAgentPanelContribution<PluginText>): PluginCleanup;
@@ -194,6 +226,8 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
     contribution: PluginComposerPillContribution<PluginText>,
   ): PluginButtonRegistration<PluginText>;
   addAttachmentSource(contribution: PluginAttachmentSourceContribution<PluginText>): PluginCleanup;
+  addComposerItem(contribution: PluginComposerItemContribution): PluginCleanup;
+  addNewWorkspaceItem(contribution: PluginNewWorkspaceItemContribution): PluginCleanup;
   addTheme(contribution: PluginThemeContribution<PluginText>): PluginCleanup;
   addFilePanel(contribution: PluginFilePanelContribution<PluginText>): PluginCleanup;
   addTimelineTransformer<ItemType extends AgentTimelineItem["type"]>(
@@ -203,6 +237,16 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
     contribution: PluginTimelineRendererContribution<Schema>,
   ): PluginCleanup;
   openPanel(id: string, options: PluginClientOpenPanelOptions): void;
+  /**
+   * Subscribes to a plugin subscription on this client's host. Paseo re-subscribes after a
+   * reconnect and releases what is left when the plugin stops.
+   */
+  subscribe<InputSchema extends ZodType, EventSchema extends ZodType>(
+    contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+    input: PluginWireInput<ZodInput<InputSchema>>,
+    onEvent: (event: ZodOutput<EventSchema>) => void,
+    options?: PluginSubscribeOptions,
+  ): PluginSubscriptionHandle;
 }
 
 export type PluginClientContribution = (client: PluginClientContext) => PluginCleanup;
@@ -292,12 +336,14 @@ export interface PluginTimelineRendererContribution<Schema extends ZodType = Zod
 }
 
 export interface PluginCommandCapabilities {
-  paseo: PaseoApi;
+  paseo: PluginPaseoApi;
   rpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
     contract: PluginRpcContract<InputSchema, OutputSchema>,
-    input: ZodInput<InputSchema>,
+    input: PluginWireInput<ZodInput<InputSchema>>,
   ): Promise<ZodOutput<OutputSchema>>;
   openScreen(input: PluginOpenScreenInput): void;
+  /** The composers `selector` names, whether or not their tabs are open; see `useComposers`. */
+  composers(selector: PluginComposerSelector): readonly PluginComposer[];
   /** @deprecated Use `openScreen`. */
   openSurface(id: string): void;
   openSettings(id: string): void;
diff --git a/packages/plugin/src/client/host.test.ts b/packages/plugin/src/client/host.test.ts
index 5b5333fcd1..aad5eed8fd 100644
--- a/packages/plugin/src/client/host.test.ts
+++ b/packages/plugin/src/client/host.test.ts
@@ -24,17 +24,23 @@ describe("plugin RPC contracts", () => {
     expectTypeOf<RpcOutput<typeof contract>>().toEqualTypeOf<{ value: number }>();
   });
 
-  it("validates input before invoking the daemon", async () => {
-    let invocations = 0;
-    const invoke = async () => {
-      invocations += 1;
-      return { value: 2 };
+  it("sends input unchanged for the plugin to parse", async () => {
+    let parses = 0;
+    const transformed = defineRpc({
+      name: "transformed",
+      input: z.string().transform((text) => {
+        parses += 1;
+        return Number(text);
+      }),
+      output: z.number(),
+    });
+    const invoke = async (_method: string, input: unknown) => {
+      expect(input).toBe("2");
+      expect(parses).toBe(0);
+      return transformed.input.parseAsync(input);
     };
-
-    await expect(callPluginRpc(contract, invoke, { value: "wrong" })).rejects.toBeInstanceOf(
-      z.ZodError,
-    );
-    expect(invocations).toBe(0);
+    await expect(callPluginRpc(transformed, invoke, "2")).resolves.toBe(2);
+    expect(parses).toBe(1);
   });
 
   it("validates output before resolving", async () => {
diff --git a/packages/plugin/src/client/host.ts b/packages/plugin/src/client/host.ts
index 987f047109..1dd26fc341 100644
--- a/packages/plugin/src/client/host.ts
+++ b/packages/plugin/src/client/host.ts
@@ -1,6 +1,17 @@
 import type { PluginText } from "../text.js";
 import { PluginAttachmentSearchPayloadSchema } from "../attachments.js";
-export { PluginClientStateProvider, type PluginClientStateSource } from "./client-state.js";
+export {
+  PluginClientStateProvider,
+  usePaseoSelector,
+  type PluginClientStateSource,
+  type PluginClientSnapshot,
+} from "./client-state.js";
+export {
+  PluginComposerProvider,
+  PluginComposersProvider,
+  type PluginComposersSource,
+} from "./composer.js";
+export { PluginNewWorkspaceProvider } from "./new-workspace.js";
 export {
   usePluginRuntimeContextBridge,
   type PluginRuntimeContextBridge,
@@ -8,7 +19,7 @@ export {
 import type { PluginAttachmentSourceContribution } from "../contracts.js";
 import { PluginRpcProvider } from "./rpc-context.js";
 import { PaseoApiProvider } from "./paseo-context.js";
-import { callPluginRpc } from "../rpc.js";
+import { callPluginRpc, subscribePluginRpc, type PluginSubscriptionObserver } from "../rpc.js";
 
 export async function searchPluginAttachments(
   source: PluginAttachmentSourceContribution<PluginText>,
@@ -19,7 +30,9 @@ export async function searchPluginAttachments(
   return PluginAttachmentSearchPayloadSchema.parseAsync(output);
 }
 
-export { callPluginRpc, PaseoApiProvider, PluginRpcProvider };
+export { callPluginRpc, subscribePluginRpc, PaseoApiProvider, PluginRpcProvider };
+export type { PluginSubscriptionObserver };
+export type { PluginSubscribe } from "./rpc-context.js";
 
 export {
   PluginTranslationRuntime,
@@ -29,3 +42,7 @@ export {
   isPluginMessage,
 } from "./translations.js";
 export type { PluginLocaleSource } from "./translations.js";
+
+export { createEntityRefs } from "./refs.js";
+
+export { createPluginReferenceApi } from "./reference-api.js";
diff --git a/packages/plugin/src/client/index.ts b/packages/plugin/src/client/index.ts
index 62cf7e2dc3..0597e56afe 100644
--- a/packages/plugin/src/client/index.ts
+++ b/packages/plugin/src/client/index.ts
@@ -15,6 +15,8 @@ export type {
   PluginOpenScreenInput,
   PluginScreenLocation,
   PluginSidebarItemProps,
+  PluginSidebarViewProps,
+  PluginSidebarViewContribution,
   PluginSidebarItemContribution,
   PluginIcon,
   PluginPanelLocation,
@@ -70,8 +72,37 @@ export {
   useFileUrl,
 } from "./file.js";
 export { usePaseo } from "./paseo-context.js";
-export { useAgent, useWorkspace } from "./client-state.js";
-export { useRpc } from "./rpc-context.js";
+export {
+  useAgent,
+  useWorkspace,
+  useProject,
+  useTerminal,
+  useWorkspaces,
+  useAgents,
+  useProjects,
+  useTerminals,
+} from "./client-state.js";
+export { useComposer, useComposers } from "./composer.js";
+export type {
+  PluginComposer,
+  PluginComposerAttachment,
+  PluginComposerFocusOptions,
+  PluginComposerItemContribution,
+  PluginComposerItemProps,
+  PluginComposerSelector,
+} from "./composer.js";
+export { useNewWorkspace } from "./new-workspace.js";
+export type {
+  PluginNewWorkspace,
+  PluginNewWorkspaceItemContribution,
+  PluginNewWorkspaceItemProps,
+} from "./new-workspace.js";
+export { useRpc, useSubscription, type PluginSubscriptionState } from "./rpc-context.js";
+export type {
+  PluginSubscribeOptions,
+  PluginSubscriptionClosed,
+  PluginSubscriptionHandle,
+} from "../rpc.js";
 import type { SettingsDefinition } from "../settings.js";
 import type { SettingsState } from "./contracts.js";
 import type { ZodType } from "zod";
@@ -97,3 +128,8 @@ export type { PluginI18n } from "./translations.js";
 export type { PluginText, PluginMessage, PluginTranslations } from "../text.js";
 
 export { useTabState } from "./tab.js";
+
+export type { WorkspaceRef, AgentRef, ProjectRef, TerminalRef } from "../refs.js";
+export type { Query, Group, GroupKey } from "./query.js";
+
+export type { PluginPaseoApi, PluginProjectHandle, PluginTerminalHandle } from "./reference-api.js";
diff --git a/packages/plugin/src/client/new-workspace.tsx b/packages/plugin/src/client/new-workspace.tsx
new file mode 100644
index 0000000000..7a12593b41
--- /dev/null
+++ b/packages/plugin/src/client/new-workspace.tsx
@@ -0,0 +1,78 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginHostProps } from "./contracts.js";
+
+/**
+ * The New workspace setup the item sits in. `host` and `project` are the user's choices and are
+ * read-only. The commands change what the created workspace is built from, under the same rules as
+ * the screen's own pickers.
+ */
+export interface PluginNewWorkspace {
+  readonly host: { readonly id: string; readonly label: string };
+  readonly project: { readonly id: string; readonly name: string } | null;
+  /** What the screen will create. A project that cannot make worktrees reads `"local"`. */
+  readonly isolation: "local" | "worktree";
+  /**
+   * What a new worktree starts from; `null` until the project's default is known. A branch's
+   * `name` is the exact ref creation uses, such as `refs/remotes/origin/main`, so
+   * `setBaseRef(newWorkspace.baseRef)` changes nothing.
+   */
+  readonly baseRef:
+    | { readonly type: "branch"; readonly name: string }
+    | { readonly type: "change-request"; readonly number: number }
+    | null;
+  /**
+   * The name of the branch a new worktree is created on; `null` lets Paseo pick one. It is kept
+   * while isolation is local or the base is a change request. It names the new branch of any
+   * worktree that cuts one, from the default base or a chosen branch, and does not apply to a
+   * worktree that checks out an existing branch or change request.
+   */
+  readonly branch: string | null;
+  /** The workspace's metadata, not the first agent's. */
+  readonly metadata: Readonly<Record<string, JsonValue>>;
+  /** Rejects `"worktree"` for a project that cannot make worktrees. */
+  setIsolation(isolation: "local" | "worktree"): Promise<void>;
+  /**
+   * Starts the workspace from a branch. `name` is any ref the Base picker offers, such as
+   * `refs/remotes/origin/main`, or a bare branch name, which Paseo resolves the way it does for
+   * a branch name it is given anywhere else. Rejects while no project is chosen.
+   */
+  setBaseRef(ref: { type: "branch"; name: string }): Promise<void>;
+  setBranch(name: string | null): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. Rejects on a host without metadata support. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+export interface PluginNewWorkspaceItemProps extends PluginHostProps {}
+
+export interface PluginNewWorkspaceItemContribution {
+  id: string;
+  Component: ComponentType<PluginNewWorkspaceItemProps>;
+}
+
+const PluginNewWorkspaceContext = createContext<PluginNewWorkspace | null>(null);
+
+export function PluginNewWorkspaceProvider({
+  newWorkspace,
+  children,
+}: {
+  newWorkspace: PluginNewWorkspace;
+  children: ReactNode;
+}) {
+  return (
+    <PluginNewWorkspaceContext.Provider value={newWorkspace}>
+      {children}
+    </PluginNewWorkspaceContext.Provider>
+  );
+}
+
+export function usePluginNewWorkspaceValue(): PluginNewWorkspace | null {
+  return useContext(PluginNewWorkspaceContext);
+}
+
+/** The New workspace setup this item sits in. Call it from a component registered with `addNewWorkspaceItem`. */
+export function useNewWorkspace(): PluginNewWorkspace {
+  const newWorkspace = useContext(PluginNewWorkspaceContext);
+  if (!newWorkspace) throw new Error("useNewWorkspace must run inside a New workspace item");
+  return newWorkspace;
+}
diff --git a/packages/plugin/src/client/paseo-context.tsx b/packages/plugin/src/client/paseo-context.tsx
index fe1a0b9c5c..8ec6910bb2 100644
--- a/packages/plugin/src/client/paseo-context.tsx
+++ b/packages/plugin/src/client/paseo-context.tsx
@@ -1,17 +1,23 @@
-import type { PaseoApi } from "@getpaseo/client";
+import type { PluginPaseoApi } from "./reference-api.js";
 import { createContext, useContext, type ReactNode } from "react";
 
-const PaseoApiContext = createContext<PaseoApi | null>(null);
+const PaseoApiContext = createContext<PluginPaseoApi | null>(null);
 
-export function usePaseoContextValue(): PaseoApi | null {
+export function usePaseoContextValue(): PluginPaseoApi | null {
   return useContext(PaseoApiContext);
 }
 
-export function PaseoApiProvider({ children, paseo }: { children: ReactNode; paseo: PaseoApi }) {
+export function PaseoApiProvider({
+  children,
+  paseo,
+}: {
+  children: ReactNode;
+  paseo: PluginPaseoApi;
+}) {
   return <PaseoApiContext.Provider value={paseo}>{children}</PaseoApiContext.Provider>;
 }
 
-export function usePaseo(): PaseoApi {
+export function usePaseo(): PluginPaseoApi {
   const paseo = usePaseoContextValue();
   if (!paseo) throw new Error("usePaseo must run inside a contributed plugin surface");
   return paseo;
diff --git a/packages/plugin/src/client/query.test.ts b/packages/plugin/src/client/query.test.ts
new file mode 100644
index 0000000000..ce0dd9bd3c
--- /dev/null
+++ b/packages/plugin/src/client/query.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { createCollectionQuery, type GroupKey } from "./query.js";
+
+const first = Object.freeze({ key: "a" });
+const second = Object.freeze({ key: "b" });
+const work: GroupKey = "work";
+const snapshots = [
+  { ref: first, hostId: "one", title: "A", status: "running", labels: [work, work] },
+  { ref: second, hostId: "two", title: "B", status: "idle", labels: ["home"] },
+];
+
+describe("collection query structural sharing", () => {
+  it("preserves collection identity when a row changes without changing membership", () => {
+    const project = createCollectionQuery<(typeof snapshots)[number]>();
+    const before = project(snapshots);
+    const after = project([{ ...snapshots[0]!, status: "waiting" }, snapshots[1]!]);
+    expect(after).toBe(before);
+    expect(after).toEqual([first, second]);
+  });
+
+  it("shares unaffected groups and deduplicates membership", () => {
+    const project = createCollectionQuery<(typeof snapshots)[number]>();
+    const query = { groupBy: (item: (typeof snapshots)[number]) => item.labels };
+    const before = project(snapshots, query);
+    const after = project([{ ...snapshots[0]!, labels: ["new"] }, snapshots[1]!], query);
+    expect(after[1]).toBe(before[1]);
+    expect(before[0]).toEqual({ key: "work", title: null, color: null, items: [first] });
+    expect(after[0]).toEqual({ key: "new", title: null, color: null, items: [first] });
+    expect(project([{ ...snapshots[0]!, labels: ["new"] }, snapshots[1]!], query)).toBe(after);
+  });
+
+  it("filters hosts and predicates before sorting", () => {
+    const project = createCollectionQuery<(typeof snapshots)[number]>();
+    expect(project(snapshots, { hosts: ["two"] })).toEqual([second]);
+    expect(project(snapshots, { where: (item) => item.status === "running" })).toEqual([first]);
+    expect(project(snapshots, { orderBy: ["title", "desc"] })).toEqual([second, first]);
+    expect(project(snapshots, { orderBy: (a, b) => a.title.localeCompare(b.title) })).toEqual([
+      first,
+      second,
+    ]);
+  });
+
+  it("keeps nulls last in either direction and metadata from the first group", () => {
+    const project = createCollectionQuery<{
+      ref: typeof first;
+      hostId: string;
+      title: string | null;
+    }>();
+    const items = [
+      { ref: first, hostId: "one", title: null },
+      { ref: second, hostId: "one", title: "Z" },
+    ];
+    expect(project(items, { orderBy: ["title", "desc"] })).toEqual([second, first]);
+    expect(
+      project(items, { groupBy: (item) => ({ key: "all", title: item.title ?? "First" }) }),
+    ).toEqual([{ key: "all", title: "First", color: null, items: [first, second] }]);
+  });
+});
diff --git a/packages/plugin/src/client/query.ts b/packages/plugin/src/client/query.ts
new file mode 100644
index 0000000000..8e291602ca
--- /dev/null
+++ b/packages/plugin/src/client/query.ts
@@ -0,0 +1,115 @@
+interface GroupDescriptor {
+  readonly key: string;
+  readonly title?: string;
+  readonly color?: string;
+}
+
+export type GroupKey = string | GroupDescriptor;
+
+export interface Query<Snapshot> {
+  readonly hosts?: readonly string[];
+  readonly where?: (item: Snapshot) => boolean;
+  readonly orderBy?:
+    | keyof Snapshot
+    | readonly [keyof Snapshot, "asc" | "desc"]
+    | ((a: Snapshot, b: Snapshot) => number);
+  readonly groupBy?: (item: Snapshot) => GroupKey | readonly GroupKey[];
+}
+
+export interface Group<Ref> {
+  readonly key: string;
+  readonly title: string | null;
+  readonly color: string | null;
+  readonly items: readonly Ref[];
+}
+
+function groupKeys(value: GroupKey | readonly GroupKey[]): readonly GroupKey[] {
+  if (typeof value === "string") return [value];
+  if ("key" in value) return [value];
+  return value;
+}
+
+interface Referenced {
+  readonly hostId: string;
+  readonly ref: unknown;
+}
+
+function sameSequence<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
+function compareValues(left: unknown, right: unknown, direction: number): number {
+  if (Object.is(left, right)) return 0;
+  if (left === null || left === undefined) return 1;
+  if (right === null || right === undefined) return -1;
+  if (typeof left === "number" && typeof right === "number") return (left - right) * direction;
+  return String(left).localeCompare(String(right)) * direction;
+}
+
+/** A hook owns one projection; sharing survives both source and query changes. */
+export function createCollectionQuery<Snapshot extends Referenced>() {
+  type Ref = Snapshot["ref"];
+  let previousItems: readonly Ref[] = Object.freeze([]);
+  let previousGroups: readonly Group<Ref>[] = Object.freeze([]);
+
+  return function project(
+    snapshots: readonly Snapshot[],
+    query: Query<Snapshot> = {},
+  ): readonly Ref[] | readonly Group<Ref>[] {
+    const items = snapshots.filter((item) => {
+      if (query.hosts && !query.hosts.includes(item.hostId)) return false;
+      return !query.where || query.where(item);
+    });
+    const order = query.orderBy;
+    if (typeof order === "function") items.sort(order);
+    else if (order !== undefined) {
+      const field = typeof order === "object" ? order[0] : order;
+      const direction = typeof order === "object" && order[1] === "desc" ? -1 : 1;
+      items.sort((a, b) => compareValues(a[field], b[field], direction));
+    }
+    if (!query.groupBy) {
+      const refs = items.map((item) => item.ref);
+      if (!sameSequence(previousItems, refs)) previousItems = Object.freeze(refs);
+      return previousItems;
+    }
+    const groups = new Map<
+      string,
+      { key: string; title: string | null; color: string | null; items: Ref[] }
+    >();
+    for (const item of items) {
+      const grouping = query.groupBy(item);
+      const keys = groupKeys(grouping);
+      const seen = new Set<string>();
+      for (const value of keys) {
+        const descriptor = typeof value === "string" ? { key: value } : value;
+        if (seen.has(descriptor.key)) continue;
+        seen.add(descriptor.key);
+        let group = groups.get(descriptor.key);
+        if (!group) {
+          group = {
+            key: descriptor.key,
+            title: descriptor.title ?? null,
+            color: descriptor.color ?? null,
+            items: [],
+          };
+          groups.set(descriptor.key, group);
+        }
+        group.items.push(item.ref);
+      }
+    }
+    const oldGroups = new Map(previousGroups.map((group) => [group.key, group]));
+    const nextGroups = Array.from(groups.values(), (group) => {
+      const previous = oldGroups.get(group.key);
+      if (
+        previous &&
+        previous.title === group.title &&
+        previous.color === group.color &&
+        sameSequence(previous.items, group.items)
+      )
+        return previous;
+      return Object.freeze({ ...group, items: Object.freeze(group.items) });
+    });
+    if (!sameSequence(previousGroups, nextGroups)) previousGroups = Object.freeze(nextGroups);
+    return previousGroups;
+  };
+}
diff --git a/packages/plugin/src/client/reference-api.ts b/packages/plugin/src/client/reference-api.ts
new file mode 100644
index 0000000000..b782e26438
--- /dev/null
+++ b/packages/plugin/src/client/reference-api.ts
@@ -0,0 +1,88 @@
+import type {
+  PaseoApi,
+  PaseoAgent,
+  PaseoAgentHandle,
+  PaseoWorkspace,
+  PaseoWorkspaceHandle,
+  PaseoWorkspaceCreateOptions,
+} from "@getpaseo/client";
+import type { PaseoTerminal, PaseoTerminalHandle } from "@getpaseo/client";
+import type { PluginProjectSnapshot } from "../contracts.js";
+import type { AgentRef, ProjectRef, TerminalRef, WorkspaceRef } from "../refs.js";
+import type { PluginSidebarViewProps } from "./contracts.js";
+
+export interface PluginProjectHandle {
+  readonly ref: ProjectRef;
+  open(): void;
+  createWorkspace(
+    input?: Omit<PaseoWorkspaceCreateOptions, "source"> & {
+      source?: PaseoWorkspaceCreateOptions["source"];
+    },
+  ): Promise<PaseoWorkspaceHandle>;
+}
+export interface PluginTerminalHandle extends PaseoTerminalHandle {
+  focus(): void;
+}
+export interface PluginPaseoApi extends PaseoApi {
+  workspaces: Omit<PaseoApi["workspaces"], "ref"> & {
+    ref(workspace: string | PaseoWorkspace | WorkspaceRef): PaseoWorkspaceHandle;
+  };
+  agents: Omit<PaseoApi["agents"], "ref"> & {
+    ref(agent: string | PaseoAgent | AgentRef): PaseoAgentHandle;
+  };
+  projects: PaseoApi["projects"] & { ref(project: ProjectRef): PluginProjectHandle };
+  terminals: Omit<PaseoApi["terminals"], "ref"> & {
+    ref(terminal: TerminalRef): PluginTerminalHandle;
+    ref(terminal: string | PaseoTerminal): PaseoTerminalHandle;
+  };
+}
+
+/** Host adapter; the installation retains its single API identity across every surface. */
+export function createPluginReferenceApi(input: {
+  paseo: PaseoApi;
+  resolveHost(hostId: string): PaseoApi;
+  readProject(ref: ProjectRef): PluginProjectSnapshot | null;
+  navigation: PluginSidebarViewProps["navigation"];
+}): PluginPaseoApi {
+  const { paseo } = input;
+  const workspaceRef = paseo.workspaces.ref;
+  const agentRef = paseo.agents.ref;
+  const terminalRef = paseo.terminals.ref;
+  function refWorkspace(workspace: string | PaseoWorkspace | WorkspaceRef) {
+    if (typeof workspace !== "string" && "hostId" in workspace)
+      return input.resolveHost(workspace.hostId).workspaces.ref(workspace.id);
+    return workspaceRef(workspace);
+  }
+  function refAgent(agent: string | PaseoAgent | AgentRef) {
+    if (typeof agent !== "string" && "hostId" in agent)
+      return input.resolveHost(agent.hostId).agents.ref(agent.id);
+    return agentRef(agent);
+  }
+  function terminal(ref: TerminalRef): PluginTerminalHandle;
+  function terminal(ref: string | PaseoTerminal): PaseoTerminalHandle;
+  function terminal(ref: TerminalRef | string | PaseoTerminal): PaseoTerminalHandle {
+    if (typeof ref !== "string" && "hostId" in ref) {
+      const handle = input.resolveHost(ref.hostId).terminals.ref(ref.id);
+      return Object.assign(handle, { focus: () => input.navigation.openTerminal(ref) });
+    }
+    return terminalRef(ref);
+  }
+  function project(ref: ProjectRef): PluginProjectHandle {
+    return {
+      ref,
+      open: () => input.navigation.openProject(ref),
+      async createWorkspace(options = {}) {
+        const snapshot = input.readProject(ref);
+        if (!snapshot) throw new Error("Project is no longer available");
+        const source = options.source ?? { kind: "directory", path: snapshot.rootPath };
+        return input.resolveHost(ref.hostId).workspaces.create({ ...options, source });
+      },
+    };
+  }
+  return Object.assign(paseo, {
+    workspaces: Object.assign(paseo.workspaces, { ref: refWorkspace }),
+    agents: Object.assign(paseo.agents, { ref: refAgent }),
+    projects: Object.assign(paseo.projects, { ref: project }),
+    terminals: Object.assign(paseo.terminals, { ref: terminal }),
+  });
+}
diff --git a/packages/plugin/src/client/refs.test.ts b/packages/plugin/src/client/refs.test.ts
new file mode 100644
index 0000000000..93407414fc
--- /dev/null
+++ b/packages/plugin/src/client/refs.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { createEntityRefs } from "./refs.js";
+
+describe("session entity references", () => {
+  it("interns frozen references separately by kind, host and entity", () => {
+    const refs = createEntityRefs();
+    for (const reference of [refs.workspace, refs.agent, refs.project, refs.terminal]) {
+      const first = reference("host", "entity");
+      expect(reference("host", "entity")).toBe(first);
+      expect(Object.isFrozen(first)).toBe(true);
+      expect(reference("other", "entity")).not.toBe(first);
+      expect(reference("host", "other")).not.toBe(first);
+    }
+    expect(refs.workspace("host", "entity")).not.toBe(refs.agent("host", "entity"));
+  });
+
+  it("keeps opaque ids unambiguous and interning scoped to one app session", () => {
+    const refs = createEntityRefs();
+    expect(refs.workspace("a:b", "c").key).not.toBe(refs.workspace("a", "b:c").key);
+    expect(createEntityRefs().workspace("host", "entity")).not.toBe(
+      refs.workspace("host", "entity"),
+    );
+  });
+});
diff --git a/packages/plugin/src/client/refs.ts b/packages/plugin/src/client/refs.ts
new file mode 100644
index 0000000000..0dbdd69428
--- /dev/null
+++ b/packages/plugin/src/client/refs.ts
@@ -0,0 +1,26 @@
+import type { AgentRef, ProjectRef, TerminalRef, WorkspaceRef } from "../refs.js";
+
+/** Owned by the app session, shared by every plugin installation. */
+export function createEntityRefs() {
+  function intern<Kind extends string>(kind: Kind) {
+    const references = new Map<
+      string,
+      Readonly<{ kind: Kind; key: string; hostId: string; id: string }>
+    >();
+    return function reference(hostId: string, id: string) {
+      const key = JSON.stringify([hostId, id]);
+      let ref = references.get(key);
+      if (!ref) {
+        ref = Object.freeze({ kind, key, hostId, id });
+        references.set(key, ref);
+      }
+      return ref;
+    };
+  }
+  return {
+    workspace: intern("workspace") satisfies (hostId: string, id: string) => WorkspaceRef,
+    agent: intern("agent") satisfies (hostId: string, id: string) => AgentRef,
+    project: intern("project") satisfies (hostId: string, id: string) => ProjectRef,
+    terminal: intern("terminal") satisfies (hostId: string, id: string) => TerminalRef,
+  };
+}
diff --git a/packages/plugin/src/client/rpc-context.tsx b/packages/plugin/src/client/rpc-context.tsx
index 7cd9bb176a..837bcbea46 100644
--- a/packages/plugin/src/client/rpc-context.tsx
+++ b/packages/plugin/src/client/rpc-context.tsx
@@ -1,9 +1,34 @@
-import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
-import { callPluginRpc, type PluginRpcContract } from "../rpc.js";
+import {
+  callPluginRpc,
+  subscribePluginRpc,
+  type PluginRpcContract,
+  type PluginSubscriptionContract,
+  type PluginSubscriptionHandle,
+  type PluginSubscriptionObserver,
+  type PluginWireInput,
+} from "../rpc.js";
+import { shallowEqual } from "./shallow.js";
+
+export type PluginSubscribe = (
+  method: string,
+  input: unknown,
+  observer: PluginSubscriptionObserver,
+) => PluginSubscriptionHandle;
 
 export interface PluginRpcContextValue {
   invoke(method: string, input: unknown): Promise<unknown>;
+  subscribe: PluginSubscribe;
 }
 
 const PluginRpcContext = createContext<PluginRpcContextValue | null>(null);
@@ -15,22 +40,100 @@ export function usePluginRpcContextValue(): PluginRpcContextValue | null {
 export function PluginRpcProvider({
   children,
   invoke,
+  subscribe,
 }: {
   children: ReactNode;
   invoke(method: string, input: unknown): Promise<unknown>;
+  subscribe: PluginSubscribe;
 }) {
-  const value = useMemo(() => ({ invoke }), [invoke]);
+  const value = useMemo(() => ({ invoke, subscribe }), [invoke, subscribe]);
   return <PluginRpcContext.Provider value={value}>{children}</PluginRpcContext.Provider>;
 }
 
 export function useRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
   contract: PluginRpcContract<InputSchema, OutputSchema>,
-): (input: ZodInput<InputSchema>) => Promise<ZodOutput<OutputSchema>> {
+): (input: PluginWireInput<ZodInput<InputSchema>>) => Promise<ZodOutput<OutputSchema>> {
   const context = usePluginRpcContextValue();
   if (!context) throw new Error("useRpc must run inside a contributed plugin surface");
 
   return useCallback(
-    (input: ZodInput<InputSchema>) => callPluginRpc(contract, context.invoke, input),
+    (input: PluginWireInput<ZodInput<InputSchema>>) =>
+      callPluginRpc(contract, context.invoke, input),
     [context, contract],
   );
 }
+
+export type PluginSubscriptionState =
+  | { status: "connecting" }
+  | { status: "live" }
+  /** The plugin's handler finished. The hook subscribes again when `input` changes. */
+  | { status: "closed" }
+  | { status: "error"; error: Error };
+
+/**
+ * Subscribes while the component is mounted. Re-subscribes when `input` changes by shallow
+ * comparison; `onEvent` always runs the latest callback.
+ */
+export function useSubscription<InputSchema extends ZodType, EventSchema extends ZodType>(
+  contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+  input: PluginWireInput<ZodInput<InputSchema>>,
+  onEvent: (event: ZodOutput<EventSchema>) => void,
+): PluginSubscriptionState {
+  const context = usePluginRpcContextValue();
+  if (!context) throw new Error("useSubscription must run inside a contributed plugin surface");
+  const subscribe = context.subscribe;
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const stableInput = useShallowStable(input);
+  const [state, setState] = useState<PluginSubscriptionState>({ status: "connecting" });
+
+  useEffect(() => {
+    let active = true;
+    setState({ status: "connecting" });
+    let handle: PluginSubscriptionHandle;
+    try {
+      handle = subscribePluginRpc(
+        contract,
+        subscribe,
+        stableInput,
+        (event) => onEventRef.current(event),
+        {
+          onClosed: ({ error }) => {
+            if (active) setState(error ? { status: "error", error } : CLOSED);
+          },
+        },
+      );
+    } catch (error) {
+      setState({ status: "error", error: toError(error) });
+      return;
+    }
+    handle.ready.then(
+      () => {
+        if (active) setState((current) => (current.status === "connecting" ? LIVE : current));
+        return undefined;
+      },
+      (error: unknown) => {
+        if (active) setState({ status: "error", error: toError(error) });
+      },
+    );
+    return () => {
+      active = false;
+      handle();
+    };
+  }, [contract, subscribe, stableInput]);
+
+  return state;
+}
+
+const LIVE: PluginSubscriptionState = { status: "live" };
+const CLOSED: PluginSubscriptionState = { status: "closed" };
+
+function useShallowStable<Value>(value: Value): Value {
+  const ref = useRef(value);
+  if (!shallowEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
diff --git a/packages/plugin/src/client/runtime-context-bridge.tsx b/packages/plugin/src/client/runtime-context-bridge.tsx
index b18588b32c..c9315084cb 100644
--- a/packages/plugin/src/client/runtime-context-bridge.tsx
+++ b/packages/plugin/src/client/runtime-context-bridge.tsx
@@ -1,6 +1,13 @@
 import { PluginTranslationProvider, usePluginTranslationRuntime } from "./translations.js";
 import { useCallback, type ReactNode } from "react";
+import {
+  PluginComposerProvider,
+  PluginComposersProvider,
+  usePluginComposerValue,
+  usePluginComposersSource,
+} from "./composer.js";
 import { PluginClientStateProvider, usePluginClientStateSource } from "./client-state.js";
+import { PluginNewWorkspaceProvider, usePluginNewWorkspaceValue } from "./new-workspace.js";
 import { PaseoApiProvider, usePaseoContextValue } from "./paseo-context.js";
 import { PluginRpcProvider, usePluginRpcContextValue } from "./rpc-context.js";
 
@@ -12,6 +19,9 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
   const paseo = usePaseoContextValue();
   const rpc = usePluginRpcContextValue();
   const state = usePluginClientStateSource();
+  const composer = usePluginComposerValue();
+  const composers = usePluginComposersSource();
+  const newWorkspace = usePluginNewWorkspaceValue();
 
   if (!paseo || !rpc) {
     throw new Error("Plugin UI must run inside a contributed plugin surface");
@@ -19,19 +29,36 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
 
   return useCallback(
     (children: ReactNode) => {
-      const content = state ? (
+      const withState = state ? (
         <PluginClientStateProvider source={state}>{children}</PluginClientStateProvider>
       ) : (
         children
       );
+      const withComposers = composers ? (
+        <PluginComposersProvider source={composers}>{withState}</PluginComposersProvider>
+      ) : (
+        withState
+      );
+      const withNewWorkspace = newWorkspace ? (
+        <PluginNewWorkspaceProvider newWorkspace={newWorkspace}>
+          {withComposers}
+        </PluginNewWorkspaceProvider>
+      ) : (
+        withComposers
+      );
+      const content = composer ? (
+        <PluginComposerProvider composer={composer}>{withNewWorkspace}</PluginComposerProvider>
+      ) : (
+        withNewWorkspace
+      );
       return (
         <PaseoApiProvider paseo={paseo}>
-          <PluginRpcProvider invoke={rpc.invoke}>
+          <PluginRpcProvider invoke={rpc.invoke} subscribe={rpc.subscribe}>
             <PluginTranslationProvider runtime={translations}>{content}</PluginTranslationProvider>
           </PluginRpcProvider>
         </PaseoApiProvider>
       );
     },
-    [paseo, rpc, state, translations],
+    [composer, composers, newWorkspace, paseo, rpc, state, translations],
   );
 }
diff --git a/packages/plugin/src/client/ui.ts b/packages/plugin/src/client/ui.ts
index c012753181..30ad3e178a 100644
--- a/packages/plugin/src/client/ui.ts
+++ b/packages/plugin/src/client/ui.ts
@@ -185,3 +185,60 @@ export interface MarkdownProps {
 
 /** Renders Markdown using Paseo’s theme, selection, and link behavior. */
 export declare const Markdown: ComponentType<MarkdownProps>;
+
+export interface ComposerControlProps {
+  /** The control's label and tooltip. */
+  title: string;
+  /** A Lucide icon name, inline SVG, or a component. */
+  icon: PluginIcon;
+  disabled?: boolean;
+}
+/**
+ * What a control's callback receives. A returned promise marks the control pending until it
+ * settles, and Paseo reports a rejection to the user.
+ */
+export interface ToggleProps extends ComposerControlProps {
+  value: boolean;
+  onValueChange(event: { value: boolean }): void | Promise<void>;
+}
+export interface SelectProps<Value extends string = string> extends ComposerControlProps {
+  value: Value;
+  options: readonly { value: Value; label: string; description?: string }[];
+  onValueChange(event: { value: Value }): void | Promise<void>;
+}
+export interface ActionPressEvent {}
+export interface ActionProps extends ComposerControlProps {
+  onPress(event: ActionPressEvent): void | Promise<void>;
+}
+/** One result of a `Combobox` search. Extra fields ride along to `onSelect`. */
+export interface ComboboxItem {
+  id: string;
+  label: string;
+  description?: string;
+}
+export interface ComboboxSearchEvent {
+  /** Empty when the list opens. */
+  query: string;
+}
+export interface ComboboxProps<
+  Item extends ComboboxItem = ComboboxItem,
+> extends ComposerControlProps {
+  /** What the control shows. It need not be among the search results. */
+  value: ComboboxItem | null;
+  /**
+   * Called when the list opens and again, debounced, as the user types. Paseo shows the loading
+   * and error states, keeps the previous results while a search runs, and ignores a search that a
+   * newer one replaced.
+   */
+  search(event: ComboboxSearchEvent): Promise<readonly Item[]>;
+  onSelect(event: { item: Item }): void | Promise<void>;
+}
+/**
+ * Paseo's controls. Render them from a composer item's or a New workspace item's `Component`.
+ * Paseo draws them where the item sits: inline when the composer has room and as rows in its
+ * overflow sheet when it does not, and as a field in the New workspace setup.
+ */
+export declare const Toggle: ComponentType<ToggleProps>;
+export declare function Select<Value extends string>(props: SelectProps<Value>): ReactNode;
+export declare const Action: ComponentType<ActionProps>;
+export declare function Combobox<Item extends ComboboxItem>(props: ComboboxProps<Item>): ReactNode;
diff --git a/packages/plugin/src/contracts.ts b/packages/plugin/src/contracts.ts
index 7e71cb22c5..9bb5f0353d 100644
--- a/packages/plugin/src/contracts.ts
+++ b/packages/plugin/src/contracts.ts
@@ -1,3 +1,4 @@
+import type { WorkspaceRef, AgentRef, ProjectRef, TerminalRef } from "./refs.js";
 import type { PluginText } from "./text.js";
 import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { PluginSerializableIcon } from "./icons.js";
@@ -19,7 +20,22 @@ export interface PluginTheme {
   };
 }
 
+export type WorkspaceIndicator = "needs_input" | "failed" | "running" | "attention" | "done";
+
 export interface PluginWorkspaceSnapshot {
+  readonly ref: WorkspaceRef;
+  readonly hostId: string;
+  readonly project: ProjectRef;
+  readonly pinnedAt: string | null;
+  readonly labels: readonly string[];
+  readonly background: boolean;
+  readonly branch: string | null;
+  /** Null when an older host has not supplied the workspace creation time. */
+  readonly createdAt: string | null;
+  readonly lastPromptAt: string | null;
+  readonly parentAgent: AgentRef | null;
+  readonly indicator: WorkspaceIndicator;
+  readonly indicatorLabel: string | null;
   readonly id: string;
   readonly projectId: string;
   readonly projectDisplayName: string;
@@ -29,6 +45,7 @@ export interface PluginWorkspaceSnapshot {
   readonly kind: "directory" | "local_checkout" | "checkout" | "worktree";
   readonly name: string;
   readonly title: string | null;
+  /** Raw daemon status; prefer indicator for presentation. */
   readonly status: "needs_input" | "failed" | "running" | "attention" | "done";
   readonly statusEnteredAt: string | null;
   readonly archivingAt: string | null;
@@ -36,6 +53,10 @@ export interface PluginWorkspaceSnapshot {
 }
 
 export interface PluginAgentSnapshot {
+  readonly ref: AgentRef;
+  readonly hostId: string;
+  readonly workspace: WorkspaceRef;
+  readonly parentAgent: AgentRef | null;
   readonly id: string;
   readonly workspaceId: string;
   readonly provider: string;
@@ -52,6 +73,8 @@ export interface PluginAgentSnapshot {
   readonly attentionReason: "finished" | "error" | "permission" | null;
   readonly parentAgentId: string | null;
   readonly labels: Readonly<Record<string, string>>;
+  /** Structured data plugins store on the agent. */
+  readonly metadata: Readonly<Record<string, JsonValue>>;
 }
 
 export interface PluginThemeColors {
@@ -96,3 +119,22 @@ export interface PluginTimelineTransformResult {
 }
 
 export type PluginCleanup = () => void | Promise<void>;
+
+export interface PluginProjectSnapshot {
+  readonly ref: ProjectRef;
+  readonly hostId: string;
+  readonly displayName: string;
+  readonly rootPath: string;
+  readonly kind: PluginWorkspaceSnapshot["projectKind"];
+  readonly iconRevision: string | null;
+}
+
+export interface PluginTerminalSnapshot {
+  readonly ref: TerminalRef;
+  readonly hostId: string;
+  readonly workspace: WorkspaceRef;
+  readonly title: string;
+  readonly isScript: boolean;
+  /** Null for terminals owned by workers started before timestamps were tracked. */
+  readonly createdAt: string | null;
+}
diff --git a/packages/plugin/src/index.ts b/packages/plugin/src/index.ts
index 2bc20fa9ac..8680ae949f 100644
--- a/packages/plugin/src/index.ts
+++ b/packages/plugin/src/index.ts
@@ -3,6 +3,9 @@ export type {
   PluginTheme,
   PluginWorkspaceSnapshot,
   PluginAgentSnapshot,
+  PluginProjectSnapshot,
+  PluginTerminalSnapshot,
+  WorkspaceIndicator,
   PluginThemeColors,
   PluginThemeContribution,
   PluginAttachmentSourceContribution,
@@ -19,7 +22,16 @@ export {
   type PluginAttachmentItem,
   type PluginAttachmentSearchPayload,
 } from "./attachments.js";
-export { defineRpc, type PluginRpcContract, type RpcInput, type RpcOutput } from "./rpc.js";
+export {
+  defineRpc,
+  defineSubscription,
+  type PluginRpcContract,
+  type PluginSubscriptionContract,
+  type RpcInput,
+  type RpcOutput,
+  type SubscriptionEvent,
+  type SubscriptionInput,
+} from "./rpc.js";
 
 export type { PluginText, PluginMessage } from "./text.js";
 export {
diff --git a/packages/plugin/src/refs.ts b/packages/plugin/src/refs.ts
new file mode 100644
index 0000000000..e0293bfe09
--- /dev/null
+++ b/packages/plugin/src/refs.ts
@@ -0,0 +1,11 @@
+interface EntityRef<Kind extends string> {
+  readonly kind: Kind;
+  readonly key: string;
+  readonly hostId: string;
+  readonly id: string;
+}
+
+export interface WorkspaceRef extends EntityRef<"workspace"> {}
+export interface AgentRef extends EntityRef<"agent"> {}
+export interface ProjectRef extends EntityRef<"project"> {}
+export interface TerminalRef extends EntityRef<"terminal"> {}
diff --git a/packages/plugin/src/rpc.ts b/packages/plugin/src/rpc.ts
index 6a16a19691..fd550b101f 100644
--- a/packages/plugin/src/rpc.ts
+++ b/packages/plugin/src/rpc.ts
@@ -9,6 +9,12 @@ export interface PluginRpcContract<
   output: OutputSchema;
 }
 
+/**
+ * `z.instanceof(Uint8Array)` infers `Uint8Array<ArrayBuffer>`; values crossing the wire accept any
+ * `Uint8Array`, including a `Buffer` or a view of a shared buffer.
+ */
+export type PluginWireInput<Value> = Value extends Uint8Array ? Uint8Array : Value;
+
 export type RpcInput<Contract extends PluginRpcContract> = ZodOutput<Contract["input"]>;
 export type RpcOutput<Contract extends PluginRpcContract> = ZodInput<Contract["output"]>;
 
@@ -31,9 +37,98 @@ export function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodT
 export async function callPluginRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
   contract: PluginRpcContract<InputSchema, OutputSchema>,
   invoke: (method: string, input: unknown) => Promise<unknown>,
-  input: ZodInput<InputSchema>,
+  input: PluginWireInput<ZodInput<InputSchema>>,
 ): Promise<ZodOutput<OutputSchema>> {
-  const parsedInput = await contract.input.parseAsync(input);
-  const output = await invoke(contract.name, parsedInput);
+  const output = await invoke(contract.name, input);
   return contract.output.parseAsync(output);
 }
+
+export interface PluginSubscriptionContract<
+  InputSchema extends ZodType = ZodType,
+  EventSchema extends ZodType = ZodType,
+> {
+  name: string;
+  input: InputSchema;
+  event: EventSchema;
+}
+
+export type SubscriptionInput<Contract extends PluginSubscriptionContract> = ZodOutput<
+  Contract["input"]
+>;
+export type SubscriptionEvent<Contract extends PluginSubscriptionContract> = ZodOutput<
+  Contract["event"]
+>;
+
+interface SubscriptionDefinition<InputSchema extends ZodType, EventSchema extends ZodType> {
+  name: string;
+  input: InputSchema;
+  event: EventSchema;
+}
+
+export function defineSubscription<InputSchema extends ZodType, EventSchema extends ZodType>(
+  definition: SubscriptionDefinition<InputSchema, EventSchema>,
+): PluginSubscriptionContract<InputSchema, EventSchema> {
+  const name = definition.name.trim();
+  if (!RPC_NAME.test(name)) throw new Error(`Invalid plugin subscription: ${definition.name}`);
+  return { ...definition, name };
+}
+
+/** One subscription from a client surface. Calling it or `release()` ends it. */
+export type PluginSubscriptionHandle = (() => void) & {
+  /** Resolves once the plugin acknowledged the subscription; rejects if it refused. */
+  readonly ready: Promise<void>;
+  release(): Promise<void>;
+};
+
+export interface PluginSubscriptionObserver {
+  event(event: unknown): void;
+  closed(error?: Error): void;
+}
+
+export interface PluginSubscriptionClosed {
+  /** Set when the plugin's handler failed, the plugin stopped, or an event failed validation. */
+  error?: Error;
+}
+
+export interface PluginSubscribeOptions {
+  /** Aborting releases the subscription. */
+  signal?: AbortSignal;
+  /** Runs once when the daemon closes the subscription. Not called after a release. */
+  onClosed?: (closed: PluginSubscriptionClosed) => void;
+}
+
+export function subscribePluginRpc<InputSchema extends ZodType, EventSchema extends ZodType>(
+  contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+  subscribe: (
+    method: string,
+    input: unknown,
+    observer: PluginSubscriptionObserver,
+  ) => PluginSubscriptionHandle,
+  input: PluginWireInput<ZodInput<InputSchema>>,
+  onEvent: (event: ZodOutput<EventSchema>) => void,
+  options: PluginSubscribeOptions = {},
+): PluginSubscriptionHandle {
+  // The plugin parses the input into the schema's output, so it receives the input as given.
+  contract.input.parse(input);
+  let closed = false;
+  function close(error?: Error) {
+    if (closed) return;
+    closed = true;
+    options.onClosed?.(error ? { error } : {});
+  }
+  const handle = subscribe(contract.name, input, {
+    event(event) {
+      if (closed) return;
+      const parsed = contract.event.safeParse(event);
+      if (parsed.success) return onEvent(parsed.data);
+      handle();
+      close(new Error(`Plugin subscription ${contract.name} sent an invalid event`));
+    },
+    closed: close,
+  });
+  if (options.signal) {
+    if (options.signal.aborted) handle();
+    else options.signal.addEventListener("abort", () => handle(), { once: true });
+  }
+  return handle;
+}
diff --git a/packages/plugin/src/server/acp-internal/connection.ts b/packages/plugin/src/server/acp-internal/connection.ts
index 86e22b2afe..f853a6006a 100644
--- a/packages/plugin/src/server/acp-internal/connection.ts
+++ b/packages/plugin/src/server/acp-internal/connection.ts
@@ -695,15 +695,16 @@ class AcpRuntime {
   async configure(
     changes: Extract<ProviderInput, { type: "session.configure" }>["changes"],
   ): Promise<void> {
-    const ordered: AcpConfigChange[] = [];
-    if (changes.model !== undefined) ordered.push({ target: "model", value: changes.model });
-    if (changes.mode !== undefined) ordered.push({ target: "mode", value: changes.mode });
+    const requested: AcpConfigChange[] = [];
+    if (changes.model !== undefined) requested.push({ target: "model", value: changes.model });
+    if (changes.mode !== undefined) requested.push({ target: "mode", value: changes.mode });
     if (changes.thinkingOption !== undefined) {
-      ordered.push({ target: "thinking", value: changes.thinkingOption });
+      requested.push({ target: "thinking", value: changes.thinkingOption });
     }
     for (const [id, value] of Object.entries(changes.settings ?? {})) {
-      ordered.push({ target: "setting", id, value });
+      requested.push({ target: "setting", id, value });
     }
+    const ordered = this.inAgentOrder(requested);
     const previousModes = this.modes ? structuredClone(this.modes) : null;
     const previousOptions = structuredClone(this.configOptions);
     this.configTransaction = true;
@@ -769,14 +770,36 @@ class AcpRuntime {
   }
 
   private async applyInitialConfig(config: ProviderSessionConfig): Promise<void> {
-    if (config.model) await this.applyConfigChange({ target: "model", value: config.model });
-    if (config.mode) await this.applyConfigChange({ target: "mode", value: config.mode });
+    const requested: AcpConfigChange[] = [];
+    if (config.model) requested.push({ target: "model", value: config.model });
+    if (config.mode) requested.push({ target: "mode", value: config.mode });
     if (config.thinkingOption) {
-      await this.applyConfigChange({ target: "thinking", value: config.thinkingOption });
+      requested.push({ target: "thinking", value: config.thinkingOption });
     }
     for (const [id, value] of Object.entries(config.settings)) {
-      await this.applyConfigChange({ target: "setting", id, value });
+      requested.push({ target: "setting", id, value });
     }
+    for (const change of this.inAgentOrder(requested)) await this.applyConfigChange(change);
+  }
+
+  // One option can reset another: choosing an fx provider also selects that provider's saved
+  // model, so a model applied first would be lost. Agents list the option that decides first.
+  private inAgentOrder(changes: readonly AcpConfigChange[]): AcpConfigChange[] {
+    const position = (change: AcpConfigChange): number => {
+      const configId = this.configIdFor(change);
+      const index = this.configOptions.findIndex((option) => option.id === configId);
+      return index === -1 ? this.configOptions.length : index;
+    };
+    return changes.toSorted((left, right) => position(left) - position(right));
+  }
+
+  private configIdFor(change: AcpConfigChange): string | undefined {
+    if (change.target === "setting") return change.id;
+    if (change.target === "model") return modelOption(this.configOptions)?.id;
+    if (change.target === "thinking") {
+      return this.configOptions.find((option) => option.category === "thought_level")?.id;
+    }
+    return this.configOptions.find((option) => option.category === "mode")?.id;
   }
 
   private async applyConfigChange(change: AcpConfigChange): Promise<void> {
@@ -804,13 +827,7 @@ class AcpRuntime {
       this.modes = { ...this.modes, currentModeId: change.value };
       return;
     }
-    let category: "model" | "thought_level" | null = null;
-    if (change.target === "model") category = "model";
-    if (change.target === "thinking") category = "thought_level";
-    const configId =
-      change.target === "setting"
-        ? change.id
-        : this.configOptions.find((option) => option.category === category)?.id;
+    const configId = this.configIdFor(change);
     if (!configId) {
       throw new Error(`ACP session does not expose ${change.target} configuration`);
     }
@@ -1375,7 +1392,7 @@ function toProviderConfigState(
   modes: NewSessionResponse["modes"],
   options: readonly SessionConfigOption[],
 ): ProviderConfigState {
-  const model = options.find((option) => option.category === "model");
+  const model = modelOption(options);
   const thinking = options.find((option) => option.category === "thought_level");
   return {
     model: selectedValue(model),
@@ -1393,11 +1410,23 @@ function toProviderConfigState(
       label: option.label,
     })),
     settings: options
-      .filter((option) => option.category !== "model" && option.category !== "thought_level")
+      .filter(
+        (option) =>
+          option !== model &&
+          option.category !== "thought_level" &&
+          !(modes && option.category === "mode"),
+      )
       .map(toProviderSetting),
   };
 }
 
+// ACP's category is a grouping hint, so one category can hold several controls. fx files its
+// provider first, then the model, Fast, and Ultrafast under "model".
+function modelOption(options: readonly SessionConfigOption[]): SessionConfigOption | undefined {
+  const candidates = options.filter((option) => option.category === "model");
+  return candidates.find((option) => option.id === "model") ?? candidates[0];
+}
+
 function toProviderCatalog(
   modes: NewSessionResponse["modes"],
   options: readonly SessionConfigOption[],
diff --git a/packages/plugin/src/server/acp.test.ts b/packages/plugin/src/server/acp.test.ts
index 1d99c73a75..266d0b0109 100644
--- a/packages/plugin/src/server/acp.test.ts
+++ b/packages/plugin/src/server/acp.test.ts
@@ -1155,6 +1155,99 @@ lines.on("line", (line) => {
     },
   );
 
+  it("selects the model control when an agent files several controls under the model category", async () => {
+    const executable = await fakeAcp(`const readline = require("node:readline");
+const lines = readline.createInterface({ input: process.stdin });
+const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
+let model = "small";
+const modes = { currentModeId: "auto", availableModes: [{ id: "auto", name: "Auto" }, { id: "ask", name: "Ask" }] };
+const options = () => [
+  { id: "provider", name: "Provider", category: "model", type: "select", currentValue: "gateway", options: [{ name: "Gateway", value: "gateway" }, { name: "Local", value: "local" }] },
+  { id: "model", name: "Model", category: "model", type: "select", currentValue: model, options: [{ name: "Small", value: "small" }, { name: "Large", value: "large" }] },
+  { id: "mode", name: "Session Mode", category: "mode", type: "select", currentValue: "auto", options: [{ name: "Auto", value: "auto" }, { name: "Ask", value: "ask" }] },
+  { id: "fast", name: "Fast Mode", category: "model", type: "select", currentValue: "false", options: [{ name: "Off", value: "false" }, { name: "On", value: "true" }] },
+];
+lines.on("line", (line) => {
+  const message = JSON.parse(line);
+  if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
+  else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", modes, configOptions: options() } });
+  else if (message.method === "session/set_config_option") {
+    if (message.params.configId === "model") model = message.params.value;
+    send({ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } });
+  }
+});`);
+    const { connection, events } = await connect(executable, [
+      "prompt.message",
+      "session.configure",
+    ]);
+    await connection.send({ type: "catalog", requestId: "catalog-1" });
+    await waitForEvent(events, (event) => event.type === "catalog");
+    expect(events.find((event) => event.type === "catalog")).toMatchObject({
+      catalog: {
+        defaultModel: "small",
+        models: [
+          { id: "small", label: "Small" },
+          { id: "large", label: "Large" },
+        ],
+      },
+    });
+
+    await connection.send(openInput());
+    await waitForEvent(events, (event) => event.type === "session.ready");
+    await connection.send({
+      type: "session.configure",
+      requestId: "configure-1",
+      sessionId: "session-1",
+      changes: { model: "large" },
+    });
+    await waitForEvent(
+      events,
+      (event) => event.type === "request.completed" && event.requestId === "configure-1",
+    );
+    const config = events.findLast((event) => event.type === "session.config");
+    expect(config).toMatchObject({ config: { model: "large" } });
+    if (config?.type !== "session.config") throw new Error("Expected session.config");
+    expect(config.config.settings?.map((setting) => setting.id)).toEqual(["provider", "fast"]);
+    await connection.close();
+  });
+
+  it("applies opening configuration in the order the agent lists its options", async () => {
+    const executable = await fakeAcp(`const readline = require("node:readline");
+const lines = readline.createInterface({ input: process.stdin });
+const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
+let provider = "first";
+let model = "first-saved";
+const saved = { first: "first-saved", second: "second-saved" };
+const select = (id, currentValue, values) => ({ id, name: id, category: "model", type: "select", currentValue, options: values.map((value) => ({ name: value, value })) });
+const options = () => [
+  select("provider", provider, ["first", "second"]),
+  select("model", model, ["first-saved", "second-saved", "second-chosen"]),
+];
+lines.on("line", (line) => {
+  const message = JSON.parse(line);
+  if (message.method === "initialize") send({ jsonrpc: "2.0", id: message.id, result: { protocolVersion: message.params.protocolVersion, agentCapabilities: {} } });
+  else if (message.method === "session/new") send({ jsonrpc: "2.0", id: message.id, result: { sessionId: "native-1", configOptions: options() } });
+  else if (message.method === "session/set_config_option") {
+    if (message.params.configId === "provider") { provider = message.params.value; model = saved[provider]; }
+    if (message.params.configId === "model") model = message.params.value;
+    send({ jsonrpc: "2.0", id: message.id, result: { configOptions: options() } });
+  }
+});`);
+    const { connection, events } = await connect(executable, [
+      "prompt.message",
+      "session.configure",
+    ]);
+    const input = openInput({ provider: "second" });
+
+    await connection.send({ ...input, config: { ...input.config, model: "second-chosen" } });
+
+    await waitForEvent(events, (event) => event.type === "session.ready");
+    expect(events.findLast((event) => event.type === "session.config")).toMatchObject({
+      config: { model: "second-chosen" },
+    });
+    await connection.close();
+  });
+
   it("gives discovery transformers the discovered session configuration facade", async () => {
     const executable = await fakeAcp(`const readline = require("node:readline");
 const lines = readline.createInterface({ input: process.stdin });
diff --git a/packages/plugin/src/server/contracts.ts b/packages/plugin/src/server/contracts.ts
index 984b9c117b..45b283743d 100644
--- a/packages/plugin/src/server/contracts.ts
+++ b/packages/plugin/src/server/contracts.ts
@@ -1,6 +1,6 @@
 import type { PaseoApi } from "@getpaseo/client";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
-import type { PluginRpcContract } from "../rpc.js";
+import type { PluginRpcContract, PluginSubscriptionContract, PluginWireInput } from "../rpc.js";
 import type { PluginCleanup } from "../contracts.js";
 import type { ProviderRegistration } from "./provider.js";
 import type { UsageSourceRegistration } from "./usage.js";
@@ -10,6 +10,18 @@ export interface PluginHandlerContext {
   paseo: PaseoApi;
 }
 
+/** What a subscription handler receives beside its input. */
+export interface PluginSubscriptionContext<Event = unknown> extends PluginHandlerContext {
+  /**
+   * Sends one event to this subscriber. A `Uint8Array` event travels as a binary frame; any other
+   * event is JSON and must not contain a `Uint8Array`. Resolves once the event left the plugin
+   * process. Events pushed after `signal` aborts are dropped.
+   */
+  push(event: Event): Promise<void>;
+  /** Aborts when the subscriber releases, disconnects, or the plugin stops. */
+  signal: AbortSignal;
+}
+
 export type PluginSettingsState<Schema extends ZodType> =
   | {
       status: "ready";
@@ -31,12 +43,24 @@ export interface PluginServerContext extends PluginLifecycleRegistration {
   registerSettings<Schema extends ZodType>(
     definition: import("../settings.js").SettingsDefinition<Schema>,
   ): PluginSettings<Schema>;
+  /**
+   * Serves a subscription. The handler starts the work and returns; the subscription stays open
+   * until `signal` aborts. A handler that throws refuses the subscription. When it returns a
+   * promise, settling the promise closes the subscription, with the rejection as its error.
+   */
+  handle<InputSchema extends ZodType, EventSchema extends ZodType>(
+    contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+    handler: (
+      input: ZodOutput<InputSchema>,
+      context: PluginSubscriptionContext<PluginWireInput<ZodInput<EventSchema>>>,
+    ) => void | Promise<void>,
+  ): void;
   handle<InputSchema extends ZodType, OutputSchema extends ZodType>(
     contract: PluginRpcContract<InputSchema, OutputSchema>,
     handler: (
       input: ZodOutput<InputSchema>,
       context: PluginHandlerContext,
-    ) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>,
+    ) => PluginWireInput<ZodInput<OutputSchema>> | Promise<PluginWireInput<ZodInput<OutputSchema>>>,
   ): void;
   registerProvider(provider: ProviderRegistration): void;
   registerUsageSource(source: UsageSourceRegistration): void;
diff --git a/packages/plugin/src/server/index.ts b/packages/plugin/src/server/index.ts
index bb6bf4ede8..4ff70ae74d 100644
--- a/packages/plugin/src/server/index.ts
+++ b/packages/plugin/src/server/index.ts
@@ -11,6 +11,7 @@ export type {
   PluginServerContribution,
   PluginSettings,
   PluginSettingsState,
+  PluginSubscriptionContext,
 } from "./contracts.js";
 export type {
   PluginHooks,
diff --git a/packages/plugin/src/server/lifecycle.ts b/packages/plugin/src/server/lifecycle.ts
index 20df9c2dcb..acc703ed12 100644
--- a/packages/plugin/src/server/lifecycle.ts
+++ b/packages/plugin/src/server/lifecycle.ts
@@ -4,6 +4,7 @@ import type {
   AgentPermissionResponse,
   AgentTimelineItem,
   AgentSessionConfig,
+  JsonValue,
 } from "@getpaseo/protocol/agent-types";
 import type { PaseoApi } from "@getpaseo/client";
 import type { WorkspaceCreateRequest } from "@getpaseo/protocol/messages";
@@ -19,6 +20,8 @@ export interface PluginHookWorkspace {
   cwd: string;
   name: string | null;
   archivedAt: string | null;
+  /** Data plugins stored on the workspace. Paseo never reads a key. */
+  metadata: Record<string, JsonValue>;
 }
 
 export interface PluginHookWorktree {
@@ -68,6 +71,8 @@ export interface PluginHookAgent {
   provider: string;
   cwd: string;
   title: string | null;
+  /** Data plugins stored on the agent. Paseo never reads a key. */
+  metadata: Record<string, JsonValue>;
 }
 
 export interface PluginSessionOpenRequest {
@@ -79,6 +84,7 @@ export interface PluginSessionOpenRequest {
   purpose: "interactive" | "history";
   readonly title: string | null;
   readonly labels: Readonly<Record<string, string>>;
+  readonly metadata: Readonly<Record<string, JsonValue>>;
   tools: AgentToolDefinition[];
   env: Record<string, string>;
   mcpServers: NonNullable<AgentSessionConfig["mcpServers"]>;
@@ -116,15 +122,27 @@ export interface PluginHookEvents {
 
 export interface PluginHookRequests {
   "worktree.create.before": PluginWorktreeCreateRequest;
-  "agent.create.before": { config: AgentSessionConfig; env?: Record<string, string> };
+  "agent.create.before": {
+    config: AgentSessionConfig;
+    env?: Record<string, string>;
+    /** Stored on the new agent. Always present in the payload; return it changed to change it. */
+    metadata?: Record<string, JsonValue>;
+  };
   "agent.open.before": PluginSessionOpenRequest;
   "workspace.create.before": Omit<WorkspaceCreateRequest, "type" | "requestId">;
 }
 
+/** What a hook may return. An omitted `metadata` stays as it was. */
+type PluginHookRequestResults = Omit<PluginHookRequests, "agent.open.before"> & {
+  "agent.open.before": Omit<PluginSessionOpenRequest, "metadata"> & {
+    metadata?: Readonly<Record<string, JsonValue>>;
+  };
+};
+
 export type PluginHooks = {
   [Name in keyof PluginHookRequests]: {
     request: PluginHookRequests[Name];
-    result: PluginHookRequests[Name];
+    result: PluginHookRequestResults[Name];
   };
 } & { [Name in keyof PluginHookEvents]: { payload: PluginHookEvents[Name] } } & {
   "worktree.create.after": { payload: { worktree: PluginHookWorktree } };
diff --git a/packages/plugin/src/server/provider.ts b/packages/plugin/src/server/provider.ts
index ee9fbc21c2..5b9511f1f7 100644
--- a/packages/plugin/src/server/provider.ts
+++ b/packages/plugin/src/server/provider.ts
@@ -116,7 +116,9 @@ export interface ProviderSessionConfig {
   model?: string;
   mode?: string;
   thinkingOption?: string;
+  /** @deprecated The same values as `providerOptions`. */
   settings: Readonly<Record<string, JsonValue>>;
+  /** The agent's options, the provider defaults from `config.json` included. */
   providerOptions?: Readonly<Record<string, unknown>>;
   title?: string;
   persist: boolean;
@@ -126,6 +128,13 @@ export interface ProviderConfigChanges {
   model?: string | null;
   mode?: string | null;
   thinkingOption?: string | null;
+  /**
+   * The option keys to change on the running session, with or without a control. Apply every key
+   * or fail the whole request, for a key you only read when a session opens. `null` returns the
+   * key to the provider's own default. The committed values come back in `session.config`.
+   */
+  providerOptions?: Readonly<Record<string, JsonValue>>;
+  /** @deprecated Sent next to `providerOptions` to a provider that reports `settings`. */
   settings?: Readonly<Record<string, JsonValue>>;
 }
 
@@ -311,6 +320,34 @@ export interface ProviderMode {
   isUnattended?: boolean;
 }
 
+/**
+ * Draws one top-level option key in the composer. The control holds no value: Paseo reads it
+ * from the agent's options.
+ */
+export type ProviderOptionControl =
+  | {
+      type: "toggle";
+      key: string;
+      label: string;
+      description?: string;
+      /** A Lucide icon name. */
+      icon?: string;
+      /** Shown while the key has no value. */
+      defaultValue?: boolean;
+    }
+  | {
+      type: "select";
+      key: string;
+      label: string;
+      description?: string;
+      /** A Lucide icon name. */
+      icon?: string;
+      /** The choice shown while the key has no value. */
+      defaultValue?: string;
+      choices: ReadonlyArray<{ value: string; label: string; description?: string }>;
+    };
+
+/** @deprecated Report `controls` and `providerOptions` instead. */
 export type ProviderSetting =
   | {
       type: "toggle";
@@ -335,7 +372,12 @@ export interface ProviderConfigState {
   models: readonly ProviderModel[];
   modes: readonly ProviderMode[];
   thinkingOptions: readonly ProviderThinkingOption[];
-  settings: readonly ProviderSetting[];
+  /** The option keys that get a composer control. May change at runtime, for example per model. */
+  controls?: readonly ProviderOptionControl[];
+  /** What the session runs with now, for the keys it reports. Publish the committed values. */
+  providerOptions?: Readonly<Record<string, JsonValue>>;
+  /** @deprecated Report `controls` and `providerOptions`. Each setting id is an option key. */
+  settings?: readonly ProviderSetting[];
 }
 
 export interface ProviderCatalog {
@@ -888,6 +930,7 @@ const configChangesSchema = z
     model: z.string().nullable().optional(),
     mode: z.string().nullable().optional(),
     thinkingOption: z.string().nullable().optional(),
+    providerOptions: jsonObjectSchema.optional(),
     settings: jsonObjectSchema.optional(),
   })
   .strict();
@@ -1024,6 +1067,33 @@ const settingSchema = z.discriminatedUnion("type", [
     })
     .strip(),
 ]);
+const controlSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("toggle"),
+      key: idSchema,
+      label: z.string(),
+      description: z.string().optional(),
+      icon: z.string().optional(),
+      defaultValue: z.boolean().optional(),
+    })
+    .strip(),
+  z
+    .object({
+      type: z.literal("select"),
+      key: idSchema,
+      label: z.string(),
+      description: z.string().optional(),
+      icon: z.string().optional(),
+      defaultValue: z.string().optional(),
+      choices: z.array(
+        z
+          .object({ value: z.string(), label: z.string(), description: z.string().optional() })
+          .strip(),
+      ),
+    })
+    .strip(),
+]);
 const configStateSchema = z
   .object({
     model: z.string().optional(),
@@ -1032,7 +1102,9 @@ const configStateSchema = z
     models: z.array(modelSchema),
     modes: z.array(modeSchema),
     thinkingOptions: z.array(selectOptionSchema),
-    settings: z.array(settingSchema),
+    controls: z.array(controlSchema).optional(),
+    providerOptions: jsonObjectSchema.optional(),
+    settings: z.array(settingSchema).optional(),
   })
   .strip();
 const catalogSchema = z
diff --git a/packages/plugin/src/settings.ts b/packages/plugin/src/settings.ts
index 30e890b3ef..e670885678 100644
--- a/packages/plugin/src/settings.ts
+++ b/packages/plugin/src/settings.ts
@@ -4,10 +4,10 @@ import { defineRpc } from "./rpc.js";
 
 export interface SettingsDefinition<Schema extends ZodType = ZodType> {
   id: string;
-  scope: "host";
+  scope: "host" | "device";
   version: number;
   schema: Schema;
-  /** Convert a previous stored version to the current schema. Runs on the host. */
+  /** Convert a previous stored version to the current schema. Runs in the selected scope. */
   migrate?: (values: unknown, fromVersion: number) => unknown | Promise<unknown>;
 }
 
@@ -15,7 +15,8 @@ export function defineSettings<Schema extends ZodType>(
   definition: SettingsDefinition<Schema>,
 ): SettingsDefinition<Schema> {
   if (!/^[a-z][a-z0-9_-]*$/.test(definition.id)) throw new Error("Invalid settings ID");
-  if (definition.scope !== "host") throw new Error("Only host-scoped settings are supported");
+  if (definition.scope !== "host" && definition.scope !== "device")
+    throw new Error("Invalid settings scope");
   if (!Number.isSafeInteger(definition.version) || definition.version < 1)
     throw new Error("Invalid settings version");
   return definition;
diff --git a/packages/protocol/LICENSE b/packages/protocol/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/protocol/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/protocol/package.json b/packages/protocol/package.json
index 21d500fd4f..6877c084af 100644
--- a/packages/protocol/package.json
+++ b/packages/protocol/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo shared protocol schemas and wire types",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map",
diff --git a/packages/protocol/src/agent-profile.ts b/packages/protocol/src/agent-profile.ts
index 2534984240..9ed75a38a9 100644
--- a/packages/protocol/src/agent-profile.ts
+++ b/packages/protocol/src/agent-profile.ts
@@ -21,7 +21,10 @@ export const AgentProfileSchema = z
     model: z.string().optional(),
     modeId: z.string().optional(),
     thinkingOptionId: z.string().optional(),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read as `options`.
     featureValues: z.record(z.string(), z.unknown()).optional(),
+    /** Provider options applied when the profile creates an agent. */
+    options: z.record(z.string(), z.unknown()).optional(),
     /** Free text, surfaced to orchestrating agents by the `list_profiles` MCP tool. */
     notes: z.string().optional(),
   })
diff --git a/packages/protocol/src/agent-state-bucket.test.ts b/packages/protocol/src/agent-state-bucket.test.ts
index 3c5d281b39..ef57394577 100644
--- a/packages/protocol/src/agent-state-bucket.test.ts
+++ b/packages/protocol/src/agent-state-bucket.test.ts
@@ -6,6 +6,30 @@ import {
 } from "./agent-state-bucket.js";
 
 describe("deriveAgentStateBucket", () => {
+  it("shows idle agents with background work as running while preserving attention precedence", () => {
+    const backgroundWork = { count: 1 };
+    expect(
+      deriveAgentStateBucket({
+        status: "idle",
+        backgroundWork,
+        requiresAttention: true,
+        attentionReason: "finished",
+      }),
+    ).toBe("running");
+    expect(
+      deriveAgentStateBucket({ status: "idle", backgroundWork, attentionReason: "permission" }),
+    ).toBe("needs_input");
+    expect(deriveAgentStateBucket({ status: "error", backgroundWork })).toBe("running");
+    expect(
+      deriveAgentStateBucket({
+        status: "error",
+        backgroundWork,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
+    ).toBe("failed");
+    expect(deriveAgentStateBucket({ status: "idle", backgroundWork: { count: 0 } })).toBe("done");
+  });
   it("prioritizes pending permissions as needs_input", () => {
     expect(
       deriveAgentStateBucket({
@@ -39,6 +63,28 @@ describe("deriveAgentStateBucket", () => {
     ).toBe("failed");
   });
 
+  it("treats an errored agent whose error was read as done", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: false,
+        attentionReason: null,
+      }),
+    ).toBe("done");
+  });
+
+  it("treats an errored agent with unread error attention as failed", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
+    ).toBe("failed");
+  });
+
   it("treats unread finished agents as attention", () => {
     expect(
       deriveAgentStateBucket({
@@ -83,10 +129,21 @@ describe("getAgentStatusPriority", () => {
   it("prioritizes pending permissions before errors and running agents", () => {
     const permission = getAgentStatusPriority({ status: "running", pendingPermissionCount: 1 });
     expect(permission).toBeLessThan(
-      getAgentStatusPriority({ status: "error", pendingPermissionCount: 0 }),
+      getAgentStatusPriority({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
     );
     expect(permission).toBeLessThan(
       getAgentStatusPriority({ status: "running", pendingPermissionCount: 0 }),
     );
   });
+
+  it("ranks an errored agent with a read error alongside completed agents", () => {
+    expect(getAgentStatusPriority({ status: "error", requiresAttention: false })).toBe(
+      getAgentStatusPriority({ status: "idle" }),
+    );
+  });
 });
diff --git a/packages/protocol/src/agent-state-bucket.ts b/packages/protocol/src/agent-state-bucket.ts
index 2973152f1d..2e696c5bbe 100644
--- a/packages/protocol/src/agent-state-bucket.ts
+++ b/packages/protocol/src/agent-state-bucket.ts
@@ -9,6 +9,7 @@ export interface AgentStateBucketInput {
   pendingPermissionCount?: number;
   requiresAttention?: boolean;
   attentionReason?: AgentAttentionReason;
+  backgroundWork?: { count: number } | null;
 }
 
 const WORKSPACE_STATE_BUCKET_PRIORITY = {
@@ -19,14 +20,20 @@ const WORKSPACE_STATE_BUCKET_PRIORITY = {
   done: 4,
 } as const satisfies Record<WorkspaceStateBucket, number>;
 
+// An error is a notification like a finish: once the user has seen it, the agent stops showing as
+// failed even though its lifecycle stays "error" until the next turn starts.
+function hasUnreadError(input: AgentStateBucketInput): boolean {
+  return input.requiresAttention === true && input.attentionReason === "error";
+}
+
 export function deriveAgentStateBucket(input: AgentStateBucketInput): WorkspaceStateBucket {
   if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
     return "needs_input";
   }
-  if (input.status === "error" || input.attentionReason === "error") {
+  if (hasUnreadError(input)) {
     return "failed";
   }
-  if (input.status === "running") {
+  if (input.status === "running" || (input.backgroundWork?.count ?? 0) > 0) {
     return "running";
   }
   if (input.requiresAttention) {
@@ -43,10 +50,10 @@ export function getAgentStatusPriority(input: AgentStateBucketInput): number {
   if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
     return 0;
   }
-  if (input.status === "error" || input.attentionReason === "error") {
+  if (hasUnreadError(input)) {
     return 1;
   }
-  if (input.status === "running") {
+  if (input.status === "running" || (input.backgroundWork?.count ?? 0) > 0) {
     return 2;
   }
   if (input.status === "initializing") {
diff --git a/packages/protocol/src/agent-types.ts b/packages/protocol/src/agent-types.ts
index ca04655430..efbd119c31 100644
--- a/packages/protocol/src/agent-types.ts
+++ b/packages/protocol/src/agent-types.ts
@@ -1,5 +1,12 @@
 import type { AgentMessage } from "./agent-message.js";
-import type { AgentAttachment } from "./messages.js";
+import type {
+  AgentAttachment,
+  AgentOptionChoiceSchema,
+  AgentOptionControlSchema,
+  AgentOptionSelectControlSchema,
+  AgentOptionToggleControlSchema,
+} from "./messages.js";
+import type { z } from "zod";
 
 export type AgentProvider = string;
 
@@ -154,6 +161,20 @@ export interface AgentFeatureSelect {
 
 export type AgentFeature = AgentFeatureToggle | AgentFeatureSelect;
 
+export type AgentOptionChoice = z.infer<typeof AgentOptionChoiceSchema>;
+
+/** `key` is the top-level provider option key the control reads and writes. */
+export type AgentOptionToggleControl = z.infer<typeof AgentOptionToggleControlSchema>;
+
+/** `defaultValue` is the choice an unset option stands for. */
+export type AgentOptionSelectControl = z.infer<typeof AgentOptionSelectControlSchema>;
+
+/**
+ * A provider's description of a composer control over one top-level option key.
+ * The control carries no value: it is read from the agent's effective options.
+ */
+export type AgentOptionControl = z.infer<typeof AgentOptionControlSchema>;
+
 export interface AgentCapabilityFlags {
   [capability: string]: boolean | undefined;
   supportsStreaming: boolean;
@@ -523,6 +544,10 @@ export interface AgentSessionConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
+  /**
+   * @deprecated COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+   * Folded into `providerOptions` at the daemon's edge; the daemon never reads it internally.
+   */
   featureValues?: Record<string, unknown>;
   title?: string | null;
   providerOptions?: ProviderOptions;
diff --git a/packages/protocol/src/binary-frames/demux.ts b/packages/protocol/src/binary-frames/demux.ts
index c207026362..b21118d301 100644
--- a/packages/protocol/src/binary-frames/demux.ts
+++ b/packages/protocol/src/binary-frames/demux.ts
@@ -1,9 +1,11 @@
+import { decodeDiffFrame, DiffOpcode, type DiffFrame } from "./diff.js";
 import { HOST_ROUTE_OPCODE, decodeHostRouteFrame, type HostRouteFrame } from "./host-route.js";
 import {
   decodeFileTransferFrame,
   FileTransferOpcode,
   type FileTransferFrame,
 } from "./file-transfer.js";
+import { decodePluginFrame, PluginFrameOpcode, type PluginFrame } from "./plugin.js";
 import {
   decodeTerminalStreamFrame,
   TerminalStreamOpcode,
@@ -11,11 +13,20 @@ import {
 } from "./terminal.js";
 
 export type BinaryFrame =
+  | { kind: "diff"; frame: DiffFrame }
   | { kind: "host_route"; frame: HostRouteFrame }
   | { kind: "terminal"; frame: TerminalStreamFrame }
-  | { kind: "file_transfer"; frame: FileTransferFrame };
+  | { kind: "file_transfer"; frame: FileTransferFrame }
+  | { kind: "plugin"; frame: PluginFrame };
 
 export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
+  if (Object.values(DiffOpcode).some((opcode) => opcode === bytes[0])) {
+    return { kind: "diff", frame: decodeDiffFrame(bytes) };
+  }
+  return decodeExistingBinaryFrame(bytes);
+}
+
+function decodeExistingBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
   switch (bytes[0]) {
     case HOST_ROUTE_OPCODE: {
       const frame = decodeHostRouteFrame(bytes);
@@ -38,6 +49,12 @@ export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
       const frame = decodeFileTransferFrame(bytes);
       return frame ? { kind: "file_transfer", frame } : null;
     }
+    case PluginFrameOpcode.Event:
+    case PluginFrameOpcode.Output:
+    case PluginFrameOpcode.Input: {
+      const frame = decodePluginFrame(bytes);
+      return frame ? { kind: "plugin", frame } : null;
+    }
     default:
       return null;
   }
diff --git a/packages/protocol/src/binary-frames/diff.test.ts b/packages/protocol/src/binary-frames/diff.test.ts
new file mode 100644
index 0000000000..fcc2885521
--- /dev/null
+++ b/packages/protocol/src/binary-frames/diff.test.ts
@@ -0,0 +1,270 @@
+import { expect, test } from "vitest";
+import { decodeDiffFrame, encodeDiffFrame } from "./diff.js";
+import { decodeBinaryFrame } from "./demux.js";
+import { decodePluginFrame } from "./plugin.js";
+
+test("routes diff revisions independently of plugin frames", () => {
+  const frame = {
+    opcode: 0x40 as const,
+    slot: 0,
+    revision: 1,
+    baseRevision: 0,
+    baseSha: "",
+    headSha: "",
+    mergeBaseSha: "",
+    entries: [],
+  };
+  const bytes = encodeDiffFrame(frame);
+  expect([...bytes]).toEqual([64, 0, 1, 1, 0, 0, 0, 0, 0]);
+  expect(decodeDiffFrame(bytes)).toEqual(frame);
+  expect(decodeBinaryFrame(bytes)).toEqual({ kind: "diff", frame });
+  expect(decodePluginFrame(bytes)).toBeNull();
+});
+
+test("roundtrips Unicode runs and materializes the existing file shape", async () => {
+  const { materializeDiffFile } = await import("./diff.js");
+  const frame = {
+    opcode: 0x41 as const,
+    slot: 255,
+    revision: 128,
+    files: [
+      {
+        path: "é.ts",
+        hunks: [
+          {
+            oldStart: 1,
+            oldCount: 1,
+            newStart: 1,
+            newCount: 1,
+            lines: [
+              {
+                type: "add" as const,
+                content: "😀é",
+                runs: [
+                  { style: "string", length: 2 },
+                  { style: null, length: 2 },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+  const file = materializeDiffFile(
+    {
+      path: "é.ts",
+      oldPath: null,
+      change: "modified",
+      content: "text",
+      additions: 1,
+      deletions: 1,
+      body: true,
+    },
+    frame.files[0],
+    false,
+  );
+  expect(file.hunks[0].lines[0].tokens).toEqual([
+    { text: "😀", style: "string" },
+    { text: "é", style: null },
+  ]);
+});
+
+test("preserves binary additions, modifications, deletions and mode-only text", async () => {
+  const { materializeDiffFile } = await import("./diff.js");
+  for (const change of ["added", "modified", "deleted"] as const) {
+    const entry = {
+      path: "image.png",
+      oldPath: null,
+      change,
+      content: "binary" as const,
+      additions: 0,
+      deletions: 0,
+      body: false,
+    };
+    const begin = {
+      opcode: 0x40 as const,
+      slot: 1,
+      revision: 1,
+      baseRevision: 0,
+      baseSha: "",
+      headSha: "",
+      mergeBaseSha: "",
+      entries: [entry],
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(begin))).toEqual(begin);
+    expect(materializeDiffFile(entry, null, false)).toEqual({
+      path: "image.png",
+      isNew: change === "added",
+      isDeleted: change === "deleted",
+      additions: 0,
+      deletions: 0,
+      status: "binary",
+      hunks: [],
+    });
+  }
+  expect(
+    materializeDiffFile(
+      {
+        path: "script",
+        oldPath: null,
+        change: "modified",
+        content: "text",
+        additions: 0,
+        deletions: 0,
+        body: true,
+      },
+      { path: "script", hunks: [] },
+      false,
+    ),
+  ).toEqual({
+    path: "script",
+    isNew: false,
+    isDeleted: false,
+    additions: 0,
+    deletions: 0,
+    status: "ok",
+    hunks: [],
+  });
+});
+
+test("rejects every truncated prefix, unknown version, trailing data, and invalid coverage", () => {
+  const end = {
+    opcode: 0x42 as const,
+    slot: 1,
+    revision: 9007199254740991,
+    diffTooLarge: true,
+    omitted: ["a.ts"],
+    error: { code: "REF_NOT_FOUND" as const, message: "missing" },
+  };
+  const bytes = encodeDiffFrame(end);
+  expect(decodeDiffFrame(bytes)).toEqual(end);
+  for (let length = 0; length < bytes.length; length++)
+    expect(() => decodeDiffFrame(bytes.slice(0, length))).toThrow();
+  const version = bytes.slice();
+  version[2] = 2;
+  expect(() => decodeDiffFrame(version)).toThrow("version");
+  expect(() => decodeDiffFrame(Uint8Array.from([...bytes, 0]))).toThrow("Trailing");
+  expect(() =>
+    encodeDiffFrame({
+      opcode: 0x41,
+      slot: 1,
+      revision: 1,
+      files: [
+        {
+          path: "x",
+          hunks: [
+            {
+              oldStart: 0,
+              oldCount: 0,
+              newStart: 1,
+              newCount: 1,
+              lines: [{ type: "add", content: "😀", runs: [{ style: null, length: 1 }] }],
+            },
+          ],
+        },
+      ],
+    }),
+  ).toThrow("cover");
+});
+
+test("uses fixed UTF-8 byte vectors while runs count UTF-16 units", () => {
+  const bytes = Uint8Array.from([
+    65, 0, 1, 1, 1, 1, 120, 1, 0, 0, 1, 1, 1, 129, 7, 240, 159, 152, 128, 101, 204, 129, 1, 3, 4,
+  ]);
+  const frame = {
+    opcode: 0x41 as const,
+    slot: 0,
+    revision: 1,
+    files: [
+      {
+        path: "x",
+        hunks: [
+          {
+            oldStart: 0,
+            oldCount: 0,
+            newStart: 1,
+            newCount: 1,
+            lines: [
+              { type: "add" as const, content: "😀é", runs: [{ style: "string", length: 4 }] },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  expect(encodeDiffFrame(frame)).toEqual(bytes);
+  expect(decodeDiffFrame(bytes)).toEqual(frame);
+  const unknownStyle = bytes.slice();
+  unknownStyle[23] = 255;
+  expect(decodeDiffFrame(unknownStyle)).toEqual({
+    ...frame,
+    files: [
+      {
+        ...frame.files[0],
+        hunks: [
+          {
+            ...frame.files[0].hunks[0],
+            lines: [{ type: "add", content: "😀é", runs: [{ style: null, length: 4 }] }],
+          },
+        ],
+      },
+    ],
+  });
+});
+
+test("roundtrips generated entry lists across varint boundaries", () => {
+  for (const revision of [0, 1, 127, 128, 16383, 16384, 4294967296, Number.MAX_SAFE_INTEGER]) {
+    const entries = Array.from({ length: 130 }, (_, index) => ({
+      path: `src/${index}-😀.ts`,
+      oldPath: `old/${index}.ts`,
+      change: "renamed" as const,
+      content: "text" as const,
+      additions: index * 128,
+      deletions: index,
+      body: true,
+    }));
+    const begin = {
+      opcode: 0x40 as const,
+      slot: 255,
+      revision,
+      baseRevision: 0,
+      baseSha: "base",
+      headSha: "head",
+      mergeBaseSha: "merge",
+      entries,
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(begin))).toEqual(begin);
+  }
+});
+
+test.each([true, false])(
+  "preserves BOM-prefixed paths and source lines with runs=%s",
+  (highlight) => {
+    const frame = {
+      opcode: 0x41 as const,
+      slot: 0,
+      revision: 1,
+      files: [
+        {
+          path: "\uFEFFbom.ts",
+          hunks: [
+            {
+              oldStart: 1,
+              oldCount: 1,
+              newStart: 1,
+              newCount: 1,
+              lines: (["add", "remove", "context"] as const).map((type) => ({
+                type,
+                content: "\uFEFFvalue",
+                runs: highlight ? [{ style: null, length: 6 }] : undefined,
+              })),
+            },
+          ],
+        },
+      ],
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+  },
+);
diff --git a/packages/protocol/src/binary-frames/diff.ts b/packages/protocol/src/binary-frames/diff.ts
new file mode 100644
index 0000000000..9f11450b7d
--- /dev/null
+++ b/packages/protocol/src/binary-frames/diff.ts
@@ -0,0 +1,360 @@
+import type { ParsedDiffFile } from "../messages.js";
+
+// Opcodes 0x40–0x4f are reserved for diff revisions. Plugins own 0x20–0x2f.
+export const DiffOpcode = { Begin: 0x40, Bodies: 0x41, End: 0x42 } as const;
+export const DIFF_HIGHLIGHT_STYLES = [
+  null,
+  "keyword",
+  "comment",
+  "string",
+  "number",
+  "literal",
+  "function",
+  "definition",
+  "class",
+  "type",
+  "tag",
+  "attribute",
+  "property",
+  "variable",
+  "operator",
+  "punctuation",
+  "regexp",
+  "escape",
+  "meta",
+  "heading",
+  "link",
+] as const;
+const CHANGES = ["added", "modified", "deleted", "renamed"] as const;
+const CONTENTS = ["text", "binary"] as const;
+const KINDS = ["context", "add", "remove", "header"] as const;
+const ERRORS = [
+  null,
+  "NOT_GIT_REPO",
+  "REF_NOT_FOUND",
+  "INVALID_COMPARE",
+  "TOO_MANY_SUBSCRIPTIONS",
+  "UNKNOWN",
+] as const;
+export interface DiffEntry {
+  path: string;
+  oldPath: string | null;
+  change: (typeof CHANGES)[number];
+  content: (typeof CONTENTS)[number];
+  additions: number;
+  deletions: number;
+  body: boolean;
+}
+export interface DiffRun {
+  style: string | null;
+  length: number;
+}
+export interface DiffStreamLine {
+  type: (typeof KINDS)[number];
+  content: string;
+  runs?: DiffRun[];
+}
+export interface DiffStreamHunk {
+  oldStart: number;
+  oldCount: number;
+  newStart: number;
+  newCount: number;
+  lines: DiffStreamLine[];
+}
+export interface DiffBody {
+  path: string;
+  hunks: DiffStreamHunk[];
+}
+export interface DiffBegin {
+  opcode: typeof DiffOpcode.Begin;
+  slot: number;
+  revision: number;
+  baseRevision: number;
+  baseSha: string;
+  headSha: string;
+  mergeBaseSha: string;
+  entries: DiffEntry[];
+}
+export interface DiffBodies {
+  opcode: typeof DiffOpcode.Bodies;
+  slot: number;
+  revision: number;
+  files: DiffBody[];
+}
+export interface DiffEnd {
+  opcode: typeof DiffOpcode.End;
+  slot: number;
+  revision: number;
+  diffTooLarge: boolean;
+  omitted: string[];
+  error: { code: NonNullable<(typeof ERRORS)[number]>; message: string } | null;
+}
+export type DiffFrame = DiffBegin | DiffBodies | DiffEnd;
+export class InvalidDiffFrameError extends Error {}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+class Writer {
+  private bytes: number[] = [];
+  byte(value: number): void {
+    if (!Number.isInteger(value) || value < 0 || value > 255)
+      throw new InvalidDiffFrameError("Invalid byte");
+    this.bytes.push(value);
+  }
+  uint(value: number): void {
+    if (!Number.isSafeInteger(value) || value < 0)
+      throw new InvalidDiffFrameError("Invalid unsigned integer");
+    do {
+      const next = value % 128;
+      value = Math.floor(value / 128);
+      this.byte(next + (value ? 128 : 0));
+    } while (value);
+  }
+  str(value: string): void {
+    const bytes = textEncoder.encode(value);
+    this.uint(bytes.length);
+    for (const byte of bytes) this.byte(byte);
+  }
+  finish(): Uint8Array {
+    return Uint8Array.from(this.bytes);
+  }
+}
+class Reader {
+  private offset = 0;
+  constructor(private bytes: Uint8Array) {}
+  byte(): number {
+    if (this.offset >= this.bytes.length) throw new InvalidDiffFrameError("Truncated diff frame");
+    return this.bytes[this.offset++];
+  }
+  uint(): number {
+    let value = 0;
+    let factor = 1;
+    for (let index = 0; index < 8; index++) {
+      const byte = this.byte();
+      value += (byte & 127) * factor;
+      if (!Number.isSafeInteger(value)) throw new InvalidDiffFrameError("Integer overflow");
+      if (byte < 128) return value;
+      factor *= 128;
+    }
+    throw new InvalidDiffFrameError("Invalid varint");
+  }
+  count(): number {
+    const value = this.uint();
+    if (value > this.bytes.length - this.offset)
+      throw new InvalidDiffFrameError("Count exceeds frame");
+    return value;
+  }
+  str(): string {
+    const size = this.count();
+    const start = this.offset;
+    this.offset += size;
+    try {
+      return textDecoder.decode(this.bytes.subarray(start, this.offset));
+    } catch {
+      throw new InvalidDiffFrameError("Invalid UTF-8");
+    }
+  }
+  done(): void {
+    if (this.offset !== this.bytes.length) throw new InvalidDiffFrameError("Trailing bytes");
+  }
+}
+function enumAt<T>(values: readonly T[], index: number): T {
+  if (index >= values.length) throw new InvalidDiffFrameError("Unknown enum value");
+  return values[index];
+}
+function validateRuns(line: DiffStreamLine): void {
+  if (!line.runs) return;
+  let length = 0;
+  for (const run of line.runs) {
+    if (!Number.isSafeInteger(run.length) || run.length <= 0)
+      throw new InvalidDiffFrameError("Invalid run length");
+    length += run.length;
+  }
+  if (length !== line.content.length) throw new InvalidDiffFrameError("Runs do not cover line");
+}
+function writeLine(writer: Writer, line: DiffStreamLine): void {
+  validateRuns(line);
+  writer.byte(KINDS.indexOf(line.type) | (line.runs ? 128 : 0));
+  writer.str(line.content);
+  writer.uint(line.runs ? line.runs.length : 0);
+  for (const run of line.runs ?? []) {
+    const style = DIFF_HIGHLIGHT_STYLES.findIndex((value) => value === run.style);
+    writer.byte(Math.max(0, style));
+    writer.uint(run.length);
+  }
+}
+function readLine(reader: Reader): DiffStreamLine {
+  const flags = reader.byte();
+  const type = enumAt(KINDS, flags & 127);
+  const content = reader.str();
+  const count = reader.count();
+  const runs: DiffRun[] = [];
+  for (let index = 0; index < count; index++) {
+    const styleIndex = reader.byte();
+    const style = DIFF_HIGHLIGHT_STYLES[styleIndex] ?? null;
+    runs.push({ style, length: reader.uint() });
+  }
+  if (!(flags & 128)) {
+    if (count) throw new InvalidDiffFrameError("Runs without flag");
+    return { type, content };
+  }
+  const line = { type, content, runs };
+  validateRuns(line);
+  return line;
+}
+export function encodeDiffFrame(frame: DiffFrame): Uint8Array {
+  const writer = new Writer();
+  writer.byte(frame.opcode);
+  writer.byte(frame.slot);
+  writer.byte(1);
+  writer.uint(frame.revision);
+  if (frame.opcode === DiffOpcode.Begin) {
+    writer.uint(frame.baseRevision);
+    writer.str(frame.baseSha);
+    writer.str(frame.headSha);
+    writer.str(frame.mergeBaseSha);
+    writer.uint(frame.entries.length);
+    for (const entry of frame.entries) {
+      if (entry.content === "binary" && entry.body)
+        throw new InvalidDiffFrameError("Binary entry has a body");
+      writer.str(entry.path);
+      writer.str(entry.oldPath ?? "");
+      writer.byte(CHANGES.indexOf(entry.change));
+      writer.byte(CONTENTS.indexOf(entry.content));
+      writer.uint(entry.additions);
+      writer.uint(entry.deletions);
+      writer.byte(Number(entry.body));
+    }
+  } else if (frame.opcode === DiffOpcode.Bodies) {
+    writer.uint(frame.files.length);
+    for (const file of frame.files) {
+      writer.str(file.path);
+      writer.uint(file.hunks.length);
+      for (const hunk of file.hunks) {
+        writer.uint(hunk.oldStart);
+        writer.uint(hunk.oldCount);
+        writer.uint(hunk.newStart);
+        writer.uint(hunk.newCount);
+        writer.uint(hunk.lines.length);
+        for (const line of hunk.lines) writeLine(writer, line);
+      }
+    }
+  } else {
+    writer.byte(Number(frame.diffTooLarge));
+    writer.uint(frame.omitted.length);
+    for (const path of frame.omitted) writer.str(path);
+    writer.byte(frame.error ? ERRORS.indexOf(frame.error.code) : 0);
+    writer.str(frame.error ? frame.error.message : "");
+  }
+  return writer.finish();
+}
+export function decodeDiffFrame(bytes: Uint8Array): DiffFrame {
+  const reader = new Reader(bytes);
+  const opcode = reader.byte();
+  const slot = reader.byte();
+  if (reader.byte() !== 1) throw new InvalidDiffFrameError("Unknown diff version");
+  const revision = reader.uint();
+  let frame: DiffFrame;
+  if (opcode === DiffOpcode.Begin) {
+    const baseRevision = reader.uint();
+    const baseSha = reader.str();
+    const headSha = reader.str();
+    const mergeBaseSha = reader.str();
+    const count = reader.count();
+    const entries: DiffEntry[] = [];
+    for (let index = 0; index < count; index++) {
+      const path = reader.str();
+      const oldPath = reader.str() || null;
+      const change = enumAt(CHANGES, reader.byte());
+      const content = enumAt(CONTENTS, reader.byte());
+      const additions = reader.uint();
+      const deletions = reader.uint();
+      const bodyByte = reader.byte();
+      if (bodyByte > 1 || (content === "binary" && bodyByte))
+        throw new InvalidDiffFrameError("Invalid entry body");
+      entries.push({ path, oldPath, change, content, additions, deletions, body: bodyByte === 1 });
+    }
+    frame = { opcode, slot, revision, baseRevision, baseSha, headSha, mergeBaseSha, entries };
+  } else if (opcode === DiffOpcode.Bodies) {
+    const count = reader.count();
+    const files: DiffBody[] = [];
+    for (let index = 0; index < count; index++) {
+      const path = reader.str();
+      const hunkCount = reader.count();
+      const hunks: DiffStreamHunk[] = [];
+      for (let h = 0; h < hunkCount; h++) {
+        const oldStart = reader.uint();
+        const oldCount = reader.uint();
+        const newStart = reader.uint();
+        const newCount = reader.uint();
+        const lineCount = reader.count();
+        const lines: DiffStreamLine[] = [];
+        for (let l = 0; l < lineCount; l++) lines.push(readLine(reader));
+        hunks.push({ oldStart, oldCount, newStart, newCount, lines });
+      }
+      files.push({ path, hunks });
+    }
+    frame = { opcode, slot, revision, files };
+  } else if (opcode === DiffOpcode.End) {
+    const flags = reader.byte();
+    if (flags > 1) throw new InvalidDiffFrameError("Unknown flags");
+    const count = reader.count();
+    const omitted: string[] = [];
+    for (let index = 0; index < count; index++) omitted.push(reader.str());
+    const code = enumAt(ERRORS, reader.byte());
+    const message = reader.str();
+    frame = {
+      opcode,
+      slot,
+      revision,
+      diffTooLarge: flags === 1,
+      omitted,
+      error: code ? { code, message } : null,
+    };
+  } else {
+    throw new InvalidDiffFrameError("Unknown diff opcode");
+  }
+  reader.done();
+  return frame;
+}
+export function runsToTokens(
+  line: DiffStreamLine,
+): NonNullable<ParsedDiffFile["hunks"][number]["lines"][number]["tokens"]> {
+  let offset = 0;
+  return (line.runs ?? []).map((run) => {
+    const text = line.content.slice(offset, offset + run.length);
+    offset += run.length;
+    return { text, style: run.style };
+  });
+}
+export function materializeDiffFile(
+  entry: DiffEntry,
+  body: DiffBody | null,
+  omitted: boolean,
+): ParsedDiffFile {
+  let status: "ok" | "binary" | "too_large" = "ok";
+  if (entry.content === "binary") status = "binary";
+  else if (omitted) status = "too_large";
+  const hunks = body
+    ? body.hunks.map((hunk) => ({
+        ...hunk,
+        lines: hunk.lines.map((line) => {
+          if (line.runs)
+            return { type: line.type, content: line.content, tokens: runsToTokens(line) };
+          return { type: line.type, content: line.content };
+        }),
+      }))
+    : [];
+  const file: ParsedDiffFile = {
+    path: entry.path,
+    isNew: entry.change === "added",
+    isDeleted: entry.change === "deleted",
+    additions: entry.additions,
+    deletions: entry.deletions,
+    hunks,
+    status,
+  };
+  if (entry.oldPath !== null) file.oldPath = entry.oldPath;
+  return file;
+}
diff --git a/packages/protocol/src/binary-frames/index.ts b/packages/protocol/src/binary-frames/index.ts
index cb24172960..946a1c7051 100644
--- a/packages/protocol/src/binary-frames/index.ts
+++ b/packages/protocol/src/binary-frames/index.ts
@@ -2,3 +2,5 @@ export * from "./demux.js";
 export * from "./file-transfer.js";
 export * from "./terminal.js";
 export * from "./host-route.js";
+export * from "./plugin.js";
+export * from "./diff.js";
diff --git a/packages/protocol/src/binary-frames/plugin.test.ts b/packages/protocol/src/binary-frames/plugin.test.ts
new file mode 100644
index 0000000000..644e6235ef
--- /dev/null
+++ b/packages/protocol/src/binary-frames/plugin.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertPluginWireValue,
+  decodeBinaryFrame,
+  decodePluginFrame,
+  encodePluginEventFrame,
+  encodePluginInputFrame,
+  encodePluginOutputFrame,
+  FileTransferOpcode,
+  MAX_PLUGIN_PAYLOAD_BYTES,
+  MAX_ROUTED_PAYLOAD_BYTES,
+  PluginFrameOpcode,
+  TerminalStreamOpcode,
+} from "./index.js";
+
+describe("plugin binary frames", () => {
+  it("uses the reserved plugin opcode range", () => {
+    for (const opcode of Object.values(PluginFrameOpcode)) {
+      expect(opcode).toBeGreaterThanOrEqual(0x20);
+      expect(opcode).toBeLessThanOrEqual(0x2f);
+      expect(Object.values(TerminalStreamOpcode)).not.toContain(opcode);
+      expect(Object.values(FileTransferOpcode)).not.toContain(opcode);
+    }
+  });
+
+  it("frames a subscription event as opcode, id length, id, and the untouched payload", () => {
+    const payload = new Uint8Array([9, 8, 7]);
+    const frame = encodePluginEventFrame("sub-1", payload);
+    expect([...frame]).toEqual([0x20, 5, ...new TextEncoder().encode("sub-1"), 9, 8, 7]);
+    expect(decodeBinaryFrame(frame)).toEqual({
+      kind: "plugin",
+      frame: { opcode: PluginFrameOpcode.Event, subscriptionId: "sub-1", payload },
+    });
+  });
+
+  it("decodes payloads as views into the received buffer", () => {
+    const frame = encodePluginOutputFrame("req-1", new Uint8Array([1, 2, 3, 4]));
+    const decoded = decodePluginFrame(frame);
+    if (decoded?.opcode !== PluginFrameOpcode.Output) throw new Error("Expected an output frame");
+    expect(decoded.requestId).toBe("req-1");
+    expect(decoded.payload.buffer).toBe(frame.buffer);
+    expect([...decoded.payload]).toEqual([1, 2, 3, 4]);
+  });
+
+  it("frames an RPC input with the plugin and method in its header", () => {
+    const frame = encodePluginInputFrame({
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+    expect(decodePluginFrame(frame)).toEqual({
+      opcode: PluginFrameOpcode.Input,
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+  });
+
+  it("rejects truncated frames", () => {
+    expect(decodePluginFrame(new Uint8Array([0x20]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x20, 9, 1]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x22, 1, 65, 0, 40]))).toBeNull();
+  });
+});
+
+describe("the plugin byte rule", () => {
+  it("accepts JSON values and a top-level Uint8Array", () => {
+    expect(() => assertPluginWireValue({ a: [1, "b", null] }, "event")).not.toThrow();
+    expect(() => assertPluginWireValue(new Uint8Array(4), "event")).not.toThrow();
+  });
+
+  it("rejects bytes that would not fit in one frame with the largest header", () => {
+    const bytes = new Uint8Array(MAX_PLUGIN_PAYLOAD_BYTES + 1);
+    expect(() => assertPluginWireValue(bytes.subarray(1), "event")).not.toThrow();
+    expect(() => assertPluginWireValue(bytes, "event")).toThrow(
+      `event is ${MAX_PLUGIN_PAYLOAD_BYTES + 1} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+    );
+    const frame = encodePluginInputFrame({
+      requestId: "r".repeat(255),
+      pluginId: "p",
+      method: "m".repeat(0xffff - 30),
+      payload: bytes.subarray(1),
+    });
+    expect(frame.byteLength).toBeLessThanOrEqual(MAX_ROUTED_PAYLOAD_BYTES);
+  });
+
+  it("rejects bytes nested in a value and names the rule and the path", () => {
+    expect(() => assertPluginWireValue({ frames: [{ data: new Uint8Array(1) }] }, "event")).toThrow(
+      "event.frames[0].data is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.",
+    );
+  });
+});
diff --git a/packages/protocol/src/binary-frames/plugin.ts b/packages/protocol/src/binary-frames/plugin.ts
new file mode 100644
index 0000000000..a2db0addf9
--- /dev/null
+++ b/packages/protocol/src/binary-frames/plugin.ts
@@ -0,0 +1,152 @@
+import { MAX_ROUTED_PAYLOAD_BYTES } from "./host-route.js";
+
+/**
+ * Plugin values that are a `Uint8Array` travel as binary frames. Opcodes 0x20-0x2f are
+ * reserved for plugin traffic. Every frame is `[opcode][id length u8][id]...` and the payload
+ * is the rest of the frame, decoded as a view so no hop copies it.
+ */
+export const PluginFrameOpcode = {
+  /** `[0x20][id length][subscriptionId][payload]`: a subscription event. */
+  Event: 0x20,
+  /** `[0x21][id length][requestId][payload]`: an RPC output; no JSON response follows. */
+  Output: 0x21,
+  /** `[0x22][id length][requestId][header length u16][header JSON][payload]`: an RPC input. */
+  Input: 0x22,
+} as const;
+
+export type PluginFrameOpcode = (typeof PluginFrameOpcode)[keyof typeof PluginFrameOpcode];
+
+/** The largest frame header: an input's opcode, ID and header JSON, each at its maximum length. */
+const MAX_PLUGIN_FRAME_HEADER_BYTES = 2 + 0xff + 2 + 0xffff;
+
+/** The largest `Uint8Array` a plugin value carries, so its frame fits in one routed message. */
+export const MAX_PLUGIN_PAYLOAD_BYTES = MAX_ROUTED_PAYLOAD_BYTES - MAX_PLUGIN_FRAME_HEADER_BYTES;
+
+export type PluginFrame =
+  | { opcode: typeof PluginFrameOpcode.Event; subscriptionId: string; payload: Uint8Array }
+  | { opcode: typeof PluginFrameOpcode.Output; requestId: string; payload: Uint8Array }
+  | {
+      opcode: typeof PluginFrameOpcode.Input;
+      requestId: string;
+      pluginId: string;
+      method: string;
+      payload: Uint8Array;
+    };
+
+export function isPluginFrameOpcode(value: number | undefined): value is PluginFrameOpcode {
+  return (
+    value === PluginFrameOpcode.Event ||
+    value === PluginFrameOpcode.Output ||
+    value === PluginFrameOpcode.Input
+  );
+}
+
+export function encodePluginEventFrame(subscriptionId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Event, subscriptionId, new Uint8Array(0), payload);
+}
+
+export function encodePluginOutputFrame(requestId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Output, requestId, new Uint8Array(0), payload);
+}
+
+export function encodePluginInputFrame(input: {
+  requestId: string;
+  pluginId: string;
+  method: string;
+  payload: Uint8Array;
+}): Uint8Array {
+  const header = new TextEncoder().encode(
+    JSON.stringify({ pluginId: input.pluginId, method: input.method }),
+  );
+  if (header.byteLength > 0xffff) throw new RangeError("Plugin input header is too long");
+  const prefix = new Uint8Array(2 + header.byteLength);
+  new DataView(prefix.buffer).setUint16(0, header.byteLength);
+  prefix.set(header, 2);
+  return encodeFrame(PluginFrameOpcode.Input, input.requestId, prefix, input.payload);
+}
+
+export function decodePluginFrame(bytes: Uint8Array): PluginFrame | null {
+  const opcode = bytes[0];
+  if (bytes.byteLength < 2 || !isPluginFrameOpcode(opcode)) return null;
+  const idLength = bytes[1];
+  if (idLength === 0 || idLength > bytes.byteLength - 2) return null;
+  const id = new TextDecoder().decode(bytes.subarray(2, 2 + idLength));
+  const body = bytes.subarray(2 + idLength);
+  if (opcode === PluginFrameOpcode.Event) return { opcode, subscriptionId: id, payload: body };
+  if (opcode === PluginFrameOpcode.Output) return { opcode, requestId: id, payload: body };
+  if (body.byteLength < 2) return null;
+  const headerLength = new DataView(body.buffer, body.byteOffset, body.byteLength).getUint16(0);
+  if (headerLength > body.byteLength - 2) return null;
+  const header = decodeInputHeader(body.subarray(2, 2 + headerLength));
+  if (!header) return null;
+  return { opcode, requestId: id, ...header, payload: body.subarray(2 + headerLength) };
+}
+
+function encodeFrame(
+  opcode: PluginFrameOpcode,
+  id: string,
+  prefix: Uint8Array,
+  payload: Uint8Array,
+): Uint8Array {
+  const idBytes = new TextEncoder().encode(id);
+  if (idBytes.byteLength === 0) throw new RangeError("Plugin frame ID is required");
+  if (idBytes.byteLength > 0xff) throw new RangeError("Plugin frame ID is too long");
+  const headerLength = 2 + idBytes.byteLength + prefix.byteLength;
+  const frame = new Uint8Array(headerLength + payload.byteLength);
+  frame[0] = opcode;
+  frame[1] = idBytes.byteLength;
+  frame.set(idBytes, 2);
+  frame.set(prefix, 2 + idBytes.byteLength);
+  frame.set(payload, headerLength);
+  return frame;
+}
+
+function decodeInputHeader(bytes: Uint8Array): { pluginId: string; method: string } | null {
+  try {
+    const header: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    if (typeof header !== "object" || header === null) return null;
+    const pluginId = Reflect.get(header, "pluginId");
+    const method = Reflect.get(header, "method");
+    if (typeof pluginId !== "string" || typeof method !== "string" || !pluginId || !method)
+      return null;
+    return { pluginId, method };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The byte rule: a plugin value is either a `Uint8Array`, sent as a binary frame, or a JSON value
+ * with no `Uint8Array` inside it. Checks object structure only; never reads the bytes.
+ */
+export function assertPluginWireValue(value: unknown, label: string): void {
+  if (value instanceof Uint8Array) {
+    if (value.byteLength > MAX_PLUGIN_PAYLOAD_BYTES)
+      throw new RangeError(
+        `${label} is ${value.byteLength} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+      );
+    return;
+  }
+  const nested = findNestedBytes(value, label);
+  if (nested)
+    throw new TypeError(
+      `${nested} is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.`,
+    );
+}
+
+function findNestedBytes(value: unknown, path: string): string | null {
+  if (value instanceof Uint8Array) return path;
+  if (typeof value !== "object" || value === null) return null;
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const found = findNestedBytes(value[index], `${path}[${index}]`);
+      if (found) return found;
+    }
+    return null;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const found = findNestedBytes(entry, `${path}.${key}`);
+    if (found) return found;
+  }
+  return null;
+}
diff --git a/packages/protocol/src/chunked-transport.test.ts b/packages/protocol/src/chunked-transport.test.ts
index 3979b48885..caca79c0dc 100644
--- a/packages/protocol/src/chunked-transport.test.ts
+++ b/packages/protocol/src/chunked-transport.test.ts
@@ -390,3 +390,65 @@ it("unpaced transports retain ordinary outbound admission and accept inbound chu
   expect(delivered).toEqual(["A"]);
   await transport.send("small");
 });
+
+it("fills an ordered writer's window while keeping chunk sequences contiguous", async () => {
+  const delivered: (string | Uint8Array)[] = [];
+  const receiver = new ChunkedTransport({
+    frameBytes: 8,
+    send() {},
+    deliver: (frame) => {
+      delivered.push(frame);
+    },
+  });
+  receiver.enabled = true;
+  const drain = Promise.withResolvers<void>();
+  const frames: (string | Uint8Array)[] = [];
+  const sender = new ChunkedTransport({
+    frameBytes: 8,
+    supportsConcurrentWrites: true,
+    send: (frame) => {
+      frames.push(frame);
+      receiver.receive(frame);
+      return drain.promise;
+    },
+    deliver() {},
+  });
+  sender.enabled = true;
+  const first = sender.send("one");
+  const second = sender.send("two");
+  expect(delivered).toEqual(["one", "two"]);
+  expect(sender.queuedByteLength).toBe(0);
+  const large = sender.send("large message");
+  const after = sender.send("after");
+  expect(frames).toHaveLength(3);
+  expect(sender.queuedByteLength).toBe(5);
+  drain.resolve();
+  await Promise.all([first, second, large, after]);
+  expect(delivered).toEqual(["one", "two", "large message", "after"]);
+  expect(sender.queuedByteLength).toBe(0);
+});
+
+it("accounts for independently draining writes and a rejected admission", async () => {
+  const firstDrain = Promise.withResolvers<void>();
+  const secondDrain = Promise.withResolvers<void>();
+  const sender = new ChunkedTransport({
+    frameBytes: 8,
+    supportsConcurrentWrites: true,
+    send: (frame) => {
+      if (frame === "reject") throw new Error("capacity");
+      return frame === "one" ? firstDrain.promise : secondDrain.promise;
+    },
+    deliver() {},
+  });
+  const first = sender.send("one");
+  const second = sender.send("two");
+  expect(() => sender.send("reject")).toThrow("capacity");
+  expect(sender.queuedByteLength).toBe(0);
+  secondDrain.resolve();
+  await second;
+  expect(sender.queuedByteLength).toBe(0);
+  firstDrain.resolve();
+  await first;
+  expect(sender.queuedByteLength).toBe(0);
+  await sender.send("usable");
+});
diff --git a/packages/protocol/src/chunked-transport.ts b/packages/protocol/src/chunked-transport.ts
index a32d68424f..51d8b888a8 100644
--- a/packages/protocol/src/chunked-transport.ts
+++ b/packages/protocol/src/chunked-transport.ts
@@ -23,8 +23,11 @@ export class ChunkedTransport {
     private readonly io: {
       frameBytes: number;
       supportsDrain?: boolean;
+      /** Writes are admitted synchronously in order; promises track only their drain. */
+      supportsConcurrentWrites?: boolean;
       send: (frame: Frame, waitForDrain: boolean) => void | Promise<void>;
       deliver: (frame: Frame) => void;
+      onActivity?: () => void;
       onFailure?: (error: unknown) => void;
     },
   ) {
@@ -45,9 +48,11 @@ export class ChunkedTransport {
     const chunk =
       this.enabled && this.io.supportsDrain !== false && byteLength > this.io.frameBytes;
     if (this.closed) throw new Error("Transport closed");
+    let started = false;
     const write = () => {
       if (this.closed) throw new Error("Transport closed");
-      this.activeBytes = byteLength;
+      started = true;
+      this.activeBytes += byteLength;
       // A synchronous rejection did not admit a frame. Only accepted writes can
       // fail the connection; queued admission failures still belong to their sender.
       const result = chunk
@@ -75,27 +80,31 @@ export class ChunkedTransport {
       result = this.pending ? this.pending.then(write) : write();
     } catch (error) {
       this.queuedBytes -= byteLength;
-      this.activeBytes = 0;
+      if (started) this.activeBytes -= byteLength;
       throw error;
     }
     if (!result) {
       this.queuedBytes -= byteLength;
-      this.activeBytes = 0;
+      if (started) this.activeBytes -= byteLength;
       return Promise.resolve();
     }
     const completion = Promise.resolve(result).finally(() => {
       this.queuedBytes -= byteLength;
-      this.activeBytes = 0;
-    });
-    const tail = completion.then(
-      () => undefined,
-      () => undefined,
-    );
-    this.pending = tail;
-    void tail.then(() => {
-      if (this.pending === tail) this.pending = undefined;
-      return undefined;
+      if (started) this.activeBytes -= byteLength;
     });
+    // Ordinary writes already entered an ordered writer and can use its bounded
+    // window. Chunk sequences remain a barrier so their frames never interleave.
+    if (chunk || !this.io.supportsConcurrentWrites) {
+      const tail = completion.then(
+        () => undefined,
+        () => undefined,
+      );
+      this.pending = tail;
+      void tail.then(() => {
+        if (this.pending === tail) this.pending = undefined;
+        return undefined;
+      });
+    }
     return completion;
   }
 
@@ -134,6 +143,7 @@ export class ChunkedTransport {
         { cause: error },
       );
     }
+    this.io.onActivity?.();
     if (message !== undefined) this.io.deliver(message);
   }
 
diff --git a/packages/protocol/src/client-capabilities.ts b/packages/protocol/src/client-capabilities.ts
index 6f88b0fdbc..f1d07e4794 100644
--- a/packages/protocol/src/client-capabilities.ts
+++ b/packages/protocol/src/client-capabilities.ts
@@ -49,8 +49,15 @@ export const CLIENT_CAPS = {
   // COMPAT(pluginTimelineItems): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
   pluginTimelineItems: "plugin_timeline_items",
   workspaceSetupObservation: "workspace_setup_observation",
+  // COMPAT(pluginBinaryPayloads): added in v0.15.0, remove after 2027-05-02 once client floor >= v0.15.0.
+  // The daemon sends plugin RPC outputs as binary opcode 0x21 only to clients that decode it.
+  pluginBinaryPayloads: "plugin_binary_payloads",
   // COMPAT(workspaceSetupBlocked): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
   workspaceSetupBlocked: "workspace_setup_blocked",
+  // COMPAT(backgroundAgents): added in v0.15.0, remove after 2027-05-03 once client floor >= v0.15.0.
+  // Sources without it never receive agent-level background agents in inclusive lists or
+  // update subscriptions, because older apps auto-open a tab for every replicated root agent.
+  backgroundAgents: "background_agents",
   browserHost: "browser_host",
 } as const;
 
diff --git a/packages/protocol/src/hosts.ts b/packages/protocol/src/hosts.ts
index 7d36a50236..8311d4268c 100644
--- a/packages/protocol/src/hosts.ts
+++ b/packages/protocol/src/hosts.ts
@@ -116,8 +116,19 @@ export const HostsLinkOpenRequestSchema = z.object({
   type: z.literal("hosts.link.open.request"),
   requestId: z.string(),
   channelId: z.string().min(1).max(256),
+  flowControl: z.boolean().optional(),
 });
 export const HostsLinkOpenResponseSchema = z.object({
   type: z.literal("hosts.link.open.response"),
-  payload: z.object({ requestId: z.string(), routeId: z.string() }),
+  payload: z.object({
+    requestId: z.string(),
+    routeId: z.string(),
+    flowControl: z.boolean().optional(),
+  }),
+});
+
+export const HostsLinkAckSchema = z.object({
+  type: z.literal("hosts.link.ack.request"),
+  routeId: z.string(),
+  sequence: z.number().int().positive(),
 });
diff --git a/packages/protocol/src/messages.background-work.test.ts b/packages/protocol/src/messages.background-work.test.ts
new file mode 100644
index 0000000000..d8d8de8ad5
--- /dev/null
+++ b/packages/protocol/src/messages.background-work.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  ServerInfoStatusPayloadSchema,
+  SessionEventSubscriptionSchema,
+  SessionInboundMessageSchema,
+  SessionOutboundMessageSchema,
+} from "./messages.js";
+
+const ITEM = {
+  id: "bash-1",
+  kind: "shell",
+  description: "sleep 20",
+  startedAt: "2026-10-06T10:00:00.000Z",
+};
+
+describe("agent background work protocol", () => {
+  test("accepts a list request and its response", () => {
+    expect(
+      SessionInboundMessageSchema.parse({
+        type: "agent.background_work.list.request",
+        agentId: "agent-1",
+        requestId: "request-1",
+      }),
+    ).toMatchObject({ agentId: "agent-1", requestId: "request-1" });
+
+    expect(
+      SessionOutboundMessageSchema.parse({
+        type: "agent.background_work.list.response",
+        payload: { requestId: "request-1", agentId: "agent-1", items: [ITEM], error: null },
+      }),
+    ).toMatchObject({ payload: { items: [ITEM] } });
+  });
+
+  test("accepts an update with or without a subscription id", () => {
+    for (const payload of [
+      { agentId: "agent-1", items: [] },
+      { subscriptionId: "events-1", agentId: "agent-1", items: [ITEM] },
+    ]) {
+      expect(
+        SessionOutboundMessageSchema.parse({ type: "agent.background_work.update", payload }),
+      ).toMatchObject({ payload });
+    }
+  });
+
+  test("keeps kind an open string so new kinds parse on old clients", () => {
+    expect(
+      SessionOutboundMessageSchema.parse({
+        type: "agent.background_work.update",
+        payload: { agentId: "agent-1", items: [{ ...ITEM, kind: "future-kind" }] },
+      }),
+    ).toMatchObject({ payload: { items: [{ kind: "future-kind" }] } });
+  });
+
+  test("preserves an optional command while accepting older items", () => {
+    const withCommand = { ...ITEM, description: "Watch build", command: "tail -f build.log" };
+    const parsed = SessionOutboundMessageSchema.parse({
+      type: "agent.background_work.update",
+      payload: { agentId: "agent-1", items: [ITEM, withCommand] },
+    });
+    expect(parsed).toMatchObject({ payload: { items: [ITEM, withCommand] } });
+  });
+
+  test("is a subscribable event", () => {
+    expect(SessionEventSubscriptionSchema.parse("agent.background_work.update")).toBe(
+      "agent.background_work.update",
+    );
+  });
+
+  test("keeps the feature optional for older server info payloads", () => {
+    expect(
+      ServerInfoStatusPayloadSchema.parse({
+        status: "server_info",
+        serverId: "server-1",
+        features: {},
+      }).features?.agentBackgroundWork,
+    ).toBeUndefined();
+  });
+});
+
+test("stop requests carry an inventory token and preserve legacy item parsing", () => {
+  expect(
+    SessionInboundMessageSchema.parse({
+      type: "agent.background_work.stop.request",
+      agentId: "a",
+      itemId: "x",
+      stopToken: "token",
+      requestId: "r",
+    }),
+  ).toMatchObject({ stopToken: "token" });
+  expect(
+    SessionOutboundMessageSchema.parse({
+      type: "agent.background_work.stop.response",
+      payload: { requestId: "r", agentId: "a", itemId: "x", error: null },
+    }),
+  ).toMatchObject({ payload: { error: null } });
+  expect(
+    SessionOutboundMessageSchema.parse({
+      type: "agent.background_work.update",
+      payload: { agentId: "a", items: [ITEM] },
+    }),
+  ).toMatchObject({ payload: { items: [ITEM] } });
+});
diff --git a/packages/protocol/src/messages.checkout-pr-schema.test.ts b/packages/protocol/src/messages.checkout-pr-schema.test.ts
index 3966d6eb71..db412a831a 100644
--- a/packages/protocol/src/messages.checkout-pr-schema.test.ts
+++ b/packages/protocol/src/messages.checkout-pr-schema.test.ts
@@ -813,13 +813,14 @@ describe("checkout PR schemas", () => {
   });
 });
 
-test.each([undefined, false, true])(
-  "accepts optional Hoplite capability (%s)",
-  (hopliteProvider) => {
-    const features = hopliteProvider === undefined ? {} : { hopliteProvider };
-    expect(
-      ServerInfoStatusPayloadSchema.parse({ status: "server_info", serverId: "test", features })
-        .features,
-    ).toEqual(features);
-  },
-);
+test.each(
+  ["hopliteProvider", "fxProvider"].flatMap((name) =>
+    [undefined, false, true].map((value) => [name, value] as const),
+  ),
+)("accepts optional bundled provider capability (%s: %s)", (name, value) => {
+  const features = value === undefined ? {} : { [name]: value };
+  expect(
+    ServerInfoStatusPayloadSchema.parse({ status: "server_info", serverId: "test", features })
+      .features,
+  ).toEqual(features);
+});
diff --git a/packages/protocol/src/messages.diff.test.ts b/packages/protocol/src/messages.diff.test.ts
new file mode 100644
index 0000000000..f2831ab147
--- /dev/null
+++ b/packages/protocol/src/messages.diff.test.ts
@@ -0,0 +1,24 @@
+import { expect, test } from "vitest";
+import { DiffSubscribeRequestSchema, DiffSubscribeResponseSchema } from "./messages.js";
+
+test("accepts explicit endpoints without changing legacy schemas", () => {
+  const request = {
+    type: "diff.subscribe.request",
+    requestId: "r",
+    cwd: "/repo",
+    base: { kind: "rev", rev: "v1" },
+    head: { kind: "worktree" },
+    mergeBase: true,
+    highlight: false,
+  };
+  expect(DiffSubscribeRequestSchema.parse(request)).toEqual(request);
+  expect(
+    DiffSubscribeRequestSchema.safeParse({ ...request, base: { kind: "unknown" } }).success,
+  ).toBe(false);
+  expect(
+    DiffSubscribeResponseSchema.safeParse({
+      type: "diff.subscribe.response",
+      payload: { requestId: "r", subscriptionId: "s", slot: 256, error: null },
+    }).success,
+  ).toBe(false);
+});
diff --git a/packages/protocol/src/messages.plugins.test.ts b/packages/protocol/src/messages.plugins.test.ts
index 47e91493fe..dce5a11bca 100644
--- a/packages/protocol/src/messages.plugins.test.ts
+++ b/packages/protocol/src/messages.plugins.test.ts
@@ -372,3 +372,43 @@ it("npm metadata leaves legacy plugin rows parseable without extending their clo
     payload: { requestId: "npm", plugins: [plugin] },
   });
 });
+
+describe("plugin subscription protocol", () => {
+  it("parses a subscribe request and its response", () => {
+    const request = {
+      type: "plugin.rpc.subscribe.request",
+      requestId: "r1",
+      pluginId: "diff-watch",
+      method: "diff.watch",
+      input: { a: "main", b: "HEAD" },
+    };
+    expect(SessionInboundMessageSchema.parse(request)).toEqual(request);
+    const response = {
+      type: "plugin.rpc.subscribe.response",
+      payload: { requestId: "r1", subscriptionId: "s1" },
+    };
+    expect(SessionOutboundMessageSchema.parse(response)).toEqual(response);
+  });
+
+  it("parses JSON events and closes with and without an error", () => {
+    for (const message of [
+      { type: "plugin.rpc.event", payload: { subscriptionId: "s1", event: { path: "a.ts" } } },
+      { type: "plugin.rpc.closed", payload: { subscriptionId: "s1" } },
+      { type: "plugin.rpc.closed", payload: { subscriptionId: "s1", error: "boom" } },
+    ]) {
+      expect(SessionOutboundMessageSchema.parse(message)).toEqual(message);
+    }
+  });
+
+  it("advertises the feature as an optional flag", () => {
+    const status = {
+      type: "status",
+      payload: {
+        status: "server_info",
+        serverId: "srv",
+        features: { pluginSubscriptions: true },
+      },
+    };
+    expect(StatusMessageSchema.parse(status)).toMatchObject(status);
+  });
+});
diff --git a/packages/protocol/src/messages.test.ts b/packages/protocol/src/messages.test.ts
index 373cef409b..453c7aa1c1 100644
--- a/packages/protocol/src/messages.test.ts
+++ b/packages/protocol/src/messages.test.ts
@@ -492,6 +492,26 @@ describe("daemon update messages", () => {
 });
 
 describe("viewed timeline subscription messages", () => {
+  test("carries a cursor per chat and a freshness answer per chat", () => {
+    const cursors = { "agent-a": { epoch: "epoch-1", seq: 42 } };
+    const timelines = { "agent-a": "current", "agent-b": "behind" };
+
+    expect(
+      SessionInboundMessageSchema.parse({
+        type: "agent.timeline.set_subscription.request",
+        agentIds: ["agent-a"],
+        requestId: "timeline-subscription-2",
+        cursors,
+      }),
+    ).toMatchObject({ cursors });
+    expect(
+      SessionOutboundMessageSchema.parse({
+        type: "agent.timeline.set_subscription.response",
+        payload: { agentIds: ["agent-a"], requestId: "timeline-subscription-2", timelines },
+      }),
+    ).toMatchObject({ payload: { timelines } });
+  });
+
   test("parses a complete viewed-agent set and its acknowledgement", () => {
     const request = SessionInboundMessageSchema.parse({
       type: "agent.timeline.set_subscription.request",
@@ -571,3 +591,43 @@ test.each(["all", "base", "uncommitted"] as const)(
     expect(parsed.attachments).toEqual([attachment]);
   },
 );
+
+describe("terminal collection protocol compatibility", () => {
+  test("accepts released directory observations and their snapshots", () => {
+    expect(
+      SessionInboundMessageSchema.parse({
+        type: "subscribe_terminals_request",
+        cwd: "/repo",
+        requestId: "old",
+      }),
+    ).toMatchObject({ cwd: "/repo" });
+    expect(
+      SessionOutboundMessageSchema.parse({
+        type: "terminals_changed",
+        payload: { cwd: "/repo", terminals: [{ id: "terminal", name: "Shell" }] },
+      }),
+    ).toMatchObject({ payload: { cwd: "/repo" } });
+  });
+  test("accepts capability-gated host observations and additive metadata", () => {
+    expect(
+      SessionInboundMessageSchema.parse({ type: "subscribe_terminals_request", requestId: "host" }),
+    ).toMatchObject({ requestId: "host" });
+    expect(
+      SessionOutboundMessageSchema.parse({
+        type: "terminals_changed",
+        payload: {
+          terminals: [
+            {
+              id: "terminal",
+              name: "Shell",
+              cwd: "/repo",
+              workspaceId: "workspace",
+              createdAt: null,
+              isScript: true,
+            },
+          ],
+        },
+      }),
+    ).toMatchObject({ payload: { terminals: [{ isScript: true, createdAt: null }] } });
+  });
+});
diff --git a/packages/protocol/src/messages.ts b/packages/protocol/src/messages.ts
index a9d1e236b6..2a7617580b 100644
--- a/packages/protocol/src/messages.ts
+++ b/packages/protocol/src/messages.ts
@@ -5,6 +5,7 @@ import {
   HostsUpdateRequestSchema,
   HostsRemoveRequestSchema,
   HostsLinkOpenRequestSchema,
+  HostsLinkAckSchema,
   HostsRouteOpenRequestSchema,
   HostsRouteFrameRequestSchema,
   HostsRouteCloseRequestSchema,
@@ -303,6 +304,9 @@ import type {
 // unknown avoids zod-aot's recursive z.json() object-codegen regression.
 const JsonWireValueSchema = z.unknown() as z.ZodType<JsonValue>;
 
+/** Plugin-owned data on an agent or workspace. Paseo stores it and never reads a key. */
+const EntityMetadataSchema = z.record(z.string(), JsonWireValueSchema);
+
 export const AgentStatusSchema = z.enum(AGENT_LIFECYCLE_STATUSES);
 
 const AgentModeSchema: z.ZodType<AgentMode> = z.object({
@@ -361,6 +365,39 @@ export const AgentFeatureSchema = z.discriminatedUnion("type", [
   AgentFeatureSelectSchema,
 ]);
 
+export const AgentOptionChoiceSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+export const AgentOptionToggleControlSchema = z.object({
+  type: z.literal("toggle"),
+  key: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  tooltip: z.string().optional(),
+  icon: z.string().optional(),
+  defaultValue: z.boolean().optional(),
+});
+
+export const AgentOptionSelectControlSchema = z.object({
+  type: z.literal("select"),
+  key: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  tooltip: z.string().optional(),
+  icon: z.string().optional(),
+  desktopTrigger: z.enum(["icon", "label"]).optional(),
+  defaultValue: z.string().optional(),
+  choices: z.array(AgentOptionChoiceSchema),
+});
+
+export const AgentOptionControlSchema = z.discriminatedUnion("type", [
+  AgentOptionToggleControlSchema,
+  AgentOptionSelectControlSchema,
+]);
+
 const AgentModelDefinitionSchema = z.object({
   provider: AgentProviderSchema,
   id: z.string(),
@@ -490,6 +527,7 @@ const AgentSessionConfigSchema = z.object({
   modeId: z.string().optional(),
   model: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
   title: z.string().trim().min(1).max(MAX_EXPLICIT_AGENT_TITLE_CHARS).optional().nullable(),
   providerOptions: ProviderOptionsSchema.optional(),
@@ -866,13 +904,18 @@ export const AgentSnapshotPayloadSchema = z.object({
   cwd: z.string(),
   workspaceId: z.string().optional(),
   model: z.string().nullable(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Built from controls + options.
   features: z.array(AgentFeatureSchema).optional(),
+  /** Effective provider options: `config.json` defaults deep-merged with the agent's own. */
+  options: ProviderOptionsSchema.optional(),
+  controls: z.array(AgentOptionControlSchema).optional(),
   thinkingOptionId: z.string().nullable().optional(),
   effectiveThinkingOptionId: z.string().nullable().optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
   lastUserMessageAt: z.string().nullable(),
   status: AgentStatusSchema,
+  backgroundWork: z.object({ count: z.number().int().nonnegative() }).optional(),
   activeTurn: AgentActiveTurnPayloadSchema.nullable().optional(),
   capabilities: AgentCapabilityFlagsSchema,
   currentModeId: z.string().nullable(),
@@ -880,10 +923,13 @@ export const AgentSnapshotPayloadSchema = z.object({
   pendingPermissions: z.array(AgentPermissionRequestPayloadSchema),
   persistence: AgentPersistenceHandleSchema.nullable(),
   runtimeInfo: AgentRuntimeInfoSchema.optional(),
+  /** Opaque. Changes whenever the accounts this agent reports usage for can change. */
+  usageScopeKey: z.string().optional(),
   lastUsage: AgentUsageSchema.optional(),
   lastError: z.string().optional(),
   title: z.string().nullable(),
   labels: z.record(z.string(), z.string()).default({}),
+  metadata: EntityMetadataSchema.optional(),
   requiresAttention: z.boolean().optional(),
   attentionReason: z.enum(["finished", "error", "permission"]).nullable().optional(),
   attentionTimestamp: z.string().nullable().optional(),
@@ -891,6 +937,9 @@ export const AgentSnapshotPayloadSchema = z.object({
   providerUnavailable: z.boolean().optional(),
   // Private helper marker, retained for exact-ID snapshots and older wire messages.
   internal: z.boolean().optional(),
+  // Background agent: hidden from default discovery, tabs, tracks and notifications.
+  // Fixed at creation. Effective background also includes the workspace's flag.
+  background: z.boolean().optional(),
 });
 
 export type AgentSnapshotPayload = z.infer<typeof AgentSnapshotPayloadSchema>;
@@ -904,6 +953,7 @@ export const AgentListItemPayloadSchema = z.object({
   thinkingOptionId: z.string().nullable().optional(),
   effectiveThinkingOptionId: z.string().nullable().optional(),
   status: AgentStatusSchema,
+  backgroundWork: z.object({ count: z.number().int().nonnegative() }).optional(),
   cwd: z.string(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -1030,6 +1080,22 @@ export const WorkspaceTitleSetRequestSchema = z.object({
   requestId: z.string(),
 });
 
+export const AgentMetadataUpdateRequestSchema = z.object({
+  type: z.literal("agent.metadata.update.request"),
+  agentId: z.string(),
+  // Top-level keys replace; null removes the key.
+  patch: EntityMetadataSchema,
+  requestId: z.string(),
+});
+
+export const WorkspaceMetadataUpdateRequestSchema = z.object({
+  type: z.literal("workspace.metadata.update.request"),
+  workspaceId: z.string(),
+  // Top-level keys replace; null removes the key.
+  patch: EntityMetadataSchema,
+  requestId: z.string(),
+});
+
 export const WorkspacePinSetRequestSchema = z.object({
   type: z.literal("workspace.pin.set.request"),
   workspaceId: z.string(),
@@ -1037,6 +1103,13 @@ export const WorkspacePinSetRequestSchema = z.object({
   requestId: z.string(),
 });
 
+export const WorkspaceBaseBranchSetRequestSchema = z.object({
+  type: z.literal("workspace.base_branch.set.request"),
+  workspaceId: z.string(),
+  baseRef: z.string(),
+  requestId: z.string(),
+});
+
 export const WorkspaceLabelColorSchema = z.enum(WORKSPACE_LABEL_COLORS);
 export const WorkspaceLabelDefinitionSchema = z.object({
   name: z.string(),
@@ -1095,6 +1168,14 @@ export const WorkspaceRecoveryRestoreRequestSchema = z.object({
   requestId: z.string(),
 });
 
+// Undoes the latest archive of a workspace: cancels it if it is still running, otherwise
+// restores the workspace, then unarchives the agents that archive took down.
+export const WorkspaceArchiveUndoRequestSchema = z.object({
+  type: z.literal("workspace.archive.undo.request"),
+  workspaceId: z.string(),
+  requestId: z.string(),
+});
+
 export const SetVoiceModeMessageSchema = z.object({
   type: z.literal("set_voice_mode"),
   enabled: z.boolean(),
@@ -1370,6 +1451,15 @@ export const ProjectListRequestMessageSchema = z.object({
   sync: DirectorySyncRequestSchema.optional(),
 });
 
+export const ProjectSuggestionsRequestSchema = z.object({
+  type: z.literal("project.suggestions.request"),
+  requestId: z.string(),
+  providers: z.array(z.string()).optional(),
+  // ISO timestamp. Sessions older than this are ignored. Defaults to 30 days ago.
+  since: z.string().optional(),
+  limit: z.number().int().positive().max(100).optional(),
+});
+
 export const FetchAgentHistoryRequestMessageSchema = z.object({
   type: z.literal("fetch_agent_history_request"),
   requestId: z.string(),
@@ -1603,6 +1693,14 @@ export const PluginRpcInvokeRequestSchema = z.object({
   requestId: z.string(),
   pluginId: PluginIdSchema,
   method: z.string().min(1),
+  input: z.unknown().optional(),
+});
+
+export const PluginRpcSubscribeRequestSchema = z.object({
+  type: z.literal("plugin.rpc.subscribe.request"),
+  requestId: z.string(),
+  pluginId: PluginIdSchema,
+  method: z.string().min(1),
   input: z.unknown(),
 });
 
@@ -1785,9 +1883,11 @@ export const CreateAgentRequestMessageSchema = z.object({
   // in the config schema, which is reused for updates. Retained for wire parsing;
   // public internal creation is no longer supported.
   internal: z.boolean().optional(),
-  // Workspace creation intent, rejected when selecting an existing workspace.
+  // The created agent is a background agent. A workspace this request creates inherits it.
+  // Omitted on agent-scoped creation, the caller agent's own value applies.
   background: z.boolean().optional(),
   labels: z.record(z.string(), z.string()).default({}),
+  metadata: EntityMetadataSchema.optional(),
   requestId: z.string(),
 });
 
@@ -1965,6 +2065,20 @@ export const ProviderSubagentListRequestMessageSchema = z.object({
   requestId: z.string(),
 });
 
+export const AgentBackgroundWorkListRequestMessageSchema = z.object({
+  type: z.literal("agent.background_work.list.request"),
+  agentId: z.string(),
+  requestId: z.string(),
+});
+
+export const AgentBackgroundWorkStopRequestMessageSchema = z.object({
+  type: z.literal("agent.background_work.stop.request"),
+  agentId: z.string(),
+  itemId: z.string(),
+  stopToken: z.string(),
+  requestId: z.string(),
+});
+
 export const ProviderSubagentTimelineRequestMessageSchema = z.object({
   type: z.literal("agent.provider_subagents.timeline.get.request"),
   parentAgentId: z.string(),
@@ -1975,10 +2089,16 @@ export const ProviderSubagentTimelineRequestMessageSchema = z.object({
   limit: z.number().int().nonnegative().optional(),
 });
 
+// "current" means the daemon has this agent loaded, the epoch matches, and the cursor is at the head.
+// Anything else is "behind", including an agent the daemon has not loaded.
+export const TimelineFreshnessSchema = z.enum(["current", "behind"]);
+
 export const SetAgentTimelineSubscriptionRequestMessageSchema = z.object({
   type: z.literal("agent.timeline.set_subscription.request"),
   agentIds: z.array(z.string()),
   requestId: z.string(),
+  // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+  cursors: z.record(z.string(), AgentTimelineCursorSchema).optional(),
 });
 
 export const AgentForkContextRequestMessageSchema = z.object({
@@ -2055,7 +2175,10 @@ export const AgentConfigApplySchema = z.object({
   modelId: z.string().nullable().optional(),
   modeId: z.string().optional(),
   thinkingOptionId: z.string().nullable().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Maps to an options patch.
   featureValues: z.record(z.string(), z.unknown()).optional(),
+  /** Patch of the agent's own options: replaces top-level keys; `null` removes the key. */
+  options: ProviderOptionsSchema.optional(),
 });
 
 export type AgentConfigApply = z.infer<typeof AgentConfigApplySchema>;
@@ -2163,6 +2286,28 @@ export const WorkspaceTitleSetResponseSchema = z.object({
   payload: WorkspaceTitleSetResponsePayloadSchema,
 });
 
+export const AgentMetadataUpdateResponseSchema = z.object({
+  type: z.literal("agent.metadata.update.response"),
+  payload: z.object({
+    requestId: z.string(),
+    agentId: z.string(),
+    accepted: z.boolean(),
+    metadata: EntityMetadataSchema.nullable(),
+    error: z.string().nullable(),
+  }),
+});
+
+export const WorkspaceMetadataUpdateResponseSchema = z.object({
+  type: z.literal("workspace.metadata.update.response"),
+  payload: z.object({
+    requestId: z.string(),
+    workspaceId: z.string(),
+    accepted: z.boolean(),
+    metadata: EntityMetadataSchema.nullable(),
+    error: z.string().nullable(),
+  }),
+});
+
 export const WorkspacePinSetResponsePayloadSchema = z.object({
   requestId: z.string(),
   workspaceId: z.string(),
@@ -2176,6 +2321,17 @@ export const WorkspacePinSetResponseSchema = z.object({
   payload: WorkspacePinSetResponsePayloadSchema,
 });
 
+export const WorkspaceBaseBranchSetResponseSchema = z.object({
+  type: z.literal("workspace.base_branch.set.response"),
+  payload: z.object({
+    requestId: z.string(),
+    workspaceId: z.string(),
+    accepted: z.boolean(),
+    baseRef: z.string().nullable(),
+    error: z.string().nullable(),
+  }),
+});
+
 export const WorkspaceRecoveryStateSchema = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("recoverable"),
@@ -2210,6 +2366,16 @@ export const WorkspaceRecoveryRestoreResponseSchema = z.object({
   }),
 });
 
+export const WorkspaceArchiveUndoResponseSchema = z.object({
+  type: z.literal("workspace.archive.undo.response"),
+  payload: z.object({
+    requestId: z.string(),
+    workspaceId: z.string(),
+    accepted: z.boolean(),
+    error: z.string().nullable(),
+  }),
+});
+
 export const SetVoiceModeResponseMessageSchema = z.object({
   type: z.literal("set_voice_mode_response"),
   payload: z.object({
@@ -2249,6 +2415,51 @@ const CheckoutDiffCompareSchema = z.object({
   ignoreWhitespace: z.boolean().optional(),
 });
 
+export const DiffEndpointSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("rev"), rev: z.string() }),
+  z.object({ kind: z.literal("index") }),
+  z.object({ kind: z.literal("worktree") }),
+  z.object({ kind: z.literal("empty") }),
+]);
+export const DiffErrorSchema = z.object({
+  code: z.enum([
+    "NOT_GIT_REPO",
+    "REF_NOT_FOUND",
+    "INVALID_COMPARE",
+    "TOO_MANY_SUBSCRIPTIONS",
+    "UNKNOWN",
+  ]),
+  message: z.string(),
+});
+export const DiffSubscribeRequestSchema = z.object({
+  type: z.literal("diff.subscribe.request"),
+  requestId: z.string(),
+  cwd: z.string(),
+  base: DiffEndpointSchema,
+  head: DiffEndpointSchema,
+  mergeBase: z.boolean().optional(),
+  ignoreWhitespace: z.boolean().optional(),
+  highlight: z.boolean().optional(),
+});
+// Unsubscribe is fire-and-forget; release has no correlated response.
+export const DiffUnsubscribeRequestSchema = z.object({
+  type: z.literal("diff.unsubscribe.request"),
+  subscriptionId: z.string(),
+});
+export const DiffSubscribeResponseSchema = z.object({
+  type: z.literal("diff.subscribe.response"),
+  payload: z.object({
+    requestId: z.string(),
+    subscriptionId: z.string(),
+    slot: z.number().int().min(0).max(255),
+    error: DiffErrorSchema.nullable(),
+  }),
+});
+export type DiffEndpoint = z.infer<typeof DiffEndpointSchema>;
+export type DiffError = z.infer<typeof DiffErrorSchema>;
+export type DiffSubscribeRequest = z.infer<typeof DiffSubscribeRequestSchema>;
+export type DiffSubscribeResponse = z.infer<typeof DiffSubscribeResponseSchema>;
+
 export const CheckoutStatusRequestSchema = z.object({
   type: z.literal("checkout_status_request"),
   cwd: z.string(),
@@ -2493,6 +2704,7 @@ export const BranchSuggestionsRequestSchema = z.object({
   cwd: z.string(),
   query: z.string().optional(),
   limit: z.number().int().min(1).max(200).optional(),
+  refMode: z.literal("exact").optional(),
   requestId: z.string(),
 });
 
@@ -2718,6 +2930,7 @@ export const WorkspaceCreateRequestSchema = z.object({
   idempotencyKey: z.string().min(1).max(512).optional(),
   // Optional user-set title applied to the created workspace.
   title: z.string().optional(),
+  metadata: EntityMetadataSchema.optional(),
   // Optional prompt context for workspace-level name/branch generation.
   firstAgentContext: FirstAgentContextSchema.optional(),
   // Retained for wire parsing; public internal creation is no longer supported.
@@ -2971,7 +3184,9 @@ const ListCommandsDraftConfigSchema = z.object({
   modeId: z.string().optional(),
   model: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
+  providerOptions: ProviderOptionsSchema.optional(),
 });
 
 export const ListProviderFeaturesRequestMessageSchema = z.object({
@@ -2980,6 +3195,12 @@ export const ListProviderFeaturesRequestMessageSchema = z.object({
   requestId: z.string(),
 });
 
+export const ProviderControlsListRequestMessageSchema = z.object({
+  type: z.literal("provider.controls.list.request"),
+  draftConfig: ListCommandsDraftConfigSchema,
+  requestId: z.string(),
+});
+
 export const ListCommandsRequestSchema = z.object({
   type: z.literal("list_commands_request"),
   agentId: z.string(),
@@ -3019,13 +3240,13 @@ export const ListTerminalsRequestSchema = z.object({
 export const SubscribeTerminalsRequestSchema = z.object({
   type: z.literal("subscribe_terminals_request"),
   requestId: z.string().optional(),
-  cwd: z.string(),
+  cwd: z.string().optional(),
   workspaceId: z.string().optional(),
 });
 
 export const UnsubscribeTerminalsRequestSchema = z.object({
   type: z.literal("unsubscribe_terminals_request"),
-  cwd: z.string(),
+  cwd: z.string().optional(),
   workspaceId: z.string().optional(),
 });
 
@@ -3157,6 +3378,7 @@ export const HubExecutionAgentCreateRequestSchema = z.object({
   model: z.string().optional(),
   modeId: z.string().optional(),
   thinkingOptionId: z.string().optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
   featureValues: z.record(z.string(), z.unknown()).optional(),
   providerOptions: ProviderOptionsSchema.optional(),
   toolPolicy: ToolPolicySchema.optional(),
@@ -3229,6 +3451,7 @@ export const SessionEventSubscriptionSchema = z.enum([
   "script_status_update",
   "workspace_setup_progress",
   "agent.provider_subagents.update",
+  "agent.background_work.update",
   "terminal_attention_required",
   "status.server_info",
   "status.daemon_config_changed",
@@ -3277,6 +3500,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   HostsUpdateRequestSchema,
   HostsRemoveRequestSchema,
   HostsLinkOpenRequestSchema,
+  HostsLinkAckSchema,
   HostsRouteOpenRequestSchema,
   HostsRouteFrameRequestSchema,
   HostsRouteCloseRequestSchema,
@@ -3296,6 +3520,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   FetchRecentProviderSessionsRequestMessageSchema,
   FetchWorkspacesRequestMessageSchema,
   ProjectListRequestMessageSchema,
+  ProjectSuggestionsRequestSchema,
   FetchAgentRequestMessageSchema,
   DeleteAgentRequestMessageSchema,
   ArchiveAgentRequestMessageSchema,
@@ -3305,7 +3530,10 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ProjectIconSetRequestSchema,
   ProjectRemoveRequestSchema,
   WorkspaceTitleSetRequestSchema,
+  AgentMetadataUpdateRequestSchema,
+  WorkspaceMetadataUpdateRequestSchema,
   WorkspacePinSetRequestSchema,
+  WorkspaceBaseBranchSetRequestSchema,
   WorkspaceLabelListRequestSchema,
   WorkspaceLabelAssignmentSetRequestSchema,
   WorkspaceLabelUpdateRequestSchema,
@@ -3313,6 +3541,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   WorkspaceLabelDeleteInspectRequestSchema,
   WorkspaceRecoveryInspectRequestSchema,
   WorkspaceRecoveryRestoreRequestSchema,
+  WorkspaceArchiveUndoRequestSchema,
   SetVoiceModeMessageSchema,
   SendAgentMessageRequestSchema,
   WaitForFinishRequestSchema,
@@ -3339,6 +3568,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableRequestSchema,
   PluginRemoveRequestSchema,
   PluginRpcInvokeRequestSchema,
+  PluginRpcSubscribeRequestSchema,
   AgentTimelineAppendRequestSchema,
   AgentSkillsGetStatusRequestSchema,
   AgentSkillsReconcileRequestSchema,
@@ -3357,6 +3587,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModelsRequestMessageSchema,
   ListProviderModesRequestMessageSchema,
   ListProviderFeaturesRequestMessageSchema,
+  ProviderControlsListRequestMessageSchema,
   ListAvailableProvidersRequestMessageSchema,
   GetProvidersSnapshotRequestMessageSchema,
   RefreshProvidersSnapshotRequestMessageSchema,
@@ -3374,6 +3605,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   AgentTimelineSearchRequestMessageSchema,
   AgentTimelineListPromptsRequestMessageSchema,
   ProviderSubagentListRequestMessageSchema,
+  AgentBackgroundWorkListRequestMessageSchema,
+  AgentBackgroundWorkStopRequestMessageSchema,
   ProviderSubagentTimelineRequestMessageSchema,
   SetAgentTimelineSubscriptionRequestMessageSchema,
   AgentForkContextRequestMessageSchema,
@@ -3385,6 +3618,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   AgentDetachRequestMessageSchema,
   AgentRewindRequestMessageSchema,
   AgentPermissionResponseMessageSchema,
+  DiffSubscribeRequestSchema,
+  DiffUnsubscribeRequestSchema,
   CheckoutStatusRequestSchema,
   CheckoutDiffGetRequestSchema,
   SubscribeCheckoutDiffRequestSchema,
@@ -3675,6 +3910,8 @@ export const ServerInfoStatusPayloadSchema = z
         // COMPAT(internalWorkspaces): added in v0.9.0; remove gate after 2027-03-17.
         internalWorkspaces: z.boolean().optional(),
         backgroundWorkspaces: z.boolean().optional(),
+        // COMPAT(backgroundAgents): added in v0.15.0; remove gate after 2027-05-03.
+        backgroundAgents: z.boolean().optional(),
         providersSnapshot: z.boolean().optional(),
         connectedHosts: z.boolean().optional(),
         hostMultiplexing: z.boolean().optional(),
@@ -3687,6 +3924,9 @@ export const ServerInfoStatusPayloadSchema = z
         directorySync: z.boolean().optional(),
         // COMPAT(workspaceLabels): added in v0.5.0, remove after 2027-08-14.
         workspaceLabels: z.boolean().optional(),
+        terminalCollection: z.boolean().optional(),
+        // COMPAT(workspaceBaseBranch): added after v0.11.2, remove gate after 2027-10-14.
+        workspaceBaseBranch: z.boolean().optional(),
         // COMPAT(workspaceSetupRun): added in v0.8.0, remove gate after 2027-09-02.
         workspaceSetupRun: z.boolean().optional(),
         // COMPAT(workspaceTerminals): added in v0.8.0, remove gate after 2027-09-05.
@@ -3739,6 +3979,8 @@ export const ServerInfoStatusPayloadSchema = z
         pluginThemes: z.boolean().optional(),
         pluginSettings: z.boolean().optional(),
         pluginTimelineItems: z.boolean().optional(),
+        // COMPAT(pluginSubscriptions): added in v0.15.0, remove gate after 2027-05-02.
+        pluginSubscriptions: z.boolean().optional(),
         // COMPAT(skillManagement): added in v0.4.0, remove gate after 2027-08-16.
         skillManagement: z.boolean().optional(),
         // COMPAT(idleRuntimeCleanupSetting): added in v0.13.0, remove gate after 2027-04-26.
@@ -3751,6 +3993,8 @@ export const ServerInfoStatusPayloadSchema = z
         "terminal-input-mode-replay": z.boolean().optional(),
         // COMPAT(terminalSizeOwnership): added in v0.2.6, remove gate after 2027-02-02.
         "terminal-size-ownership": z.boolean().optional(),
+        // COMPAT(terminalGraphemeWidths): added in v0.15.0, remove gate after 2027-05-01.
+        "terminal-grapheme-widths": z.boolean().optional(),
         // COMPAT(rewind): added in v0.1.X, drop the gate when floor >= v0.1.X.
         rewind: z.boolean().optional(),
         // COMPAT(timelineRewindOperations): added in v0.14.1, remove gate after 2027-05-10.
@@ -3772,6 +4016,8 @@ export const ServerInfoStatusPayloadSchema = z
         worktreeRestore: z.boolean().optional(),
         // COMPAT(workspaceRecovery): added in v0.1.105, remove after 2027-01-11 once daemon floor >= v0.1.105.
         workspaceRecovery: z.boolean().optional(),
+        // COMPAT(workspaceArchiveUndo): added in v0.15.3, remove gate after 2027-05-06.
+        workspaceArchiveUndo: z.boolean().optional(),
         // COMPAT(workspaceFileEditing): added in v0.2.0, remove after 2027-01-18 once daemon floor >= v0.2.0.
         workspaceFileEditing: z.boolean().optional(),
         // COMPAT(fileByteWrites): added in v0.13.0, remove gate after 2027-04-20.
@@ -3794,6 +4040,10 @@ export const ServerInfoStatusPayloadSchema = z
         agentForkContextCursor: z.boolean().optional(),
         // COMPAT(providerSubagents): added in v0.1.107, remove gate after 2027-01-12.
         providerSubagents: z.boolean().optional(),
+        // COMPAT(agentBackgroundWork): added after v0.11.0-beta.5, remove gate after 2027-04-06.
+        agentBackgroundWork: z.boolean().optional(),
+        // COMPAT(agentBackgroundWorkStop): added after v0.15.0, remove after 2027-05-03.
+        agentBackgroundWorkStop: z.boolean().optional(),
         // COMPAT(projectedSubagentTimeline): added after v0.8.0, remove gates after 2027-03-14; retain wire field.
         projectedSubagentTimeline: z.boolean().optional(),
         wholeTurnTimeline: z.boolean().optional(),
@@ -3816,6 +4066,8 @@ export const ServerInfoStatusPayloadSchema = z
         projectCreateDirectory: z.boolean().optional(),
         // COMPAT(projectList): added in v0.2.4, drop the gate when floor >= v0.2.4.
         projectList: z.boolean().optional(),
+        // COMPAT(projectSuggestions): added in v0.14.1, remove gate after 2027-05-01.
+        projectSuggestions: z.boolean().optional(),
         // COMPAT(commitsList): added in v0.1.110, remove gate after 2027-01-16.
         commitsList: z.boolean().optional(),
         // COMPAT(commitBaseClassification): added in v0.2.0, remove gate after 2027-01-23.
@@ -3824,6 +4076,8 @@ export const ServerInfoStatusPayloadSchema = z
         providerRemoval: z.boolean().optional(),
         // COMPAT(hopliteProvider): added after v0.11.2, remove after 2027-04-15 once host floor includes the bundled adapter.
         hopliteProvider: z.boolean().optional(),
+        // COMPAT(fxProvider): added after v0.15.3, remove after 2027-05-09 once host floor includes the bundled adapter.
+        fxProvider: z.boolean().optional(),
         // COMPAT(importSessionWorkspaceTarget): added in v0.1.110, remove gate after 2027-01-16.
         importSessionWorkspaceTarget: z.boolean().optional(),
         // COMPAT(importSessionSearch): added in v0.8.0, remove gate after 2027-03-02.
@@ -3835,8 +4089,13 @@ export const ServerInfoStatusPayloadSchema = z
         forgeProviders: z.boolean().optional(),
         // COMPAT(selectiveAgentTimeline): added in v0.1.106, remove after 2027-01-12.
         selectiveAgentTimeline: z.boolean().optional(),
+        // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+        timelineFreshnessCheck: z.boolean().optional(),
         explicitEventSubscriptions: z.boolean().optional(),
         ownedSubscriptions: z.boolean().optional(),
+        providerOptionControls: z.boolean().optional(),
+        entityMetadata: z.boolean().optional(),
+        diffSubscription: z.boolean().optional(),
         binaryChunkingV1: z.boolean().optional(),
         workspaceSetupObservation: z.boolean().optional(),
         workspaceSortTimes: z.boolean().optional(),
@@ -4141,6 +4400,8 @@ export const WorkspaceGitHubRuntimePayloadSchema = z
 
 export const WorkspaceDescriptorPayloadSchema = z
   .object({
+    // Informational creation ancestry; independent of placement and lifecycle.
+    parentWorkspaceId: z.string().optional(),
     id: z.string(),
     projectId: z.string(),
     projectDisplayName: z.string(),
@@ -4173,6 +4434,7 @@ export const WorkspaceDescriptorPayloadSchema = z
     pinnedAt: z.string().nullable().optional(),
     // COMPAT(workspaceLabels): added in v0.5.0, remove optional after 2027-08-14.
     labels: z.array(z.string()).optional(),
+    metadata: EntityMetadataSchema.optional(),
     // Retained for wire parsing of older daemon descriptors.
     internal: z.boolean().optional(),
     background: z.boolean().optional(),
@@ -4503,6 +4765,24 @@ export const ProjectListResponseMessageSchema = z.object({
   }),
 });
 
+export const ProjectSuggestionSchema = z.object({
+  // The main repository root for git checkouts and their worktrees; the session cwd otherwise.
+  rootPath: z.string(),
+  displayName: z.string(),
+  sessionCount: z.number().int().nonnegative(),
+  providerIds: z.array(z.string()),
+  lastActivityAt: z.string(),
+});
+
+export const ProjectSuggestionsResponseSchema = z.object({
+  type: z.literal("project.suggestions.response"),
+  payload: z.object({
+    requestId: z.string(),
+    suggestions: z.array(ProjectSuggestionSchema),
+    providerErrors: z.array(z.object({ provider: z.string(), message: z.string() })),
+  }),
+});
+
 export const ScriptStatusUpdateMessageSchema = z.object({
   type: z.literal("script_status_update"),
   payload: z.object({
@@ -4728,6 +5008,8 @@ export const ArchiveWorkspaceResponseMessageSchema = z.object({
     workspaceId: z.string(),
     archivedAt: z.string().nullable(),
     error: z.string().nullable(),
+    // An undo stopped this archive before it finished; `error` carries the reason.
+    canceled: z.boolean().optional(),
   }),
 });
 
@@ -4883,6 +5165,51 @@ export const ProviderSubagentListResponseMessageSchema = z.object({
   }),
 });
 
+export const AgentBackgroundWorkItemSchema = z.object({
+  id: z.string(),
+  // Open string: known kinds include "shell" and "monitor".
+  // Clients treat unknown values as "other".
+  kind: z.string(),
+  description: z.string().nullable(),
+  command: z.string().optional(),
+  startedAt: z.string(),
+  canStop: z.boolean().optional(),
+  stopToken: z.string().optional(),
+});
+
+export type AgentBackgroundWorkItemPayload = z.infer<typeof AgentBackgroundWorkItemSchema>;
+
+export const AgentBackgroundWorkListResponseMessageSchema = z.object({
+  type: z.literal("agent.background_work.list.response"),
+  payload: z.object({
+    requestId: z.string(),
+    agentId: z.string(),
+    items: z.array(AgentBackgroundWorkItemSchema),
+    error: z.string().nullable(),
+  }),
+});
+
+export const AgentBackgroundWorkStopResponseMessageSchema = z.object({
+  type: z.literal("agent.background_work.stop.response"),
+  payload: z.object({
+    requestId: z.string(),
+    agentId: z.string(),
+    itemId: z.string(),
+    error: z.string().nullable(),
+  }),
+});
+
+// Event push delivered through session.events.set_subscription; it has no .request/.response pair.
+// Each update replaces the agent's whole list.
+export const AgentBackgroundWorkUpdateMessageSchema = z.object({
+  type: z.literal("agent.background_work.update"),
+  payload: z.object({
+    subscriptionId: z.string().optional(),
+    agentId: z.string(),
+    items: z.array(AgentBackgroundWorkItemSchema),
+  }),
+});
+
 export const ProviderSubagentTimelineResponseMessageSchema = z.object({
   type: z.literal("agent.provider_subagents.timeline.get.response"),
   payload: z.object({
@@ -4960,6 +5287,11 @@ export const SetAgentTimelineSubscriptionResponseMessageSchema = z.object({
     subscriptionId: z.string().optional(),
     agentIds: z.array(z.string()),
     requestId: z.string(),
+    // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+    timelines: z.record(z.string(), TimelineFreshnessSchema).optional(),
+    // The agent row for each chat answered "current", which gets no timeline fetch to carry it.
+    // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+    agents: z.record(z.string(), AgentSnapshotPayloadSchema).optional(),
   }),
 });
 
@@ -5382,6 +5714,8 @@ const CheckoutStatusCommonSchema = z.object({
   cwd: z.string(),
   error: CheckoutErrorSchema.nullable(),
   requestId: z.string(),
+  baseRefExact: z.string().nullable().optional(),
+  comparisonBaseRef: z.string().nullable().optional(),
   // The full ref currentBranch tracks, as git resolves `<branch>@{upstream}`:
   // "refs/remotes/origin/main", "refs/remotes/upstream/main" on a fork, or a
   // "refs/heads/..." ref for a branch tracking a local branch. Null when there is no
@@ -6327,6 +6661,19 @@ export const ListProviderModesResponseMessageSchema = z.object({
   }),
 });
 
+export const ProviderControlsListResponseMessageSchema = z.object({
+  type: z.literal("provider.controls.list.response"),
+  payload: z.object({
+    provider: AgentProviderSchema,
+    controls: z.array(AgentOptionControlSchema).optional(),
+    /** Effective options for the draft: `config.json` defaults merged with the draft's own. */
+    options: ProviderOptionsSchema.optional(),
+    error: z.string().nullable().optional(),
+    fetchedAt: z.string(),
+    requestId: z.string(),
+  }),
+});
+
 export const ListProviderFeaturesResponseMessageSchema = z.object({
   type: z.literal("list_provider_features_response"),
   payload: z.object({
@@ -6545,6 +6892,8 @@ export const ListCommandsResponseSchema = z.object({
 // ============================================================================
 
 const TerminalInfoSchema = z.object({
+  createdAt: z.string().nullable().optional(),
+  isScript: z.boolean().optional(),
   id: z.string(),
   name: z.string(),
   cwd: z.string(),
@@ -6608,8 +6957,8 @@ export const TerminalsChangedSchema = z.object({
     subscriptionId: z.string().optional(),
     requestId: z.string().optional(),
     workspaceId: z.string().optional(),
-    cwd: z.string(),
-    terminals: z.array(TerminalInfoSchema.omit({ cwd: true })),
+    cwd: z.string().optional(),
+    terminals: z.array(TerminalInfoSchema.partial({ cwd: true })),
   }),
 });
 
@@ -6982,10 +7331,26 @@ export const PluginRpcInvokeResponseSchema = z.object({
   type: z.literal("plugin.rpc.invoke.response"),
   payload: z.object({
     requestId: z.string(),
-    output: z.unknown(),
+    output: z.unknown().optional(),
   }),
 });
 
+export const PluginRpcSubscribeResponseSchema = z.object({
+  type: z.literal("plugin.rpc.subscribe.response"),
+  payload: z.object({ requestId: z.string(), subscriptionId: z.string() }),
+});
+
+/** A JSON subscription event. A `Uint8Array` event rides as binary opcode 0x20 instead. */
+export const PluginRpcEventSchema = z.object({
+  type: z.literal("plugin.rpc.event"),
+  payload: z.object({ subscriptionId: z.string(), event: z.unknown() }),
+});
+
+export const PluginRpcClosedSchema = z.object({
+  type: z.literal("plugin.rpc.closed"),
+  payload: z.object({ subscriptionId: z.string(), error: z.string().optional() }),
+});
+
 export const AgentTimelineAppendResponseSchema = z.object({
   type: z.literal("agent.timeline.append.response"),
   payload: z.object({
@@ -7059,6 +7424,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableResponseSchema,
   PluginRemoveResponseSchema,
   PluginRpcInvokeResponseSchema,
+  PluginRpcSubscribeResponseSchema,
+  PluginRpcEventSchema,
+  PluginRpcClosedSchema,
   AgentTimelineAppendResponseSchema,
   AgentSkillsGetStatusResponseSchema,
   AgentSkillsReconcileResponseSchema,
@@ -7090,6 +7458,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   WorkspaceLabelDeleteInspectResponseSchema,
   ProjectUpdateMessageSchema,
   ProjectListResponseMessageSchema,
+  ProjectSuggestionsResponseSchema,
   ScriptStatusUpdateMessageSchema,
   WorkspaceSetupProgressMessageSchema,
   WorkspaceSetupStatusResponseMessageSchema,
@@ -7122,6 +7491,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ProviderSubagentListResponseMessageSchema,
   ProviderSubagentTimelineResponseMessageSchema,
   ProviderSubagentUpdateMessageSchema,
+  AgentBackgroundWorkListResponseMessageSchema,
+  AgentBackgroundWorkStopResponseMessageSchema,
+  AgentBackgroundWorkUpdateMessageSchema,
   SetAgentTimelineSubscriptionResponseMessageSchema,
   AgentAttentionRequiredMessageSchema,
   AgentForkContextResponseMessageSchema,
@@ -7160,15 +7532,20 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ProjectIconSetResponseSchema,
   ProjectRemoveResponseSchema,
   WorkspaceTitleSetResponseSchema,
+  AgentMetadataUpdateResponseSchema,
+  WorkspaceMetadataUpdateResponseSchema,
   WorkspacePinSetResponseSchema,
+  WorkspaceBaseBranchSetResponseSchema,
   WorkspaceRecoveryInspectResponseSchema,
   WorkspaceRecoveryRestoreResponseSchema,
+  WorkspaceArchiveUndoResponseSchema,
   WaitForFinishResponseMessageSchema,
   AgentPermissionRequestMessageSchema,
   AgentPermissionResolvedMessageSchema,
   AgentDeletedMessageSchema,
   AgentArchivedMessageSchema,
   CloseItemsResponseSchema,
+  DiffSubscribeResponseSchema,
   CheckoutStatusResponseSchema,
   CheckoutStatusUpdateSchema,
   CheckoutDiffGetResponseSchema,
@@ -7220,6 +7597,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModelsResponseMessageSchema,
   ListProviderModesResponseMessageSchema,
   ListProviderFeaturesResponseMessageSchema,
+  ProviderControlsListResponseMessageSchema,
   ListAvailableProvidersResponseSchema,
   GetProvidersSnapshotResponseMessageSchema,
   ProvidersSnapshotUpdateMessageSchema,
@@ -7376,6 +7754,7 @@ export type WorkspaceRecoveryInspectResponse = z.infer<
 export type WorkspaceRecoveryRestoreResponse = z.infer<
   typeof WorkspaceRecoveryRestoreResponseSchema
 >;
+export type WorkspaceArchiveUndoResponse = z.infer<typeof WorkspaceArchiveUndoResponseSchema>;
 export type WorkspaceCreateRequest = z.infer<typeof WorkspaceCreateRequestSchema>;
 export type WorkspaceCreateResponse = z.infer<typeof WorkspaceCreateResponseSchema>;
 export type ProjectRenameResponsePayload = z.infer<typeof ProjectRenameResponsePayloadSchema>;
@@ -7455,6 +7834,9 @@ export type FetchRecentProviderSessionsRequestMessage = z.infer<
 >;
 export type FetchWorkspacesRequestMessage = z.infer<typeof FetchWorkspacesRequestMessageSchema>;
 export type ProjectListRequestMessage = z.infer<typeof ProjectListRequestMessageSchema>;
+export type ProjectSuggestionsRequest = z.infer<typeof ProjectSuggestionsRequestSchema>;
+export type ProjectSuggestion = z.infer<typeof ProjectSuggestionSchema>;
+export type ProjectSuggestionsResponse = z.infer<typeof ProjectSuggestionsResponseSchema>;
 export type FetchAgentRequestMessage = z.infer<typeof FetchAgentRequestMessageSchema>;
 export type AgentForkContextRequestMessage = z.infer<typeof AgentForkContextRequestMessageSchema>;
 export type SendAgentMessageRequest = z.infer<typeof SendAgentMessageRequestSchema>;
@@ -7474,6 +7856,12 @@ export type ListProviderModelsRequestMessage = z.infer<
   typeof ListProviderModelsRequestMessageSchema
 >;
 export type ListProviderModesRequestMessage = z.infer<typeof ListProviderModesRequestMessageSchema>;
+export type ProviderControlsListRequestMessage = z.infer<
+  typeof ProviderControlsListRequestMessageSchema
+>;
+export type ProviderControlsListResponseMessage = z.infer<
+  typeof ProviderControlsListResponseMessageSchema
+>;
 export type ListProviderFeaturesRequestMessage = z.infer<
   typeof ListProviderFeaturesRequestMessageSchema
 >;
@@ -7519,8 +7907,14 @@ export type ProjectIconSetRequest = z.infer<typeof ProjectIconSetRequestSchema>;
 export type ProjectRemoveRequest = z.infer<typeof ProjectRemoveRequestSchema>;
 export type WorkspaceTitleSetRequest = z.infer<typeof WorkspaceTitleSetRequestSchema>;
 export type WorkspacePinSetRequest = z.infer<typeof WorkspacePinSetRequestSchema>;
+export type AgentMetadataUpdateRequest = z.infer<typeof AgentMetadataUpdateRequestSchema>;
+export type WorkspaceMetadataUpdateRequest = z.infer<typeof WorkspaceMetadataUpdateRequestSchema>;
+export type AgentMetadataUpdateResponse = z.infer<typeof AgentMetadataUpdateResponseSchema>;
+export type WorkspaceMetadataUpdateResponse = z.infer<typeof WorkspaceMetadataUpdateResponseSchema>;
+export type WorkspaceBaseBranchSetRequest = z.infer<typeof WorkspaceBaseBranchSetRequestSchema>;
 export type WorkspaceRecoveryInspectRequest = z.infer<typeof WorkspaceRecoveryInspectRequestSchema>;
 export type WorkspaceRecoveryRestoreRequest = z.infer<typeof WorkspaceRecoveryRestoreRequestSchema>;
+export type WorkspaceArchiveUndoRequest = z.infer<typeof WorkspaceArchiveUndoRequestSchema>;
 export type SetAgentModeRequestMessage = z.infer<typeof SetAgentModeRequestMessageSchema>;
 export type SetAgentModelRequestMessage = z.infer<typeof SetAgentModelRequestMessageSchema>;
 export type SetAgentThinkingRequestMessage = z.infer<typeof SetAgentThinkingRequestMessageSchema>;
@@ -7764,6 +8158,7 @@ export const WSHelloMessageSchema = z.object({
       [CLIENT_CAPS.timelineReplacementInvalidation]: z.boolean().optional(),
       [CLIENT_CAPS.timelineRewindOperations]: z.boolean().optional(),
       [CLIENT_CAPS.timelineNotifications]: z.boolean().optional(),
+      [CLIENT_CAPS.backgroundAgents]: z.boolean().optional(),
       [CLIENT_CAPS.browserHost]: BrowserAutomationHostCapabilitySchema.optional(),
     })
     .passthrough()
diff --git a/packages/protocol/src/messages.wire-compat.test.ts b/packages/protocol/src/messages.wire-compat.test.ts
index 9ce4f2061d..940f340a59 100644
--- a/packages/protocol/src/messages.wire-compat.test.ts
+++ b/packages/protocol/src/messages.wire-compat.test.ts
@@ -12,8 +12,65 @@ import {
   WorkspaceSetupSnapshotSchema,
   WorkspaceSetupProgressMessageSchema,
   AgentTimelineEntryPayloadSchema,
+  CheckoutStatusResponseSchema,
+  BranchSuggestionsRequestSchema,
+  WorkspaceBaseBranchSetRequestSchema,
+  WorkspaceBaseBranchSetResponseSchema,
 } from "./messages.js";
 
+test("base selection RPCs are correlated while older checkout and branch messages remain valid", () => {
+  const payload = {
+    cwd: "/repo",
+    requestId: "status",
+    error: null,
+    isGit: true,
+    isPaseoOwnedWorktree: false,
+    repoRoot: "/repo",
+    currentBranch: "feature",
+    isDirty: false,
+    baseRef: "release",
+    aheadBehind: null,
+    aheadOfOrigin: null,
+    behindOfOrigin: null,
+    hasRemote: false,
+    remoteUrl: null,
+  };
+  expect(
+    CheckoutStatusResponseSchema.safeParse({ type: "checkout_status_response", payload }).success,
+  ).toBe(true);
+  expect(
+    CheckoutStatusResponseSchema.parse({
+      type: "checkout_status_response",
+      payload: { ...payload, baseRefExact: "refs/remotes/upstream/release" },
+    }).payload.baseRefExact,
+  ).toBe("refs/remotes/upstream/release");
+  expect(
+    BranchSuggestionsRequestSchema.safeParse({
+      type: "branch_suggestions_request",
+      cwd: "/repo",
+      requestId: "branches",
+    }).success,
+  ).toBe(true);
+  const request = {
+    type: "workspace.base_branch.set.request",
+    workspaceId: "workspace",
+    baseRef: "refs/heads/release",
+    requestId: "base",
+  };
+  expect(WorkspaceBaseBranchSetRequestSchema.parse(request)).toEqual(request);
+  const response = {
+    type: "workspace.base_branch.set.response",
+    payload: {
+      workspaceId: "workspace",
+      baseRef: "refs/heads/release",
+      requestId: "base",
+      accepted: true,
+      error: null,
+    },
+  };
+  expect(WorkspaceBaseBranchSetResponseSchema.parse(response)).toEqual(response);
+});
+
 test("terminal listings accept older rows and retain new per-terminal directories", () => {
   const response = {
     type: "list_terminals_response",
diff --git a/packages/protocol/src/messages.workspaces.test.ts b/packages/protocol/src/messages.workspaces.test.ts
index 3cb9b0d5bd..8a5bd13224 100644
--- a/packages/protocol/src/messages.workspaces.test.ts
+++ b/packages/protocol/src/messages.workspaces.test.ts
@@ -634,6 +634,26 @@ describe("workspace message schemas", () => {
     ]);
   });
 
+  test("preserves informational workspace parentage in directory updates", () => {
+    const workspace = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "project",
+      projectDisplayName: "repo",
+      projectRootPath: "/repo",
+      projectKind: "git",
+      workspaceKind: "worktree",
+      name: "child",
+      status: "done",
+      activityAt: null,
+    };
+    expect(WorkspaceDescriptorPayloadSchema.parse(workspace).parentWorkspaceId).toBe("parent");
+    expect(
+      WorkspaceDescriptorPayloadSchema.parse({ ...workspace, parentWorkspaceId: undefined })
+        .parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   test("parses legacy workspace descriptors without workspaceDirectory", () => {
     const parsed = SessionOutboundMessageSchema.parse({
       type: "workspace_update",
diff --git a/packages/protocol/src/option-controls.ts b/packages/protocol/src/option-controls.ts
new file mode 100644
index 0000000000..29b7df40fb
--- /dev/null
+++ b/packages/protocol/src/option-controls.ts
@@ -0,0 +1,107 @@
+import type {
+  AgentFeature,
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  ProviderOptions,
+} from "./agent-types.js";
+
+// COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+// `features` are controls with their value attached. The daemon builds them for apps that
+// predate controls, and the client package rebuilds controls and options from them when it
+// talks to a daemon that predates controls. Both directions live here so they stay inverse.
+
+function selectedChoice(control: AgentOptionSelectControl, options: ProviderOptions) {
+  const value = options[control.key];
+  if (typeof value === "string") {
+    const choice = control.choices.find((candidate) => candidate.value === value);
+    if (choice) return choice.value;
+  }
+  return control.defaultValue ?? null;
+}
+
+function describe(control: { description?: string; tooltip?: string; icon?: string }): {
+  description?: string;
+  tooltip?: string;
+  icon?: string;
+} {
+  return {
+    ...(control.description !== undefined ? { description: control.description } : {}),
+    ...(control.tooltip !== undefined ? { tooltip: control.tooltip } : {}),
+    ...(control.icon !== undefined ? { icon: control.icon } : {}),
+  };
+}
+
+function featureFromControl(control: AgentOptionControl, effective: ProviderOptions): AgentFeature {
+  if (control.type === "toggle") {
+    const value = effective[control.key];
+    return {
+      type: "toggle",
+      id: control.key,
+      label: control.label,
+      ...describe(control),
+      value: typeof value === "boolean" ? value : (control.defaultValue ?? false),
+    };
+  }
+  return {
+    type: "select",
+    id: control.key,
+    label: control.label,
+    ...describe(control),
+    ...(control.desktopTrigger ? { desktopTrigger: control.desktopTrigger } : {}),
+    value: selectedChoice(control, effective),
+    options: control.choices.map((choice) => ({
+      id: choice.value,
+      label: choice.label,
+      ...(choice.description ? { description: choice.description } : {}),
+      ...(choice.value === control.defaultValue ? { isDefault: true } : {}),
+    })),
+  };
+}
+
+/** Apps that predate controls render `features`; build them from controls + effective options. */
+export function featuresFromControls(input: {
+  controls: readonly AgentOptionControl[] | undefined;
+  options: ProviderOptions | undefined;
+}): AgentFeature[] {
+  const { controls, options } = input;
+  const effective = options ?? {};
+  return (controls ?? []).map((control) => featureFromControl(control, effective));
+}
+
+/** A recorded feature's value is not carried over: controls hold no state, only `options` do. */
+function controlFromFeature(feature: AgentFeature): AgentOptionControl {
+  const descriptor = {
+    key: feature.id,
+    label: feature.label,
+    ...describe(feature),
+  };
+  if (feature.type === "toggle") {
+    return { type: "toggle", ...descriptor };
+  }
+  const defaultChoice = feature.options.find((option) => option.isDefault);
+  return {
+    type: "select",
+    ...descriptor,
+    ...(feature.desktopTrigger ? { desktopTrigger: feature.desktopTrigger } : {}),
+    ...(defaultChoice ? { defaultValue: defaultChoice.id } : {}),
+    choices: feature.options.map((option) => ({
+      value: option.id,
+      label: option.label,
+      ...(option.description ? { description: option.description } : {}),
+    })),
+  };
+}
+
+/** Agent records and daemons that predate controls carry `features`; their descriptors become controls. */
+export function controlsFromFeatures(
+  features: readonly AgentFeature[] | undefined,
+): AgentOptionControl[] {
+  return (features ?? []).map(controlFromFeature);
+}
+
+/** The options a list of `features` stands for: each feature's value under its id. */
+export function optionsFromFeatures(
+  features: readonly AgentFeature[] | undefined,
+): ProviderOptions {
+  return Object.fromEntries((features ?? []).map((feature) => [feature.id, feature.value]));
+}
diff --git a/packages/protocol/src/provider-icon-names.ts b/packages/protocol/src/provider-icon-names.ts
index 5f707dfeff..37dac496dc 100644
--- a/packages/protocol/src/provider-icon-names.ts
+++ b/packages/protocol/src/provider-icon-names.ts
@@ -28,6 +28,7 @@ export const ACP_PROVIDER_ICON_NAMES = [
   "dirac",
   "factory-droid",
   "fast-agent",
+  "fx",
   "gemini",
   "gjc",
   "glm-acp-agent",
diff --git a/packages/protocol/src/schedule/cron-expression.test.ts b/packages/protocol/src/schedule/cron-expression.test.ts
index 0db1d68ea1..cb15451700 100644
--- a/packages/protocol/src/schedule/cron-expression.test.ts
+++ b/packages/protocol/src/schedule/cron-expression.test.ts
@@ -13,6 +13,37 @@ describe("cron expression parser", () => {
     expect(cron.dayOfWeek.matches(0)).toBe(false);
   });
 
+  it("rejects a step after a standalone number", () => {
+    expect(validateCronExpression("0/15 * * * *")).toBe(
+      "Invalid cron minute step: use * or a range before /",
+    );
+  });
+
+  it.each([
+    ["5/1 * * * *", "minute"],
+    ["0,5/15 * * * *", "minute"],
+    ["* 1/2 * * *", "hour"],
+    ["* * 1/2 * *", "day-of-month"],
+    ["* * * 1/2 *", "month"],
+    ["* * * * 1/2", "day-of-week"],
+  ])("rejects ignored numeric steps in %s", (expression, field) => {
+    expect(validateCronExpression(expression)).toBe(
+      `Invalid cron ${field} step: use * or a range before /`,
+    );
+  });
+
+  it.each([
+    { expression: "*/15 * * * *", expected: [0, 15, 30, 45] },
+    { expression: "0-59/15 * * * *", expected: [0, 15, 30, 45] },
+    { expression: "5-59/15 * * * *", expected: [5, 20, 35, 50] },
+  ])("preserves supported steps in $expression", ({ expression, expected }) => {
+    const cron = parseCronExpression(expression);
+    const minutes = Array.from({ length: 60 }, (_, minute) => minute);
+    const matches = minutes.filter((minute) => cron.minute.matches(minute));
+
+    expect(matches).toEqual(expected);
+  });
+
   it("reports invalid expressions with server-facing copy", () => {
     expect(validateCronExpression("* * *")).toBe("Cron expressions must have 5 fields");
     expect(validateCronExpression("*/5/2 * * * *")).toBe("Invalid cron minute step");
diff --git a/packages/protocol/src/schedule/cron-expression.ts b/packages/protocol/src/schedule/cron-expression.ts
index 691631d682..5cfffbbb1b 100644
--- a/packages/protocol/src/schedule/cron-expression.ts
+++ b/packages/protocol/src/schedule/cron-expression.ts
@@ -5,6 +5,7 @@ interface CronFieldBounds {
 }
 
 export interface CronFieldMatcher {
+  isWildcard: boolean;
   matches(value: number): boolean;
 }
 
@@ -90,6 +91,9 @@ function parseField(source: string, bounds: CronFieldBounds): CronFieldMatcher {
     if (!/^\d+$/.test(base)) {
       throw new Error(`Invalid cron ${bounds.name} value`);
     }
+    // COMPAT(cronNumericSteps): added in v0.12.0, remove after 2027-04-17 once
+    // persisted numeric steps are migrated. Validation rejects new numeric steps;
+    // existing schedules retain their historical singleton match.
     const value = Number.parseInt(base, 10);
     if (!Number.isInteger(value) || value < bounds.min || value > bounds.max) {
       throw new Error(`Invalid cron ${bounds.name} value`);
@@ -98,6 +102,7 @@ function parseField(source: string, bounds: CronFieldBounds): CronFieldMatcher {
   }
 
   return {
+    isWildcard: trimmed.startsWith("*"),
     matches(value: number): boolean {
       return allowed.has(value);
     },
@@ -122,6 +127,12 @@ export function parseCronExpression(expression: string): ParsedCronExpression {
 export function validateCronExpression(expression: string): string | null {
   try {
     parseCronExpression(expression);
+    const fields = expression.trim().split(/\s+/);
+    for (const [index, field] of fields.entries()) {
+      if (field.split(",").some((part) => /^\d+\//.test(part))) {
+        return `Invalid cron ${CRON_FIELD_BOUNDS[index].name} step: use * or a range before /`;
+      }
+    }
     return null;
   } catch (error) {
     return error instanceof Error ? error.message : "Invalid cron expression";
diff --git a/packages/protocol/src/schedule/types.ts b/packages/protocol/src/schedule/types.ts
index 718c7e05ca..731d902970 100644
--- a/packages/protocol/src/schedule/types.ts
+++ b/packages/protocol/src/schedule/types.ts
@@ -34,6 +34,7 @@ export const ScheduleTargetSchema = z.discriminatedUnion("type", [
       isolation: z.enum(["local", "worktree"]).optional(),
       title: z.string().trim().min(1).nullable().optional(),
       providerOptions: z.record(z.string(), z.unknown()).optional(),
+      // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Folded into providerOptions.
       featureValues: z.record(z.string(), z.unknown()).optional(),
       systemPrompt: z.string().optional(),
       mcpServers: z.record(z.string(), z.unknown()).optional(),
diff --git a/packages/protocol/src/terminal-subscription-key.ts b/packages/protocol/src/terminal-subscription-key.ts
index 648ff96f71..4d64dfff83 100644
--- a/packages/protocol/src/terminal-subscription-key.ts
+++ b/packages/protocol/src/terminal-subscription-key.ts
@@ -3,6 +3,11 @@
 // and tear down its own live subscription without disturbing the other. An
 // absent workspaceId (old clients) keys to the cwd on its own. The `::`
 // separator cannot collide with a workspace id, which is always `wks_<hex>`.
-export function terminalSubscriptionKey(cwd: string, workspaceId: string | undefined): string {
+export function terminalSubscriptionKey(
+  cwd: string | undefined,
+  workspaceId: string | undefined,
+): string {
+  if (cwd === undefined)
+    return workspaceId === undefined ? "terminal-host" : `${workspaceId}::terminal-host`;
   return workspaceId === undefined ? cwd : `${workspaceId}::${cwd}`;
 }
diff --git a/packages/protocol/tests/validation/ws-outbound.test.ts b/packages/protocol/tests/validation/ws-outbound.test.ts
index ed147d89ad..18b0cd999f 100644
--- a/packages/protocol/tests/validation/ws-outbound.test.ts
+++ b/packages/protocol/tests/validation/ws-outbound.test.ts
@@ -5,7 +5,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 import type { z } from "zod";
 import { describe, expect, it } from "vitest";
-import { WSOutboundMessageSchema } from "../../src/messages.js";
+import { PluginRpcInvokeResponseSchema, WSOutboundMessageSchema } from "../../src/messages.js";
 import { validateWSOutboundMessage } from "../../src/validation/ws-outbound.js";
 
 interface GeneratedSchema {
@@ -401,3 +401,8 @@ const SourceSchema = z.object({
     });
   });
 });
+
+it("accepts omitted RPC output so the receiving client can apply schema defaults", () => {
+  const message = { type: "plugin.rpc.invoke.response", payload: { requestId: "default-output" } };
+  expect(PluginRpcInvokeResponseSchema.safeParse(message).success).toBe(true);
+});
diff --git a/packages/relay/LICENSE b/packages/relay/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/relay/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/relay/package.json b/packages/relay/package.json
index ec1deebff7..1f83852939 100644
--- a/packages/relay/package.json
+++ b/packages/relay/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo relay for bridging daemon and client connections",
+  "license": "Apache-2.0",
   "files": [
     "dist",
     "!dist/**/*.map"
diff --git a/packages/relay/src/e2e.test.ts b/packages/relay/src/e2e.test.ts
index cbc19f57b6..9c9a8957e1 100644
--- a/packages/relay/src/e2e.test.ts
+++ b/packages/relay/src/e2e.test.ts
@@ -56,6 +56,9 @@ function spawnRelayDevServer(port: number): ChildProcess {
       wranglerCliPath,
       "dev",
       "--local",
+      // Local execution still inherits production vars; exercise the local Durable Object.
+      "--var",
+      "PASEO_RELAY_UPSTREAM:",
       "--ip",
       "127.0.0.1",
       "--port",
diff --git a/packages/relay/src/handshake-lifetime.test.ts b/packages/relay/src/handshake-lifetime.test.ts
new file mode 100644
index 0000000000..ea99005916
--- /dev/null
+++ b/packages/relay/src/handshake-lifetime.test.ts
@@ -0,0 +1,60 @@
+import { expect, it, vi } from "vitest";
+import { exportPublicKey, generateKeyPair } from "./crypto.js";
+import type { Transport } from "./encrypted-channel.js";
+import { openClientSecureChannel } from "./secure-channel.js";
+
+/** A socket whose peer never acknowledges the close handshake. */
+class UnresponsiveTransport implements Transport {
+  onmessage: Transport["onmessage"] = null;
+  onclose: Transport["onclose"] = null;
+  onerror: Transport["onerror"] = null;
+  sends = 0;
+  closing = false;
+
+  send(): void {
+    this.sends += 1;
+    if (this.closing) throw new Error("WebSocket not open (readyState=2)");
+  }
+
+  close(): void {
+    this.closing = true;
+  }
+}
+
+it.each(["client close", "handshake rejection"] as const)(
+  "stops handshake retries after %s without a socket acknowledgment",
+  async (trigger) => {
+    vi.useFakeTimers();
+    const transport = new UnresponsiveTransport();
+    const errors: Error[] = [];
+    let closed = 0;
+    try {
+      const channel = await openClientSecureChannel(transport, {
+        daemonPublicKeyB64: exportPublicKey(generateKeyPair().publicKey),
+        minimumMode: "protected",
+        events: { onerror: (error) => errors.push(error) },
+      });
+      channel.onClose(() => closed++);
+
+      // The handshake still retries while the connection is wanted.
+      await vi.advanceTimersByTimeAsync(2_000);
+      expect(transport.sends).toBe(3);
+      if (trigger === "client close") {
+        channel.close();
+      } else {
+        transport.onmessage?.({ data: JSON.stringify({ type: "e2ee_ready" }), isBinary: false });
+      }
+      await vi.advanceTimersByTimeAsync(5_000);
+
+      expect(transport.sends).toBe(3);
+      expect(errors).toHaveLength(trigger === "client close" ? 0 : 1);
+      expect(closed).toBe(1);
+      // A late socket acknowledgment does not close the channel a second time.
+      transport.onclose?.(1000, "Normal closure");
+      expect(closed).toBe(1);
+    } finally {
+      vi.clearAllTimers();
+      vi.useRealTimers();
+    }
+  },
+);
diff --git a/packages/relay/src/secure-channel.ts b/packages/relay/src/secure-channel.ts
index 760dcc49d0..49cbce1a53 100644
--- a/packages/relay/src/secure-channel.ts
+++ b/packages/relay/src/secure-channel.ts
@@ -344,8 +344,7 @@ class ClientSecureChannel implements SecureChannel {
 
   private fail(code: number, reason: string): void {
     if (this.state === "closed") return;
-    this.state = "closed";
-    this.handshake = null;
+    this.notifyClosed();
     try {
       this.transport.close(code, reason);
     } catch {
@@ -364,13 +363,12 @@ class ClientSecureChannel implements SecureChannel {
   }
 
   close(code = 1000, reason = "Normal closure"): void {
+    this.notifyClosed();
     if (this.inner) {
       this.inner.close(code, reason);
     } else {
       this.transport.close(code, reason);
     }
-    this.state = "closed";
-    this.handshake = null;
   }
 
   isOpen(): boolean {
diff --git a/packages/server/LICENSE b/packages/server/LICENSE
new file mode 100644
index 0000000000..2f5903143b
--- /dev/null
+++ b/packages/server/LICENSE
@@ -0,0 +1,211 @@
+Copyright (c) 2025-present Mohamed Boudra
+
+Portions of this software are licensed as follows:
+
+* Third-party components incorporated into Paseo remain licensed under
+  the licenses provided by their respective copyright holders.
+* Except for those third-party components, Paseo is licensed under the
+  Apache License, Version 2.0, reproduced below.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/server/package.json b/packages/server/package.json
index 0fcbacaf24..b1075aa240 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "description": "Paseo backend server",
+  "license": "Apache-2.0",
   "files": [
     "dist/server",
     "dist/src",
@@ -89,7 +90,7 @@
     "speech:transcribe:local": "tsx scripts/transcribe-local-wav.ts",
     "test": "npm run test:unit && npm run test:integration",
     "test:unit": "vitest run --fileParallelism --exclude \"**/*.e2e.test.ts\"",
-    "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"",
+    "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/create-agent-mode.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/creation-status.e2e.test.ts src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"",
     "test:hub-cli-contract": "vitest run --maxWorkers=1 src/server/hub/hub-cli-contract.test.ts",
     "test:integration:all": "npm run test:e2e",
     "test:integration:real": "vitest run real.e2e.test.ts",
@@ -101,23 +102,25 @@
     "test:e2e:real": "npm run test:integration:real",
     "test:e2e:local": "npm run test:integration:local",
     "test:e2e:relay:live": "cross-env RUN_LIVE_RELAY_E2E=1 vitest run src/server/daemon-e2e/live-relay.real.e2e.test.ts --maxWorkers=1",
-    "test:e2e:ui": "vitest --ui e2e.test.ts"
+    "test:e2e:ui": "vitest --ui e2e.test.ts",
+    "measure:diff-subscriptions": "tsx scripts/measure-diff-subscriptions.ts"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.3.246",
     "@anthropic-ai/sdk": "^0.104.2",
-    "@getpaseo/client": "0.14.0",
-    "@getpaseo/highlight": "0.14.0",
-    "@getpaseo/plugin": "0.14.0",
-    "@getpaseo/protocol": "0.14.0",
-    "@getpaseo/relay": "0.14.0",
+    "@getpaseo/client": "0.15.4",
+    "@getpaseo/highlight": "0.15.4",
+    "@getpaseo/plugin": "0.15.4",
+    "@getpaseo/protocol": "0.15.4",
+    "@getpaseo/relay": "0.15.4",
     "@isaacs/ttlcache": "^2.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@opencode-ai/sdk": "1.14.46",
     "@opencode/client": "2.0.10",
     "@xterm/addon-serialize": "0.14.0",
-    "@xterm/headless": "^6.0.0",
+    "@xterm/addon-unicode-graphemes": "0.5.0-beta.330",
+    "@xterm/headless": "6.1.0-beta.334",
     "ai": "5.0.78",
     "ajv": "^8.20.0",
     "bcryptjs": "^3.0.3",
diff --git a/packages/server/scripts/build-opencode-bridge-plugin.mjs b/packages/server/scripts/build-opencode-bridge-plugin.mjs
index 69f1e774f0..33cd3402ce 100644
--- a/packages/server/scripts/build-opencode-bridge-plugin.mjs
+++ b/packages/server/scripts/build-opencode-bridge-plugin.mjs
@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { copyFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -27,4 +27,10 @@ for (const directory of ["", "v2/"]) {
     target: "es2022",
     outfile: outputPath,
   });
+  if (directory === "v2/") {
+    await copyFile(
+      new URL("../src/server/agent/providers/opencode/v2/state.mjs", import.meta.url),
+      path.join(path.dirname(outputPath), "state.mjs"),
+    );
+  }
 }
diff --git a/packages/server/scripts/measure-diff-subscriptions.ts b/packages/server/scripts/measure-diff-subscriptions.ts
new file mode 100644
index 0000000000..e8e058708e
--- /dev/null
+++ b/packages/server/scripts/measure-diff-subscriptions.ts
@@ -0,0 +1,111 @@
+import { performance } from "node:perf_hooks";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  encodeDiffFrame,
+  DiffOpcode,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import { DiffSubscriptions } from "../src/server/diff/index.js";
+import { createFileObserver } from "../src/server/file-observer/index.js";
+import { runGitCommand } from "../src/utils/run-git-command.js";
+import { parseAndHighlightDiff } from "../src/server/utils/diff-highlighter.js";
+import { validateWSOutboundMessage } from "@getpaseo/protocol/validation/ws-outbound";
+
+const cwd = resolve(import.meta.dirname, "../../..");
+const artifacts = resolve(cwd, ".artifacts/diff-subscription");
+await mkdir(artifacts, { recursive: true });
+const pinnedHead = "3ed57e9dd";
+const observer = createFileObserver();
+const engine = new DiffSubscriptions({
+  async requestWorkingTreeWatch(root, changed) {
+    const watch = await observer.subscribe(root, () => changed(), {
+      ignore: [resolve(root, ".git")],
+    });
+    return {
+      repoRoot: root,
+      unsubscribe: async () => {
+        await watch.unsubscribe();
+      },
+    };
+  },
+});
+try {
+  for (const count of [1, 30]) {
+    const [base, head] = await Promise.all([
+      runGitCommand(["rev-parse", `${pinnedHead}~${count}`], { cwd }),
+      runGitCommand(["rev-parse", pinnedHead], { cwd }),
+    ]);
+    const started = performance.now();
+    const frames: DiffFrame[] = [];
+    const encoded: Uint8Array[] = [];
+    const subscription = await engine.subscribe(
+      {
+        cwd,
+        base: { kind: "rev", rev: base.stdout.trim() },
+        head: { kind: "rev", rev: head.stdout.trim() },
+      },
+      async (frame) => {
+        frames.push(frame);
+        encoded.push(encodeDiffFrame(frame));
+      },
+    );
+    await subscription.start();
+    const coldMs = performance.now() - started;
+    await subscription.release();
+    const raw = await runGitCommand(["diff", base.stdout.trim(), head.stdout.trim()], {
+      cwd,
+      maxOutputBytes: 50 * 1024 * 1024,
+    });
+    const contentAt = async (sha: string, path: string) => {
+      const result = await runGitCommand(["show", `${sha}:${path}`], {
+        cwd,
+        acceptExitCodes: [0, 128],
+      });
+      return result.exitCode === 0 ? result.stdout : null;
+    };
+    const legacyFiles = await parseAndHighlightDiff(raw.stdout, cwd, {
+      getOldFileContent: (file) => contentAt(base.stdout.trim(), file.path),
+      getNewFileContent: (file) => contentAt(head.stdout.trim(), file.path),
+    });
+    const legacy = JSON.stringify({
+      type: "session",
+      message: {
+        type: "checkout_diff_update",
+        payload: { cwd, subscriptionId: "benchmark", files: legacyFiles, error: null },
+      },
+    });
+    const parseStart = performance.now();
+    const validation = validateWSOutboundMessage(JSON.parse(legacy));
+    if (!validation.success) throw validation.error;
+    const jsonParseValidationMs = performance.now() - parseStart;
+    const begin = frames.find((frame) => frame.opcode === DiffOpcode.Begin);
+    const end = frames.findLast((frame) => frame.opcode === DiffOpcode.End);
+    if (!begin || begin.opcode !== DiffOpcode.Begin || !end || end.opcode !== DiffOpcode.End)
+      throw new Error("Revision was not delimited");
+    if (end.error) throw new Error(end.error.message);
+    const metrics = {
+      pinnedHead: head.stdout.trim(),
+      count,
+      files: begin.entries.length,
+      rawPatchBytes: Buffer.byteLength(raw.stdout),
+      encodedBytes: encoded.reduce((sum, bytes) => sum + bytes.length, 0),
+      legacyJsonBytes: Buffer.byteLength(legacy),
+      coldMs,
+      jsonParseValidationMs,
+      omitted: end.omitted,
+    };
+    console.log(JSON.stringify(metrics));
+    await writeFile(
+      resolve(artifacts, `corpus-${count}.json`),
+      JSON.stringify({
+        metrics,
+        legacy,
+        frames: encoded.map((bytes) => Buffer.from(bytes).toString("base64")),
+      }),
+    );
+  }
+} finally {
+  await engine.close();
+  await observer.close();
+}
diff --git a/packages/server/scripts/measure-file-observer.test.ts b/packages/server/scripts/measure-file-observer.test.ts
index 345da462bb..a784a9fbdd 100644
--- a/packages/server/scripts/measure-file-observer.test.ts
+++ b/packages/server/scripts/measure-file-observer.test.ts
@@ -8,10 +8,10 @@ import { expect, test } from "vitest";
 
 const execFileAsync = promisify(execFile);
 
-// Linux delivers the existing inventory as one batch. Other backends have
-// different startup semantics, so they do not exercise this regression.
+// The Linux backend scans the existing inventory at startup without reporting
+// it. Other backends have different startup semantics.
 test.skipIf(process.platform !== "linux").each(["healthy", "directory-churn"])(
-  "%s benchmark collects a startup batch larger than the argument limit",
+  "%s benchmark over a large pre-populated tree reports only later edits",
   async (mode) => {
     const temporaryRoot = await mkdtemp(join(tmpdir(), "paseo-watch-benchmark-test-"));
     try {
@@ -47,7 +47,7 @@ test.skipIf(process.platform !== "linux").each(["healthy", "directory-churn"])(
         },
       );
       const measurement = JSON.parse(stdout);
-      expect(measurement.startupEvents).toBe(40_000);
+      expect(measurement.startupEvents).toBe(0);
       expect(measurement.deliveredEvents).toBeGreaterThan(measurement.startupEvents);
       expect(measurement.missedTrackedPaths).toBe(0);
       expect(measurement.ignoredEvents).toBe(0);
diff --git a/packages/server/src/server/agent/activity-curator.test.ts b/packages/server/src/server/agent/activity-curator.test.ts
index 4e9ce49528..6a1d85bcf0 100644
--- a/packages/server/src/server/agent/activity-curator.test.ts
+++ b/packages/server/src/server/agent/activity-curator.test.ts
@@ -454,6 +454,34 @@ second line'`,
     ).toThrow("Fork from a later completed response");
   });
 
+  it("forks from a checkpoint when a plugin card was updated after it", () => {
+    const card = (seq: number, turns: number) =>
+      row(seq, {
+        type: "plugin",
+        id: "memory-receipt",
+        pluginId: "memorise",
+        kind: "memory-receipt",
+        version: 1,
+        data: { turns },
+      });
+    const result = buildAgentForkContextAttachment({
+      boundaryMessageId: "assistant-1",
+      rows: [
+        row(1, { type: "user_message", text: "First question", messageId: "user-1" }),
+        card(2, 1),
+        row(3, { type: "assistant_message", text: "First answer.", messageId: "assistant-1" }),
+        row(4, { type: "user_message", text: "Second question", messageId: "user-2" }),
+        row(5, { type: "assistant_message", text: "Second answer.", messageId: "assistant-2" }),
+        card(6, 2),
+      ],
+    });
+
+    expect(result.attachment.text).toContain("[User] First question");
+    expect(result.attachment.text).toContain("[Assistant] First answer.");
+    expect(result.attachment.text).not.toContain("Second question");
+    expect(result.attachment.text).not.toContain("memory-receipt");
+  });
+
   it("selects a synthetic assistant error by its timeline cursor", () => {
     const result = buildAgentForkContextAttachment({
       cursorBoundary: {
diff --git a/packages/server/src/server/agent/activity-curator.ts b/packages/server/src/server/agent/activity-curator.ts
index 2a7cbff5e6..a0c537254a 100644
--- a/packages/server/src/server/agent/activity-curator.ts
+++ b/packages/server/src/server/agent/activity-curator.ts
@@ -13,6 +13,12 @@ const MAX_TOOL_SUMMARY_CHARS = 200;
 const MAX_FORK_CONTEXT_CHARS = 100_000;
 const MAX_FORK_METADATA_CHARS = 1_000;
 const FORK_HISTORY_OMITTED = "[Earlier chat history omitted]\n";
+// A fork copies only these kinds, so only they can make a checkpoint stale.
+const FORK_CONTEXT_KINDS: readonly AgentTimelineItem["type"][] = [
+  "user_message",
+  "assistant_message",
+  "tool_call",
+];
 
 interface ActivityCuratorOptions {
   maxItems?: number;
@@ -269,7 +275,14 @@ function selectForkContextRows(input: {
     );
   }
   const boundarySeq = projectedRows[boundaryIndex].seqEnd;
-  if (projectedRows.some((row) => row.seqStart <= boundarySeq && row.seqEnd > boundarySeq)) {
+  if (
+    projectedRows.some(
+      (row) =>
+        FORK_CONTEXT_KINDS.includes(row.item.type) &&
+        row.seqStart <= boundarySeq &&
+        row.seqEnd > boundarySeq,
+    )
+  ) {
     throw new Error(
       "This checkpoint changed after it was created. Fork from a later completed response instead.",
     );
@@ -349,7 +362,7 @@ export function buildAgentForkContextAttachment(input: {
   const entries = curateProjectedActivityEntries(selected.items, {
     maxItems: 0,
     labelAssistantMessages: true,
-    includeKinds: ["user_message", "assistant_message", "tool_call"],
+    includeKinds: FORK_CONTEXT_KINDS,
     includeExternalToolInput: false,
   });
   const metadata = { agentTitle: input.agentTitle, cwd: input.cwd };
diff --git a/packages/server/src/server/agent/agent-loading.test.ts b/packages/server/src/server/agent/agent-loading.test.ts
index 9df22ba26b..d6a53fb1bc 100644
--- a/packages/server/src/server/agent/agent-loading.test.ts
+++ b/packages/server/src/server/agent/agent-loading.test.ts
@@ -1,11 +1,12 @@
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { expect, test } from "vitest";
+import { expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import { AgentManager } from "./agent-manager.js";
 import { AgentNotFoundError, ensureAgentLoaded, loadAgentHistory } from "./agent-loading.js";
+import { startAgentRun } from "./agent-prompt.js";
 import { AgentStorage } from "./agent-storage.js";
 import type {
   AgentClient,
@@ -16,6 +17,7 @@ import type {
   AgentSessionConfig,
 } from "./agent-sdk-types.js";
 import { createTestAgentClients } from "../test-utils/fake-agent-client.js";
+import { createDaemonTestContext } from "../test-utils/daemon-test-context.js";
 
 test("loads archived records for history and active records with the interactive default", async () => {
   const root = await mkdtemp(path.join(tmpdir(), "agent-loading-purpose-"));
@@ -141,51 +143,82 @@ test("resuming a stored agent keeps its unread flag and its last-activity time",
   }
 });
 
-test("loads an archived agent's history after its working directory is removed", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "agent-loading-missing-cwd-"));
-  const worktree = path.join(root, "managed-worktree");
-  await mkdir(worktree, { recursive: true });
+test("reopening an agent with no resumable session keeps a metadata write that overlaps it", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agent-loading-handleless-metadata-"));
   const logger = createTestLogger();
   const storage = new AgentStorage(path.join(root, "agents"), logger);
+  const base = createTestAgentClients().codex!;
+  // A provider whose sessions leave nothing to resume (Codex before its first prompt).
+  const client: AgentClient = {
+    provider: base.provider,
+    capabilities: base.capabilities,
+    createSession: async (config, context) => {
+      const session = await base.createSession(config, context);
+      session.describePersistence = () => null;
+      const runtimeInfo = session.getRuntimeInfo.bind(session);
+      session.getRuntimeInfo = async () => {
+        const { sessionId: _sessionId, ...rest } = await runtimeInfo();
+        return rest;
+      };
+      return session;
+    },
+    resumeSession: (handle, overrides, context, options) =>
+      base.resumeSession(handle, overrides, context, options),
+    fetchCatalog: (options) => base.fetchCatalog(options),
+    isAvailable: () => base.isAvailable(),
+  };
+  let holdCreate: Promise<void> | null = null;
+  let createEntered!: () => void;
+  const entered = new Promise<void>((resolve) => {
+    createEntered = resolve;
+  });
   const manager = new AgentManager({
-    clients: createTestAgentClients(),
+    clients: { codex: client },
     registry: storage,
     logger,
+    pluginLifecycle: {
+      emit: () => {},
+      before: async (name, request) => {
+        if (name === "agent.create.before" && holdCreate) {
+          createEntered();
+          await holdCreate;
+        }
+        return request;
+      },
+    },
   });
-
-  const agentId = "00000000-0000-4000-8000-000000000501";
+  const agentId = "00000000-0000-4000-8000-000000000701";
 
   try {
-    const agent = await manager.createAgent({ provider: "codex", cwd: worktree }, agentId, {
-      workspaceId: "workspace-worktree",
+    await manager.createAgent({ provider: "codex", cwd: root }, agentId, {
+      workspaceId: "workspace-a",
+      metadata: { first: 1 },
     });
-    // Archive once the turn has finished, so the reply is part of the history archive keeps.
-    await manager.runAgent(agent.id, "what did you change");
-    await manager.archiveAgent(agent.id);
-    await manager.closeAgent(agent.id);
+    await manager.closeAgent(agentId);
     await manager.flush();
     await storage.flush();
+    expect((await storage.get(agentId))?.persistence ?? null).toBeNull();
 
-    // Archiving the workspace removes the worktree it owned. The agent's history is
-    // persisted and reading it must not depend on that directory still being there.
-    await rm(worktree, { recursive: true, force: true });
-
-    const loaded = await ensureAgentLoaded(agentId, {
+    // The reopen is held in its create hook while a plugin writes metadata to the same agent.
+    let release!: () => void;
+    holdCreate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const reopened = ensureAgentLoaded(agentId, {
       agentManager: manager,
       agentStorage: storage,
       logger,
     });
+    await entered;
+    const saved = manager.setMetadata(agentId, { second: 2 });
+    release();
 
-    expect(loaded.id).toBe(agentId);
-    // Archive kept the transcript, so the reply the agent gave before the worktree went away
-    // is still readable from the resumed agent.
-    const replies = (await manager.getTimeline(agentId)).filter(
-      (item) => item.type === "assistant_message",
-    );
-    expect(replies.length).toBeGreaterThan(0);
-    expect(replies.every((item) => item.type === "assistant_message" && item.text.length > 0)).toBe(
-      true,
-    );
+    expect(await saved).toEqual({ first: 1, second: 2 });
+    await reopened;
+    expect(manager.getAgent(agentId)?.metadata).toEqual({ first: 1, second: 2 });
+    await manager.flush();
+    await storage.flush();
+    expect((await storage.get(agentId))?.metadata).toEqual({ first: 1, second: 2 });
   } finally {
     await manager.closeAgent(agentId).catch(() => undefined);
     await manager.flush().catch(() => undefined);
@@ -296,3 +329,250 @@ test("reads stored history without starting or requiring the provider, and impor
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test.each([false, true])(
+  "loads history after its working directory is removed (archived: %s)",
+  async (archived) => {
+    const root = await mkdtemp(path.join(tmpdir(), "agent-loading-missing-cwd-"));
+    const worktree = path.join(root, "managed-worktree");
+    await mkdir(worktree, { recursive: true });
+    const logger = createTestLogger();
+    const storage = new AgentStorage(path.join(root, "agents"), logger);
+    const manager = new AgentManager({
+      clients: createTestAgentClients(),
+      registry: storage,
+      logger,
+    });
+
+    const agentId = "00000000-0000-4000-8000-000000000501";
+
+    try {
+      const agent = await manager.createAgent({ provider: "codex", cwd: worktree }, agentId, {
+        workspaceId: "workspace-worktree",
+      });
+      await startAgentRun(manager, agent.id, "what did you change", logger, {});
+      // Dispatching a run does not finish it: the provider appends the reply to its
+      // history afterwards, and the turn is finalized only once that append lands.
+      // Archive after the turn is finalized so the transcript this test reads back is
+      // already on disk when the worktree goes away.
+      const finished = await manager.waitForAgentEvent(agent.id);
+      expect(finished.status).toBe("idle");
+      if (archived) await manager.archiveAgent(agent.id);
+      await manager.closeAgent(agent.id);
+      await manager.flush();
+      await storage.flush();
+
+      // Archiving the workspace removes the worktree it owned. The agent's history is
+      // persisted and reading it must not depend on that directory still being there.
+      await rm(worktree, { recursive: true, force: true });
+
+      const loaded = await ensureAgentLoaded(agentId, {
+        agentManager: manager,
+        agentStorage: storage,
+        logger,
+        purpose: "history",
+      });
+
+      expect(loaded.id).toBe(agentId);
+      // The manager kept the transcript when the agent closed, so the reply the agent gave
+      // before the worktree went away is still readable.
+      const replies = (await manager.getTimeline(agentId)).filter(
+        (item) => item.type === "assistant_message",
+      );
+      expect(replies.length).toBeGreaterThan(0);
+      expect(
+        replies.every((item) => item.type === "assistant_message" && item.text.length > 0),
+      ).toBe(true);
+    } finally {
+      await manager.closeAgent(agentId).catch(() => undefined);
+      await manager.flush().catch(() => undefined);
+      await storage.flush().catch(() => undefined);
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+);
+
+test("timeline requests read unarchived stored history with a deleted cwd", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = await mkdtemp(path.join(tmpdir(), "timeline-deleted-cwd-"));
+  try {
+    const agent = await ctx.client.createAgent({ provider: "codex", cwd });
+    await ctx.client.sendMessage(agent.id, "remember this conversation");
+    await ctx.client.waitForFinish(agent.id, 15000);
+    const before = await ctx.client.fetchAgentTimeline(agent.id);
+    await ctx.daemon.daemon.agentManager.closeAgent(agent.id);
+    await ctx.daemon.daemon.agentManager.flush();
+    await rm(cwd, { recursive: true, force: true });
+    const after = await ctx.client.fetchAgentTimeline(agent.id);
+    expect(after.entries).toEqual(before.entries);
+    expect(after.entries.length).toBeGreaterThan(0);
+    await expect(ctx.client.sendMessage(agent.id, "continue")).rejects.toThrow(
+      "Working directory does not exist",
+    );
+    await expect(ctx.client.createAgent({ provider: "codex", cwd })).rejects.toThrow(
+      "Working directory does not exist",
+    );
+    await mkdir(cwd);
+    await ctx.client.sendMessage(agent.id, "continue after restoring directory");
+    expect((await ctx.client.waitForFinish(agent.id, 15000)).status).toBe("idle");
+  } finally {
+    await ctx.cleanup();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test("timeline reads of stored history leave the provider closed until a prompt resumes it interactively", async () => {
+  const clients = createTestAgentClients();
+  const base = clients.codex!;
+  const purposes: Array<AgentResumeSessionOptions | undefined> = [];
+  const client: AgentClient = {
+    provider: base.provider,
+    capabilities: base.capabilities,
+    createSession: (config, context) => base.createSession(config, context),
+    resumeSession: (handle, overrides, context, options) => {
+      purposes.push(options);
+      return base.resumeSession(handle, overrides, context, options);
+    },
+    fetchCatalog: (options) => base.fetchCatalog(options),
+    isAvailable: () => base.isAvailable(),
+  };
+  const ctx = await createDaemonTestContext({ agentClients: { codex: client } });
+  const cwd = await mkdtemp(path.join(tmpdir(), "timeline-interactive-"));
+  try {
+    const agent = await ctx.client.createAgent({ provider: "codex", cwd });
+    await ctx.daemon.daemon.agentManager.closeAgent(agent.id);
+    await ctx.client.fetchAgentTimeline(agent.id);
+    // The manager serves the stored timeline itself, so the read resumes no provider session.
+    expect(purposes).toEqual([]);
+    await ctx.client.sendMessage(agent.id, "continue after opening history");
+    expect((await ctx.client.waitForFinish(agent.id, 15000)).status).toBe("idle");
+    const timeline = await ctx.client.fetchAgentTimeline(agent.id);
+    expect(timeline.entries.length).toBeGreaterThan(0);
+    await ctx.daemon.daemon.agentManager.closeAgent(agent.id);
+    await rm(cwd, { recursive: true, force: true });
+    await ctx.client.fetchAgentTimeline(agent.id);
+    await mkdir(cwd);
+    const manager = ctx.daemon.daemon.agentManager;
+    await Promise.all([
+      manager.tryRunOutOfBand(agent.id, "first prompt"),
+      manager.tryRunOutOfBand(agent.id, "second prompt"),
+    ]);
+    // The prompt resumed once, and the concurrent prompts after the removed-cwd read share one
+    // resume. Every resume is interactive, so no history session needs replacing.
+    expect(purposes).toEqual([{ purpose: "interactive" }, { purpose: "interactive" }]);
+  } finally {
+    await ctx.cleanup();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test.each(["mode", "thinking", "rewind"])(
+  "restored OMP history accepts %s before starting an interactive turn",
+  async (setting) => {
+    const { OmpAgentClient } = await import("./providers/omp/agent.js");
+    const { FakeOmp } = await import("./providers/omp/test-utils/fake-omp.js");
+    const { sendPreparedPromptToAgent } = await import("./agent-prompt.js");
+    const root = await mkdtemp(path.join(tmpdir(), "history-mode-"));
+    const cwd = path.join(root, "removed-worktree");
+    const sessionFile = path.join(root, "session.jsonl");
+    await writeFile(
+      sessionFile,
+      [
+        { type: "session", id: "root", parentId: null },
+        {
+          type: "message",
+          id: "user-1",
+          parentId: "root",
+          message: { role: "user", content: "saved question" },
+        },
+      ]
+        .map((entry) => JSON.stringify(entry))
+        .join("\n") + "\n",
+    );
+    const logger = createTestLogger();
+    const storage = new AgentStorage(path.join(root, "agents"), logger);
+    const runtime = new FakeOmp();
+    const manager = new AgentManager({
+      clients: {
+        omp: new OmpAgentClient({
+          logger,
+          runtime,
+          runtimeSettings: { command: { mode: "replace", argv: [process.execPath] } },
+        }),
+      },
+      registry: storage,
+      logger,
+    });
+    const agentId = "00000000-0000-4000-8000-000000000601";
+    const now = new Date().toISOString();
+    try {
+      await storage.upsert({
+        id: agentId,
+        provider: "omp",
+        cwd,
+        createdAt: now,
+        updatedAt: now,
+        labels: {},
+        lastStatus: "closed",
+        archivedAt: null,
+        persistence: {
+          provider: "omp",
+          sessionId: "history-mode",
+          nativeHandle: sessionFile,
+          metadata: { cwd },
+        },
+      });
+      await ensureAgentLoaded(agentId, {
+        agentManager: manager,
+        agentStorage: storage,
+        logger,
+        purpose: "history",
+      });
+      expect(
+        runtime.recordedLaunches.filter((launch) => launch.session === sessionFile),
+      ).toHaveLength(0);
+      await mkdir(cwd);
+      if (setting === "rewind") {
+        await manager.rewind(agentId, "user-1", "conversation");
+        expect(runtime.latestSession().branchRequests).toEqual(["user-1"]);
+      }
+      if (setting === "thinking") {
+        await manager.setAgentThinkingOption(agentId, "high");
+        expect(manager.getAgent(agentId)?.config.thinkingOptionId).toBe("high");
+        expect(runtime.latestSession().setThinkingLevelRequests).toContain("high");
+      }
+      await sendPreparedPromptToAgent({
+        agentManager: manager,
+        agentStorage: storage,
+        agentId,
+        logger,
+        prompt: "continue",
+        sessionMode: "full",
+      });
+      expect(
+        runtime.recordedLaunches.filter((launch) => launch.session === sessionFile),
+      ).toHaveLength(1);
+      expect(manager.getAgent(agentId)?.currentModeId).toBe("full");
+      // The run reads its timeline before the provider starts the turn.
+      await vi.waitFor(() =>
+        expect(runtime.latestSession().prompts).toEqual([
+          expect.objectContaining({ message: "continue" }),
+        ]),
+      );
+      runtime.latestSession().finishTurn();
+      await manager.waitForAgentEvent(agentId);
+      await manager.archiveAgent(agentId);
+      await manager.closeAgent(agentId);
+      await ensureAgentLoaded(agentId, { agentManager: manager, agentStorage: storage, logger });
+      const launchesBeforeModeChange = runtime.recordedLaunches.length;
+      await expect(manager.setAgentMode(agentId, "full")).rejects.toThrow("Agent is archived");
+      expect(runtime.recordedLaunches).toHaveLength(launchesBeforeModeChange);
+    } finally {
+      await manager.closeAgent(agentId).catch(() => undefined);
+      await manager.flush();
+      await storage.flush();
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+  30000,
+);
diff --git a/packages/server/src/server/agent/agent-loading.ts b/packages/server/src/server/agent/agent-loading.ts
index 245da8840e..903d101e4e 100644
--- a/packages/server/src/server/agent/agent-loading.ts
+++ b/packages/server/src/server/agent/agent-loading.ts
@@ -5,7 +5,6 @@ import type { AgentManager, ManagedAgent } from "./agent-manager.js";
 import type { AgentStorage, StoredAgentRecord } from "./agent-storage.js";
 import {
   buildConfigOverrides,
-  buildSessionConfig,
   extractAttention,
   extractTimestamps,
   isStoredAgentProviderAvailable,
@@ -23,7 +22,7 @@ const pendingAgentInitializations = new Map<string, Promise<ManagedAgent>>();
 
 export type AgentLoaderManager = Pick<
   AgentManager,
-  "createAgent" | "getAgent" | "getRegisteredProviderIds" | "resumeAgentFromPersistence"
+  "createAgentFromRecord" | "getAgent" | "getRegisteredProviderIds" | "resumeAgentFromPersistence"
 > &
   Partial<Pick<AgentManager, "waitForAgentClose">>;
 
@@ -31,6 +30,7 @@ export interface EnsureAgentLoadedDeps {
   agentManager: AgentLoaderManager;
   agentStorage: AgentStorage;
   validProviders?: Iterable<AgentProvider>;
+  purpose?: "history" | "interactive";
   logger: Logger;
 }
 
@@ -139,25 +139,15 @@ export async function ensureAgentLoaded(
         buildConfigOverrides(record),
         agentId,
         { ...extractTimestamps(record), attention: extractAttention(record) },
-        record.archivedAt ? { purpose: "history" } : undefined,
+        deps.purpose ? { purpose: deps.purpose } : undefined,
       );
       deps.logger.info({ agentId, provider: record.provider }, "Agent resumed from persistence");
     } else {
       // No provider handle to resume: this starts the agent's first session rather than
       // bringing one back, so it stamps activity and carries no stored attention. Records
-      // without a handle never got far enough to accumulate either.
-      const config = buildSessionConfig(record, {
-        validProviders,
-      });
-      if (!config) {
-        throw new Error(`Agent ${agentId} references unavailable provider '${record.provider}'`);
-      }
-      snapshot = await deps.agentManager.createAgent(config, agentId, {
-        labels: record.labels,
-        workspaceId: record.workspaceId,
-        owner: record.owner,
-        env: record.launchEnv,
-      });
+      // without a handle never got far enough to accumulate either. The manager rereads the
+      // record inside the agent's lane, so a write that lands after this read is not lost.
+      snapshot = await deps.agentManager.createAgentFromRecord(agentId);
       deps.logger.info({ agentId, provider: record.provider }, "Agent created from stored config");
     }
 
diff --git a/packages/server/src/server/agent/agent-manager.test.ts b/packages/server/src/server/agent/agent-manager.test.ts
index 07d6514b0c..8ee8130012 100644
--- a/packages/server/src/server/agent/agent-manager.test.ts
+++ b/packages/server/src/server/agent/agent-manager.test.ts
@@ -6,7 +6,7 @@ import {
 } from "./agent-messages/index.js";
 import { expect, test, vi, onTestFinished } from "vitest";
 import { spawn } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -20,11 +20,12 @@ import {
   type AgentManagerEvent,
   type ManagedAgent,
 } from "./agent-manager.js";
-import { AgentStorage } from "./agent-storage.js";
+import { AgentStorage, parseStoredAgentRecord } from "./agent-storage.js";
 import { AgentTimeline } from "./timeline/index.js";
 import { DeferredTimelineBackend } from "./timeline/testing.js";
 import { limitAgentTimelineItemContent } from "./agent-timeline-content.js";
-import { toAgentPayload } from "./agent-projections.js";
+import { buildStoredAgentPayload, toAgentPayload } from "./agent-projections.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { projectTimelineRows } from "./timeline-projection.js";
 import { getOpenAgentTabLabel, PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
 import { startAgentRun } from "./agent-prompt.js";
@@ -34,7 +35,8 @@ import type { StoredAgentRecord } from "./agent-storage.js";
 import type {
   AgentClient,
   AgentCreateSessionOptions,
-  AgentFeature,
+  AgentDraftControls,
+  AgentOptionControl,
   AgentLaunchContext,
   AgentPromptInput,
   AgentProvider,
@@ -53,6 +55,12 @@ import type {
 } from "./agent-sdk-types.js";
 import type { PaseoToolCatalog } from "./tools/types.js";
 import type { ProviderDefinition } from "./provider-registry.js";
+import { mergeProviderOptions } from "./provider-options.js";
+
+import { OpenCodeV2AgentClient } from "./providers/opencode/v2/agent.js";
+import { CursorACPAgentClient } from "./providers/cursor-acp-agent.js";
+import { fileURLToPath } from "node:url";
+import { V2Harness } from "./providers/opencode/test-utils/v2-harness.js";
 
 const DESKTOP_OPEN_AGENT_TAB_LABEL = getOpenAgentTabLabel("desktop-client");
 const MOBILE_OPEN_AGENT_TAB_LABEL = getOpenAgentTabLabel("mobile-client");
@@ -111,13 +119,8 @@ const TEST_CAPABILITIES = {
   supportsToolInvocations: false,
 } as const;
 
-function createFeature(args: { id: string; label: string; value: boolean }): AgentFeature {
-  return {
-    type: "toggle",
-    id: args.id,
-    label: args.label,
-    value: args.value,
-  };
+function createControl(args: { key: string; label: string }): AgentOptionControl {
+  return { type: "toggle", key: args.key, label: args.label };
 }
 
 function expectArchivedAgentRecord(
@@ -395,7 +398,7 @@ class TestAgentSession implements AgentSession {
 
   async startTurn(): Promise<{ turnId: string }> {
     this.interrupted = false;
-    const turnId = `turn-${++this.turnIdCounter}`;
+    const turnId = `turn-${this.id}-${++this.turnIdCounter}`;
     // Use setTimeout so events arrive after the caller sets up the foreground waiter
     setTimeout(() => {
       this.pushEvent({ type: "turn_started", provider: this.provider, turnId });
@@ -599,6 +602,98 @@ async function startAndSteerThroughManager(
   return { manager, agentId: agent.id, workdir };
 }
 
+test("stops an OpenCode execution already active when its conversation is reopened", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-opencode-resume-"));
+  onTestFinished(() => rmSync(workdir, { recursive: true, force: true }));
+  const harness = new V2Harness();
+  harness.info.location.directory = workdir;
+  harness.startExecution();
+  const client = new OpenCodeV2AgentClient({ logger, runtime: harness.runtime });
+  const manager = new AgentManager({ clients: { opencode: client }, logger });
+  const agent = await manager.resumeAgentFromPersistence({
+    provider: "opencode",
+    sessionId: "session",
+    nativeHandle: "session",
+    metadata: { cwd: workdir },
+  });
+  try {
+    expect(await manager.cancelAgentRun(agent.id)).toEqual({ status: "settled" });
+    expect(harness.active).toBe(false);
+    for await (const _event of manager.streamAgent(agent.id, "continue after restart")) {
+      // Drain the next turn through the same interface used by callers.
+    }
+    expect(harness.prompts).toEqual(["continue after restart"]);
+  } finally {
+    await manager.closeAgent(agent.id);
+    await client.shutdown();
+  }
+});
+
+test("a completed OpenCode model switch does not depend on another session read", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-opencode-model-"));
+  const harness = new V2Harness();
+  harness.info.location.directory = workdir;
+  harness.info.model = { providerID: "provider", id: "source" };
+  let observationUnavailable = false;
+  harness.api.model.list = async () => ({
+    location: { directory: workdir },
+    data: [
+      {
+        providerID: "provider",
+        id: "target",
+        modelID: "target",
+        name: "Target",
+        capabilities: { tools: true, input: ["text"], output: ["text"] },
+        enabled: true,
+        variants: [],
+        time: { released: 1 },
+        cost: [],
+        status: "active",
+        limit: { context: 200000, output: 10000 },
+      },
+    ],
+  });
+  harness.api.session.switchModel = async ({ model }) => {
+    harness.info.model = model;
+    observationUnavailable = true;
+  };
+  harness.api.session.get = async () => {
+    if (observationUnavailable) throw new Error("Transport");
+    return harness.info;
+  };
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const client = new OpenCodeV2AgentClient({ logger, runtime: harness.runtime });
+  const manager = new AgentManager({ clients: { opencode: client }, registry: storage, logger });
+  const agent = await manager.resumeAgentFromPersistence({
+    provider: "opencode",
+    sessionId: "session",
+    nativeHandle: "session",
+    metadata: { cwd: workdir },
+  });
+  try {
+    await manager.setAgentModel(agent.id, "provider/target");
+    await manager.flush();
+    expect(harness.info.model?.id).toBe("target");
+    expect(manager.getAgent(agent.id)?.config.model).toBe("provider/target");
+    expect(manager.getAgent(agent.id)?.runtimeInfo?.model).toBe("provider/target");
+    const stored = await storage.get(agent.id);
+    expect(stored?.config?.model).toBe("provider/target");
+    expect(stored?.runtimeInfo?.model).toBe("provider/target");
+    expect(stored?.persistence?.metadata?.model).toBe("provider/target");
+    observationUnavailable = false;
+    for await (const _event of manager.streamAgent(agent.id, "continue after switching")) {
+      // A successful mutation leaves a usable session.
+    }
+    expect(harness.prompts).toEqual(["continue after switching"]);
+  } finally {
+    observationUnavailable = false;
+    await manager.closeAgent(agent.id);
+    await manager.flush();
+    await client.shutdown();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("commits timeline items through an injected asynchronous backend", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-timeline-store-"));
   const backend = new DeferredTimelineBackend();
@@ -1358,6 +1453,74 @@ test("orders buffered pre-steer output before an immediately accepted steer", as
   }
 });
 
+test("a steer the provider names without echoing it can be rewound to", async () => {
+  // Claude takes a steered message into the running turn without echoing it back as a user
+  // message, so the id it minted for the message reaches the manager only through the admission.
+  class SilentSteeringSession extends SteeringTestSession {
+    override readonly capabilities = {
+      ...TEST_CAPABILITIES,
+      supportsRewindFiles: true,
+    };
+    rewindMessageIds: string[] = [];
+
+    override async steerActiveTurn(
+      _prompt: AgentPromptInput,
+      options: import("./agent-sdk-types.js").SteerActiveTurnOptions,
+    ): Promise<import("./agent-sdk-types.js").SteerResult> {
+      if (options.expectedTurnId !== `active-turn-${this.startCount}`) {
+        return { status: "unavailable" };
+      }
+      return { status: "accepted", providerMessageId: `provider-${options.clientMessageId}` };
+    }
+
+    override async revertFiles({ messageId }: { messageId: string }): Promise<void> {
+      this.rewindMessageIds.push(messageId);
+    }
+  }
+  const session = new SilentSteeringSession({ provider: "codex", cwd: process.cwd() });
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-steer-rewind-"));
+  const manager = new AgentManager({
+    clients: {
+      codex: new (class extends TestAgentClient {
+        override async createSession(): Promise<AgentSession> {
+          return session;
+        }
+      })(),
+    },
+    logger,
+  });
+  let agentId: string | null = null;
+  try {
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+    agentId = agent.id;
+    const run = manager.streamAgent(agent.id, "initial");
+    void (async () => {
+      for await (const _event of run) {
+      }
+    })();
+    await manager.waitForAgentRunStart(agent.id);
+
+    await expect(
+      manager.steerAgentRun(agent.id, "steered", { clientMessageId: "steer-client" }),
+    ).resolves.toMatchObject({ status: "accepted" });
+    const row = (await manager.fetchTimeline(agent.id, { limit: 0 })).rows.find(
+      (candidate) => candidate.item.type === "user_message",
+    );
+    expect(row).toMatchObject({
+      providerMessageId: "provider-steer-client",
+      item: { text: "steered", clientMessageId: "steer-client" },
+    });
+
+    await manager.rewind(agent.id, "steer-client", "files");
+    expect(session.rewindMessageIds).toEqual(["provider-steer-client"]);
+  } finally {
+    if (agentId) await manager.closeAgent(agentId).catch(() => undefined);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("orders a concurrent replacement after a pending accepted steer", async () => {
   const entered = deferred<void>();
   const release = deferred<void>();
@@ -2420,7 +2583,7 @@ test("listDraftCommands uses explicit model config without default model fetchin
   ]);
 });
 
-test("listDraftFeatures does not start a fallback session without a model", async () => {
+test("listDraftControls does not start a fallback session without a model", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
@@ -2453,18 +2616,21 @@ test("listDraftFeatures does not start a fallback session without a model", asyn
     logger,
   });
 
-  await expect(manager.listDraftFeatures({ provider: "codex", cwd: workdir })).resolves.toEqual([]);
+  await expect(manager.listDraftControls({ provider: "codex", cwd: workdir })).resolves.toEqual({
+    controls: [],
+    options: {},
+  });
 
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
   expect(client.availabilityCalls).toBe(0);
 });
 
-test("listDraftFeatures uses client feature listing without a model", async () => {
+test("listDraftControls uses client feature listing without a model", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
-  const draftFeature = createFeature({ id: "auto_accept", label: "Auto Accept", value: false });
+  const draftControl = createControl({ key: "auto_accept", label: "Auto Accept" });
   class DraftFeatureClient extends TestAgentClient {
     fetchCatalogCalls = 0;
     createSessionCalls = 0;
@@ -2486,9 +2652,9 @@ test("listDraftFeatures uses client feature listing without a model", async () =
       return await super.createSession(config);
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
       this.featureConfigs.push(config);
-      return [draftFeature];
+      return { controls: [draftControl], options: config.providerOptions ?? {} };
     }
   }
   const client = new DraftFeatureClient();
@@ -2500,9 +2666,13 @@ test("listDraftFeatures uses client feature listing without a model", async () =
     logger,
   });
 
-  await expect(manager.listDraftFeatures({ provider: "codex", cwd: workdir })).resolves.toEqual([
-    draftFeature,
-  ]);
+  await expect(
+    manager.listDraftControls({
+      provider: "codex",
+      cwd: workdir,
+      providerOptions: { auto_accept: true },
+    }),
+  ).resolves.toEqual({ controls: [draftControl], options: { auto_accept: true } });
 
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
@@ -2511,15 +2681,28 @@ test("listDraftFeatures uses client feature listing without a model", async () =
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { auto_accept: true },
     },
   ]);
+
+  // Options without a control come back too.
+  await expect(
+    manager.listDraftControls({
+      provider: "codex",
+      cwd: workdir,
+      providerOptions: { auto_accept: true, sandbox_mode: "workspace-write" },
+    }),
+  ).resolves.toEqual({
+    controls: [draftControl],
+    options: { auto_accept: true, sandbox_mode: "workspace-write" },
+  });
 });
 
-test("listDraftFeatures uses explicit model config without default model fetching", async () => {
+test("listDraftControls uses explicit model config without default model fetching", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-features-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
-  const draftFeature = createFeature({ id: "fast_mode", label: "Fast mode", value: false });
+  const draftControl = createControl({ key: "web_search", label: "Fast mode" });
   class DraftFeatureClient extends TestAgentClient {
     fetchCatalogCalls = 0;
     createSessionCalls = 0;
@@ -2535,9 +2718,9 @@ test("listDraftFeatures uses explicit model config without default model fetchin
       return await super.createSession(config);
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
       this.featureConfigs.push(config);
-      return [draftFeature];
+      return { controls: [draftControl], options: config.providerOptions ?? {} };
     }
   }
   const client = new DraftFeatureClient();
@@ -2549,13 +2732,13 @@ test("listDraftFeatures uses explicit model config without default model fetchin
     logger,
   });
 
-  const features = await manager.listDraftFeatures({
+  const draft = await manager.listDraftControls({
     provider: "codex",
     cwd: workdir,
     model: "gpt-5.4",
   });
 
-  expect(features).toEqual([draftFeature]);
+  expect(draft).toEqual({ controls: [draftControl], options: {} });
   expect(client.fetchCatalogCalls).toBe(0);
   expect(client.createSessionCalls).toBe(0);
   expect(client.featureConfigs).toEqual([
@@ -2567,6 +2750,60 @@ test("listDraftFeatures uses explicit model config without default model fetchin
   ]);
 });
 
+test("listDraftControls reports the Fast selection a fresh Cursor draft opens with", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-draft-cursor-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const fakeAgentPath = fileURLToPath(
+    new URL("./providers/test-utils/fake-acp-agent.mjs", import.meta.url),
+  );
+  const scenario = {
+    options: [
+      {
+        id: "fast",
+        name: "Fast",
+        type: "select",
+        currentValue: "true",
+        options: [
+          { value: "false", name: "Off" },
+          { value: "true", name: "Fast" },
+        ],
+      },
+    ],
+  };
+  // The registry maps "cursor" onto the generic ACP provider id; this manager has no registry.
+  const client = new CursorACPAgentClient({
+    logger,
+    command: [process.execPath, fakeAgentPath, JSON.stringify(scenario)],
+  });
+  const manager = new AgentManager({ clients: { acp: client }, registry: storage, logger });
+  const controls = [
+    expect.objectContaining({ type: "toggle", key: "auto_accept" }),
+    expect.objectContaining({
+      type: "select",
+      key: "fast",
+      choices: [
+        { value: "false", label: "Off" },
+        { value: "true", label: "Fast" },
+      ],
+    }),
+  ];
+
+  // Nobody set Fast, so the draft shows the value the agent opens with.
+  await expect(manager.listDraftControls({ provider: "acp", cwd: workdir })).resolves.toEqual({
+    controls,
+    options: { fast: "true" },
+  });
+
+  // A set value stands over the probe's reading.
+  await expect(
+    manager.listDraftControls({
+      provider: "acp",
+      cwd: workdir,
+      providerOptions: { fast: "false" },
+    }),
+  ).resolves.toEqual({ controls, options: { fast: "false" } });
+});
+
 test("createAgent injects daemon append system prompt at runtime only", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
   const storagePath = join(workdir, "agents");
@@ -2857,6 +3094,53 @@ test("closing during reload leaves the replacement closed", async () => {
   }
 });
 
+test("every failed reload raises error attention, replacing unread finished attention", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-reload-error-attention-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const client = new HeldReloadCloseClient();
+  const attentionReasons: Array<"finished" | "error" | "permission"> = [];
+  const manager = new AgentManager({
+    clients: { codex: client },
+    registry: storage,
+    logger,
+    rescueTimeouts: { reloadSessionCloseMs: 10 },
+    onAgentAttention: ({ reason }) => attentionReasons.push(reason),
+  });
+  try {
+    const created = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+    await manager.markAgentUnread(created.id);
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      attentionReason: "finished",
+    });
+
+    await expect(manager.reloadAgentSession(created.id)).rejects.toThrow("Timed out closing");
+
+    expect(manager.getAgent(created.id)?.lifecycle).toBe("error");
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    expect(attentionReasons).toEqual(["error"]);
+
+    await manager.clearAgentAttention(created.id);
+    await expect(manager.reloadAgentSession(created.id)).rejects.toThrow("Timed out closing");
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    expect(attentionReasons).toEqual(["error", "error"]);
+
+    client.finishClosing();
+    await manager.closeAgent(created.id);
+  } finally {
+    client.finishClosing();
+    await storage.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("retrying a timed-out reload waits for the original close to finish", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-reload-late-close-"));
   const storage = new AgentStorage(join(workdir, "agents"), logger);
@@ -3295,6 +3579,78 @@ test.each([
   },
 );
 
+test("createAgent and resume give the agent its workspace id", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-workspace-env-"));
+  const storagePath = join(workdir, "agents");
+  const storage = new AgentStorage(storagePath, logger);
+
+  class CaptureClient extends TestAgentClient {
+    createLaunchContext: AgentLaunchContext | undefined;
+    resumeLaunchContext: AgentLaunchContext | undefined;
+
+    override async createSession(
+      config: AgentSessionConfig,
+      launchContext?: AgentLaunchContext,
+    ): Promise<AgentSession> {
+      this.createLaunchContext = launchContext;
+      return new TestAgentSession(config);
+    }
+
+    override async resumeSession(
+      handle: AgentPersistenceHandle,
+      overrides?: Partial<AgentSessionConfig>,
+      launchContext?: AgentLaunchContext,
+    ): Promise<AgentSession> {
+      this.resumeLaunchContext = launchContext;
+      const metadata = (handle.metadata ?? {}) as Partial<AgentSessionConfig>;
+      return new TestAgentSession({ ...metadata, ...overrides, provider: "codex", cwd: workdir });
+    }
+  }
+
+  const client = new CaptureClient();
+  const manager = new AgentManager({
+    clients: {
+      codex: client,
+    },
+    registry: storage,
+    logger,
+    idFactory: () => "00000000-0000-4000-8000-000000000140",
+  });
+
+  const snapshot = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: "ws-agent-home",
+  });
+  expect(client.createLaunchContext?.env).toEqual({
+    PASEO_AGENT_ID: snapshot.id,
+    PASEO_AGENT_CWD: workdir,
+    PASEO_WORKSPACE_ID: "ws-agent-home",
+  });
+
+  // The stored record supplies the workspace when the caller doesn't.
+  const handle: AgentPersistenceHandle = {
+    provider: "codex",
+    sessionId: "workspace-env-session",
+    metadata: { provider: "codex", cwd: workdir },
+  };
+  const expectedEnv = {
+    PASEO_AGENT_ID: snapshot.id,
+    PASEO_AGENT_CWD: workdir,
+    PASEO_WORKSPACE_ID: "ws-agent-home",
+  };
+
+  await manager.closeAgent(snapshot.id);
+  const resumed = await manager.resumeAgentFromPersistence(handle, { cwd: workdir }, snapshot.id);
+  expect(client.resumeLaunchContext?.env).toEqual(expectedEnv);
+  expect(resumed.workspaceId).toBe("ws-agent-home");
+  expect((await storage.get(snapshot.id))?.workspaceId).toBe("ws-agent-home");
+
+  // Each restart reads what the previous resume stored.
+  client.resumeLaunchContext = undefined;
+  await manager.closeAgent(snapshot.id);
+  await manager.resumeAgentFromPersistence(handle, { cwd: workdir }, snapshot.id);
+  expect(client.resumeLaunchContext?.env).toEqual(expectedEnv);
+});
+
 test("createAgent passes persistSession to provider create options", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
   const storagePath = join(workdir, "agents");
@@ -4148,7 +4504,7 @@ test("createAgent rejects a disabled provider without creating a session", async
     ),
   ).rejects.toThrow("Provider 'codex' is disabled");
   expect(disabledClient.createSessionCalls).toBe(0);
-  expect(await storage.list()).toHaveLength(0);
+  expect(await storage.listAll()).toHaveLength(0);
 });
 
 test("updateProviderRegistry re-enables a previously disabled provider", async () => {
@@ -4636,6 +4992,91 @@ test("resumeAgentFromPersistence keeps metadata config, applies overrides, and p
   });
 });
 
+test("importProviderSession reports the defaults the session launched with, not defaults edited during the import", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-import-options-"));
+  let tier = "default";
+  class ImportClient extends TestAgentClient {
+    effectiveOptions(own: ProviderOptions | undefined): ProviderOptions {
+      return { service_tier: tier, ...own };
+    }
+
+    async importSession(input: ImportProviderSessionInput) {
+      // The user edits the default in config.json after the provider has launched.
+      tier = "fast";
+      return {
+        session: new TestAgentSession({ provider: "codex", cwd: workdir }),
+        config: { provider: "codex" as const, cwd: workdir },
+        persistence: {
+          provider: "codex" as const,
+          sessionId: input.providerHandleId,
+          nativeHandle: input.providerHandleId,
+          metadata: { provider: "codex", cwd: workdir },
+        },
+        timeline: [],
+      };
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new ImportClient() },
+    registry: new AgentStorage(join(workdir, "agents"), logger),
+    logger,
+  });
+
+  const imported = await manager.importProviderSession({
+    provider: "codex",
+    providerHandleId: "thread-selected",
+    cwd: workdir,
+    workspaceId: "ws-imported",
+  });
+
+  expect(imported.effectiveOptions).toEqual({ service_tier: "default" });
+});
+
+test("importProviderSession preserves the native model instead of applying the new-session default", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-import-model-"));
+  onTestFinished(() => rmSync(workdir, { recursive: true, force: true }));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const nativeModel = "native-selected-model";
+
+  class ImportClient extends TestAgentClient {
+    importConfig: AgentSessionConfig | undefined;
+
+    async importSession(input: ImportProviderSessionInput, context: ImportProviderSessionContext) {
+      this.importConfig = context.config;
+      // A resumable provider applies explicit selections but otherwise retains its model.
+      const session = new TestAgentSession({
+        ...context.config,
+        model: context.config.model ?? nativeModel,
+      });
+      return {
+        session,
+        config: context.storedConfig,
+        persistence: { provider: this.provider, sessionId: input.providerHandleId },
+        timeline: [],
+      };
+    }
+  }
+
+  const client = new ImportClient();
+  const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+  const imported = await manager.importProviderSession({
+    provider: "codex",
+    providerHandleId: "native-session",
+    cwd: workdir,
+    workspaceId: "import-model",
+  });
+  await manager.flush();
+
+  expect(imported.runtimeInfo?.model).toBe(nativeModel);
+  expect(imported.config.model).toBe(nativeModel);
+  expect(client.importConfig?.model).toBeUndefined();
+  expect((await storage.get(imported.id))?.config.model).toBe(nativeModel);
+
+  await manager.reloadAgentSession(imported.id);
+  expect(client.resumeOverrides.at(-1)?.model).toBe(nativeModel);
+  await manager.getAgent(imported.id)?.session?.close();
+});
+
 test("importProviderSession imports the selected session without listing and publishes ready state", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-import-session-"));
   const storagePath = join(workdir, "agents");
@@ -4740,6 +5181,7 @@ test("importProviderSession imports the selected session without listing and pub
     env: {
       PASEO_AGENT_ID: imported.id,
       PASEO_AGENT_CWD: workdir,
+      PASEO_WORKSPACE_ID: "ws-imported",
     },
   });
   expect(imported.lifecycle).toBe("idle");
@@ -5254,6 +5696,9 @@ test("model changes persist the resolved thinking and fresh provider handle befo
         thinkingOptionId: null,
       });
     }
+    override async getRuntimeInfo() {
+      return { ...(await super.getRuntimeInfo()), ...this.selection };
+    }
     describePersistence() {
       return { provider: "codex" as const, sessionId: this.id, metadata: { ...this.selection } };
     }
@@ -5336,6 +5781,102 @@ test("later explicit config mutations win over events emitted by earlier mutatio
   expect(manager.getAgent(snapshot.id)?.config.thinkingOptionId).toBe("high");
 });
 
+test("a running agent's model and thinking option changes reach the session unchecked", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-selection-unchecked-"));
+  const received: Array<[string, string | null]> = [];
+  class RecordingSession extends TestAgentSession {
+    async setModel(modelId: string | null): Promise<void> {
+      received.push(["model", modelId]);
+    }
+    async setThinkingOption(thinkingOptionId: string | null): Promise<null> {
+      received.push(["thinking", thinkingOptionId]);
+      return null;
+    }
+  }
+  class RecordingClient extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      return new RecordingSession(config);
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new RecordingClient() },
+    registry: new AgentStorage(join(workdir, "agents"), logger),
+    logger,
+    idFactory: () => "00000000-0000-4000-8000-000000000136",
+  });
+  const snapshot = await manager.createAgent(
+    { provider: "codex", cwd: workdir, model: "gpt-5.4" },
+    undefined,
+    { workspaceId: undefined },
+  );
+
+  await manager.setAgentModel(snapshot.id, "not-in-any-catalog");
+  await manager.setAgentThinkingOption(snapshot.id, "not-a-level");
+
+  expect(received).toEqual([
+    ["model", "not-in-any-catalog"],
+    ["thinking", "not-a-level"],
+  ]);
+  expect(manager.getAgent(snapshot.id)?.config.model).toBe("not-in-any-catalog");
+});
+
+test.each([
+  { requested: "unavailable", effective: "source" },
+  { requested: "alias", effective: "canonical" },
+  { requested: null, effective: null },
+])(
+  "setAgentModel stores effective selections and preserves resets for $requested",
+  async ({ requested, effective }) => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-effective-model-"));
+    class SelectingSession extends TestAgentSession {
+      private model: string | null = "source";
+
+      async setModel(model: string | null) {
+        if (model && model !== "unavailable") this.model = model === "alias" ? "canonical" : model;
+        return { model: this.model };
+      }
+
+      override async getRuntimeInfo() {
+        return { ...(await super.getRuntimeInfo()), model: this.model };
+      }
+    }
+    class SelectingClient extends TestAgentClient {
+      override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+        return new SelectingSession(config);
+      }
+    }
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const manager = new AgentManager({
+      clients: { codex: new SelectingClient() },
+      registry: storage,
+      logger,
+    });
+    try {
+      const snapshot = await manager.createAgent(
+        { provider: "codex", cwd: workdir, model: "source" },
+        undefined,
+        { workspaceId: undefined },
+      );
+      await manager.setAgentModel(snapshot.id, requested);
+      await manager.flush();
+
+      expect(manager.getAgent(snapshot.id)?.config.model).toBe(effective ?? undefined);
+      expect(manager.getAgent(snapshot.id)?.runtimeInfo?.model).toBe(effective);
+      const persisted = await storage.get(snapshot.id);
+      expect(persisted?.config?.model).toBe(effective ?? undefined);
+      expect(persisted?.runtimeInfo?.model).toBe(effective);
+
+      await manager.setAgentModel(snapshot.id, "target");
+      expect(manager.getAgent(snapshot.id)?.config.model).toBe("target");
+      expect(manager.getAgent(snapshot.id)?.runtimeInfo?.model).toBe("target");
+    } finally {
+      for (const agent of manager.listAgents()) await manager.closeAgent(agent.id);
+      await manager.flush();
+      rmSync(workdir, { recursive: true, force: true });
+    }
+  },
+);
+
 test("setAgentThinkingOption adopts the session's effective clamped level", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-thinking-clamp-"));
   class ClampingSession extends TestAgentSession {
@@ -5544,6 +6085,37 @@ test("setLabels merges and persists labels", async () => {
   });
 });
 
+test("reopening a closed agent keeps metadata saved while the loader was reading its record", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-metadata-reopen-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const manager = new AgentManager({
+    clients: { codex: new TestAgentClient() },
+    registry: storage,
+    logger,
+  });
+  const created = await manager.createAgent(
+    { provider: "codex", cwd: workdir, title: "Metadata reopen" },
+    undefined,
+    { workspaceId: undefined, metadata: { first: 1 } },
+  );
+  const agentId = created.id;
+  await manager.closeAgent(agentId);
+
+  // The loader reads the record, then a setMetadata is queued before its resume runs.
+  const readByLoader = await storage.get(agentId);
+  const saved = manager.setMetadata(agentId, { second: 2 });
+  const reopened = manager.resumeAgentFromPersistence(
+    { provider: "codex", sessionId: "session-metadata", metadata: { cwd: workdir } },
+    { cwd: workdir },
+    agentId,
+    { metadata: readByLoader?.metadata },
+  );
+
+  expect(await saved).toEqual({ first: 1, second: 2 });
+  expect((await reopened).metadata).toEqual({ first: 1, second: 2 });
+  expect((await storage.get(agentId))?.metadata).toEqual({ first: 1, second: 2 });
+});
+
 test("detachAgent removes relationship lifecycle labels from a live agent and emits state", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-detach-live-"));
   const storagePath = join(workdir, "agents");
@@ -5811,6 +6383,52 @@ test("archiveSnapshot dispatches archived state for stored-only agents", async (
   expect(last.lifecycle).toBe("closed");
 });
 
+test("markAgentUnread restores error attention on a read errored agent", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-mark-unread-error-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  class ErrorClient extends TestAgentClient {
+    readonly session = new TestAgentSession({ provider: "codex", cwd: workdir });
+
+    override async createSession(): Promise<AgentSession> {
+      return this.session;
+    }
+  }
+  const client = new ErrorClient();
+  const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+  onTestFinished(async () => {
+    await manager.closeAgent(agent.id);
+    await manager.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  const running = waitForAgentLifecycle(manager, agent.id, "running");
+  client.session.pushEvent({ type: "turn_started", provider: "codex", turnId: "failed-turn" });
+  await running;
+  const failed = waitForAgentLifecycle(manager, agent.id, "error");
+  client.session.pushEvent({
+    type: "turn_failed",
+    provider: "codex",
+    turnId: "failed-turn",
+    error: "Selected model is at capacity.",
+  });
+  await failed;
+  await manager.clearAgentAttention(agent.id);
+
+  await manager.markAgentUnread(agent.id);
+
+  expect(manager.getAgent(agent.id)?.attention).toMatchObject({
+    requiresAttention: true,
+    attentionReason: "error",
+  });
+  expect(await storage.get(agent.id)).toMatchObject({
+    lastStatus: "error",
+    requiresAttention: true,
+    attentionReason: "error",
+  });
+});
+
 test("markAgentUnread dispatches stored attention to every subscriber", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-mark-unread-dispatch-"));
   const storage = new AgentStorage(join(workdir, "agents"), logger);
@@ -7343,6 +7961,7 @@ test("ignores stale autonomous terminals without lowering the active turn lifecy
     const running = manager.getAgent(snapshot.id);
     expect(running?.lifecycle).toBe("running");
     expect(running ? toAgentPayload(running).activeTurn?.turnId : null).toBe("turn-b");
+    expect(running?.lastError).toBeUndefined();
   });
 
   const active = manager.getAgent(snapshot.id)!;
@@ -7385,7 +8004,7 @@ test("ignores stale autonomous terminals without lowering the active turn lifecy
     const stillRunning = manager.getAgent(snapshot.id);
     expect(stillRunning?.lifecycle).toBe("running");
     expect(stillRunning ? toAgentPayload(stillRunning).activeTurn?.turnId : null).toBe("turn-b");
-    expect(stillRunning?.lastError).toBe("turn-b marker");
+    expect(stillRunning?.lastError).toBeUndefined();
     expect(stillRunning?.lastUsage).toEqual({ inputTokens: 7 });
     expect(stillRunning?.pendingPermissions.has("turn-b-permission")).toBe(true);
     expect(await manager.getTimeline(snapshot.id)).toEqual(timelineBeforeStaleTerminals);
@@ -8268,7 +8887,7 @@ test("archiveAgent closes an internal agent without writing a record", async ()
   expect(Number.isNaN(Date.parse(archivedAt))).toBe(false);
   expect(manager.getAgent(internalAgentId)).toBeNull();
   expect(await storage.get(internalAgentId)).toBeNull();
-  expect(await storage.list()).toEqual([]);
+  expect(await storage.listAll()).toEqual([]);
   expect(manager.getRetiredInternalAgent(internalAgentId)).toEqual({
     record: expect.objectContaining({
       id: internalAgentId,
@@ -8709,6 +9328,118 @@ test("clearAgentAttention on errored agent stays cleared until a new error trans
   expect(persistedAfterSecondFailure?.attentionReason).toBe("error");
 });
 
+test.each([
+  ["autonomous", "turn_completed", "idle", "finished", undefined],
+  ["autonomous", "turn_failed", "error", "error", "Retry failed."],
+  ["foreground", "turn_completed", "idle", "finished", undefined],
+  ["foreground", "turn_failed", "error", "error", "Retry failed."],
+] as const)(
+  "%s recovery clears error attention before %s",
+  async (mode, terminal, status, expectedReason, lastError) => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-attention-recovery-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    class RecoverySession extends TestAgentSession {
+      override async startTurn(): Promise<{ turnId: string }> {
+        return { turnId: "recovered-turn" };
+      }
+    }
+
+    class RecoveryClient extends TestAgentClient {
+      readonly session = new RecoverySession({ provider: "codex", cwd: workdir });
+
+      override async createSession(): Promise<AgentSession> {
+        return this.session;
+      }
+    }
+
+    const client = new RecoveryClient();
+    const attentionReasons: Array<"finished" | "error" | "permission"> = [];
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      onAgentAttention: ({ reason }) => attentionReasons.push(reason),
+    });
+    onTestFinished(async () => {
+      await manager.closeAgent(agent.id);
+      await manager.flush();
+      rmSync(workdir, { recursive: true, force: true });
+    });
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    const running = waitForAgentLifecycle(manager, agent.id, "running");
+    client.session.pushEvent({ type: "turn_started", provider: "codex", turnId: "failed-turn" });
+    await running;
+    const failed = waitForAgentLifecycle(manager, agent.id, "error");
+    client.session.pushEvent({
+      type: "turn_failed",
+      provider: "codex",
+      turnId: "failed-turn",
+      error: "Selected model is at capacity.",
+    });
+    await failed;
+    await vi.waitFor(() => expect(manager.hasInFlightRun(agent.id)).toBe(false));
+    expect(toAgentPayload(manager.getAgent(agent.id)!)).toMatchObject({
+      status: "error",
+      attentionReason: "error",
+      lastError: "Selected model is at capacity.",
+    });
+
+    const recovered = waitForAgentLifecycle(manager, agent.id, "running");
+    const stream =
+      mode === "foreground"
+        ? drainAsyncGenerator(manager.streamAgent(agent.id, "Continue after capacity recovers."))
+        : null;
+    if (mode === "autonomous") {
+      client.session.pushEvent({
+        type: "turn_started",
+        provider: "codex",
+        turnId: "recovered-turn",
+      });
+    }
+    await recovered;
+    await manager.flush();
+    expect(toAgentPayload(manager.getAgent(agent.id)!)).toMatchObject({
+      status: "running",
+      requiresAttention: false,
+      attentionReason: null,
+    });
+    expect(manager.getAgent(agent.id)?.lastError).toBeUndefined();
+    expect(await storage.get(agent.id)).toMatchObject({
+      lastStatus: "running",
+      requiresAttention: false,
+      attentionReason: null,
+    });
+    expect((await storage.get(agent.id))?.lastError).toBeUndefined();
+
+    const settled = waitForAgentLifecycle(manager, agent.id, status);
+    client.session.pushEvent({
+      type: terminal,
+      provider: "codex",
+      turnId: "recovered-turn",
+      ...(terminal === "turn_failed" ? { error: "Retry failed." } : {}),
+    });
+    await settled;
+    await stream;
+    await manager.flush();
+    expect(toAgentPayload(manager.getAgent(agent.id)!)).toMatchObject({
+      status,
+      requiresAttention: true,
+      attentionReason: expectedReason,
+    });
+    expect(manager.getAgent(agent.id)?.lastError).toBe(lastError);
+    expect(await storage.get(agent.id)).toMatchObject({
+      lastStatus: status,
+      requiresAttention: true,
+      attentionReason: expectedReason,
+    });
+    expect((await storage.get(agent.id))?.lastError).toBe(lastError);
+    expect(attentionReasons).toEqual(["error", expectedReason]);
+  },
+);
+
 test("streamAgent clears pending run when startTurn fails before a turn id exists", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-start-turn-failure-"));
   const storagePath = join(workdir, "agents");
@@ -9256,14 +9987,76 @@ test("archiveAgent detaches a cross-workspace child even when its tab is closed"
   expect(storedChild?.labels[PARENT_AGENT_ID_LABEL]).toBeUndefined();
 });
 
+test.each([
+  { workspaceId: "workspace-b", open: "false" },
+  { workspaceId: "workspace-a", open: "true" },
+])(
+  "archiveAgent publishes stored survivor detach updates ($workspaceId, open=$open)",
+  async ({ workspaceId, open }) => {
+    const artifacts = join(process.cwd(), ".artifacts");
+    mkdirSync(artifacts, { recursive: true });
+    const workdir = mkdtempSync(join(artifacts, "stored-child-detach-"));
+    onTestFinished(() => rmSync(workdir, { recursive: true, force: true }));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const manager = new AgentManager({
+      clients: { codex: new TestAgentClient() },
+      registry: storage,
+      logger,
+    });
+    const parent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, title: "Parent" },
+      undefined,
+      { workspaceId: "workspace-a" },
+    );
+    const child = await manager.createAgent(
+      { provider: "codex", cwd: workdir, title: "Closed cross-workspace child" },
+      undefined,
+      {
+        workspaceId,
+        labels: {
+          [PARENT_AGENT_ID_LABEL]: parent.id,
+          [DESKTOP_OPEN_AGENT_TAB_LABEL]: open,
+          team: "ios",
+        },
+      },
+    );
+    await manager.closeAgent(child.id);
+    // Unfiltered, as a session subscribes: a closed survivor's update must reach every client.
+    const emittedLabels: Array<Record<string, string>> = [];
+    const unsubscribe = manager.subscribe(
+      (event) => {
+        if (event.type === "agent_state" && event.agent.id === child.id) {
+          emittedLabels.push(event.agent.labels);
+        }
+      },
+      { replayState: false },
+    );
+
+    await manager.archiveAgent(parent.id);
+    await manager.flush();
+    unsubscribe();
+
+    const expectedLabels = { team: "ios" };
+    const storedChild = await storage.get(child.id);
+    expect(storedChild?.archivedAt).toBeUndefined();
+    expect(storedChild?.labels).toEqual(expectedLabels);
+    expect(emittedLabels).toEqual([expectedLabels]);
+
+    // The child is already detached; repeating detach has nothing to sever.
+    const detached = await manager.detachAgent(child.id);
+    expect(detached.previousParentAgentId).toBeNull();
+    expect(detached.record.labels).toEqual(expectedLabels);
+  },
+);
+
 test("archiveAgent re-reads a child before deciding whether to cascade", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-cascade-fresh-child-"));
 
   class ChildOpensAfterCascadeListStorage extends AgentStorage {
     childId: string | null = null;
 
-    override async list(): Promise<StoredAgentRecord[]> {
-      const records = await super.list();
+    override async listActive(): Promise<StoredAgentRecord[]> {
+      const records = await super.listAll();
       const parentIsArchived = records.some(
         (record) => record.id !== this.childId && Boolean(record.archivedAt),
       );
@@ -10006,16 +10799,13 @@ test("respondToPermission updates currentModeId after plan approval", async () =
   expect(client.resumedModeId).toBe("acceptEdits");
 });
 
-test("respondToPermission refreshes features and runtime info after provider-managed plan approval", async () => {
+test("respondToPermission applies provider option changes and refreshes runtime info after provider-managed plan approval", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
   const storagePath = join(workdir, "agents");
   const storage = new AgentStorage(storagePath, logger);
 
   class RefreshingPermissionSession extends TestAgentSession {
-    private featureState: AgentFeature[] = [
-      createFeature({ id: "fast_mode", label: "Fast", value: true }),
-      createFeature({ id: "plan_mode", label: "Plan", value: true }),
-    ];
+    private planMode = true;
     private modeId = "auto";
     private pending = [
       {
@@ -10027,8 +10817,11 @@ test("respondToPermission refreshes features and runtime info after provider-man
       },
     ];
 
-    get features(): AgentFeature[] {
-      return this.featureState;
+    get controls(): AgentOptionControl[] {
+      return [
+        createControl({ key: "web_search", label: "Fast" }),
+        createControl({ key: "plan_mode", label: "Plan" }),
+      ];
     }
 
     override async getRuntimeInfo() {
@@ -10037,7 +10830,7 @@ test("respondToPermission refreshes features and runtime info after provider-man
         sessionId: this.id,
         model: "gpt-5.4",
         modeId: this.modeId,
-        extra: { collaborationMode: this.features[1]?.value ? "Plan" : "Code" },
+        extra: { collaborationMode: this.planMode ? "Plan" : "Code" },
       };
     }
 
@@ -10052,10 +10845,12 @@ test("respondToPermission refreshes features and runtime info after provider-man
     override async respondToPermission(): Promise<void> {
       this.modeId = "auto";
       this.pending = [];
-      this.featureState = [
-        createFeature({ id: "fast_mode", label: "Fast", value: true }),
-        createFeature({ id: "plan_mode", label: "Plan", value: false }),
-      ];
+      this.planMode = false;
+      this.pushEvent({
+        type: "options_changed",
+        provider: this.provider,
+        patch: { plan_mode: false },
+      });
     }
   }
 
@@ -10078,6 +10873,7 @@ test("respondToPermission refreshes features and runtime info after provider-man
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { web_search: true, plan_mode: true },
     },
     undefined,
     { workspaceId: undefined },
@@ -10102,20 +10898,14 @@ test("respondToPermission refreshes features and runtime info after provider-man
 
   const updated = manager.getAgent(snapshot.id);
   expect(updated?.pendingPermissions.size).toBe(0);
-  expect(updated?.features).toEqual([
-    createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    createFeature({ id: "plan_mode", label: "Plan", value: false }),
-  ]);
+  expect(updated?.effectiveOptions).toEqual({ web_search: true, plan_mode: false });
   expect(updated?.runtimeInfo).toMatchObject({
     model: "gpt-5.4",
     extra: { collaborationMode: "Code" },
   });
 
   const persisted = await storage.get(snapshot.id);
-  expect(persisted?.features).toEqual([
-    createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    createFeature({ id: "plan_mode", label: "Plan", value: false }),
-  ]);
+  expect(persisted?.config?.providerOptions).toEqual({ web_search: true, plan_mode: false });
 });
 
 test("respondToPermission emits refreshed state before permission_resolved", async () => {
@@ -10124,9 +10914,6 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
   const storage = new AgentStorage(storagePath, logger);
 
   class OrderedPermissionSession extends TestAgentSession {
-    private featureState: AgentFeature[] = [
-      createFeature({ id: "fast_mode", label: "Fast", value: true }),
-    ];
     private modeId = "plan";
     private pending = [
       {
@@ -10138,8 +10925,8 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
       },
     ];
 
-    get features(): AgentFeature[] {
-      return this.featureState;
+    get controls(): AgentOptionControl[] {
+      return [createControl({ key: "web_search", label: "Fast" })];
     }
 
     override async getRuntimeInfo() {
@@ -10160,6 +10947,11 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
     }
 
     override async respondToPermission(): Promise<void> {
+      this.pushEvent({
+        type: "options_changed",
+        provider: this.provider,
+        patch: { web_search: false },
+      });
       this.pushEvent({
         type: "permission_resolved",
         provider: this.provider,
@@ -10167,7 +10959,6 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
         resolution: { behavior: "allow" },
       });
       this.modeId = "acceptEdits";
-      this.featureState = [createFeature({ id: "fast_mode", label: "Fast", value: false })];
       this.pending = [];
     }
   }
@@ -10191,6 +10982,7 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
     {
       provider: "codex",
       cwd: workdir,
+      providerOptions: { web_search: true },
     },
     undefined,
     { workspaceId: undefined },
@@ -10202,9 +10994,8 @@ test("respondToPermission emits refreshed state before permission_resolved", asy
       return;
     }
     if (event.type === "agent_state" && event.agent.id === snapshot.id) {
-      const fastMode = event.agent.features?.find((feature) => feature.id === "fast_mode");
       seen.push(
-        `state:${event.agent.currentModeId}:${String(fastMode?.type === "toggle" ? fastMode.value : null)}`,
+        `state:${event.agent.currentModeId}:${String(event.agent.effectiveOptions?.web_search)}`,
       );
       return;
     }
@@ -10969,6 +11760,86 @@ test("concurrent explicit closes tear down the runtime once", async () => {
   }
 });
 
+test("close drains provider tool cleanup before retiring the runtime", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-close-cleanup-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  class CleanupSession extends TestAgentSession {
+    override async startTurn(): Promise<{ turnId: string }> {
+      const turnId = "cleanup-turn";
+      this.pushEvent({ type: "turn_started", provider: this.provider, turnId });
+      for (const callId of ["first-tool", "second-tool"]) {
+        this.pushEvent({
+          type: "timeline",
+          provider: this.provider,
+          turnId,
+          item: {
+            type: "tool_call",
+            callId,
+            name: "Bash",
+            detail: { type: "shell", command: "sleep 10" },
+            status: "running",
+            error: null,
+          },
+        });
+      }
+      return { turnId };
+    }
+    override async close(): Promise<void> {
+      for (const callId of ["first-tool", "second-tool"]) {
+        this.pushEvent({
+          type: "timeline",
+          provider: this.provider,
+          turnId: "cleanup-turn",
+          item: {
+            type: "tool_call",
+            callId,
+            name: "Bash",
+            detail: { type: "shell", command: "sleep 10" },
+            status: "canceled",
+            error: null,
+          },
+        });
+      }
+    }
+  }
+  const client = new (class extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      return new CleanupSession(config);
+    }
+  })();
+  const manager = new AgentManager({
+    clients: { codex: client },
+    registry: storage,
+    logger,
+  });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  const run = drainAsyncGenerator(manager.streamAgent(agent.id, "run both tools"));
+  try {
+    await manager.waitForAgentRunStart(agent.id);
+    await manager.flush();
+    await manager.closeAgent(agent.id);
+    await run;
+    await manager.flush();
+    // Closing keeps the agent's history, so the cancellations close emitted are read back from it.
+    expect(
+      (await manager.getTimeline(agent.id))
+        .filter((item) => item.type === "tool_call")
+        .map((item) => ({ callId: item.callId, status: item.status })),
+    ).toEqual([
+      { callId: "first-tool", status: "canceled" },
+      { callId: "second-tool", status: "canceled" },
+    ]);
+    expect((await storage.get(agent.id))?.lastStatus).toBe("closed");
+  } finally {
+    await manager.closeAgent(agent.id).catch(() => undefined);
+    await run;
+    await manager.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("provider close failure retains the runtime for cleanup instead of allowing another writer", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-close-failure-"));
   const storage = new AgentStorage(join(workdir, "agents"), logger);
@@ -12494,6 +13365,7 @@ test.each([
               provider: "codex",
               cwd: workdir,
               title: null,
+              metadata: {},
             },
             turnId: "hook-turn",
             outcome,
@@ -12773,3 +13645,787 @@ test("an out-of-band command racing idle cleanup waits for the resumed runtime",
   expect(h.commands).toEqual(["/maintenance"]);
   expect(h.prompts).toEqual([]);
 });
+
+describe("agent options", () => {
+  class OptionsSession extends TestAgentSession {
+    readonly applied: ProviderOptions[] = [];
+    rejectWith: Error | null = null;
+    /** Holds the next apply only; the one after it is answered at once. */
+    applyGate: Promise<void> | null = null;
+    /** What the session says it ended up with after the next apply. */
+    ended: Record<string, unknown> = {};
+    openOptionsPatch: Record<string, unknown> = {};
+    runtimeModel: string | null = null;
+    /** The model the next apply moves the session to, as a provider's connection option does. */
+    movesModelTo: string | null = null;
+
+    async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+      if (this.rejectWith) throw this.rejectWith;
+      const gate = this.applyGate;
+      this.applyGate = null;
+      await gate;
+      this.applied.push(options);
+      if (this.movesModelTo) this.runtimeModel = this.movesModelTo;
+      return this.ended;
+    }
+
+    override async getRuntimeInfo() {
+      const info = await super.getRuntimeInfo();
+      return this.runtimeModel ? { ...info, model: this.runtimeModel } : info;
+    }
+  }
+
+  class OptionsClient extends TestAgentClient {
+    session: OptionsSession | null = null;
+    openOptionsPatch: Record<string, unknown> = {};
+    runtimeModel: string | null = null;
+
+    // Stands in for the `config.json` provider defaults the registry wrapper merges in.
+    effectiveOptions(own: ProviderOptions | undefined): ProviderOptions {
+      return { service_tier: "default", ...own };
+    }
+
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      this.session = new OptionsSession(config);
+      this.session.openOptionsPatch = this.openOptionsPatch;
+      this.session.runtimeModel = this.runtimeModel;
+      return this.session;
+    }
+  }
+
+  async function createOptionsAgent(
+    providerOptions?: ProviderOptions,
+    openOptionsPatch: Record<string, unknown> = {},
+    opened: { model?: string; runtimeModel?: string } = {},
+  ) {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    client.openOptionsPatch = openOptionsPatch;
+    client.runtimeModel = opened.runtimeModel ?? null;
+    const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+    const agent = await manager.createAgent(
+      {
+        provider: "codex",
+        cwd: workdir,
+        ...(opened.model ? { model: opened.model } : {}),
+        ...(providerOptions ? { providerOptions } : {}),
+      },
+      undefined,
+      { workspaceId: undefined },
+    );
+    return { manager, client, storage, agentId: agent.id };
+  }
+
+  test("config.json defaults show as effective options without entering the agent's own options", async () => {
+    const { manager, agentId } = await createOptionsAgent({ web_search: true });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+    expect(toAgentPayload(agent!).options).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("a stored legacy Codex record reads its saved Fast speed as the speed its control selects", () => {
+    const manager = new AgentManager({ clients: { codex: new OptionsClient() }, logger });
+    // Written by a daemon that took `fast_mode`; never reopened since the upgrade.
+    const record = parseStoredAgentRecord({
+      id: "agent-legacy-fast",
+      provider: "codex",
+      cwd: "/repo",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      lastStatus: "closed",
+      config: { featureValues: { fast_mode: true } },
+      features: [
+        {
+          type: "select",
+          id: "service_tier",
+          label: "Speed",
+          value: "fast",
+          options: [
+            { id: "default", label: "Normal", isDefault: true },
+            { id: "fast", label: "Fast" },
+          ],
+        },
+      ],
+      persistence: { provider: "codex", sessionId: "thread-1" },
+    });
+
+    const payload = buildStoredAgentPayload(record, ["codex"], (provider, own) =>
+      manager.effectiveOptionsFor(provider, own),
+    );
+
+    expect(payload.options).toEqual({ service_tier: "fast" });
+    expect(payload.features).toEqual([
+      expect.objectContaining({ id: "service_tier", value: "fast" }),
+    ]);
+  });
+
+  test("a stored record with a malformed legacy speed still reads; opening it is what rejects it", () => {
+    const manager = new AgentManager({ clients: { codex: new OptionsClient() }, logger });
+    // An older daemon accepted any value here; this one rejects it on create and on change.
+    const record = parseStoredAgentRecord({
+      id: "agent-legacy-malformed",
+      provider: "codex",
+      cwd: "/repo",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      lastStatus: "closed",
+      config: { providerOptions: { fast_mode: "false" } },
+      persistence: { provider: "codex", sessionId: "thread-2" },
+    });
+
+    const payload = buildStoredAgentPayload(record, ["codex"], (provider, own) =>
+      manager.effectiveOptionsFor(provider, own),
+    );
+
+    expect(payload.options).toEqual({ service_tier: "default", fast_mode: "false" });
+  });
+
+  test("setAgentOptions hands the provider only the keys the patch sets", async () => {
+    const { manager, client, storage, agentId } = await createOptionsAgent({ web_search: true });
+
+    await manager.setAgentOptions(agentId, { service_tier: "fast" });
+
+    expect(client.session?.applied).toEqual([{ service_tier: "fast" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true, service_tier: "fast" });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "fast", web_search: true });
+    await manager.flush();
+    expect((await storage.get(agentId))?.config?.providerOptions).toEqual({
+      web_search: true,
+      service_tier: "fast",
+    });
+  });
+
+  test("an option that moves the agent to another model reopens on that model", async () => {
+    const { manager, client, storage, agentId } = await createOptionsAgent(
+      undefined,
+      {},
+      { model: "first-connection-model" },
+    );
+    client.session!.movesModelTo = "second-connection-model";
+
+    await manager.setAgentOptions(agentId, { web_search: true });
+
+    expect(manager.getAgent(agentId)?.config.model).toBe("second-connection-model");
+    await manager.flush();
+    expect((await storage.get(agentId))?.config?.model).toBe("second-connection-model");
+  });
+
+  test("an option that leaves the model alone keeps the model the user chose", async () => {
+    const { manager, agentId } = await createOptionsAgent(
+      undefined,
+      {},
+      { model: "alias", runtimeModel: "canonical" },
+    );
+
+    await manager.setAgentOptions(agentId, { web_search: true });
+
+    expect(manager.getAgent(agentId)?.config.model).toBe("alias");
+  });
+
+  test("a patch key is resolved against the configured defaults, merging nested objects", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    client.effectiveOptions = (own) =>
+      mergeProviderOptions({ sandbox: { enabled: true, failIfUnavailable: true } }, own) ?? {};
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    await manager.setAgentOptions(agent.id, {
+      sandbox: { network: { allowedDomains: ["a.test"] } },
+    });
+
+    expect(client.session?.applied).toEqual([
+      {
+        sandbox: {
+          enabled: true,
+          failIfUnavailable: true,
+          network: { allowedDomains: ["a.test"] },
+        },
+      },
+    ]);
+    expect(manager.getAgent(agent.id)?.config.providerOptions).toEqual({
+      sandbox: { network: { allowedDomains: ["a.test"] } },
+    });
+    // The snapshot shows what the provider was given, defaults included, and keeps showing it.
+    await manager.markAgentUnread(agent.id);
+    expect(manager.getAgent(agent.id)?.effectiveOptions).toEqual({
+      sandbox: {
+        enabled: true,
+        failIfUnavailable: true,
+        network: { allowedDomains: ["a.test"] },
+      },
+    });
+  });
+
+  test("setAgentOptions sends a removal to the provider like any change, as the default it falls back to", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ service_tier: "fast" });
+
+    await manager.setAgentOptions(agentId, { service_tier: null });
+
+    expect(client.session?.applied).toEqual([{ service_tier: "default" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toBeUndefined();
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default" });
+  });
+
+  test("a removal with no default is sent as null", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+
+    await manager.setAgentOptions(agentId, { web_search: null });
+
+    expect(client.session?.applied).toEqual([{ web_search: null }]);
+    expect(manager.getAgent(agentId)?.config.providerOptions).toBeUndefined();
+  });
+
+  test("a value the provider kept through a removal is stored", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+    client.session!.ended = { web_search: true };
+
+    await manager.setAgentOptions(agentId, { web_search: null });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ web_search: true });
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("what the provider ended up with is stored together with the patch", async () => {
+    const { manager, client, agentId } = await createOptionsAgent();
+    client.session!.ended = { service_tier: "slow" };
+
+    await manager.setAgentOptions(agentId, { service_tier: "fast", plan_mode: true });
+
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({
+      service_tier: "slow",
+      plan_mode: true,
+    });
+  });
+
+  test("the difference a session opened with is stored before the agent is published", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    client.openOptionsPatch = { service_tier: "slow", web_search: null };
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const published: Array<ProviderOptions | undefined> = [];
+    manager.subscribe((event) => {
+      if (event.type === "agent_state") published.push(event.agent.config.providerOptions);
+    });
+
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(agent.config.providerOptions).toEqual({ service_tier: "slow" });
+    expect(published.length).toBeGreaterThan(0);
+    expect(published.every((options) => options?.service_tier === "slow")).toBe(true);
+  });
+
+  test("a default edited while the session is opening does not change the opening snapshot", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-options-"));
+    const client = new OptionsClient();
+    let tier = "default";
+    client.effectiveOptions = (own) => ({ service_tier: tier, ...own });
+    const open = client.createSession.bind(client);
+    client.createSession = async (config) => {
+      const session = await open(config);
+      // The user edits the default in config.json after the provider has launched.
+      tier = "fast";
+      return session;
+    };
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    expect(agent.effectiveOptions).toEqual({ service_tier: "default" });
+  });
+
+  test("an option the session dropped when opening does not come back from a configured default", async () => {
+    const { manager, agentId } = await createOptionsAgent(undefined, { service_tier: null });
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.effectiveOptions).toEqual({});
+    await manager.markAgentUnread(agentId);
+    expect(toAgentPayload(manager.getAgent(agentId)!).options).toEqual({});
+  });
+
+  test("an option without a control is settable through the patch and readable in the snapshot", async () => {
+    const { manager, client, storage, agentId } = await createOptionsAgent();
+
+    await manager.setAgentOptions(agentId, { sandbox_mode: "read-only" });
+
+    expect(client.session?.applied).toEqual([{ sandbox_mode: "read-only" }]);
+    const agent = manager.getAgent(agentId);
+    expect(agent?.config.providerOptions).toEqual({ sandbox_mode: "read-only" });
+    expect(toAgentPayload(agent!).options).toEqual({
+      service_tier: "default",
+      sandbox_mode: "read-only",
+    });
+    await manager.flush();
+    expect((await storage.get(agentId))?.config?.providerOptions).toEqual({
+      sandbox_mode: "read-only",
+    });
+  });
+
+  test("overlapping patches reach the provider one after the other, and both land", async () => {
+    const { manager, client, agentId } = await createOptionsAgent();
+    let release!: () => void;
+    client.session!.applyGate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    const slow = manager.setAgentOptions(agentId, { sandbox_mode: "read-only" });
+    const next = manager.setAgentOptions(agentId, { web_search: true });
+    await new Promise<void>((resolve) => setTimeout(resolve, 20));
+    // The second patch waits for the first to be answered: the provider never sees two at once.
+    expect(client.session?.applied).toEqual([]);
+    release();
+    await Promise.all([slow, next]);
+
+    expect(client.session?.applied).toEqual([{ sandbox_mode: "read-only" }, { web_search: true }]);
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({
+      sandbox_mode: "read-only",
+      web_search: true,
+    });
+  });
+
+  test("a stored agent that is not loaded still reports its effective options", async () => {
+    const { manager, agentId } = await createOptionsAgent({ web_search: true });
+    await manager.closeAgent(agentId);
+    const states: ManagedAgent[] = [];
+    manager.subscribe(
+      (event) => {
+        if (event.type === "agent_state" && event.agent.id === agentId) states.push(event.agent);
+      },
+      { replayState: false },
+    );
+
+    await manager.markAgentUnread(agentId);
+
+    expect(states.at(-1)?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("editing a provider default does not change the options of a loaded agent", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: true });
+    expect(manager.getAgent(agentId)?.effectiveOptions).toEqual({
+      service_tier: "default",
+      web_search: true,
+    });
+
+    // The user edits the default in config.json while the agent is running.
+    client.effectiveOptions = (own) => ({ service_tier: "fast", ...own });
+    await manager.markAgentUnread(agentId);
+
+    const agent = manager.getAgent(agentId);
+    expect(agent?.effectiveOptions).toEqual({ service_tier: "default", web_search: true });
+    expect(toAgentPayload(agent!).options).toEqual({ service_tier: "default", web_search: true });
+  });
+
+  test("a provider that rejects an option leaves the stored options unchanged", async () => {
+    const { manager, client, agentId } = await createOptionsAgent({ web_search: false });
+    client.session!.rejectWith = new Error("fast mode unavailable");
+
+    await expect(manager.setAgentOptions(agentId, { web_search: true })).rejects.toThrow(
+      "fast mode unavailable",
+    );
+
+    expect(manager.getAgent(agentId)?.config.providerOptions).toEqual({ web_search: false });
+  });
+
+  test("a provider whose session cannot apply options rejects a patch and stores nothing", async () => {
+    // Like a provider with no live option support: the session has no `applyOptions`.
+    class NoOptionsSession extends TestAgentSession {
+      constructor(config: AgentSessionConfig) {
+        super(config);
+        Object.defineProperty(this, "applyOptions", { value: undefined });
+      }
+    }
+    class NoOptionsClient extends TestAgentClient {
+      override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+        return new NoOptionsSession(config);
+      }
+    }
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-no-options-"));
+    const manager = new AgentManager({
+      clients: { codex: new NoOptionsClient() },
+      registry: new AgentStorage(join(workdir, "agents"), logger),
+      logger,
+    });
+    const agent = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    await expect(manager.setAgentOptions(agent.id, { web_search: true })).rejects.toThrow(
+      /web_search.*cannot change on a running session/,
+    );
+
+    expect(manager.getAgent(agent.id)?.config.providerOptions).toEqual({ web_search: false });
+  });
+
+  test("agent.create.before hook featureValues fold into providerOptions", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        before: async (_name, request) => ({
+          ...request,
+          config: { ...request.config, featureValues: { web_search: true } },
+        }),
+      },
+    });
+
+    const created = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({ web_search: true });
+    expect(manager.getAgent(created.id)?.config).not.toHaveProperty("featureValues");
+  });
+
+  test("agent.create.before hook featureValues edit overrides an option the create already set", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        // A plugin written against the previous SDK: flips one value, leaves the rest.
+        before: async (name, request) =>
+          name === "agent.create.before"
+            ? {
+                ...request,
+                config: {
+                  ...request.config,
+                  featureValues: { ...request.config.featureValues, web_search: true },
+                },
+              }
+            : request,
+      },
+    });
+
+    const created = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false, plan_mode: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({
+      web_search: true,
+      plan_mode: true,
+    });
+  });
+
+  test("agent.create.before hook leaving featureValues untouched keeps providerOptions edits", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const client = new OptionsClient();
+    const manager = new AgentManager({
+      clients: { codex: client },
+      registry: storage,
+      logger,
+      pluginLifecycle: {
+        emit: () => {},
+        before: async (name, request) =>
+          name === "agent.create.before"
+            ? {
+                ...request,
+                config: {
+                  ...request.config,
+                  providerOptions: { ...request.config.providerOptions, plan_mode: false },
+                },
+              }
+            : request,
+      },
+    });
+
+    const created = await manager.createAgent(
+      { provider: "codex", cwd: workdir, providerOptions: { web_search: false, plan_mode: true } },
+      undefined,
+      { workspaceId: undefined },
+    );
+
+    expect(manager.getAgent(created.id)?.config.providerOptions).toEqual({
+      web_search: false,
+      plan_mode: false,
+    });
+  });
+
+  describe.each([
+    {
+      name: "deletes a key",
+      edit: (values: Record<string, unknown> | undefined) => {
+        const { web_search: _removed, ...rest } = values ?? {};
+        return { featureValues: rest };
+      },
+      expected: { plan_mode: true },
+    },
+    {
+      name: "empties featureValues",
+      edit: () => ({ featureValues: {} }),
+      expected: {},
+    },
+    {
+      name: "drops featureValues",
+      edit: () => ({ featureValues: undefined }),
+      expected: {},
+    },
+  ])("agent.create.before hook that $name", ({ edit, expected }) => {
+    test("removes those options from the new agent", async () => {
+      const workdir = mkdtempSync(join(tmpdir(), "agent-manager-hook-"));
+      const manager = new AgentManager({
+        clients: { codex: new OptionsClient() },
+        registry: new AgentStorage(join(workdir, "agents"), logger),
+        logger,
+        pluginLifecycle: {
+          emit: () => {},
+          before: async (name, request) =>
+            name === "agent.create.before"
+              ? {
+                  ...request,
+                  config: { ...request.config, ...edit(request.config.featureValues) },
+                }
+              : request,
+        },
+      });
+
+      const created = await manager.createAgent(
+        { provider: "codex", cwd: workdir, providerOptions: { web_search: true, plan_mode: true } },
+        undefined,
+        { workspaceId: undefined },
+      );
+
+      expect(manager.getAgent(created.id)?.config.providerOptions).toEqual(expected);
+    });
+  });
+});
+
+test("folds provider background work and clears it when the agent closes", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-background-work-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  let activeSession: TestAgentSession | null = null;
+  class BackgroundWorkClient extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      activeSession = new TestAgentSession(config);
+      return activeSession;
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new BackgroundWorkClient() },
+    registry: storage,
+    logger,
+    idFactory: () => "00000000-0000-4000-8000-000000000201",
+  });
+  const snapshot = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  const events: AgentManagerEvent[] = [];
+  manager.subscribe((event) => events.push(event), { agentId: snapshot.id, replayState: false });
+
+  activeSession?.pushEvent({
+    type: "background_work",
+    provider: "codex",
+    items: [{ id: "bash-1", kind: "shell", description: "sleep 20" }],
+  });
+
+  await vi.waitFor(() =>
+    expect(manager.listAgentBackgroundWork(snapshot.id)).toEqual([
+      { id: "bash-1", kind: "shell", description: "sleep 20", startedAt: expect.any(String) },
+    ]),
+  );
+  expect(events).toContainEqual({
+    type: "background_work",
+    agentId: snapshot.id,
+    items: [expect.objectContaining({ id: "bash-1" })],
+  });
+  expect(manager.getAgent(snapshot.id)?.lifecycle).toBe("idle");
+  expect(manager.getAgentBackgroundWorkSummary(snapshot.id)).toEqual({ count: 1 });
+  expect(
+    events.some((event) => event.type === "agent_stream" && event.event.type === "background_work"),
+  ).toBe(false);
+
+  await manager.closeAgent(snapshot.id);
+
+  expect(events).toContainEqual({ type: "background_work", agentId: snapshot.id, items: [] });
+  expect(manager.getAgentBackgroundWorkSummary(snapshot.id)).toBeUndefined();
+});
+
+test("does not deliver an internal agent's background work to global subscribers", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-background-work-internal-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  let activeSession: TestAgentSession | null = null;
+  class BackgroundWorkClient extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      activeSession = new TestAgentSession(config);
+      return activeSession;
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new BackgroundWorkClient() },
+    registry: storage,
+    logger,
+    idFactory: () => "00000000-0000-4000-8000-000000000202",
+  });
+  const events: AgentManagerEvent[] = [];
+  manager.subscribe((event) => events.push(event), { replayState: false });
+  const agent = await manager.createAgent(
+    { provider: "codex", cwd: workdir, internal: true },
+    undefined,
+    { workspaceId: undefined },
+  );
+  const agentEvents: AgentManagerEvent[] = [];
+  manager.subscribe((event) => agentEvents.push(event), {
+    agentId: agent.id,
+    replayState: false,
+  });
+
+  activeSession?.pushEvent({
+    type: "background_work",
+    provider: "codex",
+    items: [{ id: "bash-1", kind: "shell", description: null }],
+  });
+  // The per-agent subscriber proves the event was emitted before the global one is checked.
+  await vi.waitFor(() =>
+    expect(agentEvents).toContainEqual(
+      expect.objectContaining({ type: "background_work", agentId: agent.id }),
+    ),
+  );
+
+  expect(events.some((event) => event.type === "background_work")).toBe(false);
+  await expect(
+    manager.stopAgentBackgroundWork({ agentId: agent.id, itemId: "bash-1", stopToken: "token" }),
+  ).rejects.toThrow("Unknown agent");
+});
+
+test("stops only a currently owned public background item with its current token", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-background-stop-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const stopped: string[] = [];
+  let activeSession: TestAgentSession | null = null;
+  class StoppableSession extends TestAgentSession {
+    async stopBackgroundWork(id: string) {
+      stopped.push(id);
+    }
+  }
+  class BackgroundWorkClient extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+      activeSession = new StoppableSession(config);
+      return activeSession;
+    }
+  }
+  const manager = new AgentManager({
+    clients: { codex: new BackgroundWorkClient() },
+    registry: storage,
+    logger,
+    idFactory: () => "00000000-0000-4000-8000-000000000204",
+  });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  activeSession?.pushEvent({
+    type: "background_work",
+    provider: "codex",
+    items: [
+      { id: "one", kind: "shell", description: null, canStop: true },
+      { id: "two", kind: "other", description: null },
+    ],
+  });
+  await vi.waitFor(() => expect(manager.listAgentBackgroundWork(agent.id)).toHaveLength(2));
+  const [one] = manager.listAgentBackgroundWork(agent.id);
+  await expect(
+    manager.stopAgentBackgroundWork({ agentId: agent.id, itemId: "one", stopToken: "stale-token" }),
+  ).rejects.toThrow();
+  await expect(
+    manager.stopAgentBackgroundWork({
+      agentId: agent.id,
+      itemId: "two",
+      stopToken: one.stopToken!,
+    }),
+  ).rejects.toThrow();
+  await manager.stopAgentBackgroundWork({
+    agentId: agent.id,
+    itemId: "one",
+    stopToken: one.stopToken!,
+  });
+  expect(stopped).toEqual(["one"]);
+  activeSession?.pushEvent({
+    type: "background_work",
+    provider: "codex",
+    items: [{ id: "one", kind: "shell", description: null }],
+  });
+  activeSession?.pushEvent({
+    type: "background_work",
+    provider: "codex",
+    items: [{ id: "one", kind: "shell", description: null, canStop: true }],
+  });
+  await expect(
+    manager.stopAgentBackgroundWork({
+      agentId: agent.id,
+      itemId: "one",
+      stopToken: one.stopToken!,
+    }),
+  ).rejects.toThrow();
+  expect(stopped).toEqual(["one"]);
+  await manager.closeAgent(agent.id);
+});
+
+test("turns keep distinct identities across an idle runtime collection and resume", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-turn-identity-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const client = new TestAgentClient();
+  const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+  const collect = runtimeCleanup(manager);
+  try {
+    const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+    const consume = async (prompt: string, clientMessageId: string) => {
+      for await (const _event of manager.streamAgent(agent.id, prompt, { clientMessageId })) {
+      }
+    };
+    await consume("first", "first");
+    const later = new Date(Date.now() + 61 * 60_000);
+    expect((await collect({ now: later })).collected).toHaveLength(1);
+    await ensureAgentLoaded(agent.id, { agentManager: manager, agentStorage: storage, logger });
+    await consume("second", "second");
+    const rows = (await manager.fetchTimeline(agent.id, { limit: 0 })).rows;
+    const userTurnIds = rows
+      .filter((row) => row.item.type === "user_message")
+      .map((row) => row.turnId);
+    expect(userTurnIds).toHaveLength(2);
+    expect(new Set(userTurnIds).size).toBe(2);
+  } finally {
+    await manager.closeAgent(manager.listAgents()[0]?.id ?? "missing").catch(() => undefined);
+    await storage.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/agent-manager.ts b/packages/server/src/server/agent/agent-manager.ts
index bd1817733a..88b66608e0 100644
--- a/packages/server/src/server/agent/agent-manager.ts
+++ b/packages/server/src/server/agent/agent-manager.ts
@@ -1,9 +1,11 @@
 import type { AttachedAgentTool, PluginAgentToolsRuntime } from "../plugins/agent-tools.js";
+import { ProviderOptionsValidationError } from "./provider-options.js";
 import type { AgentToolResult } from "@getpaseo/plugin/server";
 import type { RuntimeCleanupCandidate } from "./idle-runtime-cleanup/index.js";
-import { ensureAgentLoaded } from "./agent-loading.js";
+import { AgentNotFoundError, ensureAgentLoaded } from "./agent-loading.js";
 import type { PluginLifecycle } from "../plugins/lifecycle/index.js";
 import { describeHookAgent, publishAgentStream } from "../plugins/lifecycle/index.js";
+import { applyRecordPatch } from "../record-patch.js";
 import type { PluginSessionOpenRequest } from "@getpaseo/plugin/server";
 import { randomUUID } from "node:crypto";
 import { basename, resolve } from "node:path";
@@ -32,7 +34,8 @@ import {
   type AgentCreateSessionOptions,
   type AgentResumePurpose,
   type AgentResumeSessionOptions,
-  type AgentFeature,
+  type AgentDraftControls,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentSlashCommand,
   type AgentMode,
@@ -60,7 +63,17 @@ import {
   RewindNotAppliedError,
 } from "./agent-sdk-types.js";
 import { buildArchivedAgentRecord, type ArchivedStoredAgentRecord } from "./agent-archive.js";
+import type { JsonValue, ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { toStoredAgentRecord } from "./agent-projections.js";
+import {
+  applyProviderOptionsPatch,
+  exposeFeatureValuesToHook,
+  convertLegacyOptions,
+  MalformedLegacyOptionError,
+  resolveAdapter,
+  foldHookFeatureValues,
+  type ProviderOptionsPatch,
+} from "./option-controls.js";
 import type { StoredAgentRecord, AgentStorage } from "./agent-storage.js";
 import type { AgentOwner } from "./agent-owner.js";
 import type {
@@ -109,8 +122,9 @@ import {
   type ProviderSubagentDescriptor,
   type ProviderSubagentStoreEvent,
 } from "./provider-subagents/store.js";
+import { AgentBackgroundWorkStore, type AgentBackgroundWorkItem } from "./background-work/index.js";
 import { withTimeout } from "../../utils/promise-timeout.js";
-import { extractAttention } from "../persistence-hooks.js";
+import { buildSessionConfig, extractAttention } from "../persistence-hooks.js";
 
 const RELOAD_SESSION_CLOSE_TIMEOUT_MS = 3_000;
 const INTERRUPT_SESSION_TIMEOUT_MS = 2_000;
@@ -185,6 +199,29 @@ async function assertUsableWorkingDirectory(cwd: string): Promise<void> {
   }
 }
 
+interface StopAgentBackgroundWorkOptions {
+  agentId: string;
+  itemId: string;
+  stopToken: string;
+}
+
+async function resolveResumePurpose(
+  record: StoredAgentRecord | null,
+  requested: AgentResumePurpose | undefined,
+  cwd: string,
+): Promise<AgentResumePurpose> {
+  if (!record) return requested ?? "interactive";
+  if (record.archivedAt) return "history";
+  if (requested !== "history") return "interactive";
+  try {
+    await stat(cwd);
+    return "interactive";
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "history";
+    throw error;
+  }
+}
+
 interface PreparedSessionConfig {
   storedConfig: AgentSessionConfig;
   launchConfig: AgentSessionConfig;
@@ -224,9 +261,6 @@ function buildStoredAgentConfig(record: StoredAgentRecord): AgentSessionConfig {
   if (record.config.thinkingOptionId != null) {
     config.thinkingOptionId = record.config.thinkingOptionId;
   }
-  if (record.config.featureValues != null) {
-    config.featureValues = record.config.featureValues;
-  }
   if (record.config.providerOptions != null) {
     config.providerOptions = record.config.providerOptions;
   }
@@ -262,6 +296,7 @@ export type AgentManagerEvent =
       /** Retirements of this history so far, including this one. */
       retirementCount: number;
     }
+  | { type: "background_work"; agentId: string; items: AgentBackgroundWorkItem[] }
   | {
       type: "agent_stream";
       agentId: string;
@@ -350,6 +385,7 @@ type ProviderClientMap = Partial<Record<AgentProvider, AgentClient>>;
 
 export interface CreateAgentOptions {
   labels?: Record<string, string>;
+  metadata?: AgentMetadata;
   initialPrompt?: string;
   env?: Record<string, string>;
   persistSession?: boolean;
@@ -357,6 +393,8 @@ export interface CreateAgentOptions {
   // undefined is an explicit decision: the agent never appears in the sidebar.
   workspaceId: string | undefined;
   owner?: AgentOwner;
+  /** Background agents stay out of discovery, tabs, tracks and attention. Fixed at creation. */
+  background?: boolean;
 }
 
 export interface AgentManagerOptions {
@@ -419,6 +457,18 @@ export type AttentionState =
       attentionTimestamp: Date;
     };
 
+/** Private helpers and background agents report to their creator, never to the user. */
+function raisesAttention(agent: Pick<ManagedAgent, "internal" | "background">): boolean {
+  return !agent.internal && !agent.background;
+}
+
+/** The attention a read agent gets back when marked unread; null while it is still working. */
+function unreadAttentionReason(status: AgentLifecycleStatus): "finished" | "error" | null {
+  if (status === "idle" || status === "closed") return "finished";
+  if (status === "error") return "error";
+  return null;
+}
+
 function resolveInitialAttention(input: AttentionState | undefined): AttentionState {
   if (input == null || !input.requiresAttention) {
     return { requiresAttention: false };
@@ -460,7 +510,9 @@ interface ManagedAgentBase {
   createdAt: Date;
   updatedAt: Date;
   availableModes: AgentMode[];
-  features?: AgentFeature[];
+  controls?: AgentOptionControl[];
+  /** `config.json` defaults deep-merged with `config.providerOptions`; refreshed on every state emit. */
+  effectiveOptions?: ProviderOptions;
   currentModeId: string | null;
   pendingPermissions: Map<string, AgentPermissionRequest>;
   bufferedPermissionResolutions: Map<
@@ -488,10 +540,17 @@ interface ManagedAgentBase {
    * Internal agents are hidden from listings and don't trigger notifications.
    */
   internal?: boolean;
+  /**
+   * Background agents are durable but hidden from default discovery and never raise attention.
+   * Fixed at creation.
+   */
+  background?: boolean;
   /**
    * User-defined labels for categorizing agents (e.g., { surface: "workspace" }).
    */
   labels: Record<string, string>;
+  /** Plugin-owned data. Paseo persists and forwards it and never reads a key. */
+  metadata: AgentMetadata;
 }
 
 type ManagedAgentWithSession = ManagedAgentBase & {
@@ -551,6 +610,7 @@ type ActiveManagedAgent =
 
 type LiveManagedAgent = ActiveManagedAgent;
 type AgentLabelPatch = Record<string, string | null>;
+type AgentMetadata = Record<string, JsonValue>;
 
 function attachManagedTurnIdentity(
   agent: ActiveManagedAgent,
@@ -598,6 +658,7 @@ interface WriteLabelsResult {
 interface AgentMetadataPatch {
   title?: string;
   labels?: AgentLabelPatch;
+  metadata?: Record<string, JsonValue | null>;
 }
 
 const SYSTEM_ERROR_PREFIX = "[System Error]";
@@ -657,6 +718,41 @@ function createAbortError(signal: AbortSignal | undefined, fallbackMessage: stri
   return Object.assign(new Error(message), { name: "AbortError" });
 }
 
+/** The user labels and plugin metadata an agent carries; both default to empty. */
+function agentEntityData(source?: { labels?: Record<string, string>; metadata?: AgentMetadata }) {
+  return { labels: source?.labels ?? {}, metadata: source?.metadata ?? {} };
+}
+
+// PASEO_WORKSPACE_ID lets an agent rename or archive its own workspace; several workspaces can
+// share one cwd, so the agent can't work it out from PASEO_AGENT_CWD.
+function agentIdentityEnv({
+  agentId,
+  cwd,
+  opening,
+}: {
+  agentId: string;
+  cwd: string;
+  opening: { workspaceId?: string | null } | undefined;
+}): Record<string, string> {
+  const workspaceId = opening?.workspaceId;
+  return {
+    PASEO_AGENT_ID: agentId,
+    PASEO_AGENT_CWD: cwd,
+    ...(workspaceId ? { PASEO_WORKSPACE_ID: workspaceId } : {}),
+  };
+}
+
+// Launch env and the registered agent must agree, or the next snapshot erases the stored workspace.
+function resolveResumeWorkspaceId({
+  options,
+  record,
+}: {
+  options: { workspaceId?: string } | undefined;
+  record: Pick<StoredAgentRecord, "workspaceId"> | null;
+}): string | undefined {
+  return options?.workspaceId ?? record?.workspaceId;
+}
+
 function validateAgentId(agentId: string, source: string): string {
   const result = AgentIdSchema.safeParse(agentId);
   if (!result.success) {
@@ -665,21 +761,6 @@ function validateAgentId(agentId: string, source: string): string {
   return result.data;
 }
 
-function applyLabelPatch(
-  labels: Record<string, string>,
-  patch: AgentLabelPatch,
-): Record<string, string> {
-  const nextLabels = { ...labels };
-  for (const [key, value] of Object.entries(patch)) {
-    if (value === null) {
-      delete nextLabels[key];
-    } else {
-      nextLabels[key] = value;
-    }
-  }
-  return nextLabels;
-}
-
 function buildExplicitTimelineSeedForRegister(
   now: Date,
   options:
@@ -810,6 +891,7 @@ export class AgentManager {
    * activity and idle cleanup read this instead.
    */
   private readonly runningProviderSubagents = new Map<string, Set<string>>();
+  private readonly backgroundWork = new AgentBackgroundWorkStore();
   private readonly agentsAwaitingInitialSnapshotPersist = new Set<string>();
   private readonly sessionEventTails = new Map<string, Promise<void>>();
   private readonly steerEventBarriers = new Map<string, SteerEventBarrier>();
@@ -822,6 +904,7 @@ export class AgentManager {
   private readonly backgroundTasks = new Set<Promise<void>>();
   private readonly agentRegistrationTasks = new Set<Promise<void>>();
   private readonly inFlightAgentCloses = new Map<string, Promise<void>>();
+  private readonly historySessions = new WeakSet<AgentSession>();
   private readonly reloadedSessionCloses = new WeakMap<AgentSession, Promise<void>>();
   private readonly runtimeCleanupIdentities = new WeakMap<AgentSession, object>();
   private readonly collectingRuntimes = new Set<string>();
@@ -1298,11 +1381,15 @@ export class AgentManager {
     }
   }
 
-  async listDraftFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+  async listDraftControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
     const normalizedConfig = await this.normalizeConfig(config, { resolveDefaultModel: false });
     const client = this.requireClient(normalizedConfig.provider);
-    if (!normalizedConfig.model && !client.listFeatures) {
-      return [];
+    const options = this.effectiveOptionsFor(
+      normalizedConfig.provider,
+      normalizedConfig.providerOptions,
+    );
+    if (!normalizedConfig.model && !client.listControls) {
+      return { controls: [], options };
     }
     const available = await client.isAvailable();
     if (!available) {
@@ -1311,13 +1398,18 @@ export class AgentManager {
       );
     }
 
-    if (client.listFeatures) {
-      return await client.listFeatures(normalizedConfig);
+    if (client.listControls) {
+      return await client.listControls(normalizedConfig);
     }
 
     const session = await client.createSession(normalizedConfig);
     try {
-      return session.features ?? [];
+      // The options a session opens with, as create would report them, so the controls'
+      // selection matches what the first turn runs with.
+      return {
+        controls: session.controls ?? [],
+        options: this.openedEffectiveOptions({ session, launchedOptions: options }),
+      };
     } finally {
       try {
         await session.close();
@@ -1357,6 +1449,22 @@ export class AgentManager {
     return await this.timeline.readRows({ agentId: id });
   }
 
+  /**
+   * The timeline head of a loaded agent, or null when this agent is not loaded. Never loads.
+   * `seq` is the last committed sequence number, a retirement's included.
+   */
+  async getLoadedTimelineHead(
+    id: string,
+  ): Promise<{ epoch: string; seq: number; retirementCount: number } | null> {
+    if (!this.getAgent(id)) return null;
+    const page = await this.timeline.fetch({ agentId: id }, { direction: "tail", limit: 0 });
+    return {
+      epoch: page.epoch,
+      seq: page.window.nextSeq - 1,
+      retirementCount: page.retirementCount,
+    };
+  }
+
   async fetchTimeline(
     id: string,
     options?: AgentTimelineFetchOptions,
@@ -1370,6 +1478,38 @@ export class AgentManager {
     return await this.providerSubagents.list(parentAgentId);
   }
 
+  listAgentBackgroundWork(agentId: string): AgentBackgroundWorkItem[] {
+    this.requirePublicAgent(agentId);
+    return this.backgroundWork.list(agentId);
+  }
+
+  async stopAgentBackgroundWork({
+    agentId,
+    itemId,
+    stopToken,
+  }: StopAgentBackgroundWorkOptions): Promise<void> {
+    this.requirePublicAgent(agentId);
+    // Inventory events share the session queue; drain events already received before
+    // authorizing the token, including a reconnect's ownership revocation.
+    await this.sessionEventTails.get(agentId)?.catch(() => undefined);
+    const agent = this.requirePublicAgent(agentId);
+    if (!agent.session || !agent.session.stopBackgroundWork)
+      throw new Error("Background work cannot be stopped");
+    const item = this.backgroundWork.list(agentId).find((entry) => entry.id === itemId);
+    if (!item?.canStop || item.stopToken !== stopToken)
+      throw new Error("Background work is no longer available to stop");
+    await agent.session.stopBackgroundWork(itemId);
+  }
+
+  getAgentBackgroundWorkSummary(agentId: string): { count: number } | undefined {
+    return this.backgroundWork.summary(agentId);
+  }
+
+  private clearBackgroundWork(agentId: string): void {
+    const items = this.backgroundWork.clear(agentId);
+    if (items) this.dispatch({ type: "background_work", agentId, items });
+  }
+
   /** The children each loaded public agent's current runtime reports running. */
   async listProviderSubagentActivity(): Promise<ProviderSubagentDescriptor[]> {
     const publicParents = Array.from(this.agents.values()).filter((agent) => !agent.internal);
@@ -1401,28 +1541,75 @@ export class AgentManager {
     return this.providerSubagents.fetchTimeline(parentAgentId, subagentId, options);
   }
 
-  createAgent(
+  async createAgent(
     config: AgentSessionConfig,
     agentId: string | undefined,
     options: CreateAgentOptions,
   ): Promise<ManagedAgent> {
-    return this.trackAgentRegistrationOperation(this.createAgentInternal(config, agentId, options));
+    const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "createAgent");
+    return this.trackAgentRegistrationOperation(
+      this.runLifecycleMutation(resolvedAgentId, () =>
+        this.createAgentInternal(config, resolvedAgentId, options),
+      ),
+    );
+  }
+
+  /**
+   * Opens a stored agent whose provider left no session to resume: its first session, created
+   * from the record as it is when the lane reaches it. A write queued ahead (`setMetadata`,
+   * `setLabels`) is in that record; one queued behind applies to the live agent.
+   */
+  createAgentFromRecord(agentId: string): Promise<ManagedAgent> {
+    const resolvedAgentId = validateAgentId(agentId, "createAgentFromRecord");
+    return this.trackAgentRegistrationOperation(
+      this.runLifecycleMutation(resolvedAgentId, async () => {
+        const record = await this.requireRegistry().get(resolvedAgentId);
+        if (!record) throw new AgentNotFoundError(resolvedAgentId);
+        const config = buildSessionConfig(record, {
+          validProviders: this.getRegisteredProviderIds(),
+        });
+        if (!config) {
+          throw new Error(
+            `Agent ${resolvedAgentId} references unavailable provider '${record.provider}'`,
+          );
+        }
+        return this.createAgentInternal(config, resolvedAgentId, {
+          labels: record.labels,
+          metadata: record.metadata,
+          workspaceId: record.workspaceId,
+          owner: record.owner,
+          background: record.background,
+          env: record.launchEnv,
+        });
+      }),
+    );
   }
 
   private async createAgentInternal(
     config: AgentSessionConfig,
-    agentId: string | undefined,
+    resolvedAgentId: string,
     options: CreateAgentOptions,
   ): Promise<ManagedAgent> {
     this.assertAcceptingAgentRegistrations();
-    const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "createAgent");
+    config = this.withConvertedOptions(config);
     if (this.pluginLifecycle && !config.internal) {
+      const sent = exposeFeatureValuesToHook(config);
       const request = await this.pluginLifecycle.before("agent.create.before", {
-        config,
+        config: sent,
         env: options.env,
+        metadata: options.metadata ?? {},
       });
-      config = { ...request.config, internal: config.internal };
-      options = { ...options, env: request.env };
+      // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. A plugin written
+      // against the previous SDK edits `config.featureValues`.
+      config = {
+        ...foldHookFeatureValues({
+          returned: request.config,
+          sent,
+          convert: (values) => this.convertLegacyOptions(request.config.provider, values),
+        }),
+        internal: config.internal,
+      };
+      options = { ...options, env: request.env, metadata: request.metadata ?? options.metadata };
     }
     await this.deleteAgentState(resolvedAgentId);
     const { storedConfig, launchConfig, paseoToolPolicy } = await this.prepareSessionConfig(
@@ -1447,17 +1634,22 @@ export class AgentManager {
         workspaceId: options.workspaceId ?? null,
         title: options.initialTitle ?? storedConfig.title ?? null,
         labels: options.labels ?? {},
+        metadata: options.metadata ?? {},
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     const createOptions = this.buildCreateSessionOptions(options);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const session = await client.createSession(providerLaunchConfig, launchContext, createOptions);
     await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     const agent = await this.registerSession(session, storedConfig, resolvedAgentId, {
+      launchedOptions,
       labels: options.labels,
+      metadata: options.metadata,
       initialTitle: options.initialTitle,
       workspaceId: options.workspaceId,
       owner: options.owner,
+      background: options.background,
       launchEnv: options.env ? { ...options.env } : undefined,
     });
     if (!agent.internal) {
@@ -1487,8 +1679,10 @@ export class AgentManager {
       updatedAt?: Date;
       lastUserMessageAt?: Date | null;
       labels?: Record<string, string>;
+      metadata?: AgentMetadata;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
       attention?: AttentionState;
     },
     resumeOptions?: AgentResumeSessionOptions,
@@ -1519,8 +1713,10 @@ export class AgentManager {
       updatedAt?: Date;
       lastUserMessageAt?: Date | null;
       labels?: Record<string, string>;
+      metadata?: AgentMetadata;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
       attention?: AttentionState;
     },
     resumeOptions?: AgentResumeSessionOptions,
@@ -1541,12 +1737,11 @@ export class AgentManager {
     // settled before the config is prepared, because a history load reads an archived
     // agent whose working directory may be gone.
     const record = this.registry ? await this.registry.get(resolvedAgentId) : null;
-    const currentResumeOptions = record
-      ? { purpose: record.archivedAt ? ("history" as const) : ("interactive" as const) }
-      : resumeOptions;
-    const purpose = currentResumeOptions?.purpose ?? "interactive";
+    const purpose = await resolveResumePurpose(record, resumeOptions?.purpose, mergedConfig.cwd);
+    const currentResumeOptions = { purpose } satisfies AgentResumeSessionOptions;
 
     const launchEnv = record?.launchEnv;
+    const workspaceId = resolveResumeWorkspaceId({ options, record });
     const { storedConfig, launchConfig, paseoToolPolicy } = await this.prepareSessionConfig(
       mergedConfig,
       resolvedAgentId,
@@ -1569,21 +1764,28 @@ export class AgentManager {
       {
         reason: "resume",
         purpose,
-        workspaceId: options?.workspaceId ?? null,
+        workspaceId,
         title: record?.title ?? mergedConfig.title ?? null,
-        labels: record?.labels ?? options?.labels ?? {},
+        ...agentEntityData(record ?? options),
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const session = await client.resumeSession(
       handle,
       providerLaunchConfig,
       launchContext,
       currentResumeOptions,
     );
+    if (purpose === "history") this.historySessions.add(session);
     await this.requireExternalMcpSupport(session, providerLaunchConfig, launchContext);
     const registered = await this.registerSession(session, storedConfig, resolvedAgentId, {
+      launchedOptions,
       ...options,
+      // The caller read its metadata before this turn in the lane; a setMetadata queued ahead of
+      // it has saved a newer record, the one the open hooks saw.
+      ...(record ? { metadata: record.metadata } : {}),
+      workspaceId,
       launchEnv,
       persistence: handle,
       restoring: true,
@@ -1624,6 +1826,7 @@ export class AgentManager {
         cwd: input.cwd,
       },
       resolvedAgentId,
+      { resolveDefaultModel: false },
     );
     this.paseoToolPolicies.set(resolvedAgentId, paseoToolPolicy);
     const launchContext = await this.buildLaunchContext(
@@ -1640,6 +1843,7 @@ export class AgentManager {
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
+    const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
     const imported = await client.importSession(
       {
         providerHandleId: input.providerHandleId,
@@ -1650,14 +1854,20 @@ export class AgentManager {
     await this.requireExternalMcpSupport(imported.session, providerLaunchConfig, launchContext);
     let handedToRegistration = false;
     try {
+      const runtimeInfo = await imported.session.getRuntimeInfo();
       const importedConfig = await this.normalizeConfig(
-        stripInternalPaseoMcpServer(imported.config),
+        stripInternalPaseoMcpServer({
+          ...imported.config,
+          model: runtimeInfo.model ?? imported.config.model,
+        }),
+        { resolveDefaultModel: false },
       );
       const timelineRows = buildImportedTimelineRows(imported.timeline);
       const initialTitle = resolveImportedAgentTitle(importedConfig, timelineRows);
 
       handedToRegistration = true;
       const agent = await this.registerSession(imported.session, importedConfig, resolvedAgentId, {
+        launchedOptions,
         labels: input.labels,
         workspaceId: input.workspaceId,
         timelineRows,
@@ -1736,6 +1946,7 @@ export class AgentManager {
         workspaceId: existing.workspaceId,
         title: await this.resolveInitialPersistedTitle(agentId, existing.config, null),
         labels: existing.labels,
+        metadata: existing.metadata,
       },
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
@@ -1754,11 +1965,13 @@ export class AgentManager {
       await this.closeReloadedSession(existing.session, agentId);
       await this.drainSessionEvents(agentId);
       await this.cancelRunningProviderSubagents(agentId);
+      this.clearBackgroundWork(agentId);
       closedExisting = await this.prepareAgentForClosure(existing, "agent reloaded");
       await this.persistSnapshot(closedExisting);
       this.assertAcceptingAgentRegistrations();
 
       this.paseoToolPolicies.set(agentId, paseoToolPolicy);
+      const launchedOptions = this.launchOptionsFor({ client, own: storedConfig.providerOptions });
       session = handle
         ? await client.resumeSession(handle, providerLaunchConfig, launchContext)
         : await client.createSession(providerLaunchConfig, launchContext);
@@ -1768,9 +1981,12 @@ export class AgentManager {
       // Preserve existing labels and timeline during reload.
       handedToRegistration = true;
       const registered = this.registerSession(session, storedConfig, agentId, {
+        launchedOptions,
         labels: existing.labels,
+        metadata: existing.metadata,
         workspaceId: existing.workspaceId,
         owner: existing.owner,
+        background: existing.background,
         launchEnv: existing.launchEnv,
         createdAt: existing.createdAt,
         updatedAt: existing.updatedAt,
@@ -1789,6 +2005,7 @@ export class AgentManager {
       } else if (this.agents.get(agentId) === existing) {
         existing.lifecycle = "error";
         existing.lastError = error instanceof Error ? error.message : String(error);
+        this.raiseErrorAttention(existing);
         this.emitState(existing);
       }
       throw error;
@@ -2033,7 +2250,10 @@ export class AgentManager {
     // Retain ownership until shutdown succeeds. A failed close may still own a
     // native writer, so publishing a resumable closed snapshot would orphan it.
     await agent.session.close();
+    await this.drainSessionEvents(agentId);
     await this.cancelRunningProviderSubagents(agentId);
+    // close() drops the session's subscribers before the provider could report an empty list.
+    this.clearBackgroundWork(agentId);
     const closedAgent = await this.prepareAgentForClosure(agent, "agent closed");
 
     let persistError: unknown;
@@ -2139,7 +2359,7 @@ export class AgentManager {
       return;
     }
     const parentAgentId = parent.id;
-    const records = await registry.list();
+    const records = await registry.listActive();
     for (const record of records) {
       if (record.archivedAt) {
         continue;
@@ -2161,7 +2381,10 @@ export class AgentManager {
           return;
         }
         if (shouldDetachFromArchivedParent(parent, currentChild)) {
-          await this.detachAgentUnlocked(currentChild.id);
+          const detached = await this.detachAgentUnlocked(currentChild.id);
+          if (!detached.live) {
+            this.dispatchStoredAgentState(detached.record);
+          }
         } else if (this.agents.has(currentChild.id)) {
           await this.archiveAgentUnlocked(currentChild.id);
         } else {
@@ -2247,12 +2470,16 @@ export class AgentManager {
         session: null,
         capabilities: STORED_AGENT_CAPABILITIES,
         config: buildStoredAgentConfig(record),
-        runtimeInfo: undefined,
+        runtimeInfo: record.runtimeInfo,
         lifecycle: "closed",
         createdAt: new Date(record.createdAt),
         updatedAt,
         availableModes: [],
-        features: record.features,
+        controls: record.controls,
+        effectiveOptions: this.effectiveOptionsFor(
+          record.provider,
+          record.config?.providerOptions ?? undefined,
+        ),
         currentModeId: record.lastModeId ?? null,
         pendingPermissions: new Map(),
         bufferedPermissionResolutions: new Map(),
@@ -2270,92 +2497,222 @@ export class AgentManager {
         lastError: record.lastError ?? undefined,
         attention,
         internal: record.internal,
+        background: record.background,
         labels: record.labels,
+        metadata: record.metadata,
       },
     });
   }
 
+  // Mode, model, thinking and options change inside the agent's lifecycle lane, like every other
+  // mutation of one agent. A provider session therefore never has two of `setMode`, `setModel`,
+  // `setThinkingOption` and `applyOptions` in flight at once, and none of them overlaps an open,
+  // reload or close; providers do no sequencing of their own.
+
   async setAgentMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null> {
-    const agent = this.requireSessionAgent(agentId);
-    const notice = (await agent.session.setMode(modeId)) ?? null;
-    await this.drainSessionEvents(agentId);
-    const currentMode = (await agent.session.getCurrentMode()) ?? modeId;
-    agent.config.modeId = currentMode ?? undefined;
-    agent.currentModeId = currentMode;
-    // Update runtimeInfo to reflect the new mode
-    if (agent.runtimeInfo) {
-      agent.runtimeInfo = { ...agent.runtimeInfo, modeId: currentMode };
-    }
-    this.touchUpdatedAt(agent);
-    this.emitState(agent);
-    return notice;
+    return this.runLifecycleMutation(agentId, async () => {
+      const agent = await this.ensureInteractiveSessionUnlocked(agentId);
+      const notice = (await agent.session.setMode(modeId)) ?? null;
+      await this.drainSessionEvents(agentId);
+      const currentMode = (await agent.session.getCurrentMode()) ?? modeId;
+      agent.config.modeId = currentMode ?? undefined;
+      agent.currentModeId = currentMode;
+      // Update runtimeInfo to reflect the new mode
+      if (agent.runtimeInfo) {
+        agent.runtimeInfo = { ...agent.runtimeInfo, modeId: currentMode };
+      }
+      this.touchUpdatedAt(agent);
+      this.emitState(agent);
+      return notice;
+    });
   }
 
   async setAgentModel(agentId: string, modelId: string | null): Promise<void> {
-    const agent = this.requireSessionAgent(agentId);
-    const normalizedModelId =
-      typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
+    return this.runLifecycleMutation(agentId, async () => {
+      const agent = await this.ensureInteractiveSessionUnlocked(agentId);
+      const normalizedModelId =
+        typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
 
-    if (agent.session.setModel) {
-      await agent.session.setModel(normalizedModelId);
-    }
-    await this.drainSessionEvents(agentId);
+      const selection = await agent.session.setModel?.(normalizedModelId);
+      await this.drainSessionEvents(agentId);
 
-    agent.config.model = normalizedModelId ?? undefined;
-    if (agent.runtimeInfo) {
-      agent.runtimeInfo = { ...agent.runtimeInfo, model: normalizedModelId };
-    }
-    this.refreshSessionPersistence(agent);
-    this.touchUpdatedAt(agent);
-    this.emitState(agent);
+      // A reset clears the preference even when the provider retains its active model.
+      let effectiveModelId = normalizedModelId;
+      if (normalizedModelId !== null && selection) effectiveModelId = selection.model;
+
+      agent.config.model = effectiveModelId ?? undefined;
+      if (agent.runtimeInfo) {
+        agent.runtimeInfo = { ...agent.runtimeInfo, model: effectiveModelId };
+      }
+      this.refreshSessionPersistence(agent);
+      this.touchUpdatedAt(agent);
+      this.emitState(agent);
+    });
   }
 
   async setAgentThinkingOption(
     agentId: string,
     thinkingOptionId: string | null,
   ): Promise<AgentProviderNotice | null> {
-    const agent = this.requireSessionAgent(agentId);
-    const normalizedThinkingOptionId =
-      typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
-        ? thinkingOptionId
-        : null;
+    return this.runLifecycleMutation(agentId, async () => {
+      const agent = await this.ensureInteractiveSessionUnlocked(agentId);
+      const normalizedThinkingOptionId =
+        typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
+          ? thinkingOptionId
+          : null;
 
-    let notice: AgentProviderNotice | null = null;
-    if (agent.session.setThinkingOption) {
-      notice = (await agent.session.setThinkingOption(normalizedThinkingOptionId)) ?? null;
-    }
-    await this.drainSessionEvents(agentId);
+      let notice: AgentProviderNotice | null = null;
+      if (agent.session.setThinkingOption) {
+        notice = (await agent.session.setThinkingOption(normalizedThinkingOptionId)) ?? null;
+      }
+      await this.drainSessionEvents(agentId);
 
-    let effectiveThinkingOptionId = normalizedThinkingOptionId;
-    const runtimeInfo = await agent.session.getRuntimeInfo();
-    if (runtimeInfo.thinkingOptionId !== undefined) {
-      effectiveThinkingOptionId = runtimeInfo.thinkingOptionId;
-    }
+      let effectiveThinkingOptionId = normalizedThinkingOptionId;
+      const runtimeInfo = await agent.session.getRuntimeInfo();
+      if (runtimeInfo.thinkingOptionId !== undefined) {
+        effectiveThinkingOptionId = runtimeInfo.thinkingOptionId;
+      }
 
-    agent.config.thinkingOptionId = effectiveThinkingOptionId ?? undefined;
-    if (agent.runtimeInfo) {
-      agent.runtimeInfo = {
-        ...agent.runtimeInfo,
-        thinkingOptionId: effectiveThinkingOptionId,
-      };
-    }
-    this.touchUpdatedAt(agent);
-    this.emitState(agent);
-    return notice;
+      agent.config.thinkingOptionId = effectiveThinkingOptionId ?? undefined;
+      if (agent.runtimeInfo) {
+        agent.runtimeInfo = {
+          ...agent.runtimeInfo,
+          thinkingOptionId: effectiveThinkingOptionId,
+        };
+      }
+      this.touchUpdatedAt(agent);
+      this.emitState(agent);
+      return notice;
+    });
   }
 
-  async setAgentFeature(agentId: string, featureId: string, value: unknown): Promise<void> {
-    const agent = this.requireAgent(agentId);
+  /**
+   * Applies an options patch to a running agent (see `AgentSession.applyOptions`). The provider
+   * gets each key the patch touches, resolved against the `config.json` defaults, with `null`
+   * where nothing is set. The patch and whatever the provider says it ended up with are stored in
+   * one step once the provider accepts. Patches to one agent run one at a time, in arrival order.
+   */
+  async setAgentOptions(agentId: string, requested: ProviderOptionsPatch): Promise<void> {
+    return this.runLifecycleMutation(agentId, async () => {
+      const agent = await this.ensureInteractiveSessionUnlocked(agentId);
+      const patch = this.convertLegacyOptions(agent.provider, requested);
+      let ended: ProviderOptionsPatch = {};
+      let sent: ProviderOptionsPatch = {};
+      if (Object.keys(patch).length > 0) {
+        // A provider that cannot apply options to a running agent must not store them either.
+        if (!agent.session.applyOptions) {
+          throw new ProviderOptionsValidationError(
+            agent.provider,
+            Object.keys(patch).map((key) => ({
+              path: [key],
+              message: "cannot change on a running session; it applies when the agent is opened",
+            })),
+          );
+        }
+        const set = Object.fromEntries(Object.entries(patch).filter(([, value]) => value != null));
+        const resolved = this.effectiveOptionsFor(agent.provider, set);
+        sent = Object.fromEntries(Object.keys(patch).map((key) => [key, resolved[key] ?? null]));
+        const modelBefore = agent.runtimeInfo?.model;
+        ended = (await agent.session.applyOptions(sent)) ?? {};
+        // Changes the provider made on its own while applying are older than its final answer.
+        await this.drainSessionEvents(agentId);
+        await this.refreshRuntimeInfo(agent, { emit: false });
+        // An option can choose the model too, as an fx connection does. Reopening the agent on
+        // the earlier preference would send that model to the new connection.
+        const modelAfter = agent.runtimeInfo?.model;
+        if (agent.config.model && modelAfter && modelAfter !== modelBefore) {
+          agent.config.model = modelAfter;
+        }
+      }
+      this.storeOptionsPatch({ agent, patch: { ...patch, ...ended } });
+      this.updateEffectiveOptions({ agent, sent, reported: ended });
+      this.touchUpdatedAt(agent);
+      this.emitState(agent);
+    });
+  }
 
-    if (!agent.session.setFeature) {
-      throw new Error("Agent session does not support setting features");
+  /** The config as the opened session left it: its own difference from the options it was given. */
+  private withOpenedOptions(input: {
+    config: AgentSessionConfig;
+    session: AgentSession;
+  }): AgentSessionConfig {
+    const { config } = input;
+    const opened = input.session.openOptionsPatch;
+    if (!opened || Object.keys(opened).length === 0) return config;
+    const own = applyProviderOptionsPatch({ options: config.providerOptions, patch: opened });
+    return { ...config, providerOptions: Object.keys(own).length > 0 ? own : undefined };
+  }
+
+  private storeOptionsPatch(input: { agent: ManagedAgent; patch: ProviderOptionsPatch }): void {
+    const { agent } = input;
+    const own = applyProviderOptionsPatch({
+      options: agent.config.providerOptions,
+      patch: input.patch,
+    });
+    agent.config.providerOptions = Object.keys(own).length > 0 ? own : undefined;
+  }
+
+  /**
+   * What the running session has: the options it opened with, moved only by what an apply sent
+   * it (defaults merged in, `null` where a removal left nothing) and by what the provider reports
+   * back. The agent's own stored options keep only the raw patch.
+   */
+  private updateEffectiveOptions(input: {
+    agent: ManagedAgent;
+    sent: ProviderOptionsPatch;
+    reported: ProviderOptionsPatch;
+  }): void {
+    input.agent.effectiveOptions = applyProviderOptionsPatch({
+      options: input.agent.effectiveOptions,
+      patch: { ...input.sent, ...input.reported },
+    });
+  }
+
+  /**
+   * Defaults merge into what the session was given; what it reports it ended up with comes
+   * after, so an option it dropped does not come back from a default.
+   */
+  private openedEffectiveOptions(input: {
+    session: AgentSession;
+    launchedOptions: ProviderOptions;
+  }): ProviderOptions {
+    return applyProviderOptionsPatch({
+      options: input.launchedOptions,
+      patch: input.session.openOptionsPatch ?? {},
+    });
+  }
+
+  /** The options a client opens with: its own defaults merged under the agent's. */
+  private launchOptionsFor(input: {
+    client: AgentClient;
+    own: ProviderOptions | undefined;
+  }): ProviderOptions {
+    return input.client.effectiveOptions?.(input.own) ?? input.own ?? {};
+  }
+
+  /**
+   * What an agent of this provider runs with, given its own options: the defaults under them.
+   * Stored records are read through here before they are reopened, so the legacy conversion
+   * runs here too; a record converted on open passes through unchanged. A legacy value the
+   * conversion cannot read stays as stored: this describes the record, and opening or changing
+   * the agent is what rejects the value.
+   */
+  effectiveOptionsFor(provider: AgentProvider, own: ProviderOptions | undefined): ProviderOptions {
+    const client = this.clients.get(provider);
+    const converted = this.convertStoredOptions(provider, own);
+    return client ? this.launchOptionsFor({ client, own: converted }) : (converted ?? {});
+  }
+
+  private convertStoredOptions(
+    provider: AgentProvider,
+    own: ProviderOptions | undefined,
+  ): ProviderOptions | undefined {
+    try {
+      return this.convertLegacyOptions(provider, own);
+    } catch (error) {
+      if (error instanceof MalformedLegacyOptionError) return own;
+      throw error;
     }
-
-    await agent.session.setFeature(featureId, value);
-    await this.drainSessionEvents(agentId);
-    agent.config.featureValues = { ...agent.config.featureValues, [featureId]: value };
-    this.touchUpdatedAt(agent);
-    this.emitState(agent);
   }
 
   async setTitle(agentId: string, title: string): Promise<void> {
@@ -2383,10 +2740,30 @@ export class AgentManager {
     });
   }
 
+  /** Applies a plugin-metadata patch (null removes a key) and returns the stored result. */
+  async setMetadata(
+    agentId: string,
+    patch: Record<string, JsonValue | null>,
+  ): Promise<AgentMetadata> {
+    return this.runLifecycleMutation(agentId, async () => {
+      const liveAgent = this.agents.get(agentId);
+      if (liveAgent) {
+        liveAgent.metadata = applyRecordPatch<JsonValue>(liveAgent.metadata, patch);
+        this.touchUpdatedAt(liveAgent);
+        await this.persistSnapshot(liveAgent);
+        this.emitState(liveAgent, { persist: false });
+        return liveAgent.metadata;
+      }
+      const record = await this.writeStoredMetadata(agentId, { metadata: patch });
+      if (!record.internal) this.dispatchStoredAgentState(record);
+      return record.metadata;
+    });
+  }
+
   private async writeLabels(agentId: string, patch: AgentLabelPatch): Promise<WriteLabelsResult> {
     const liveAgent = this.agents.get(agentId);
     if (liveAgent) {
-      liveAgent.labels = applyLabelPatch(liveAgent.labels, patch);
+      liveAgent.labels = applyRecordPatch(liveAgent.labels, patch);
       this.touchUpdatedAt(liveAgent);
       await this.persistSnapshot(liveAgent);
       this.emitState(liveAgent, { persist: false });
@@ -2411,7 +2788,8 @@ export class AgentManager {
     const nextRecord = {
       ...record,
       ...(patch.title ? { title: patch.title } : {}),
-      ...(patch.labels ? { labels: applyLabelPatch(record.labels, patch.labels) } : {}),
+      ...(patch.labels ? { labels: applyRecordPatch(record.labels, patch.labels) } : {}),
+      ...(patch.metadata ? { metadata: applyRecordPatch(record.metadata, patch.metadata) } : {}),
       updatedAt: this.nextStoredUpdatedAt(record),
     };
     await registry.upsert(nextRecord);
@@ -2477,27 +2855,45 @@ export class AgentManager {
   }
 
   async clearAgentAttention(agentId: string): Promise<void> {
-    const agent = this.requireAgent(agentId);
-    if (agent.attention.requiresAttention) {
-      agent.attention = { requiresAttention: false };
-      await this.persistSnapshot(agent);
-      this.emitState(agent, { persist: false });
+    const agent = this.agents.get(agentId);
+    if (agent) {
+      if (agent.attention.requiresAttention) {
+        agent.attention = { requiresAttention: false };
+        await this.persistSnapshot(agent);
+        this.emitState(agent, { persist: false });
+      }
+      return;
     }
+
+    const registry = this.requireRegistry();
+    const record = await registry.get(agentId);
+    if (!record || record.internal || record.archivedAt || record.requiresAttention !== true) {
+      return;
+    }
+    const nextRecord: StoredAgentRecord = {
+      ...record,
+      updatedAt: this.nextStoredUpdatedAt(record),
+      requiresAttention: false,
+      attentionReason: null,
+      attentionTimestamp: null,
+    };
+    await registry.upsert(nextRecord);
+    this.dispatchStoredAgentState(nextRecord);
   }
 
   async markAgentUnread(agentId: string): Promise<void> {
     const liveAgent = this.agents.get(agentId);
     if (liveAgent) {
-      const isFinished = liveAgent.lifecycle === "idle";
+      const attentionReason = unreadAttentionReason(liveAgent.lifecycle);
       const hasPendingPermissions = liveAgent.pendingPermissions.size > 0;
       const canMarkUnread =
-        isFinished && !liveAgent.attention.requiresAttention && !hasPendingPermissions;
+        attentionReason && !liveAgent.attention.requiresAttention && !hasPendingPermissions;
       if (!canMarkUnread) {
-        throw new Error(`Agent is no longer finished and read: ${agentId}`);
+        throw new Error(`Agent is no longer settled and read: ${agentId}`);
       }
       liveAgent.attention = {
         requiresAttention: true,
-        attentionReason: "finished",
+        attentionReason,
         attentionTimestamp: new Date(),
       };
       await this.persistSnapshot(liveAgent);
@@ -2507,18 +2903,18 @@ export class AgentManager {
 
     const registry = this.requireRegistry();
     const record = await registry.get(agentId);
-    const hasFinishedStatus = record?.lastStatus === "idle" || record?.lastStatus === "closed";
+    const attentionReason = record?.lastStatus ? unreadAttentionReason(record.lastStatus) : null;
     const canMarkUnread =
       record && !record.internal && !record.archivedAt && !record.requiresAttention;
-    if (!canMarkUnread || !hasFinishedStatus) {
-      throw new Error(`Agent is no longer finished and read: ${agentId}`);
+    if (!canMarkUnread || !attentionReason) {
+      throw new Error(`Agent is no longer settled and read: ${agentId}`);
     }
     const updatedAt = this.nextStoredUpdatedAt(record);
     const nextRecord: StoredAgentRecord = {
       ...record,
       updatedAt,
       requiresAttention: true,
-      attentionReason: "finished",
+      attentionReason,
       attentionTimestamp: updatedAt,
     };
     await registry.upsert(nextRecord);
@@ -2588,23 +2984,28 @@ export class AgentManager {
     if (this.agents.has(agentId)) await this.closeAgentRuntime(agentId);
     await this.syncNativeArchiveState(record.provider, record.persistence, "restore");
 
-    await registry.upsert({
+    const nextRecord: StoredAgentRecord = {
       ...record,
       ...(updates?.workspaceId ? { workspaceId: updates.workspaceId } : {}),
-      ...(updates?.labels ? { labels: applyLabelPatch(record.labels, updates.labels) } : {}),
+      ...(updates?.labels ? { labels: applyRecordPatch(record.labels, updates.labels) } : {}),
       archivedAt: null,
       updatedAt: new Date().toISOString(),
-    });
+    };
+    await registry.upsert(nextRecord);
 
     if (this.getAgent(agentId)) {
       this.notifyAgentState(agentId);
+    } else if (!nextRecord.internal) {
+      // Same publication archiveSnapshot makes, so a stored-only agent reappears for every client.
+      this.dispatchStoredAgentState(nextRecord);
     }
     return true;
   }
 
   async unarchiveSnapshotByHandle(handle: AgentPersistenceHandle): Promise<void> {
     const registry = this.requireRegistry();
-    const records = await registry.list();
+    // Restoring an archived provider session is an explicit recovery operation.
+    const records = await registry.listAll();
     const matched = records.find(
       (record) =>
         record.persistence?.provider === handle.provider &&
@@ -2727,7 +3128,7 @@ export class AgentManager {
         logger: this.logger,
       });
     }
-    const agent = this.requireSessionAgent(agentId);
+    const agent = await this.ensureInteractiveSession(agentId);
     // Providers parse slash commands from the raw text, so a command another agent sent
     // must reach them without its sender envelope.
     const agentMessage = typeof prompt === "string" ? parseAgentMessage(prompt) : null;
@@ -2863,6 +3264,37 @@ export class AgentManager {
     }
   }
 
+  private async ensureInteractiveSession(agentId: string): Promise<ActiveManagedAgent> {
+    const agent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(agent.session)) {
+      await this.runLifecycleMutation(agentId, () =>
+        this.ensureInteractiveSessionUnlocked(agentId),
+      );
+    }
+    return this.requireSessionAgent(agentId);
+  }
+
+  /** Inside the agent's lane: a history session is upgraded before anything is applied to it. */
+  private async ensureInteractiveSessionUnlocked(agentId: string): Promise<ActiveManagedAgent> {
+    const agent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(agent.session)) {
+      const record = await this.registry?.get(agentId);
+      if (record?.archivedAt) throw new Error(`Agent is archived: ${agentId}`);
+      // Reload validates the directory before releasing readable history.
+      await this.trackAgentRegistrationOperation(this.reloadSession(agentId));
+    }
+    return this.requireSessionAgent(agentId);
+  }
+
+  private async *streamAfterHistoryLoad(
+    agentId: string,
+    prompt: AgentPromptInput,
+    options?: AgentRunOptions,
+  ): AsyncGenerator<AgentStreamEvent> {
+    await this.ensureInteractiveSession(agentId);
+    yield* this.streamAgent(agentId, prompt, options);
+  }
+
   private async *streamAfterRuntimeCollection(
     agentId: string,
     prompt: AgentPromptInput,
@@ -2885,6 +3317,8 @@ export class AgentManager {
     if (this.collectingRuntimes.has(agentId) || (!this.agents.has(agentId) && this.registry))
       return this.streamAfterRuntimeCollection(agentId, prompt, options);
     const existingAgent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(existingAgent.session))
+      return this.streamAfterHistoryLoad(agentId, prompt, options);
     this.logger.trace(
       {
         agentId,
@@ -2939,6 +3373,7 @@ export class AgentManager {
       this.runs.settleForegroundStart(pendingRun, { status: "started", turnId });
       agent.activeForegroundTurnId = turnId;
       this.openActiveTurn(agent, turnId, turnStartedAt);
+      agent.attention = { requiresAttention: false };
       agent.lifecycle = "running";
       this.touchUpdatedAt(agent);
       // AgentManager owns the accepted-turn boundary. Publish liveness before the canonical
@@ -3138,7 +3573,13 @@ export class AgentManager {
         expectedTurnId,
       });
       if (admission.status === "accepted") {
-        await this.recordAcceptedSteer(agent, prompt, options?.clientMessageId, expectedTurnId);
+        await this.recordAcceptedSteer(
+          agent,
+          prompt,
+          options?.clientMessageId,
+          expectedTurnId,
+          admission.providerMessageId,
+        );
       }
       return admission;
     });
@@ -3171,7 +3612,13 @@ export class AgentManager {
             expectedTurnId,
           });
           if (admission.status === "accepted") {
-            await this.recordAcceptedSteer(agent, prompt, options?.clientMessageId, expectedTurnId);
+            await this.recordAcceptedSteer(
+              agent,
+              prompt,
+              options?.clientMessageId,
+              expectedTurnId,
+              admission.providerMessageId,
+            );
           }
           return admission;
         })
@@ -3277,6 +3724,7 @@ export class AgentManager {
     prompt: AgentPromptInput,
     clientMessageId: string | undefined,
     expectedTurnId: string,
+    providerMessageId: string | undefined,
   ): Promise<void> {
     if (!clientMessageId) {
       return;
@@ -3284,6 +3732,7 @@ export class AgentManager {
     await this.recordSubmittedPrompt(agent, prompt, clientMessageId, "accepted", {
       messageId: clientMessageId,
       turnId: expectedTurnId,
+      ...(providerMessageId ? { providerMessageId } : {}),
     });
     this.emitState(agent);
   }
@@ -3562,9 +4011,12 @@ export class AgentManager {
   }
 
   async rewind(agentId: string, messageId: string, mode: RewindMode): Promise<void> {
-    const agent = this.requireSessionAgent(agentId);
-    // Without an active run, the rewind holds the run from its call, so no prompt starts
-    // while it reads the history.
+    let agent = this.requireSessionAgent(agentId);
+    if (this.historySessions.has(agent.session)) {
+      agent = await this.ensureInteractiveSession(agentId);
+    }
+    // An interactive session acquires its rewind lock without yielding: without an active run,
+    // the rewind holds the run from its call, so no prompt starts while it reads the history.
     const heldFromCall = this.hasInFlightRun(agentId) ? null : this.runs.createPendingRun(agentId);
     const scope: TimelineScope = { agentId };
     let providerMessageId: string;
@@ -3605,6 +4057,10 @@ export class AgentManager {
         "agent.rewind.complete",
       );
     } catch (error) {
+      // Native rewind can commit a fork before history refresh fails. Recovery
+      // must resume that latest handle rather than the abandoned conversation.
+      this.refreshSessionPersistence(agent);
+      await this.persistSnapshot(agent);
       this.logger.warn(
         { err: error, agentId, provider: agent.provider, messageId, mode },
         "agent.rewind.failed",
@@ -3973,13 +4429,14 @@ export class AgentManager {
 
   private async registerSession(
     session: AgentSession,
-    config: AgentSessionConfig,
+    openedConfig: AgentSessionConfig,
     agentId: string,
-    options?: {
+    options: {
       createdAt?: Date;
       updatedAt?: Date;
       lastUserMessageAt?: Date | null;
       labels?: Record<string, string>;
+      metadata?: AgentMetadata;
       timeline?: AgentTimelineItem[];
       timelineRows?: AgentTimelineRow[];
       timelineNextSeq?: number;
@@ -3997,17 +4454,25 @@ export class AgentManager {
        * attention come from what was already recorded, and installing the session is not
        * activity in it.
        */
+      /**
+       * The effective options the opening resolved before the session started. Registration
+       * starts from these rather than reading the defaults again, which may have been edited
+       * while the provider was opening.
+       */
+      launchedOptions: ProviderOptions;
       restoring?: boolean;
       initialTitle?: string | null;
       publishWhenReady?: boolean;
       workspaceId?: string;
       owner?: AgentOwner;
+      background?: boolean;
       launchEnv?: Record<string, string>;
     },
   ): Promise<ManagedAgent> {
     let registered = false;
     try {
       this.assertAcceptingAgentRegistrations();
+      const config = this.withOpenedOptions({ config: openedConfig, session });
       const resolvedAgentId = validateAgentId(agentId, "registerSession");
       if (this.agents.has(resolvedAgentId)) {
         throw new Error(`Agent with id ${resolvedAgentId} already exists`);
@@ -4032,7 +4497,12 @@ export class AgentManager {
         resolvedAgentId,
         session,
         config,
+        effectiveOptions: this.openedEffectiveOptions({
+          session,
+          launchedOptions: options.launchedOptions,
+        }),
         now,
+        background: options?.background === true,
         options,
       });
 
@@ -4205,13 +4675,16 @@ export class AgentManager {
     resolvedAgentId: string;
     session: AgentSession;
     config: AgentSessionConfig;
+    effectiveOptions: ProviderOptions;
     now: Date;
+    background: boolean;
     options:
       | {
           createdAt?: Date;
           updatedAt?: Date;
           lastUserMessageAt?: Date | null;
           labels?: Record<string, string>;
+          metadata?: AgentMetadata;
           lastUsage?: AgentUsage;
           lastError?: string;
           attention?: AttentionState;
@@ -4222,7 +4695,7 @@ export class AgentManager {
         }
       | undefined;
   }): ActiveManagedAgent {
-    const { resolvedAgentId, session, config, now, options } = params;
+    const { resolvedAgentId, session, config, effectiveOptions, now, options } = params;
     return {
       id: resolvedAgentId,
       provider: config.provider,
@@ -4233,6 +4706,8 @@ export class AgentManager {
       session,
       capabilities: session.capabilities,
       config,
+      // What the session opened with. Provider defaults edited later reach it when it next opens.
+      effectiveOptions,
       runtimeInfo: undefined,
       lifecycle: "initializing",
       createdAt: options?.createdAt ?? now,
@@ -4258,7 +4733,8 @@ export class AgentManager {
       lastError: options?.lastError,
       attention: resolveInitialAttention(options?.attention),
       internal: config.internal ?? false,
-      labels: options?.labels ?? {},
+      background: params.background,
+      ...agentEntityData(options),
     } as ActiveManagedAgent;
   }
 
@@ -4304,6 +4780,7 @@ export class AgentManager {
     this.paseoToolPolicies.delete(agentId);
     this.detachPluginTools(agentId);
     for (const event of removed) this.publishProviderSubagent(event);
+    this.clearBackgroundWork(agentId);
   }
 
   private emitClosedAgent(agent: ManagedAgentClosed, options?: { persist?: boolean }): void {
@@ -4417,6 +4894,14 @@ export class AgentManager {
       this.publishProviderSubagent(update);
       return;
     }
+    if (event.type === "background_work") {
+      const items =
+        event.items === null
+          ? this.backgroundWork.clear(agent.id)
+          : this.backgroundWork.apply(agent.id, event.items);
+      if (items) this.dispatch({ type: "background_work", agentId: agent.id, items });
+      return;
+    }
     const turnId = getAgentStreamEventTurnId(event);
     const matchingWaiters = this.runs.getMatchingWaiters(agent, turnId);
     this.logger.trace(
@@ -4528,7 +5013,7 @@ export class AgentManager {
       agent.pendingPermissions.clear();
     }
 
-    this.syncFeaturesFromSession(agent);
+    this.syncControls(agent);
     await this.refreshRuntimeInfo(agent, options);
   }
 
@@ -4716,6 +5201,18 @@ export class AgentManager {
     );
   }
 
+  private onStreamOptionsChanged(params: {
+    agent: ActiveManagedAgent;
+    patch: ProviderOptionsPatch;
+    flags: StreamEventFlags;
+  }): void {
+    const { agent, patch, flags } = params;
+    this.storeOptionsPatch({ agent, patch });
+    this.updateEffectiveOptions({ agent, sent: {}, reported: patch });
+    flags.shouldDispatchEvent = false;
+    this.emitState(agent);
+  }
+
   private dispatchStreamEventByType(params: {
     agent: ActiveManagedAgent;
     event: AgentStreamEvent;
@@ -4767,6 +5264,9 @@ export class AgentManager {
         flags.shouldDispatchEvent = false;
         this.emitState(agent);
         return undefined;
+      case "options_changed":
+        this.onStreamOptionsChanged({ agent, patch: event.patch, flags });
+        return undefined;
       case "timeline":
         return this.onStreamTimelineEvent({ agent, event, options, flags });
       case "turn_completed":
@@ -5007,6 +5507,8 @@ export class AgentManager {
     if (eventTurnId) {
       this.openActiveTurn(agent, eventTurnId, new Date());
     }
+    agent.lastError = undefined;
+    agent.attention = { requiresAttention: false };
     agent.lifecycle = "running";
     this.emitState(agent);
   }
@@ -5018,7 +5520,7 @@ export class AgentManager {
     const hadPendingPermissions = agent.pendingPermissions.size > 0;
     agent.pendingPermissions.set(event.request.id, event.request);
     this.refreshSessionPersistence(agent);
-    if (!hadPendingPermissions && !agent.internal) {
+    if (!hadPendingPermissions && raisesAttention(agent)) {
       this.broadcastAgentAttention(agent, "permission");
     }
     this.emitState(agent);
@@ -5306,7 +5808,7 @@ export class AgentManager {
       this.enqueueBackgroundPersist(agent);
     }
 
-    this.syncFeaturesFromSession(agent);
+    this.syncControls(agent);
 
     this.logger.trace(
       {
@@ -5328,9 +5830,9 @@ export class AgentManager {
     });
   }
 
-  private syncFeaturesFromSession(agent: ManagedAgent): void {
-    if ("session" in agent && agent.session?.features) {
-      agent.features = agent.session.features;
+  private syncControls(agent: ManagedAgent): void {
+    if ("session" in agent && agent.session?.controls) {
+      agent.controls = agent.session.controls;
     }
   }
 
@@ -5341,17 +5843,19 @@ export class AgentManager {
     // Track the new status
     this.previousStatuses.set(agent.id, currentStatus);
 
-    // Skip attention tracking for internal agents
-    if (agent.internal) {
+    if (!raisesAttention(agent)) {
+      return;
+    }
+
+    if (previousStatus !== "error" && currentStatus === "error") {
+      this.raiseErrorAttention(agent);
       return;
     }
 
-    // Skip if already requires attention
     if (agent.attention.requiresAttention) {
       return;
     }
 
-    // Check if agent transitioned from running to idle (finished)
     if (previousStatus === "running" && currentStatus === "idle") {
       agent.attention = {
         requiresAttention: true,
@@ -5359,19 +5863,25 @@ export class AgentManager {
         attentionTimestamp: new Date(),
       };
       this.broadcastAgentAttention(agent, "finished");
-      return;
     }
+  }
 
-    // Check if agent entered error state
-    if (previousStatus !== "error" && currentStatus === "error") {
-      agent.attention = {
-        requiresAttention: true,
-        attentionReason: "error",
-        attentionTimestamp: new Date(),
-      };
-      this.broadcastAgentAttention(agent, "error");
+  // The failed state is only shown while error attention is unread, so every new failure raises
+  // it, including one that keeps the lifecycle at "error". An error outranks an unread finish,
+  // which would otherwise make the failure look green.
+  private raiseErrorAttention(agent: ManagedAgent): void {
+    if (!raisesAttention(agent)) {
       return;
     }
+    if (agent.attention.requiresAttention && agent.attention.attentionReason !== "finished") {
+      return;
+    }
+    agent.attention = {
+      requiresAttention: true,
+      attentionReason: "error",
+      attentionTimestamp: new Date(),
+    };
+    this.broadcastAgentAttention(agent, "error");
   }
 
   private enqueueBackgroundPersist(agent: ManagedAgent): void {
@@ -5493,6 +6003,13 @@ export class AgentManager {
       ) {
         continue;
       }
+      if (
+        subscriber.agentId &&
+        event.type === "background_work" &&
+        subscriber.agentId !== event.agentId
+      ) {
+        continue;
+      }
       if (
         subscriber.agentId &&
         event.type === "agent_state" &&
@@ -5526,6 +6043,7 @@ export class AgentManager {
     if (event.type === "agent_state") return event.agent.internal === true;
     if (event.type === "agent_removed") return event.internal;
     if (event.type === "agent_stream") return this.agents.get(event.agentId)?.internal === true;
+    if (event.type === "background_work") return this.agents.get(event.agentId)?.internal === true;
     if (event.type !== "provider_subagent") return false;
     const parentAgentId =
       event.event.type === "upsert"
@@ -5538,7 +6056,7 @@ export class AgentManager {
     config: AgentSessionConfig,
     options: NormalizeConfigOptions = {},
   ): Promise<AgentSessionConfig> {
-    const normalized: AgentSessionConfig = { ...config };
+    const normalized: AgentSessionConfig = { ...this.withConvertedOptions(config) };
 
     // Always resolve cwd to absolute path for consistent history file lookup
     if (normalized.cwd) {
@@ -5610,14 +6128,39 @@ export class AgentManager {
     }
   }
 
+  /** The adapter a provider id runs on: a custom provider is named by the one it extends. */
+  private adapterOf(provider: AgentProvider): AgentProvider {
+    return resolveAdapter({
+      provider,
+      extendsOf: (id) => this.providerDefinitions.get(id)?.derivedFromProviderId,
+    });
+  }
+
+  /**
+   * Options older data carries are converted for the adapter the provider runs on, before
+   * defaults merge and before anything is stored; nothing past the manager sees the old keys.
+   */
+  private convertLegacyOptions<T extends ProviderOptions | undefined>(
+    provider: AgentProvider,
+    options: T,
+  ): T {
+    return convertLegacyOptions({ provider: this.adapterOf(provider), options }) as T;
+  }
+
+  private withConvertedOptions(config: AgentSessionConfig): AgentSessionConfig {
+    const providerOptions = this.convertLegacyOptions(config.provider, config.providerOptions);
+    return providerOptions === config.providerOptions ? config : { ...config, providerOptions };
+  }
+
   private async prepareSessionConfig(
     config: AgentSessionConfig,
     agentId: string,
-    options: { env?: Record<string, string>; purpose?: AgentResumePurpose } = {},
+    options: NormalizeConfigOptions = {},
   ): Promise<PreparedSessionConfig> {
     const storedConfig = await this.normalizeConfig(stripInternalPaseoMcpServer(config), {
       env: options.env,
       purpose: options.purpose,
+      resolveDefaultModel: options.resolveDefaultModel,
     });
     const paseoToolPolicy = this.paseoToolsEnabled
       ? this.resolvePaseoToolPolicy(storedConfig.provider)
@@ -5661,6 +6204,7 @@ export class AgentManager {
       workspaceId?: string | null;
       title?: string | null;
       labels?: Record<string, string>;
+      metadata?: AgentMetadata;
     },
   ): Promise<AgentLaunchContext> {
     // A plugin changing during this open must still make the resulting session stale.
@@ -5678,7 +6222,7 @@ export class AgentManager {
         purpose: opening?.purpose ?? "interactive",
         env: { ...env },
         title: opening?.title ?? null,
-        labels: opening?.labels ?? {},
+        ...agentEntityData(opening),
         tools: [],
         mcpServers: {},
       };
@@ -5696,8 +6240,7 @@ export class AgentManager {
       mcpServerOwners,
       env: {
         ...env,
-        PASEO_AGENT_ID: agentId,
-        PASEO_AGENT_CWD: cwd,
+        ...agentIdentityEnv({ agentId, cwd, opening }),
       },
     };
     const useNativeTools =
diff --git a/packages/server/src/server/agent/agent-projections.test.ts b/packages/server/src/server/agent/agent-projections.test.ts
index 26452c6606..dbbc938de3 100644
--- a/packages/server/src/server/agent/agent-projections.test.ts
+++ b/packages/server/src/server/agent/agent-projections.test.ts
@@ -4,19 +4,23 @@ import { AGENT_LIFECYCLE_STATUSES } from "./agent-manager.js";
 import {
   buildStoredAgentPayload,
   toAgentPayload,
+  toAgentListItemPayload,
   toRecentProviderSessionDescriptorPayload,
   toStoredAgentRecord,
   type ManagedAgent,
 } from "./agent-projections.js";
 import type { AgentSession } from "./agent-sdk-types.js";
 import type {
-  AgentFeature,
+  AgentOptionControl,
   ImportableProviderSession,
   AgentPermissionRequest,
   AgentPersistenceHandle,
   AgentSessionConfig,
 } from "./agent-sdk-types.js";
 
+/** A provider with no defaults of its own: the effective options are the agent's own. */
+const ownOptionsOnly = (_provider: string, own: Record<string, unknown> | undefined) => own ?? {};
+
 type ManagedAgentOverrides = Omit<Partial<ManagedAgent>, "config" | "pendingPermissions"> & {
   config?: Partial<AgentSessionConfig>;
   pendingPermissions?: Map<string, AgentPermissionRequest>;
@@ -127,16 +131,6 @@ function createPermission(overrides: Partial<AgentPermissionRequest> = {}): Agen
   return { ...base, ...overrides };
 }
 
-function createFeature(overrides: Partial<AgentFeature> = {}): AgentFeature {
-  return {
-    type: "toggle",
-    id: "fast_mode",
-    label: "Fast mode",
-    value: true,
-    ...overrides,
-  };
-}
-
 describe("toStoredAgentRecord", () => {
   it("captures lifecycle metadata, config, and persistence", () => {
     const agent = createManagedAgent({
@@ -276,6 +270,19 @@ describe("toAgentPayload", () => {
     expect(permissionA.title).toBe("Run command");
   });
 
+  it("changes the usage scope key when the harness session or its model changes", () => {
+    function usageScopeKey(usageSession: ReturnType<NonNullable<AgentSession["usageSession"]>>) {
+      const session = { usageSession: () => usageSession } as unknown as AgentSession;
+      return toAgentPayload(createManagedAgent({ session })).usageScopeKey;
+    }
+    const scope = { provider: "claude", model: "opus", env: {}, sessionKey: "session-a" };
+
+    expect(usageScopeKey(scope)).toBe(usageScopeKey({ ...scope }));
+    expect(usageScopeKey({ ...scope, sessionKey: "session-b" })).not.toBe(usageScopeKey(scope));
+    expect(usageScopeKey({ ...scope, model: "sonnet" })).not.toBe(usageScopeKey(scope));
+    expect(usageScopeKey(null)).toBeUndefined();
+  });
+
   it("omits usage when any numeric usage field is NaN", () => {
     const fields = [
       "inputTokens",
@@ -390,7 +397,7 @@ describe("toAgentPayload", () => {
       }),
     );
 
-    const payload = buildStoredAgentPayload(record, ["codex"]);
+    const payload = buildStoredAgentPayload(record, ["codex"], ownOptionsOnly);
 
     expect(record.persistence?.metadata).toEqual({
       conversationId: "conversation-stored",
@@ -406,15 +413,81 @@ describe("toAgentPayload", () => {
     });
   });
 
+  it("projects a closed agent's stored controls and options", () => {
+    const controls: AgentOptionControl[] = [
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "priority", label: "Fast" },
+        ],
+      },
+    ];
+    const record = toStoredAgentRecord(
+      createManagedAgent({
+        provider: "codex",
+        lifecycle: "closed",
+        controls,
+        config: {
+          provider: "codex",
+          providerOptions: { service_tier: "priority", sandbox_mode: "read-only" },
+        },
+      }),
+    );
+
+    const payload = buildStoredAgentPayload(record, ["codex"], ownOptionsOnly);
+
+    expect(payload.status).toBe("closed");
+    expect(payload.controls).toEqual(controls);
+    expect(payload.options).toEqual({ service_tier: "priority", sandbox_mode: "read-only" });
+    expect(payload.features).toEqual([
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "priority",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "priority", label: "Fast" },
+        ],
+      },
+    ]);
+  });
+
+  it("projects a closed agent's options with the provider defaults under its own, like a live one", () => {
+    const record = toStoredAgentRecord(
+      createManagedAgent({
+        provider: "claude",
+        lifecycle: "closed",
+        controls: [{ type: "toggle", key: "fast_mode", label: "Fast" }],
+        config: { provider: "claude", providerOptions: {} },
+      }),
+    );
+    const withConfigDefaults = (_provider: string, own: Record<string, unknown> | undefined) => ({
+      fast_mode: true,
+      ...own,
+    });
+
+    const payload = buildStoredAgentPayload(record, ["claude"], withConfigDefaults);
+
+    expect(payload.options).toEqual({ fast_mode: true });
+    expect(payload.features).toEqual([
+      { type: "toggle", id: "fast_mode", label: "Fast", value: true },
+    ]);
+  });
+
   it("carries a stored lastError onto the payload", () => {
     const record = toStoredAgentRecord(
       createManagedAgent({ provider: "codex", config: { provider: "codex" }, lastError: "boom" }),
     );
 
-    expect(buildStoredAgentPayload(record, ["codex"]).lastError).toBe("boom");
-    expect(buildStoredAgentPayload({ ...record, lastError: null }, ["codex"])).not.toHaveProperty(
-      "lastError",
-    );
+    expect(buildStoredAgentPayload(record, ["codex"], ownOptionsOnly).lastError).toBe("boom");
+    expect(
+      buildStoredAgentPayload({ ...record, lastError: null }, ["codex"], ownOptionsOnly),
+    ).not.toHaveProperty("lastError");
   });
 
   it("omits lastUsage when not available", () => {
@@ -473,13 +546,44 @@ describe("toAgentPayload", () => {
     });
   });
 
-  it("includes features in the snapshot payload", () => {
-    const features = [createFeature()];
-    const agent = createManagedAgent({ features });
+  it("projects controls, effective options, and legacy features from the same source", () => {
+    const controls: AgentOptionControl[] = [
+      { type: "toggle", key: "fast_mode", label: "Fast mode" },
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "fast", label: "Fast" },
+        ],
+      },
+    ];
+    // `config.json` supplies fast_mode; the agent itself sets nothing for service_tier.
+    // Options without a control are part of the snapshot too.
+    const agent = createManagedAgent({
+      controls,
+      effectiveOptions: { fast_mode: true, sandbox_mode: "workspace-write" },
+    });
 
     const payload = toAgentPayload(agent);
 
-    expect(payload.features).toEqual(features);
+    expect(payload.controls).toEqual(controls);
+    expect(payload.options).toEqual({ fast_mode: true, sandbox_mode: "workspace-write" });
+    expect(payload.features).toEqual([
+      { type: "toggle", id: "fast_mode", label: "Fast mode", value: true },
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "default",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "fast", label: "Fast" },
+        ],
+      },
+    ]);
   });
 });
 
@@ -538,3 +642,11 @@ describe("toRecentProviderSessionDescriptorPayload", () => {
     });
   });
 });
+
+it("omits unknown background work and preserves known summary in list items", () => {
+  const snapshot = toAgentPayload(createManagedAgent());
+  expect(toAgentListItemPayload(snapshot)).not.toHaveProperty("backgroundWork");
+  expect(toAgentListItemPayload({ ...snapshot, backgroundWork: { count: 2 } })).toMatchObject({
+    backgroundWork: { count: 2 },
+  });
+});
diff --git a/packages/server/src/server/agent/agent-projections.ts b/packages/server/src/server/agent/agent-projections.ts
index b388143d8e..09d9461858 100644
--- a/packages/server/src/server/agent/agent-projections.ts
+++ b/packages/server/src/server/agent/agent-projections.ts
@@ -7,7 +7,7 @@ import type {
 import type { SerializableAgentConfig, StoredAgentRecord } from "./agent-storage.js";
 import type {
   AgentCapabilityFlags,
-  AgentFeature,
+  AgentOptionControl,
   AgentMetadata,
   AgentMode,
   AgentPermissionRequest,
@@ -18,7 +18,9 @@ import type {
   AgentUsage,
   ImportableProviderSession,
 } from "./agent-sdk-types.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import type { ManagedAgent } from "./agent-manager.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
 import type { JsonValue } from "../json-utils.js";
 import {
   isStoredAgentProviderAvailable,
@@ -92,12 +94,13 @@ export function toStoredAgentRecord(
     lastUserMessageAt: agent.lastUserMessageAt ? agent.lastUserMessageAt.toISOString() : null,
     title: options?.title ?? null,
     labels: agent.labels,
+    metadata: agent.metadata,
     lastStatus: agent.lifecycle,
     lastModeId: agent.currentModeId ?? config?.modeId ?? null,
     config: config ?? null,
     launchEnv: agent.launchEnv ? { ...agent.launchEnv } : undefined,
     runtimeInfo,
-    features: normalizeFeatures(agent.features),
+    controls: normalizeControls(agent.controls),
     persistence,
     lastError: agent.lastError ?? undefined,
     requiresAttention: agent.attention.requiresAttention,
@@ -106,10 +109,17 @@ export function toStoredAgentRecord(
       ? agent.attention.attentionTimestamp.toISOString()
       : null,
     internal: options?.internal,
+    ...(agent.background ? { background: true } : {}),
     owner: agent.owner,
   } satisfies StoredAgentRecord;
 }
 
+/** Account discovery depends on the harness session and its model, so the key follows both. */
+function projectUsageScopeKey(agent: ManagedAgent): string | undefined {
+  const usageSession = agent.session?.usageSession?.();
+  return usageSession ? `${usageSession.sessionKey}:${usageSession.model ?? ""}` : undefined;
+}
+
 export function toAgentPayload(
   agent: ManagedAgent,
   options?: ProjectionOptions,
@@ -143,15 +153,26 @@ export function toAgentPayload(
     capabilities: cloneCapabilities(agent.capabilities),
     currentModeId: agent.currentModeId,
     availableModes: cloneAvailableModes(agent.availableModes),
-    features: normalizeFeatures(agent.features),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    features: featuresFromControls({ controls: agent.controls, options: agent.effectiveOptions }),
+    ...(agent.effectiveOptions
+      ? { options: sanitizeEffectiveOptions(agent.effectiveOptions) }
+      : {}),
+    controls: normalizeControls(agent.controls),
     pendingPermissions: sanitizePendingPermissions(agent.pendingPermissions),
     persistence: projectPersistenceHandleForWire(agent.persistence),
     title: options?.title ?? null,
     labels: agent.labels,
+    metadata: agent.metadata,
     archivedAt: options?.archivedAt ?? null,
-    ...(agent.internal ? { internal: true } : {}),
+    ...visibilityFlags(agent),
   };
 
+  const usageScopeKey = projectUsageScopeKey(agent);
+  if (usageScopeKey !== undefined) {
+    payload.usageScopeKey = usageScopeKey;
+  }
+
   const usage = sanitizeUsage(agent.lastUsage);
   if (usage !== undefined) {
     payload.lastUsage = usage;
@@ -206,9 +227,43 @@ function buildStoredPersistenceHandle(
   return toAgentPersistenceHandle(validProviders, record.persistence);
 }
 
+/** The wire carries `internal` and `background` only when set. */
+function visibilityFlags(agent: {
+  internal?: boolean;
+  background?: boolean;
+}): Pick<AgentSnapshotPayload, "internal" | "background"> {
+  return {
+    ...(agent.internal ? { internal: true } : {}),
+    ...(agent.background ? { background: true } : {}),
+  };
+}
+
+/** The options an agent runs with, given the options it owns; see `toAgentPayload`. */
+export type EffectiveOptionsResolver = (
+  provider: AgentProvider,
+  own: ProviderOptions | undefined,
+) => ProviderOptions;
+
+function buildStoredOptionControls(
+  record: StoredAgentRecord,
+  effectiveOptionsFor: EffectiveOptionsResolver,
+): Pick<AgentSnapshotPayload, "features" | "options" | "controls"> {
+  const controls = normalizeControls(record.controls);
+  const options = sanitizeEffectiveOptions(
+    effectiveOptionsFor(record.provider, record.config?.providerOptions ?? undefined),
+  );
+  return {
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    features: featuresFromControls({ controls, options }),
+    options,
+    controls,
+  };
+}
+
 export function buildStoredAgentPayload(
   record: StoredAgentRecord,
   validProviders: Iterable<AgentProvider>,
+  effectiveOptionsFor: EffectiveOptionsResolver,
 ): AgentSnapshotPayload {
   const defaultCapabilities = {
     supportsStreaming: false,
@@ -227,6 +282,7 @@ export function buildStoredAgentPayload(
   const lastUserMessageAt = record.lastUserMessageAt ? new Date(record.lastUserMessageAt) : null;
 
   const runtimeInfo = buildStoredRuntimeInfo(record);
+  const optionControls = buildStoredOptionControls(record, effectiveOptionsFor);
   const providerAvailable = isStoredAgentProviderAvailable(record, validProviders);
   const persistence = projectPersistenceHandleForWire(
     buildStoredPersistenceHandle(record, validProviders),
@@ -251,6 +307,7 @@ export function buildStoredAgentPayload(
     capabilities: defaultCapabilities,
     currentModeId: record.lastModeId ?? null,
     availableModes: [],
+    ...optionControls,
     pendingPermissions: [],
     persistence,
     title: record.title ?? null,
@@ -258,8 +315,9 @@ export function buildStoredAgentPayload(
     attentionReason: record.attentionReason ?? null,
     attentionTimestamp: record.attentionTimestamp ?? null,
     archivedAt: record.archivedAt ?? null,
-    ...(record.internal ? { internal: true } : {}),
+    ...visibilityFlags(record),
     labels: normalizeLabels(record.labels),
+    metadata: record.metadata,
     ...(typeof record.lastError === "string" ? { lastError: record.lastError } : {}),
     ...(providerAvailable ? {} : { providerUnavailable: true }),
   };
@@ -275,6 +333,7 @@ export function toAgentListItemPayload(agent: AgentSnapshotPayload): AgentListIt
     thinkingOptionId: agent.thinkingOptionId,
     effectiveThinkingOptionId: agent.effectiveThinkingOptionId,
     status: agent.status,
+    ...(agent.backgroundWork ? { backgroundWork: agent.backgroundWork } : {}),
     cwd: agent.cwd,
     createdAt: agent.createdAt,
     updatedAt: agent.updatedAt,
@@ -375,12 +434,6 @@ function buildSerializableConfig(config: AgentSessionConfig): SerializableAgentC
   if (config.thinkingOptionId) {
     serializable.thinkingOptionId = config.thinkingOptionId;
   }
-  if (Object.prototype.hasOwnProperty.call(config, "featureValues")) {
-    const featureValues = sanitizeMetadata(config.featureValues);
-    if (featureValues !== undefined) {
-      serializable.featureValues = featureValues;
-    }
-  }
   if (config.providerOptions !== undefined) {
     const providerOptions = sanitizeOptionalJson(config.providerOptions);
     if (providerOptions && isJsonObject(providerOptions)) {
@@ -456,8 +509,15 @@ function cloneAvailableModes(modes: AgentMode[]): AgentMode[] {
   return modes.map((mode) => ({ ...mode }));
 }
 
-function normalizeFeatures(features: AgentFeature[] | null | undefined): AgentFeature[] {
-  return Array.isArray(features) ? features.map((feature) => ({ ...feature })) : [];
+function normalizeControls(
+  controls: AgentOptionControl[] | null | undefined,
+): AgentOptionControl[] {
+  return Array.isArray(controls) ? controls.map((control) => ({ ...control })) : [];
+}
+
+function sanitizeEffectiveOptions(options: Record<string, unknown>): ProviderOptions {
+  const sanitized = sanitizeOptionalJson(options);
+  return sanitized && isJsonObject(sanitized) ? sanitized : {};
 }
 
 function sanitizeOptionalJson(value: unknown): JsonValue | undefined {
diff --git a/packages/server/src/server/agent/agent-sdk-types.ts b/packages/server/src/server/agent/agent-sdk-types.ts
index 05ca59938e..6697ce66db 100644
--- a/packages/server/src/server/agent/agent-sdk-types.ts
+++ b/packages/server/src/server/agent/agent-sdk-types.ts
@@ -1,7 +1,7 @@
 import type {
-  AgentFeature,
-  AgentFeatureSelect,
-  AgentFeatureToggle,
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  AgentOptionToggleControl,
   AgentProviderNotice,
   AgentTaskItem,
   JsonValue,
@@ -13,9 +13,9 @@ import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import type { PaseoToolCatalog } from "./tools/types.js";
 
 export type {
-  AgentFeature,
-  AgentFeatureSelect,
-  AgentFeatureToggle,
+  AgentOptionControl,
+  AgentOptionSelectControl,
+  AgentOptionToggleControl,
   AgentProviderNotice,
   AgentTaskItem,
 };
@@ -148,7 +148,7 @@ export interface AgentCreateConfigParent {
 export interface ResolveAgentCreateConfigInput {
   provider: AgentProvider;
   requestedMode: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
   parent: AgentCreateConfigParent | null;
   unattended: boolean;
   availableModes: AgentMode[] | undefined;
@@ -156,13 +156,13 @@ export interface ResolveAgentCreateConfigInput {
 
 export interface ResolveAgentCreateConfigResult {
   modeId: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
 }
 
 export interface AgentCreateConfigUnattendedInput {
   modeId: string | null;
   config: AgentSessionConfig;
-  features?: AgentFeature[];
+  controls?: AgentOptionControl[];
   availableModes: AgentMode[];
 }
 
@@ -208,7 +208,11 @@ export interface AgentSteerOptions extends AgentRunOptions {
   clearPendingPermissions?: boolean;
 }
 
-export type SteerResult = { status: "accepted" } | { status: "unavailable" };
+// providerMessageId names the steered message in the provider's own history, when the provider
+// mints one. Rewinding to the message needs it.
+export type SteerResult =
+  | { status: "accepted"; providerMessageId?: string }
+  | { status: "unavailable" };
 
 export interface SteerActiveTurnOptions extends AgentSteerOptions {
   expectedTurnId: string;
@@ -425,6 +429,14 @@ export type AgentStreamEvent =
       provider: AgentProvider;
       thinkingOptionId: string | null;
     }
+  /**
+   * The provider changed options on its own: after `createSession`/`resumeSession` or
+   * `applyOptions` it ended up different from what it was given, or later it changed a setting
+   * itself. The daemon stores the patch and forwards it; it does not undo it. `null` removes the
+   * agent's own value. Only for changes that happen on the provider's own initiative: the result
+   * of opening goes in `openOptionsPatch` and the result of `applyOptions` is its return value.
+   */
+  | { type: "options_changed"; provider: AgentProvider; patch: Record<string, unknown> }
   | {
       type: "turn_failed";
       provider: AgentProvider;
@@ -464,6 +476,12 @@ export type AgentStreamEvent =
       type: "provider_subagent";
       provider: AgentProvider;
       event: import("./provider-subagents/store.js").ProviderSubagentInputEvent;
+    }
+  | {
+      /** Full replacement of the agent's live background work (shells, monitors…). */
+      type: "background_work";
+      provider: AgentProvider;
+      items: import("./background-work/index.js").AgentBackgroundWorkInput[] | null;
     };
 
 export function getAgentStreamEventTurnId(event: AgentStreamEvent): string | undefined {
@@ -638,7 +656,6 @@ export interface AgentSessionConfig {
   modeId?: string;
   model?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
   title?: string | null;
   providerOptions?: ProviderOptions;
   toolPolicy?: ToolPolicy;
@@ -707,11 +724,19 @@ export interface AgentSession {
   readonly provider: AgentProvider;
   readonly id: string | null;
   readonly capabilities: AgentCapabilityFlags;
-  readonly features?: AgentFeature[];
+  /** Composer controls over top-level option keys. Values come from the agent's effective options. */
+  readonly controls?: AgentOptionControl[];
+  /**
+   * How the session ended up different from the options it was opened with, as a patch (`null`
+   * removes a key). Set by the time `createSession`/`resumeSession` resolves; the daemon stores it
+   * before the agent is published.
+   */
+  readonly openOptionsPatch?: Record<string, unknown>;
   /** New provider-owned rows to commit on registration. streamHistory must also
    * replay them at their original timestamps; restored sessions omit old rows. */
   readonly initialTimeline?: ImportedTimelineEntry[];
   run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+  /** Returns an ID unique across the agent lifetime, including resumed sessions and daemon restarts. */
   startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{ turnId: string }>;
   steerActiveTurn?(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult>;
   subscribe(callback: (event: AgentStreamEvent) => void): () => void;
@@ -725,6 +750,7 @@ export interface AgentSession {
     requestId: string,
     response: AgentPermissionResponse,
   ): Promise<AgentPermissionResult | void>;
+  /** Null until a new provider process could resume this session; see docs/providers.md. */
   describePersistence(): AgentPersistenceHandle | null;
   /**
    * Resolve once every foreground turn that predates this call can no longer run or become active.
@@ -732,6 +758,8 @@ export interface AgentSession {
    * still uncertain.
    */
   interrupt(): Promise<void>;
+  /** Stop one currently owned background item and wait for provider confirmation. */
+  stopBackgroundWork?(id: string): Promise<void>;
   /** True only when releasing this runtime loses no background work or pending replies.
    * An optional additional veto: missing methods use daemon baseline eligibility;
    * implemented checks that reject or return false keep the runtime resident. */
@@ -739,9 +767,24 @@ export interface AgentSession {
   /** Release live runtime resources without archiving or deleting the durable native session. */
   close(): Promise<void>;
   listCommands?(): Promise<AgentSlashCommand[]>;
-  setModel?(modelId: string | null): Promise<void>;
+  /** A returned model is the effective selection committed by this mutation.
+   * Returning void means the requested selection was accepted. No status read is required. */
+  setModel?(modelId: string | null): Promise<void | { model: string | null }>;
   setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
-  setFeature?(featureId: string, value: unknown): Promise<void>;
+  /**
+   * Apply an options patch. `options` holds only the keys the patch touches, resolved against
+   * the `config.json` defaults; `null` means nothing is set for the key, so return it to the
+   * session's own default if that can be done. Leave every other setting alone. Throw to reject a
+   * value, or a key the running session cannot apply (one the provider reads only when it
+   * opens): the daemon stores the patch only when this resolves, so a stored option always
+   * describes what runs, and the call is all-or-nothing.
+   * Emit nothing from here. Return the options the session ended up with when they differ from
+   * the request (a patch, `null` removes a key), for example a value it kept because it could not
+   * be reverted; the daemon stores it together with the patch. When a throw leaves the session's
+   * state moved anyway, report the moved values once as `options_changed` after the call has
+   * ended, so the stored options still match what runs.
+   */
+  applyOptions?(options: ProviderOptions): Promise<Record<string, unknown> | void>;
   /**
    * Rewinds the provider conversation to before the prompt `messageId`. Resolves with what the
    * provider actually removed; `void` means exactly the target and everything after it. Rejects
@@ -796,14 +839,25 @@ export interface ResolveAgentDefaultModeInput {
   signal?: AbortSignal;
 }
 
+export interface AgentDraftControls {
+  controls: AgentOptionControl[];
+  options: ProviderOptions;
+}
+
 export interface AgentClient {
   readonly provider: AgentProvider;
   readonly capabilities: AgentCapabilityFlags;
+  /**
+   * Create the agent with `config.providerOptions` (defaults already merged in). Emit nothing
+   * about options while creating. If the agent ended up different from the options, say so in the
+   * session's `openOptionsPatch`.
+   */
   createSession(
     config: AgentSessionConfig,
     launchContext?: AgentLaunchContext,
     options?: AgentCreateSessionOptions,
   ): Promise<AgentSession>;
+  /** Same contract as `createSession`: open with the options, report any difference in `openOptionsPatch`. */
   resumeSession(
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
@@ -832,7 +886,14 @@ export interface AgentClient {
   resolveCreateConfig?(input: ResolveAgentCreateConfigInput): ResolveAgentCreateConfigResult;
   isCreateConfigUnattended?(input: AgentCreateConfigUnattendedInput): boolean;
   listCommands?(config: AgentSessionConfig): Promise<AgentSlashCommand[]>;
-  listFeatures?(config: AgentSessionConfig): Promise<AgentFeature[]>;
+  /**
+   * The controls of a draft, with the options a session opened from `config` would run with:
+   * `config.providerOptions` (defaults already merged in) plus what the provider resolves
+   * natively for the ones nobody set.
+   */
+  listControls?(config: AgentSessionConfig): Promise<AgentDraftControls>;
+  /** Effective options: provider defaults from `config.json` deep-merged with the agent's own. */
+  effectiveOptions?(own: ProviderOptions | undefined): ProviderOptions;
   listImportableSessions?(
     options?: ListImportableSessionsOptions,
   ): Promise<ImportableProviderSession[]>;
diff --git a/packages/server/src/server/agent/agent-storage.test.ts b/packages/server/src/server/agent/agent-storage.test.ts
index 0ebb008199..930d020e16 100644
--- a/packages/server/src/server/agent/agent-storage.test.ts
+++ b/packages/server/src/server/agent/agent-storage.test.ts
@@ -1,8 +1,10 @@
 import { describe, expect, test, beforeEach, afterEach } from "vitest";
 import os from "node:os";
 import path from "node:path";
-import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { promises as fs } from "node:fs";
+import { Session as InspectorSession } from "node:inspector/promises";
+import type { HeapProfiler } from "node:inspector";
 
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import { AgentStorage } from "./agent-storage.js";
@@ -44,9 +46,6 @@ function buildManagedAgentConfig(
     systemPrompt: configOverrides.systemPrompt,
     mcpServers: configOverrides.mcpServers,
   };
-  if (Object.prototype.hasOwnProperty.call(configOverrides, "featureValues")) {
-    config.featureValues = configOverrides.featureValues;
-  }
   return config;
 }
 
@@ -131,6 +130,14 @@ function createManagedAgent(overrides: ManagedAgentOverrides = {}): ManagedAgent
   };
 }
 
+function findRecordFile(baseDir: string, agentId: string): string {
+  for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
+    const candidate = path.join(baseDir, entry.name, `${agentId}.json`);
+    if (entry.isDirectory() && existsSync(candidate)) return candidate;
+  }
+  throw new Error(`No stored record for ${agentId}`);
+}
+
 describe("AgentStorage", () => {
   let tmpDir: string;
   let storagePath: string;
@@ -147,6 +154,101 @@ describe("AgentStorage", () => {
     rmSync(tmpDir, { recursive: true, force: true });
   });
 
+  test("workspace and active queries follow updates, removal, and reload", async () => {
+    const base = {
+      provider: "codex",
+      cwd: tmpDir,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      labels: {},
+    };
+    await storage.upsert({
+      ...base,
+      id: "a",
+      workspaceId: "one",
+      lastUserMessageAt: base.createdAt,
+    });
+    await storage.upsert({ ...base, id: "b", workspaceId: "two", archivedAt: base.createdAt });
+    expect((await storage.listActive()).map((r) => r.id)).toEqual(["a"]);
+    await storage.upsert({
+      ...base,
+      id: "a",
+      workspaceId: "two",
+      lastUserMessageAt: base.updatedAt,
+    });
+    expect(await storage.listByWorkspaces(["one"])).toEqual([]);
+    expect((await storage.listByWorkspaces(["two"])).map((r) => r.id)).toEqual(["a"]);
+    expect(
+      (await storage.listByWorkspaces(["two"], { includeArchived: true })).map((r) => r.id).sort(),
+    ).toEqual(["a", "b"]);
+    expect(await storage.lastUserMessageAtByWorkspace(["one", "two"])).toEqual(
+      new Map([["two", base.createdAt]]),
+    );
+    await storage.flush();
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
+    expect((await reloaded.listActive()).map((r) => r.id)).toEqual(["a"]);
+    expect(
+      await reloaded.lastUserMessageAtByWorkspace(["two"], { excludeAgentIds: ["a"] }),
+    ).toEqual(new Map());
+    await reloaded.remove("a");
+    expect(await reloaded.listActive()).toEqual([]);
+    expect(await reloaded.lastUserMessageAtByWorkspace(["two"])).toEqual(new Map());
+  });
+
+  test("single-agent lookups keep allocations bounded with a large stored history", async () => {
+    await fs.mkdir(storagePath, { recursive: true });
+    const record = {
+      id: "history-0",
+      provider: "codex",
+      cwd: tmpDir,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      labels: {},
+      lastStatus: "idle",
+    };
+    for (let offset = 0; offset < 2048; offset += 64) {
+      await Promise.all(
+        Array.from({ length: 64 }, (_, index) => {
+          const id = `history-${offset + index}`;
+          return fs.writeFile(
+            path.join(storagePath, `${id}.json`),
+            JSON.stringify({ ...record, id }),
+          );
+        }),
+      );
+    }
+    await storage.initialize();
+    expect(await storage.listAll()).toHaveLength(2048);
+    const expected = await storage.get(record.id);
+    expect(expected).toMatchObject(record);
+
+    const inspector = new InspectorSession();
+    inspector.connect();
+    let allocatedBytes = 0;
+    let matches = 0;
+    try {
+      await inspector.post("HeapProfiler.startSampling", {
+        samplingInterval: 16384,
+        includeObjectsCollectedByMajorGC: true,
+        includeObjectsCollectedByMinorGC: true,
+      });
+      for (let index = 0; index < 1000; index++) {
+        if ((await storage.get(record.id)) === expected) matches++;
+      }
+      const { profile } = await inspector.post("HeapProfiler.stopSampling");
+      const sum = (node: HeapProfiler.SamplingHeapProfileNode): number =>
+        node.selfSize + node.children.reduce((bytes, child) => bytes + sum(child), 0);
+      allocatedBytes = sum(profile.head);
+    } finally {
+      inspector.disconnect();
+    }
+
+    expect(matches).toBe(1000);
+    // Copying this history on every lookup allocates >16 MiB. Allow generous
+    // sampling/runtime overhead without relying on the host's execution speed.
+    expect(allocatedBytes).toBeLessThan(4 * 1024 * 1024);
+  });
+
   test("applySnapshot persists configs and snapshot metadata", async () => {
     await storage.applySnapshot(
       createManagedAgent({
@@ -171,7 +273,7 @@ describe("AgentStorage", () => {
       }),
     );
 
-    const records = await storage.list();
+    const records = await storage.listAll();
     expect(records).toHaveLength(1);
     const [record] = records;
     expect(record.provider).toBe("claude");
@@ -188,68 +290,83 @@ describe("AgentStorage", () => {
     expect(record.lastModeId).toBe("coding");
     expect(record.lastStatus).toBe("idle");
 
-    const reloaded = new AgentStorage(storagePath, logger);
-    const [persisted] = await reloaded.list();
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
+    const [persisted] = await reloaded.listAll();
     expect(persisted.cwd).toBe("/tmp/project");
     expect(persisted.config?.providerOptions).toEqual({ allowedTools: ["Read"] });
   });
 
-  test("applySnapshot stores and reloads featureValues when present", async () => {
+  test("applySnapshot stores and reloads composer values as providerOptions", async () => {
     await storage.applySnapshot(
       createManagedAgent({
-        id: "agent-feature-values",
-        config: {
-          featureValues: {
-            fast_mode: true,
-          },
-        },
+        id: "agent-provider-options",
+        config: { providerOptions: { fast_mode: true } },
       }),
     );
 
-    const record = await storage.get("agent-feature-values");
-    expect(record?.config?.featureValues).toEqual({ fast_mode: true });
-
-    const reloaded = new AgentStorage(storagePath, logger);
-    const persisted = await reloaded.get("agent-feature-values");
-    expect(persisted?.config?.featureValues).toEqual({ fast_mode: true });
-    expect(buildSessionConfig(persisted!).featureValues).toEqual({ fast_mode: true });
-  });
-
-  test("applySnapshot keeps featureValues absent when they were never set", async () => {
-    await storage.applySnapshot(
-      createManagedAgent({
-        id: "agent-no-feature-values",
-      }),
-    );
-
-    const reloaded = new AgentStorage(storagePath, logger);
-    const persisted = await reloaded.get("agent-no-feature-values");
-    expect(persisted?.config?.featureValues).toBeUndefined();
-    expect(buildSessionConfig(persisted!).featureValues).toBeUndefined();
-  });
-
-  test("buildConfigOverrides includes featureValues when present in stored config", async () => {
-    await storage.applySnapshot(
-      createManagedAgent({
-        id: "agent-resume-overrides",
-        config: {
-          featureValues: {
-            fast_mode: true,
-          },
-        },
-      }),
-    );
-
-    const record = await storage.get("agent-resume-overrides");
-    expect(record).not.toBeNull();
-    expect(buildConfigOverrides(record!)).toMatchObject({
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
+    const persisted = await reloaded.get("agent-provider-options");
+    expect(persisted?.config?.providerOptions).toEqual({ fast_mode: true });
+    expect(buildSessionConfig(persisted!).providerOptions).toEqual({ fast_mode: true });
+    expect(buildConfigOverrides(persisted!)).toMatchObject({
       cwd: "/tmp/project",
-      featureValues: {
-        fast_mode: true,
-      },
+      providerOptions: { fast_mode: true },
     });
   });
 
+  test("a record stored with featureValues loads them in providerOptions", async () => {
+    await storage.applySnapshot(createManagedAgent({ id: "agent-legacy" }));
+    const file = findRecordFile(storagePath, "agent-legacy");
+    const stored = JSON.parse(await fs.readFile(file, "utf8"));
+    stored.config.providerOptions = { allowedTools: ["Read"], fast_mode: false };
+    stored.config.featureValues = { fast_mode: true, service_tier: "fast" };
+    delete stored.controls;
+    stored.features = [
+      { type: "toggle", id: "fast_mode", label: "Fast mode", value: true },
+      {
+        type: "select",
+        id: "service_tier",
+        label: "Speed",
+        value: "fast",
+        options: [
+          { id: "default", label: "Normal", isDefault: true },
+          { id: "fast", label: "Fast" },
+        ],
+      },
+    ];
+    await fs.writeFile(file, JSON.stringify(stored));
+
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
+    const persisted = await reloaded.get("agent-legacy");
+
+    // An explicit providerOptions key wins over the same featureValues key.
+    expect(persisted?.config?.providerOptions).toEqual({
+      allowedTools: ["Read"],
+      fast_mode: false,
+      service_tier: "fast",
+    });
+    expect(persisted?.config).not.toHaveProperty("featureValues");
+    expect(persisted).not.toHaveProperty("features");
+    expect(persisted?.controls).toEqual([
+      { type: "toggle", key: "fast_mode", label: "Fast mode" },
+      {
+        type: "select",
+        key: "service_tier",
+        label: "Speed",
+        defaultValue: "default",
+        choices: [
+          { value: "default", label: "Normal" },
+          { value: "fast", label: "Fast" },
+        ],
+      },
+    ]);
+
+    await reloaded.applySnapshot(createManagedAgent({ id: "agent-legacy" }));
+    const rewritten = JSON.parse(await fs.readFile(file, "utf8"));
+    expect(rewritten.config).not.toHaveProperty("featureValues");
+    expect(rewritten).not.toHaveProperty("features");
+  });
+
   test("applySnapshot preserves original createdAt timestamp", async () => {
     const agentId = "agent-created-at";
     const firstTimestamp = new Date("2025-01-01T00:00:00.000Z");
@@ -311,7 +428,7 @@ describe("AgentStorage", () => {
     const current = await storage.get("agent-2");
     expect(current?.title).toBe("Fix Login Bug");
 
-    const reloaded = new AgentStorage(storagePath, logger);
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
     const persisted = await reloaded.get("agent-2");
     expect(persisted?.title).toBe("Fix Login Bug");
   });
@@ -414,7 +531,7 @@ describe("AgentStorage", () => {
     );
 
     // Registry should return all agents - filtering is done at the manager level
-    const records = await storage.list();
+    const records = await storage.listAll();
     expect(records).toHaveLength(2);
   });
 
@@ -485,12 +602,12 @@ describe("AgentStorage", () => {
     );
 
     // Reload the registry from disk
-    const reloaded = new AgentStorage(storagePath, logger);
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
     const record = await reloaded.get("internal-agent");
     expect(record?.internal).toBe(true);
 
     // Registry returns all agents - filtering happens at manager level
-    const records = await reloaded.list();
+    const records = await reloaded.listAll();
     expect(records).toHaveLength(1);
     expect(records[0]?.internal).toBe(true);
   });
@@ -542,8 +659,8 @@ describe("AgentStorage", () => {
     );
 
     // Force a reload so the registry has to discover from disk (and may choose either copy).
-    const reloaded = new AgentStorage(storagePath, logger);
-    const before = await reloaded.list();
+    const reloaded = new AgentStorage(storagePath, createTestLogger());
+    const before = await reloaded.listAll();
     expect(before.map((r) => r.id)).toContain(agentId);
 
     await reloaded.remove(agentId);
@@ -570,8 +687,8 @@ describe("AgentStorage", () => {
 
     expect(await hasAnyRecordFile()).toBe(false);
 
-    const afterReload = new AgentStorage(storagePath, logger);
-    const after = await afterReload.list();
+    const afterReload = new AgentStorage(storagePath, createTestLogger());
+    const after = await afterReload.listAll();
     expect(after.some((r) => r.id === agentId)).toBe(false);
   });
 });
diff --git a/packages/server/src/server/agent/agent-storage.ts b/packages/server/src/server/agent/agent-storage.ts
index a097bd7f82..9fe88ded66 100644
--- a/packages/server/src/server/agent/agent-storage.ts
+++ b/packages/server/src/server/agent/agent-storage.ts
@@ -2,19 +2,23 @@ import { promises as fs, type Dirent } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import type { Logger } from "pino";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 
 import { writeJsonFileAtomic } from "../atomic-file.js";
-import { AgentFeatureSchema, AgentStatusSchema } from "../messages.js";
+import { AgentFeatureSchema, AgentOptionControlSchema, AgentStatusSchema } from "../messages.js";
 import { toStoredAgentRecord } from "./agent-projections.js";
 import type { ManagedAgent } from "./agent-manager.js";
 import type { AgentSessionConfig } from "./agent-sdk-types.js";
 import { AgentOwnerSchema, daemonExecutionKey, type DaemonAgentOwner } from "./agent-owner.js";
+import { controlsFromFeatures } from "@getpaseo/protocol/option-controls";
+import { foldFeatureValues } from "./option-controls.js";
 
 const SERIALIZABLE_CONFIG_SCHEMA = z
   .object({
     modeId: z.string().nullable().optional(),
     model: z.string().nullable().optional(),
     thinkingOptionId: z.string().nullable().optional(),
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read-only; folded on parse.
     featureValues: z.record(z.string(), z.unknown()).nullable().optional(),
     providerOptions: z.record(z.string(), z.unknown()).nullable().optional(),
     toolPolicy: z
@@ -42,7 +46,7 @@ const PERSISTENCE_HANDLE_SCHEMA = z
   .nullable()
   .optional();
 
-const STORED_AGENT_SCHEMA = z.object({
+const RAW_STORED_AGENT_SCHEMA = z.object({
   id: z.string(),
   provider: z.string(),
   cwd: z.string(),
@@ -53,6 +57,7 @@ const STORED_AGENT_SCHEMA = z.object({
   lastUserMessageAt: z.string().nullable().optional(),
   title: z.string().nullable().optional(),
   labels: z.record(z.string(), z.string()).default({}),
+  metadata: z.record(z.string(), z.custom<JsonValue>()).default({}),
   lastStatus: AgentStatusSchema.default("closed"),
   resumeOnStartup: z.boolean().optional(),
   lastModeId: z.string().nullable().optional(),
@@ -68,6 +73,8 @@ const STORED_AGENT_SCHEMA = z.object({
       extra: z.record(z.string(), z.unknown()).optional(),
     })
     .optional(),
+  controls: z.array(AgentOptionControlSchema).optional(),
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Read-only; becomes controls.
   features: z.array(AgentFeatureSchema).optional(),
   persistence: PERSISTENCE_HANDLE_SCHEMA,
   lastError: z.string().nullable().optional(),
@@ -75,6 +82,7 @@ const STORED_AGENT_SCHEMA = z.object({
   attentionReason: z.enum(["finished", "error", "permission"]).nullable().optional(),
   attentionTimestamp: z.string().nullable().optional(),
   internal: z.boolean().optional(),
+  background: z.boolean().optional(),
   archivedAt: z.string().nullable().optional(),
   owner: AgentOwnerSchema.optional(),
 });
@@ -84,14 +92,32 @@ export type SerializableAgentConfig = Pick<
   | "modeId"
   | "model"
   | "thinkingOptionId"
-  | "featureValues"
   | "providerOptions"
   | "toolPolicy"
   | "systemPrompt"
   | "mcpServers"
 >;
 
-export type StoredAgentRecord = z.infer<typeof STORED_AGENT_SCHEMA>;
+type RawStoredAgentRecord = z.infer<typeof RAW_STORED_AGENT_SCHEMA>;
+type RawStoredAgentConfig = NonNullable<RawStoredAgentRecord["config"]>;
+
+/** Records carry `providerOptions` and `controls` only; legacy fields are folded when read. */
+export type StoredAgentRecord = Omit<RawStoredAgentRecord, "config" | "features"> & {
+  config?: Omit<RawStoredAgentConfig, "featureValues"> | null;
+};
+
+// COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+function foldLegacyRecordFields(record: RawStoredAgentRecord): StoredAgentRecord {
+  const { features, config, controls, ...rest } = record;
+  return {
+    ...rest,
+    ...(config ? { config: foldFeatureValues(config) } : { config }),
+    ...((controls ?? features) ? { controls: controls ?? controlsFromFeatures(features) } : {}),
+  };
+}
+
+const STORED_AGENT_SCHEMA = RAW_STORED_AGENT_SCHEMA.transform(foldLegacyRecordFields);
+
 export function parseStoredAgentRecord(value: unknown): StoredAgentRecord {
   return STORED_AGENT_SCHEMA.parse(value);
 }
@@ -104,9 +130,14 @@ export class AgentStorage {
   private deleting: Set<string> = new Set();
   private daemonAgentIdsByExecution: Map<string, string> = new Map();
   private daemonExecutionKeysByAgentId: Map<string, string> = new Map();
+  private readonly idsByWorkspace = new Map<string, Set<string>>();
+  private readonly workspaceById = new Map<string, string>();
+  private readonly activeIds = new Set<string>();
+  private readonly promptTimeByAgent = new Map<string, string>();
+  private readonly promptTimes = new Map<string, string>();
   private loaded = false;
   private baseDir: string;
-  private loadPromise: Promise<StoredAgentRecord[]> | null = null;
+  private loadPromise: Promise<void> | null = null;
   private logger: Logger;
 
   constructor(baseDir: string, logger: Logger) {
@@ -118,11 +149,119 @@ export class AgentStorage {
     await this.load();
   }
 
-  async list(): Promise<StoredAgentRecord[]> {
+  async listAll(): Promise<StoredAgentRecord[]> {
     await this.load();
     return Array.from(this.cache.values());
   }
 
+  async listActive(options?: { includeArchived?: boolean }): Promise<StoredAgentRecord[]> {
+    await this.load();
+    return Array.from(
+      options?.includeArchived ? this.cache.keys() : this.activeIds,
+      (id) => this.cache.get(id)!,
+    );
+  }
+
+  async listByWorkspaces(
+    workspaceIds: Iterable<string>,
+    options?: { includeArchived?: boolean },
+  ): Promise<StoredAgentRecord[]> {
+    await this.load();
+    const records: StoredAgentRecord[] = [];
+    for (const workspaceId of new Set(workspaceIds)) {
+      for (const id of this.idsByWorkspace.get(workspaceId) ?? []) {
+        const record = this.cache.get(id)!;
+        if (options?.includeArchived || !record.archivedAt) records.push(record);
+      }
+    }
+    return records;
+  }
+
+  async lastUserMessageAtByWorkspace(
+    workspaceIds?: Iterable<string>,
+    options?: { excludeAgentIds?: Iterable<string> },
+  ): Promise<ReadonlyMap<string, string>> {
+    await this.load();
+    const times = new Map<string, string>();
+    const excluded = new Set(options?.excludeAgentIds);
+    const affected = new Set(Array.from(excluded, (id) => this.workspaceById.get(id)));
+    for (const id of workspaceIds ?? this.promptTimes.keys()) {
+      let at = this.promptTimes.get(id);
+      if (affected.has(id)) {
+        at = undefined;
+        for (const agentId of this.idsByWorkspace.get(id) ?? []) {
+          const record = this.cache.get(agentId)!;
+          if (
+            !excluded.has(agentId) &&
+            !record.internal &&
+            !record.background &&
+            record.lastUserMessageAt &&
+            record.lastUserMessageAt > (at ?? "")
+          ) {
+            at = record.lastUserMessageAt;
+          }
+        }
+      }
+      if (at) times.set(id, at);
+    }
+    return times;
+  }
+
+  private indexWorkspace(record: StoredAgentRecord): void {
+    const previous = this.workspaceById.get(record.id);
+    if (previous) this.idsByWorkspace.get(previous)?.delete(record.id);
+    this.workspaceById.delete(record.id);
+    this.activeIds.delete(record.id);
+    if (!record.archivedAt) this.activeIds.add(record.id);
+    if (record.workspaceId) {
+      const ids = this.idsByWorkspace.get(record.workspaceId) ?? new Set<string>();
+      ids.add(record.id);
+      this.idsByWorkspace.set(record.workspaceId, ids);
+      this.workspaceById.set(record.id, record.workspaceId);
+    }
+    this.indexPromptTime(record, previous);
+  }
+
+  private indexPromptTime(record: StoredAgentRecord, previous: string | undefined): void {
+    const previousTime = this.promptTimeByAgent.get(record.id);
+    const nextTime =
+      !record.internal && !record.background ? (record.lastUserMessageAt ?? undefined) : undefined;
+    if (nextTime) this.promptTimeByAgent.set(record.id, nextTime);
+    else this.promptTimeByAgent.delete(record.id);
+    if (previous === record.workspaceId && previousTime === nextTime) return;
+    if (
+      previous &&
+      previousTime &&
+      this.promptTimes.get(previous) === previousTime &&
+      (previous !== record.workspaceId || !nextTime || nextTime < previousTime)
+    ) {
+      this.refreshPromptTime(previous);
+    }
+    if (
+      record.workspaceId &&
+      nextTime &&
+      nextTime > (this.promptTimes.get(record.workspaceId) ?? "")
+    ) {
+      this.promptTimes.set(record.workspaceId, nextTime);
+    }
+  }
+
+  private refreshPromptTime(workspaceId: string): void {
+    this.promptTimes.delete(workspaceId);
+    let latest = "";
+    for (const id of this.idsByWorkspace.get(workspaceId) ?? []) {
+      const record = this.cache.get(id)!;
+      if (
+        !record.internal &&
+        !record.background &&
+        record.lastUserMessageAt &&
+        record.lastUserMessageAt > latest
+      )
+        latest = record.lastUserMessageAt;
+    }
+    if (latest) this.promptTimes.set(workspaceId, latest);
+  }
+
   async get(agentId: string): Promise<StoredAgentRecord | null> {
     await this.load();
     return this.cache.get(agentId) ?? null;
@@ -142,8 +281,7 @@ export class AgentStorage {
   }
 
   async listByWorkspace(workspaceId: string): Promise<StoredAgentRecord[]> {
-    await this.load();
-    return Array.from(this.cache.values()).filter((record) => record.workspaceId === workspaceId);
+    return this.listByWorkspaces([workspaceId], { includeArchived: true });
   }
 
   async findByDaemonExecution(owner: DaemonAgentOwner): Promise<StoredAgentRecord | null> {
@@ -233,6 +371,14 @@ export class AgentStorage {
       }),
     );
 
+    const workspaceId = this.workspaceById.get(agentId);
+    this.workspaceById.delete(agentId);
+    this.promptTimeByAgent.delete(agentId);
+    this.activeIds.delete(agentId);
+    if (workspaceId) {
+      this.idsByWorkspace.get(workspaceId)?.delete(agentId);
+      this.refreshPromptTime(workspaceId);
+    }
     this.cache.delete(agentId);
     this.removeOwnerIndex(agentId);
     this.pathById.delete(agentId);
@@ -261,6 +407,8 @@ export class AgentStorage {
       if (existing && existing.archivedAt !== undefined) {
         record.archivedAt = existing.archivedAt;
       }
+      // Background is fixed at creation; a runtime opened without it cannot clear it.
+      if (existing?.background) record.background = true;
       record.resumeOnStartup =
         existing?.resumeOnStartup && agent.lifecycle !== "idle" && agent.lifecycle !== "error";
       return record;
@@ -283,9 +431,9 @@ export class AgentStorage {
     await Promise.allSettled(writes);
   }
 
-  private async load(): Promise<StoredAgentRecord[]> {
+  private async load(): Promise<void> {
     if (this.loaded) {
-      return Array.from(this.cache.values());
+      return;
     }
 
     if (!this.loadPromise) {
@@ -295,7 +443,7 @@ export class AgentStorage {
     return this.loadPromise;
   }
 
-  private async doLoad(): Promise<StoredAgentRecord[]> {
+  private async doLoad(): Promise<void> {
     this.cache.clear();
     this.pathById.clear();
     this.pathsById.clear();
@@ -303,28 +451,25 @@ export class AgentStorage {
     this.daemonExecutionKeysByAgentId.clear();
 
     try {
-      const records = await this.scanDisk();
+      await this.scanDisk();
       this.loaded = true;
-      return records;
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
         this.loaded = true;
-        return [];
+        return;
       }
       this.logger.error({ err: error }, "Failed to load agents");
       this.loaded = true;
-      return [];
     }
   }
 
-  private async scanDisk(): Promise<StoredAgentRecord[]> {
-    const records: StoredAgentRecord[] = [];
+  private async scanDisk(): Promise<void> {
     let entries: Dirent[] = [];
     try {
       entries = await fs.readdir(this.baseDir, { withFileTypes: true });
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return [];
+        return;
       }
       throw error;
     }
@@ -361,14 +506,11 @@ export class AgentStorage {
     for (const item of loaded) {
       if (!item) continue;
       const { record, filePath } = item;
-      records.push(record);
       this.cache.set(record.id, record);
       this.indexOwner(record);
       this.pathById.set(record.id, filePath);
       this.addIndexedPath(record.id, filePath);
     }
-
-    return records;
   }
 
   private async readRecordFile(filePath: string): Promise<StoredAgentRecord | null> {
@@ -405,6 +547,7 @@ export class AgentStorage {
   }
 
   private indexOwner(record: StoredAgentRecord): void {
+    this.indexWorkspace(record);
     this.removeOwnerIndex(record.id);
     if (record.owner?.kind === "daemon") {
       const key = daemonExecutionKey(record.owner);
diff --git a/packages/server/src/server/agent/background-work/index.test.ts b/packages/server/src/server/agent/background-work/index.test.ts
new file mode 100644
index 0000000000..3a8f28dfea
--- /dev/null
+++ b/packages/server/src/server/agent/background-work/index.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, test } from "vitest";
+
+import { AgentBackgroundWorkStore } from "./index.js";
+
+const T0 = "2026-10-06T10:00:00.000Z";
+const T1 = "2026-10-06T10:05:00.000Z";
+
+describe("AgentBackgroundWorkStore", () => {
+  test("stamps new items and keeps their start time across replacements", () => {
+    const store = new AgentBackgroundWorkStore();
+
+    expect(
+      store.apply("agent-a", [{ id: "bash-1", kind: "shell", description: "sleep 20" }], T0),
+    ).toEqual([{ id: "bash-1", kind: "shell", description: "sleep 20", startedAt: T0 }]);
+
+    expect(
+      store.apply(
+        "agent-a",
+        [
+          { id: "bash-1", kind: "shell", description: "sleep 20" },
+          { id: "task-1", kind: "other", description: null },
+        ],
+        T1,
+      ),
+    ).toEqual([
+      { id: "bash-1", kind: "shell", description: "sleep 20", startedAt: T0 },
+      { id: "task-1", kind: "other", description: null, startedAt: T1 },
+    ]);
+  });
+
+  test("returns null when the replacement changes nothing", () => {
+    const store = new AgentBackgroundWorkStore();
+    store.apply("agent-a", [{ id: "bash-1", kind: "shell", description: "sleep 20" }], T0);
+
+    expect(
+      store.apply("agent-a", [{ id: "bash-1", kind: "shell", description: "sleep 20" }], T1),
+    ).toBeNull();
+    expect(store.apply("agent-b", [], T1)).toEqual([]);
+    expect(store.apply("agent-b", [], T1)).toBeNull();
+  });
+
+  test("distinguishes an unknown inventory from an observed empty inventory", () => {
+    const store = new AgentBackgroundWorkStore();
+    expect(store.summary("agent-a")).toBeUndefined();
+    store.apply("agent-a", []);
+    expect(store.summary("agent-a")).toEqual({ count: 0 });
+    store.clear("agent-a");
+    expect(store.summary("agent-a")).toBeUndefined();
+  });
+
+  test("keeps the first occurrence of a duplicated id", () => {
+    const store = new AgentBackgroundWorkStore();
+
+    expect(
+      store.apply(
+        "agent-a",
+        [
+          { id: "bash-1", kind: "shell", description: "first" },
+          { id: "bash-1", kind: "shell", description: "second" },
+        ],
+        T0,
+      ),
+    ).toEqual([{ id: "bash-1", kind: "shell", description: "first", startedAt: T0 }]);
+  });
+
+  test("scopes lists per agent and clears one agent", () => {
+    const store = new AgentBackgroundWorkStore();
+    store.apply("agent-a", [{ id: "bash-1", kind: "shell", description: null }], T0);
+    store.apply("agent-b", [{ id: "bash-2", kind: "shell", description: null }], T0);
+
+    expect(store.clear("agent-a")).toEqual([]);
+    expect(store.clear("agent-a")).toBeNull();
+    expect(store.list("agent-a")).toEqual([]);
+    expect(store.list("agent-b")).toHaveLength(1);
+  });
+
+  test("keeps only the wire fields of each input", () => {
+    const store = new AgentBackgroundWorkStore();
+    const input = { id: "bash-1", kind: "shell", description: null, pid: 4242 };
+
+    expect(store.apply("agent-a", [input], T0)).toEqual([
+      { id: "bash-1", kind: "shell", description: null, startedAt: T0 },
+    ]);
+  });
+
+  test("list returns a copy", () => {
+    const store = new AgentBackgroundWorkStore();
+    store.apply("agent-a", [{ id: "bash-1", kind: "shell", description: null }], T0);
+
+    store.list("agent-a").pop();
+
+    expect(store.list("agent-a")).toHaveLength(1);
+  });
+});
+
+test("stop tokens follow a live item and change when an id is reused", () => {
+  const store = new AgentBackgroundWorkStore();
+  const input = { id: "1", kind: "shell", description: null, canStop: true };
+  const first = store.apply("agent", [input], T0)![0];
+  expect(first.stopToken).toBeTruthy();
+  expect(store.apply("agent", [input], T1)).toBeNull();
+  store.apply("agent", []);
+  const second = store.apply("agent", [input], T0)![0];
+  expect(second.stopToken).not.toBe(first.stopToken);
+});
+
+test("revokes a stop token while inventory ownership is being re-established", () => {
+  const store = new AgentBackgroundWorkStore();
+  const item = { id: "1", kind: "shell", description: null, canStop: true };
+  const first = store.apply("agent", [item])![0];
+  const stale = store.apply("agent", [{ ...item, canStop: false }])![0];
+  expect(stale.stopToken).toBeUndefined();
+  expect(store.apply("agent", [item])![0].stopToken).not.toBe(first.stopToken);
+});
+
+test("publishes command changes without replacing a live item's identity", () => {
+  const store = new AgentBackgroundWorkStore();
+  const item = {
+    id: "1",
+    kind: "monitor",
+    description: "Watch build",
+    command: "tail -f build.log",
+    canStop: true,
+  };
+  const first = store.apply("agent", [item], T0)![0];
+  expect(first.command).toBe("tail -f build.log");
+  const changed = store.apply("agent", [{ ...item, command: "tail -f other.log" }], T1)![0];
+  expect(changed).toMatchObject({
+    command: "tail -f other.log",
+    startedAt: T0,
+    stopToken: first.stopToken,
+  });
+});
diff --git a/packages/server/src/server/agent/background-work/index.ts b/packages/server/src/server/agent/background-work/index.ts
new file mode 100644
index 0000000000..3290f13503
--- /dev/null
+++ b/packages/server/src/server/agent/background-work/index.ts
@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+
+export interface AgentBackgroundWorkInput {
+  id: string;
+  /** Provider-neutral kind; consumers treat unknown kinds as other work. */
+  kind: string;
+  description: string | null;
+  command?: string;
+  canStop?: boolean;
+}
+
+export interface AgentBackgroundWorkItem extends AgentBackgroundWorkInput {
+  startedAt: string;
+  stopToken?: string;
+}
+
+/**
+ * Live background work per agent. Providers report the whole list on every change, so `apply`
+ * replaces it. `startedAt` is stamped the first time an id is seen and kept while it stays listed.
+ * Nothing is persisted; providers determine when their live inventory is no longer available.
+ */
+export class AgentBackgroundWorkStore {
+  private readonly items = new Map<string, AgentBackgroundWorkItem[]>();
+
+  apply(
+    agentId: string,
+    inputs: readonly AgentBackgroundWorkInput[],
+    timestamp: string = new Date().toISOString(),
+  ): AgentBackgroundWorkItem[] | null {
+    const known = this.items.has(agentId);
+    const previous = this.items.get(agentId) ?? [];
+    const previousById = new Map(previous.map((item) => [item.id, item]));
+    const seen = new Set<string>();
+    const next: AgentBackgroundWorkItem[] = [];
+    for (const input of inputs) {
+      if (seen.has(input.id)) continue;
+      seen.add(input.id);
+      next.push({
+        id: input.id,
+        kind: input.kind,
+        description: input.description,
+        ...(input.command ? { command: input.command } : {}),
+        ...(input.canStop
+          ? { canStop: true, stopToken: previousById.get(input.id)?.stopToken ?? randomUUID() }
+          : {}),
+        startedAt: previousById.get(input.id)?.startedAt ?? timestamp,
+      });
+    }
+    if (known && sameItems(previous, next)) return null;
+    this.items.set(agentId, next);
+    return [...next];
+  }
+
+  list(agentId: string): AgentBackgroundWorkItem[] {
+    return [...(this.items.get(agentId) ?? [])];
+  }
+
+  summary(agentId: string): { count: number } | undefined {
+    const items = this.items.get(agentId);
+    return items ? { count: items.length } : undefined;
+  }
+
+  clear(agentId: string): AgentBackgroundWorkItem[] | null {
+    if (!this.items.delete(agentId)) return null;
+    return [];
+  }
+}
+
+function sameItems(
+  left: readonly AgentBackgroundWorkItem[],
+  right: readonly AgentBackgroundWorkItem[],
+): boolean {
+  return (
+    left.length === right.length &&
+    left.every((item, index) => {
+      const other = right[index];
+      return (
+        item.id === other.id &&
+        item.kind === other.kind &&
+        item.description === other.description &&
+        item.command === other.command &&
+        item.canStop === other.canStop &&
+        item.stopToken === other.stopToken &&
+        item.startedAt === other.startedAt
+      );
+    })
+  );
+}
diff --git a/packages/server/src/server/agent/create-agent-mode.test.ts b/packages/server/src/server/agent/create-agent-mode.test.ts
index dd7d83d8a4..1662ec4c25 100644
--- a/packages/server/src/server/agent/create-agent-mode.test.ts
+++ b/packages/server/src/server/agent/create-agent-mode.test.ts
@@ -78,7 +78,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         availableModes: OPENCODE_MODES,
       }),
     ).toThrow(
-      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'opencode'). Pass an explicit mode. Available modes for 'opencode': build, plan",
+      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'opencode'). Pass an explicit mode in settings.modeId. Available modes for 'opencode': build, plan",
     );
   });
 
@@ -92,7 +92,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         availableModes: CODEX_MODES,
       }),
     ).toThrow(
-      "cannot inherit mode '<none>' from caller (provider 'opencode') for new agent (provider 'codex'). Pass an explicit mode. Available modes for 'codex': auto, full-access",
+      "cannot inherit mode '<none>' from caller (provider 'opencode') for new agent (provider 'codex'). Pass an explicit mode in settings.modeId. Available modes for 'codex': auto, full-access",
     );
   });
 
@@ -180,7 +180,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         targetUnattendedMode: "full-access",
       }),
     ).toThrow(
-      "cannot inherit mode 'default' from caller (provider 'claude') for new agent (provider 'codex'). Pass an explicit mode. Available modes for 'codex': auto, full-access",
+      "cannot inherit mode 'default' from caller (provider 'claude') for new agent (provider 'codex'). Pass an explicit mode in settings.modeId. Available modes for 'codex': auto, full-access",
     );
   });
 
@@ -195,7 +195,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         targetUnattendedMode: undefined,
       }),
     ).toThrow(
-      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'zai-custom'). Pass an explicit mode. Available modes for 'zai-custom': unknown",
+      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'zai-custom'). Pass an explicit mode in settings.modeId. Available modes for 'zai-custom': unknown",
     );
   });
 
diff --git a/packages/server/src/server/agent/create-agent-mode.ts b/packages/server/src/server/agent/create-agent-mode.ts
index 973642e475..1c8343769e 100644
--- a/packages/server/src/server/agent/create-agent-mode.ts
+++ b/packages/server/src/server/agent/create-agent-mode.ts
@@ -77,7 +77,7 @@ export function resolveAndValidateCreateAgentMode(
   }
 
   throw new Error(
-    `cannot inherit mode '${formatCreateConfigParentMode(parent)}' from ${formatCreateConfigParentSource(parent)} for new agent (provider '${targetProvider}'). Pass an explicit mode. Available modes for '${targetProvider}': ${listModes(availableModes)}`,
+    `cannot inherit mode '${formatCreateConfigParentMode(parent)}' from ${formatCreateConfigParentSource(parent)} for new agent (provider '${targetProvider}'). Pass an explicit mode in settings.modeId. Available modes for '${targetProvider}': ${listModes(availableModes)}`,
   );
 }
 
@@ -94,7 +94,7 @@ export function resolveDefaultAgentCreateConfig(
       availableModes: availableModeIds,
       targetUnattendedMode: input.availableModes?.find(isUnattendedMode)?.id,
     }),
-    featureValues: input.featureValues,
+    providerOptions: input.providerOptions,
   };
 }
 
diff --git a/packages/server/src/server/agent/create-agent/create.test.ts b/packages/server/src/server/agent/create-agent/create.test.ts
index daa5ba9ec1..4943628b17 100644
--- a/packages/server/src/server/agent/create-agent/create.test.ts
+++ b/packages/server/src/server/agent/create-agent/create.test.ts
@@ -147,7 +147,7 @@ test("session create applies the resolved mode from the provider create config",
   const stub = createProviderSnapshotManagerStub();
   stub.resolveCreateConfig.mockResolvedValue({
     modeId: "build",
-    featureValues: { auto_accept: true },
+    providerOptions: { auto_accept: true },
   });
   const dependencies: Parameters<typeof createAgentCommand>[0] = {
     agentManager: {
@@ -171,7 +171,7 @@ test("session create applies the resolved mode from the provider create config",
   expect(createAgent).toHaveBeenCalledWith(
     expect.objectContaining({
       modeId: "build",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     }),
     undefined,
     expect.anything(),
diff --git a/packages/server/src/server/agent/create-agent/create.ts b/packages/server/src/server/agent/create-agent/create.ts
index 77cdde673b..10782907b3 100644
--- a/packages/server/src/server/agent/create-agent/create.ts
+++ b/packages/server/src/server/agent/create-agent/create.ts
@@ -21,7 +21,19 @@ import { resolveCreateAgentTitles } from "../create-agent-title.js";
 import { buildAgentPrompt } from "../prompt-attachments.js";
 import { normalizeClientMessageId, resolveClientMessageId } from "../../client-message-id.js";
 import { resolveRequiredProviderModel, type ResolvedProviderModel } from "../mcp-shared.js";
-import { resolveCreateAgentIntent } from "./intent.js";
+import {
+  inheritAgentBackground,
+  inheritWorkspaceBackground,
+  resolveCreateAgentIntent,
+} from "./intent.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { foldFeatureValues, type LegacyFeatureValues } from "../option-controls.js";
+
+/** How a workspace this creation makes inherits its creator's visibility. */
+interface McpWorkspaceIntent {
+  background?: boolean;
+  callerWorkspaceId?: string;
+}
 
 export interface CreateAgentCommandDependencies {
   finishSubscriptions?: FinishSubscriptions;
@@ -40,15 +52,17 @@ export interface CreateAgentCommandDependencies {
 export type EnsureWorkspaceForCreate = (
   cwd: string,
   firstAgentContext?: FirstAgentContext,
-  context?: { callerWorkspaceId?: string },
+  context?: { background?: boolean; callerWorkspaceId?: string },
 ) => Promise<string>;
 
 export interface CreateAgentFromSessionInput {
   kind: "session";
   onAgentReady?: (agent: ManagedAgent) => Promise<void>;
   agentId?: string;
-  config: AgentSessionConfig;
+  /** Wire configs from older clients can still carry `featureValues`; they are folded on entry. */
+  config: AgentSessionConfig & LegacyFeatureValues;
   workspaceId: string;
+  background: boolean;
   initialPrompt?: string;
   source?: AgentPromptSource;
   clientMessageId?: string;
@@ -56,6 +70,7 @@ export interface CreateAgentFromSessionInput {
   images?: Array<{ data: string; mimeType: string }>;
   attachments?: AgentAttachment[];
   labels: Record<string, string>;
+  metadata?: CreateAgentOptions["metadata"];
   env?: Record<string, string>;
   provisionalTitle: string | null;
   firstAgentContext: FirstAgentContext;
@@ -70,13 +85,15 @@ export interface CreateAgentFromMcpInput {
   cwd?: string;
   workspaceId?: string;
   thinking?: string;
-  features?: Record<string, unknown>;
+  providerOptions?: ProviderOptions;
   labels?: Record<string, string>;
   mode?: string;
   unattended?: boolean;
   promptFailure?: CreateAgentPromptFailureMode;
   notifyOnFinish: boolean;
   internal?: boolean;
+  /** Omitted with a caller, the caller agent's own background applies. */
+  background?: boolean;
   detached?: boolean;
   owner?: AgentOwner;
   env?: Record<string, string>;
@@ -218,19 +235,19 @@ async function resolveSessionCreateAgent(
   input: CreateAgentFromSessionInput,
 ): Promise<ResolvedCreateAgent> {
   const trimmedPrompt = input.initialPrompt?.trim();
-  const builtSessionConfig = input.config;
+  const builtSessionConfig = foldFeatureValues(input.config);
   const resolvedCreateConfig = await dependencies.providerSnapshotManager.resolveCreateConfig({
     cwd: builtSessionConfig.cwd,
     provider: builtSessionConfig.provider,
     requestedMode: builtSessionConfig.modeId,
-    featureValues: builtSessionConfig.featureValues,
+    providerOptions: builtSessionConfig.providerOptions,
     parent: null,
     unattended: false,
   });
   const sessionConfig: AgentSessionConfig = {
     ...builtSessionConfig,
     modeId: resolvedCreateConfig.modeId,
-    featureValues: resolvedCreateConfig.featureValues,
+    providerOptions: resolvedCreateConfig.providerOptions,
   };
   const prompt = buildAgentPrompt(trimmedPrompt ?? "", input.images, input.attachments);
   const hasPromptContent = Array.isArray(prompt) ? prompt.length > 0 : prompt.length > 0;
@@ -248,6 +265,7 @@ async function resolveSessionCreateAgent(
     config: sessionConfig,
     createOptions: {
       labels: input.labels,
+      metadata: input.metadata,
       initialPrompt: trimmedPrompt,
       env: input.env,
       initialTitle: input.provisionalTitle,
@@ -255,6 +273,7 @@ async function resolveSessionCreateAgent(
       // provider session either. Same as the daemon's own ephemeral helpers.
       ...(sessionConfig.internal ? { persistSession: false } : {}),
       workspaceId: requireResolvedWorkspaceId(workspaceId),
+      background: input.background,
     },
     prompt: hasPromptContent ? prompt : undefined,
     source: input.source,
@@ -277,12 +296,16 @@ async function resolveMcpCreateAgent(
     ? requireParentAgent(dependencies.agentManager, input.callerAgentId)
     : null;
   const cwd = resolveMcpInitialCwd(input, parentAgent);
+  const workspaceIntent = {
+    background: inheritWorkspaceBackground(input.background, parentAgent),
+    callerWorkspaceId: parentAgent?.workspaceId,
+  };
   const { resolvedCwd, createdWorkspaceId, createdWorktree } = await resolveMcpCwd({
     dependencies,
     cwd,
     worktree: input.worktree,
     initialPrompt: input.initialPrompt ?? "",
-    callerWorkspaceId: parentAgent?.workspaceId,
+    workspaceIntent,
   });
   if (createdWorktree) input.onWorktreeCreated?.(createdWorktree);
   const intent = await resolveCreateAgentIntent({
@@ -300,7 +323,7 @@ async function resolveMcpCreateAgent(
           dependencies,
           resolvedCwd,
           input.initialPrompt ?? "",
-          parentAgent?.workspaceId,
+          workspaceIntent,
         ),
       ),
       cwd: resolvedCwd,
@@ -323,12 +346,13 @@ async function resolveMcpCreateAgent(
       resolvedCwd: intent.cwd,
       trimmedPrompt,
       resolvedMode: resolvedCreateConfig.modeId,
-      resolvedFeatures: resolvedCreateConfig.featureValues,
+      resolvedProviderOptions: resolvedCreateConfig.providerOptions,
     }),
     createOptions: {
       ...(Object.keys(intent.labels).length > 0 ? { labels: intent.labels } : {}),
       workspaceId: intent.workspaceId,
       owner: input.owner,
+      background: inheritAgentBackground(input.background, parentAgent),
       env: input.env,
     },
     prompt: trimmedPrompt ? trimmedPrompt : undefined,
@@ -361,18 +385,23 @@ async function resolveMcpProviderCreateConfig(params: {
   provider: string;
   resolvedCwd: string;
   parentAgent: ManagedAgent | null;
-}): Promise<{ modeId?: string; featureValues?: Record<string, unknown> }> {
+}): Promise<{ modeId?: string; providerOptions?: ProviderOptions }> {
   const passthroughConfig = params.input.config;
   return params.dependencies.providerSnapshotManager.resolveCreateConfig({
     cwd: params.resolvedCwd,
     provider: params.provider,
     requestedMode: params.input.mode ?? passthroughConfig?.modeId,
-    featureValues: params.input.features ?? passthroughConfig?.featureValues,
+    providerOptions: mergeMcpProviderOptions(params.input),
     parent: params.parentAgent,
     unattended: params.input.unattended ?? false,
   });
 }
 
+function mergeMcpProviderOptions(input: CreateAgentFromMcpInput): ProviderOptions | undefined {
+  if (!input.providerOptions) return input.config?.providerOptions;
+  return { ...input.config?.providerOptions, ...input.providerOptions };
+}
+
 function buildMcpSessionConfig(params: {
   input: CreateAgentFromMcpInput;
   resolvedProviderModel: ResolvedProviderModel;
@@ -380,14 +409,14 @@ function buildMcpSessionConfig(params: {
   resolvedCwd: string;
   trimmedPrompt: string;
   resolvedMode?: string;
-  resolvedFeatures?: Record<string, unknown>;
+  resolvedProviderOptions?: ProviderOptions;
 }): AgentSessionConfig {
   const passthroughConfig = params.input.config;
   const { provisionalTitle } = resolveCreateAgentTitles({
     configTitle: passthroughConfig?.title ?? params.input.title,
     initialPrompt: params.trimmedPrompt,
   });
-  const featureValues = params.resolvedFeatures ?? passthroughConfig?.featureValues;
+  const providerOptions = params.resolvedProviderOptions ?? mergeMcpProviderOptions(params.input);
   const config: AgentSessionConfig = {
     ...passthroughConfig,
     provider: params.provider,
@@ -400,8 +429,8 @@ function buildMcpSessionConfig(params: {
   if (provisionalTitle) {
     config.title = provisionalTitle;
   }
-  if (featureValues) {
-    config.featureValues = featureValues;
+  if (providerOptions) {
+    config.providerOptions = providerOptions;
   }
   return config;
 }
@@ -410,16 +439,12 @@ async function ensureWorkspaceForMcpCreate(
   dependencies: CreateAgentCommandDependencies,
   cwd: string,
   initialPrompt: string,
-  callerWorkspaceId?: string,
+  workspaceIntent: McpWorkspaceIntent,
 ): Promise<string | undefined> {
   if (!dependencies.ensureWorkspaceForCreate) {
     return undefined;
   }
-  return dependencies.ensureWorkspaceForCreate(
-    cwd,
-    { prompt: initialPrompt },
-    { callerWorkspaceId },
-  );
+  return dependencies.ensureWorkspaceForCreate(cwd, { prompt: initialPrompt }, workspaceIntent);
 }
 
 async function sendInitialPrompt(
@@ -512,7 +537,7 @@ async function resolveMcpCwd(params: {
   dependencies: CreateAgentCommandDependencies;
   cwd: string;
   initialPrompt: string;
-  callerWorkspaceId?: string;
+  workspaceIntent: McpWorkspaceIntent;
   worktree: CreateAgentFromMcpInput["worktree"];
 }): Promise<{
   resolvedCwd: string;
@@ -542,7 +567,7 @@ async function resolveMcpCwd(params: {
   const createdWorktree = await createMcpWorktree({
     input: {
       cwd: params.cwd,
-      callerWorkspaceId: params.callerWorkspaceId,
+      ...params.workspaceIntent,
       worktreeSlug: worktree.worktreeName,
       branchName: worktree.branchName,
       refName: worktree.refName,
diff --git a/packages/server/src/server/agent/create-agent/intent.ts b/packages/server/src/server/agent/create-agent/intent.ts
index c811144b74..d9ea675b6f 100644
--- a/packages/server/src/server/agent/create-agent/intent.ts
+++ b/packages/server/src/server/agent/create-agent/intent.ts
@@ -6,6 +6,30 @@ export interface CreateAgentCaller {
   workspaceId?: string;
 }
 
+/** The agent on whose behalf something is created, as far as background inheritance goes. */
+export interface BackgroundCaller {
+  background?: boolean;
+}
+
+/** Omitted, an agent inherits its caller agent's own background; without a caller it is visible. */
+export function inheritAgentBackground(
+  requested: boolean | undefined,
+  caller: BackgroundCaller | null | undefined,
+): boolean {
+  return requested ?? caller?.background === true;
+}
+
+/**
+ * Omitted, a new workspace inherits its caller's effective background. A background caller
+ * agent decides it here; otherwise `undefined` lets provisioning apply the caller workspace's value.
+ */
+export function inheritWorkspaceBackground(
+  requested: boolean | undefined,
+  caller: BackgroundCaller | null | undefined,
+): boolean | undefined {
+  return requested ?? (caller?.background === true ? true : undefined);
+}
+
 export interface CreateAgentPlacement {
   workspaceId: string;
   cwd: string;
diff --git a/packages/server/src/server/agent/directory.test.ts b/packages/server/src/server/agent/directory.test.ts
new file mode 100644
index 0000000000..647db9aef9
--- /dev/null
+++ b/packages/server/src/server/agent/directory.test.ts
@@ -0,0 +1,140 @@
+import { resolveWorkspaceRootAgent } from "../workspace-directory.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, expect, test } from "vitest";
+
+import { createTestLogger } from "../../test-utils/test-logger.js";
+import { buildStoredAgentPayload } from "./agent-projections.js";
+import { AgentStorage } from "./agent-storage.js";
+import { AgentDirectory, type BackgroundVisibility } from "./directory.js";
+import type { PersistedWorkspaceRecord } from "../workspace-registry.js";
+
+const NOW = "2026-03-01T12:00:00.000Z";
+
+let home: string;
+let storage: AgentStorage;
+let directory: AgentDirectory;
+
+function workspace(workspaceId: string, background: boolean): PersistedWorkspaceRecord {
+  return {
+    workspaceId,
+    projectId: "project",
+    cwd: home,
+    kind: "local_checkout",
+    displayName: workspaceId,
+    background,
+    createdAt: NOW,
+    updatedAt: NOW,
+    archivedAt: null,
+  };
+}
+
+beforeEach(async () => {
+  home = await mkdtemp(join(tmpdir(), "agent-directory-"));
+  storage = new AgentStorage(home, createTestLogger());
+  const base = {
+    provider: "codex",
+    cwd: home,
+    createdAt: NOW,
+    updatedAt: NOW,
+    labels: {},
+    lastStatus: "idle" as const,
+  };
+  await storage.upsert({ ...base, id: "visible", workspaceId: "open" });
+  await storage.upsert({ ...base, id: "background", workspaceId: "open", background: true });
+  await storage.upsert({ ...base, id: "in-background-workspace", workspaceId: "hidden" });
+  await storage.upsert({ ...base, id: "internal", workspaceId: "open", internal: true });
+  const workspaces = [workspace("open", false), workspace("hidden", true)];
+  directory = new AgentDirectory({
+    storage,
+    manager: { listAgents: () => [] },
+    workspaces: {
+      get: async (id) => workspaces.find((entry) => entry.workspaceId === id) ?? null,
+    },
+    projectLive: () => {
+      throw new Error("No live agents in this suite");
+    },
+    projectStored: (record) =>
+      buildStoredAgentPayload(record, ["codex"], (_provider, own) => own ?? {}),
+    isProviderVisible: () => true,
+    isStoredProviderAvailable: () => true,
+  });
+});
+
+afterEach(async () => {
+  await rm(home, { recursive: true, force: true });
+});
+
+async function listedIds(includeBackground: BackgroundVisibility): Promise<string[]> {
+  return (await directory.list({ includeBackground })).map((agent) => agent.id).toSorted();
+}
+
+test("default lists hide agents that are background or live in a background workspace", async () => {
+  expect(await listedIds(false)).toEqual(["visible"]);
+});
+
+test("inclusive lists show every background agent", async () => {
+  expect(await listedIds(true)).toEqual(["background", "in-background-workspace", "visible"]);
+});
+
+test("workspace-only visibility hides agent-level background agents from older clients", async () => {
+  expect(await listedIds("workspaces")).toEqual(["in-background-workspace", "visible"]);
+});
+
+test("includes applies the same visibility to a single agent", async () => {
+  const background = { workspaceId: "open", background: true };
+  const inBackgroundWorkspace = { workspaceId: "hidden" };
+  expect(await directory.includes(background)).toBe(false);
+  expect(await directory.includes(background, "workspaces")).toBe(false);
+  expect(await directory.includes(background, true)).toBe(true);
+  expect(await directory.includes(inBackgroundWorkspace)).toBe(false);
+  expect(await directory.includes(inBackgroundWorkspace, "workspaces")).toBe(true);
+});
+
+test("prompt recency ignores background agents", async () => {
+  const base = {
+    provider: "codex",
+    cwd: home,
+    workspaceId: "open",
+    createdAt: NOW,
+    updatedAt: NOW,
+    labels: {},
+    lastStatus: "idle" as const,
+  };
+  await storage.upsert({ ...base, id: "visible", lastUserMessageAt: "2026-03-02T00:00:00.000Z" });
+  await storage.upsert({
+    ...base,
+    id: "background",
+    background: true,
+    lastUserMessageAt: "2026-03-03T00:00:00.000Z",
+  });
+  expect(await directory.workspaceLastUserMessageTimes()).toEqual(
+    new Map([["open", "2026-03-02T00:00:00.000Z"]]),
+  );
+});
+
+test("scoped status queries retain cross-workspace parent context", async () => {
+  const base = { provider: "codex", cwd: home, createdAt: NOW, updatedAt: NOW };
+  await storage.upsert({ ...base, id: "parent", workspaceId: "open" });
+  await storage.upsert({
+    ...base,
+    id: "child",
+    workspaceId: "hidden",
+    labels: { "paseo.parent-agent-id": "parent" },
+    lastStatus: "running",
+  });
+  const agents = await directory.list({
+    workspaceIds: ["hidden"],
+    includeBackground: true,
+    includeAncestors: true,
+  });
+  const child = agents.find((agent) => agent.id === "child")!;
+  expect(
+    resolveWorkspaceRootAgent(child, new Map(agents.map((agent) => [agent.id, agent])))?.id,
+  ).toBe("child");
+  expect(child.status).toBe("running");
+  expect(
+    (await directory.list({ workspaceIds: ["hidden"], includeBackground: true })).map((a) => a.id),
+  ).not.toContain("parent");
+});
diff --git a/packages/server/src/server/agent/directory.ts b/packages/server/src/server/agent/directory.ts
index b15053ff04..1f3b88df67 100644
--- a/packages/server/src/server/agent/directory.ts
+++ b/packages/server/src/server/agent/directory.ts
@@ -1,15 +1,37 @@
+import { getParentAgentIdFromLabels } from "@getpaseo/protocol/agent-labels";
 import type { AgentSnapshotPayload } from "../messages.js";
 import type { WorkspaceRegistry } from "../workspace-registry.js";
 import type { AgentManager, ManagedAgent } from "./agent-manager.js";
 import type { AgentStorage, StoredAgentRecord } from "./agent-storage.js";
 
-/** Public agent discovery owns workspace visibility for live and durable records. */
+/**
+ * Which background agents a discovery read admits. An agent is effectively background when
+ * it or its workspace is background.
+ * - `false`: none, the default for lists.
+ * - `true`: all of them.
+ * - `"workspaces"`: only agents in background workspaces.
+ *   COMPAT(backgroundAgents): added in v0.15.0, remove after 2027-05-03 once client floor
+ *   >= v0.15.0. Inclusive reads from sources without `background_agents` use it: older apps
+ *   replicate inclusively and auto-open a tab for every root agent.
+ */
+export type BackgroundVisibility = boolean | "workspaces";
+
+interface DiscoverableAgent {
+  workspaceId?: string;
+  internal?: boolean;
+  background?: boolean;
+}
+
+/** Public agent discovery owns background visibility for live and durable records. */
 export class AgentDirectory {
   constructor(
     private readonly deps: {
       manager: Pick<AgentManager, "listAgents">;
-      storage: Pick<AgentStorage, "list">;
-      workspaces: Pick<WorkspaceRegistry, "get" | "list">;
+      storage: Pick<
+        AgentStorage,
+        "get" | "listActive" | "listByWorkspaces" | "lastUserMessageAtByWorkspace"
+      >;
+      workspaces: Pick<WorkspaceRegistry, "get">;
       projectLive(agent: ManagedAgent): Promise<AgentSnapshotPayload>;
       projectStored(record: StoredAgentRecord): AgentSnapshotPayload;
       isProviderVisible(provider: string): boolean;
@@ -18,70 +40,127 @@ export class AgentDirectory {
   ) {}
 
   /** Human prompt recency includes archived/unavailable agents without projecting their UI payloads. */
-  async workspaceLastUserMessageTimes(): Promise<Map<string, string>> {
+  async workspaceLastUserMessageTimes(
+    workspaceIds?: Iterable<string>,
+  ): Promise<Map<string, string>> {
+    const requested = workspaceIds ? new Set(workspaceIds) : undefined;
     const live = this.deps.manager.listAgents();
-    const liveIds = new Set(live.map((agent) => agent.id));
-    const times = new Map<string, string>();
-    const record = (workspaceId: string | undefined, at: string | null | undefined) => {
-      if (!workspaceId || !at) return;
-      const previous = times.get(workspaceId);
-      if (!previous || at > previous) times.set(workspaceId, at);
-    };
-    for (const agent of await this.deps.storage.list()) {
-      if (!agent.internal && !liveIds.has(agent.id))
-        record(agent.workspaceId, agent.lastUserMessageAt);
-    }
+    const times = new Map(
+      await this.deps.storage.lastUserMessageAtByWorkspace(requested, {
+        excludeAgentIds: live.map((agent) => agent.id),
+      }),
+    );
     for (const agent of live) {
-      if (!agent.internal) record(agent.workspaceId, agent.lastUserMessageAt?.toISOString());
+      if (agent.internal || agent.background || !agent.workspaceId || !agent.lastUserMessageAt)
+        continue;
+      if (requested && !requested.has(agent.workspaceId)) continue;
+      const at = agent.lastUserMessageAt.toISOString();
+      if (at > (times.get(agent.workspaceId) ?? "")) times.set(agent.workspaceId, at);
     }
     return times;
   }
 
   async includes(
-    agent: Pick<AgentSnapshotPayload, "workspaceId" | "internal">,
-    includeBackground = false,
+    agent: DiscoverableAgent,
+    visibility: BackgroundVisibility = false,
   ): Promise<boolean> {
-    if (agent.internal) return false;
-    if (includeBackground || !agent.workspaceId) return true;
-    return !(await this.deps.workspaces.get(agent.workspaceId))?.background;
+    const workspace = agent.workspaceId ? await this.deps.workspaces.get(agent.workspaceId) : null;
+    return admits(agent, workspace?.background === true, visibility);
+  }
+
+  private async appendAncestors(
+    live: ManagedAgent[],
+    selectedLive: ManagedAgent[],
+    records: StoredAgentRecord[],
+  ): Promise<void> {
+    const selectedIds = new Set([...selectedLive, ...records].map((agent) => agent.id));
+    const liveById = new Map(live.map((agent) => [agent.id, agent]));
+    const pending = [...selectedLive, ...records];
+    for (const agent of pending) {
+      const parentId = getParentAgentIdFromLabels(agent.labels);
+      if (!parentId || selectedIds.has(parentId)) continue;
+      selectedIds.add(parentId);
+      const liveParent = liveById.get(parentId);
+      if (liveParent) {
+        pending.push(liveParent);
+        selectedLive.push(liveParent);
+      } else {
+        const storedParent = await this.deps.storage.get(parentId);
+        if (storedParent) {
+          pending.push(storedParent);
+          records.push(storedParent);
+        }
+      }
+    }
   }
 
   async list(filter?: {
+    workspaceIds?: Iterable<string>;
+    /** Include parent chains by ID for workspace root classification. */
+    includeAncestors?: boolean;
     labels?: Record<string, string>;
     includeArchived?: boolean;
-    includeBackground?: boolean;
+    includeBackground?: BackgroundVisibility;
     includeUnavailablePersisted?: boolean;
   }): Promise<AgentSnapshotPayload[]> {
+    const requested = filter?.workspaceIds ? new Set(filter.workspaceIds) : null;
     const live = this.deps.manager.listAgents();
     const liveIds = new Set(live.map((agent) => agent.id));
     const labels = Object.entries(filter?.labels ?? {});
-    const backgroundIds = new Set(
-      filter?.includeBackground
-        ? []
-        : (await this.deps.workspaces.list())
-            .filter((workspace) => workspace.background)
-            .map((workspace) => workspace.workspaceId),
+    const visibility = filter?.includeBackground ?? false;
+    const records = requested
+      ? await this.deps.storage.listByWorkspaces(requested, filter)
+      : await this.deps.storage.listActive(filter);
+    const selectedLive = requested
+      ? live.filter((agent) => requested.has(agent.workspaceId ?? ""))
+      : live;
+    if (filter?.includeAncestors && requested) {
+      await this.appendAncestors(live, selectedLive, records);
+    }
+
+    const workspaceIds = new Set(
+      [...selectedLive, ...records].flatMap((agent) =>
+        agent.workspaceId ? [agent.workspaceId] : [],
+      ),
     );
-    const matches = (agent: {
-      archivedAt?: string | null;
-      workspaceId?: string;
-      labels?: Record<string, string>;
-    }) =>
+    const backgroundWorkspaceIds = new Set<string>();
+    if (visibility !== true) {
+      for (const id of workspaceIds) {
+        if ((await this.deps.workspaces.get(id))?.background) backgroundWorkspaceIds.add(id);
+      }
+    }
+    const matches = (
+      agent: DiscoverableAgent & { archivedAt?: string | null; labels?: Record<string, string> },
+    ) =>
       (filter?.includeArchived || !agent.archivedAt) &&
-      (filter?.includeBackground || !agent.workspaceId || !backgroundIds.has(agent.workspaceId)) &&
+      admits(
+        agent,
+        agent.workspaceId !== undefined && backgroundWorkspaceIds.has(agent.workspaceId),
+        visibility,
+      ) &&
       labels.every(([key, value]) => agent.labels?.[key] === value);
-    const stored = (await this.deps.storage.list())
-      .filter((record) => !record.internal && !liveIds.has(record.id) && matches(record))
+    const stored = records
+      .filter((record) => !liveIds.has(record.id) && matches(record))
       .filter(
         (record) =>
           filter?.includeUnavailablePersisted || this.deps.isStoredProviderAvailable(record),
       )
       .map((record) => this.deps.projectStored(record));
     const active = await Promise.all(
-      live.filter(matches).map((agent) => this.deps.projectLive(agent)),
+      selectedLive.filter(matches).map((agent) => this.deps.projectLive(agent)),
     );
     return [...active, ...stored]
       .filter(matches)
       .filter((agent) => this.deps.isProviderVisible(agent.provider));
   }
 }
+
+function admits(
+  agent: DiscoverableAgent,
+  inBackgroundWorkspace: boolean,
+  visibility: BackgroundVisibility,
+): boolean {
+  if (agent.internal) return false;
+  if (agent.background) return visibility === true;
+  return !inBackgroundWorkspace || visibility !== false;
+}
diff --git a/packages/server/src/server/agent/finish-subscriptions/finish-subscriptions.test.ts b/packages/server/src/server/agent/finish-subscriptions/finish-subscriptions.test.ts
index 323e4be48f..9e18f87948 100644
--- a/packages/server/src/server/agent/finish-subscriptions/finish-subscriptions.test.ts
+++ b/packages/server/src/server/agent/finish-subscriptions/finish-subscriptions.test.ts
@@ -123,6 +123,7 @@ function outcome(status: "idle" | "running" | "closed" | "error" = "closed"): Wa
         lastStatus: status,
       },
       ["codex"],
+      (_provider, own) => own ?? {},
     ),
     lastMessage: "Partial work saved",
     error: null,
diff --git a/packages/server/src/server/agent/finish-subscriptions/internal/observation-stream.test.ts b/packages/server/src/server/agent/finish-subscriptions/internal/observation-stream.test.ts
index 1d15a890df..5bc0b3f7d7 100644
--- a/packages/server/src/server/agent/finish-subscriptions/internal/observation-stream.test.ts
+++ b/packages/server/src/server/agent/finish-subscriptions/internal/observation-stream.test.ts
@@ -43,6 +43,7 @@ class Host implements HostObservation {
           updatedAt: "2026-01-01",
         },
         ["codex"],
+        (_provider, own) => own ?? {},
       ),
       event,
       "Last response",
@@ -133,6 +134,7 @@ test("late initial permission snapshot cannot resurrect an already resolved requ
         updatedAt: "2026-01-01",
       },
       ["codex"],
+      (_provider, own) => own ?? {},
     );
     if (requestEvent.type !== "permission_requested") throw new Error("Expected permission");
     final.pendingPermissions = [requestEvent.request];
diff --git a/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts b/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
index 7abe483cf4..bfe77db3f2 100644
--- a/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
+++ b/packages/server/src/server/agent/finish-subscriptions/internal/observation.ts
@@ -34,7 +34,11 @@ export function createFinishObservation(input: {
           const stored = await agentStorage.get(agentId);
           return {
             status: stored?.lastStatus === "error" ? "error" : "idle",
-            final: stored ? buildStoredAgentPayload(stored, [stored.provider]) : null,
+            final: stored
+              ? buildStoredAgentPayload(stored, [stored.provider], (provider, own) =>
+                  agentManager.effectiveOptionsFor(provider, own),
+                )
+              : null,
             lastMessage: await agentManager.getLastAssistantMessage(agentId),
             error: stored?.lastError ?? null,
           };
@@ -93,7 +97,14 @@ export function createFinishObservation(input: {
             type: "turn_started",
             provider: current.provider,
           });
-        else publish(stored ? buildStoredAgentPayload(stored, [stored.provider]) : null);
+        else
+          publish(
+            stored
+              ? buildStoredAgentPayload(stored, [stored.provider], (provider, own) =>
+                  agentManager.effectiveOptionsFor(provider, own),
+                )
+              : null,
+          );
         const stop = () => unsubscribe();
         signal.addEventListener("abort", stop, { once: true });
         return async () => {
diff --git a/packages/server/src/server/agent/host-operations/index.test.ts b/packages/server/src/server/agent/host-operations/index.test.ts
new file mode 100644
index 0000000000..fbd492e881
--- /dev/null
+++ b/packages/server/src/server/agent/host-operations/index.test.ts
@@ -0,0 +1,149 @@
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { afterEach, expect, test } from "vitest";
+
+import { createHostResolver, type HostOperations } from "./index.js";
+
+type Handler = ((event?: unknown) => void) | null;
+
+/** A connected host from before background agents: background workspaces, no background agents. */
+class OlderHostSocket {
+  readyState = 1;
+  readonly requests: Array<Record<string, unknown>> = [];
+  onopen: Handler = null;
+  onmessage: Handler = null;
+  onclose: Handler = null;
+  onerror: Handler = null;
+  private readonly createSent = Promise.withResolvers<Record<string, unknown>>();
+
+  constructor() {
+    queueMicrotask(() => this.onopen?.());
+  }
+
+  createRequest(): Promise<Record<string, unknown>> {
+    return this.createSent.promise;
+  }
+
+  send(data: string): void {
+    const frame = JSON.parse(data);
+    if (frame.type === "hello") {
+      this.reply({
+        type: "status",
+        payload: {
+          status: "server_info",
+          serverId: "srv_older",
+          hostname: null,
+          version: null,
+          features: {
+            providerUsageList: true,
+            providersSnapshotCwd: true,
+            ownedSubscriptions: true,
+            backgroundWorkspaces: true,
+          },
+        },
+      });
+      return;
+    }
+    if (frame.type !== "session") return;
+    const message = frame.message;
+    this.requests.push(message);
+    if (message.type === "fetch_workspaces_request") {
+      this.reply({
+        type: "fetch_workspaces_response",
+        payload: {
+          requestId: message.requestId,
+          entries: [workspace],
+          pageInfo: emptyPage,
+        },
+      });
+    }
+    if (message.type === "create_agent_request") this.createSent.resolve(message);
+  }
+
+  close(): void {
+    this.readyState = 3;
+    this.onclose?.({ code: 1000, reason: "closed" });
+  }
+
+  private reply(message: object): void {
+    this.onmessage?.({ data: JSON.stringify({ type: "session", message }) });
+  }
+}
+
+const emptyPage = { nextCursor: null, prevCursor: null, hasMore: false };
+
+const workspace = {
+  id: "workspace_older",
+  projectId: "project_older",
+  projectDisplayName: "Older",
+  projectRootPath: "/repo/older",
+  workspaceDirectory: "/repo/older",
+  projectKind: "git",
+  workspaceKind: "directory",
+  name: "older",
+  archivingAt: null,
+  status: "done",
+  statusEnteredAt: null,
+  activityAt: "2026-05-16T00:00:00.000Z",
+  scripts: [],
+  gitRuntime: null,
+  githubRuntime: null,
+};
+
+const clients: DaemonClient[] = [];
+afterEach(async () => {
+  await Promise.all(clients.splice(0).map((client) => client.close()));
+});
+
+async function olderHost() {
+  const socket = new OlderHostSocket();
+  const client = new DaemonClient({
+    url: "ws://older.test",
+    clientId: "older-host-test",
+    webSocketFactory: () => socket,
+    reconnect: { enabled: false },
+  });
+  clients.push(client);
+  await client.connect();
+  return { client, socket };
+}
+
+function resolverFor(client: DaemonClient, callerBackground: boolean) {
+  return createHostResolver({
+    serverId: "origin",
+    callerAgentId: "caller",
+    caller: () => ({ background: callerBackground }),
+    local: {} as HostOperations,
+    hosts: () => ({
+      directory: async () => ({ self: { serverId: "origin", label: "Origin" }, hosts: [] }),
+      use: (_serverId, action) => action(client),
+    }),
+  });
+}
+
+const createArgs = {
+  workspaceId: workspace.id,
+  provider: "codex/gpt-5.4",
+  title: "Helper",
+  initialPrompt: "Summarize",
+};
+
+test("a visible caller still creates agents on a host without background agents", async () => {
+  const { client, socket } = await olderHost();
+  const creating = resolverFor(client, false).use("srv_older", (host) =>
+    host.createAgent(createArgs, {} as never),
+  );
+  creating.catch(() => {});
+
+  const request = await socket.createRequest();
+  expect(request).toMatchObject({ workspaceId: workspace.id });
+  expect(request).not.toHaveProperty("background");
+});
+
+test("a background caller's remote child asks the host to update instead of turning visible", async () => {
+  const { client, socket } = await olderHost();
+
+  await expect(
+    resolverFor(client, true).use("srv_older", (host) => host.createAgent(createArgs, {} as never)),
+  ).rejects.toThrow("Update the host to use background agents.");
+  expect(socket.requests.map((request) => request.type)).not.toContain("create_agent_request");
+});
diff --git a/packages/server/src/server/agent/host-operations/index.ts b/packages/server/src/server/agent/host-operations/index.ts
index 2242c3b872..f6ae774375 100644
--- a/packages/server/src/server/agent/host-operations/index.ts
+++ b/packages/server/src/server/agent/host-operations/index.ts
@@ -16,6 +16,11 @@ import type { ConnectedHosts } from "../../connected-hosts/index.js";
 import { resolveRequiredProviderModel } from "../mcp-shared.js";
 import { selectAgentListItems } from "../agent-projections.js";
 import { summarizeAgentActivity } from "../activity-curator.js";
+import {
+  inheritAgentBackground,
+  inheritWorkspaceBackground,
+  type BackgroundCaller,
+} from "../create-agent/intent.js";
 import { expandUserPath } from "../../path-utils.js";
 import type { PaseoToolExecutionContext, PaseoToolResult } from "../tools/types.js";
 
@@ -177,6 +182,7 @@ const remoteCreate = z
     workspaceId: z.string().min(1),
     labels: z.record(z.string(), z.string()).optional(),
     notifyOnFinish: z.boolean().optional(),
+    background: z.boolean().optional(),
     idempotencyKey: z.string().optional(),
     settings: z
       .object({
@@ -197,6 +203,8 @@ export function createHostResolver(input: {
   local: HostOperations;
   hosts: () => ToolHosts;
   callerAgentId?: string;
+  /** The destination can't see the caller, so its background defaults resolve before routing. */
+  caller: () => BackgroundCaller | null;
   lockedCwd?: string;
 }) {
   return {
@@ -214,9 +222,7 @@ export function createHostResolver(input: {
           async createAgent(args) {
             const parsed = remoteCreate.parse(args);
             const { provider, model } = resolveRequiredProviderModel(parsed.provider);
-            const workspace = (await client.fetchWorkspaces({})).entries.find(
-              (row) => row.id === parsed.workspaceId,
-            );
+            const workspace = await client.findWorkspace(parsed.workspaceId);
             if (!workspace) throw new Error(`Workspace ${parsed.workspaceId} not found`);
             const labels = {
               ...parsed.labels,
@@ -235,6 +241,10 @@ export function createHostResolver(input: {
                 featureValues: parsed.settings?.features,
               },
               workspaceId: parsed.workspaceId,
+              // Older hosts reject any background with a workspaceId, so a visible create omits it.
+              ...(inheritAgentBackground(parsed.background, input.caller())
+                ? { background: true }
+                : {}),
               labels,
               initialPrompt: parsed.initialPrompt,
               idempotencyKey: parsed.idempotencyKey,
@@ -359,7 +369,10 @@ export function createHostResolver(input: {
                       worktreeSlug: args.worktreeSlug as string | undefined,
                     },
               title: args.title as string | undefined,
-              background: args.background as boolean | undefined,
+              background: inheritWorkspaceBackground(
+                args.background as boolean | undefined,
+                input.caller(),
+              ),
             });
             if (response.error || !response.workspace)
               throw new Error(response.error ?? "Workspace creation failed");
@@ -399,14 +412,16 @@ function remoteObservation(client: DaemonClient): HostObservation {
           // A new turn may start between the snapshot and the current-response read.
           // Bound that wait and refresh state instead of attributing the old event to it.
           const current = await client.waitForFinish(agentId, 100);
-          if (current.status === "timeout")
-            snapshot = (await client.fetchAgent(agentId))?.agent ?? null;
-          else {
-            if (!current.final && current.error && current.error !== `Agent not found: ${agentId}`)
-              throw new Error(current.error);
-            snapshot = current.final;
-            lastMessage = current.lastMessage;
+          if (current.status === "timeout") {
+            // Queued delivery can leave a closed/error snapshot visible before the new turn.
+            // A timed-out wait has not established an outcome for that queued work.
+            if (event?.type === "permission_resolved") handler(snapshot, event);
+            return;
           }
+          if (!current.final && current.error && current.error !== `Agent not found: ${agentId}`)
+            throw new Error(current.error);
+          snapshot = current.final;
+          lastMessage = current.lastMessage;
         }
         handler(snapshot, event, lastMessage);
       };
diff --git a/packages/server/src/server/agent/import-sessions.test.ts b/packages/server/src/server/agent/import-sessions.test.ts
index 823784a2f9..7d6fb9d201 100644
--- a/packages/server/src/server/agent/import-sessions.test.ts
+++ b/packages/server/src/server/agent/import-sessions.test.ts
@@ -220,7 +220,7 @@ test("listImportableProviderSessions filters, sorts, limits, and projects import
     listImportableSessions,
   } satisfies Pick<AgentManager, "listAgents" | "listImportableSessions">;
   const agentStorage = {
-    list: async () => [
+    listAll: async () => [
       {
         provider: "codex",
         persistence: {
@@ -230,7 +230,7 @@ test("listImportableProviderSessions filters, sorts, limits, and projects import
         },
       } as StoredAgentRecord,
     ],
-  } satisfies Pick<AgentStorage, "list">;
+  } satisfies Pick<AgentStorage, "listAll">;
 
   const result = await listImportableProviderSessions({
     request: makeRequest({
@@ -302,7 +302,7 @@ test("listImportableProviderSessions looks past already-imported rows to fill th
       listImportableSessions,
     },
     agentStorage: {
-      list: async () => [
+      listAll: async () => [
         {
           provider: "claude",
           persistence: { provider: "claude", sessionId: "already-imported" },
@@ -359,7 +359,7 @@ test("listImportableProviderSessions requests a bounded deep scan for search res
   const result = await listImportableProviderSessions({
     request: makeRequest({ query: "INVOICE", limit: 10 }),
     agentManager: { listAgents: () => [], listImportableSessions },
-    agentStorage: { list: async () => [] },
+    agentStorage: { listAll: async () => [] },
     providerSnapshotManager: { getProviderLabel: (provider) => provider },
   });
 
@@ -396,7 +396,7 @@ test("listImportableProviderSessions includes a provider session after its Paseo
       listImportableSessions: async () => makeImportableSessionsResult([archivedSession]),
     },
     agentStorage: {
-      list: async () => [
+      listAll: async () => [
         {
           provider: "claude",
           archivedAt: "2026-04-30T12:01:00.000Z",
@@ -440,7 +440,7 @@ test("listImportableProviderSessions includes an archived provider session still
       listImportableSessions: async () => makeImportableSessionsResult([archivedSession]),
     },
     agentStorage: {
-      list: async () => [
+      listAll: async () => [
         {
           id: agentId,
           provider: "claude",
@@ -488,8 +488,8 @@ test("listImportableProviderSessions filters out metadata generation sessions",
       listImportableSessions: async () => makeImportableSessionsResult(sessions),
     } satisfies Pick<AgentManager, "listAgents" | "listImportableSessions">,
     agentStorage: {
-      list: async () => [],
-    } satisfies Pick<AgentStorage, "list">,
+      listAll: async () => [],
+    } satisfies Pick<AgentStorage, "listAll">,
     providerSnapshotManager: { getProviderLabel: () => "Codex" },
   });
 
@@ -524,8 +524,8 @@ test("listImportableProviderSessions keeps realpath-equivalent cwd matches", asy
         ]),
     } satisfies Pick<AgentManager, "listAgents" | "listImportableSessions">,
     agentStorage: {
-      list: async () => [],
-    } satisfies Pick<AgentStorage, "list">,
+      listAll: async () => [],
+    } satisfies Pick<AgentStorage, "listAll">,
     providerSnapshotManager: { getProviderLabel: () => "Pi" },
   });
 
@@ -541,8 +541,8 @@ test("listImportableProviderSessions rejects invalid since values", async () =>
         listImportableSessions: async () => makeImportableSessionsResult([]),
       } satisfies Pick<AgentManager, "listAgents" | "listImportableSessions">,
       agentStorage: {
-        list: async () => [],
-      } satisfies Pick<AgentStorage, "list">,
+        listAll: async () => [],
+      } satisfies Pick<AgentStorage, "listAll">,
       providerSnapshotManager: { getProviderLabel: () => "" },
     }),
   ).rejects.toMatchObject(
@@ -660,7 +660,7 @@ class ProviderImportHarness {
       notifyAgentState: () => {},
       getAgent: () => this.activeAgent,
       getRegisteredProviderIds: () => ["codex"],
-      createAgent: async () => {
+      createAgentFromRecord: async () => {
         throw new Error("Stored provider imports must resume their persisted session");
       },
       resumeAgentFromPersistence: async (
diff --git a/packages/server/src/server/agent/import-sessions.ts b/packages/server/src/server/agent/import-sessions.ts
index c7d7527ebf..5b3a5fb85f 100644
--- a/packages/server/src/server/agent/import-sessions.ts
+++ b/packages/server/src/server/agent/import-sessions.ts
@@ -64,7 +64,7 @@ export class ImportSessionsRequestError extends Error {
 export interface ListImportableProviderSessionsInput {
   request: FetchRecentProviderSessionsRequestMessage;
   agentManager: Pick<AgentManager, "listAgents" | "listImportableSessions">;
-  agentStorage: Pick<AgentStorage, "list">;
+  agentStorage: Pick<AgentStorage, "listAll">;
   providerSnapshotManager: Pick<ProviderSnapshotManager, "getProviderLabel">;
 }
 
@@ -342,12 +342,13 @@ function parseRecentProviderSessionsSince(since: string | undefined): number | n
 
 async function collectImportedProviderSessions(
   agentManager: Pick<AgentManager, "listAgents">,
-  agentStorage: Pick<AgentStorage, "list">,
+  agentStorage: Pick<AgentStorage, "listAll">,
   providerFilter: Set<string> | undefined,
 ): Promise<{ handles: Set<string>; count: number }> {
   const handles = new Set<string>();
   const sessions = new Set<string>();
-  const records = await agentStorage.list();
+  // Explicit provider-history import deduplicates against archived as well as active sessions.
+  const records = await agentStorage.listAll();
   const storedRecordsById = new Map(records.map((record) => [record.id, record]));
 
   const collect = (
@@ -380,7 +381,7 @@ function toProviderSessionHandleKey(provider: string, providerHandleId: string):
   return `${provider}\0${providerHandleId}`;
 }
 
-function isMetadataGenerationSession(input: { firstPromptPreview: string | null }): boolean {
+export function isMetadataGenerationSession(input: { firstPromptPreview: string | null }): boolean {
   return (
     input.firstPromptPreview?.trimStart().startsWith(METADATA_GENERATION_PROMPT_PREFIX) ?? false
   );
diff --git a/packages/server/src/server/agent/mcp-parity.e2e.test.ts b/packages/server/src/server/agent/mcp-parity.e2e.test.ts
index 091588b774..7c78faf419 100644
--- a/packages/server/src/server/agent/mcp-parity.e2e.test.ts
+++ b/packages/server/src/server/agent/mcp-parity.e2e.test.ts
@@ -186,8 +186,8 @@ function createRecordingAgentClients(): Record<AgentProvider, AgentClient> {
     if (client.listCommands) {
       wrappedClient.listCommands = async (config) => await client.listCommands!(config);
     }
-    if (client.listFeatures) {
-      wrappedClient.listFeatures = async (config) => await client.listFeatures!(config);
+    if (client.listControls) {
+      wrappedClient.listControls = async (config) => await client.listControls!(config);
     }
     if (client.listImportableSessions) {
       wrappedClient.listImportableSessions = async (options) =>
@@ -404,6 +404,7 @@ describe("Suite A: Core Fixes", () => {
           expect(parseAgentMessage(callerPrompts[0]).source).toEqual({
             kind: "agent-notification",
             agentId: childId,
+            serverId: daemon.daemon.getServerId(),
             title: "Notification child",
             event: "finished",
           });
@@ -517,6 +518,7 @@ describe("Suite A: Core Fixes", () => {
         expect(notification.source).toEqual({
           kind: "agent-notification",
           agentId: childId,
+          serverId: daemon.daemon.getServerId(),
           title: "Watched child",
           event: "errored",
         });
@@ -579,7 +581,11 @@ describe("Suite A: Core Fixes", () => {
             type: "tool_call",
             agentMessage: {
               event: outcome,
-              sender: { id: childId, title: "Follow-up child" },
+              sender: {
+                id: childId,
+                serverId: daemonHandle.daemon.getServerId(),
+                title: "Follow-up child",
+              },
               text: expect.stringContaining(`(Follow-up child) ${outcome}.`),
             },
           }),
@@ -1165,7 +1171,7 @@ describe("Suite E: Workspace Tools", () => {
         .callTool({ name: "archive_workspace", args: { workspaceId } })
         .catch(() => undefined);
     }
-  });
+  }, 30_000);
 
   test("agent-scoped workspace creation inherits visibility and permits an explicit false override", async () => {
     const parentWorkspace = await callToolStructured(topLevelClient, "create_workspace", {
@@ -1191,12 +1197,43 @@ describe("Suite E: Workspace Tools", () => {
       });
       ownedWorkspaces.push(str(inherited.workspaceId));
       expect(inherited.background).toBe(true);
+      expect(inherited.parentWorkspaceId).toBe(parentWorkspaceId);
       const visible = await callToolStructured(scoped, "create_workspace", {
         isolation: "local",
         background: false,
       });
       ownedWorkspaces.push(str(visible.workspaceId));
       expect(visible.background).toBe(false);
+      expect(visible.parentWorkspaceId).toBe(parentWorkspaceId);
+      const worktree = await callToolStructured(scoped, "create_workspace", {
+        isolation: "worktree",
+        branchName: "parentage-child",
+        baseBranch: "main",
+        background: false,
+      });
+      ownedWorkspaces.push(str(worktree.workspaceId));
+      expect(worktree.parentWorkspaceId).toBe(parentWorkspaceId);
+      const client = new DaemonClient({ url: `ws://127.0.0.1:${daemonHandle.port}/ws` });
+      try {
+        await client.connect();
+        const created = await client.createWorkspace({
+          source: { kind: "directory", path: worktreeRepoCwd },
+          callerAgentId: str(parent.agentId),
+          background: false,
+        });
+        const workspaceId = str(created.workspace?.id);
+        ownedWorkspaces.push(workspaceId);
+        expect(created.workspace?.parentWorkspaceId).toBe(parentWorkspaceId);
+        const listed = await client.fetchWorkspaces();
+        expect(listed.entries).toContainEqual(
+          expect.objectContaining({
+            id: workspaceId,
+            parentWorkspaceId: parentWorkspaceId,
+          }),
+        );
+      } finally {
+        await client.close();
+      }
     } finally {
       await scoped?.close();
       for (const workspaceId of ownedWorkspaces.toReversed())
@@ -1204,5 +1241,138 @@ describe("Suite E: Workspace Tools", () => {
           .callTool({ name: "archive_workspace", args: { workspaceId } })
           .catch(() => undefined);
     }
+  }, 30_000);
+
+  test("a background agent's children and workspaces are background unless it overrides", async () => {
+    const visibleAgentId = await createTopLevelAgent();
+    const workspaceId = daemonHandle.daemon.agentManager.getAgent(visibleAgentId)?.workspaceId;
+    const caller = await callToolStructured(topLevelClient, "create_agent", {
+      workspaceId,
+      title: "Background caller",
+      provider: "claude/claude-test-model",
+      initialPrompt: "Say done.",
+      background: true,
+    });
+    const callerId = str(caller.agentId);
+    const background = (agentId: string) =>
+      daemonHandle.daemon.agentManager.getAgent(agentId)?.background;
+    expect(background(callerId)).toBe(true);
+    const scoped = await createMcpClient(
+      `http://127.0.0.1:${daemonHandle.port}/mcp/agents?callerAgentId=${callerId}`,
+    );
+    const ownedWorkspaces: string[] = [];
+    try {
+      const inheritedChild = await callToolStructured(scoped, "create_agent", {
+        relationship: { kind: "subagent" },
+        workspace: { kind: "current" },
+        title: "Inherited child",
+        provider: "claude/claude-test-model",
+        initialPrompt: "Say done.",
+        notifyOnFinish: false,
+      });
+      expect(background(str(inheritedChild.agentId))).toBe(true);
+      const visibleChild = await callToolStructured(scoped, "create_agent", {
+        relationship: { kind: "subagent" },
+        workspace: { kind: "current" },
+        title: "Visible child",
+        provider: "claude/claude-test-model",
+        initialPrompt: "Say done.",
+        notifyOnFinish: false,
+        background: false,
+      });
+      expect(background(str(visibleChild.agentId))).toBe(false);
+      const inheritedWorkspace = await callToolStructured(scoped, "create_workspace", {
+        isolation: "local",
+      });
+      ownedWorkspaces.push(str(inheritedWorkspace.workspaceId));
+      expect(inheritedWorkspace.background).toBe(true);
+    } finally {
+      await scoped.close();
+      await archiveAgentIfPresent(callerId);
+      await archiveAgentIfPresent(visibleAgentId);
+      for (const id of ownedWorkspaces)
+        await topLevelClient
+          .callTool({ name: "archive_workspace", args: { workspaceId: id } })
+          .catch(() => undefined);
+    }
   });
+
+  test("a background subagent stays out of default lists, notifies its parent and archives with it", async () => {
+    const callerPrompts: string[] = [];
+    const daemon = await createTestPaseoDaemon({
+      agentClients: createTestAgentClients({
+        onStartTurn(prompt, config) {
+          if (config.title === "Background parent" && typeof prompt === "string")
+            callerPrompts.push(prompt);
+        },
+      }),
+    });
+    const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+    let mcp: McpClient | undefined;
+    try {
+      await client.connect();
+      const caller = await client.createAgent({
+        provider: "claude",
+        cwd: daemon.paseoHome,
+        title: "Background parent",
+        modeId: "bypassPermissions",
+      });
+      mcp = await createMcpClient(
+        buildExpectedAgentMcpUrl({ host: "127.0.0.1", port: daemon.port, agentId: caller.id }),
+      );
+      const created = await callToolStructured(mcp, "create_agent", {
+        relationship: { kind: "subagent" },
+        workspace: { kind: "current" },
+        provider: "codex/gpt-5.4",
+        title: "Background child",
+        initialPrompt: "say done and stop",
+        notifyOnFinish: true,
+        background: true,
+        settings: { modeId: "full-access" },
+      });
+      const childId = str(created.agentId);
+      expect((await client.fetchAgent(childId))?.agent).toMatchObject({
+        background: true,
+        workspaceId: caller.workspaceId,
+        labels: { [PARENT_AGENT_ID_LABEL]: caller.id },
+      });
+      expect((await client.fetchAgents()).entries.map((entry) => entry.agent.id)).not.toContain(
+        childId,
+      );
+      expect(
+        (await client.fetchAgents({ filter: { includeBackground: true } })).entries.map(
+          (entry) => entry.agent.id,
+        ),
+      ).toContain(childId);
+
+      await waitFor({
+        timeoutMs: 10000,
+        label: "parent finish notification",
+        check: () => (callerPrompts.length > 0 ? true : null),
+      });
+      expect(parseAgentMessage(callerPrompts[0]).source).toMatchObject({
+        kind: "agent-notification",
+        agentId: childId,
+        event: "finished",
+      });
+      expect((await client.fetchAgent(childId))?.agent.requiresAttention).toBe(false);
+
+      await waitFor({
+        timeoutMs: 10000,
+        label: "parent idle",
+        check: () =>
+          daemon.daemon.agentManager.getAgent(caller.id)?.lifecycle === "idle" ? true : null,
+      });
+      await client.archiveAgent(caller.id);
+      await waitFor({
+        timeoutMs: 10000,
+        label: "child archived with parent",
+        check: async () => ((await client.fetchAgent(childId))?.agent.archivedAt ? true : null),
+      });
+    } finally {
+      await mcp?.close();
+      await client.close();
+      await daemon.close();
+    }
+  }, 30_000);
 });
diff --git a/packages/server/src/server/agent/mcp-server.test.ts b/packages/server/src/server/agent/mcp-server.test.ts
index b706157f07..27f730e536 100644
--- a/packages/server/src/server/agent/mcp-server.test.ts
+++ b/packages/server/src/server/agent/mcp-server.test.ts
@@ -257,7 +257,7 @@ function buildAgentManagerSpies() {
     setAgentMode: vi.fn().mockResolvedValue(undefined),
     setAgentModel: vi.fn().mockResolvedValue(undefined),
     setAgentThinkingOption: vi.fn().mockResolvedValue(undefined),
-    setAgentFeature: vi.fn().mockResolvedValue(undefined),
+    setAgentOptions: vi.fn().mockResolvedValue(undefined),
     setLabels: vi.fn().mockResolvedValue(undefined),
     setTitle: vi.fn().mockResolvedValue(undefined),
     updateAgentMetadata: vi.fn().mockResolvedValue(undefined),
@@ -271,6 +271,7 @@ function buildAgentManagerSpies() {
     appendTimelineItem: vi.fn().mockResolvedValue(undefined),
     emitLiveTimelineItem: vi.fn().mockResolvedValue(undefined),
     getPluginTools: () => [],
+    effectiveOptionsFor: (_provider: string, own?: Record<string, unknown>) => own ?? {},
     reloadStalePluginSession: async () => {},
     hasInFlightRun: vi.fn().mockReturnValue(false),
     steerOrReplaceActiveTurn: async () => ({ status: "inactive" as const }),
@@ -282,7 +283,7 @@ function buildAgentManagerSpies() {
     cancelAgentRun: vi.fn(),
     getPendingPermissions: vi.fn(),
     getRegisteredProviderIds: vi.fn().mockReturnValue(["claude"]),
-    listDraftFeatures: vi.fn(),
+    listDraftControls: vi.fn(),
   };
 }
 
@@ -292,7 +293,9 @@ function buildAgentStorageSpies() {
     setTitle: vi.fn().mockResolvedValue(undefined),
     upsert: vi.fn().mockResolvedValue(undefined),
     applySnapshot: vi.fn(),
-    list: vi.fn().mockResolvedValue([]),
+    listActive: vi.fn().mockResolvedValue([]),
+    listByWorkspaces: vi.fn().mockResolvedValue([]),
+    lastUserMessageAtByWorkspace: async () => new Map<string, string>(),
     remove: vi.fn(),
   };
 }
@@ -472,9 +475,9 @@ function configureOpenCodeProviderStub(
     const opts = input as {
       provider: AgentProvider;
       requestedMode: string | undefined;
-      featureValues: Record<string, unknown> | undefined;
+      providerOptions: Record<string, unknown> | undefined;
     };
-    return { modeId: opts.requestedMode, featureValues: opts.featureValues };
+    return { modeId: opts.requestedMode, providerOptions: opts.providerOptions };
   });
 }
 
@@ -562,6 +565,7 @@ function createManagedAgent(overrides: Partial<ManagedAgent> = {}): ManagedAgent
     pendingPermissions: new Map(),
     persistence: null,
     labels: {},
+    metadata: {},
     attention: { requiresAttention: false },
     ...overrides,
   } as ManagedAgent;
@@ -639,7 +643,16 @@ class BoundaryAgentManagerFake {
 }
 
 class BoundaryAgentStorageFake {
-  public async list(): Promise<StoredAgentRecord[]> {
+  public async listActive(): Promise<StoredAgentRecord[]> {
+    return [];
+  }
+  async listByWorkspaces() {
+    return [];
+  }
+  async lastUserMessageAtByWorkspace() {
+    return new Map<string, string>();
+  }
+  async listAll() {
     return [];
   }
 }
@@ -772,7 +785,8 @@ function createPaseoWorktreeForMcpTest(options: {
     initialize: async () => {},
     existsOnDisk: async () => true,
     get: async (workspaceId: string) => workspaces.get(workspaceId) ?? null,
-    list: async () => Array.from(workspaces.values()),
+    listAll: async () => Array.from(workspaces.values()),
+    listActive: async () => Array.from(workspaces.values()).filter((w) => !w.archivedAt),
     update: async (workspaceId, updater) => {
       const workspace = workspaces.get(workspaceId);
       if (!workspace) return null;
@@ -894,7 +908,11 @@ async function createAgentMcpServer(
   const server = await createAgentMcpServerWithDependencies({
     agentMessages: () => messages,
     finishSubscriptions: () => subscriptions,
-    workspaceRegistry: { get: async () => null, list: async () => [], upsert: async () => {} },
+    workspaceRegistry: {
+      get: async () => null,
+      listActive: async () => [],
+      upsert: async () => {},
+    },
     ...options,
   });
   serverSubscriptionRecords.set(server, records);
@@ -1647,11 +1665,11 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({ cwd: existingCwd }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
-  it("rejects public internal helpers and the old top-level execution background option", async () => {
+  it("rejects public internal helpers", async () => {
     const workdir = await mkdtemp(join(tmpdir(), "mcp-public-helper-removal-"));
     const storage = new AgentStorage(join(workdir, "agents"), logger);
     const agentManager = new AgentManager({
@@ -1669,9 +1687,6 @@ describe("create_agent MCP tool", () => {
       const tool = registeredTool(server, "create_agent");
       const input = { title: "Helper", provider: "codex/gpt-5.4", initialPrompt: "Summarize" };
       await expect(tool.handler({ ...input, internal: true })).rejects.toThrow(/Unrecognized key/);
-      await expect(tool.handler({ ...input, background: true })).rejects.toThrow(
-        /Unrecognized key/,
-      );
     } finally {
       await removeAgentStateDir(agentManager, storage, workdir);
     }
@@ -1793,7 +1808,7 @@ describe("create_agent MCP tool", () => {
         cwd: existingCwd,
       }),
       undefined,
-      { workspaceId: "wks_existing" },
+      { workspaceId: "wks_existing", background: false },
     );
   });
 
@@ -1805,7 +1820,7 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: null,
       availableModes: [],
-      config: { title: "Feature test", featureValues: { fast_mode: true } },
+      config: { title: "Feature test", providerOptions: { fast_mode: true } },
     } as ManagedAgent);
 
     const server = await createAgentMcpServer({
@@ -1834,10 +1849,10 @@ describe("create_agent MCP tool", () => {
       expect.objectContaining({
         provider: "codex",
         model: "gpt-5.4",
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2033,7 +2048,7 @@ describe("create_agent MCP tool", () => {
         title: "Fix auth bug",
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2068,7 +2083,7 @@ describe("create_agent MCP tool", () => {
         title: "Fix auth",
       }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -2112,6 +2127,7 @@ describe("create_agent MCP tool", () => {
       {
         labels: { source: "mcp" },
         workspaceId: "workspace-created",
+        background: false,
       },
     );
   });
@@ -2214,7 +2230,7 @@ describe("create_agent MCP tool", () => {
           title: "Directory agent",
         }),
         undefined,
-        { workspaceId: "workspace-directory-auto-title" },
+        { workspaceId: "workspace-directory-auto-title", background: false },
       );
       expect(workspaceRecords.get("workspace-directory-auto-title")).toMatchObject({
         title: "Directory Workspace Title",
@@ -2699,7 +2715,7 @@ describe("create_agent MCP tool", () => {
       providerSnapshotManager: createOpenCodeManager().manager,
       workspaceRegistry: {
         get: vi.fn(async () => workspace),
-        list: vi.fn(async () => [workspace]),
+        listActive: vi.fn(async () => [workspace]),
         upsert: vi.fn(async () => undefined),
       },
       logger,
@@ -2732,7 +2748,7 @@ describe("create_agent MCP tool", () => {
       providerSnapshotManager: createOpenCodeManager().manager,
       workspaceRegistry: {
         get: vi.fn(async () => backgroundWorkspace),
-        list: vi.fn(async () => [backgroundWorkspace]),
+        listActive: vi.fn(async () => [backgroundWorkspace]),
         upsert: vi.fn(async () => undefined),
       },
       createDirectoryWorkspace: async (cwd, _title, _projectId, context) => {
@@ -2828,12 +2844,13 @@ describe("create_agent MCP tool", () => {
           source: "voice",
         },
         workspaceId: "wks_voice",
+        background: false,
       },
     );
     await rm(baseDir, { recursive: true, force: true });
   });
 
-  it("rejects background from caller agents and defaults notify-on-finish on", async () => {
+  it("defaults notify-on-finish on for caller agents", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
     spies.agentManager.getAgent.mockReturnValue({
       id: "parent-agent",
@@ -2853,16 +2870,6 @@ describe("create_agent MCP tool", () => {
     });
 
     const tool = registeredTool(server, "create_agent");
-    await expect(
-      tool.handler({
-        ...subagentCurrentWorkspace(),
-        title: "Child",
-        provider: "codex/gpt-5.4",
-        initialPrompt: "Do work",
-        background: false,
-      }),
-    ).rejects.toThrow(/Unrecognized key/);
-
     const parsed = await tool.inputSchema.safeParseAsync({
       ...subagentCurrentWorkspace(),
       title: "Child",
@@ -3019,6 +3026,7 @@ describe("create_agent MCP tool", () => {
           source: "handoff",
         },
         workspaceId: "wks_parent",
+        background: false,
       },
     );
   });
@@ -3039,12 +3047,12 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: null,
       availableModes: [],
-      config: { title: "Child", featureValues: { fast_mode: true } },
+      config: { title: "Child", providerOptions: { fast_mode: true } },
     } as ManagedAgent);
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockImplementation(async (input) => {
-      const opts = input as { featureValues: Record<string, unknown> | undefined };
-      return { modeId: undefined, featureValues: opts.featureValues };
+      const opts = input as { providerOptions: Record<string, unknown> | undefined };
+      return { modeId: undefined, providerOptions: opts.providerOptions };
     });
 
     const server = await createAgentMcpServer({
@@ -3072,7 +3080,7 @@ describe("create_agent MCP tool", () => {
       expect.objectContaining({
         provider: "codex",
         model: "gpt-5.4",
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
       }),
       undefined,
       {
@@ -3080,6 +3088,7 @@ describe("create_agent MCP tool", () => {
           [PARENT_AGENT_ID_LABEL]: "parent-agent",
         },
         workspaceId: "wks_parent",
+        background: false,
       },
     );
   });
@@ -3218,6 +3227,7 @@ describe("create_agent MCP tool", () => {
     expect(agentIdArg).toBeUndefined();
     expect(optionsArg).toEqual({
       workspaceId: "workspace-created",
+      background: false,
     });
   });
 
@@ -3273,7 +3283,7 @@ describe("create_agent MCP tool", () => {
     provStub.resolveCreateConfig.mockImplementation(async (input) => {
       const opts = input as { requestedMode: string | undefined };
       expect(opts.requestedMode).toBe("dynamic");
-      return { modeId: "dynamic", featureValues: undefined };
+      return { modeId: "dynamic", providerOptions: undefined };
     });
     const server = await createAgentMcpServer({
       agentManager,
@@ -3295,7 +3305,7 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({ modeId: "dynamic" }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -3307,12 +3317,12 @@ describe("create_agent MCP tool", () => {
       lifecycle: "idle",
       currentModeId: "build",
       availableModes: [],
-      config: { title: "Child", featureValues: { auto_accept: true } },
+      config: { title: "Child", providerOptions: { auto_accept: true } },
     } as ManagedAgent);
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockResolvedValue({
       modeId: "build",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const server = await createAgentMcpServer({
       agentManager,
@@ -3332,9 +3342,9 @@ describe("create_agent MCP tool", () => {
     });
 
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
-      expect.objectContaining({ modeId: "build", featureValues: { auto_accept: true } }),
+      expect.objectContaining({ modeId: "build", providerOptions: { auto_accept: true } }),
       undefined,
-      { workspaceId: "workspace-created" },
+      { workspaceId: "workspace-created", background: false },
     );
   });
 
@@ -3360,7 +3370,7 @@ describe("create_agent MCP tool", () => {
     const providerSnapshot = createOpenCodeManager();
     providerSnapshot.stub.resolveCreateConfig.mockResolvedValue({
       modeId: "resolver-mode",
-      featureValues: { resolver_feature: true },
+      providerOptions: { resolver_feature: true },
     });
 
     const server = await createAgentMcpServer({
@@ -3384,7 +3394,7 @@ describe("create_agent MCP tool", () => {
     expect(spies.agentManager.createAgent).toHaveBeenCalledWith(
       expect.objectContaining({
         modeId: "resolver-mode",
-        featureValues: { resolver_feature: true },
+        providerOptions: { resolver_feature: true },
       }),
       undefined,
       expect.any(Object),
@@ -4717,7 +4727,7 @@ describe("update_agent MCP tool", () => {
     expect(spies.agentManager.setAgentMode).toHaveBeenCalledWith("agent-1", "full-access");
     expect(spies.agentManager.setAgentModel).toHaveBeenCalledWith("agent-1", "gpt-5.4");
     expect(spies.agentManager.setAgentThinkingOption).toHaveBeenCalledWith("agent-1", "high");
-    expect(spies.agentManager.setAgentFeature).toHaveBeenCalledWith("agent-1", "fast_mode", true);
+    expect(spies.agentManager.setAgentOptions).toHaveBeenCalledWith("agent-1", { fast_mode: true });
     expect(spies.agentManager.updateAgentMetadata).toHaveBeenCalledWith("agent-1", {
       title: "Updated agent",
       labels: { role: "worker" },
@@ -4742,12 +4752,12 @@ describe("update_agent MCP tool", () => {
     expect(spies.agentManager.setAgentMode).not.toHaveBeenCalled();
     expect(spies.agentManager.setAgentModel).not.toHaveBeenCalled();
     expect(spies.agentManager.setAgentThinkingOption).not.toHaveBeenCalled();
-    expect(spies.agentManager.setAgentFeature).not.toHaveBeenCalled();
+    expect(spies.agentManager.setAgentOptions).not.toHaveBeenCalled();
   });
 
   it("does not update metadata when runtime settings fail", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
-    spies.agentManager.setAgentFeature.mockRejectedValue(new Error("unsupported feature"));
+    spies.agentManager.setAgentOptions.mockRejectedValue(new Error("unsupported feature"));
     const server = await createAgentMcpServer({
       agentManager,
       agentStorage,
@@ -5065,7 +5075,7 @@ describe("create_schedule MCP tool", () => {
       config: {
         title: "Parent agent",
         model: "openai/gpt-5.5",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       },
     } as ManagedAgent);
     const createOrReplace = vi.fn(async (input: CreateScheduleInput) =>
@@ -5093,7 +5103,7 @@ describe("create_schedule MCP tool", () => {
         cwd: REPO_CWD,
         modeId: "build",
         model: "openai/gpt-5.5",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       },
     });
   });
@@ -5867,7 +5877,7 @@ describe("agent profile listing MCP tool", () => {
         model: "claude-test-model",
         modeId: "bypassPermissions",
         thinkingOptionId: "high",
-        featureValues: { fast_mode: true },
+        options: { fast_mode: true },
         notes: "Use for UI work: components, layout, design tokens. Not for backend.",
       },
     ];
@@ -5882,7 +5892,21 @@ describe("agent profile listing MCP tool", () => {
 
     const response = await tool.handler({});
 
-    expect(response.structuredContent).toEqual({ profiles });
+    // The config store holds profiles with `options` only; the tool reports them as stored.
+    expect(response.structuredContent).toEqual({
+      profiles: [
+        {
+          id: "ui-profile",
+          name: "UI work",
+          provider: "claude",
+          model: "claude-test-model",
+          modeId: "bypassPermissions",
+          thinkingOptionId: "high",
+          options: { fast_mode: true },
+          notes: "Use for UI work: components, layout, design tokens. Not for backend.",
+        },
+      ],
+    });
   });
 
   it("returns an empty array when no profiles are configured", async () => {
@@ -5934,14 +5958,10 @@ describe("provider MCP tools", () => {
 
   it("inspects provider features for a draft agent configuration", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
-    spies.agentManager.listDraftFeatures.mockResolvedValue([
-      {
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast mode",
-        value: false,
-      },
-    ]);
+    spies.agentManager.listDraftControls.mockResolvedValue({
+      controls: [{ type: "toggle", key: "fast_mode", label: "Fast mode" }],
+      options: { fast_mode: true },
+    });
     const provStub = createProviderSnapshotManagerStub();
     provStub.listRegisteredProviderIds.mockReturnValue(["codex"]);
     const codexEntry = buildSnapshotEntry({
@@ -5974,13 +5994,13 @@ describe("provider MCP tools", () => {
 
     const response = await tool.handler(input);
 
-    expect(spies.agentManager.listDraftFeatures).toHaveBeenCalledWith({
+    expect(spies.agentManager.listDraftControls).toHaveBeenCalledWith({
       provider: "codex",
       cwd: expect.stringContaining("repo"),
       modeId: "full-access",
       model: "gpt-5.4",
       thinkingOptionId: "high",
-      featureValues: { fast_mode: true },
+      providerOptions: { fast_mode: true },
     });
     expect(response.structuredContent).toEqual({
       provider: "codex",
@@ -5995,7 +6015,7 @@ describe("provider MCP tools", () => {
           type: "toggle",
           id: "fast_mode",
           label: "Fast mode",
-          value: false,
+          value: true,
         },
       ],
     });
@@ -6211,14 +6231,8 @@ describe("agent snapshot MCP serialization", () => {
             description: "Default coding mode",
           },
         ],
-        features: [
-          {
-            type: "toggle",
-            id: "web-search",
-            label: "Web search",
-            value: true,
-          },
-        ],
+        controls: [{ type: "toggle", key: "web-search", label: "Web search" }],
+        effectiveOptions: { "web-search": true },
         pendingPermissions: new Map(),
         persistence: {
           provider: "codex",
@@ -6334,7 +6348,7 @@ describe("agent snapshot MCP serialization", () => {
       createManagedAgent({ id: "in-child-cwd", cwd: "/tmp/workspace/packages/server" }),
       createManagedAgent({ id: "other-cwd", cwd: "/tmp/other" }),
     ]);
-    spies.agentStorage.list.mockResolvedValue([
+    spies.agentStorage.listActive.mockResolvedValue([
       createStoredRecord({
         id: "stored-in-cwd",
         cwd: "/tmp/workspace",
@@ -6393,7 +6407,7 @@ describe("agent snapshot MCP serialization", () => {
         updatedAt: new Date(old),
       }),
     ]);
-    spies.agentStorage.list.mockResolvedValue([
+    spies.agentStorage.listActive.mockResolvedValue([
       createStoredRecord({ id: "recent-archived", cwd: TARGET_CWD, archivedAt: recent }),
       createStoredRecord({ id: "old-archived", cwd: TARGET_CWD, archivedAt: old }),
       createStoredRecord({
@@ -6434,7 +6448,7 @@ describe("agent snapshot MCP serialization", () => {
         archivedAt: new Date(now - index * 60 * 1000).toISOString(),
       }),
     );
-    spies.agentStorage.list.mockResolvedValue([
+    spies.agentStorage.listActive.mockResolvedValue([
       ...recentArchivedRecords,
       createStoredRecord({
         id: "old-archived",
@@ -6465,7 +6479,7 @@ describe("agent snapshot MCP serialization", () => {
   it("returns compact list items for stored archived agents", async () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
     const now = new Date().toISOString();
-    spies.agentStorage.list.mockResolvedValue([
+    spies.agentStorage.listActive.mockResolvedValue([
       createStoredRecord({
         id: "stored-archived-compact",
         cwd: REPO_CWD,
@@ -6584,7 +6598,7 @@ describe("agent snapshot MCP serialization", () => {
     const { agentManager, agentStorage, spies } = createTestDeps();
     const now = new Date().toISOString();
     spies.agentManager.listAgents.mockReturnValue([createManagedAgent()]);
-    spies.agentStorage.list.mockResolvedValue([
+    spies.agentStorage.listActive.mockResolvedValue([
       createStoredRecord({
         id: "stored-non-archived",
         updatedAt: now,
diff --git a/packages/server/src/server/agent/option-controls.test.ts b/packages/server/src/server/agent/option-controls.test.ts
new file mode 100644
index 0000000000..50babb0e0a
--- /dev/null
+++ b/packages/server/src/server/agent/option-controls.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { convertLegacyOptions, foldHookFeatureValues } from "./option-controls.js";
+
+describe("convertLegacyOptions rejects a malformed Codex fast_mode", () => {
+  test.each(["false", 1, {}])("%j", (value) => {
+    expect(() =>
+      convertLegacyOptions({ provider: "codex", options: { fast_mode: value } }),
+    ).toThrow(/fast_mode must be true, false or null/);
+  });
+});
+
+describe("convertLegacyOptions", () => {
+  test.each([
+    { legacy: true, tier: "fast" },
+    { legacy: false, tier: "default" },
+    { legacy: null, tier: null },
+  ])("Codex fast_mode: $legacy becomes service_tier: $tier", ({ legacy, tier }) => {
+    expect(
+      convertLegacyOptions({ provider: "codex", options: { fast_mode: legacy, plan_mode: true } }),
+    ).toEqual({ plan_mode: true, service_tier: tier });
+  });
+
+  test("a service_tier in the same input wins", () => {
+    expect(
+      convertLegacyOptions({
+        provider: "codex",
+        options: { service_tier: "default", fast_mode: true },
+      }),
+    ).toEqual({ service_tier: "default" });
+  });
+
+  test("other providers keep fast_mode", () => {
+    const options = { fast_mode: true };
+    expect(convertLegacyOptions({ provider: "claude", options })).toBe(options);
+  });
+});
+
+describe("foldHookFeatureValues", () => {
+  const convert = (options: Record<string, unknown>) =>
+    convertLegacyOptions({ provider: "codex", options });
+
+  test("a hook that edits featureValues.fast_mode sets service_tier", () => {
+    const sent = { providerOptions: {}, featureValues: {} };
+    const returned = { providerOptions: {}, featureValues: { fast_mode: true } };
+
+    expect(foldHookFeatureValues({ returned, sent, convert }).providerOptions).toEqual({
+      service_tier: "fast",
+    });
+  });
+
+  test("a hook that replaces the speed it was sent with fast_mode selects Fast", () => {
+    const sent = {
+      providerOptions: { service_tier: "default" },
+      featureValues: { service_tier: "default" },
+    };
+    const returned = { ...sent, featureValues: { fast_mode: true } };
+
+    expect(foldHookFeatureValues({ returned, sent, convert }).providerOptions).toEqual({
+      service_tier: "fast",
+    });
+  });
+});
diff --git a/packages/server/src/server/agent/option-controls.ts b/packages/server/src/server/agent/option-controls.ts
new file mode 100644
index 0000000000..f1c4183b26
--- /dev/null
+++ b/packages/server/src/server/agent/option-controls.ts
@@ -0,0 +1,208 @@
+import { isDeepStrictEqual } from "node:util";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+
+/**
+ * A patch over an agent's own options: top-level keys replace, `null` removes the key so the
+ * `config.json` default (or the provider's own default) applies again.
+ */
+export type ProviderOptionsPatch = Record<string, unknown>;
+
+export function applyProviderOptionsPatch(input: {
+  options: ProviderOptions | undefined;
+  patch: ProviderOptionsPatch;
+}): ProviderOptions {
+  const { options, patch } = input;
+  const next: ProviderOptions = { ...options };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete next[key];
+    } else if (value !== undefined) {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+/** COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. */
+export interface LegacyFeatureValues {
+  featureValues?: Record<string, unknown>;
+}
+
+/**
+ * COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast
+ * preferences have migrated. Codex used to take `fast_mode`; it takes `service_tier` now. Old
+ * data (stored records, config.json defaults, profiles, older clients, hooks) is converted here
+ * as it enters, so nothing past this point sees `fast_mode` for Codex. A `service_tier` in the
+ * same input wins. A patch's `null` stays `null`, which removes the speed.
+ */
+interface LegacyOptionsInput<O> {
+  provider: string | undefined;
+  options: O;
+}
+
+/** A legacy option value the conversion cannot read. */
+export class MalformedLegacyOptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MalformedLegacyOptionError";
+  }
+}
+
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown>>,
+): Record<string, unknown>;
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown> | undefined>,
+): Record<string, unknown> | undefined;
+export function convertLegacyOptions(
+  input: LegacyOptionsInput<Record<string, unknown> | undefined>,
+): Record<string, unknown> | undefined {
+  const { provider, options } = input;
+  if (provider !== "codex" || !options || !("fast_mode" in options)) return options;
+  const { fast_mode: legacy, ...rest } = options;
+  if (legacy !== undefined && legacy !== null && typeof legacy !== "boolean") {
+    throw new MalformedLegacyOptionError("Codex fast_mode must be true, false or null");
+  }
+  if ("service_tier" in rest || legacy === undefined) return rest;
+  if (legacy === null) return { ...rest, service_tier: null };
+  return { ...rest, service_tier: legacy ? "fast" : "default" };
+}
+
+/**
+ * The built-in adapter a provider id runs on: a custom provider is named by the one it
+ * `extends`, followed until a provider that extends nothing. `extendsOf` is where the caller
+ * reads that link (the registry's definitions, or `config.json`'s `providers` section).
+ */
+export function resolveAdapter(input: {
+  provider: string;
+  extendsOf: (provider: string) => string | null | undefined;
+}): string {
+  const seen = new Set<string>();
+  let current = input.provider;
+  for (;;) {
+    seen.add(current);
+    const base = input.extendsOf(current);
+    if (!base || seen.has(base)) return current;
+    current = base;
+  }
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * Older clients, stored records, profiles, and plugin hooks carry composer values in
+ * `featureValues`. This is the one place they become `providerOptions`; an explicit
+ * `providerOptions` key wins over a `featureValues` key of the same name.
+ */
+export function foldFeatureValues<
+  T extends {
+    providerOptions?: ProviderOptions | null;
+    featureValues?: Record<string, unknown> | null;
+  },
+>(config: T): Omit<T, "featureValues"> {
+  const { featureValues, ...rest } = config;
+  if (!featureValues || Object.keys(featureValues).length === 0) return rest;
+  return { ...rest, providerOptions: { ...featureValues, ...rest.providerOptions } };
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * A plugin written against the previous SDK reads and edits `config.featureValues`, so a
+ * hook sees a copy of the config's options there. What the hook did to that copy (set,
+ * replaced or deleted a key, or dropped the field) is applied as a patch over the options it
+ * returned; keys it left alone change nothing.
+ */
+export function exposeFeatureValuesToHook<
+  T extends { providerOptions?: ProviderOptions | null; featureValues?: Record<string, unknown> },
+>(config: T): T {
+  if (!config.providerOptions || Object.keys(config.providerOptions).length === 0) return config;
+  return { ...config, featureValues: { ...config.providerOptions } };
+}
+
+export function foldHookFeatureValues<
+  T extends {
+    providerOptions?: ProviderOptions | null;
+    featureValues?: Record<string, unknown>;
+  },
+>(input: {
+  returned: T;
+  sent: T;
+  /** Brings what the hook returned to the form of the copy it was sent. */
+  convert: (options: Record<string, unknown>) => Record<string, unknown>;
+}): Omit<T, "featureValues"> {
+  const { returned, sent, convert } = input;
+  const { featureValues, ...rest } = returned;
+  const before = sent.featureValues;
+  if (!before) {
+    // No copy was sent, so everything the hook put in `featureValues` is new.
+    return foldFeatureValues(returned);
+  }
+  // A hook may return an older key where it was sent the current one; comparing in the same
+  // form keeps a replaced value from reading as a deletion.
+  const after = convert(featureValues ?? {});
+  const patch: ProviderOptionsPatch = {};
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (isDeepStrictEqual(after[key], before[key])) continue;
+    patch[key] = key in after ? after[key] : null;
+  }
+  return {
+    ...rest,
+    providerOptions: applyProviderOptionsPatch({
+      options: rest.providerOptions ?? undefined,
+      patch,
+    }),
+  };
+}
+
+type ConvertedOptions = Record<string, unknown> | undefined;
+
+interface ProfileOptionFields {
+  provider?: string;
+  options?: Record<string, unknown>;
+  featureValues?: Record<string, unknown>;
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * Profiles saved before options carry `featureValues`; when one comes from storage, `options`
+ * wins over a stale `featureValues` key.
+ *
+ * A write that carries `options`, empty included, is from a client that knows them: its
+ * `featureValues` fold over those. A write without `options` is from the unchanged app, whose
+ * form only knows the controls: its `featureValues` are a patch (`null` deletes) over the
+ * options stored for that profile, so options the form never shows, such as `sandbox_mode`,
+ * survive an edit. A profile moved to another provider starts from no options, because the old
+ * provider's keys mean nothing to the new one. A profile with no options is stored without the
+ * key.
+ */
+export function foldProfileFeatureValues<T extends ProfileOptionFields>(input: {
+  profile: T;
+  stored: ProfileOptionFields | undefined;
+  source: "stored" | "client write";
+  /** Renames old option keys for the adapter the profile's provider runs on. */
+  convert: (provider: string, options: Record<string, unknown> | undefined) => ConvertedOptions;
+}): Omit<T, "featureValues"> {
+  const { profile, stored, source, convert } = input;
+  const { featureValues: legacyValues, ...rest } = profile;
+  // A profile is stored in the current keys, so removal and merging below see one vocabulary.
+  const provider = rest.provider ?? "";
+  const featureValues = convert(provider, legacyValues);
+  const ownOptions = convert(provider, rest.options);
+  if (source === "stored") {
+    if (featureValues) return { ...rest, options: { ...featureValues, ...ownOptions } };
+    return ownOptions ? { ...rest, options: ownOptions } : rest;
+  }
+  const storedOptions =
+    stored?.provider === rest.provider ? convert(provider, stored?.options) : undefined;
+  const base = rest.options !== undefined ? ownOptions : storedOptions;
+  const options = applyProviderOptionsPatch({ options: base, patch: featureValues ?? {} });
+  return Object.keys(options).length > 0 ? { ...rest, options } : { ...rest, options: undefined };
+}
+
+/**
+ * COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+ * The unchanged app reads a profile's options from `featureValues`; the config API answers with
+ * both fields.
+ */
+export function withLegacyProfileFeatureValues<T extends ProfileOptionFields>(profile: T): T {
+  return profile.options ? { ...profile, featureValues: { ...profile.options } } : profile;
+}
diff --git a/packages/server/src/server/agent/plugin-provider-options.ts b/packages/server/src/server/agent/plugin-provider-options.ts
new file mode 100644
index 0000000000..686baec1ac
--- /dev/null
+++ b/packages/server/src/server/agent/plugin-provider-options.ts
@@ -0,0 +1,60 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { ProviderConfigState } from "@getpaseo/plugin/server/provider";
+import type { AgentOptionControl } from "./agent-sdk-types.js";
+
+/** How a provider session's composer options look to the daemon, whichever shape it reports. */
+export interface PluginOptionState {
+  controls: AgentOptionControl[];
+  /** The values the session runs with, for the keys it reports. */
+  options: Record<string, JsonValue>;
+  /** The provider reports `settings`, so it also reads `changes.settings`. */
+  legacySettings: boolean;
+}
+
+/**
+ * A provider that reports `controls` and `providerOptions` is read as is.
+ * COMPAT(plugin-provider-settings): added in v0.15.0, remove after 2027-05-01. A provider still
+ * reporting `settings` has each setting id read as an option key and its value as the option.
+ */
+export function readPluginOptionState(config: ProviderConfigState): PluginOptionState {
+  if (config.controls || config.providerOptions) {
+    return {
+      controls: (config.controls ?? []).map(toControl),
+      options: { ...config.providerOptions },
+      legacySettings: false,
+    };
+  }
+  const settings = config.settings ?? [];
+  return {
+    controls: settings.map(
+      (setting): AgentOptionControl =>
+        setting.type === "toggle"
+          ? {
+              type: "toggle",
+              key: setting.id,
+              label: setting.label,
+              ...(setting.description ? { description: setting.description } : {}),
+            }
+          : {
+              type: "select",
+              key: setting.id,
+              label: setting.label,
+              ...(setting.description ? { description: setting.description } : {}),
+              choices: setting.options.map((option) => ({
+                value: option.value,
+                label: option.label,
+              })),
+            },
+    ),
+    options: Object.fromEntries(settings.map((setting) => [setting.id, setting.value])),
+    legacySettings: true,
+  };
+}
+
+function toControl(
+  control: NonNullable<ProviderConfigState["controls"]>[number],
+): AgentOptionControl {
+  return control.type === "toggle"
+    ? { ...control }
+    : { ...control, choices: control.choices.map((choice) => ({ ...choice })) };
+}
diff --git a/packages/server/src/server/agent/plugin-provider.test.ts b/packages/server/src/server/agent/plugin-provider.test.ts
index 9bb0a7f8a1..4535ba0888 100644
--- a/packages/server/src/server/agent/plugin-provider.test.ts
+++ b/packages/server/src/server/agent/plugin-provider.test.ts
@@ -16,6 +16,7 @@ import type {
 import { setImmediate as nextTurn } from "node:timers/promises";
 import { describe, expect, test } from "vitest";
 import { createTestLogger } from "../../test-utils/test-logger.js";
+import { RewindOutcomeUnknownError } from "./rewind/rewind.js";
 import {
   RewindNotAppliedError,
   type AgentClient,
@@ -61,10 +62,19 @@ const CAPABILITIES = [
 interface ProviderHarnessOptions {
   capabilities?: ProviderConnection["capabilities"];
   completeTurn?: boolean;
+  closeAcknowledgementOnly?: boolean;
   openChildren?: (rootSessionId: string, emit: (event: ProviderEvent) => void) => void;
   handleInput?: (input: ProviderInput, emit: (event: ProviderEvent) => void) => Promise<boolean>;
 }
 
+function controlKey(control: { key: string }): string {
+  return control.key;
+}
+
+function lastConfigure(inputs: ProviderInput[]): ProviderInput | undefined {
+  return inputs.findLast((input) => input.type === "session.configure");
+}
+
 function createProviderHarness(options: ProviderHarnessOptions = {}) {
   let listener: ((event: ProviderEvent) => void) | null = null;
   let closeCount = 0;
@@ -216,6 +226,7 @@ function createProviderHarness(options: ProviderHarnessOptions = {}) {
       }
       if (input.type === "session.close") {
         emit({ type: "session.closed", sessionId: input.sessionId });
+        if (options.closeAcknowledgementOnly) return;
       }
       if ("requestId" in input) {
         emit({ type: "request.completed", requestId: input.requestId });
@@ -254,6 +265,721 @@ function eventsOfType(events: AgentStreamEvent[], type: AgentStreamEvent["type"]
   return events.filter((event) => event.type === type);
 }
 
+function createRewindProviderHarness(
+  options: {
+    reuseAnswerId?: boolean;
+    forkOnRevert?: boolean;
+    handleInput?: ProviderHarnessOptions["handleInput"];
+  } = {},
+) {
+  const nativeMessages: string[] = [];
+  let originalMessages: string[] | null = null;
+  const harness = createProviderHarness({
+    closeAcknowledgementOnly: true,
+    capabilities: [
+      ...CAPABILITIES,
+      "session.revert.conversation",
+      "session.revert.files",
+      "session.revert.both",
+    ],
+    async handleInput(input, emit) {
+      if (await options.handleInput?.(input, emit)) return true;
+      if (input.type === "session.open" && input.history === "replay") {
+        emit({
+          type: "session.opened",
+          requestId: input.requestId,
+          sessionId: input.sessionId,
+          capabilities: [
+            ...CAPABILITIES,
+            "session.revert.conversation",
+            "session.revert.files",
+            "session.revert.both",
+          ],
+          restoration: "core",
+          persistence: input.persistence ?? { version: 1, data: { token: "root" } },
+          cwd: input.config.cwd,
+        });
+        const messages =
+          options.forkOnRevert &&
+          (input.persistence?.data as { token?: string })?.token === "root" &&
+          originalMessages
+            ? originalMessages
+            : nativeMessages;
+        for (const [index, text] of messages.entries()) {
+          emit({
+            type: "timeline.item",
+            sessionId: input.sessionId,
+            item: { type: "user_message", id: `user-${text}`, text, revertToken: text },
+          });
+          emit({
+            type: "timeline.item",
+            sessionId: input.sessionId,
+            item: {
+              type: "assistant_message",
+              id: options.reuseAnswerId ? `answer-${index + 1}` : `answer-${text}`,
+              text: `Reply ${text}`,
+            },
+          });
+        }
+        emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+        return true;
+      }
+      if (input.type === "session.prompt") {
+        if (input.prompt.input.type !== "message") throw new Error("Expected a message");
+        const text = input.prompt.input.content
+          .flatMap((part) => (part.type === "text" ? [part.text] : []))
+          .join("");
+        nativeMessages.push(text);
+        const turnId = `turn-${text}`;
+        emit({
+          type: "session.prompt_result",
+          sessionId: input.sessionId,
+          clientMessageId: input.prompt.clientMessageId,
+          result: { type: "turn", turnId },
+        });
+        emit({ type: "session.turn", sessionId: input.sessionId, turnId, state: "started" });
+        emit({
+          type: "timeline.item",
+          sessionId: input.sessionId,
+          item: {
+            type: "user_message",
+            id: `user-${text}`,
+            text,
+            clientMessageId: input.prompt.clientMessageId,
+            revertToken: text,
+          },
+        });
+        emit({
+          type: "timeline.item",
+          sessionId: input.sessionId,
+          item: {
+            type: "assistant_message",
+            id: options.reuseAnswerId ? `answer-${nativeMessages.length}` : `answer-${text}`,
+            text: `Reply ${text}`,
+          },
+        });
+        emit({ type: "session.turn", sessionId: input.sessionId, turnId, state: "completed" });
+        return true;
+      }
+      if (input.type === "session.revert") {
+        if (options.forkOnRevert && input.scope !== "files") {
+          originalMessages = [...nativeMessages];
+          emit({
+            type: "session.persistence",
+            sessionId: input.sessionId,
+            persistence: { version: 1, data: { token: "fork" } },
+          });
+        }
+        if (input.scope !== "files")
+          nativeMessages.splice(nativeMessages.indexOf(String(input.token)));
+        emit({ type: "request.completed", requestId: input.requestId });
+        return true;
+      }
+      return false;
+    },
+  });
+  return { ...harness, nativeMessages };
+}
+
+async function withRewindAgent(
+  run: (context: {
+    manager: AgentManager;
+    agentId: string;
+    nativeMessages: string[];
+    messages: () => Promise<string[]>;
+  }) => Promise<void>,
+  options: Parameters<typeof createRewindProviderHarness>[0] = {},
+) {
+  const harness = createRewindProviderHarness(options);
+  const logger = createTestLogger();
+  const registry = new PluginAgentClientRegistry(logger);
+  registry.replace([harness.registration]);
+  const manager = new AgentManager({
+    logger,
+    clients: registry.clients(),
+    providerDefinitions: registry.definitions(),
+  });
+  const agent = await manager.createAgent(
+    { provider: harness.registration.id, cwd: tmpdir() },
+    undefined,
+    { workspaceId: undefined },
+  );
+  const messages = async () =>
+    (await manager.getTimeline(agent.id)).flatMap((item) =>
+      item.type === "user_message" || item.type === "assistant_message" ? [item.text] : [],
+    );
+  try {
+    await manager.runAgent(agent.id, "A", { clientMessageId: "client-A" });
+    await manager.runAgent(agent.id, "B", { clientMessageId: "client-B" });
+    await manager.runAgent(agent.id, "C", { clientMessageId: "client-C" });
+    expect(await messages()).toEqual(["A", "Reply A", "B", "Reply B", "C", "Reply C"]);
+    await run({ manager, agentId: agent.id, nativeMessages: harness.nativeMessages, messages });
+  } finally {
+    await manager.closeAgent(agent.id);
+    await registry.shutdown();
+  }
+}
+
+test("conversation rewind discards withdrawn plugin turns before and after a replacement prompt", async () => {
+  await withRewindAgent(async ({ manager, agentId, nativeMessages, messages }) => {
+    await manager.rewind(agentId, "client-B", "conversation");
+    const afterRewind = await messages();
+    expect(nativeMessages).toEqual(["A"]);
+    await manager.runAgent(agentId, "D", { clientMessageId: "client-D" });
+    const afterReplacement = await messages();
+    expect(nativeMessages).toEqual(["A", "D"]);
+    expect({ afterRewind, afterReplacement }).toEqual({
+      afterRewind: ["A", "Reply A"],
+      afterReplacement: ["A", "Reply A", "D", "Reply D"],
+    });
+  });
+});
+
+test("file-only plugin rewind preserves the conversation before and after a replacement prompt", async () => {
+  await withRewindAgent(async ({ manager, agentId, nativeMessages, messages }) => {
+    await manager.rewind(agentId, "client-B", "files");
+    expect(nativeMessages).toEqual(["A", "B", "C"]);
+    expect(await messages()).toEqual(["A", "Reply A", "B", "Reply B", "C", "Reply C"]);
+    await manager.runAgent(agentId, "D", { clientMessageId: "client-D" });
+    expect(await messages()).toEqual([
+      "A",
+      "Reply A",
+      "B",
+      "Reply B",
+      "C",
+      "Reply C",
+      "D",
+      "Reply D",
+    ]);
+  });
+});
+
+test("plugin rewind restores translation state when a replacement reuses a discarded item id", async () => {
+  const harness = createRewindProviderHarness({ reuseAnswerId: true });
+  const registry = new PluginAgentClientRegistry(createTestLogger());
+  registry.replace([harness.registration]);
+  const client = registry.clients()[harness.registration.id]!;
+  const session = await client.createSession({ provider: harness.registration.id, cwd: tmpdir() });
+  const live: AgentStreamEvent[] = [];
+  try {
+    await session.run("A");
+    await session.run("B");
+    session.subscribe((event) => live.push(event));
+    await session.revertConversation!({ messageId: "user-B" });
+    live.length = 0;
+    await session.run("B revised");
+    const assistant = live.flatMap((event) =>
+      event.type === "timeline" && event.item.type === "assistant_message" ? [event.item.text] : [],
+    );
+    expect(harness.nativeMessages).toEqual(["A", "B revised"]);
+    expect(assistant).toEqual(["Reply B revised"]);
+  } finally {
+    await session.close();
+    await registry.shutdown();
+  }
+});
+
+async function withPluginRewindSession(
+  options: Parameters<typeof createRewindProviderHarness>[0],
+  run: (
+    session: Awaited<ReturnType<AgentClient["createSession"]>>,
+    harness: ReturnType<typeof createRewindProviderHarness>,
+  ) => Promise<void>,
+) {
+  const harness = createRewindProviderHarness(options);
+  const registry = new PluginAgentClientRegistry(createTestLogger());
+  registry.replace([harness.registration]);
+  const client = registry.clients()[harness.registration.id]!;
+  const session = await client.createSession({ provider: harness.registration.id, cwd: tmpdir() });
+  try {
+    await session.run("A");
+    await session.run("B");
+    await session.run("C");
+    await run(session, harness);
+  } finally {
+    await session.close();
+    await registry.shutdown();
+  }
+}
+
+async function pluginMessages(session: Awaited<ReturnType<AgentClient["createSession"]>>) {
+  const events = await Array.fromAsync(session.streamHistory());
+  return events.flatMap((event) =>
+    event.type === "timeline" &&
+    (event.item.type === "user_message" || event.item.type === "assistant_message")
+      ? [event.item.text]
+      : [],
+  );
+}
+
+test("combined plugin rewind replays the retained native branch", async () => {
+  await withPluginRewindSession({}, async (session) => {
+    await session.revertBoth!({ messageId: "user-B" });
+    expect(await pluginMessages(session)).toEqual(["A", "Reply A"]);
+    await session.revertConversation!({ messageId: "user-A" });
+    expect(await pluginMessages(session)).toEqual([]);
+  });
+});
+
+test("a rewind reopens with the options as they stand, a reset included", async () => {
+  const options: Record<string, boolean> = {};
+  const report = (emit: (event: ProviderEvent) => void, sessionId: string) =>
+    emit({
+      type: "session.config",
+      sessionId,
+      config: {
+        model: "plugin-model",
+        mode: "build",
+        models: [{ id: "plugin-model", label: "Plugin model" }],
+        modes: [{ id: "build", label: "Build" }],
+        thinkingOptions: [],
+        controls: [{ type: "toggle", key: "concise", label: "Concise" }],
+        providerOptions: { ...options },
+      },
+    });
+  const harness = createRewindProviderHarness({
+    handleInput: async (input, emit) => {
+      if (input.type === "session.open" && input.history !== "replay") {
+        options.concise = true;
+        emit({
+          type: "session.opened",
+          requestId: input.requestId,
+          sessionId: input.sessionId,
+          capabilities: [...CAPABILITIES, "session.revert.conversation"],
+          restoration: "core",
+          persistence: { version: 1, data: { token: "root" } },
+          cwd: input.config.cwd,
+        });
+        report(emit, input.sessionId);
+        emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+        return true;
+      }
+      if (input.type === "session.configure") {
+        // A plugin that represents the default by leaving the key out.
+        delete options.concise;
+        report(emit, input.sessionId);
+        emit({ type: "request.completed", requestId: input.requestId });
+        return true;
+      }
+      return false;
+    },
+  });
+  const registry = new PluginAgentClientRegistry(createTestLogger());
+  registry.replace([harness.registration]);
+  const session = await registry.clients()[harness.registration.id]!.createSession({
+    provider: harness.registration.id,
+    cwd: tmpdir(),
+    providerOptions: { concise: true },
+  });
+  await session.run("A");
+  await session.applyOptions?.({ concise: null });
+
+  await session.revertConversation!({ messageId: "user-A" });
+
+  const reopened = harness.inputs.findLast((input) => input.type === "session.open");
+  expect(reopened?.config.providerOptions).toEqual({});
+  await session.close();
+  await registry.shutdown();
+});
+
+// A plugin may report no options at all while it runs the ones it was given.
+async function withUnreportedOptionSession(
+  run: (
+    session: Awaited<ReturnType<AgentClient["createSession"]>>,
+    harness: ReturnType<typeof createRewindProviderHarness>,
+  ) => Promise<void>,
+) {
+  const harness = createRewindProviderHarness({
+    handleInput: async (input, emit) => {
+      if (input.type === "session.open" && input.history !== "replay") {
+        emit({
+          type: "session.opened",
+          requestId: input.requestId,
+          sessionId: input.sessionId,
+          capabilities: [...CAPABILITIES, "session.revert.conversation"],
+          restoration: "core",
+          persistence: { version: 1, data: { token: "root" } },
+          cwd: input.config.cwd,
+        });
+        emit({
+          type: "session.config",
+          sessionId: input.sessionId,
+          config: {
+            model: "plugin-model",
+            mode: "build",
+            models: [{ id: "plugin-model", label: "Plugin model" }],
+            modes: [{ id: "build", label: "Build" }],
+            thinkingOptions: [],
+            controls: [],
+            providerOptions: {},
+          },
+        });
+        emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+        return true;
+      }
+      if (input.type === "session.configure") {
+        emit({ type: "request.completed", requestId: input.requestId });
+        return true;
+      }
+      return false;
+    },
+  });
+  const registry = new PluginAgentClientRegistry(createTestLogger());
+  registry.replace([harness.registration]);
+  const session = await registry.clients()[harness.registration.id]!.createSession({
+    provider: harness.registration.id,
+    cwd: tmpdir(),
+    providerOptions: { token_budget: 1000 },
+  });
+  try {
+    await run(session, harness);
+  } finally {
+    await session.close();
+    await registry.shutdown();
+  }
+}
+
+test("applying an option the plugin never reports leaves the stored option alone", async () => {
+  await withUnreportedOptionSession(async (session) => {
+    // The same value as a whole-profile patch carries it, then a new one.
+    expect(await session.applyOptions?.({ token_budget: 1000 })).toEqual({});
+    expect(await session.applyOptions?.({ token_budget: 2000 })).toEqual({});
+  });
+});
+
+test("a rewind reopens with the value the plugin accepted for an option it never reports", async () => {
+  await withUnreportedOptionSession(async (session, harness) => {
+    await session.run("A");
+    await session.applyOptions?.({ token_budget: 2000 });
+
+    await session.revertConversation!({ messageId: "user-A" });
+
+    const reopened = harness.inputs.findLast((input) => input.type === "session.open");
+    expect(reopened?.config.providerOptions).toEqual({ token_budget: 2000 });
+  });
+});
+
+test("plugin rewind resumes the latest persistence rather than the original handle", async () => {
+  await withPluginRewindSession(
+    {
+      handleInput: async (input, emit) => {
+        if (input.type === "session.revert")
+          emit({
+            type: "session.persistence",
+            sessionId: input.sessionId,
+            persistence: { version: 1, data: { token: "fork" } },
+          });
+        return false;
+      },
+    },
+    async (session, harness) => {
+      await session.revertConversation!({ messageId: "user-B" });
+      expect(harness.inputs.findLast((input) => input.type === "session.open")).toMatchObject({
+        persistence: { version: 1, data: { token: "fork" } },
+        history: "replay",
+      });
+      expect(await pluginMessages(session)).toEqual(["A", "Reply A"]);
+    },
+  );
+});
+
+test("failed native plugin rewind preserves history and does not reopen", async () => {
+  await withPluginRewindSession(
+    {
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.revert") return false;
+        emit({
+          type: "request.failed",
+          requestId: input.requestId,
+          error: { message: "native rewind failed" },
+        });
+        return true;
+      },
+    },
+    async (session, harness) => {
+      await expect(session.revertConversation!({ messageId: "user-B" })).rejects.toThrow(
+        "native rewind failed",
+      );
+      expect(await pluginMessages(session)).toEqual([
+        "A",
+        "Reply A",
+        "B",
+        "Reply B",
+        "C",
+        "Reply C",
+      ]);
+      expect(harness.inputs.filter((input) => input.type === "session.open")).toHaveLength(1);
+    },
+  );
+});
+
+test("failed plugin rewind replay blocks prompts until retry without repeating native rewind", async () => {
+  let failReplay = true;
+  await withPluginRewindSession(
+    {
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.open" || input.history !== "replay" || !failReplay)
+          return false;
+        failReplay = false;
+        emit({
+          type: "request.failed",
+          requestId: input.requestId,
+          error: { message: "replay failed" },
+        });
+        return true;
+      },
+    },
+    async (session, harness) => {
+      await expect(session.revertConversation!({ messageId: "user-B" })).rejects.toThrow(
+        "replay failed",
+      );
+      await expect(session.run("D")).rejects.toThrow("Retry the rewind or reload");
+      await session.revertConversation!({ messageId: "user-B" });
+      await session.run("D");
+      expect(await pluginMessages(session)).toEqual(["A", "Reply A", "D", "Reply D"]);
+      expect(harness.inputs.filter((input) => input.type === "session.revert")).toHaveLength(1);
+    },
+  );
+});
+
+test("a failed plugin rewind replay blocks prompts until a reload settles the committed rewind", async () => {
+  let failReplay = true;
+  await withRewindAgent(
+    async ({ manager, agentId, messages }) => {
+      // The native revert committed, but the session could not replay what it kept.
+      await expect(manager.rewind(agentId, "client-B", "conversation")).rejects.toMatchObject({
+        name: "RewindOutcomeUnknownError",
+        cause: { message: "replay failed" },
+      });
+      await expect(manager.runAgent(agentId, "D")).rejects.toBeInstanceOf(
+        RewindOutcomeUnknownError,
+      );
+      await manager.reloadAgentSession(agentId);
+      expect(await messages()).toEqual(["A", "Reply A"]);
+      await manager.runAgent(agentId, "D");
+      expect(await messages()).toEqual(["A", "Reply A", "D", "Reply D"]);
+    },
+    {
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.open" || input.history !== "replay" || !failReplay)
+          return false;
+        failReplay = false;
+        emit({
+          type: "request.failed",
+          requestId: input.requestId,
+          error: { message: "replay failed" },
+        });
+        return true;
+      },
+    },
+  );
+});
+
+test("reload after failed plugin rewind replay resumes the committed fork", async () => {
+  let failReplay = true;
+  await withRewindAgent(
+    async ({ manager, agentId, messages }) => {
+      await expect(manager.rewind(agentId, "client-B", "conversation")).rejects.toMatchObject({
+        name: "RewindOutcomeUnknownError",
+        cause: { message: "replay failed" },
+      });
+      await manager.reloadAgentSession(agentId, undefined, { rehydrateFromDisk: true });
+      expect(await messages()).toEqual(["A", "Reply A"]);
+    },
+    {
+      forkOnRevert: true,
+      handleInput: async (input, emit) => {
+        if (input.type === "session.close") {
+          emit({ type: "request.completed", requestId: input.requestId });
+          return true;
+        }
+        if (input.type !== "session.open" || input.history !== "replay" || !failReplay)
+          return false;
+        failReplay = false;
+        emit({
+          type: "request.failed",
+          requestId: input.requestId,
+          error: { message: "replay failed" },
+        });
+        return true;
+      },
+    },
+  );
+});
+
+test("closing during plugin rewind replay closes each native binding once", async () => {
+  let opened!: () => void;
+  let release!: () => void;
+  const replayStarted = new Promise<void>((resolve) => {
+    opened = resolve;
+  });
+  const replayAllowed = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  await withPluginRewindSession(
+    {
+      handleInput: async (input) => {
+        if (input.type === "session.open" && input.history === "replay") {
+          opened();
+          await replayAllowed;
+        }
+        return false;
+      },
+    },
+    async (session, harness) => {
+      const rewind = session.revertConversation!({ messageId: "user-B" });
+      await replayStarted;
+      const closing = session.close();
+      release();
+      await Promise.all([rewind, closing]);
+      const closes = harness.inputs.flatMap((input) =>
+        input.type === "session.close" ? [input.sessionId] : [],
+      );
+      expect(closes).toHaveLength(2);
+      expect(new Set(closes).size).toBe(2);
+    },
+  );
+});
+
+test("plugin rewind retries a failed close before reopening the native writer", async () => {
+  let failClose = true;
+  await withPluginRewindSession(
+    {
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.close" || !failClose) return false;
+        failClose = false;
+        emit({
+          type: "request.failed",
+          requestId: input.requestId,
+          error: { message: "close failed" },
+        });
+        return true;
+      },
+    },
+    async (session, harness) => {
+      await expect(session.revertConversation!({ messageId: "user-B" })).rejects.toThrow(
+        "close failed",
+      );
+      expect(harness.inputs.filter((input) => input.type === "session.open")).toHaveLength(1);
+      expect(await pluginMessages(session)).toEqual(["A", "Reply A"]);
+      expect(harness.inputs.filter((input) => input.type === "session.revert")).toHaveLength(1);
+    },
+  );
+});
+
+test("plugin rewind retries permission settlement before retiring its session", async () => {
+  let failPermission = true;
+  await withPluginRewindSession(
+    {
+      handleInput: async (input) => {
+        if (input.type !== "session.permission" || !failPermission) return false;
+        failPermission = false;
+        throw new Error("permission delivery failed");
+      },
+    },
+    async (session, harness) => {
+      const opened = harness.inputs.find((input) => input.type === "session.open")!;
+      if (opened.type !== "session.open") throw new Error("Missing root");
+      harness.emit({
+        type: "session.permission",
+        sessionId: opened.sessionId,
+        request: { id: "pending", name: "tool", kind: "tool" },
+      });
+      await expect(session.revertConversation!({ messageId: "user-B" })).rejects.toThrow(
+        "permission delivery failed",
+      );
+      expect(session.getPendingPermissions()).toHaveLength(1);
+      expect(harness.inputs.filter((input) => input.type === "session.close")).toHaveLength(0);
+      expect(await pluginMessages(session)).toEqual(["A", "Reply A"]);
+      expect(session.getPendingPermissions()).toEqual([]);
+      expect(harness.inputs.filter((input) => input.type === "session.permission")).toHaveLength(2);
+    },
+  );
+});
+
+test("plugin rewind replaces child listeners and settles old pending permissions", async () => {
+  await withPluginRewindSession({}, async (session, harness) => {
+    const root = harness.inputs.find((input) => input.type === "session.open")!;
+    if (root.type !== "session.open") throw new Error("Missing root");
+    harness.emit({
+      type: "session.permission",
+      sessionId: root.sessionId,
+      request: { id: "old-permission", name: "tool", kind: "tool", title: "Run tool" },
+    });
+    expect(session.getPendingPermissions()).toHaveLength(1);
+    await session.revertConversation!({ messageId: "user-B" });
+    expect(session.getPendingPermissions()).toEqual([]);
+    expect(harness.inputs).toContainEqual(
+      expect.objectContaining({
+        type: "session.permission",
+        permissionId: "old-permission",
+        response: { behavior: "deny", message: "Session replaced after rewind" },
+      }),
+    );
+    harness.emit({
+      type: "timeline.item",
+      sessionId: "child-1",
+      item: { type: "assistant_message", id: "child-message", text: "Discarded child update" },
+    });
+    const history = await Array.fromAsync(session.streamHistory());
+    expect(history.filter((event) => event.type === "provider_subagent")).toEqual([]);
+    const reopened = harness.inputs.findLast((input) => input.type === "session.open")!;
+    if (reopened.type !== "session.open") throw new Error("Missing reopened root");
+    harness.emit({
+      type: "session.opened",
+      sessionId: "child-1",
+      parentSessionId: reopened.sessionId,
+      capabilities: [],
+      restoration: "parent",
+      cwd: tmpdir(),
+    });
+    harness.emit({
+      type: "timeline.item",
+      sessionId: "child-1",
+      item: { type: "assistant_message", id: "child-message", text: "New child reply" },
+    });
+    const next = await Array.fromAsync(session.streamHistory());
+    expect(next).toContainEqual(
+      expect.objectContaining({
+        type: "provider_subagent",
+        event: expect.objectContaining({
+          type: "timeline",
+          item: expect.objectContaining({ text: "New child reply" }),
+        }),
+      }),
+    );
+  });
+});
+
+test("nonpersisted plugin sessions reject conversation rewind before native mutation", async () => {
+  await withPluginRewindSession(
+    {
+      handleInput: async (input, emit) => {
+        if (input.type !== "session.open") return false;
+        emit({
+          type: "session.opened",
+          requestId: input.requestId,
+          sessionId: input.sessionId,
+          capabilities: [...CAPABILITIES, "session.revert.conversation", "session.revert.files"],
+          restoration: "core",
+          cwd: input.config.cwd,
+        });
+        emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+        return true;
+      },
+    },
+    async (session, harness) => {
+      expect(session.capabilities.supportsRewindConversation).toBe(false);
+      await expect(session.revertConversation!({ messageId: "user-B" })).rejects.toThrow(
+        "requires session persistence",
+      );
+      expect(harness.inputs.filter((input) => input.type === "session.revert")).toEqual([]);
+      await session.revertFiles!({ messageId: "user-B" });
+      expect(harness.nativeMessages).toEqual(["A", "B", "C"]);
+    },
+  );
+});
+
 function openNestedChildren(rootSessionId: string, emit: (event: ProviderEvent) => void) {
   for (const [sessionId, parentSessionId] of [
     ["a", rootSessionId],
@@ -410,7 +1136,7 @@ describe("PluginAgentClientRegistry", () => {
     }
   });
 
-  test("stores only agent options while the plugin receives merged defaults", async () => {
+  test("stores the agent options and the settings the plugin opened with, not the merged config defaults", async () => {
     const logger = createTestLogger();
     const harness = createProviderHarness();
     const plugins = new PluginAgentClientRegistry(logger);
@@ -432,13 +1158,323 @@ describe("PluginAgentClientRegistry", () => {
       undefined,
       { workspaceId: undefined },
     );
-    expect(toStoredAgentRecord(agent).config?.providerOptions).toEqual(own);
+    // `nested.base` comes from `config.json` and is not stored; `voice` is the plugin's own opening state.
+    expect(toStoredAgentRecord(agent).config?.providerOptions).toEqual({ ...own, voice: "direct" });
     expect(harness.inputs.find((input) => input.type === "session.open")).toMatchObject({
       config: { providerOptions: { nested: { base: true, replace: "agent" } } },
     });
     await agent.session?.close();
   });
 
+  // The same contract holds for a plugin that reports `controls` and `providerOptions` and for one
+  // still reporting `settings`.
+  describe.each(["controls", "settings"] as const)("options of a plugin reporting %s", (shape) => {
+    // A plugin that keeps `voice` on "direct" whatever it is asked, and takes `loud` as given.
+    async function openStubbornVoiceSession(
+      given: Record<string, boolean | string>,
+      { refuseAfterChanging = false }: { refuseAfterChanging?: boolean } = {},
+    ) {
+      const state: { voice: string; loud: boolean; tokenBudget?: number } = {
+        voice: "direct",
+        loud: false,
+      };
+      let openedSessionId = "";
+      const reported = () =>
+        shape === "controls"
+          ? {
+              controls: [
+                {
+                  type: "select" as const,
+                  key: "voice",
+                  label: "Voice",
+                  icon: "Mic",
+                  defaultValue: "direct",
+                  choices: [
+                    { label: "Direct", value: "direct" },
+                    { label: "Other", value: "other" },
+                  ],
+                },
+                {
+                  type: "toggle" as const,
+                  key: "loud",
+                  label: "Loud",
+                  icon: "Volume2",
+                  defaultValue: false,
+                },
+              ],
+              providerOptions: {
+                voice: state.voice,
+                loud: state.loud,
+                ...(state.tokenBudget === undefined ? {} : { token_budget: state.tokenBudget }),
+              },
+            }
+          : {
+              settings: [
+                {
+                  type: "select" as const,
+                  id: "voice",
+                  label: "Voice",
+                  value: state.voice,
+                  options: [
+                    { label: "Direct", value: "direct" },
+                    { label: "Other", value: "other" },
+                  ],
+                },
+                { type: "toggle" as const, id: "loud", label: "Loud", value: state.loud },
+              ],
+            };
+      const emitConfig = (emit: (event: ProviderEvent) => void, sessionId: string) =>
+        emit({
+          type: "session.config",
+          sessionId,
+          config: {
+            model: "plugin-model",
+            mode: "build",
+            models: [{ id: "plugin-model", label: "Plugin model" }],
+            modes: [{ id: "build", label: "Build" }],
+            thinkingOptions: [],
+            ...reported(),
+          },
+        });
+      const harness = createProviderHarness({
+        async handleInput(input, emit) {
+          if (input.type === "session.open") {
+            openedSessionId = input.sessionId;
+            emit({
+              type: "session.opened",
+              requestId: input.requestId,
+              sessionId: input.sessionId,
+              capabilities: CAPABILITIES,
+              restoration: "core",
+              persistence: { version: 1, data: { token: "root" } },
+              cwd: input.config.cwd,
+            });
+            emitConfig(emit, input.sessionId);
+            emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
+            return true;
+          }
+          if (input.type === "session.configure") {
+            const patch =
+              shape === "settings" ? input.changes.settings : input.changes.providerOptions;
+            const { loud, token_budget: tokenBudget } = patch ?? {};
+            // A plugin that takes `token_budget` live refuses the whole request on a bad value.
+            if (tokenBudget !== undefined && typeof tokenBudget !== "number") {
+              emit({
+                type: "request.failed",
+                requestId: input.requestId,
+                error: { message: "bad budget" },
+              });
+              return true;
+            }
+            if (typeof loud === "boolean") state.loud = loud;
+            if (typeof tokenBudget === "number") state.tokenBudget = tokenBudget;
+            // Going loud returns an unrequested token budget to its default, by leaving it out.
+            if (loud === true && tokenBudget === undefined) state.tokenBudget = undefined;
+            emitConfig(emit, input.sessionId);
+            emit(
+              refuseAfterChanging
+                ? { type: "request.failed", requestId: input.requestId, error: { message: "no" } }
+                : { type: "request.completed", requestId: input.requestId },
+            );
+            return true;
+          }
+          return false;
+        },
+      });
+      const plugins = new PluginAgentClientRegistry(createTestLogger());
+      plugins.replace([harness.registration]);
+      const session = await plugins.clients()["plugin-direct"]!.createSession({
+        provider: "plugin-direct",
+        cwd: tmpdir(),
+        providerOptions: given,
+      });
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+      const changeOnItsOwn = (change: Partial<typeof state>) => {
+        Object.assign(state, change);
+        emitConfig(harness.emit, openedSessionId);
+      };
+      return { harness, session, events, changeOnItsOwn };
+    }
+
+    test("forwards a setting the plugin changes on its own", async () => {
+      const { session, events, changeOnItsOwn } = await openStubbornVoiceSession({});
+
+      changeOnItsOwn({ loud: true });
+
+      expect(eventsOfType(events, "options_changed")).toEqual([
+        { type: "options_changed", provider: "plugin-direct", patch: { loud: true } },
+      ]);
+      await session.close();
+    });
+
+    test.runIf(shape === "controls")(
+      "reports an option the plugin stops reporting as removed, alone or with another change",
+      async () => {
+        const { session, events, changeOnItsOwn } = await openStubbornVoiceSession({});
+        changeOnItsOwn({ tokenBudget: 500 });
+
+        changeOnItsOwn({ tokenBudget: undefined });
+        changeOnItsOwn({ tokenBudget: 700 });
+        changeOnItsOwn({ tokenBudget: undefined, loud: true });
+
+        expect(eventsOfType(events, "options_changed")).toEqual([
+          { type: "options_changed", provider: "plugin-direct", patch: { token_budget: 500 } },
+          { type: "options_changed", provider: "plugin-direct", patch: { token_budget: null } },
+          { type: "options_changed", provider: "plugin-direct", patch: { token_budget: 700 } },
+          {
+            type: "options_changed",
+            provider: "plugin-direct",
+            patch: { token_budget: null, loud: true },
+          },
+        ]);
+        await session.close();
+      },
+    );
+
+    test.runIf(shape === "controls")(
+      "an apply returns the option the plugin reset along the way as removed",
+      async () => {
+        const { session, events, changeOnItsOwn } = await openStubbornVoiceSession({});
+        changeOnItsOwn({ tokenBudget: 500 });
+
+        const ended = await session.applyOptions?.({ loud: true });
+
+        expect(ended).toEqual({ token_budget: null });
+        // The apply reports it; the plugin's later identical report is not a second change.
+        expect(eventsOfType(events, "options_changed")).toEqual([
+          { type: "options_changed", provider: "plugin-direct", patch: { token_budget: 500 } },
+        ]);
+        await session.close();
+      },
+    );
+
+    test("a rejected apply reports what the plugin moved before refusing, since nothing is stored", async () => {
+      const { session, events } = await openStubbornVoiceSession({}, { refuseAfterChanging: true });
+
+      await expect(session.applyOptions?.({ loud: true })).rejects.toThrow("no");
+
+      expect(eventsOfType(events, "options_changed")).toEqual([
+        { type: "options_changed", provider: "plugin-direct", patch: { loud: true } },
+      ]);
+      await session.close();
+    });
+
+    test("a setting the plugin opened differently is the session's open patch, not an event", async () => {
+      const { session, events } = await openStubbornVoiceSession({ voice: "other", loud: false });
+
+      expect(session.openOptionsPatch).toEqual({ voice: "direct" });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+
+    test("options the plugin opened with that nobody set are in the open patch, defaults included", async () => {
+      const { session, events } = await openStubbornVoiceSession({});
+
+      expect(session.openOptionsPatch).toEqual({ voice: "direct", loud: false });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+
+    test("applying options configures only the settings it is given", async () => {
+      const { harness, session } = await openStubbornVoiceSession({});
+
+      await session.applyOptions?.({ loud: true });
+
+      const configure = lastConfigure(harness.inputs);
+      // Only a plugin that reports `settings` is also sent them.
+      expect((configure as { changes: object }).changes).toEqual(
+        shape === "settings"
+          ? { providerOptions: { loud: true }, settings: { loud: true } }
+          : { providerOptions: { loud: true } },
+      );
+      await session.close();
+    });
+
+    test("a removal reaches the plugin as null", async () => {
+      const { harness, session } = await openStubbornVoiceSession({});
+
+      const ended = await session.applyOptions?.({ loud: null });
+
+      expect(lastConfigure(harness.inputs)).toMatchObject({
+        changes: { providerOptions: { loud: null } },
+      });
+      // It went back to its default, and what it ended up with is reported like any provider's.
+      expect(ended).toEqual({ loud: false });
+      await session.close();
+    });
+
+    test("draws a control from what the plugin reports", async () => {
+      const { session } = await openStubbornVoiceSession({});
+
+      expect((session.controls ?? []).map(controlKey)).toEqual(["voice", "loud"]);
+      await session.close();
+    });
+
+    test.runIf(shape === "controls")(
+      "keeps a control's icon, default and choices as the plugin declared them",
+      async () => {
+        const { session } = await openStubbornVoiceSession({});
+
+        expect(session.controls?.[0]).toMatchObject({
+          icon: "Mic",
+          defaultValue: "direct",
+          choices: [
+            { label: "Direct", value: "direct" },
+            { label: "Other", value: "other" },
+          ],
+        });
+        await session.close();
+      },
+    );
+
+    test.runIf(shape === "controls")(
+      "sends a live option that has no control, and the plugin's answer decides",
+      async () => {
+        const { harness, session, events } = await openStubbornVoiceSession({});
+
+        await session.applyOptions?.({ token_budget: 2000 });
+        expect(lastConfigure(harness.inputs)).toMatchObject({
+          changes: { providerOptions: { token_budget: 2000 } },
+        });
+
+        // The plugin refuses the request as a whole, so the other key it was given is not applied.
+        await expect(session.applyOptions?.({ loud: true, token_budget: "lots" })).rejects.toThrow(
+          "bad budget",
+        );
+        expect(eventsOfType(events, "options_changed")).toEqual([]);
+        expect(await session.applyOptions?.({ token_budget: 3000 })).toEqual({});
+        await session.close();
+      },
+    );
+
+    test("sends a key the plugin does not report, for the plugin to accept or refuse", async () => {
+      const { harness, session } = await openStubbornVoiceSession({});
+
+      await session.applyOptions?.({ loud: true, launch_key: "changed" });
+
+      const configure = lastConfigure(harness.inputs) as {
+        changes: { providerOptions: object; settings?: object };
+      };
+      expect(configure.changes.providerOptions).toEqual({ loud: true, launch_key: "changed" });
+      // A plugin reporting `settings` is sent the same keys under that name.
+      expect(configure.changes.settings).toEqual(
+        shape === "settings" ? { loud: true, launch_key: "changed" } : undefined,
+      );
+      await session.close();
+    });
+
+    test("applying options returns the settings that ended up different, and emits nothing", async () => {
+      const { session, events } = await openStubbornVoiceSession({});
+
+      const ended = await session.applyOptions?.({ voice: "other", loud: true });
+
+      expect(ended).toEqual({ voice: "direct" });
+      expect(eventsOfType(events, "options_changed")).toEqual([]);
+      await session.close();
+    });
+  });
+
   test.each([
     { options: { nested: { base: true, replace: "config" }, list: [1, 2], scalar: "config" } },
     { params: { nested: { base: true, replace: "config" }, list: [1, 2], scalar: "config" } },
@@ -951,12 +1987,13 @@ describe("PluginAgentClientRegistry", () => {
     });
 
     const session = await client!.createSession({ provider: "plugin-direct", cwd: "/workspace" });
-    expect(session.features).toEqual([
-      expect.objectContaining({
+    expect(session.controls).toEqual([
+      {
         type: "select",
-        id: "voice",
-        options: [{ id: "direct", label: "Direct", value: "direct" }],
-      }),
+        key: "voice",
+        label: "Voice",
+        choices: [{ value: "direct", label: "Direct" }],
+      },
     ]);
     expect(session.describePersistence()).toMatchObject({
       provider: "plugin-direct",
diff --git a/packages/server/src/server/agent/plugin-provider.ts b/packages/server/src/server/agent/plugin-provider.ts
index dbf39bbdb1..35477f43dc 100644
--- a/packages/server/src/server/agent/plugin-provider.ts
+++ b/packages/server/src/server/agent/plugin-provider.ts
@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { PluginSessionHistory } from "./plugin-session-history.js";
 import { resolve as resolvePath } from "node:path";
 import type { Logger } from "pino";
-import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { JsonValue, ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { z } from "zod";
 import {
   PROVIDER_CAPABILITIES,
@@ -31,10 +32,10 @@ import type {
   AgentCapabilityFlags,
   AgentClient,
   AgentCreateSessionOptions,
-  AgentFeature,
   AgentLaunchContext,
   AgentMode,
   AgentModelDefinition,
+  AgentOptionControl,
   AgentPermissionRequest,
   AgentPermissionResponse,
   AgentPersistenceHandle,
@@ -65,6 +66,7 @@ import {
   createProviderEnv,
   type ProviderRuntimeSettings,
 } from "./provider-launch-config.js";
+import { readPluginOptionState } from "./plugin-provider-options.js";
 import type { RegisteredProviderDefinition } from "./provider-registry.js";
 import { runProviderTurn } from "./providers/provider-runner.js";
 import { StaleProviderSessionError } from "./stale-provider-session-error.js";
@@ -605,7 +607,8 @@ class ProviderRuntimeSession {
   >();
   private readonly activeTurnIds = new Set<string>();
   private terminal = false;
-  config: ProviderConfigState = { models: [], modes: [], thinkingOptions: [], settings: [] };
+  private closePromise: Promise<void> | null = null;
+  config: ProviderConfigState = { models: [], modes: [], thinkingOptions: [] };
   commands: Array<{ name: string; description: string; argumentHint?: string }> = [];
   persistence: ProviderPersistence | null = null;
 
@@ -726,6 +729,14 @@ class ProviderRuntimeSession {
       this.runtime.removeSession(this.id, this.providerSessionId);
       return;
     }
+    this.closePromise ??= this.closeNativeSession().catch((error) => {
+      this.closePromise = null;
+      throw error;
+    });
+    await this.closePromise;
+  }
+
+  private async closeNativeSession(): Promise<void> {
     try {
       await this.runtime.complete({
         type: "session.close",
@@ -734,9 +745,9 @@ class ProviderRuntimeSession {
       });
     } catch (error) {
       if (!this.runtime.isClosed) throw error;
-    } finally {
-      this.runtime.removeSession(this.id, this.providerSessionId);
     }
+    // A failed close still needs its routing for a subsequent session.closed ack.
+    this.runtime.removeSession(this.id, this.providerSessionId);
   }
 
   beginOpen(requestId: string): Promise<void> {
@@ -1094,11 +1105,40 @@ class PluginAgentClient implements AgentClient {
       persistence: input.persistence,
       history: input.history,
     });
-    const session = new PluginAgentSession(this.provider, bridge, () => {
-      this.rootsBySession.delete(bridge.id);
-    });
-    this.rootsBySession.set(bridge.id, session);
-    this.attachPendingChildren();
+    const forget = () => {
+      for (const [id, owner] of this.rootsBySession) {
+        if (owner === session) this.rootsBySession.delete(id);
+      }
+    };
+    const bind = (next: ProviderRuntimeSession) => {
+      this.rootsBySession.set(next.id, session);
+      this.attachPendingChildren();
+    };
+    const config = mapSessionConfig(input.config, input.launchContext, input.persist);
+    const session = new PluginAgentSession(
+      this.provider,
+      bridge,
+      forget,
+      async (persistence, state, options) => {
+        forget();
+        return await this.runtime.openSession({
+          sessionId: randomUUID(),
+          config: {
+            ...config,
+            model: state.model,
+            mode: state.mode,
+            thinkingOption: state.thinkingOption,
+            settings: options,
+            providerOptions: options,
+          },
+          persistence,
+          history: "replay",
+        });
+      },
+      bind,
+      config.settings,
+    );
+    bind(bridge);
     return session;
   }
 
@@ -1159,18 +1199,48 @@ class PluginAgentSession implements AgentSession {
   private readonly revertTokens = new Map<string, ProviderTimelineItem["revertToken"]>();
   private readonly timelineSnapshots = new Map<string, TimelineTextSnapshot>();
   private readonly subagentIdsBySession = new Map<string, string | null>();
-  private readonly childUnsubscribes = new Map<string, () => void>();
+  private readonly children = new Map<
+    string,
+    { session: ProviderRuntimeSession; unsubscribe: () => void }
+  >();
   private readonly childSnapshots = new Map<string, Map<string, TimelineTextSnapshot>>();
   private unsubscribe: (() => void) | null = null;
+  /** How the opened session differs from the options it was given. */
+  readonly openOptionsPatch: Record<string, JsonValue>;
+  private knownOptions: Record<string, JsonValue> = {};
+  // The options a reopened session starts with: what it launched with, then every value the
+  // plugin reported or was given, minus every key that was reset.
+  private readonly committedOptions: Record<string, JsonValue>;
+  /** While `applyOptions` waits on the plugin, its `session.config` answers that call. */
+  private applyingOptions = false;
   private currentTurnId: string | null = null;
   private closed = false;
+  private replay: {
+    persistence: ProviderPersistence;
+    config: ProviderConfigState;
+    messageId: string;
+    scope: "conversation" | "both";
+    closed: boolean;
+  } | null = null;
+  private replaying: Promise<void> | null = null;
 
   constructor(
     readonly provider: string,
-    private readonly bridge: ProviderRuntimeSession,
+    private bridge: ProviderRuntimeSession,
     private readonly onClose: () => void,
+    private readonly reopen: (
+      persistence: ProviderPersistence,
+      state: ProviderConfigState,
+      options: Readonly<Record<string, JsonValue>>,
+    ) => Promise<ProviderRuntimeSession>,
+    private readonly onBind: (bridge: ProviderRuntimeSession) => void,
+    givenOptions: Readonly<Record<string, JsonValue>>,
   ) {
     this.subagentIdsBySession.set(bridge.id, null);
+    // Every setting the session opened with that was not given, including ones nobody set.
+    this.committedOptions = { ...givenOptions };
+    this.openOptionsPatch = this.optionDifferences(givenOptions);
+    this.commitOptions();
     for (const event of bridge.history) this.accept(event, false);
     // Opening notices arrive before the manager subscribes to the session.
     // Commit them on registration and replay the same timestamps from history.
@@ -1185,18 +1255,17 @@ class PluginAgentSession implements AgentSession {
   }
 
   get capabilities(): AgentCapabilityFlags {
-    return agentCapabilities(this.bridge.negotiatedCapabilities);
+    const capabilities = agentCapabilities(this.bridge.negotiatedCapabilities);
+    const resumable = this.canReplayHistory;
+    return {
+      ...capabilities,
+      supportsRewindConversation: capabilities.supportsRewindConversation && resumable,
+      supportsRewindBoth: capabilities.supportsRewindBoth && resumable,
+    };
   }
 
-  get features(): AgentFeature[] {
-    return this.bridge.config.settings.map((setting) =>
-      setting.type === "toggle"
-        ? { ...setting }
-        : {
-            ...setting,
-            options: setting.options.map((option) => ({ ...option, id: option.value })),
-          },
-    );
+  get controls(): AgentOptionControl[] {
+    return readPluginOptionState(this.bridge.config).controls;
   }
 
   async run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult> {
@@ -1213,6 +1282,7 @@ class PluginAgentSession implements AgentSession {
     prompt: AgentPromptInput,
     options: AgentRunOptions = {},
   ): Promise<{ turnId: string }> {
+    this.assertReplayComplete();
     const clientMessageId = options.clientMessageId ?? randomUUID();
     const result = await this.bridge.prompt({
       clientMessageId,
@@ -1235,6 +1305,7 @@ class PluginAgentSession implements AgentSession {
     prompt: AgentPromptInput,
     options: SteerActiveTurnOptions,
   ): Promise<SteerResult> {
+    this.assertReplayComplete();
     if (!this.bridge.negotiatedCapabilities.includes("prompt.steer")) {
       return { status: "unavailable" };
     }
@@ -1258,6 +1329,7 @@ class PluginAgentSession implements AgentSession {
   }
 
   async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
+    await this.ensureReplay();
     for (const event of this.history.read(this.provider)) yield event;
   }
 
@@ -1285,6 +1357,7 @@ class PluginAgentSession implements AgentSession {
   }
 
   async setMode(modeId: string): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({ mode: modeId });
   }
 
@@ -1321,17 +1394,10 @@ class PluginAgentSession implements AgentSession {
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
-    this.unsubscribe?.();
-    this.unsubscribe = null;
-    for (const unsubscribe of this.childUnsubscribes.values()) unsubscribe();
-    this.childUnsubscribes.clear();
-    this.subagentIdsBySession.clear();
-    this.history.clear();
-    this.timelineSnapshots.clear();
-    this.childSnapshots.clear();
-    this.revertTokens.clear();
-    this.pendingPermissions.clear();
-    this.permissionResponses.clear();
+    this.listeners.clear();
+    await this.replaying?.catch(() => undefined);
+    await this.clearBinding();
+    this.replay = null;
     this.listeners.clear();
     this.onClose();
     await this.bridge.close();
@@ -1345,18 +1411,50 @@ class PluginAgentSession implements AgentSession {
     }));
   }
 
-  async setModel(modelId: string | null): Promise<void> {
+  async setModel(modelId: string | null): Promise<{ model: string | null }> {
+    this.assertReplayComplete();
     await this.bridge.configure({ model: modelId });
+    return { model: this.bridge.config.model ?? null };
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void> {
+    this.assertReplayComplete();
     await this.bridge.configure({ thinkingOption: thinkingOptionId });
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    await this.bridge.configure({
-      settings: { [featureId]: toJsonValue(value, `setting '${featureId}'`) },
-    });
+  /** The agent manager sends one apply at a time per session. */
+  async applyOptions(options: ProviderOptions): Promise<Record<string, JsonValue>> {
+    this.assertReplayComplete();
+    const before = this.currentOptions();
+    const { legacySettings } = readPluginOptionState(this.bridge.config);
+    // The plugin applies every key it is given or rejects the whole request.
+    const settings: Record<string, JsonValue> = {};
+    for (const [id, value] of Object.entries(options)) {
+      settings[id] = toJsonValue(value, `option '${id}'`);
+    }
+    if (Object.keys(settings).length === 0) return {};
+    this.applyingOptions = true;
+    try {
+      // COMPAT(plugin-provider-settings): added in v0.15.0, remove after 2027-05-01. A plugin
+      // reporting `settings` is sent the same keys under that name.
+      await this.bridge.configure({
+        providerOptions: settings,
+        ...(legacySettings ? { settings } : {}),
+      });
+    } catch (error) {
+      // Nothing is stored for a refused patch, so what the plugin moved is reported once the
+      // call has ended.
+      this.applyingOptions = false;
+      for (const event of this.reportOptionChanges()) this.publish(event);
+      throw error;
+    } finally {
+      this.applyingOptions = false;
+    }
+    // A requested key is a request, not a report: only a key the plugin reported before can be
+    // one it has now dropped.
+    const ended = this.optionChanges({ ...before, ...settings }, before);
+    this.commitOptions(settings);
+    return ended;
   }
 
   // A plugin completes `session.revert` without saying which messages it removed, and a failed
@@ -1422,10 +1520,10 @@ class PluginAgentSession implements AgentSession {
     const snapshots = new Map<string, TimelineTextSnapshot>();
     this.childSnapshots.set(childId, snapshots);
     for (const event of child.history) this.acceptChildEvent(childId, event, snapshots);
-    this.childUnsubscribes.set(
-      child.id,
-      child.onEvent((event) => this.acceptChildEvent(childId, event, snapshots)),
-    );
+    this.children.set(child.id, {
+      session: child,
+      unsubscribe: child.onEvent((event) => this.acceptChildEvent(childId, event, snapshots)),
+    });
   }
 
   private accept(event: ProviderEvent, live: boolean): void {
@@ -1543,10 +1641,66 @@ class PluginAgentSession implements AgentSession {
     };
   }
 
+  private currentOptions(): Record<string, JsonValue> {
+    return readPluginOptionState(this.bridge.config).options;
+  }
+
+  /** Options whose value differs from `known`: the plugin's own change or its opening state. */
+  private optionDifferences(known: Readonly<Record<string, JsonValue>>): Record<string, JsonValue> {
+    const patch: Record<string, JsonValue> = {};
+    for (const [id, value] of Object.entries(this.currentOptions())) {
+      if (!isDeepStrictEqual(known[id], value)) patch[id] = value;
+    }
+    return patch;
+  }
+
+  /**
+   * Settle the options a reopened session starts with: what is committed, then the request the
+   * plugin accepted, then what it reported back. A key it reported before and no longer reports
+   * was reset.
+   */
+  private commitOptions(accepted: Readonly<Record<string, JsonValue>> = {}): void {
+    for (const [id, value] of Object.entries(accepted)) {
+      if (value === null) delete this.committedOptions[id];
+      else this.committedOptions[id] = value;
+    }
+    const current = this.currentOptions();
+    for (const id of Object.keys(this.knownOptions)) {
+      if (!(id in current)) delete this.committedOptions[id];
+    }
+    Object.assign(this.committedOptions, current);
+    this.knownOptions = current;
+  }
+
+  /**
+   * What changed against the options `known` to be set: values that differ, and `null` for a key
+   * in `reported` that the plugin no longer reports, which went back to its default.
+   */
+  private optionChanges(
+    known: Readonly<Record<string, JsonValue>>,
+    reported: Readonly<Record<string, JsonValue>>,
+  ): Record<string, JsonValue> {
+    const patch = this.optionDifferences(known);
+    const current = this.currentOptions();
+    for (const id of Object.keys(reported)) {
+      if (known[id] !== null && !(id in current)) patch[id] = null;
+    }
+    return patch;
+  }
+
+  private reportOptionChanges(): AgentStreamEvent[] {
+    if (this.applyingOptions) return [];
+    const patch = this.optionChanges(this.knownOptions, this.knownOptions);
+    if (Object.keys(patch).length === 0) return [];
+    this.commitOptions();
+    return [{ type: "options_changed", provider: this.provider, patch }];
+  }
+
   private translateConfig(
     event: Extract<ProviderEvent, { type: "session.config" }>,
   ): AgentStreamEvent[] {
     return [
+      ...this.reportOptionChanges(),
       {
         type: "mode_changed",
         provider: this.provider,
@@ -1643,7 +1797,84 @@ class PluginAgentSession implements AgentSession {
     }
   }
 
+  private async clearBinding(): Promise<void> {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    for (const child of this.children.values()) {
+      child.unsubscribe();
+      await child.session.close();
+    }
+    this.children.clear();
+    this.subagentIdsBySession.clear();
+    this.history.clear();
+    this.timelineSnapshots.clear();
+    this.childSnapshots.clear();
+    this.revertTokens.clear();
+    this.pendingPermissions.clear();
+    this.permissionResponses.clear();
+    this.currentTurnId = null;
+  }
+
+  private assertReplayComplete(): void {
+    if (this.replay) {
+      throw new Error(
+        "Plugin rewind history refresh is incomplete. Retry the rewind or reload the agent before continuing.",
+      );
+    }
+  }
+
+  // A native rewind has already committed. Until replay succeeds, neither history
+  // nor a new prompt may use the retired binding. Keep its latest handle for retry.
+  private async ensureReplay(): Promise<void> {
+    if (!this.replay) return;
+    if (this.closed) throw new StaleProviderSessionError(this.id);
+    if (!this.replaying) {
+      this.replaying = this.replayBinding().finally(() => {
+        this.replaying = null;
+      });
+    }
+    await this.replaying;
+  }
+
+  private async replayBinding(): Promise<void> {
+    const replay = this.replay!;
+    if (!replay.closed) {
+      for (const request of this.pendingPermissions.values()) {
+        await this.respondToPermission(request.id, {
+          behavior: "deny",
+          message: "Session replaced after rewind",
+        });
+        this.pendingPermissions.delete(request.id);
+        this.permissionResponses.delete(request.id);
+      }
+      await this.clearBinding();
+      await this.bridge.close();
+      replay.closed = true;
+    }
+    const bridge = await this.reopen(replay.persistence, replay.config, this.committedOptions);
+    this.bridge = bridge;
+    this.subagentIdsBySession.set(bridge.id, null);
+    for (const event of bridge.history) this.accept(event, false);
+    this.unsubscribe = bridge.onEvent((event) => this.accept(event, true));
+    this.onBind(bridge);
+    this.replay = null;
+  }
+
+  private get canReplayHistory(): boolean {
+    return (
+      this.bridge.restoration === "core" &&
+      this.bridge.persistence !== null &&
+      this.bridge.negotiatedCapabilities.includes("session.persistence")
+    );
+  }
+
   private async revert(messageId: string, scope: "conversation" | "files" | "both") {
+    const pending = this.replay;
+    await this.ensureReplay();
+    if (pending?.messageId === messageId && pending.scope === scope) return;
+    if (scope !== "files" && !this.canReplayHistory) {
+      throw new Error("Plugin conversation rewind requires session persistence for history replay");
+    }
     const token = this.revertTokens.get(messageId);
     if (token === undefined) {
       throw new RewindNotAppliedError(`No provider revert token for message ${messageId}`);
@@ -1655,6 +1886,12 @@ class PluginAgentSession implements AgentSession {
       token,
       scope,
     });
+    if (scope !== "files") {
+      const persistence = this.bridge.persistence;
+      if (!persistence) throw new Error("Plugin rewind removed session persistence");
+      this.replay = { persistence, config: this.bridge.config, messageId, scope, closed: false };
+      await this.ensureReplay();
+    }
   }
 
   private publish(event: AgentStreamEvent): void {
@@ -1718,7 +1955,8 @@ function mapSessionConfig(
     model: config.model,
     mode: config.modeId,
     thinkingOption: config.thinkingOptionId,
-    settings: toJsonObject(config.featureValues ?? {}, "provider settings"),
+    // The plugin SDK reads composer values from `settings`; they are options here.
+    settings: toJsonObject(config.providerOptions ?? {}, "provider settings"),
     providerOptions: config.providerOptions,
     title: config.title ?? undefined,
     persist,
diff --git a/packages/server/src/server/agent/provider-options.ts b/packages/server/src/server/agent/provider-options.ts
index 8a7d0b16af..76a9d638b6 100644
--- a/packages/server/src/server/agent/provider-options.ts
+++ b/packages/server/src/server/agent/provider-options.ts
@@ -1,4 +1,5 @@
 import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { isDeepStrictEqual } from "node:util";
 import type { z } from "zod";
 
 export interface ProviderOptionIssue {
@@ -103,3 +104,26 @@ function isPlainObject(value: unknown): value is ProviderOptions {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
+
+/**
+ * Rejects a live patch that changes a key the running session cannot apply (one the provider
+ * reads only when it opens). A key whose value already matches the session's is not a change.
+ */
+export function assertChangesAreLive(input: {
+  provider: string;
+  patch: ProviderOptions;
+  current: ProviderOptions | undefined;
+  live: readonly string[];
+}): void {
+  const issues = Object.entries(input.patch)
+    .filter(
+      ([key, value]) =>
+        !input.live.includes(key) &&
+        !isDeepStrictEqual(input.current?.[key] ?? null, value ?? null),
+    )
+    .map(([key]) => ({
+      path: [key],
+      message: "cannot change on a running session; it applies when the agent is opened",
+    }));
+  if (issues.length > 0) throw new ProviderOptionsValidationError(input.provider, issues);
+}
diff --git a/packages/server/src/server/agent/provider-registry-wrap.test.ts b/packages/server/src/server/agent/provider-registry-wrap.test.ts
index 04d123ead1..cfe7b56fe0 100644
--- a/packages/server/src/server/agent/provider-registry-wrap.test.ts
+++ b/packages/server/src/server/agent/provider-registry-wrap.test.ts
@@ -25,7 +25,7 @@ const OPTIONAL_AGENT_SESSION_METHOD_NAMES = [
   "listCommands",
   "setModel",
   "setThinkingOption",
-  "setFeature",
+  "applyOptions",
   "revertConversation",
   "revertFiles",
   "revertBoth",
@@ -152,8 +152,8 @@ class FakeSession implements AgentSession {
     this.recordedCalls.push("setThinkingOption");
   }
 
-  async setFeature() {
-    this.recordedCalls.push("setFeature");
+  async applyOptions() {
+    this.recordedCalls.push("applyOptions");
   }
 
   async revertConversation() {
@@ -193,7 +193,7 @@ describe("wrapSessionProvider", () => {
     await wrapped.listCommands?.();
     await wrapped.setModel?.("sonnet");
     await wrapped.setThinkingOption?.("high");
-    await wrapped.setFeature?.("feature-1", true);
+    await wrapped.applyOptions?.({ "feature-1": true });
     await wrapped.revertConversation?.({ messageId: "message-1" });
     await wrapped.revertFiles?.({ messageId: "message-1" });
     await wrapped.revertBoth?.({ messageId: "message-1" });
@@ -208,7 +208,7 @@ describe("wrapSessionProvider", () => {
       "listCommands",
       "setModel",
       "setThinkingOption",
-      "setFeature",
+      "applyOptions",
       "revertConversation",
       "revertFiles",
       "revertBoth",
diff --git a/packages/server/src/server/agent/provider-registry.test.ts b/packages/server/src/server/agent/provider-registry.test.ts
index 9a2cb768f0..f1fda21dff 100644
--- a/packages/server/src/server/agent/provider-registry.test.ts
+++ b/packages/server/src/server/agent/provider-registry.test.ts
@@ -4,7 +4,7 @@ import type { ToolPolicy } from "@getpaseo/protocol/agent-types";
 import { createTestLogger } from "../../test-utils/test-logger.js";
 import type {
   AgentClient,
-  AgentFeature,
+  AgentDraftControls,
   AgentModelDefinition,
   AgentMode,
   AgentSessionConfig,
@@ -392,17 +392,20 @@ vi.mock("./providers/cursor-acp-agent.js", () => ({
       return true;
     }
 
-    async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
+    async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
       mockState.cursorListFeaturesConfigs.push(config);
-      return [
-        {
-          type: "select",
-          id: "fast",
-          label: "Fast",
-          value: "false",
-          options: [{ id: "false", label: "Off" }],
-        },
-      ];
+      return {
+        options: config.providerOptions ?? {},
+        controls: [
+          {
+            type: "select",
+            key: "fast",
+            label: "Fast",
+            defaultValue: "false",
+            choices: [{ value: "false", label: "Off" }],
+          },
+        ],
+      };
     }
   },
 }));
@@ -791,6 +794,33 @@ test("ACP provider configuration retains opaque options", () => {
   });
 });
 
+test("a saved legacy Codex Fast preference wins over a configured service_tier default", () => {
+  const registry = buildProviderRegistry(logger, {
+    providerOverrides: { codex: { options: { service_tier: "default", plan_mode: false } } },
+  });
+  const client = registry.codex.createClient(logger);
+
+  // The manager hands the registry a pre-v0.10 record's `fast_mode` already converted.
+  expect(client.effectiveOptions?.({ service_tier: "fast" })).toEqual({
+    service_tier: "fast",
+    plan_mode: false,
+  });
+  expect(client.effectiveOptions?.({})).toEqual({ service_tier: "default", plan_mode: false });
+});
+
+test("a configured legacy Codex Fast default supplies the service_tier default", () => {
+  const registry = buildProviderRegistry(logger, {
+    providerOverrides: { codex: { options: { fast_mode: true } } },
+  });
+  const client = registry.codex.createClient(logger);
+
+  // Removing an agent's own speed falls back to the configured Fast.
+  expect(client.effectiveOptions?.({})).toEqual({ service_tier: "fast" });
+  expect(client.effectiveOptions?.({ service_tier: "default" })).toEqual({
+    service_tier: "default",
+  });
+});
+
 test("cursor provider extending acp uses CursorACPAgentClient", () => {
   const registry = buildProviderRegistry(logger, {
     providerOverrides: {
@@ -823,7 +853,7 @@ test("cursor provider extending acp uses CursorACPAgentClient", () => {
   expect(mockState.constructorArgs.genericAcp).toEqual([]);
 });
 
-test("wrapped cursor client lists ACP features through the inner provider", async () => {
+test("wrapped cursor client lists ACP controls through the inner provider", async () => {
   const registry = buildProviderRegistry(logger, {
     providerOverrides: {
       cursor: {
@@ -837,19 +867,22 @@ test("wrapped cursor client lists ACP features through the inner provider", asyn
   const client = registry.cursor.createClient(logger);
 
   await expect(
-    client.listFeatures?.({
+    client.listControls?.({
       provider: "cursor",
       cwd: "/tmp/cursor",
     }),
-  ).resolves.toEqual([
-    {
-      type: "select",
-      id: "fast",
-      label: "Fast",
-      value: "false",
-      options: [{ id: "false", label: "Off" }],
-    },
-  ]);
+  ).resolves.toEqual({
+    controls: [
+      {
+        type: "select",
+        key: "fast",
+        label: "Fast",
+        defaultValue: "false",
+        choices: [{ value: "false", label: "Off" }],
+      },
+    ],
+    options: {},
+  });
   expect(mockState.cursorListFeaturesConfigs).toEqual([
     {
       provider: "acp",
diff --git a/packages/server/src/server/agent/provider-registry.ts b/packages/server/src/server/agent/provider-registry.ts
index 0f3c39868a..2449b9a90b 100644
--- a/packages/server/src/server/agent/provider-registry.ts
+++ b/packages/server/src/server/agent/provider-registry.ts
@@ -48,6 +48,7 @@ import { PiRpcAgentClient } from "./providers/pi/agent.js";
 import { TraeACPAgentClient } from "./providers/trae-acp-agent.js";
 import { MockLoadTestAgentClient } from "./providers/mock-load-test-agent.js";
 import { MockSlowProviderClient } from "./providers/mock-slow-provider.js";
+import { convertLegacyOptions } from "./option-controls.js";
 import { ToolPolicyUnsupportedError, mergeProviderOptions } from "./provider-options.js";
 import {
   AGENT_PROVIDER_DEFINITIONS,
@@ -447,8 +448,11 @@ export function wrapSessionProvider(provider: AgentProvider, inner: AgentSession
     get initialTimeline() {
       return inner.initialTimeline;
     },
-    get features() {
-      return inner.features;
+    get controls() {
+      return inner.controls;
+    },
+    get openOptionsPatch() {
+      return inner.openOptionsPatch;
     },
     usageSession: inner.usageSession?.bind(inner),
     run: (prompt, options) => inner.run(prompt, options),
@@ -468,12 +472,13 @@ export function wrapSessionProvider(provider: AgentProvider, inner: AgentSession
     respondToPermission: (requestId, response) => inner.respondToPermission(requestId, response),
     describePersistence: () => mapPersistenceHandle(provider, inner.describePersistence()),
     interrupt: () => inner.interrupt(),
+    stopBackgroundWork: inner.stopBackgroundWork?.bind(inner),
     close: () => inner.close(),
     canStopRuntime: inner.canStopRuntime?.bind(inner),
     listCommands: inner.listCommands?.bind(inner),
     setModel: inner.setModel?.bind(inner),
     setThinkingOption: inner.setThinkingOption?.bind(inner),
-    setFeature: inner.setFeature?.bind(inner),
+    applyOptions: inner.applyOptions?.bind(inner),
     revertConversation: inner.revertConversation?.bind(inner),
     revertFiles: inner.revertFiles?.bind(inner),
     revertBoth: inner.revertBoth?.bind(inner),
@@ -487,14 +492,20 @@ function wrapClientProvider(
   profileModels: ProviderProfileModel[],
   additionalModels: ProviderProfileModel[],
   profileModelsAreAdditive: boolean,
-  providerOptions: ProviderOptions | undefined,
+  configuredOptions: ProviderOptions | undefined,
 ): AgentClient {
   const listImportableSessions = inner.listImportableSessions?.bind(inner);
   const importSession = inner.importSession?.bind(inner);
-  const listFeatures = inner.listFeatures?.bind(inner);
+  const listControls = inner.listControls?.bind(inner);
   const archiveNativeSession = inner.archiveNativeSession?.bind(inner);
   const unarchiveNativeSession = inner.unarchiveNativeSession?.bind(inner);
   const configuredModelIds = [...profileModels, ...additionalModels].map((model) => model.id);
+  // Converted where it is used, so a malformed configured default fails the call that reads it
+  // rather than the registry that holds every provider.
+  const configuredDefaults = () =>
+    convertLegacyOptions({ provider: inner.provider, options: configuredOptions });
+  const withDefaults = (own: ProviderOptions | undefined) =>
+    mergeProviderOptions(configuredDefaults(), own);
 
   return {
     provider,
@@ -509,7 +520,7 @@ function wrapClientProvider(
           {
             ...config,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+            providerOptions: withDefaults(config.providerOptions),
           },
           launchContext,
           { ...options, configuredModelIds },
@@ -526,14 +537,17 @@ function wrapClientProvider(
           {
             ...overrides,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, overrides?.providerOptions),
+            providerOptions: withDefaults(overrides?.providerOptions),
           },
           launchContext,
           { ...options, configuredModelIds },
         ),
       ),
     fetchCatalog: async (options, context) => {
-      const catalog = await inner.fetchCatalog({ ...options, providerOptions }, context);
+      const catalog = await inner.fetchCatalog(
+        { ...options, providerOptions: configuredDefaults() },
+        context,
+      );
       return {
         ...catalog,
         models: mergeModels(provider, profileModels, additionalModels, catalog.models, {
@@ -548,7 +562,7 @@ function wrapClientProvider(
             config: {
               ...config,
               provider: inner.provider,
-              providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+              providerOptions: withDefaults(config.providerOptions),
             },
             env,
             signal,
@@ -557,16 +571,18 @@ function wrapClientProvider(
     resolveCreateConfig: inner.resolveCreateConfig?.bind(inner),
     resolveConfiguredModel: inner.resolveConfiguredModel?.bind(inner),
     isCreateConfigUnattended: inner.isCreateConfigUnattended?.bind(inner),
-    listFeatures: listFeatures
+    effectiveOptions: (own) => withDefaults(own) ?? {},
+    listControls: listControls
       ? async (config) =>
-          await listFeatures({
+          await listControls({
             ...config,
             provider: inner.provider,
-            providerOptions: mergeProviderOptions(providerOptions, config.providerOptions),
+            providerOptions: withDefaults(config.providerOptions),
           })
       : undefined,
     listImportableSessions: listImportableSessions
-      ? async (options) => await listImportableSessions({ ...options, providerOptions })
+      ? async (options) =>
+          await listImportableSessions({ ...options, providerOptions: configuredDefaults() })
       : undefined,
     importSession: importSession
       ? async (input, context) => {
@@ -575,10 +591,7 @@ function wrapClientProvider(
             config: {
               ...context.config,
               provider: inner.provider,
-              providerOptions: mergeProviderOptions(
-                providerOptions,
-                context.config.providerOptions,
-              ),
+              providerOptions: withDefaults(context.config.providerOptions),
             },
             storedConfig: {
               ...context.storedConfig,
diff --git a/packages/server/src/server/agent/provider-runtime.ts b/packages/server/src/server/agent/provider-runtime.ts
index 398d35746d..c266614273 100644
--- a/packages/server/src/server/agent/provider-runtime.ts
+++ b/packages/server/src/server/agent/provider-runtime.ts
@@ -22,7 +22,12 @@ interface CreateAgentProviderRuntimeOptions {
 export async function createAgentProviderRuntime(
   options: CreateAgentProviderRuntimeOptions,
 ): Promise<AgentProviderRuntime> {
-  const bridge = new OpenCodeBridge({ paseoHome: options.paseoHome, logger: options.logger });
+  const configuredPort =
+    options.snapshotManager.runtimeSettings?.opencode?.env?.PASEO_OPENCODE_BRIDGE_PORT;
+  const port = configuredPort === undefined ? undefined : Number(configuredPort);
+  if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65535))
+    throw new Error("PASEO_OPENCODE_BRIDGE_PORT must be an integer between 1 and 65535");
+  const bridge = new OpenCodeBridge({ paseoHome: options.paseoHome, logger: options.logger, port });
   try {
     await bridge.start();
     const snapshotManager = new ProviderSnapshotManager({
diff --git a/packages/server/src/server/agent/provider-snapshot-manager.test.ts b/packages/server/src/server/agent/provider-snapshot-manager.test.ts
index f663ccf55b..bae5ba4001 100644
--- a/packages/server/src/server/agent/provider-snapshot-manager.test.ts
+++ b/packages/server/src/server/agent/provider-snapshot-manager.test.ts
@@ -1306,7 +1306,7 @@ describe("ProviderSnapshotManager public surface", () => {
             resolverInputs.push(input);
             return {
               modeId: input.parent?.isUnattended ? "child-unattended" : undefined,
-              featureValues: undefined,
+              providerOptions: undefined,
             };
           },
         }),
@@ -1337,17 +1337,17 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "codex",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent,
         unattended: false,
       });
 
-      expect(resolved).toEqual({ modeId: "child-unattended", featureValues: undefined });
+      expect(resolved).toEqual({ modeId: "child-unattended", providerOptions: undefined });
       expect(resolverInputs).toEqual([
         {
           provider: "codex",
           requestedMode: undefined,
-          featureValues: undefined,
+          providerOptions: undefined,
           parent: {
             provider: "claude",
             modeId: "parent-unattended",
@@ -1385,7 +1385,7 @@ describe("ProviderSnapshotManager public surface", () => {
             resolverInputs.push(input);
             return {
               modeId: input.unattended ? "worker" : undefined,
-              featureValues: undefined,
+              providerOptions: undefined,
             };
           },
         }),
@@ -1396,17 +1396,17 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "codex",
         requestedMode: undefined,
-        featureValues: { fast_mode: true },
+        providerOptions: { fast_mode: true },
         parent: null,
         unattended: true,
       });
 
-      expect(resolved).toEqual({ modeId: "worker", featureValues: undefined });
+      expect(resolved).toEqual({ modeId: "worker", providerOptions: undefined });
       expect(resolverInputs).toEqual([
         {
           provider: "codex",
           requestedMode: undefined,
-          featureValues: { fast_mode: true },
+          providerOptions: { fast_mode: true },
           parent: null,
           unattended: true,
           availableModes: modes,
@@ -1455,7 +1455,7 @@ describe("ProviderSnapshotManager public surface", () => {
         config: {
           provider: "opencode",
           cwd: "/tmp/project",
-          featureValues: { auto_accept: true },
+          providerOptions: { auto_accept: true },
         },
       };
 
@@ -1463,12 +1463,28 @@ describe("ProviderSnapshotManager public surface", () => {
         cwd: "/tmp/project",
         provider: "opencode",
         requestedMode: "base",
-        featureValues: undefined,
+        providerOptions: undefined,
         parent,
         unattended: false,
       });
 
-      expect(resolved).toEqual({ modeId: "base", featureValues: { auto_accept: true } });
+      expect(resolved).toEqual({ modeId: "base", providerOptions: { auto_accept: true } });
+
+      // A parent whose Auto Accept comes from the provider's config.json default has no own
+      // option; it is classified on its effective options.
+      const inheriting = await manager.resolveCreateConfig({
+        cwd: "/tmp/project",
+        provider: "opencode",
+        requestedMode: "base",
+        providerOptions: undefined,
+        parent: {
+          ...parent,
+          config: { provider: "opencode", cwd: "/tmp/project" },
+          effectiveOptions: { auto_accept: true },
+        },
+        unattended: false,
+      });
+      expect(inheriting).toEqual({ modeId: "base", providerOptions: { auto_accept: true } });
     } finally {
       manager.destroy();
     }
diff --git a/packages/server/src/server/agent/provider-snapshot-manager.ts b/packages/server/src/server/agent/provider-snapshot-manager.ts
index b10a4f8e02..7e728713be 100644
--- a/packages/server/src/server/agent/provider-snapshot-manager.ts
+++ b/packages/server/src/server/agent/provider-snapshot-manager.ts
@@ -1,4 +1,4 @@
-import { normalizeAgentModelCatalog } from "@getpaseo/protocol/agent-types";
+import { normalizeAgentModelCatalog, type ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { homedir } from "node:os";
@@ -160,14 +160,14 @@ export interface ResolveProviderCreateConfigOptions {
   cwd?: string | null;
   provider: AgentProvider;
   requestedMode: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
   parent: ManagedAgent | null;
   unattended: boolean;
 }
 
 export interface ResolvedProviderCreateConfig {
   modeId: string | undefined;
-  featureValues: Record<string, unknown> | undefined;
+  providerOptions: ProviderOptions | undefined;
 }
 
 interface ResolveDefaultModelOptions {
@@ -563,7 +563,7 @@ export class ProviderSnapshotManager {
     return definition.resolveCreateConfig({
       provider: input.provider,
       requestedMode: input.requestedMode,
-      featureValues: input.featureValues,
+      providerOptions: input.providerOptions,
       parent,
       unattended: input.unattended || parent?.isUnattended === true,
       availableModes: entry.modes ?? [],
@@ -744,8 +744,13 @@ export class ProviderSnapshotManager {
       modeId: parent.currentModeId,
       isUnattended: definition.isCreateConfigUnattended({
         modeId: parent.currentModeId,
-        config: parent.config,
-        features: parent.features,
+        // Provider defaults from `config.json` apply to the parent too, so classify on the
+        // effective options while the stored overrides stay as they are.
+        config: {
+          ...parent.config,
+          providerOptions: parent.effectiveOptions ?? parent.config.providerOptions,
+        },
+        controls: parent.controls,
         availableModes: parent.availableModes ?? definition.modes ?? [],
       }),
     };
diff --git a/packages/server/src/server/agent/providers/acp-agent.mode-namespace.test.ts b/packages/server/src/server/agent/providers/acp-agent.mode-namespace.test.ts
new file mode 100644
index 0000000000..8128604684
--- /dev/null
+++ b/packages/server/src/server/agent/providers/acp-agent.mode-namespace.test.ts
@@ -0,0 +1,298 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { SessionConfigOption, SessionUpdate } from "@agentclientprotocol/sdk";
+import { ACPAgentClient, type SessionStateResponse } from "./acp-agent.js";
+import { CopilotACPAgentClient, COPILOT_ALLOW_ALL_MODE_ID } from "./copilot-acp-agent.js";
+import type { AgentSession } from "../agent-sdk-types.js";
+import { createTestLogger } from "../../../test-utils/test-logger.js";
+
+const modes = {
+  currentModeId: "accept_edits",
+  availableModes: [
+    { id: "default", name: "Default" },
+    { id: "accept_edits", name: "Accept Edits" },
+    { id: "dont_ask", name: "Don't Ask" },
+  ],
+};
+
+function editOptions(currentValue = "workspace_session"): SessionConfigOption[] {
+  return [
+    {
+      id: "edit_approval_policy",
+      name: "Edits",
+      category: "mode",
+      type: "select",
+      currentValue,
+      options: [
+        { value: "ask", name: "Default" },
+        { value: "workspace_session", name: "Accept Edits" },
+        { value: "session", name: "Don't Ask" },
+      ],
+    },
+  ];
+}
+
+// A controlled ACP process, speaking the same stdio protocol as a provider.
+// Notifications precede session/new's response to exercise queued initialization updates.
+const modePeerScript = String.raw`
+import { createInterface } from "node:readline";
+import { readFileSync, appendFileSync } from "node:fs";
+const scenario = JSON.parse(readFileSync(process.argv[2], "utf8"));
+let configOptions = scenario.state.configOptions;
+const send = (message) => process.stdout.write(JSON.stringify(message) + "\n");
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line);
+  const reply = (result) => send({jsonrpc: "2.0", id: request.id, result});
+  const reject = (message) => send({jsonrpc: "2.0", id: request.id, error: {code: -32602, message}});
+  switch (request.method) {
+    case "initialize":
+      reply({protocolVersion: 1, agentCapabilities: {}});
+      break;
+    case "session/new":
+      for (const update of scenario.updates) {
+        send({jsonrpc: "2.0", method: "session/update", params: {sessionId: "mode-session", update}});
+      }
+      reply({sessionId: "mode-session", ...scenario.state});
+      break;
+    case "session/set_mode":
+      appendFileSync(process.argv[3], JSON.stringify(request) + "\n");
+      if (request.params.modeId === scenario.rejectedMode) {
+        reject("mode denied");
+      } else if (!scenario.state.modes?.availableModes.some(mode => mode.id === request.params.modeId)) {
+        reject("invalid_params");
+      } else {
+        reply({});
+      }
+      break;
+    case "session/set_config_option":
+      appendFileSync(process.argv[3], JSON.stringify(request) + "\n");
+      configOptions = configOptions.map(option => option.id === request.params.configId
+        ? {...option, currentValue: request.params.value} : option);
+      reply({configOptions});
+      break;
+    default:
+      reject("Unexpected request: " + request.method);
+  }
+});
+`;
+
+interface ModeCall {
+  method: string;
+  params: { sessionId: string; modeId?: string; configId?: string; value?: string };
+}
+
+let session: AgentSession | undefined;
+let directory: string | undefined;
+
+afterEach(async () => {
+  try {
+    await session?.close();
+  } finally {
+    session = undefined;
+    if (directory) await rm(directory, { recursive: true, force: true });
+    directory = undefined;
+  }
+});
+
+async function fixture(
+  options: {
+    state?: Omit<SessionStateResponse, "sessionId">;
+    updates?: SessionUpdate[];
+    rejectedMode?: string;
+    startupMode?: string;
+    copilot?: boolean;
+  } = {},
+) {
+  const artifacts = path.resolve(".artifacts");
+  await mkdir(artifacts, { recursive: true });
+  directory = await mkdtemp(path.join(artifacts, "acp-mode-"));
+  const script = path.join(directory, "peer.mjs");
+  const scenario = path.join(directory, "scenario.json");
+  const calls = path.join(directory, "calls.jsonl");
+  await writeFile(script, modePeerScript);
+  await writeFile(calls, "");
+  await writeFile(
+    scenario,
+    JSON.stringify({
+      state: options.state ?? { modes, configOptions: editOptions() },
+      updates: options.updates ?? [
+        { sessionUpdate: "config_option_update", configOptions: editOptions() },
+      ],
+      rejectedMode: options.rejectedMode,
+    }),
+  );
+  const command: [string, ...string[]] = [process.execPath, script, scenario, calls];
+  const client = options.copilot
+    ? new CopilotACPAgentClient({
+        logger: createTestLogger(),
+        runtimeSettings: { command: { mode: "replace", argv: command } },
+      })
+    : new ACPAgentClient({
+        provider: "mode-peer",
+        logger: createTestLogger(),
+        defaultCommand: command,
+      });
+  session = await client.createSession({
+    provider: options.copilot ? "copilot" : "mode-peer",
+    cwd: directory,
+    modeId: options.startupMode,
+  });
+  return {
+    session,
+    async calls(): Promise<ModeCall[]> {
+      const lines = (await readFile(calls, "utf8")).trim();
+      return lines
+        ? lines.split("\n").map((line) => {
+            const { method, params } = JSON.parse(line) as ModeCall;
+            return { method, params };
+          })
+        : [];
+    },
+  };
+}
+
+const modeCall = (modeId: string) => ({
+  method: "session/set_mode",
+  params: { sessionId: "mode-session", modeId },
+});
+const configCall = (configId: string, value: string) => ({
+  method: "session/set_config_option",
+  params: { sessionId: "mode-session", configId, value },
+});
+
+describe("ACP mode and config-value namespaces over stdio", () => {
+  test("selects Don't Ask from the advertised catalogue after a queued config update", async () => {
+    const peer = await fixture();
+    const available = await peer.session.getAvailableModes();
+    const dontAsk = available.find((mode) => mode.label === "Don't Ask");
+    expect(dontAsk).toBeDefined();
+    await peer.session.setMode(dontAsk!.id);
+    expect(await peer.calls()).toEqual([modeCall("dont_ask")]);
+    expect(await peer.session.getCurrentMode()).toBe("dont_ask");
+    expect(available.map((mode) => mode.id)).toEqual(["default", "accept_edits", "dont_ask"]);
+  });
+
+  test("keeps a pushed current mode through separate-policy and empty config updates", async () => {
+    const peer = await fixture({
+      updates: [
+        { sessionUpdate: "current_mode_update", currentModeId: "dont_ask" },
+        { sessionUpdate: "config_option_update", configOptions: editOptions("session") },
+        { sessionUpdate: "config_option_update", configOptions: [] },
+      ],
+    });
+    expect(await peer.session.getCurrentMode()).toBe("dont_ask");
+    expect((await peer.session.getAvailableModes()).map((mode) => mode.id)).toEqual([
+      "default",
+      "accept_edits",
+      "dont_ask",
+    ]);
+    expect(await peer.calls()).toEqual([]);
+  });
+
+  test("ignores policy values outside the advertised session modes without an RPC", async () => {
+    const peer = await fixture();
+    await peer.session.setMode("session");
+    expect(await peer.calls()).toEqual([]);
+    expect(await peer.session.getCurrentMode()).toBe("accept_edits");
+  });
+
+  test("retains confirmed state after rejection without falling back to a config write", async () => {
+    const peer = await fixture({ rejectedMode: "dont_ask", updates: [] });
+    await expect(peer.session.setMode("dont_ask")).rejects.toThrow("mode denied");
+    expect(await peer.session.getCurrentMode()).toBe("accept_edits");
+    expect(await peer.calls()).toEqual([modeCall("dont_ask")]);
+  });
+
+  test("selects a config-only mode through its owning config option", async () => {
+    const peer = await fixture({ state: { configOptions: editOptions() } });
+    await peer.session.setMode("session");
+    expect(await peer.calls()).toEqual([configCall("edit_approval_policy", "session")]);
+    expect(await peer.session.getCurrentMode()).toBe("session");
+  });
+
+  test.each([true, false])("routes startup overrides with session modes: %s", async (withModes) => {
+    const peer = await fixture({
+      state: { modes: withModes ? modes : undefined, configOptions: editOptions() },
+      startupMode: withModes ? "dont_ask" : "session",
+    });
+    expect(await peer.calls()).toEqual([
+      withModes ? modeCall("dont_ask") : configCall("edit_approval_policy", "session"),
+    ]);
+    expect(await peer.session.getCurrentMode()).toBe(withModes ? "dont_ask" : "session");
+  });
+});
+
+const agentMode = "https://agentclientprotocol.com/protocol/session-modes#agent";
+const planMode = "https://agentclientprotocol.com/protocol/session-modes#plan";
+function copilotConfig(allowAll: string): SessionConfigOption[] {
+  return [
+    {
+      id: "mode",
+      name: "Mode",
+      category: "mode",
+      type: "select",
+      currentValue: agentMode,
+      options: [
+        { value: agentMode, name: "Agent" },
+        { value: planMode, name: "Plan" },
+      ],
+    },
+    {
+      id: "allow_all",
+      name: "Allow All",
+      type: "select",
+      currentValue: allowAll,
+      options: [
+        { value: "on", name: "On" },
+        { value: "off", name: "Off" },
+      ],
+    },
+  ];
+}
+function copilotFixture(initial: string, pushed: string) {
+  return fixture({
+    copilot: true,
+    state: {
+      modes: {
+        currentModeId: agentMode,
+        availableModes: [
+          { id: agentMode, name: "Agent" },
+          { id: planMode, name: "Plan" },
+        ],
+      },
+      configOptions: copilotConfig(initial),
+    },
+    updates: [{ sessionUpdate: "config_option_update", configOptions: copilotConfig(pushed) }],
+  });
+}
+
+describe("Copilot Allow All through the public client", () => {
+  test("adopts an Allow All notification and disables it before switching modes", async () => {
+    const peer = await copilotFixture("off", "on");
+    expect(await peer.session.getCurrentMode()).toBe(COPILOT_ALLOW_ALL_MODE_ID);
+    await peer.session.setMode(planMode);
+    expect(await peer.calls()).toEqual([configCall("allow_all", "off"), modeCall(planMode)]);
+    expect(await peer.session.getCurrentMode()).toBe(planMode);
+  });
+
+  test("adopts an Allow All off notification after initializing with it enabled", async () => {
+    const peer = await copilotFixture("on", "off");
+    expect(await peer.session.getCurrentMode()).toBe(agentMode);
+    expect(await peer.calls()).toEqual([]);
+  });
+
+  test("selects Allow All and switches away in provider RPC order", async () => {
+    const peer = await copilotFixture("off", "off");
+    await peer.session.setMode(COPILOT_ALLOW_ALL_MODE_ID);
+    expect(await peer.session.getCurrentMode()).toBe(COPILOT_ALLOW_ALL_MODE_ID);
+    await peer.session.setMode(planMode);
+    expect(await peer.calls()).toEqual([
+      modeCall(agentMode),
+      configCall("allow_all", "on"),
+      configCall("allow_all", "off"),
+      modeCall(planMode),
+    ]);
+    expect(await peer.session.getCurrentMode()).toBe(planMode);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/acp-agent.test.ts b/packages/server/src/server/agent/providers/acp-agent.test.ts
index e902493dcb..b94a6de940 100644
--- a/packages/server/src/server/agent/providers/acp-agent.test.ts
+++ b/packages/server/src/server/agent/providers/acp-agent.test.ts
@@ -1,10 +1,10 @@
 import { type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
-import { EventEmitter } from "node:events";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { EventEmitter, once } from "node:events";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   AgentSideConnection,
@@ -99,13 +99,34 @@ describe("buildACPClientCapabilities", () => {
 
 interface ACPSessionInternals {
   sessionId: string | null;
-  connection: { prompt: (...args: unknown[]) => Promise<PromptResponse> };
+  connection: {
+    prompt: (...args: unknown[]) => Promise<PromptResponse>;
+    signal: AbortSignal;
+  };
   activeForegroundTurnId: string | null;
   configOptions: SessionConfigOption[];
   translateSessionUpdate(update: SessionUpdate): AgentStreamEvent[];
   acpMcpServers(): unknown[];
 }
 
+function openPromptConnection(
+  prompt: (...args: unknown[]) => Promise<unknown>,
+): ACPSessionInternals["connection"] {
+  return {
+    prompt: prompt as ACPSessionInternals["connection"]["prompt"],
+    signal: new AbortController().signal,
+  };
+}
+
+function terminalEvents(events: AgentStreamEvent[]): AgentStreamEvent[] {
+  return events.filter(
+    (event) =>
+      event.type === "turn_completed" ||
+      event.type === "turn_failed" ||
+      event.type === "turn_canceled",
+  );
+}
+
 interface ACPModelSelectionInternals {
   sessionId: string | null;
   connection: {
@@ -119,6 +140,7 @@ interface ACPModelSelectionInternals {
 }
 
 interface ACPConfiguredOverrideInternals {
+  applySessionState(response: SessionStateResponse): void;
   sessionId: string | null;
   connection: {
     setSessionMode: (input: { sessionId: string; modeId: string }) => Promise<void>;
@@ -198,7 +220,7 @@ function createSessionWithConfig(
     provider?: string;
     modeId?: string | null;
     model?: string | null;
-    featureValues?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
   } = {},
   logger: ReturnType<typeof createTestLogger> = createTestLogger(),
 ): ACPAgentSession {
@@ -208,7 +230,7 @@ function createSessionWithConfig(
       cwd: "/tmp/paseo-acp-test",
       modeId: config.modeId ?? undefined,
       model: config.model ?? undefined,
-      featureValues: config.featureValues,
+      providerOptions: config.providerOptions,
     },
     {
       provider: config.provider ?? "claude-acp",
@@ -300,19 +322,20 @@ function selectConfigOption(
 
 function createCopilotSessionWithConfig(
   modeId?: string | null,
-  featureValues?: Record<string, unknown>,
+  providerOptions?: Record<string, unknown>,
+  defaultCommand: string[] = ["copilot", "--acp"],
 ): ACPAgentSession {
   return new ACPAgentSession(
     {
       provider: "copilot",
       cwd: "/tmp/paseo-acp-test",
       modeId: modeId ?? undefined,
-      ...(featureValues ? { featureValues } : {}),
+      ...(providerOptions ? { providerOptions } : {}),
     },
     {
       provider: "copilot",
       logger: createTestLogger(),
-      defaultCommand: ["copilot", "--acp"],
+      defaultCommand,
       defaultModes: COPILOT_MODES,
       sessionResponseTransformer: transformCopilotSessionResponse,
       configOptionsTransformer: transformCopilotConfigOptions,
@@ -423,6 +446,24 @@ function prepareConfiguredOverrideSession(
     configOptions: options.configOptions ?? [],
   }));
   const internals = asInternals<ACPConfiguredOverrideInternals>(session);
+  const availableModes = options.availableModes ?? [];
+  const modes =
+    availableModes.length > 0
+      ? {
+          currentModeId: options.currentMode ?? availableModes[0]!.id,
+          availableModes: availableModes.map((mode) => ({
+            id: mode.id,
+            label: mode.label,
+            description: mode.description,
+            name: mode.label,
+          })),
+        }
+      : undefined;
+  internals.applySessionState({
+    sessionId: "session-1",
+    modes,
+    configOptions: options.configOptions ?? [],
+  });
   internals.sessionId = "session-1";
   internals.connection = {
     setSessionMode,
@@ -480,7 +521,7 @@ test("ACP setModel only uses config-option fallback when the matching select cho
 
   setSessionConfigOption.mockClear();
 
-  await expect(session.setModel("new-provider-model")).resolves.toBeUndefined();
+  await expect(session.setModel("new-provider-model")).resolves.toEqual({ model: "sonnet" });
   expect(childLogger.warn).toHaveBeenCalledWith(
     { value: "new-provider-model" },
     expect.stringContaining("is not a valid claude-acp model config option"),
@@ -1498,7 +1539,7 @@ describe("ACPAgentSession Zed parity", () => {
   test("auto-accepts ACP permission requests when the shared feature is enabled", async () => {
     const session = createSessionWithConfig({
       provider: "cursor-acp",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const events: Array<{ type: string }> = [];
 
@@ -1530,7 +1571,7 @@ describe("ACPAgentSession Zed parity", () => {
   test("does not auto-accept ACP chooser requests", async () => {
     const session = createSessionWithConfig({
       provider: "kimi-acp",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     const events: AgentStreamEvent[] = [];
 
@@ -1583,11 +1624,8 @@ describe("ACPAgentSession Zed parity", () => {
     internals.sessionId = "session-1";
     internals.connection = {};
 
-    await session.setFeature("auto_accept", true);
+    await session.applyOptions({ auto_accept: true });
 
-    expect(session.features).toContainEqual(
-      expect.objectContaining({ type: "toggle", id: "auto_accept", value: true }),
-    );
     await expect(
       session.requestPermission({
         sessionId: "session-1",
@@ -1605,7 +1643,7 @@ describe("ACPAgentSession Zed parity", () => {
   });
 
   test("surfaces an ACP permission when auto-accept has no allow option", async () => {
-    const session = createSessionWithConfig({ featureValues: { auto_accept: true } });
+    const session = createSessionWithConfig({ providerOptions: { auto_accept: true } });
     const events: Array<{ type: string; request?: { id: string } }> = [];
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
     session.subscribe((event) => events.push(event as { type: string; request?: { id: string } }));
@@ -1765,35 +1803,18 @@ describe("ACPAgentSession Zed parity", () => {
     const internals = asInternals<ACPSessionInternals>(session);
     internals.configOptions = [copilotAgentConfigOption("")];
 
-    expect(session.features).toEqual([
-      expect.objectContaining({
-        type: "toggle",
-        id: "auto_accept",
-        value: false,
-      }),
+    expect(session.controls).toEqual([
+      expect.objectContaining({ type: "toggle", key: "auto_accept" }),
       {
         type: "select",
-        id: "agent",
+        key: "agent",
         label: "Agent",
         description: "Use a Copilot custom agent profile",
         tooltip: "Select Copilot agent",
         icon: undefined,
-        value: "",
-        options: [
-          {
-            id: "",
-            label: "Default",
-            description: undefined,
-            isDefault: true,
-            metadata: undefined,
-          },
-          {
-            id: "Probe Agent",
-            label: "Probe Agent",
-            description: "Temporary probe agent",
-            isDefault: false,
-            metadata: undefined,
-          },
+        choices: [
+          { value: "", label: "Default", description: undefined },
+          { value: "Probe Agent", label: "Probe Agent", description: "Temporary probe agent" },
         ],
       },
     ]);
@@ -1816,15 +1837,9 @@ describe("ACPAgentSession Zed parity", () => {
       configId: "agent",
       value: "Probe Agent",
     });
-    expect(session.features).toEqual([
-      expect.objectContaining({
-        id: "auto_accept",
-        value: false,
-      }),
-      expect.objectContaining({
-        id: "agent",
-        value: "Probe Agent",
-      }),
+    expect(session.controls).toEqual([
+      expect.objectContaining({ key: "auto_accept" }),
+      expect.objectContaining({ key: "agent" }),
     ]);
   });
 
@@ -1838,26 +1853,175 @@ describe("ACPAgentSession Zed parity", () => {
       connection: { setSessionConfigOption },
     });
 
-    await session.setFeature("agent", "Probe Agent");
+    await session.applyOptions({ agent: "Probe Agent" });
 
     expect(setSessionConfigOption).toHaveBeenCalledWith({
       sessionId: "session-1",
       configId: "agent",
       value: "Probe Agent",
     });
-    expect(session.features).toEqual([
-      expect.objectContaining({
-        id: "auto_accept",
-        value: false,
-      }),
-      expect.objectContaining({
-        id: "agent",
-        value: "Probe Agent",
-      }),
+    expect(session.controls).toEqual([
+      expect.objectContaining({ key: "auto_accept" }),
+      expect.objectContaining({ key: "agent" }),
     ]);
   });
 });
 
+describe("ACPAgentSession options against an ACP agent", () => {
+  const fakeAgentPath = fileURLToPath(new URL("./test-utils/fake-acp-agent.mjs", import.meta.url));
+  const sessions: ACPAgentSession[] = [];
+
+  afterEach(async () => {
+    await Promise.all(sessions.splice(0).map((session) => session.close()));
+  });
+
+  function thoughtOption(currentValue: string): SessionConfigOption {
+    return {
+      id: "thought",
+      name: "Thinking",
+      category: "thought_level",
+      type: "select",
+      currentValue,
+      options: [
+        { value: "low", name: "Low" },
+        { value: "high", name: "High" },
+      ],
+    };
+  }
+
+  async function openSession(input: {
+    agent?: string;
+    scenario?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+  }): Promise<{ session: ACPAgentSession; optionEvents: AgentStreamEvent[] }> {
+    const scenario = {
+      options: [copilotAgentConfigOption(input.agent ?? ""), thoughtOption("low")],
+      ...input.scenario,
+    };
+    await mkdir("/tmp/paseo-acp-test", { recursive: true });
+    const session = createCopilotSessionWithConfig(null, input.providerOptions, [
+      process.execPath,
+      fakeAgentPath,
+      JSON.stringify(scenario),
+    ]);
+    sessions.push(session);
+    const optionEvents: AgentStreamEvent[] = [];
+    session.subscribe((event) => {
+      if (event.type === "options_changed") optionEvents.push(event);
+    });
+    await session.initializeNewSession();
+    return { session, optionEvents };
+  }
+
+  test("a select the agent opened differently from the options is the open patch, not an event", async () => {
+    const { session, optionEvents } = await openSession({
+      providerOptions: { agent: "Probe Agent" },
+      scenario: { answers: { agent: "" } },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ agent: "" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a select the agent opened with that nobody set is in the open patch", async () => {
+    const { session, optionEvents } = await openSession({ agent: "Probe Agent" });
+
+    expect(session.openOptionsPatch).toEqual({ agent: "Probe Agent" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a notification that arrives before the open write is answered is not an event", async () => {
+    const { session, optionEvents } = await openSession({
+      providerOptions: { agent: "Probe Agent" },
+      scenario: { onWrite: "notify-first" },
+    });
+
+    expect(session.openOptionsPatch).toEqual({});
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("applying a patch returns the selects that ended up different and emits nothing", async () => {
+    const { session, optionEvents } = await openSession({ scenario: { answers: { agent: "" } } });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).resolves.toEqual({ agent: "" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a notification that arrives before the apply write is answered is not an event", async () => {
+    const { session, optionEvents } = await openSession({ scenario: { onWrite: "notify-first" } });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).resolves.toEqual({});
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a rejected apply reports what the agent moved before refusing, since nothing is stored", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { onWrite: "notify-then-reject" },
+    });
+
+    await expect(session.applyOptions({ agent: "Probe Agent" })).rejects.toThrow(/write refused/);
+    expect(optionEvents).toEqual([
+      { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+    ]);
+  });
+
+  test("a removal writes the select's empty choice and returns it, since the options hold what the session runs", async () => {
+    const { session, optionEvents } = await openSession({ agent: "Probe Agent" });
+
+    await expect(session.applyOptions({ agent: null })).resolves.toEqual({ agent: "" });
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("a removal of a select already on its empty choice returns that choice too", async () => {
+    const { session } = await openSession({ agent: "" });
+
+    await expect(session.applyOptions({ agent: null })).resolves.toEqual({ agent: "" });
+  });
+
+  test("rejects a live auto_accept the creation schema would reject, and writes nothing", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { onWrite: "notify-then-reject" },
+    });
+
+    await expect(
+      session.applyOptions({ auto_accept: "yes", agent: "Probe Agent" }),
+    ).rejects.toThrow(/auto_accept/);
+    expect(optionEvents).toEqual([]);
+  });
+
+  test("forwards a select the agent changes on its own", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: { moves: { thought: { agent: "Probe Agent" } } },
+    });
+
+    await session.setThinkingOption("high");
+
+    await vi.waitFor(() =>
+      expect(optionEvents).toEqual([
+        { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+      ]),
+    );
+  });
+
+  test("a select that appears after startup is reported with its native value", async () => {
+    const { session, optionEvents } = await openSession({
+      scenario: {
+        options: [thoughtOption("low")],
+        adds: { thought: [copilotAgentConfigOption("Probe Agent")] },
+      },
+    });
+    expect(session.openOptionsPatch).toEqual({});
+
+    await session.setThinkingOption("high");
+
+    await vi.waitFor(() =>
+      expect(optionEvents).toEqual([
+        { type: "options_changed", provider: "copilot", patch: { agent: "Probe Agent" } },
+      ]),
+    );
+  });
+});
+
 describe("deriveModelDefinitionsFromACP", () => {
   test("attaches shared thinking options to ACP model state", () => {
     const result = deriveModelDefinitionsFromACP(
@@ -2084,14 +2248,14 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: { provider_feature: "kept" },
+        providerOptions: { provider_feature: "kept" },
         parent: null,
         unattended: true,
         availableModes: [],
       }),
     ).toEqual({
       modeId: undefined,
-      featureValues: { provider_feature: "kept", auto_accept: true },
+      providerOptions: { provider_feature: "kept", auto_accept: true },
     });
   });
 
@@ -2106,12 +2270,12 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: { auto_accept: false },
+        providerOptions: { auto_accept: false },
         parent: null,
         unattended: true,
         availableModes: [],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: false } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: false } });
   });
 
   test("maps an unattended cross-provider parent to ACP Auto Accept", () => {
@@ -2125,7 +2289,7 @@ describe("ACPAgentClient config features", () => {
       client.resolveCreateConfig({
         provider: "generic-acp",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: {
           provider: "claude",
           modeId: "bypassPermissions",
@@ -2134,7 +2298,7 @@ describe("ACPAgentClient config features", () => {
         unattended: false,
         availableModes: [{ id: "agent", label: "Agent" }],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: true } });
   });
 
   test("treats Auto Accept as an unattended ACP configuration", () => {
@@ -2150,7 +2314,7 @@ describe("ACPAgentClient config features", () => {
         config: {
           provider: "generic-acp",
           cwd: "/tmp/acp-features",
-          featureValues: { auto_accept: true },
+          providerOptions: { auto_accept: true },
         },
         availableModes: [],
       }),
@@ -2165,22 +2329,20 @@ describe("ACPAgentClient config features", () => {
     });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "generic-acp",
         cwd: "/tmp/acp-features",
-        featureValues: { auto_accept: true },
+        providerOptions: { auto_accept: true },
       }),
-    ).resolves.toEqual([
-      expect.objectContaining({
-        type: "toggle",
-        id: "auto_accept",
-        label: "Auto Accept",
-        value: true,
-      }),
-    ]);
+    ).resolves.toEqual({
+      controls: [
+        expect.objectContaining({ type: "toggle", key: "auto_accept", label: "Auto Accept" }),
+      ],
+      options: { auto_accept: true },
+    });
   });
 
-  test("derives features from configured ACP select options", async () => {
+  test("derives controls from configured ACP select options", async () => {
     class TestACPAgentClient extends ACPAgentClient {
       protected override async spawnProcess(): Promise<SpawnedACPProcess> {
         return {
@@ -2205,27 +2367,26 @@ describe("ACPAgentClient config features", () => {
       configFeatureOptions: [COPILOT_AGENT_FEATURE_OPTION],
     });
 
+    // The select nobody set reads as the agent opened it.
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "copilot",
         cwd: "/tmp/acp-features",
       }),
-    ).resolves.toEqual([
-      expect.objectContaining({
-        type: "toggle",
-        id: "auto_accept",
-        value: false,
-      }),
-      expect.objectContaining({
-        type: "select",
-        id: "agent",
-        value: "Probe Agent",
-        options: [
-          expect.objectContaining({ id: "", label: "Default", isDefault: false }),
-          expect.objectContaining({ id: "Probe Agent", label: "Probe Agent", isDefault: true }),
-        ],
-      }),
-    ]);
+    ).resolves.toEqual({
+      controls: [
+        expect.objectContaining({ type: "toggle", key: "auto_accept" }),
+        expect.objectContaining({
+          type: "select",
+          key: "agent",
+          choices: [
+            expect.objectContaining({ value: "", label: "Default" }),
+            expect.objectContaining({ value: "Probe Agent", label: "Probe Agent" }),
+          ],
+        }),
+      ],
+      options: { agent: "Probe Agent" },
+    });
   });
 });
 
@@ -2634,6 +2795,72 @@ describe("ACPAgentSession slash commands", () => {
       },
     ]);
   });
+
+  test("lists late command batches through the public ACP client", async () => {
+    const artifacts = path.resolve(".artifacts");
+    await mkdir(artifacts, { recursive: true });
+    const directory = await mkdtemp(path.join(artifacts, "acp-command-inventory-"));
+    const script = path.join(directory, "agent.mjs");
+    await writeFile(
+      script,
+      `
+import { createInterface } from "node:readline";
+const send = (message) => process.stdout.write(JSON.stringify(message) + "\\n");
+const help = { name: "help", description: "Show available commands" };
+const skill = { name: "xlsx", description: "Work with spreadsheets", input: { hint: "[instructions]" } };
+const publish = (commands) => send({
+  jsonrpc: "2.0", method: "session/update", params: {
+    sessionId: "inventory-session", update: {
+      sessionUpdate: "available_commands_update", availableCommands: commands,
+    },
+  },
+});
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line);
+  if (request.method === "initialize") {
+    send({ jsonrpc: "2.0", id: request.id, result: { protocolVersion: 1, agentCapabilities: {} } });
+  } else if (request.method === "session/new") {
+    // The first batch is already cached when createSession returns.
+    publish([help]);
+    send({ jsonrpc: "2.0", id: request.id, result: { sessionId: "inventory-session" } });
+    setTimeout(() => publish([help]), 100);
+    setTimeout(() => publish([help, skill]), 350);
+  } else if (request.id !== undefined) {
+    send({ jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "Method not found" } });
+  }
+});
+`,
+    );
+    const client = new GenericACPAgentClient({
+      logger: createTestLogger(),
+      command: [process.execPath, script],
+    });
+    try {
+      const session = await client.createSession({ provider: "acp", cwd: directory });
+      try {
+        const commands = await session.listCommands!();
+        expect(commands).toEqual([
+          {
+            name: "help",
+            description: "Show available commands",
+            argumentHint: "",
+            kind: "command",
+          },
+          {
+            name: "xlsx",
+            description: "Work with spreadsheets",
+            argumentHint: "[instructions]",
+            kind: "command",
+          },
+        ]);
+        expect(await session.listCommands!()).toEqual(commands);
+      } finally {
+        await session.close();
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("ACPAgentSession", () => {
@@ -2987,7 +3214,7 @@ describe("ACPAgentSession", () => {
     );
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event as { type: string; turnId?: string });
@@ -3025,7 +3252,7 @@ describe("ACPAgentSession", () => {
     );
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3074,7 +3301,7 @@ describe("ACPAgentSession", () => {
     const prompt = vi.fn(() => new Promise<PromptResponse>(() => {}));
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3101,7 +3328,7 @@ describe("ACPAgentSession", () => {
     const prompt = vi.fn(() => new Promise<PromptResponse>(() => {}));
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3145,7 +3372,7 @@ describe("ACPAgentSession", () => {
     );
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3206,7 +3433,7 @@ describe("ACPAgentSession", () => {
     const prompt = vi.fn(() => new Promise<PromptResponse>(() => {}));
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3245,7 +3472,7 @@ describe("ACPAgentSession", () => {
     const prompt = vi.fn(() => new Promise<PromptResponse>(() => {}));
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3298,7 +3525,7 @@ describe("ACPAgentSession", () => {
     const prompt = vi.fn(() => new Promise<PromptResponse>(() => {}));
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event);
@@ -3347,7 +3574,7 @@ describe("ACPAgentSession", () => {
     );
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
 
     session.subscribe((event) => {
       events.push(event as { type: string; turnId?: string; error?: string });
@@ -3380,7 +3607,7 @@ describe("ACPAgentSession", () => {
     );
 
     asInternals<ACPSessionInternals>(session).sessionId = "session-1";
-    asInternals<ACPSessionInternals>(session).connection = { prompt };
+    asInternals<ACPSessionInternals>(session).connection = openPromptConnection(prompt);
     session.subscribe((event) => events.push(event));
 
     const { turnId } = await session.startTurn([
@@ -3485,6 +3712,148 @@ describe("ACPAgentSession", () => {
       error: expect.not.stringContaining("[object Object]"),
     });
   });
+
+  function fakeACPAgent(prompt: Agent["prompt"]): Agent {
+    return {
+      async initialize() {
+        return { protocolVersion: PROTOCOL_VERSION, agentCapabilities: {} };
+      },
+      async newSession() {
+        return { sessionId: "session-1" };
+      },
+      prompt,
+      async authenticate() {},
+      async cancel() {},
+    };
+  }
+
+  async function connectInMemoryACPAgent(
+    agent: Agent,
+    options: { closeAfterPromptResponse?: boolean } = {},
+  ): Promise<{
+    agentConnection: AgentSideConnection;
+    connection: ClientSideConnection;
+    sessionId: string;
+    closeTransport: () => Promise<void>;
+  }> {
+    const clientToAgent = new TransformStream<Uint8Array, Uint8Array>();
+    const agentToClient = new TransformStream<Uint8Array, Uint8Array>();
+    const agentOutput = agentToClient.writable.getWriter();
+    const decoder = new TextDecoder();
+    const agentConnection = new AgentSideConnection(
+      () => agent,
+      ndJsonStream(
+        new WritableStream<Uint8Array>({
+          async write(chunk) {
+            await agentOutput.write(chunk);
+            if (options.closeAfterPromptResponse && decoder.decode(chunk).includes("stopReason")) {
+              await agentOutput.close();
+            }
+          },
+        }),
+        clientToAgent.readable,
+      ),
+    );
+    const connection = new ClientSideConnection(
+      () => ({
+        async requestPermission() {
+          return { outcome: { outcome: "cancelled" } };
+        },
+        async sessionUpdate() {},
+      }),
+      ndJsonStream(clientToAgent.writable, agentToClient.readable),
+    );
+    await connection.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: {},
+      clientInfo: { name: "Paseo test", version: "dev" },
+    });
+    const { sessionId } = await connection.newSession({
+      cwd: "/tmp/paseo-acp-test",
+      mcpServers: [],
+    });
+    return {
+      agentConnection,
+      connection,
+      sessionId,
+      closeTransport: () => agentOutput.close(),
+    };
+  }
+
+  test("startTurn fails instead of hanging when the ACP connection has closed", async () => {
+    const agent = await connectInMemoryACPAgent(
+      fakeACPAgent(async () => ({ stopReason: "end_turn" })),
+    );
+    const session = createSession();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    asInternals<ACPSessionInternals>(session).sessionId = agent.sessionId;
+    asInternals<ACPSessionInternals>(session).connection = agent.connection;
+
+    await agent.closeTransport();
+    await agent.connection.closed;
+
+    await expect(session.startTurn("second")).rejects.toThrow("ACP agent disconnected");
+    expect(events.some((event) => event.type === "turn_started")).toBe(false);
+    expect(asInternals<ACPSessionInternals>(session).activeForegroundTurnId).toBeNull();
+  }, 2_000);
+
+  test("a prompt whose ACP transport closes mid-turn fails the turn", async () => {
+    let promptReceived!: () => void;
+    const received = new Promise<void>((resolve) => {
+      promptReceived = resolve;
+    });
+    const agent = await connectInMemoryACPAgent(
+      fakeACPAgent(() => {
+        promptReceived();
+        return new Promise(() => {});
+      }),
+    );
+    const session = createSession();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    asInternals<ACPSessionInternals>(session).sessionId = agent.sessionId;
+    asInternals<ACPSessionInternals>(session).connection = agent.connection;
+
+    const { turnId } = await session.startTurn("hello");
+    await received;
+    await agent.closeTransport();
+
+    await vi.waitFor(
+      () =>
+        expect(terminalEvents(events)).toEqual([
+          expect.objectContaining({
+            type: "turn_failed",
+            turnId,
+            error: "ACP agent disconnected",
+          }),
+        ]),
+      { timeout: 1_000 },
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(terminalEvents(events)).toHaveLength(1);
+    expect(asInternals<ACPSessionInternals>(session).activeForegroundTurnId).toBeNull();
+  }, 3_000);
+
+  test("a turn answered just before its ACP transport closes still completes", async () => {
+    const agent = await connectInMemoryACPAgent(
+      fakeACPAgent(async () => ({ stopReason: "end_turn" })),
+      { closeAfterPromptResponse: true },
+    );
+    const session = createSession();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    asInternals<ACPSessionInternals>(session).sessionId = agent.sessionId;
+    asInternals<ACPSessionInternals>(session).connection = agent.connection;
+
+    const { turnId } = await session.startTurn("hello");
+    await agent.connection.closed;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(terminalEvents(events)).toEqual([
+      expect.objectContaining({ type: "turn_completed", turnId }),
+    ]);
+  }, 3_000);
 });
 
 interface ACPCloseInternals {
@@ -3931,7 +4300,7 @@ describe("ACPAgentClient probe cleanup", () => {
       terminateProcess: terminator.terminate,
     });
 
-    await client.listFeatures({ provider: "copilot", cwd: "/tmp/acp-features" });
+    await client.listControls({ provider: "copilot", cwd: "/tmp/acp-features" });
 
     expect(closeSession).toHaveBeenCalledWith({ sessionId: "feature-probe-session" });
     expect(terminator.terminated).toContain(child);
@@ -4424,6 +4793,109 @@ describe("ACPAgentSession close() with an unresponsive provider", () => {
   }, 15_000);
 });
 
+const EXITING_ACP_AGENT = `
+import { Readable, Writable } from "node:stream";
+const { AgentSideConnection, PROTOCOL_VERSION, ndJsonStream } = await import(process.env.ACP_SDK_URL);
+new AgentSideConnection(
+  () => ({
+    async initialize() {
+      return { protocolVersion: PROTOCOL_VERSION, agentCapabilities: {} };
+    },
+    async newSession() {
+      return { sessionId: "exiting-session" };
+    },
+    async authenticate() {},
+    async cancel() {},
+    async prompt({ prompt }) {
+      if (prompt[0]?.text === "crash") {
+        process.stderr.write("fixture crash\\n");
+        process.exit(3);
+      }
+      setTimeout(() => process.exit(0), 100);
+      return { stopReason: "end_turn" };
+    },
+  }),
+  ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin)),
+);
+`;
+
+describe("ACPAgentSession after its provider process exits", () => {
+  let dir: string | null = null;
+  let session: ACPAgentSession | null = null;
+
+  afterEach(async () => {
+    await session?.close();
+    session = null;
+    if (dir) await rm(dir, { recursive: true, force: true });
+    dir = null;
+  });
+
+  async function startExitingProvider(): Promise<ACPAgentSession> {
+    dir = await mkdtemp(path.join(tmpdir(), "paseo-acp-exiting-"));
+    const agentScript = path.join(dir, "agent.mjs");
+    await writeFile(agentScript, EXITING_ACP_AGENT);
+    session = new ACPAgentSession(
+      { provider: "exiting-acp", cwd: dir },
+      {
+        provider: "exiting-acp",
+        logger: createTestLogger(),
+        defaultCommand: [process.execPath, agentScript],
+        defaultModes: [],
+        capabilities: { supportsStreaming: true, supportsSessionPersistence: true },
+        launchEnv: {
+          ACP_SDK_URL: pathToFileURL(
+            createRequire(import.meta.url).resolve("@agentclientprotocol/sdk"),
+          ).href,
+        },
+      },
+    );
+    await session.initializeNewSession();
+    return session;
+  }
+
+  test("startTurn after the provider exits while idle fails instead of hanging", async () => {
+    const provider = await startExitingProvider();
+    const events: AgentStreamEvent[] = [];
+    provider.subscribe((event) => events.push(event));
+    const internals = asInternals<{ child: ChildProcess; connection: ClientSideConnection }>(
+      provider,
+    );
+    const { child, connection } = internals;
+
+    const { turnId } = await provider.startTurn("first");
+    await vi.waitFor(() =>
+      expect(terminalEvents(events)).toEqual([
+        expect.objectContaining({ type: "turn_completed", turnId }),
+      ]),
+    );
+    if (child.exitCode === null) await once(child, "exit");
+    await connection.closed;
+
+    await expect(provider.startTurn("second")).rejects.toThrow(
+      "ACP agent disconnected (exit code 0)",
+    );
+    expect(terminalEvents(events)).toHaveLength(1);
+  }, 10_000);
+
+  test("a provider that crashes mid-turn still reports its exit status", async () => {
+    const provider = await startExitingProvider();
+    const events: AgentStreamEvent[] = [];
+    provider.subscribe((event) => events.push(event));
+
+    const { turnId } = await provider.startTurn("crash");
+    await vi.waitFor(() => expect(terminalEvents(events)).toHaveLength(1), { timeout: 3_000 });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(terminalEvents(events)).toEqual([
+      expect.objectContaining({
+        type: "turn_failed",
+        turnId,
+        error: "ACP agent exited unexpectedly (3)",
+      }),
+    ]);
+  }, 10_000);
+});
+
 // An ACP agent that advertises two models (or none, with ACP_ADVERTISE_MODELS=none) but,
 // like Cline, runs any model id it is given.
 const PERMISSIVE_MODEL_ACP_AGENT = `
diff --git a/packages/server/src/server/agent/providers/acp-agent.ts b/packages/server/src/server/agent/providers/acp-agent.ts
index e26b6e4ade..33664f7ad8 100644
--- a/packages/server/src/server/agent/providers/acp-agent.ts
+++ b/packages/server/src/server/agent/providers/acp-agent.ts
@@ -1,10 +1,15 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { ACPProviderOptionsSchema } from "./acp-options.js";
+import { applyProviderOptionsPatch } from "../option-controls.js";
+import { assertChangesAreLive } from "../provider-options.js";
 import { type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { once } from "node:events";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { Readable, Writable } from "node:stream";
+import { setImmediate } from "node:timers/promises";
 
 import { terminateWithTreeKill } from "../../../utils/tree-kill.js";
 import type { ProcessTerminator } from "../../../utils/tree-kill.js";
@@ -65,7 +70,8 @@ import {
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateConfigUnattendedInput,
-  type AgentFeature,
+  type AgentDraftControls,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -120,6 +126,7 @@ import {
 } from "../provider-launch-config.js";
 import { renderPromptAttachmentAsText } from "../prompt-attachments.js";
 import { appendOrReplaceGrowingAssistantMessage, runProviderTurn } from "./provider-runner.js";
+import { resolveResumeProcessCwd } from "./resume-process-cwd.js";
 import {
   buildStringCommandShellInvocation,
   createStringCommandShellEnvOverlay,
@@ -142,27 +149,37 @@ function assertChildWithPipes(
   }
 }
 
-// Node reports a failed spawn (missing binary or missing cwd) as a child
-// `error` event; without a listener it becomes an uncaught exception.
-function rejectOnSpawnError(child: ChildProcess, stderrChunks: string[]): Promise<never> {
+// Watch process failures as well as spawn errors: the SDK leaves initialize
+// pending when the child exits without replying. `close` waits for stderr to
+// drain, so the failure includes the launcher's diagnostic.
+function rejectOnProcessFailure(child: ChildProcess, stderrChunks: string[]): Promise<never> {
   return new Promise<never>((_, reject) => {
     child.once("error", (error) => {
       const stderr = stderrChunks.join("").trim();
       reject(new Error(stderr ? `${String(error)}\n${stderr}` : String(error)));
     });
+    child.once("close", (code, signal) => {
+      const stderr = stderrChunks.join("").trim();
+      const status = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+      reject(
+        new Error(
+          `ACP agent process exited before initialization completed (${status})${
+            stderr ? `\n${stderr}` : ""
+          }`,
+        ),
+      );
+    });
   });
 }
 
-async function isDirectory(target: string): Promise<boolean> {
-  try {
-    return (await fs.stat(target)).isDirectory();
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ENOENT" || code === "ENOTDIR") {
-      return false;
-    }
-    throw error;
+function describeACPDisconnect(child: ChildProcess | null): string {
+  if (child?.signalCode) {
+    return `ACP agent disconnected (signal ${child.signalCode})`;
   }
+  if (child?.exitCode != null) {
+    return `ACP agent disconnected (exit code ${child.exitCode})`;
+  }
+  return "ACP agent disconnected";
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -322,9 +339,18 @@ const ACP_PROBE_CLOSE_TIMEOUT_MS = 2_000;
 // request when the provider never answers, so these calls must be bounded
 // or the provider process is never terminated.
 const ACP_CLOSE_REQUEST_TIMEOUT_MS = 2_000;
+const ACP_DISCONNECT_EXIT_GRACE_MS = 1_000;
 const ACP_IMPORT_HISTORY_LOAD_TIMEOUT_MS = 30_000;
 const ACP_IMPORT_HISTORY_BUDGET_MS = 60_000;
 
+/**
+ * An ACP agent publishes its slash-command inventory incrementally. Wait this
+ * long without another batch before treating the inventory as complete. MiniMax
+ * publishes its skills about 350ms after its built-in commands.
+ */
+const COMMAND_INVENTORY_QUIET_MS = 600;
+const COMMAND_INVENTORY_POLL_MS = 25;
+
 function summarizeMalformedACPStdoutError(error: unknown): { type: string; message: string } {
   return {
     type: error instanceof Error ? error.name : typeof error,
@@ -542,7 +568,7 @@ interface ACPProcessTransport {
   connection: ClientSideConnection;
   stderrChunks: string[];
   spawnReady: Promise<void>;
-  spawnError: Promise<never>;
+  processError: Promise<never>;
 }
 
 interface ACPImportPromptPreviews {
@@ -634,6 +660,7 @@ interface PendingPermission {
   resolve: (response: RequestPermissionResponse) => void;
   reject: (error: Error) => void;
   turnId: string | null;
+  toolCallId: string;
 }
 
 interface PendingUserMessage {
@@ -839,10 +866,10 @@ export function deriveModelDefinitionsFromACP(
   }));
 }
 
-export function deriveFeaturesFromACP(
+export function deriveControlsFromACP(
   configOptions: SessionConfigOption[] | null | undefined,
   featureOptions: ACPConfigFeatureOption[],
-): AgentFeature[] {
+): AgentOptionControl[] {
   return featureOptions.flatMap((featureOption) => {
     const option = findSelectConfigFeatureOption(configOptions, featureOption);
     if (!option) {
@@ -852,42 +879,55 @@ export function deriveFeaturesFromACP(
     return [
       {
         type: "select",
-        id: featureOption.id,
+        key: featureOption.id,
         label: featureOption.label,
         description: featureOption.description,
         tooltip: featureOption.tooltip,
         icon: featureOption.icon,
-        value: option.currentValue ?? null,
-        options: deriveConfigFeatureSelectOptions(option, featureOption),
+        choices: deriveConfigFeatureSelectOptions(option, featureOption).map((choice) => ({
+          value: choice.id,
+          label: choice.label,
+          description: choice.description,
+        })),
       },
     ];
   });
 }
 
-function isACPAutoAcceptEnabled(config: AgentSessionConfig): boolean {
-  return config.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true;
+/** The feature selects as the agent reports them, keyed by feature id. */
+function featureValuesFromACP(
+  configOptions: SessionConfigOption[] | null | undefined,
+  featureOptions: ACPConfigFeatureOption[],
+): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const featureOption of featureOptions) {
+    const current = findSelectConfigFeatureOption(configOptions, featureOption)?.currentValue;
+    if (current != null) values[featureOption.id] = current;
+  }
+  return values;
 }
 
-function buildACPAutoAcceptFeature(config: AgentSessionConfig): AgentFeature {
-  return {
-    type: "toggle",
-    id: ACP_AUTO_ACCEPT_FEATURE_ID,
-    label: "Auto Accept",
-    description: "Automatically approves ACP permission prompts.",
-    tooltip: "Auto accept permission prompts",
-    icon: "shield-check",
-    value: isACPAutoAcceptEnabled(config),
-  };
+function isACPAutoAcceptEnabled(config: AgentSessionConfig): boolean {
+  return config.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true;
 }
 
+const ACP_AUTO_ACCEPT_CONTROL: AgentOptionControl = {
+  type: "toggle",
+  key: ACP_AUTO_ACCEPT_FEATURE_ID,
+  label: "Auto Accept",
+  description: "Automatically approves ACP permission prompts.",
+  tooltip: "Auto accept permission prompts",
+  icon: "shield-check",
+};
+
 function resolveACPCreateConfig(
   input: ResolveAgentCreateConfigInput,
 ): ResolveAgentCreateConfigResult {
   const isUnattendedCreate = input.unattended || input.parent?.isUnattended === true;
-  const featureValues =
-    isUnattendedCreate && input.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === undefined
-      ? { ...input.featureValues, [ACP_AUTO_ACCEPT_FEATURE_ID]: true }
-      : input.featureValues;
+  const providerOptions =
+    isUnattendedCreate && input.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === undefined
+      ? { ...input.providerOptions, [ACP_AUTO_ACCEPT_FEATURE_ID]: true }
+      : input.providerOptions;
 
   if (
     input.requestedMode === undefined &&
@@ -895,22 +935,16 @@ function resolveACPCreateConfig(
     input.parent !== null &&
     input.parent.provider !== input.provider
   ) {
-    return { modeId: undefined, featureValues };
+    return { modeId: undefined, providerOptions };
   }
 
-  return resolveDefaultAgentCreateConfig({ ...input, featureValues });
+  return resolveDefaultAgentCreateConfig({ ...input, providerOptions });
 }
 
 function isACPCreateConfigUnattended(input: AgentCreateConfigUnattendedInput): boolean {
   return (
     isDefaultAgentCreateConfigUnattended(input) ||
-    input.config.featureValues?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true ||
-    input.features?.some(
-      (feature) =>
-        feature.id === ACP_AUTO_ACCEPT_FEATURE_ID &&
-        feature.type === "toggle" &&
-        feature.value === true,
-    ) === true
+    input.config.providerOptions?.[ACP_AUTO_ACCEPT_FEATURE_ID] === true
   );
 }
 
@@ -1189,10 +1223,10 @@ export class ACPAgentClient implements AgentClient {
     }
   }
 
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
-    const autoAcceptFeature = buildACPAutoAcceptFeature(config);
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    const options = config.providerOptions ?? {};
     if (this.configFeatureOptions.length === 0) {
-      return [autoAcceptFeature];
+      return { controls: [ACP_AUTO_ACCEPT_CONTROL], options };
     }
 
     this.assertProvider(config);
@@ -1207,10 +1241,18 @@ export class ACPAgentClient implements AgentClient {
       );
       probeSessionId = response.sessionId;
       const transformed = this.transformSessionResponse(response);
-      return [
-        autoAcceptFeature,
-        ...deriveFeaturesFromACP(transformed.configOptions, this.configFeatureOptions),
-      ];
+      return {
+        controls: [
+          ACP_AUTO_ACCEPT_CONTROL,
+          ...deriveControlsFromACP(transformed.configOptions, this.configFeatureOptions),
+        ],
+        // The probe opened with the agent's own defaults, which a session would overwrite with
+        // the set values, so those stand over the probe's reading.
+        options: {
+          ...featureValuesFromACP(transformed.configOptions, this.configFeatureOptions),
+          ...options,
+        },
+      };
     } finally {
       await this.closeProbe(probe, probeSessionId);
     }
@@ -1380,6 +1422,7 @@ export class ACPAgentClient implements AgentClient {
       client?: ACPClient;
     },
   ): Promise<SpawnedACPProcess> {
+    const configuredOptions = ACPProviderOptionsSchema.parse(options?.providerOptions ?? {});
     const transport = await this.spawnTransport(launchEnv, options?.client);
     const probe: UninitializedACPProcess = {
       child: transport.child,
@@ -1391,7 +1434,7 @@ export class ACPAgentClient implements AgentClient {
       const initialize = await this.initializeTransport(
         transport,
         options?.initializeTimeoutMs,
-        options?.providerOptions,
+        configuredOptions.clientCapabilities,
       );
       const initializedProbe: SpawnedACPProcess = {
         ...probe,
@@ -1425,7 +1468,7 @@ export class ACPAgentClient implements AgentClient {
       stderrChunks.push(chunk.toString());
     });
 
-    const spawnErrorPromise = rejectOnSpawnError(child, stderrChunks);
+    const processErrorPromise = rejectOnProcessFailure(child, stderrChunks);
     const spawnReadyPromise = new Promise<void>((resolve) => {
       child.once("spawn", () => {
         resolve();
@@ -1444,16 +1487,15 @@ export class ACPAgentClient implements AgentClient {
       connection,
       stderrChunks,
       spawnReady: spawnReadyPromise,
-      spawnError: spawnErrorPromise,
+      processError: processErrorPromise,
     };
   }
 
   protected async initializeTransport(
     transport: ACPProcessTransport,
     initializeTimeoutMs?: number,
-    providerOptions?: Record<string, unknown>,
+    clientCapabilities?: ACPClientCapabilities,
   ): Promise<InitializeResponse> {
-    const configuredOptions = ACPProviderOptionsSchema.parse(providerOptions ?? {});
     let timeout: ReturnType<typeof setTimeout> | null = null;
     const initializeTimeoutPromise = initializeTimeoutMs
       ? new Promise<never>((_, reject) => {
@@ -1470,11 +1512,11 @@ export class ACPAgentClient implements AgentClient {
             protocolVersion: PROTOCOL_VERSION,
             clientCapabilities: buildACPClientCapabilities(
               this.clientCapabilityMeta,
-              configuredOptions.clientCapabilities ?? this.clientCapabilities,
+              clientCapabilities ?? this.clientCapabilities,
             ),
             clientInfo: { name: "Paseo", version: "dev" },
           }),
-          transport.spawnError,
+          transport.processError,
           ...(initializeTimeoutPromise ? [initializeTimeoutPromise] : []),
         ]),
       );
@@ -1555,7 +1597,7 @@ export class ACPAgentClient implements AgentClient {
       try {
         transport = await this.spawnTransport(PROBE_ENV);
         await withTimeout(
-          Promise.race([transport.spawnReady, transport.spawnError]),
+          Promise.race([transport.spawnReady, transport.processError]),
           phaseTimeoutMs,
           `ACP spawn timed out after ${phaseTimeoutMs}ms`,
         );
@@ -1746,14 +1788,20 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   private readonly earlySessionUpdates: SessionNotification[] = [];
   private currentMode: string | null = null;
   private availableModes: AgentMode[];
+  private sessionModeState: SessionStateResponse["modes"] = null;
   private currentModel: string | null = null;
   private availableModels: AvailableACPModel[] | null = null;
   private thinkingOptionId: string | null = null;
   private currentTitle: string | null = null;
   private lastActivityAt: string | null = null;
   private configOptions: SessionConfigOption[] = [];
+  /** How the opened session differs from the options it was given. */
+  openOptionsPatch: Record<string, unknown> = {};
+  /** Selects the provider moves while Paseo is opening or applying options belong to that result, not to events. */
+  private optionsTransactionDepth = 0;
   private cachedCommands: AgentSlashCommand[] = [];
-  private commandsReadyDeferred: { promise: Promise<void>; resolve: () => void } | null = null;
+  /** When the last command batch arrived; null while nothing has been published. */
+  private commandsUpdatedAt: number | null = null;
   private commandsReadySettled = false;
   private waitForInitialCommands: boolean;
   private initialCommandsWaitTimeoutMs: number;
@@ -1967,6 +2015,9 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     if (!this.connection || !this.sessionId) {
       throw new Error(`${this.provider} session is not initialized`);
     }
+    if (this.connection.signal.aborted) {
+      throw new Error(describeACPDisconnect(this.child));
+    }
     if (this.activeForegroundTurnId) {
       throw new Error("A foreground turn is already active");
     }
@@ -1981,7 +2032,11 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     this.pushEvent({ type: "turn_started", provider: this.provider, turnId });
     this.emitSubmittedUserMessage(prompt, messageId, turnId, options?.clientMessageId);
 
-    void this.connection
+    const connection = this.connection;
+    const child = this.child;
+    const failOnDisconnect = () => void this.failDisconnectedTurn(turnId, child);
+    connection.signal.addEventListener("abort", failOnDisconnect, { once: true });
+    void connection
       .prompt({
         sessionId: this.sessionId,
         messageId,
@@ -2001,11 +2056,35 @@ export class ACPAgentSession implements AgentSession, ACPClient {
           diagnostic: this.collectDiagnostic(summary.diagnostic ?? summary.message),
           turnId,
         });
-      });
+      })
+      .finally(() => connection.signal.removeEventListener("abort", failOnDisconnect));
 
     return { turnId };
   }
 
+  // The SDK aborts the connection without rejecting the pending prompt, and before the child's
+  // exit event, so wait for the exit status before failing the turn.
+  private async failDisconnectedTurn(turnId: string, child: ChildProcess | null): Promise<void> {
+    await setImmediate();
+    if (child && child.exitCode === null && child.signalCode === null) {
+      await once(child, "exit", {
+        signal: AbortSignal.timeout(ACP_DISCONNECT_EXIT_GRACE_MS),
+      }).catch(() => undefined);
+    }
+    if (this.closed || this.activeForegroundTurnId !== turnId) {
+      return;
+    }
+    this.synthesizeCanceledToolCalls();
+    const error = describeACPDisconnect(child);
+    this.finishTurn({
+      type: "turn_failed",
+      provider: this.provider,
+      error,
+      diagnostic: this.collectDiagnostic(error),
+      turnId,
+    });
+  }
+
   subscribe(callback: (event: AgentStreamEvent) => void): () => void {
     this.subscribers.add(callback);
     if (this.sessionId) {
@@ -2044,65 +2123,46 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     return this.currentMode;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
     return [
-      buildACPAutoAcceptFeature(this.config),
-      ...deriveFeaturesFromACP(this.configOptions, this.configFeatureOptions),
+      ACP_AUTO_ACCEPT_CONTROL,
+      ...deriveControlsFromACP(this.configOptions, this.configFeatureOptions),
     ];
   }
 
-  private ensureCommandsReadyDeferred(): void {
-    if (this.commandsReadyDeferred || this.commandsReadySettled || this.cachedCommands.length > 0) {
-      return;
-    }
-
-    let resolve!: () => void;
-    const promise = new Promise<void>((r) => {
-      resolve = r;
-    });
-    this.commandsReadyDeferred = { promise, resolve };
-  }
-
   private settleCommandsReady(): void {
-    if (this.commandsReadySettled) {
-      return;
-    }
     this.commandsReadySettled = true;
-    this.commandsReadyDeferred?.resolve();
-    this.commandsReadyDeferred = null;
   }
 
-  private async waitForCommandsReady(): Promise<void> {
-    const deferred = this.commandsReadyDeferred;
-    if (!deferred) {
-      return;
-    }
-
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    try {
-      await Promise.race([
-        deferred.promise,
-        new Promise<void>((resolve) => {
-          timer = setTimeout(resolve, this.initialCommandsWaitTimeoutMs);
-        }),
-      ]);
-    } finally {
-      if (timer) {
-        clearTimeout(timer);
-      }
+  /**
+   * Providers publish their command inventory incrementally. MiniMax sends its
+   * built-in commands twice, then a third batch about 350ms later that merges in
+   * every discovered skill. Returning after the first batch loses the skills.
+   *
+   * Wait for the inventory to go quiet rather than for the first batch. The
+   * quiet window must exceed the gap between a provider's own batches; 600ms
+   * covers MiniMax with margin. `initialCommandsWaitTimeoutMs` still bounds the
+   * whole wait for providers that publish once or never publish at all.
+   */
+  private async waitForCommandsToSettle(): Promise<void> {
+    const deadline = Date.now() + this.initialCommandsWaitTimeoutMs;
+    while (!this.commandsReadySettled && !this.closed) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return;
+      const quietFor = this.commandsUpdatedAt === null ? 0 : Date.now() - this.commandsUpdatedAt;
+      if (quietFor >= COMMAND_INVENTORY_QUIET_MS) return;
+      await new Promise<void>((resolve) =>
+        setTimeout(resolve, Math.min(remaining, COMMAND_INVENTORY_POLL_MS)),
+      );
     }
   }
 
   async listCommands(): Promise<AgentSlashCommand[]> {
-    if (this.cachedCommands.length > 0) {
-      return this.cachedCommands;
-    }
-    if (!this.waitForInitialCommands || this.closed) {
+    if (this.commandsReadySettled || this.closed || !this.waitForInitialCommands) {
       return this.cachedCommands;
     }
 
-    this.ensureCommandsReadyDeferred();
-    await this.waitForCommandsReady();
+    await this.waitForCommandsToSettle();
     this.settleCommandsReady();
     return this.cachedCommands;
   }
@@ -2112,11 +2172,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       throw new Error("ACP session not initialized");
     }
 
-    const selection = resolveACPModeSelection({
-      modeId,
-      availableModes: this.availableModes,
-      configOptions: this.configOptions,
-    });
+    const selection = this.resolveModeSelection(modeId);
     await this.setModeWithSelection({ modeId, selection });
   }
 
@@ -2142,7 +2198,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       if (providerResult.configOptions) {
         this.configOptions = this.transformConfigOptions(providerResult.configOptions);
       }
-      this.availableModes = deriveModesFromACP(this.defaultModes, null, this.configOptions).modes;
+      this.availableModes = this.modesFromConfig().modes;
       this.pushEvent({
         type: "mode_changed",
         provider: this.provider,
@@ -2207,6 +2263,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
 
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2221,7 +2278,8 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: modeId,
       label: "mode",
     });
-    this.availableModes = deriveModesFromACP(this.defaultModes, null, this.configOptions).modes;
+    this.reportFeatureChanges(before);
+    this.availableModes = this.modesFromConfig().modes;
     this.pushEvent({
       type: "mode_changed",
       provider: this.provider,
@@ -2248,16 +2306,17 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     };
   }
 
-  async setModel(modelId: string | null): Promise<void> {
+  async setModel(modelId: string | null): Promise<{ model: string | null }> {
     if (!this.connection || !this.sessionId) {
       throw new Error("ACP session not initialized");
     }
     if (!modelId) {
       this.currentModel = null;
-      return;
+      return { model: this.currentModel };
     }
 
     await this.setModelWithSelection({ modelId, selection: this.resolveModelSelection(modelId) });
+    return { model: this.currentModel };
   }
 
   private resolveModelSelection(modelId: string): ACPModelSelection {
@@ -2332,6 +2391,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
 
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2346,6 +2406,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: modelId,
       label: "model",
     });
+    this.reportFeatureChanges(before);
     this.pushEvent({
       type: "model_changed",
       provider: this.provider,
@@ -2383,6 +2444,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       throw new Error(`${this.provider} does not expose ACP thought-level selection`);
     }
     const { connection, sessionId } = this;
+    const before = this.featureValues();
     const response = await this.runACPRequest(() =>
       connection.setSessionConfigOption({
         sessionId,
@@ -2397,6 +2459,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       requestedValue: thinkingOptionId,
       label: "thought-level",
     });
+    this.reportFeatureChanges(before);
     this.pushEvent({
       type: "thinking_option_changed",
       provider: this.provider,
@@ -2404,14 +2467,91 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     });
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
+  /**
+   * Applies only the options the patch sets; returns the selects that ended up different.
+   * Provider notifications that arrive meanwhile are part of that result. When a write is
+   * rejected, what the provider moved is reported as an event, since nothing is stored.
+   * The agent manager sends one apply at a time per session.
+   */
+  async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+    assertChangesAreLive({
+      provider: this.config.provider,
+      patch: options,
+      current: this.config.providerOptions,
+      live: [ACP_AUTO_ACCEPT_FEATURE_ID, ...this.configFeatureOptions.map(({ id }) => id)],
+    });
+    ACPProviderOptionsSchema.parse(
+      applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+    );
+    const before = this.featureValues();
+    const requested: Record<string, unknown> = {};
+    try {
+      await this.inOptionsTransaction(async () => {
+        for (const [id, value] of Object.entries(options)) {
+          const featureOption = this.configFeatureOptions.find((candidate) => candidate.id === id);
+          if (!featureOption) continue;
+          // A removal asks for the select's empty choice; a provider without one rejects it. The
+          // choice it lands on is reported against the `null` that was asked, so the options
+          // hold the value the session runs with.
+          requested[id] = value;
+          const option = findSelectConfigFeatureOption(this.configOptions, featureOption);
+          if (!option || (value ?? "") !== option.currentValue) {
+            await this.setConfigFeature(id, value);
+          }
+        }
+      });
+    } catch (error) {
+      this.reportFeatureChanges(before);
+      throw error;
+    }
+    // Auto Accept is Paseo's own setting, so it changes only once every write has been accepted.
+    if (ACP_AUTO_ACCEPT_FEATURE_ID in options) {
+      this.config.providerOptions = {
+        ...this.config.providerOptions,
+        [ACP_AUTO_ACCEPT_FEATURE_ID]: options[ACP_AUTO_ACCEPT_FEATURE_ID] === true,
+      };
+    }
+    return this.featureDifferences({ ...before, ...requested });
+  }
+
+  private async inOptionsTransaction<T>(run: () => Promise<T>): Promise<T> {
+    this.optionsTransactionDepth += 1;
+    try {
+      return await run();
+    } finally {
+      this.optionsTransactionDepth -= 1;
+    }
+  }
+
+  /** The selects as the provider reports them now. */
+  private featureValues(): Record<string, string> {
+    return featureValuesFromACP(this.configOptions, this.configFeatureOptions);
+  }
+
+  /** The selects whose value is not what `expected` says, including ones it does not name. */
+  private featureDifferences(expected: Record<string, unknown>): Record<string, string> {
+    return Object.fromEntries(
+      Object.entries(this.featureValues()).filter(([id, value]) => expected[id] !== value),
+    );
+  }
+
+  /** Reports the selects the provider moved on its own, compared with their values `before`. */
+  private reportFeatureChanges(before: Record<string, string>): void {
+    if (this.optionsTransactionDepth > 0) return;
+    const patch = this.featureDifferences(before);
+    if (Object.keys(patch).length > 0) {
+      this.pushEvent({ type: "options_changed", provider: this.provider, patch });
+    }
+  }
+
+  private async setConfigFeature(featureId: string, value: unknown): Promise<void> {
     if (!this.connection || !this.sessionId) {
       throw new Error("ACP session not initialized");
     }
 
     if (featureId === ACP_AUTO_ACCEPT_FEATURE_ID) {
-      this.config.featureValues = {
-        ...this.config.featureValues,
+      this.config.providerOptions = {
+        ...this.config.providerOptions,
         [ACP_AUTO_ACCEPT_FEATURE_ID]: value === true,
       };
       return;
@@ -2443,14 +2583,13 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         value: requestedValue,
       }),
     );
-    const currentValue = this.applyConfigOptionResponse({
+    this.applyConfigOptionResponse({
       response,
       configId: option.id,
       category: featureOption.category,
       requestedValue,
       label: featureOption.label,
     });
-    this.config.featureValues = { ...this.config.featureValues, [featureId]: currentValue };
   }
 
   private applyConfigOptionResponse({
@@ -2653,6 +2792,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         resolve,
         reject,
         turnId: this.activeForegroundTurnId,
+        toolCallId: params.toolCall.toolCallId,
       });
     });
 
@@ -2733,14 +2873,12 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
   }
 
-  // Cache an asynchronously-delivered slash-command batch and unblock any
-  // listCommands() call that is waiting on the initial batch. Used when a
-  // provider supplies an extensionCommandsParser whose result arrives after
-  // session/new (e.g. via a vendor extension notification). The ready gate is
-  // always settled — even for an empty batch — so a provider that legitimately
-  // reports no commands does not leave listCommands() blocked for the full
-  // initial-commands timeout. An optional sessionId scopes the batch to this
-  // session; notifications addressed to a different session are ignored.
+  // Cache an asynchronously-delivered slash-command batch from a provider that
+  // supplies an extensionCommandsParser (e.g. a vendor extension notification).
+  // An empty batch is the provider saying it has no commands, so it settles the
+  // waiter immediately instead of letting it wait out the quiet window. An
+  // optional sessionId scopes the batch to this session; notifications
+  // addressed to a different session are ignored.
   private applyResolvedCommands(
     commands: AgentSlashCommand[],
     options?: { sessionId?: string },
@@ -2754,7 +2892,13 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     }
 
     if (commands.length > 0) {
+      this.commandsUpdatedAt = Date.now();
       this.cachedCommands = commands;
+      // A non-empty batch may be followed by more. Let the quiet window decide
+      // when the inventory is complete rather than settling here; an empty
+      // batch is the provider saying it has nothing, which must still unblock
+      // the waiter immediately.
+      return;
     }
     this.settleCommandsReady();
   }
@@ -2877,11 +3021,8 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   // Loading an archived agent's history runs nothing in its working directory, which
   // may have been removed with its worktree. session/load still names the original
   // directory; only the process starts from the home directory.
-  private async resolveProcessCwd(): Promise<string> {
-    if (this.resumePurpose !== "history" || (await isDirectory(this.config.cwd))) {
-      return this.config.cwd;
-    }
-    return homedir();
+  private resolveProcessCwd(): Promise<string> {
+    return resolveResumeProcessCwd(this.config.cwd, this.resumePurpose);
   }
 
   private async spawnProcess(): Promise<SpawnedACPProcess> {
@@ -2910,7 +3051,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     child.stderr.on("data", (chunk: Buffer | string) => {
       stderrChunks.push(chunk.toString());
     });
-    const spawnError = rejectOnSpawnError(child, stderrChunks);
+    const processError = rejectOnProcessFailure(child, stderrChunks);
     child.once("exit", (code, signal) => {
       if (this.closed || this.historyRuntimeReleased) {
         return;
@@ -2947,7 +3088,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
           ),
           clientInfo: { name: "Paseo", version: "dev" },
         }),
-        spawnError,
+        processError,
       ]),
     );
 
@@ -2972,6 +3113,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       : response;
 
     this.configOptions = this.transformConfigOptions(transformed.configOptions ?? []);
+    this.sessionModeState = transformed.modes ?? null;
 
     const modeInfo = deriveModesFromACP(this.defaultModes, transformed.modes, this.configOptions);
     this.availableModes = modeInfo.modes;
@@ -2994,14 +3136,14 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     return this.modeIdTransformer ? this.modeIdTransformer(modeId) : modeId;
   }
 
-  private async applyConfiguredOverrides(): Promise<void> {
+  private applyConfiguredOverrides(): Promise<void> {
+    return this.inOptionsTransaction(() => this.writeConfiguredOverrides());
+  }
+
+  private async writeConfiguredOverrides(): Promise<void> {
     const configuredModeId = this.config.modeId;
     if (configuredModeId && configuredModeId !== this.currentMode) {
-      const selection = resolveACPModeSelection({
-        modeId: configuredModeId,
-        availableModes: this.availableModes,
-        configOptions: this.configOptions,
-      });
+      const selection = this.resolveModeSelection(configuredModeId);
       await this.setModeWithSelection({ modeId: configuredModeId, selection });
     }
     const configuredModelId = this.config.model;
@@ -3026,13 +3168,13 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     if (this.config.thinkingOptionId && this.config.thinkingOptionId !== this.thinkingOptionId) {
       await this.setThinkingOption(this.config.thinkingOptionId);
     }
-    const configuredFeatureValues = this.config.featureValues ?? {};
+    const configuredFeatureValues = this.config.providerOptions ?? {};
     for (const featureOption of this.configFeatureOptions) {
       if (!Object.prototype.hasOwnProperty.call(configuredFeatureValues, featureOption.id)) {
         continue;
       }
       try {
-        await this.setFeature(featureOption.id, configuredFeatureValues[featureOption.id]);
+        await this.setConfigFeature(featureOption.id, configuredFeatureValues[featureOption.id]);
       } catch (error) {
         if (!this.isStaleFeatureValueError(error, featureOption.id, switchedModel)) {
           throw error;
@@ -3043,6 +3185,9 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         );
       }
     }
+    // The options are the state, so every select the session opened with is reported, including
+    // ones nobody set (a native default is stored like any other value).
+    this.openOptionsPatch = this.featureDifferences(configuredFeatureValues);
   }
 
   /**
@@ -3138,13 +3283,19 @@ export class ACPAgentSession implements AgentSession, ACPClient {
         this.handleUsageUpdate(update);
         return pendingUserEvents;
       case "available_commands_update":
+        this.commandsUpdatedAt = Date.now();
         this.cachedCommands = update.availableCommands.map((command) => ({
           name: command.name,
           description: command.description,
           argumentHint: command.input?.hint ?? "",
           kind: "command",
         }));
-        this.settleCommandsReady();
+        // An empty batch means the agent has no commands and would otherwise
+        // wait out the whole quiet window. A non-empty batch may be one of
+        // several, so completion belongs to the quiet window.
+        if (update.availableCommands.length === 0) {
+          this.settleCommandsReady();
+        }
         return pendingUserEvents;
       default:
         return pendingUserEvents;
@@ -3209,6 +3360,9 @@ export class ACPAgentSession implements AgentSession, ACPClient {
       snapshot = this.toolSnapshotTransformer(snapshot);
     }
     this.toolCalls.set(toolCallId, snapshot);
+    if (update.status === "completed" || update.status === "failed") {
+      this.cancelPendingPermissions((pending) => pending.toolCallId === toolCallId);
+    }
     return [this.wrapTimeline(mapToolSnapshotToTimeline(snapshot, this.terminalEntries))];
   }
 
@@ -3249,9 +3403,38 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     this.currentMode = this.transformModeId(update.currentModeId);
   }
 
+  private modesFromConfig() {
+    let modes = this.sessionModeState;
+    if (modes) {
+      let currentModeId = this.currentMode ?? modes.currentModeId;
+      const configMode = findSelectConfigOption({
+        configOptions: this.configOptions,
+        category: "mode",
+      });
+      // Copilot config updates name real modes; Hermes config values are a separate policy namespace.
+      if (configMode && modes.availableModes.some((mode) => mode.id === configMode.currentValue)) {
+        currentModeId = configMode.currentValue;
+      }
+      modes = { ...modes, currentModeId };
+    }
+    return deriveModesFromACP(this.defaultModes, modes, this.configOptions);
+  }
+
+  private resolveModeSelection(modeId: string): ACPModeSelection {
+    const hasSessionModes = Boolean(this.sessionModeState?.availableModes.length);
+    const modeConfig = findSelectConfigOption({
+      configOptions: this.configOptions,
+      category: "mode",
+    });
+    const configOnly = !hasSessionModes && modeConfig !== null;
+    const availableModes = configOnly ? [] : this.availableModes;
+    return resolveACPModeSelection({ modeId, availableModes, configOptions: this.configOptions });
+  }
+
   private handleConfigOptionUpdate(update: ConfigOptionUpdate): AgentStreamEvent[] {
+    const before = this.featureValues();
     this.configOptions = this.transformConfigOptions(update.configOptions);
-    const modeInfo = deriveModesFromACP(this.defaultModes, null, this.configOptions);
+    const modeInfo = this.modesFromConfig();
     const nextMode = modeInfo.currentModeId;
     const nextModel = deriveCurrentConfigValue(this.configOptions, "model");
     const nextThinkingOptionId = deriveCurrentConfigValue(this.configOptions, "thought_level");
@@ -3260,6 +3443,7 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     this.currentMode = nextMode ?? this.currentMode;
     this.currentModel = nextModel ?? this.currentModel;
     this.thinkingOptionId = nextThinkingOptionId ?? this.thinkingOptionId;
+    this.reportFeatureChanges(before);
 
     const events: AgentStreamEvent[] = [];
     if (nextMode !== null) {
@@ -3416,11 +3600,11 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     event: Extract<AgentStreamEvent, { type: "turn_completed" | "turn_failed" | "turn_canceled" }>,
   ): void {
     this.deliverTranslatedEvents(this.flushPendingUserMessage());
-    // A turn that ends without completing leaves no way to answer its open
-    // permission requests, so tell the agent they were cancelled.
-    if (event.type !== "turn_completed") {
-      this.cancelPendingPermissions();
-    }
+    // Failed and canceled turns clear every request in the manager. Answer the
+    // same set here so an outside-turn request cannot keep the provider blocked.
+    this.cancelPendingPermissions(
+      (pending) => event.type !== "turn_completed" || pending.turnId === event.turnId,
+    );
     this.activeForegroundTurnId = null;
     this.fallbackAssistantMessageId = null;
     if (this.submittedUserMessageTurnId === event.turnId) {
@@ -3429,11 +3613,21 @@ export class ACPAgentSession implements AgentSession, ACPClient {
     this.pushEvent(event);
   }
 
-  private cancelPendingPermissions(): void {
-    for (const pending of this.pendingPermissions.values()) {
+  private cancelPendingPermissions(
+    matches: (pending: PendingPermission) => boolean = () => true,
+  ): void {
+    for (const [requestId, pending] of this.pendingPermissions) {
+      if (!matches(pending)) continue;
+      this.pendingPermissions.delete(requestId);
       pending.resolve({ outcome: { outcome: "cancelled" } });
+      this.pushEvent({
+        type: "permission_resolved",
+        provider: this.provider,
+        requestId,
+        resolution: { behavior: "deny", message: "Permission request canceled" },
+        turnId: pending.turnId ?? undefined,
+      });
     }
-    this.pendingPermissions.clear();
   }
 
   private emitBootstrapThreadEvent(): void {
diff --git a/packages/server/src/server/agent/providers/acp-options.ts b/packages/server/src/server/agent/providers/acp-options.ts
index 4f75456e38..4d3a5c56d7 100644
--- a/packages/server/src/server/agent/providers/acp-options.ts
+++ b/packages/server/src/server/agent/providers/acp-options.ts
@@ -2,6 +2,8 @@ import { z } from "zod";
 
 export const ACPProviderOptionsSchema = z
   .object({
+    // Composer control: approves permission prompts without asking.
+    auto_accept: z.boolean().optional(),
     supportsMcpServers: z.boolean().optional(),
     clientCapabilities: z
       .object({
diff --git a/packages/server/src/server/agent/providers/acp-startup-exit.test.ts b/packages/server/src/server/agent/providers/acp-startup-exit.test.ts
new file mode 100644
index 0000000000..39ae6f743e
--- /dev/null
+++ b/packages/server/src/server/agent/providers/acp-startup-exit.test.ts
@@ -0,0 +1,112 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { describe, expect, test } from "vitest";
+
+import { GenericACPAgentClient } from "./generic-acp-agent.js";
+import { createTestLogger } from "../../../test-utils/test-logger.js";
+
+// Exercise the public catalog API with a real child, including stdout EOF and
+// stderr draining. No provider installation or external service is involved.
+const failingCommand: [string, ...string[]] = [
+  process.execPath,
+  "-e",
+  "process.stdin.once('data', () => { process.stderr.write('launcher failed: fixture startup error\\n'); process.exitCode = 1; process.stdin.destroy(); });",
+];
+
+describe("ACP catalog startup failures", () => {
+  test("reports a process that exits during initialize with its stderr", async () => {
+    const client = new GenericACPAgentClient({
+      logger: createTestLogger(),
+      command: failingCommand,
+    });
+    await expect(
+      client.fetchCatalog({ scope: "workspace", cwd: process.cwd(), force: true }),
+    ).rejects.toThrow(/launcher failed: fixture startup error/);
+  }, 5_000);
+
+  test("session startup reports the same process exit with its stderr", async () => {
+    const client = new GenericACPAgentClient({
+      logger: createTestLogger(),
+      command: failingCommand,
+    });
+    await expect(client.createSession({ provider: "acp", cwd: process.cwd() })).rejects.toThrow(
+      /launcher failed: fixture startup error/,
+    );
+  }, 5_000);
+
+  test("provider diagnostics report the startup exit instead of an initialize timeout", async () => {
+    const client = new GenericACPAgentClient({
+      logger: createTestLogger(),
+      command: failingCommand,
+      diagnosticPhaseTimeoutMs: 2_000,
+    });
+    const { diagnostic } = await client.getDiagnostic();
+    expect(diagnostic).toContain(
+      "ACP agent process exited before initialization completed (exit code 1)",
+    );
+    expect(diagnostic).toContain("launcher failed: fixture startup error");
+    expect(diagnostic).not.toContain("initialize timed out");
+  });
+
+  test("invalid provider options reject without crashing the host process", async () => {
+    const clientModule = new URL("./generic-acp-agent.ts", import.meta.url).href;
+    const loggerModule = new URL("../../../test-utils/test-logger.ts", import.meta.url).href;
+    const script = `
+      import { GenericACPAgentClient } from ${JSON.stringify(clientModule)};
+      import { createTestLogger } from ${JSON.stringify(loggerModule)};
+      const client = new GenericACPAgentClient({
+        logger: createTestLogger(),
+        command: [process.execPath, '-e', 'setInterval(() => {}, 1000)'],
+      });
+      try {
+        await client.fetchCatalog({
+          scope: 'workspace', cwd: process.cwd(), force: true,
+          providerOptions: { clientCapabilities: { fs: 'invalid' } },
+        });
+        throw new Error('Expected invalid options to reject');
+      } catch (error) {
+        if (error.name !== 'ZodError') throw error;
+      }
+      // Let child cleanup and Node's unhandled-rejection check complete.
+      await new Promise(resolve => setTimeout(resolve, 100));
+      console.log('host stayed alive');
+    `;
+    const result = await promisify(execFile)(
+      process.execPath,
+      ["--import", "tsx", "--input-type=module", "-e", script],
+      { timeout: 10_000 },
+    );
+    expect(result.stdout).toContain("host stayed alive");
+    expect(result.stderr).toBe("");
+  });
+
+  test("a successful catalog probe still returns its models and closes cleanly", async () => {
+    const client = new GenericACPAgentClient({
+      logger: createTestLogger(),
+      command: [
+        process.execPath,
+        "-e",
+        `
+        require('node:readline').createInterface({ input: process.stdin }).on('line', (line) => {
+          const request = JSON.parse(line);
+          const result = request.method === 'initialize'
+            ? { protocolVersion: 1, agentCapabilities: {} }
+            : { sessionId: 'fixture', models: {
+                currentModelId: 'fixture-model',
+                availableModels: [{ modelId: 'fixture-model', name: 'Fixture model' }]
+              } };
+          process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request.id, result }) + '\\n');
+        });
+      `,
+      ],
+    });
+    const catalog = await client.fetchCatalog({
+      scope: "workspace",
+      cwd: process.cwd(),
+      force: true,
+    });
+    expect(catalog.models).toEqual([
+      expect.objectContaining({ id: "fixture-model", label: "Fixture model" }),
+    ]);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts b/packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts
index 8aa15581ae..432071741f 100644
--- a/packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts
@@ -712,19 +712,36 @@ describe("background Claude subagents", () => {
 test("Claude runtime safety protects silent shells, monitors and pending completion notifications", () => {
   const safety = new ClaudeRuntimeSafety();
   const observe = (message: unknown) => safety.observe(message as SDKMessage);
-  observe({ type: "system", subtype: "init", claude_code_version: "2.1.292" });
+  expect(observe({ type: "system", subtype: "init", claude_code_version: "2.1.292" })).toEqual([]);
   expect(safety.canStopRuntime()).toBe(true);
+  expect(
+    observe({
+      type: "system",
+      subtype: "background_tasks_changed",
+      tasks: [
+        { task_id: "quiet-shell", task_type: "local_bash", description: "sleep 7200" },
+        { task_id: "monitor", task_type: "local_bash", description: "watch build" },
+        { task_id: "native-child", task_type: "local_agent", description: "research" },
+      ],
+    }),
+  ).toEqual([
+    { id: "quiet-shell", kind: "shell", description: "sleep 7200", canStop: true },
+    { id: "monitor", kind: "shell", description: "watch build", canStop: true },
+  ]);
+  expect(safety.canStopRuntime()).toBe(false);
   observe({
     type: "system",
-    subtype: "background_tasks_changed",
-    tasks: [
-      { task_id: "quiet-shell", task_type: "local_bash", description: "sleep 7200" },
-      { task_id: "monitor", task_type: "local_bash", description: "watch build" },
-      { task_id: "native-child", task_type: "local_agent", description: "research" },
-    ],
+    subtype: "task_started",
+    task_id: "monitor",
+    tool_use_id: "tool-monitor",
   });
-  expect(safety.canStopRuntime()).toBe(false);
-  observe({ type: "system", subtype: "background_tasks_changed", tasks: [] });
+  expect(
+    observe({
+      type: "assistant",
+      message: { content: [{ type: "tool_use", id: "tool-monitor", name: "Monitor" }] },
+    })?.find((item) => item.id === "monitor")?.kind,
+  ).toBe("monitor");
+  expect(observe({ type: "system", subtype: "background_tasks_changed", tasks: [] })).toEqual([]);
   expect(safety.canStopRuntime()).toBe(false);
   for (const task_id of ["quiet-shell", "monitor"])
     observe({ type: "system", subtype: "task_notification", task_id });
@@ -736,6 +753,108 @@ test("Claude runtime safety protects silent shells, monitors and pending complet
   expect(safety.canStopRuntime()).toBe(false);
   observe({ type: "system", subtype: "background_tasks_changed", tasks: [] });
   expect(safety.canStopRuntime()).toBe(true);
+  safety.retire();
+  expect(
+    observe({
+      type: "system",
+      subtype: "background_tasks_changed",
+      tasks: [{ task_id: "late", task_type: "local_bash" }],
+    }),
+  ).toBeUndefined();
+  safety.reset();
+  expect(
+    observe({
+      type: "system",
+      subtype: "background_tasks_changed",
+      tasks: [{ task_id: "new", task_type: "local_bash" }],
+    }),
+  ).toEqual([{ id: "new", kind: "shell", description: null, canStop: true }]);
+});
+
+test("emits inventory only when relevant observations change it", () => {
+  const safety = new ClaudeRuntimeSafety();
+  const observe = (message: unknown) => safety.observe(message as SDKMessage);
+  expect(observe({ type: "system", subtype: "init", claude_code_version: "2.1.292" })).toEqual([]);
+  expect(
+    observe({
+      type: "system",
+      subtype: "background_tasks_changed",
+      tasks: [{ task_id: "m", task_type: "local_bash" }],
+    }),
+  ).toEqual([{ id: "m", kind: "shell", description: null, canStop: true }]);
+  expect(
+    observe({
+      type: "system",
+      subtype: "background_tasks_changed",
+      tasks: [{ task_id: "m", task_type: "local_bash" }],
+    }),
+  ).toBeUndefined();
+  expect(
+    observe({ type: "system", subtype: "task_started", task_id: "m", tool_use_id: "tool" }),
+  ).toBeUndefined();
+  expect(
+    observe({
+      type: "assistant",
+      message: { content: [{ type: "tool_use", id: "tool", name: "Monitor" }] },
+    }),
+  ).toEqual([{ id: "m", kind: "monitor", description: null, canStop: true }]);
+  expect(
+    observe({ type: "assistant", message: { content: [{ type: "text", text: "streamed" }] } }),
+  ).toBeUndefined();
+  expect(
+    observe({ type: "system", subtype: "task_started", task_id: "m", tool_use_id: "other" }),
+  ).toEqual([{ id: "m", kind: "shell", description: null, canStop: true }]);
+});
+
+test("Claude runtime safety releases a process that has not been sent a turn", () => {
+  const safety = new ClaudeRuntimeSafety();
+  // A resumed process that only answered control requests never sends init.
+  expect(safety.canStopRuntime()).toBe(true);
+  safety.notePromptSent();
+  expect(safety.canStopRuntime()).toBe(false);
+  safety.observe({ type: "system", subtype: "init", claude_code_version: "2.1.292" } as SDKMessage);
+  expect(safety.canStopRuntime()).toBe(true);
+  safety.reset();
+  expect(safety.canStopRuntime()).toBe(true);
+  // A CLI without a roster that ran a turn may own background work.
+  safety.observe({ type: "system", subtype: "init", claude_code_version: "2.1.220" } as SDKMessage);
+  expect(safety.canStopRuntime()).toBe(false);
+  safety.retire();
+  expect(safety.canStopRuntime()).toBe(false);
+});
+
+test("Claude session started by a control request without a turn can stop its runtime", async () => {
+  let launched = 0;
+  const query = {
+    next: () => new Promise<IteratorResult<SDKMessage>>(() => {}),
+    return: async () => ({ done: true, value: undefined }),
+    close: () => {},
+    interrupt: async () => {},
+    setPermissionMode: async () => {},
+    setModel: async () => {},
+    supportedModels: async () => [],
+    supportedCommands: async () => [],
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  } as unknown as Query;
+  const session = await new ClaudeAgentClient({
+    logger: createTestLogger(),
+    resolveBinary: async () => "/test/claude/bin",
+    queryFactory: ({ prompt }) => {
+      if (typeof prompt === "string") throw new Error("Expected streaming input");
+      launched++;
+      return query;
+    },
+  }).createSession({ provider: "claude", cwd: process.cwd() });
+  try {
+    // Reopening a chat lists its commands, which launches Claude with no prompt.
+    await session.listCommands!();
+    expect(launched).toBe(1);
+    expect(await session.canStopRuntime!()).toBe(true);
+  } finally {
+    await session.close();
+  }
 });
 
 test("Claude session runtime safety observes pumped background work and autonomous replies", async () => {
diff --git a/packages/server/src/server/agent/providers/claude/agent.error-result.test.ts b/packages/server/src/server/agent/providers/claude/agent.error-result.test.ts
new file mode 100644
index 0000000000..9f8c2c5a6d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/agent.error-result.test.ts
@@ -0,0 +1,226 @@
+import { expect, test } from "vitest";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import { collectSessionTurnEvents } from "../test-utils/session-stream-adapter.js";
+import { ClaudeAgentClient } from "./agent.js";
+import type { ClaudeQueryFactory } from "./query.js";
+
+const LIMIT = "You've hit your session limit · resets 5:20pm (Asia/Singapore)";
+
+interface ScriptedTurn {
+  // An API error reply as Claude Code writes it: a synthetic assistant message with `error`.
+  errorReply?: string;
+  // Assistant text the model wrote before or after it.
+  before?: string;
+  after?: string;
+  isError: boolean;
+  subtype?:
+    | "error_max_turns"
+    | "error_during_execution"
+    | "error_max_budget_usd"
+    | "error_max_structured_output_retries";
+  usage?: {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    totalCostUsd: number;
+  };
+}
+
+// A query dependency that speaks Claude Code's stream interface, one scripted turn per prompt.
+function scriptedQuery(turns: ScriptedTurn[]): ClaudeQueryFactory {
+  return ({ prompt }) => {
+    let index = 0;
+    const assistant = (id: string, text: string, error?: string) => ({
+      type: "assistant",
+      session_id: "error-session",
+      parent_tool_use_id: null,
+      uuid: id,
+      message: {
+        id,
+        role: "assistant",
+        model: error ? "<synthetic>" : "claude-opus-5-5",
+        content: [{ type: "text", text }],
+        stop_reason: "stop_sequence",
+        usage: { input_tokens: 0, output_tokens: 0 },
+      },
+      ...(error ? { error } : {}),
+    });
+    const messages = (async function* () {
+      if (typeof prompt === "string") throw new Error("Expected streaming input");
+      for await (const _message of prompt) {
+        const turn = turns[index];
+        index += 1;
+        yield {
+          type: "system",
+          subtype: "init",
+          session_id: "error-session",
+          permissionMode: "default",
+          model: "claude-opus-5-5",
+        };
+        if (turn.before) yield assistant(`before-${index}`, turn.before);
+        if (turn.errorReply) yield assistant(`error-${index}`, turn.errorReply, "rate_limit");
+        if (turn.after) yield assistant(`after-${index}`, turn.after);
+        yield {
+          type: "result",
+          subtype: turn.subtype ?? "success",
+          session_id: "error-session",
+          duration_ms: 1,
+          duration_api_ms: 0,
+          is_error: turn.isError,
+          ...(turn.subtype ? { errors: ["Reached maximum number of turns (1)"] } : {}),
+          num_turns: 1,
+          result: turn.isError ? (turn.errorReply ?? "") : (turn.after ?? turn.errorReply ?? ""),
+          stop_reason: "stop_sequence",
+          total_cost_usd: turn.usage?.totalCostUsd ?? 0,
+          usage: {
+            input_tokens: turn.usage?.inputTokens ?? 0,
+            output_tokens: turn.usage?.outputTokens ?? 0,
+            cache_read_input_tokens: turn.usage?.cachedInputTokens ?? 0,
+          },
+          modelUsage: {},
+          permission_denials: [],
+          uuid: `result-${index}`,
+        };
+      }
+    })();
+    return Object.assign(messages, {
+      close: () => {
+        void messages.return();
+      },
+      interrupt: async () => undefined,
+      setModel: async () => undefined,
+      setPermissionMode: async () => undefined,
+      supportedModels: async () => [],
+      supportedCommands: async () => [],
+    }) as ReturnType<ClaudeQueryFactory>;
+  };
+}
+
+async function runTurns(turns: ScriptedTurn[]) {
+  const client = new ClaudeAgentClient({
+    logger: createTestLogger(),
+    queryFactory: scriptedQuery(turns),
+    resolveBinary: async () => process.execPath,
+  });
+  const session = await client.createSession({
+    provider: "claude",
+    cwd: process.cwd(),
+  });
+  try {
+    const results = [];
+    for (const [index] of turns.entries()) {
+      results.push(await collectSessionTurnEvents(session, `turn ${index + 1}`));
+    }
+    return results;
+  } finally {
+    await session.close();
+  }
+}
+
+function assistantTexts(events: Awaited<ReturnType<typeof runTurns>>[number]): string[] {
+  return events.flatMap((event) =>
+    event.type === "timeline" && event.item.type === "assistant_message" ? [event.item.text] : [],
+  );
+}
+
+function terminal(events: Awaited<ReturnType<typeof runTurns>>[number]) {
+  return events.find(
+    (event) =>
+      event.type === "turn_completed" ||
+      event.type === "turn_failed" ||
+      event.type === "turn_canceled",
+  );
+}
+
+test("a turn Claude Code ends on an API error fails with the error, shown once", async () => {
+  const [limited, overloaded, next] = await runTurns([
+    { errorReply: LIMIT, isError: true },
+    {
+      before: "Checking the deploy doc.",
+      errorReply: "API Error: 529 Overloaded",
+      isError: true,
+    },
+    { after: "Done.", isError: false },
+  ]);
+
+  expect(terminal(limited)).toMatchObject({
+    type: "turn_failed",
+    error: LIMIT,
+  });
+  expect(assistantTexts(limited)).toEqual([]);
+
+  expect(terminal(overloaded)).toMatchObject({
+    type: "turn_failed",
+    error: "API Error: 529 Overloaded",
+  });
+  expect(assistantTexts(overloaded)).toEqual(["Checking the deploy doc."]);
+
+  // The session keeps working after a failed turn.
+  expect(terminal(next)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(next)).toEqual(["Done."]);
+});
+
+test("a failed turn retains its final token counts and cost", async () => {
+  const usage = {
+    inputTokens: 120,
+    cachedInputTokens: 80,
+    outputTokens: 30,
+    totalCostUsd: 0.012,
+  };
+  const [failed] = await runTurns([
+    { before: "Checking the deploy doc.", errorReply: LIMIT, isError: true, usage },
+  ]);
+
+  expect(failed).toContainEqual(
+    expect.objectContaining({ type: "usage_updated", usage: expect.objectContaining(usage) }),
+  );
+  expect(terminal(failed)).toMatchObject({ type: "turn_failed", error: LIMIT });
+  expect(assistantTexts(failed)).toEqual(["Checking the deploy doc."]);
+});
+
+test("an error reply the turn moves past is still shown", async () => {
+  const [recovered, completed] = await runTurns([
+    {
+      errorReply: "API Error: 529 Overloaded",
+      after: "Recovered.",
+      isError: false,
+    },
+    { errorReply: LIMIT, isError: false },
+  ]);
+
+  expect(terminal(recovered)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(recovered)).toEqual(["API Error: 529 Overloaded", "Recovered."]);
+
+  expect(terminal(completed)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(completed)).toEqual([LIMIT]);
+});
+
+test.each([
+  "error_max_turns",
+  "error_during_execution",
+  "error_max_budget_usd",
+  "error_max_structured_output_retries",
+] as const)("a %s result publishes final usage before failure", async (subtype) => {
+  const usage = {
+    inputTokens: 2,
+    cachedInputTokens: 12577,
+    outputTokens: 110,
+    totalCostUsd: 0.00365537,
+  };
+  const [failed, next] = await runTurns([
+    { before: "Running the command.", isError: true, subtype, usage },
+    { after: "Done.", isError: false },
+  ]);
+
+  // Collection ends at the terminal event, so this also checks ordering.
+  expect(failed).toContainEqual(
+    expect.objectContaining({ type: "usage_updated", usage: expect.objectContaining(usage) }),
+  );
+  expect(terminal(failed)).toMatchObject({
+    type: "turn_failed",
+    error: "Reached maximum number of turns (1)",
+  });
+  expect(assistantTexts(failed)).toEqual(["Running the command."]);
+  expect(terminal(next)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(next)).toEqual(["Done."]);
+});
diff --git a/packages/server/src/server/agent/providers/claude/agent.history-load.test.ts b/packages/server/src/server/agent/providers/claude/agent.history-load.test.ts
index 393fda60de..e2ea6850bb 100644
--- a/packages/server/src/server/agent/providers/claude/agent.history-load.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.history-load.test.ts
@@ -614,6 +614,43 @@ describe("ClaudeAgentSession persisted history load", () => {
     );
   });
 
+  test("replays a message steered into a running turn as the user's message", async () => {
+    const queued = (commandMode: string, prompt: unknown, sourceUuid?: string) => ({
+      type: "attachment",
+      uuid: `attachment-${commandMode}`,
+      parentUuid: "a1",
+      attachment: {
+        type: "queued_command",
+        commandMode,
+        prompt,
+        ...(sourceUuid ? { source_uuid: sourceUuid } : {}),
+      },
+    });
+    const entries = [
+      { type: "user", uuid: "u1", parentUuid: null, message: { content: "first" } },
+      { type: "assistant", uuid: "a1", parentUuid: "u1", message: { content: "working" } },
+      queued("prompt", [{ type: "text", text: "steered while working" }], "steered-1"),
+      queued("task-notification", "<task-notification><task-id>t1</task-id></task-notification>"),
+      { type: "assistant", uuid: "a2", parentUuid: "a1", message: { content: "answer" } },
+    ];
+    mkdirSync(path.dirname(transcriptPath()), { recursive: true });
+    writeFileSync(transcriptPath(), entries.map((entry) => JSON.stringify(entry)).join("\n"));
+
+    const session = await resume();
+    try {
+      const users = [];
+      for await (const event of session.streamHistory()) {
+        if (event.type === "timeline" && event.item.type === "user_message") users.push(event.item);
+      }
+      expect(users).toEqual([
+        { type: "user_message", text: "first", messageId: "u1" },
+        { type: "user_message", text: "steered while working", messageId: "steered-1" },
+      ]);
+    } finally {
+      await session.close();
+    }
+  });
+
   test("loads readable history when the temporary directory is unavailable", async () => {
     const file = transcriptPath();
     const entry = { type: "assistant", message: { content: [{ type: "text", text: "saved" }] } };
diff --git a/packages/server/src/server/agent/providers/claude/agent.import-titles.test.ts b/packages/server/src/server/agent/providers/claude/agent.import-titles.test.ts
index e20b8d6faf..a826645d4c 100644
--- a/packages/server/src/server/agent/providers/claude/agent.import-titles.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.import-titles.test.ts
@@ -1,3 +1,4 @@
+import { constants as bufferConstants } from "node:buffer";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -236,4 +237,64 @@ describe("importing a renamed Claude session", () => {
 
     await expect(importSession(sessionId)).rejects.toThrow();
   });
+
+  test("reads the rename from a transcript too large to hold as one string", async () => {
+    const sessionId = "oversized-transcript";
+    const projectDir = claudeProjectDirSync(SESSION_CWD, { configDir });
+    await fs.mkdir(projectDir, { recursive: true });
+    const transcript = path.join(projectDir, `${sessionId}.jsonl`);
+    // A hole stands in for the long session this used to fail on: the file only
+    // has to be longer than a string can be, and the rename sits at its end.
+    await fs.writeFile(transcript, "");
+    await fs.truncate(transcript, bufferConstants.MAX_STRING_LENGTH + 1);
+    await fs.appendFile(
+      transcript,
+      `\n${[
+        userRecord({ sessionId, content: "Trace the slow query" }),
+        { type: "custom-title", customTitle: "Slow query hunt", sessionId },
+      ]
+        .map((record) => JSON.stringify(record))
+        .join("\n")}\n`,
+    );
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Slow query hunt");
+  });
+
+  test("reads the rename from behind more records than one read covers", async () => {
+    const sessionId = "late-records-rename";
+    await writeSession({
+      sessionId,
+      records: [
+        userRecord({ sessionId, content: "Review this project" }),
+        { type: "custom-title", customTitle: "Scrollback review", sessionId },
+        // One record longer than a single read, then enough records to leave the
+        // rename several reads back from the end of the file.
+        userRecord({ sessionId, content: "x".repeat(128 * 1024) }),
+        ...Array.from({ length: 64 }, (_, index) =>
+          userRecord({ sessionId, content: `${"y".repeat(4 * 1024)} ${index}` }),
+        ),
+      ],
+    });
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Scrollback review");
+  });
+
+  test("imports a large record after the last rename without repeatedly copying it", async () => {
+    const sessionId = "large-record-after-rename";
+    await writeSession({
+      sessionId,
+      records: [
+        { type: "custom-title", customTitle: "Large attachment review", sessionId },
+        userRecord({ sessionId, content: "x".repeat(96 * 1024 * 1024) }),
+      ],
+    });
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Large attachment review");
+  });
 });
diff --git a/packages/server/src/server/agent/providers/claude/agent.interrupt-restart-regression.test.ts b/packages/server/src/server/agent/providers/claude/agent.interrupt-restart-regression.test.ts
index 02a09ba44b..fa0266c355 100644
--- a/packages/server/src/server/agent/providers/claude/agent.interrupt-restart-regression.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.interrupt-restart-regression.test.ts
@@ -349,8 +349,11 @@ async function startSteeredTurn(sessionId: string): Promise<{
     expectedTurnId: start.value.turnId,
     clientMessageId: "steer-client",
   });
-  expect(steered).toEqual({ status: "accepted" });
   await waitFor(() => query?.prompts.length === 2);
+  expect(steered).toEqual({
+    status: "accepted",
+    providerMessageId: query?.prompts[1]?.uuid,
+  });
 
   return { session, query: () => query, turn };
 }
@@ -972,7 +975,10 @@ test("steers an autonomous turn through its existing query without restarting it
   const steeredTimeline = await autonomousEvents.next();
   const completion = await autonomousEvents.next();
 
-  expect(steer).toEqual({ status: "accepted" });
+  expect(steer).toEqual({
+    status: "accepted",
+    providerMessageId: queryRef?.prompts[1]?.uuid,
+  });
   expect(queryFactory).toHaveBeenCalledTimes(1);
   expect(queryRef?.interrupt).not.toHaveBeenCalled();
   expect(queryRef?.prompts.map((prompt) => prompt.text)).toEqual(["seed prompt", "steer prompt"]);
diff --git a/packages/server/src/server/agent/providers/claude/agent.real.e2e.test.ts b/packages/server/src/server/agent/providers/claude/agent.real.e2e.test.ts
index 74ff780aac..eaf6a68fbc 100644
--- a/packages/server/src/server/agent/providers/claude/agent.real.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.real.e2e.test.ts
@@ -143,6 +143,13 @@ function getLatestCompletedBashCall(events: AgentStreamEvent[]): ToolCallTimelin
     .find((item) => item.status === "completed" && item.name.toLowerCase() === "bash");
 }
 
+function hasBackgroundShell(events: AgentStreamEvent[]): boolean {
+  return events.some(
+    (event) =>
+      event.type === "background_work" && event.items?.some((item) => item.kind === "shell"),
+  );
+}
+
 function getInternalQuery(session: AgentSession): unknown {
   return (session as AgentSession & { query?: unknown }).query ?? null;
 }
@@ -419,6 +426,39 @@ describe("ClaudeAgentSession integration", () => {
     }
   }, 180_000);
 
+  test("lists a background shell as background work until it exits", async () => {
+    const handle = await createSession({ cwdPrefix: "claude-agent-background-work-" });
+    try {
+      const liveEventsPromise = collectSubscribedUntil(
+        handle.session,
+        (event, events) =>
+          event.type === "background_work" &&
+          event.items?.length === 0 &&
+          hasBackgroundShell(events),
+        90_000,
+      );
+
+      await collectUntilTerminal(
+        streamSession(
+          handle.session,
+          [
+            "Use the Bash tool with run_in_background.",
+            "Run exactly: sleep 8",
+            "Do not wait for the task result.",
+            "Reply immediately with exactly: SPAWNED",
+          ].join(" "),
+        ),
+        { timeoutMs: 90_000 },
+      );
+
+      const liveEvents = await liveEventsPromise;
+      expect(hasBackgroundShell(liveEvents)).toBe(true);
+      expect(liveEvents.at(-1)).toMatchObject({ type: "background_work", items: [] });
+    } finally {
+      await cleanupSession(handle);
+    }
+  }, 180_000);
+
   test("surfaces permission requests and resumes after approval", async () => {
     const handle = await createSession({
       cwdPrefix: "claude-agent-permission-",
diff --git a/packages/server/src/server/agent/providers/claude/agent.redesign.test.ts b/packages/server/src/server/agent/providers/claude/agent.redesign.test.ts
index 5393926520..dc0e468af7 100644
--- a/packages/server/src/server/agent/providers/claude/agent.redesign.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.redesign.test.ts
@@ -1206,7 +1206,7 @@ test("reuses one autonomous run for unbound stream_event bursts with no foregrou
   );
 
   const firstRunId = internal.autonomousTurn?.id ?? null;
-  expect(firstRunId).toBe("autonomous-turn-1");
+  expect(firstRunId).toEqual(expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-1$/));
   expect(internal.nextTurnOrdinal).toBe(2);
 
   await internal.routeSdkMessageFromPump(
@@ -1360,7 +1360,9 @@ test("a main-session frame opens no turn until Claude starts one", async () => {
   // session start a turn of its own, with no prompt from the user.
   await internal.routeSdkMessageFromPump(claudeTurnInit(), queryMock);
   await internal.routeSdkMessageFromPump(unboundTextDelta("picking this up"), queryMock);
-  expect(internal.autonomousTurn?.id).toBe("autonomous-turn-1");
+  expect(internal.autonomousTurn?.id).toEqual(
+    expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-1$/),
+  );
 
   await internal.routeSdkMessageFromPump(successResult(), queryMock);
   expect(internal.autonomousTurn).toBeNull();
@@ -1410,7 +1412,9 @@ test("Claude waking up after a helper finishes gets an autonomous turn that its
   expect(internal.autonomousTurn).toBeNull();
 
   await internal.routeSdkMessageFromPump(claudeTurnInit(), queryMock);
-  expect(internal.autonomousTurn?.id).toBe("autonomous-turn-1");
+  expect(internal.autonomousTurn?.id).toEqual(
+    expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-1$/),
+  );
   expect(internal.turnState).toBe("autonomous");
 
   await internal.routeSdkMessageFromPump(unboundTextDelta("the helper is done"), queryMock);
@@ -1446,7 +1450,9 @@ test("a steer folded into a turn keeps one turn, and a turn Claude starts after
 
   // A message that arrived while Claude wrote its final answer runs as a turn of its own.
   await internal.routeSdkMessageFromPump(claudeTurnInit(), queryMock);
-  expect(internal.autonomousTurn?.id).toBe("autonomous-turn-2");
+  expect(internal.autonomousTurn?.id).toEqual(
+    expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-2$/),
+  );
   await internal.routeSdkMessageFromPump(successResult(), queryMock);
   expect(internal.autonomousTurn).toBeNull();
   expect(internal.turnState).toBe("idle");
@@ -1483,7 +1489,9 @@ test("an idle session state closes an autonomous turn that no result closed", as
   session.subscribe((event) => events.push(event));
 
   await internal.routeSdkMessageFromPump(claudeTurnInit(), queryMock);
-  expect(internal.autonomousTurn?.id).toBe("autonomous-turn-1");
+  expect(internal.autonomousTurn?.id).toEqual(
+    expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-1$/),
+  );
 
   // Safety net: Claude says nothing at all is running any more.
   await internal.routeSdkMessageFromPump(sessionState("idle"), queryMock);
@@ -1685,7 +1693,9 @@ test("a new turn clears an interrupt flag no result will consume", async () => {
 
   await internal.routeSdkMessageFromPump(claudeTurnInit(), queryMock);
   expect(internal.pendingInterruptAbort).toBe(false);
-  expect(internal.autonomousTurn?.id).toBe("autonomous-turn-1");
+  expect(internal.autonomousTurn?.id).toEqual(
+    expect.stringMatching(/^autonomous-turn-[0-9a-f-]{36}-1$/),
+  );
 
   // This turn's own failure is reported, not swallowed as the interrupted turn's leftover.
   await internal.routeSdkMessageFromPump(
diff --git a/packages/server/src/server/agent/providers/claude/agent.rewind-anchors.test.ts b/packages/server/src/server/agent/providers/claude/agent.rewind-anchors.test.ts
index 8a72b34297..aa11e67fa7 100644
--- a/packages/server/src/server/agent/providers/claude/agent.rewind-anchors.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.rewind-anchors.test.ts
@@ -1,7 +1,11 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
 import { ClaudeAgentClient } from "./agent.js";
+import { claudeProjectDir } from "./project-dir.js";
 import { FakeClaudeSdk } from "./test-rewind-claude-sdk.js";
 import { streamSession } from "../test-utils/session-stream-adapter.js";
 import {
@@ -314,3 +318,49 @@ describe("Claude rewind after a turn whose last assistant message came from a su
     expect(rewindSdk.recordedForks).toEqual([{ upToMessageId: "assistant-1" }]);
   });
 });
+
+describe("Claude rewind to a message steered into a running turn", () => {
+  test("forks at the entry Claude read the message after", async () => {
+    const configDir = mkdtempSync(path.join(tmpdir(), "claude-rewind-steer-"));
+    const previousConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = configDir;
+    const conversation = createConversation([{ assistantMessageId: "assistant-1" }]);
+    const rewindSdk = new FakeClaudeSdk();
+    const session = await createSession(conversation, rewindSdk);
+
+    try {
+      await runTurns(session, 1);
+      // A steered message opens no turn: Claude Code records it as a queued_command attachment
+      // under the uuid Paseo minted for it, hung off the entry it was read after.
+      const projectDir = await claudeProjectDir(process.cwd(), { configDir });
+      mkdirSync(projectDir, { recursive: true });
+      const entries = [
+        { type: "user", uuid: conversation.userMessageIds[0], parentUuid: null },
+        { type: "assistant", uuid: "assistant-1", parentUuid: conversation.userMessageIds[0] },
+        { type: "user", uuid: "tool-result-1", parentUuid: "assistant-1" },
+        {
+          type: "attachment",
+          uuid: "queued-command-1",
+          parentUuid: "tool-result-1",
+          attachment: { type: "queued_command", source_uuid: "steered-message-1" },
+        },
+      ];
+      writeFileSync(
+        path.join(projectDir, `${SESSION_ID}.jsonl`),
+        entries.map((entry) => `${JSON.stringify(entry)}\n`).join(""),
+      );
+
+      await session.revertConversation?.({ messageId: "steered-message-1" });
+    } finally {
+      await session.close();
+      if (previousConfigDir === undefined) {
+        delete process.env.CLAUDE_CONFIG_DIR;
+      } else {
+        process.env.CLAUDE_CONFIG_DIR = previousConfigDir;
+      }
+      rmSync(configDir, { recursive: true, force: true });
+    }
+
+    expect(rewindSdk.recordedForks).toEqual([{ upToMessageId: "tool-result-1" }]);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/claude/agent.runtime-exit.test.ts b/packages/server/src/server/agent/providers/claude/agent.runtime-exit.test.ts
index 85bf450ab3..d70d068717 100644
--- a/packages/server/src/server/agent/providers/claude/agent.runtime-exit.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.runtime-exit.test.ts
@@ -118,6 +118,22 @@ const RUNNING_WORKFLOW_TURN_EVENTS = [
   COMPLETED_TURN_EVENTS[2],
 ];
 
+const BACKGROUND_SHELL_TURN_EVENTS = [
+  COMPLETED_TURN_EVENTS[0],
+  {
+    type: "system",
+    subtype: "background_tasks_changed",
+    tasks: [
+      { task_id: "bash-1", task_type: "local_bash", description: "sleep 20" },
+      { task_id: "wf-1", task_type: "local_workflow", description: "Run the spec workflow" },
+    ],
+    uuid: "00000000-0000-4000-8000-000000000001",
+    session_id: "claude-runtime-exit-session",
+  },
+  COMPLETED_TURN_EVENTS[1],
+  COMPLETED_TURN_EVENTS[2],
+];
+
 const MISSING_RESUMED_CONVERSATION_RESULT = {
   type: "result",
   subtype: "error_during_execution",
@@ -272,6 +288,155 @@ describe("Claude runtime exit", () => {
     }
   });
 
+  test("reports background tasks except subagents as background work", async () => {
+    const queryFactory = vi.fn(() => createQueryMock(BACKGROUND_SHELL_TURN_EVENTS));
+    vi.spyOn(spawnUtils, "spawnProcess").mockReturnValue(createChildProcessStub());
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+
+    try {
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+
+      await session.run("start a background shell");
+
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: "background_work",
+          provider: "claude",
+          items: [{ id: "bash-1", kind: "shell", description: "sleep 20", canStop: true }],
+        }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("empties background work when the process dies while idle", async () => {
+    let capturedOptions: Options | undefined;
+    const queryFactory = vi.fn(({ options }: ClaudeQueryInput) => {
+      capturedOptions = options;
+      return createQueryMock(BACKGROUND_SHELL_TURN_EVENTS);
+    });
+    const child = createChildProcessStub();
+    vi.spyOn(spawnUtils, "spawnProcess").mockReturnValue(child);
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+
+    try {
+      await session.run("start a background shell");
+      capturedOptions?.spawnClaudeCodeProcess?.(SPAWN_OPTIONS);
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+
+      child.emit("exit", 1, null);
+
+      expect(events).toContainEqual(
+        expect.objectContaining({ type: "background_work", provider: "claude", items: null }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("empties background work when a query restart retires the process", async () => {
+    let capturedOptions: Options | undefined;
+    const child = createChildProcessStub();
+    const queryFactory = vi.fn(({ options }: ClaudeQueryInput) => {
+      capturedOptions = options;
+      return createQueryMock(BACKGROUND_SHELL_TURN_EVENTS, {
+        tail: new Promise<never>(() => undefined),
+        onReturn: () => child.emit("exit", 0, null),
+      });
+    });
+    vi.spyOn(spawnUtils, "spawnProcess").mockReturnValue(child);
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+
+    try {
+      await session.run("start a background shell");
+      capturedOptions?.spawnClaudeCodeProcess?.(SPAWN_OPTIONS);
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+
+      await session.setThinkingOption(null);
+      await session.listCommands();
+
+      expect(events).toContainEqual(
+        expect.objectContaining({ type: "background_work", provider: "claude", items: null }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("ignores background work a retired query reports after its restart", async () => {
+    let capturedOptions: Options | undefined;
+    let deliverLateEvent: ((event: unknown) => void) | undefined;
+    let retiredQuery: Query | undefined;
+    const child = createChildProcessStub();
+    const queryFactory = vi.fn(({ options }: ClaudeQueryInput) => {
+      capturedOptions = options;
+      if (retiredQuery) {
+        return createQueryMock([], { tail: new Promise<never>(() => undefined) });
+      }
+      retiredQuery = createQueryMock(BACKGROUND_SHELL_TURN_EVENTS, {
+        tail: new Promise<unknown>((resolve) => {
+          deliverLateEvent = resolve;
+        }),
+        onReturn: () => child.emit("exit", 0, null),
+      });
+      return retiredQuery;
+    });
+    vi.spyOn(spawnUtils, "spawnProcess").mockReturnValue(child);
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+
+    try {
+      await session.run("start a background shell");
+      capturedOptions?.spawnClaudeCodeProcess?.(SPAWN_OPTIONS);
+      const events: AgentStreamEvent[] = [];
+      session.subscribe((event) => events.push(event));
+
+      await session.setThinkingOption(null);
+      await session.listCommands();
+      expect(queryFactory).toHaveBeenCalledTimes(2);
+
+      // The retired query still had this queued when the restart emptied the list.
+      deliverLateEvent?.(BACKGROUND_SHELL_TURN_EVENTS[1]);
+      // One next() per scripted event and one for the late event; the pump stops
+      // reading a query it no longer owns instead of routing that event.
+      await vi.waitFor(() =>
+        expect(retiredQuery?.next).toHaveBeenCalledTimes(BACKGROUND_SHELL_TURN_EVENTS.length + 1),
+      );
+      // Let a routed late event reach subscribers before checking the list.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+
+      const backgroundWork = events.filter((event) => event.type === "background_work");
+      expect(backgroundWork.at(-1)).toEqual(
+        expect.objectContaining({ type: "background_work", provider: "claude", items: null }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+
   test("tree-kills the retired process when the resumed conversation is gone", async () => {
     let capturedOptions: Options | undefined;
     let deliverMissingConversation: ((event: unknown) => void) | undefined;
@@ -348,4 +513,77 @@ describe("Claude runtime exit", () => {
       await session.close();
     }
   });
+  test("waits for a stopped task notification after the stop request is accepted", async () => {
+    let deliver!: (message: unknown) => void;
+    const tail = new Promise<unknown>((resolve) => {
+      deliver = resolve;
+    });
+    const query = createQueryMock(BACKGROUND_SHELL_TURN_EVENTS, { tail });
+    query.stopTask = async () => {};
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory: () => query,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+    try {
+      await session.run("start a background shell");
+      let settled = false;
+      const pending = session.stopBackgroundWork!("bash-1").then(() => {
+        settled = true;
+        return undefined;
+      });
+      await Promise.resolve();
+      expect(settled).toBe(false);
+      deliver({
+        type: "system",
+        subtype: "task_notification",
+        task_id: "bash-1",
+        status: "stopped",
+        output_file: "",
+        summary: "Stopped",
+        uuid: "00000000-0000-4000-8000-000000000002",
+        session_id: "claude-runtime-exit-session",
+      });
+      await pending;
+      expect(settled).toBe(true);
+      await expect(session.stopBackgroundWork!("wf-1")).rejects.toThrow();
+    } finally {
+      await session.close();
+    }
+  });
+  test.each(["completed", "failed"])(
+    "reports the task's %s outcome when it races a stop",
+    async (status) => {
+      let deliver!: (message: unknown) => void;
+      const tail = new Promise<unknown>((resolve) => {
+        deliver = resolve;
+      });
+      const query = createQueryMock(BACKGROUND_SHELL_TURN_EVENTS, { tail });
+      query.stopTask = async () => {};
+      const client = new ClaudeAgentClient({
+        logger: createTestLogger(),
+        queryFactory: () => query,
+        resolveBinary: async () => "/test/claude/bin",
+      });
+      const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+      try {
+        await session.run("start a background shell");
+        const result = session.stopBackgroundWork!("bash-1");
+        deliver({
+          type: "system",
+          subtype: "task_notification",
+          task_id: "bash-1",
+          status,
+          output_file: "",
+          summary: "Finished",
+          uuid: "00000000-0000-4000-8000-000000000003",
+          session_id: "claude-runtime-exit-session",
+        });
+        await expect(result).rejects.toThrow(status);
+      } finally {
+        await session.close();
+      }
+    },
+  );
 });
diff --git a/packages/server/src/server/agent/providers/claude/agent.runtime-info.test.ts b/packages/server/src/server/agent/providers/claude/agent.runtime-info.test.ts
new file mode 100644
index 0000000000..a23c95bc64
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/agent.runtime-info.test.ts
@@ -0,0 +1,48 @@
+import pino from "pino";
+import { describe, expect, test } from "vitest";
+
+import { ClaudeAgentClient } from "./agent.js";
+
+describe("Claude runtime info before a turn", () => {
+  const client = new ClaudeAgentClient({ logger: pino({ level: "silent" }) });
+
+  test("reports the explicitly configured model before the first turn", async () => {
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-haiku-5-5",
+    });
+    try {
+      expect(await session.getRuntimeInfo()).toMatchObject({ model: "claude-haiku-5-5" });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("reports the persisted configured model after rebuilding an idle session", async () => {
+    const session = await client.resumeSession({
+      provider: "claude",
+      sessionId: "runtime-model-before-turn",
+      metadata: { cwd: process.cwd(), model: "claude-haiku-5-5" },
+    });
+    try {
+      expect(await session.getRuntimeInfo()).toMatchObject({
+        sessionId: "runtime-model-before-turn",
+        model: "claude-haiku-5-5",
+      });
+      expect((await session.getRuntimeInfo()).model).toBe("claude-haiku-5-5");
+      expect((await session.getRuntimeInfo()).extra?.runtimeModel).toBeUndefined();
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("leaves the model unknown when Claude will choose its default", async () => {
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+    try {
+      expect((await session.getRuntimeInfo()).model).toBeNull();
+    } finally {
+      await session.close();
+    }
+  });
+});
diff --git a/packages/server/src/server/agent/providers/claude/agent.sub-agent-replay.test.ts b/packages/server/src/server/agent/providers/claude/agent.sub-agent-replay.test.ts
index 4728767307..91007aa7ce 100644
--- a/packages/server/src/server/agent/providers/claude/agent.sub-agent-replay.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.sub-agent-replay.test.ts
@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
 import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import { streamSession } from "../test-utils/session-stream-adapter.js";
 import { ClaudeAgentClient } from "./agent.js";
 import { claudeProjectDirSync } from "./project-dir.js";
 
@@ -77,6 +78,29 @@ function sidechainEntry(options: { agentId?: string; stopReason?: string | null
   });
 }
 
+function buildQueryMock(events: unknown[]) {
+  let index = 0;
+  return {
+    next: vi.fn(async () => {
+      if (index >= events.length) return { done: true, value: undefined };
+      const value = events[index];
+      index += 1;
+      return { done: false, value };
+    }),
+    interrupt: vi.fn(async () => undefined),
+    return: vi.fn(async () => undefined),
+    close: vi.fn(() => undefined),
+    setPermissionMode: vi.fn(async () => undefined),
+    setModel: vi.fn(async () => undefined),
+    supportedModels: vi.fn(async () => []),
+    supportedCommands: vi.fn(async () => []),
+    rewindFiles: vi.fn(async () => ({ canRewind: true })),
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  };
+}
+
 describe("ClaudeAgentSession persisted subagent replay", () => {
   const logger = createTestLogger();
   const queryFactory = vi.fn(() => {
@@ -1262,4 +1286,106 @@ describe("ClaudeAgentSession persisted subagent replay", () => {
     );
     expect(items).toEqual([{ type: "assistant_message", text: report }]);
   });
+
+  test("keeps a subagent resumed after the session reopens on the row its transcript restored", async () => {
+    // Verified on the wire (Claude Code 2.1.309): SendMessage resumes a finished subagent under its
+    // original task_id but a new tool_use_id, and the child's frames still name the original Task
+    // call as their parent. A reopened session only knows that child from its transcript.
+    writeSession({
+      parentLines: [taskToolUse(), taskToolResult()],
+      meta: JSON.stringify({ agentType: "general-purpose", toolUseId: TOOL_USE_ID }),
+      sidechainLines: [
+        JSON.stringify({
+          type: "assistant",
+          isSidechain: true,
+          agentId: AGENT_ID,
+          sessionId: "replay-session",
+          timestamp: "2026-07-26T06:27:50.000Z",
+          effort: "high",
+          message: {
+            role: "assistant",
+            model: "claude-sonnet-5",
+            content: [{ type: "text", text: "summary of the docs" }],
+            stop_reason: "end_turn",
+          },
+        }),
+      ],
+    });
+    const liveQuery = vi.fn(() =>
+      buildQueryMock([
+        {
+          type: "system",
+          subtype: "init",
+          session_id: "replay-session",
+          permissionMode: "default",
+        },
+        {
+          type: "system",
+          subtype: "task_started",
+          task_id: AGENT_ID,
+          tool_use_id: "toolu_send_message",
+          description: "Summarize the docs",
+          subagent_type: "general-purpose",
+          task_type: "local_agent",
+          is_backgrounded: true,
+          prompt: "Summarize them again",
+        },
+        {
+          type: "assistant",
+          parent_tool_use_id: TOOL_USE_ID,
+          session_id: "replay-session",
+          message: {
+            id: "msg_resumed_child",
+            role: "assistant",
+            model: "claude-opus-5",
+            content: [{ type: "text", text: "summary again" }],
+          },
+        },
+        {
+          type: "system",
+          subtype: "task_updated",
+          task_id: AGENT_ID,
+          patch: { status: "completed" },
+        },
+        {
+          type: "result",
+          subtype: "success",
+          usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 },
+          total_cost_usd: 0,
+        },
+      ]),
+    );
+    const session = await new ClaudeAgentClient({
+      logger,
+      queryFactory: liveQuery,
+      resolveVersion: async () => "2.1.309",
+      resolveBinary: async () => "/test/claude/bin",
+    }).resumeSession({ provider: "claude", sessionId: "replay-session" }, { cwd });
+    const events: AgentStreamEvent[] = [];
+    for await (const event of streamSession(session, "Ask it to summarize again")) {
+      events.push(event);
+      if (event.type === "turn_completed" || event.type === "turn_failed") break;
+    }
+    await session.close();
+
+    const live = events.flatMap((event) =>
+      event.type === "provider_subagent" ? [event.event] : [],
+    );
+    expect(new Set(live.map((event) => event.id))).toEqual(new Set([TOOL_USE_ID]));
+    expect(live).toContainEqual(
+      expect.objectContaining({
+        type: "upsert",
+        id: TOOL_USE_ID,
+        subtitle: "general-purpose · Opus 5 · High",
+      }),
+    );
+    expect(live).toContainEqual(
+      expect.objectContaining({
+        type: "timeline",
+        id: TOOL_USE_ID,
+        item: expect.objectContaining({ type: "assistant_message", text: "summary again" }),
+      }),
+    );
+    expect(live.at(-1)).toMatchObject({ type: "upsert", id: TOOL_USE_ID, status: "completed" });
+  });
 });
diff --git a/packages/server/src/server/agent/providers/claude/agent.test.ts b/packages/server/src/server/agent/providers/claude/agent.test.ts
index deb52f9a6b..3aa96635fc 100644
--- a/packages/server/src/server/agent/providers/claude/agent.test.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.test.ts
@@ -18,6 +18,9 @@ import {
   resolveClaudeCodeVersion,
   toClaudeSdkMcpConfig,
 } from "./agent.js";
+import { AgentManager } from "../../agent-manager.js";
+import { ensureAgentLoaded } from "../../agent-loading.js";
+import { AgentStorage } from "../../agent-storage.js";
 import { createImportDescriptorScheduler } from "./import-descriptor-scheduler.js";
 import { claudeProjectDirSync } from "./project-dir.js";
 import { streamSession } from "../test-utils/session-stream-adapter.js";
@@ -30,6 +33,8 @@ import type {
 } from "../../agent-sdk-types.js";
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import { buildAgentPrompt, renderPromptAttachmentAsText } from "../../prompt-attachments.js";
+import { applyProviderOptionsPatch } from "../../option-controls.js";
+import { mergeProviderOptions } from "../../provider-options.js";
 
 interface TestClaudeSession {
   translateMessageToEvents(message: SDKMessage): Promise<AgentStreamEvent[]>;
@@ -729,6 +734,196 @@ describe("ClaudeAgentSession features", () => {
     return { queryFactory, queryMock, launches };
   }
 
+  function createStreamingQueryMock() {
+    const mock = createQueryMock();
+    const messages: SDKMessage[] = [];
+    let pending: ((result: IteratorResult<SDKMessage, void>) => void) | null = null;
+    let ended = false;
+    const finish = () => {
+      ended = true;
+      pending?.({ done: true, value: undefined });
+      pending = null;
+    };
+    mock.queryMock.close.mockImplementation(finish);
+    mock.queryMock.return.mockImplementation(async () => finish());
+    mock.queryMock[Symbol.asyncIterator] = () => ({
+      next: async () => {
+        const message = messages.shift();
+        if (message) return { done: false, value: message };
+        if (ended) return { done: true, value: undefined };
+        return new Promise<IteratorResult<SDKMessage, void>>((resolve) => {
+          pending = resolve;
+        });
+      },
+    });
+    return {
+      ...mock,
+      push(message: SDKMessage) {
+        if (pending) {
+          pending({ done: false, value: message });
+          pending = null;
+        } else {
+          messages.push(message);
+        }
+      },
+    };
+  }
+
+  async function startToolForClosure() {
+    const mock = createStreamingQueryMock();
+    const session = await new ClaudeAgentClient({
+      logger,
+      queryFactory: mock.queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    }).createSession({ provider: "claude", cwd: process.cwd(), modeId: "default" });
+    const events: AgentStreamEvent[] = [];
+    let toolStarted!: () => void;
+    const running = new Promise<void>((resolve) => {
+      toolStarted = resolve;
+    });
+    const unsubscribe = session.subscribe((event) => {
+      events.push(event);
+      if (
+        event.type === "timeline" &&
+        event.item.type === "tool_call" &&
+        event.item.status === "running"
+      )
+        toolStarted();
+    });
+    await session.startTurn("run the tool");
+    mock.push({
+      type: "stream_event",
+      session_id: "closure-session",
+      uuid: "00000000-0000-4000-8000-000000000001",
+      parent_tool_use_id: null,
+      event: {
+        type: "content_block_start",
+        index: 0,
+        content_block: { type: "tool_use", id: "closure-tool", name: "Bash", input: {} },
+      },
+    });
+    mock.push({
+      type: "stream_event",
+      session_id: "closure-session",
+      uuid: "00000000-0000-4000-8000-000000000002",
+      parent_tool_use_id: null,
+      event: { type: "content_block_stop", index: 0 },
+    });
+    await running;
+    return { ...mock, session, events, unsubscribe };
+  }
+
+  test("runtime close publishes tool cleanup without reporting a user turn cancellation", async () => {
+    const fixture = await startToolForClosure();
+    try {
+      await fixture.session.close();
+      expect(fixture.queryMock.close).toHaveBeenCalledTimes(1);
+      expect(
+        fixture.events.filter(
+          (event) =>
+            event.type === "timeline" &&
+            event.item.type === "tool_call" &&
+            event.item.status === "canceled",
+        ),
+      ).toHaveLength(1);
+      expect(
+        fixture.events.filter(
+          (event) =>
+            event.type === "turn_canceled" ||
+            event.type === "turn_completed" ||
+            event.type === "turn_failed",
+        ),
+      ).toEqual([]);
+    } finally {
+      fixture.unsubscribe();
+      await fixture.session.close();
+    }
+  });
+
+  test("explicit interruption still publishes tool cleanup and one turn cancellation", async () => {
+    const fixture = await startToolForClosure();
+    try {
+      await fixture.session.interrupt();
+      expect(
+        fixture.events.filter(
+          (event) =>
+            event.type === "timeline" &&
+            event.item.type === "tool_call" &&
+            event.item.status === "canceled",
+        ),
+      ).toHaveLength(1);
+      expect(fixture.events.filter((event) => event.type === "turn_canceled")).toHaveLength(1);
+    } finally {
+      fixture.unsubscribe();
+      await fixture.session.close();
+    }
+  });
+
+  test("runtime close resolves permissions once without reporting a user turn cancellation", async () => {
+    const { queryFactory } = createQueryMock();
+    const session = await new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    }).createSession({ provider: "claude", cwd: process.cwd(), modeId: "default" });
+    const events: AgentStreamEvent[] = [];
+    const unsubscribe = session.subscribe((event) => events.push(event));
+    const abort = new AbortController();
+    try {
+      await session.startTurn("run the tool");
+      const canUseTool = queryFactory.mock.calls[0]?.[0].options.canUseTool;
+      if (!canUseTool) throw new Error("Expected canUseTool callback");
+      const permission = canUseTool(
+        "Bash",
+        { command: "printf test" },
+        { signal: abort.signal, toolUseID: "tool-closed" },
+      );
+      const rejected = expect(permission).rejects.toThrow("Claude session closed");
+      await session.close();
+      abort.abort();
+      await rejected;
+      expect(session.getPendingPermissions()).toEqual([]);
+      expect(events.filter(isPermissionResolvedEvent)).toHaveLength(1);
+      expect(events.filter((event) => event.type === "turn_canceled")).toEqual([]);
+    } finally {
+      unsubscribe();
+      await session.close();
+    }
+  });
+
+  test("runtime close prevents a query from launching after pending options resolve", async () => {
+    const { queryFactory } = createQueryMock();
+    let optionsStarted!: () => void;
+    let allowOptions!: () => void;
+    const started = new Promise<void>((resolve) => {
+      optionsStarted = resolve;
+    });
+    const allowed = new Promise<void>((resolve) => {
+      allowOptions = resolve;
+    });
+    const session = await new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => {
+        optionsStarted();
+        await allowed;
+        return "/test/claude/bin";
+      },
+    }).createSession({ provider: "claude", cwd: process.cwd(), modeId: "default" });
+    const turn = session.startTurn("must not run after closure");
+    try {
+      await started;
+      await session.close();
+      allowOptions();
+      await turn;
+      expect(queryFactory).not.toHaveBeenCalled();
+    } finally {
+      allowOptions();
+      await turn;
+      await session.close();
+    }
+  });
+
   test("publishes a resolution when the SDK aborts a permission callback", async () => {
     const { queryFactory } = createQueryMock();
     const session = await new ClaudeAgentClient({
@@ -953,60 +1148,91 @@ describe("ClaudeAgentSession features", () => {
     const client = new ClaudeAgentClient({ logger, resolveBinary: async () => "/test/claude/bin" });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual({
+      controls: [expect.objectContaining({ key: "fast_mode", type: "toggle" })],
+      options: {},
+    });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8[1m]",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual({
+      controls: [expect.objectContaining({ key: "fast_mode", type: "toggle" })],
+      options: {},
+    });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-4-8-20260101",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual({
+      controls: [expect.objectContaining({ key: "fast_mode", type: "toggle" })],
+      options: {},
+    });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-opus-5",
       }),
-    ).resolves.toEqual([expect.objectContaining({ id: "fast_mode", value: false })]);
+    ).resolves.toEqual({
+      controls: [expect.objectContaining({ key: "fast_mode", type: "toggle" })],
+      options: {},
+    });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "openrouter/anthropic/claude-opus-4-8",
       }),
-    ).resolves.toEqual([]);
+    ).resolves.toEqual({ controls: [], options: {} });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-sonnet-5",
       }),
-    ).resolves.toEqual([]);
+    ).resolves.toEqual({ controls: [], options: {} });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "claude",
         cwd: process.cwd(),
         model: "claude-sonnet-4-6",
       }),
-    ).resolves.toEqual([]);
+    ).resolves.toEqual({ controls: [], options: {} });
+  });
+
+  test("opens with Fast off on a model that has none, so unrelated options still apply", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-sonnet-5",
+      providerOptions: { fast_mode: true },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ fast_mode: false });
+    await expect(session.applyOptions?.({ allowedTools: ["Read"] })).resolves.toBeUndefined();
+    await session.close();
   });
 
   test("passes initial fast mode through Claude flag settings", async () => {
@@ -1020,7 +1246,7 @@ describe("ClaudeAgentSession features", () => {
       provider: "claude",
       cwd: process.cwd(),
       model: "claude-opus-4-8",
-      featureValues: { fast_mode: true },
+      providerOptions: { fast_mode: true },
     });
 
     await expect(
@@ -1155,6 +1381,30 @@ describe("ClaudeAgentSession features", () => {
     await session.close();
   });
 
+  test("keeps turn identities distinct across resumed session objects", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const handle = {
+      provider: "claude" as const,
+      sessionId: "saved-session",
+      metadata: { cwd: process.cwd() },
+    };
+    const first = await client.resumeSession(handle);
+    const firstTurn = await first.startTurn("first");
+    await first.close();
+    const resumed = await client.resumeSession(handle);
+    try {
+      const nextTurn = await resumed.startTurn("second");
+      expect(nextTurn.turnId).not.toBe(firstTurn.turnId);
+    } finally {
+      await resumed.close();
+    }
+  });
+
   test("disables Claude hooks for internal agents only", async () => {
     const { queryFactory } = createQueryMock();
     const client = new ClaudeAgentClient({
@@ -1224,16 +1474,17 @@ describe("ClaudeAgentSession features", () => {
       const iterator = input[Symbol.asyncIterator]();
       await expect(iterator.next()).resolves.toMatchObject({ value: { type: "user" } });
 
-      await expect(
-        session.steerActiveTurn?.("same turn follow-up", {
-          expectedTurnId: turnId,
-          clientMessageId: "steer-client-id",
-        }),
-      ).resolves.toEqual({ status: "accepted" });
+      const admission = await session.steerActiveTurn?.("same turn follow-up", {
+        expectedTurnId: turnId,
+        clientMessageId: "steer-client-id",
+      });
+      expect(admission).toEqual({ status: "accepted", providerMessageId: expect.any(String) });
+      if (admission?.status !== "accepted") throw new Error("Expected steer admission");
       await expect(iterator.next()).resolves.toMatchObject({
         value: {
           type: "user",
           priority: "next",
+          uuid: admission.providerMessageId,
           message: { content: [{ type: "text", text: "same turn follow-up" }] },
         },
       });
@@ -1291,7 +1542,7 @@ describe("ClaudeAgentSession features", () => {
           expectedTurnId: turnId,
           clearPendingPermissions: true,
         }),
-      ).resolves.toEqual({ status: "accepted" });
+      ).resolves.toEqual({ status: "accepted", providerMessageId: expect.any(String) });
       await expect(firstPermission).resolves.toMatchObject({
         behavior: "deny",
         interrupt: undefined,
@@ -1350,7 +1601,7 @@ describe("ClaudeAgentSession features", () => {
       const permission = internal.handlePermissionRequest("Write", {}, { toolUseID: "tool-1" });
       await expect(
         session.steerActiveTurn?.("system notification", { expectedTurnId: turnId }),
-      ).resolves.toEqual({ status: "accepted" });
+      ).resolves.toEqual({ status: "accepted", providerMessageId: expect.any(String) });
       expect(session.getPendingPermissions()).toHaveLength(1);
       const requestId = session.getPendingPermissions()[0]!.id;
       await session.respondToPermission(requestId, { behavior: "deny", message: "test cleanup" });
@@ -1363,6 +1614,8 @@ describe("ClaudeAgentSession features", () => {
   test.each([
     ["supported model", "claude-opus-4-8", { type: "disabled" }, undefined],
     ["Mythos 5.1", "claude-mythos-5-1", { type: "adaptive", display: "summarized" }, "high"],
+    ["Fable 5.2", "claude-fable-5-2", { type: "adaptive", display: "summarized" }, "medium"],
+    ["Mythos 5.2", "claude-mythos-5-2", { type: "adaptive", display: "summarized" }, "medium"],
     ["Haiku 5.5", "claude-haiku-5-5", { type: "disabled" }, undefined],
     ["unsupported model", "claude-fable-5", { type: "adaptive", display: "summarized" }, "high"],
     ["custom model", "openrouter/anthropic/claude-opus-4-8", undefined, undefined],
@@ -1491,7 +1744,7 @@ describe("ClaudeAgentSession features", () => {
         ensureQuery(): Promise<unknown>;
       }
     ).ensureQuery();
-    await session.setFeature?.("fast_mode", true);
+    await session.applyOptions?.({ fast_mode: true });
 
     expect(queryFactory).toHaveBeenCalledTimes(1);
     expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: true });
@@ -1500,6 +1753,242 @@ describe("ClaudeAgentSession features", () => {
 
     await session.close();
   });
+
+  test("rejects a change to a launch option while the first query is starting", async () => {
+    const { queryFactory } = createQueryMock();
+    let releaseBinary!: () => void;
+    const binaryLookup = new Promise<void>((resolve) => {
+      releaseBinary = resolve;
+    });
+    let lookupStarted!: () => void;
+    const lookupEntered = new Promise<void>((resolve) => {
+      lookupStarted = resolve;
+    });
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => {
+        lookupStarted();
+        await binaryLookup;
+        return "/test/claude/bin";
+      },
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { disallowedTools: ["Bash"] },
+    });
+
+    const turn = session.startTurn("hello");
+    await lookupEntered;
+    await expect(session.applyOptions?.({ disallowedTools: [] })).rejects.toThrow(
+      /disallowedTools.*cannot change on a running session/,
+    );
+    releaseBinary();
+    await turn;
+
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({ disallowedTools: ["Bash"] });
+    await session.close();
+  });
+
+  test("a patch before the first prompt keeps the restrictions the session opened with", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: {
+        disallowedTools: ["Bash"],
+        sandbox: { enabled: true, failIfUnavailable: true },
+      },
+    });
+
+    await session.applyOptions?.({ fast_mode: true });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({
+      disallowedTools: ["Bash"],
+      sandbox: { enabled: true, failIfUnavailable: true },
+    });
+    await session.close();
+  });
+
+  test("an option Claude reads when it starts changes before the query exists and is rejected after", async () => {
+    const { queryFactory } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { disallowedTools: ["Bash"] },
+    });
+
+    await session.applyOptions?.({ disallowedTools: ["Bash", "Write"] });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    expect(queryFactory.mock.calls[0]?.[0].options).toMatchObject({
+      disallowedTools: ["Bash", "Write"],
+    });
+
+    // The query now runs with these; replacing it would end its background work.
+    await expect(session.applyOptions?.({ disallowedTools: [] })).rejects.toThrow(
+      /disallowedTools.*cannot change on a running session/,
+    );
+    // The same value is not a change, and Fast still applies.
+    await expect(
+      session.applyOptions?.({ disallowedTools: ["Bash", "Write"], fast_mode: true }),
+    ).resolves.toBeUndefined();
+    expect(queryFactory).toHaveBeenCalledTimes(1);
+    await session.close();
+  });
+
+  test("switching to a model without Fast turns it off, reports that, and later patches still apply", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+      providerOptions: { fast_mode: true },
+    });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await session.setModel?.("claude-fable-5");
+
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: false });
+    const reported = events.filter((event) => event.type === "options_changed");
+    expect(reported).toEqual([
+      { type: "options_changed", provider: "claude", patch: { fast_mode: false } },
+    ]);
+    // With a `config.json` default of `fast_mode: true`, the agent's effective options must
+    // still read Fast as off: a removed key would let the default fill `true` back in.
+    const stored = applyProviderOptionsPatch({
+      options: { fast_mode: true },
+      patch: reported[0].patch,
+    });
+    expect(mergeProviderOptions({ fast_mode: true }, stored)).toEqual({ fast_mode: false });
+    await expect(session.applyOptions?.({ fast_mode: null })).resolves.toBeUndefined();
+    await session.close();
+  });
+
+  test("removing fast_mode turns Fast off", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+    });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    await session.applyOptions?.({ fast_mode: true });
+
+    await session.applyOptions?.({ fast_mode: null });
+
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: false });
+    await session.close();
+  });
+
+  test("retries a fast mode change the runtime rejected", async () => {
+    const { queryFactory, queryMock } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-opus-4-8",
+    });
+    await (session as unknown as { ensureQuery(): Promise<unknown> }).ensureQuery();
+    queryMock.applyFlagSettings.mockClear();
+    queryMock.applyFlagSettings.mockRejectedValueOnce(new Error("runtime unavailable"));
+
+    await expect(session.applyOptions?.({ fast_mode: true })).rejects.toThrow(
+      "runtime unavailable",
+    );
+    await session.applyOptions?.({ fast_mode: true });
+
+    expect(queryMock.applyFlagSettings).toHaveBeenCalledTimes(2);
+    expect(queryMock.applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: true });
+
+    await session.close();
+  });
+
+  test("fast mode survives a daemon restart through the stored providerOptions", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "claude-fast-restart-"));
+    const storagePath = path.join(root, "agents");
+    const makeClient = () => {
+      const mock = createQueryMock();
+      const client = new ClaudeAgentClient({
+        logger,
+        queryFactory: mock.queryFactory,
+        resolveBinary: async () => "/test/claude/bin",
+      });
+      return { ...mock, client };
+    };
+    const agentId = "00000000-0000-4000-8000-0000000000f1";
+    const before = makeClient();
+    const storage = new AgentStorage(storagePath, logger);
+    const manager = new AgentManager({
+      clients: { claude: before.client },
+      registry: storage,
+      logger,
+    });
+    try {
+      await manager.createAgent(
+        { provider: "claude", cwd: root, model: "claude-opus-4-8" },
+        agentId,
+        { workspaceId: undefined },
+      );
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+      await manager.closeAgent(agentId);
+      await manager.flush();
+      await storage.flush();
+
+      const after = makeClient();
+      const restartedStorage = new AgentStorage(storagePath, logger);
+      const restarted = new AgentManager({
+        clients: { claude: after.client },
+        registry: restartedStorage,
+        logger,
+      });
+      const agent = await ensureAgentLoaded(agentId, {
+        agentManager: restarted,
+        agentStorage: restartedStorage,
+        logger,
+      });
+      const session = (agent as unknown as { session: { ensureQuery(): Promise<unknown> } | null })
+        .session;
+      await session?.ensureQuery();
+
+      expect(restarted.getAgent(agentId)?.config.providerOptions).toEqual({ fast_mode: true });
+      expect(after.queryFactory.mock.calls[0]?.[0].options.settings).toMatchObject({
+        fastMode: true,
+      });
+      await restarted.closeAgent(agentId);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("normalizeClaudeAskUserQuestionUpdatedInput", () => {
@@ -2717,8 +3206,13 @@ describe("ClaudeAgentSession context window usage", () => {
     await session.startTurn("turn", { clientMessageId: "client-message-1" });
     await new Promise((resolve) => setTimeout(resolve, 0));
 
-    expect(events.slice(0, 2).map((event) => event.type)).toEqual(["turn_started", "timeline"]);
-    expect(events[1]).toMatchObject({
+    const started = events.findIndex((event) => event.type === "turn_started");
+    const userMessage = events.findIndex(
+      (event) => event.type === "timeline" && event.item.type === "user_message",
+    );
+    expect(started).toBeGreaterThanOrEqual(0);
+    expect(userMessage).toBeGreaterThan(started);
+    expect(events[userMessage]).toMatchObject({
       type: "timeline",
       item: { type: "user_message", clientMessageId: "client-message-1" },
     });
@@ -2789,7 +3283,7 @@ describe("ClaudeAgentSession context window usage", () => {
     expect(persistedQueryFactory.mock.calls[0]?.[0].options.persistSession).toBe(true);
   });
 
-  test("classifies Claude root-only commands separately from inline skills", async () => {
+  test("classifies Claude root-only commands separately from inline skills and hides internal ones", async () => {
     const queryFactory = vi.fn(({ prompt }: { prompt: AsyncIterable<unknown> }) => {
       void prompt;
       return {
@@ -2822,6 +3316,11 @@ describe("ClaudeAgentSession context window usage", () => {
             description: "Start a new session with empty context",
             argumentHint: "",
           },
+          {
+            name: "__remote-workflow",
+            description: "Run a remote workflow (server-launched sessions only)",
+            argumentHint: "",
+          },
         ],
         rewindFiles: async () => ({ canRewind: true }),
         [Symbol.asyncIterator]() {
diff --git a/packages/server/src/server/agent/providers/claude/agent.ts b/packages/server/src/server/agent/providers/claude/agent.ts
index 94496f8e06..6309553b79 100644
--- a/packages/server/src/server/agent/providers/claude/agent.ts
+++ b/packages/server/src/server/agent/providers/claude/agent.ts
@@ -1,6 +1,8 @@
 import { setImmediate } from "node:timers/promises";
 import { ClaudeRuntimeSafety } from "./runtime-safety.js";
-import { validateProviderOptions } from "../../provider-options.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../../provider-options.js";
 import type { ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -65,7 +67,7 @@ import { foldSubagentObservations, type SubagentObservation } from "./subagents/
 import { observeReplayWorkflows } from "./subagents/workflow-replay-source.js";
 import { limitAgentTimelineItemContent } from "../../agent-timeline-content.js";
 import { readClaudeWorkflowResultFile } from "./subagents/workflow-output.js";
-import { buildClaudeFeatures, claudeModelSupportsFastMode } from "./feature-definitions.js";
+import { buildClaudeControls, claudeModelSupportsFastMode } from "./feature-definitions.js";
 import {
   buildBinaryDiagnosticRows,
   buildCommandResolutionDiagnosticRows,
@@ -82,6 +84,7 @@ import { renderPromptAttachmentAsText } from "../../prompt-attachments.js";
 import { discoverClaudeModels } from "./model-discovery.js";
 import { claudeQuery, type ClaudeOptions, type ClaudeQueryFactory } from "./query.js";
 import {
+  findSteeredMessageParent,
   realClaudeRewindSdk,
   revertClaudeConversation,
   revertClaudeFiles,
@@ -103,7 +106,8 @@ import {
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateSessionOptions,
-  type AgentFeature,
+  type AgentDraftControls,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -444,6 +448,12 @@ interface SlashCommandInvocation {
   rawInput: string;
 }
 
+// Claude Code reserves `__`-prefixed commands for its own server-launched sessions
+// (for example `/__remote-workflow`); a user cannot run them from a Paseo agent.
+function isClaudeInternalSlashCommand(commandName: string): boolean {
+  return commandName.startsWith("__");
+}
+
 function classifyClaudeSlashCommand(commandName: string): AgentSlashCommand["kind"] {
   // Claude exposes commands and skills as one flat SDK list, without structured source
   // metadata. Keep obvious root-only/session controls out of inline autocomplete and
@@ -1754,12 +1764,11 @@ export class ClaudeAgentClient implements AgentClient {
     });
   }
 
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
-    const claudeConfig = this.assertConfig(config);
-    return buildClaudeFeatures({
-      modelId: claudeConfig.model,
-      fastModeEnabled: claudeConfig.featureValues?.fast_mode === true,
-    });
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    return {
+      controls: buildClaudeControls(this.assertConfig(config).model),
+      options: config.providerOptions ?? {},
+    };
   }
 
   async listImportableSessions(
@@ -2296,6 +2305,7 @@ class ClaudeAgentSession implements AgentSession {
   private readonly resolveBinary: () => Promise<string>;
   private query: Query | null = null;
   private readonly runtimeSafety = new ClaudeRuntimeSafety();
+  private readonly backgroundStops = new Map<string, (outcome: string) => void>();
   private processingSdkMessages = 0;
   private readonly harnessEnvironment: Record<string, string>;
   private readonly usageSessionKey = randomUUID();
@@ -2373,6 +2383,7 @@ class ClaudeAgentSession implements AgentSession {
   private historySessionId: string | null = null;
   private replayingHistory = false;
   private turnState: TurnState = "idle";
+  private readonly turnNamespace = randomUUID();
   private nextTurnOrdinal = 1;
   private cancelCurrentTurn: (() => void) | null = null;
   private cachedRuntimeInfo: AgentRuntimeInfo | null = null;
@@ -2382,6 +2393,8 @@ class ClaudeAgentSession implements AgentSession {
   private compactionMarkerOpen = false;
   private queryPumpPromise: Promise<void> | null = null;
   private queryRestartNeeded = false;
+  /** True from the moment a query's launch options are copied until the query exists. */
+  private queryStarting = false;
   private pendingInterruptAbort = false;
   /**
    * Whether Claude's main session is inside one of its own turns: set by system/init and by a
@@ -2391,6 +2404,12 @@ class ClaudeAgentSession implements AgentSession {
   private mainTurnInFlight = false;
   private foregroundHasVisibleActivity = false;
   private activeTurnHasAssistantText = false;
+  /**
+   * The reply Claude Code writes when a turn stops on an API error ("You've hit your session
+   * limit", "API Error: 529 ..."), held back until the result says whether the turn failed: a
+   * failed turn shows the same text as its error, so showing both would repeat it.
+   */
+  private withheldErrorReply: AgentTimelineItem[] = [];
   private readonly contextUsage: ClaudeContextUsageState;
   private userMessageIds: string[] = [];
   private readonly emittedUserMessageIds = new Set<string>();
@@ -2399,6 +2418,7 @@ class ClaudeAgentSession implements AgentSession {
   private pendingFreshSessionId: string | null = null;
   private recentStderr = "";
   private closed = false;
+  readonly openOptionsPatch: Record<string, unknown> = {};
 
   constructor(config: ClaudeAgentConfig, options: ClaudeAgentSessionOptions) {
     this.config = config;
@@ -2442,17 +2462,21 @@ class ClaudeAgentSession implements AgentSession {
     if (this.currentMode !== "plan") {
       this.planResumeMode = this.currentMode;
     }
+
+    // Fast cannot run on this model, so the session opens with it off. Off rather than removed
+    // keeps a `config.json` default of `fast_mode: true` from filling it back in.
+    if (config.providerOptions.fast_mode === true && !claudeModelSupportsFastMode(config.model)) {
+      this.config.providerOptions = { ...config.providerOptions, fast_mode: false };
+      this.openOptionsPatch = { fast_mode: false };
+    }
   }
 
   get id(): string | null {
     return this.claudeSessionId;
   }
 
-  get features(): AgentFeature[] {
-    return buildClaudeFeatures({
-      modelId: this.config.model,
-      fastModeEnabled: this.config.featureValues?.fast_mode === true,
-    });
+  get controls(): AgentOptionControl[] {
+    return buildClaudeControls(this.config.model);
   }
 
   async getRuntimeInfo(): Promise<AgentRuntimeInfo> {
@@ -2462,7 +2486,7 @@ class ClaudeAgentSession implements AgentSession {
     const info: AgentRuntimeInfo = {
       provider: "claude",
       sessionId: this.claudeSessionId,
-      model: this.lastOptionsModel,
+      model: this.lastOptionsModel ?? this.config.model ?? null,
       modeId: this.currentMode ?? null,
       ...(this.lastRuntimeModel
         ? {
@@ -2533,6 +2557,7 @@ class ClaudeAgentSession implements AgentSession {
     this.activeForegroundTurnId = turnId;
     this.foregroundHasVisibleActivity = false;
     this.activeTurnHasAssistantText = false;
+    this.withheldErrorReply = [];
     this.contextUsage.beginTurn();
     this.transitionTurnState("foreground", "foreground turn started");
     this.clearRecentStderr();
@@ -2579,6 +2604,7 @@ class ClaudeAgentSession implements AgentSession {
       this.activeForegroundQuery = this.query;
       this.activeForegroundInput = this.input;
       this.startQueryPump();
+      this.runtimeSafety.notePromptSent();
       this.input.push(sdkMessage);
       setTimeout(() => {
         if (this.activeForegroundTurnId === turnId) {
@@ -2630,7 +2656,7 @@ class ClaudeAgentSession implements AgentSession {
       return { status: "unavailable" };
     }
     this.enqueueSteer(input, message, options.clearPendingPermissions === true);
-    return { status: "accepted" };
+    return { status: "accepted", ...(message.uuid ? { providerMessageId: message.uuid } : {}) };
   }
 
   private enqueueSteer(
@@ -2664,6 +2690,33 @@ class ClaudeAgentSession implements AgentSession {
     };
   }
 
+  async stopBackgroundWork(id: string): Promise<void> {
+    const query = this.query;
+    if (!query || !this.runtimeSafety.canStop(id))
+      throw new Error("Background work is no longer available");
+    if (this.backgroundStops.has(id)) throw new Error("Stop is already pending");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let finish!: (outcome: string) => void;
+    const outcome = new Promise<string>((resolve) => {
+      finish = resolve;
+      this.backgroundStops.set(id, resolve);
+    });
+    try {
+      const result = await Promise.race([
+        Promise.all([query.stopTask(id), outcome]).then(([, value]) => value),
+        outcome.then((value) => (value === "stopped" ? new Promise<string>(() => {}) : value)),
+        new Promise<string>((resolve) => {
+          timer = setTimeout(() => resolve("timeout"), 15000);
+        }),
+      ]);
+      if (result !== "stopped") throw new Error(`Background work stop: ${result}`);
+      if (this.query !== query) throw new Error("Background work connection changed");
+    } finally {
+      clearTimeout(timer);
+      if (this.backgroundStops.get(id) === finish) this.backgroundStops.delete(id);
+    }
+  }
+
   async interrupt(): Promise<void> {
     if (this.cancelCurrentTurn) {
       this.cancelCurrentTurn();
@@ -2743,15 +2796,27 @@ class ClaudeAgentSession implements AgentSession {
     this.currentMode = normalized;
   }
 
-  async setModel(modelId: string | null): Promise<void> {
+  async setModel(modelId: string | null): Promise<{ model: string | null }> {
     const normalizedModelId =
       typeof modelId === "string" && modelId.trim().length > 0 ? modelId.trim() : null;
     const activeQuery = await this.ensureQuery();
     await activeQuery.setModel(normalizedModelId ?? undefined);
     this.config.model = normalizedModelId ?? undefined;
     this.reconcileThinkingOptionForModel(normalizedModelId);
-    if (!claudeModelSupportsFastMode(this.config.model) && this.config.featureValues?.fast_mode) {
-      await this.applyFastModeFeature(false, activeQuery);
+    if (this.config.providerOptions.fast_mode) {
+      const supported = claudeModelSupportsFastMode(this.config.model);
+      await activeQuery.applyFlagSettings({ fastMode: supported });
+      if (!supported) {
+        // Fast cannot run on this model. Reporting it off rather than removed keeps a
+        // `config.json` default of `fast_mode: true` from filling it back in.
+        this.config.providerOptions = { ...this.config.providerOptions, fast_mode: false };
+        this.pushEvent({
+          type: "options_changed",
+          provider: "claude",
+          patch: { fast_mode: false },
+        });
+      }
+      this.cachedRuntimeInfo = null;
     }
     this.contextUsage.setInitialContextWindowMaxTokens(
       getClaudeContextWindowMaxTokens(this.config.model),
@@ -2761,6 +2826,7 @@ class ClaudeAgentSession implements AgentSession {
     this.cachedRuntimeInfo = null;
     // Model change affects persistence metadata, so invalidate cached handle.
     this.persistence = null;
+    return { model: this.lastOptionsModel ?? this.config.model ?? null };
   }
 
   private reconcileThinkingOptionForModel(modelId: string | null): void {
@@ -2803,31 +2869,36 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    if (featureId !== "fast_mode") {
-      throw new Error(`Unknown Claude feature: ${featureId}`);
+  async applyOptions(options: ProviderOptions): Promise<void> {
+    // Every option but Fast is read when the query is built, and replacing a started query would
+    // end its background work, so once it exists only Fast can change.
+    if (this.query || this.queryStarting) {
+      assertChangesAreLive({
+        provider: "claude",
+        patch: options,
+        current: this.config.providerOptions,
+        live: ["fast_mode"],
+      });
     }
-
-    const enabled = Boolean(value);
-    if (enabled && !claudeModelSupportsFastMode(this.config.model)) {
+    const providerOptions =
+      validateProviderOptions(
+        "claude",
+        ClaudeProviderOptionsSchema,
+        applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+      ) ?? {};
+    if (providerOptions.fast_mode === true && !claudeModelSupportsFastMode(this.config.model)) {
       throw new Error(
         `Claude fast mode is not available for model '${this.config.model ?? "default"}'`,
       );
     }
-
-    await this.applyFastModeFeature(enabled);
-  }
-
-  private async applyFastModeFeature(enabled: boolean, query?: Query): Promise<void> {
-    this.config.featureValues = {
-      ...this.config.featureValues,
-      fast_mode: enabled,
-    };
-    const activeQuery = query ?? this.query;
-    if (activeQuery) {
-      await activeQuery.applyFlagSettings({ fastMode: enabled });
+    const fastModeChanged =
+      (providerOptions.fast_mode === true) !== (this.config.providerOptions.fast_mode === true);
+    if (fastModeChanged) {
+      await this.query?.applyFlagSettings({ fastMode: providerOptions.fast_mode === true });
+      this.cachedRuntimeInfo = null;
     }
-    this.cachedRuntimeInfo = null;
+    // Held until the runtime accepts, so a rejected change is retried instead of skipped.
+    this.config.providerOptions = providerOptions;
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
@@ -3013,7 +3084,9 @@ class ClaudeAgentSession implements AgentSession {
     this.closed = true;
     await this.ensureHistoryReady();
     this.rejectAllPendingPermissions(new Error("Claude session closed"));
-    this.cancelCurrentTurn?.();
+    // AgentManager settles the run after runtime release. Preserve cleanup records
+    // without reporting this closure as an explicit turn cancellation.
+    this.flushPendingToolCalls();
     this.subscribers.clear();
     this.activeForegroundTurnId = null;
     this.activeForegroundQuery = null;
@@ -3080,6 +3153,7 @@ class ClaudeAgentSession implements AgentSession {
     const commands = await q.supportedCommands();
     const commandMap = new Map<string, AgentSlashCommand>();
     for (const cmd of commands) {
+      if (isClaudeInternalSlashCommand(cmd.name)) continue;
       if (!commandMap.has(cmd.name)) {
         commandMap.set(cmd.name, {
           name: cmd.name,
@@ -3099,7 +3173,7 @@ class ClaudeAgentSession implements AgentSession {
     let target: ClaudeConversationRewindTarget;
     try {
       await this.ensureHistoryReady();
-      target = this.resolveConversationRewindTarget(input.messageId);
+      target = await this.resolveConversationRewindTarget(input.messageId);
     } catch (error) {
       throw RewindNotAppliedError.from(error);
     }
@@ -3457,12 +3531,25 @@ class ClaudeAgentSession implements AgentSession {
     return messageId;
   }
 
-  private resolveConversationRewindTarget(messageId: string): ClaudeConversationRewindTarget {
+  private async resolveConversationRewindTarget(
+    messageId: string,
+  ): Promise<ClaudeConversationRewindTarget> {
     const targetUserMessageId = this.resolveClaudeMessageId(messageId);
     const index = this.rewindTurnAnchors.findIndex(
       (anchor) => anchor.userMessageId === targetUserMessageId,
     );
     if (index < 0) {
+      // A message steered into a running turn opens no turn of its own.
+      const transcriptPath = this.claudeSessionId
+        ? await this.resolveHistoryPath(this.claudeSessionId)
+        : null;
+      const steerParent = transcriptPath
+        ? await findSteeredMessageParent(transcriptPath, targetUserMessageId)
+        : null;
+      if (steerParent) {
+        // The fork point is just before the steered message, so exactly it and what followed go.
+        return { kind: "fork", messageId: steerParent, cut: { kind: "at_target" } };
+      }
       throw new Error(`Claude rewind target ${messageId} is not in the tracked conversation`);
     }
 
@@ -3491,6 +3578,7 @@ class ClaudeAgentSession implements AgentSession {
     const oldQuery = this.query;
     if (!oldQuery) return;
     const oldInput = this.input;
+    for (const finish of this.backgroundStops.values()) finish("connection lost");
     // Null out query/input BEFORE awaiting the old iterator's return so the
     // old pump sees this.query !== activeQuery and skips failActiveTurns.
     this.query = null;
@@ -3539,10 +3627,21 @@ class ClaudeAgentSession implements AgentSession {
     this.persistence = null;
 
     const input = createAsyncMessageInput<SDKUserMessage>();
-    const options = await this.buildOptions(launchMode);
+    // buildOptions copies the launch options before it waits, so from here they are fixed.
+    this.queryStarting = true;
+    let options: ClaudeOptions;
+    try {
+      options = await this.buildOptions(launchMode);
+      // Closure can finish while launch options are being prepared.
+      if (this.closed) throw new Error("Claude session is closed");
+    } catch (error) {
+      this.queryStarting = false;
+      throw error;
+    }
     this.logger.debug({ options: summarizeClaudeOptionsForLog(options) }, "claude query");
     this.input = input;
     this.runtimeSafety.reset();
+    this.dispatchEvents([{ type: "background_work", provider: "claude", items: null }]);
     // A fresh Claude process has no turn of its own in flight.
     this.mainTurnInFlight = false;
     this.query = claudeQuery(
@@ -3557,6 +3656,7 @@ class ClaudeAgentSession implements AgentSession {
         },
       },
     );
+    this.queryStarting = false;
     const fastMode = this.resolveFastModeSetting();
     if (fastMode !== null) {
       await this.query.applyFlagSettings({ fastMode });
@@ -3676,10 +3776,9 @@ class ClaudeAgentSession implements AgentSession {
   private async buildOptions(permissionMode: PermissionMode): Promise<ClaudeOptions> {
     const { thinking, effort, ultracode } = this.resolveThinkingConfig();
     const appendedSystemPrompt = this.buildAppendedSystemPrompt();
-    const providerOptions = applyClaudeToolPolicy(
-      this.config.providerOptions,
-      this.config.toolPolicy,
-    );
+    // `fast_mode` is a composer control the provider applies through flag settings.
+    const { fast_mode: _fastMode, ...sdkProviderOptions } = this.config.providerOptions;
+    const providerOptions = applyClaudeToolPolicy(sdkProviderOptions, this.config.toolPolicy);
     const settingsOptions = await this.buildSettingsOptions(providerOptions, { ultracode });
     const sdkEnv = this.harnessEnvironment;
     assertClaudeModeCanRun(permissionMode, sdkEnv);
@@ -3798,7 +3897,7 @@ class ClaudeAgentSession implements AgentSession {
     if (!claudeModelSupportsFastMode(this.config.model)) {
       return null;
     }
-    return this.config.featureValues?.fast_mode === true;
+    return this.config.providerOptions.fast_mode === true;
   }
 
   private normalizeMcpServers(
@@ -3955,7 +4054,7 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   private createTurnId(owner: "foreground" | "autonomous"): string {
-    return `${owner}-turn-${this.nextTurnOrdinal++}`;
+    return `${owner}-turn-${this.turnNamespace}-${this.nextTurnOrdinal++}`;
   }
 
   private isTerminalTurnEvent(event: AgentStreamEvent): boolean {
@@ -4138,11 +4237,15 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   private failRunningRuntimeTasks(): void {
-    this.dispatchEvents(
-      foldSubagentObservations(this.taskProtocolSource.failRunningTasks()).map(
+    for (const finish of this.backgroundStops.values()) finish("connection lost");
+    this.runtimeSafety.retire();
+    this.dispatchEvents([
+      ...foldSubagentObservations(this.taskProtocolSource.failRunningTasks()).map(
         (event): AgentStreamEvent => ({ type: "provider_subagent", provider: "claude", event }),
       ),
-    );
+      // The SDK resets its background task set when the CLI process (re)starts.
+      { type: "background_work", provider: "claude", items: null },
+    ]);
   }
 
   private startQueryPump(): void {
@@ -4210,12 +4313,19 @@ class ClaudeAgentSession implements AgentSession {
       if (!this.ownsQuery(activeQuery)) return true;
       this.processingSdkMessages++;
       try {
-        this.runtimeSafety.observe(message);
+        const backgroundWork = this.runtimeSafety.observe(message);
+        if (message.type === "system" && message.subtype === "task_notification")
+          this.backgroundStops.get(message.task_id)?.(message.status);
         logRawMessage(message);
         consecutiveInterruptAbortRecoveries = 0;
         if (await this.handleMissingResumedConversation(message, activeQuery)) return true;
         if (!this.ownsQuery(activeQuery)) return true;
         await this.routeSdkMessageFromPump(message);
+        if (!this.ownsQuery(activeQuery)) return true;
+        if (backgroundWork && this.runtimeSafety.isCurrentInventory(backgroundWork))
+          this.dispatchEvents([
+            { type: "background_work", provider: "claude", items: backgroundWork },
+          ]);
         return false;
       } finally {
         this.processingSdkMessages--;
@@ -4441,6 +4551,21 @@ class ClaudeAgentSession implements AgentSession {
               }) satisfies AgentStreamEvent,
           );
 
+    if (!readClaudeParentToolUseId(message)) {
+      if (message.type === "assistant" && message.error) {
+        this.withheldErrorReply.push(...assistantTimelineEvents.map((event) => event.item));
+        return messageEvents;
+      }
+      if (
+        message.type === "assistant" ||
+        message.type === "user" ||
+        message.type === "stream_event"
+      ) {
+        const released: AgentStreamEvent[] = [];
+        this.releaseWithheldErrorReply(released);
+        return [...released, ...messageEvents, ...assistantTimelineEvents];
+      }
+    }
     return [...messageEvents, ...assistantTimelineEvents];
   }
 
@@ -4837,6 +4962,13 @@ class ClaudeAgentSession implements AgentSession {
       this.appendTaskNotificationEvents(message, events);
       return;
     }
+    if (message.subtype === "background_tasks_changed") {
+      this.logger.debug(
+        { tasks: message.tasks.map(({ task_id, task_type }) => ({ task_id, task_type })) },
+        "claude.background_tasks_changed",
+      );
+      return;
+    }
     if (message.subtype === "task_progress") {
       return;
     }
@@ -4988,6 +5120,23 @@ class ClaudeAgentSession implements AgentSession {
     events: AgentStreamEvent[],
   ): void {
     const usage = this.convertUsage(message);
+    // Claude Code reports a turn that stopped on an API error (a usage limit, an overloaded or
+    // rejected request) as `success` with `is_error`, carrying the error text in `result`.
+    if (message.subtype === "success" && message.is_error) {
+      const withheld = this.withheldErrorReply;
+      this.withheldErrorReply = [];
+      const resultText = typeof message.result === "string" ? message.result.trim() : "";
+      const withheldText = withheld
+        .map((item) => (item.type === "assistant_message" ? item.text : ""))
+        .join("\n")
+        .trim();
+      if (usage) events.push({ type: "usage_updated", provider: "claude", usage });
+      events.push(...this.sidechainTracker.finishAll("failed"));
+      events.push(this.buildTurnFailedEvent(resultText || withheldText || "Claude run failed"));
+      return;
+    }
+    const releasedErrorReply = this.withheldErrorReply.length > 0;
+    this.releaseWithheldErrorReply(events);
     if (message.subtype === "success") {
       events.push(...this.sidechainTracker.finishAll("completed"));
       // Built-in slash commands (e.g. /voice, /usage, "Unknown command: …")
@@ -4997,7 +5146,12 @@ class ClaudeAgentSession implements AgentSession {
       // accounting from provider gateways does not duplicate streamed output.
       const resultText = typeof message.result === "string" ? message.result.trim() : "";
       const outputTokens = message.usage?.output_tokens;
-      if (resultText.length > 0 && outputTokens === 0 && !this.activeTurnHasAssistantText) {
+      if (
+        resultText.length > 0 &&
+        outputTokens === 0 &&
+        !this.activeTurnHasAssistantText &&
+        !releasedErrorReply
+      ) {
         events.push({
           type: "timeline",
           provider: "claude",
@@ -5015,10 +5169,19 @@ class ClaudeAgentSession implements AgentSession {
       "errors" in message && Array.isArray(message.errors) && message.errors.length > 0
         ? message.errors.join("\n")
         : "Claude run failed";
+    if (usage) events.push({ type: "usage_updated", provider: "claude", usage });
     events.push(...this.sidechainTracker.finishAll("failed"));
     events.push(this.buildTurnFailedEvent(errorMessage));
   }
 
+  private releaseWithheldErrorReply(events: AgentStreamEvent[]): void {
+    if (this.withheldErrorReply.length === 0) return;
+    for (const item of this.withheldErrorReply) {
+      events.push({ type: "timeline", item, provider: "claude" });
+    }
+    this.withheldErrorReply = [];
+  }
+
   private createClaudeSessionChangedNotice(
     oldSessionId: string,
     newSessionId: string,
@@ -5477,6 +5640,7 @@ class ClaudeAgentSession implements AgentSession {
         convertEntry: (entry) => this.convertHistoryEntry(entry),
       })),
     ];
+    this.taskProtocolSource.restore(subagentReplay.restored);
     const restoredProviderSubagentIds = new Set(
       observations
         .filter((observation) => observation.kind === "declared")
@@ -6466,6 +6630,10 @@ function convertClaudeHistoryEntryPreamble(
   if (entry.type === "user" && isSyntheticHistoryUserEntry(entry)) {
     return { shortCircuit: [] };
   }
+  const steeredPrompt = readSteeredPromptHistoryItem(entry);
+  if (steeredPrompt) {
+    return { shortCircuit: [steeredPrompt] };
+  }
   // Only user and assistant records are conversation turns. Claude Code 2.1.x also journals each
   // API request as `api-request-blob` records whose message replays the system context.
   if (entry.type !== "user" && entry.type !== "assistant") {
@@ -6492,6 +6660,21 @@ function isProviderImageMessage(item: AgentTimelineItem): boolean {
   return item.type === "assistant_message" && isProviderImageMarkdown(item.text);
 }
 
+/**
+ * A message steered into a running turn. Claude Code gives it no user entry: it records a
+ * queued_command attachment in prompt mode, under the uuid Paseo minted for the message, which is
+ * also what a rewind to it resolves. The other modes carry task notifications, not user messages.
+ */
+function readSteeredPromptHistoryItem(entry: ClaudeHistoryEntry): AgentTimelineItem | null {
+  if (entry.type !== "attachment") return null;
+  const attachment = toObjectRecord(entry.attachment);
+  if (attachment?.type !== "queued_command" || attachment.commandMode !== "prompt") return null;
+  const text = extractUserMessageText(attachment.prompt);
+  if (!text) return null;
+  const messageId = readTrimmedString(attachment.source_uuid);
+  return { type: "user_message", text, ...(messageId ? { messageId } : {}) };
+}
+
 export async function convertClaudeHistoryEntry(
   entry: ClaudeHistoryEntry,
   mapBlocks: (
@@ -6855,40 +7038,79 @@ function normalizeClaudeSessionTitle(title: string | null): string | null {
 }
 
 const CLAUDE_CUSTOM_TITLE_TYPE = "custom-title";
+const CLAUDE_CUSTOM_TITLE_NEEDLE = Buffer.from(`"${CLAUDE_CUSTOM_TITLE_TYPE}"`);
+const CLAUDE_TITLE_SCAN_CHUNK_BYTES = 64 * 1024;
+
+function readClaudeCustomTitleFromRecord(record: Buffer): string | null {
+  // The needle also matches a prompt that quotes it, so a record still has to
+  // parse as a `custom-title` entry carrying a usable name. Records without the
+  // needle are never decoded, so a long one costs a byte search and nothing more.
+  if (!record.includes(CLAUDE_CUSTOM_TITLE_NEEDLE)) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(record.toString("utf8").trim());
+  } catch {
+    return null;
+  }
+  const entry = toObjectRecord(parsed);
+  if (!entry || entry.isSidechain || entry.type !== CLAUDE_CUSTOM_TITLE_TYPE) {
+    return null;
+  }
+  return normalizeClaudeSessionTitle(
+    typeof entry.customTitle === "string" ? entry.customTitle : null,
+  );
+}
 
 /**
  * The `custom-title` record is re-emitted every time the session is saved, so
- * the current name is the last usable one in the file. Searching backwards finds it without
- * walking the transcript, which matters because sessions reach tens of
- * megabytes.
+ * the current name is the last usable one in the file. Reading backwards a chunk
+ * at a time finds it without walking the transcript, which matters because
+ * sessions reach tens of megabytes, and never holds the file as one string, so a
+ * transcript past V8's maximum string length still imports.
  */
-function readLastClaudeCustomTitle(content: string): string | null {
-  const needle = `"${CLAUDE_CUSTOM_TITLE_TYPE}"`;
-  let at = content.lastIndexOf(needle);
-  while (at >= 0) {
-    const lineStart = content.lastIndexOf("\n", at) + 1;
-    const lineEnd = content.indexOf("\n", at);
-    const line = lineEnd === -1 ? content.slice(lineStart) : content.slice(lineStart, lineEnd);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line.trim());
-    } catch {
-      parsed = undefined;
-    }
-    const entry = toObjectRecord(parsed);
-    if (entry && !entry.isSidechain && entry.type === CLAUDE_CUSTOM_TITLE_TYPE) {
-      const title = normalizeClaudeSessionTitle(
-        typeof entry.customTitle === "string" ? entry.customTitle : null,
+async function readLastClaudeCustomTitle(filePath: string): Promise<string | null> {
+  const handle = await fsPromises.open(filePath, "r");
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) {
+      // Opening a directory succeeds on Windows even though reading it does not,
+      // so reject the way reading the transcript as a file would.
+      throw Object.assign(
+        new Error(`EISDIR: illegal operation on a directory, read '${filePath}'`),
+        { code: "EISDIR", path: filePath },
       );
-      if (title) {
-        return title;
-      }
     }
-    // The needle also matches a prompt that quotes it, and a record can carry no
-    // usable name, so keep looking backwards for one that does.
-    at = at <= 0 ? -1 : content.lastIndexOf(needle, at - 1);
+    let end = stats.size;
+    // Retain unfinished record pieces in reverse file order. Assemble each
+    // complete record once, so a large tool/image record costs linear work.
+    let pieces: Buffer[] = [];
+    while (end > 0) {
+      const length = Math.min(CLAUDE_TITLE_SCAN_CHUNK_BYTES, end);
+      const chunk = Buffer.alloc(length);
+      await handle.read(chunk, 0, length, end - length);
+      let recordEnd = chunk.length;
+      for (
+        let at = chunk.lastIndexOf(10);
+        at >= 0;
+        at = at === 0 ? -1 : chunk.lastIndexOf(10, at - 1)
+      ) {
+        pieces.push(chunk.subarray(at + 1, recordEnd));
+        const record = Buffer.concat(pieces.toReversed());
+        const title = readClaudeCustomTitleFromRecord(record);
+        if (title) return title;
+        pieces = [];
+        recordEnd = at;
+      }
+      if (recordEnd > 0) pieces.push(chunk.subarray(0, recordEnd));
+      end -= length;
+    }
+    // The first record in the file has no newline in front of it.
+    return readClaudeCustomTitleFromRecord(Buffer.concat(pieces.toReversed()));
+  } finally {
+    await handle.close();
   }
-  return null;
 }
 
 function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
@@ -6900,9 +7122,8 @@ async function readClaudeRenamedSessionTitle(input: {
   sessionId: string;
   configDir: string;
 }): Promise<string | null> {
-  let content: string;
   try {
-    content = await fsPromises.readFile(await claudeTranscriptPath(input), "utf8");
+    return await readLastClaudeCustomTitle(await claudeTranscriptPath(input));
   } catch (error) {
     // A session with no transcript on disk has no rename to carry over. Every
     // other read failure is a real fault and stays explicit.
@@ -6911,7 +7132,6 @@ async function readClaudeRenamedSessionTitle(input: {
     }
     throw error;
   }
-  return readLastClaudeCustomTitle(content);
 }
 
 function normalizeImportablePromptPreview(text: string): string | null {
diff --git a/packages/server/src/server/agent/providers/claude/background-work.test.ts b/packages/server/src/server/agent/providers/claude/background-work.test.ts
new file mode 100644
index 0000000000..18c1265f28
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/background-work.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, test } from "vitest";
+
+import { toBackgroundWorkInputs } from "./background-work.js";
+
+describe("toBackgroundWorkInputs", () => {
+  test("maps shells, drops subagents and workflows", () => {
+    expect(
+      toBackgroundWorkInputs([
+        { task_id: "bash-1", task_type: "local_bash", description: "sleep 20" },
+        { task_id: "agent-1", task_type: "local_agent", description: "Explore" },
+        { task_id: "wf-1", task_type: "local_workflow", description: "Run the spec workflow" },
+        { task_id: "x-1", task_type: "remote_something", description: "  " },
+        { task_id: "bash-2", task_type: "local_bash" },
+      ]),
+    ).toEqual([
+      { id: "bash-1", kind: "shell", description: "sleep 20", canStop: true },
+      { id: "x-1", kind: "other", description: null, canStop: false },
+      { id: "bash-2", kind: "shell", description: null, canStop: true },
+    ]);
+  });
+});
diff --git a/packages/server/src/server/agent/providers/claude/background-work.ts b/packages/server/src/server/agent/providers/claude/background-work.ts
new file mode 100644
index 0000000000..9727fb994d
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/background-work.ts
@@ -0,0 +1,36 @@
+import type { AgentBackgroundWorkInput } from "../../background-work/index.js";
+import { CLAUDE_SUBAGENT_TASK_TYPE, CLAUDE_WORKFLOW_TASK_TYPE } from "./subagents/live-source.js";
+
+export interface ClaudeBackgroundTask {
+  task_id: string;
+  task_type: string;
+  /** The user's `claude` binary can differ from the SDK typings, so this is read defensively. */
+  description?: unknown;
+}
+
+/** Subagents and workflows already live in the subagents track. */
+const SUBAGENT_TASK_TYPES = new Set([CLAUDE_SUBAGENT_TASK_TYPE, CLAUDE_WORKFLOW_TASK_TYPE]);
+
+/** Maps `background_tasks_changed.tasks` to provider-agnostic background work. */
+export function toBackgroundWorkInputs(
+  tasks: readonly ClaudeBackgroundTask[],
+): AgentBackgroundWorkInput[] {
+  return tasks
+    .filter((task) => !SUBAGENT_TASK_TYPES.has(task.task_type))
+    .map((task) => ({
+      id: task.task_id,
+      kind: toKind(task.task_type),
+      canStop: task.task_type === "local_bash",
+      description: readDescription(task.description),
+    }));
+}
+
+/** The inventory owner refines shell entries when launch metadata identifies a monitor. */
+function toKind(taskType: string): string {
+  if (taskType === "local_bash") return "shell";
+  return "other";
+}
+
+function readDescription(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
diff --git a/packages/server/src/server/agent/providers/claude/feature-definitions.ts b/packages/server/src/server/agent/providers/claude/feature-definitions.ts
index 63feb4088c..46df4d94bb 100644
--- a/packages/server/src/server/agent/providers/claude/feature-definitions.ts
+++ b/packages/server/src/server/agent/providers/claude/feature-definitions.ts
@@ -1,11 +1,11 @@
-import type { AgentFeature, AgentFeatureToggle } from "../../agent-sdk-types.js";
+import type { AgentOptionControl, AgentOptionToggleControl } from "../../agent-sdk-types.js";
 import { claudeManifestModelSupportsFastMode } from "./model-manifest.js";
 
-export const CLAUDE_FAST_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
+export const CLAUDE_FAST_MODE_CONTROL: AgentOptionToggleControl = {
   type: "toggle",
-  id: "fast_mode",
+  key: "fast_mode",
   label: "Fast",
-  description: "Lower latency Opus responses at higher token cost",
+  description: "Lower latency responses at higher token cost",
   tooltip: "Toggle fast mode",
   icon: "zap",
 };
@@ -14,18 +14,6 @@ export function claudeModelSupportsFastMode(modelId: string | null | undefined):
   return claudeManifestModelSupportsFastMode(modelId);
 }
 
-export function buildClaudeFeatures(input: {
-  modelId: string | null | undefined;
-  fastModeEnabled: boolean;
-}): AgentFeature[] {
-  if (!claudeModelSupportsFastMode(input.modelId)) {
-    return [];
-  }
-
-  return [
-    {
-      ...CLAUDE_FAST_MODE_FEATURE,
-      value: input.fastModeEnabled,
-    },
-  ];
+export function buildClaudeControls(modelId: string | null | undefined): AgentOptionControl[] {
+  return claudeModelSupportsFastMode(modelId) ? [{ ...CLAUDE_FAST_MODE_CONTROL }] : [];
 }
diff --git a/packages/server/src/server/agent/providers/claude/model-manifest.ts b/packages/server/src/server/agent/providers/claude/model-manifest.ts
index 45a5441109..d73ae34f7d 100644
--- a/packages/server/src/server/agent/providers/claude/model-manifest.ts
+++ b/packages/server/src/server/agent/providers/claude/model-manifest.ts
@@ -58,6 +58,17 @@ export const CLAUDE_MODEL_MANIFEST = [
     supportsThinkingDisabled: true,
     supportsFastMode: true,
   },
+  {
+    id: "claude-mythos-5-2",
+    label: "Mythos 5.2",
+    requiresDiscovery: true,
+    description: "Mythos 5.2 · Requires verified access",
+    minimumClaudeCodeVersion: "2.1.321",
+    defaultThinkingOptionId: "medium",
+    contextWindowMaxTokens: 1_000_000,
+    effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
+    supportsFastMode: true,
+  },
   {
     id: "claude-mythos-5-1",
     label: "Mythos 5.1",
@@ -66,10 +77,20 @@ export const CLAUDE_MODEL_MANIFEST = [
     contextWindowMaxTokens: 1_000_000,
     effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
   },
+  {
+    id: "claude-fable-5-2",
+    label: "Fable 5.2",
+    description: "Fable 5.2 · Most powerful model",
+    minimumClaudeCodeVersion: "2.1.321",
+    defaultThinkingOptionId: "medium",
+    contextWindowMaxTokens: 1_000_000,
+    effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
+    supportsFastMode: true,
+  },
   {
     id: "claude-fable-5-1",
     label: "Fable 5.1",
-    description: "Fable 5.1 · Most powerful model",
+    description: "Fable 5.1 · Previous release",
     contextWindowMaxTokens: 1_000_000,
     effortLevels: CLAUDE_EFFORT_LEVELS.xhigh,
   },
diff --git a/packages/server/src/server/agent/providers/claude/models.test.ts b/packages/server/src/server/agent/providers/claude/models.test.ts
index 0daa5e533a..1287fd6335 100644
--- a/packages/server/src/server/agent/providers/claude/models.test.ts
+++ b/packages/server/src/server/agent/providers/claude/models.test.ts
@@ -61,17 +61,23 @@ async function createClaudeConfigDirWithRawSettings(settings: string): Promise<s
   return configDir;
 }
 
-function createCatalogClient(claudeCodeVersion = "2.1.293"): ClaudeAgentClient {
+function createCatalogClient(claudeCodeVersion = "2.1.321"): ClaudeAgentClient {
   return new ClaudeAgentClient({
     logger: createTestLogger(),
     resolveVersion: async () => claudeCodeVersion,
     discoverModels: async () => [
       {
         value: "mythos",
-        resolvedModel: "claude-mythos-5-1",
+        resolvedModel: "claude-mythos-5-2",
         displayName: "Mythos",
         description: "",
       },
+      {
+        value: "claude-mythos-5-1",
+        resolvedModel: "claude-mythos-5-1",
+        displayName: "Mythos 5.1",
+        description: "",
+      },
     ],
   });
 }
@@ -82,7 +88,9 @@ describe("getClaudeModels", () => {
     expect(models.map((m) => m.id)).toEqual([
       "claude-opus-5-5",
       "claude-opus-5",
+      "claude-mythos-5-2",
       "claude-mythos-5-1",
+      "claude-fable-5-2",
       "claude-fable-5-1",
       "claude-fable-5",
       "claude-fable-5[1m]",
@@ -118,7 +126,9 @@ describe("getClaudeModels", () => {
       new Map([
         ["claude-opus-5-5", 1_000_000],
         ["claude-opus-5", 1_000_000],
+        ["claude-mythos-5-2", 1_000_000],
         ["claude-mythos-5-1", 1_000_000],
+        ["claude-fable-5-2", 1_000_000],
         ["claude-fable-5-1", 1_000_000],
         ["claude-fable-5", 1_000_000],
         ["claude-fable-5[1m]", 1_000_000],
@@ -163,6 +173,12 @@ describe("getClaudeModels", () => {
     expect(getClaudeModels("2.1.293").find((model) => model.isDefault)?.id).toBe("claude-opus-5-5");
   });
 
+  it("gates Fable 5.2 on Claude Code 2.1.321 without changing the default", () => {
+    expect(getClaudeModels("2.1.320").map((model) => model.id)).not.toContain("claude-fable-5-2");
+    expect(getClaudeModels("2.1.321").map((model) => model.id)).toContain("claude-fable-5-2");
+    expect(getClaudeModels("2.1.321").find((model) => model.isDefault)?.id).toBe("claude-opus-5-5");
+  });
+
   it("derives thinking options from model effort capabilities", () => {
     const models = new Map(getClaudeModels().map((model) => [model.id, model]));
 
@@ -232,6 +248,8 @@ describe("getClaudeModels", () => {
     ["claude-sonnet-5-20260101", true, "high"],
     ["claude-fable-5", false, "high"],
     ["claude-fable-5-1", false, "high"],
+    ["claude-fable-5-2", false, "medium"],
+    ["claude-mythos-5-2", false, "medium"],
     ["claude-haiku-5-5", true, "medium"],
     ["claude-haiku-5-5-20261007", true, "medium"],
     ["claude-haiku-4-5", false, undefined],
@@ -284,6 +302,31 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
     },
   );
 
+  it("offers Mythos 5.2 in place of Mythos 5.1 when Claude Code resolves mythos to 5.2", async () => {
+    const configDir = await createClaudeConfigDir({});
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      resolveVersion: async () => "2.1.321",
+      runtimeSettings: { env: { CLAUDE_CONFIG_DIR: configDir } },
+      discoverModels: async () => [
+        {
+          value: "mythos",
+          resolvedModel: "claude-mythos-5-2",
+          displayName: "Mythos",
+          description: "",
+        },
+      ],
+    });
+    const { models } = await client.fetchCatalog({
+      scope: "workspace",
+      cwd: configDir,
+      force: false,
+    });
+    expect(models.filter((model) => model.id.startsWith("claude-mythos-"))).toEqual([
+      findClaudeModel("claude-mythos-5-2"),
+    ]);
+  });
+
   it("preserves the curated catalog and explicitly configured models after discovery failure", async () => {
     const configDir = await createClaudeConfigDir({ model: "claude-mythos-5-1" });
     const client = new ClaudeAgentClient({
@@ -299,8 +342,8 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
       cwd: configDir,
       force: false,
     });
-    expect(models.filter((model) => model.id !== "claude-mythos-5-1")).toEqual(
-      getClaudeModels("2.1.293").filter((model) => model.id !== "claude-mythos-5-1"),
+    expect(models.filter((model) => !model.id.startsWith("claude-mythos-"))).toEqual(
+      getClaudeModels("2.1.293").filter((model) => !model.id.startsWith("claude-mythos-")),
     );
     expect(models.find((model) => model.id === "claude-mythos-5-1")).toEqual({
       ...findClaudeModel("claude-mythos-5-1"),
@@ -360,12 +403,26 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
     });
     expect(models.map((model) => model.id)).toEqual(
       getClaudeModels("2.1.293")
-        .filter((model) => model.id !== "claude-mythos-5-1")
+        .filter((model) => !model.id.startsWith("claude-mythos-"))
         .map((model) => model.id),
     );
   });
 
-  it("appends concrete models from Claude settings.json", async () => {
+  it("appends concrete models from Claude settings.json with thinking options", async () => {
+    const customModelThinkingOptions = [
+      { id: "low", label: "Low" },
+      { id: "medium", label: "Medium" },
+      { id: "high", label: "High", isDefault: true },
+      { id: "max", label: "Max" },
+    ];
+    const fableThinkingOptions = [
+      { id: "low", label: "Low" },
+      { id: "medium", label: "Medium" },
+      { id: "high", label: "High", isDefault: true },
+      { id: "xhigh", label: "Extra High" },
+      { id: "max", label: "Max" },
+      { id: CLAUDE_ULTRACODE_THINKING_OPTION_ID, label: "Ultra Code" },
+    ];
     const configDir = await createClaudeConfigDir({
       model: "us.anthropic.claude-opus-4-7[1m]",
       env: {
@@ -393,42 +450,49 @@ describe("ClaudeAgentClient.fetchCatalog", () => {
         id: "us.anthropic.claude-opus-4-7[1m]",
         label: "us.anthropic.claude-opus-4-7[1m]",
         description: "From Claude settings.json model",
+        thinkingOptions: customModelThinkingOptions,
       },
       {
         provider: "claude",
         id: "openrouter/anthropic/claude-sonnet-4.5",
         label: "openrouter/anthropic/claude-sonnet-4.5",
         description: "From Claude settings.json env.ANTHROPIC_MODEL",
+        thinkingOptions: customModelThinkingOptions,
       },
       {
         provider: "claude",
         id: "ollama/qwen3-coder",
         label: "ollama/qwen3-coder",
         description: "From Claude settings.json env.ANTHROPIC_SMALL_FAST_MODEL",
+        thinkingOptions: customModelThinkingOptions,
       },
       {
         provider: "claude",
         id: "claude-fable-5-1[1M]",
         label: "claude-fable-5-1[1M]",
         description: "From Claude settings.json env.ANTHROPIC_DEFAULT_FABLE_MODEL",
+        thinkingOptions: fableThinkingOptions,
       },
       {
         provider: "claude",
         id: "bedrock-opus-from-env",
         label: "bedrock-opus-from-env",
         description: "From Claude settings.json env.ANTHROPIC_DEFAULT_OPUS_MODEL",
+        thinkingOptions: customModelThinkingOptions,
       },
       {
         provider: "claude",
         id: "glm-5.1",
         label: "glm-5.1",
         description: "From Claude settings.json env.ANTHROPIC_DEFAULT_SONNET_MODEL",
+        thinkingOptions: customModelThinkingOptions,
       },
       {
         provider: "claude",
         id: "glm-5",
         label: "glm-5",
         description: "From Claude settings.json env.ANTHROPIC_DEFAULT_HAIKU_MODEL",
+        thinkingOptions: customModelThinkingOptions,
       },
     ]);
     expect(models.filter((model) => model.id === "claude-fable-5-1[1M]")).toHaveLength(1);
@@ -764,6 +828,44 @@ describe("Claude Fable 5.1 catalog", () => {
   });
 });
 
+describe("Claude Fable 5.2 catalog", () => {
+  it("offers one 1M model with medium default effort, always-on thinking, and fast mode", () => {
+    const models = getClaudeModels().filter((model) => model.id.startsWith("claude-fable-5-2"));
+    expect(models).toHaveLength(1);
+    expect(models[0]).toMatchObject({
+      id: "claude-fable-5-2",
+      label: "Fable 5.2",
+      contextWindowMaxTokens: 1_000_000,
+      defaultThinkingOptionId: "medium",
+    });
+    expect(models[0].thinkingOptions?.map((option) => option.id)).toEqual([
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+      CLAUDE_ULTRACODE_THINKING_OPTION_ID,
+    ]);
+    expect(claudeManifestModelSupportsFastMode("claude-fable-5-2")).toBe(true);
+  });
+
+  it.each([
+    "claude-fable-5-2[1m]",
+    "claude-fable-5-2-20261110",
+    "claude-fable-5-2-20261110[1m]",
+    "Fable 5.2",
+  ])("resolves %s to the single catalog entry", (id) => {
+    expect(findClaudeModel(id)?.id).toBe("claude-fable-5-2");
+  });
+
+  it.each(["claude-fable-5-2", "anthropic/claude-fable-5-2", "us.anthropic.claude-fable-5-2-v1:0"])(
+    "keeps runtime model %s from collapsing onto Fable 5",
+    (id) => {
+      expect(normalizeClaudeRuntimeModelId(id)).toBe("claude-fable-5-2");
+    },
+  );
+});
+
 describe("Claude Opus 5.5 catalog", () => {
   it("offers one Opus 5.5 entry with a 1M context window", () => {
     const opus55Models = getClaudeModels()
@@ -899,7 +1001,7 @@ describe("claudeManifestModelSupportsFastMode", () => {
 
 describe("Claude Mythos 5.1 catalog", () => {
   it("offers one 1M model with high default effort and always-on thinking", () => {
-    const models = getClaudeModels().filter((model) => model.id.startsWith("claude-mythos"));
+    const models = getClaudeModels().filter((model) => model.id.startsWith("claude-mythos-5-1"));
     expect(models).toHaveLength(1);
     expect(models[0]).toMatchObject({
       id: "claude-mythos-5-1",
@@ -944,6 +1046,61 @@ describe("Claude Mythos 5.1 catalog", () => {
   );
 });
 
+describe("Claude Mythos 5.2 catalog", () => {
+  it("stays hidden on Claude Code older than 2.1.321 even when advertised", async () => {
+    const configDir = await createClaudeConfigDir({});
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      resolveVersion: async () => "2.1.320",
+      runtimeSettings: { env: { CLAUDE_CONFIG_DIR: configDir } },
+      discoverModels: async () => [
+        {
+          value: "mythos",
+          resolvedModel: "claude-mythos-5-2",
+          displayName: "Mythos",
+          description: "",
+        },
+      ],
+    });
+
+    const { models } = await client.fetchCatalog({
+      scope: "workspace",
+      cwd: configDir,
+      force: false,
+    });
+
+    expect(models.some((model) => model.id === "claude-mythos-5-2")).toBe(false);
+  });
+
+  it("offers one 1M model with medium default effort, always-on thinking, and fast mode", () => {
+    const models = getClaudeModels().filter((model) => model.id.startsWith("claude-mythos-5-2"));
+    expect(models).toHaveLength(1);
+    expect(models[0]).toMatchObject({
+      id: "claude-mythos-5-2",
+      label: "Mythos 5.2",
+      contextWindowMaxTokens: 1_000_000,
+      defaultThinkingOptionId: "medium",
+    });
+    expect(models[0].thinkingOptions?.map((option) => option.id)).toEqual([
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+      CLAUDE_ULTRACODE_THINKING_OPTION_ID,
+    ]);
+    expect(claudeManifestModelSupportsFastMode("claude-mythos-5-2")).toBe(true);
+  });
+
+  it.each(["anthropic/claude-mythos-5-2", "us.anthropic.claude-mythos-5-2-v1:0"])(
+    "normalizes runtime identity without granting first-party capabilities: %s",
+    (id) => {
+      expect(normalizeClaudeRuntimeModelId(id)).toBe("claude-mythos-5-2");
+      expect(normalizeClaudeManifestModelId(id)).toBeNull();
+    },
+  );
+});
+
 describe("Claude model discovery process", () => {
   it("does not send a prompt or persist a session and closes after discovery", async () => {
     let closed = false;
diff --git a/packages/server/src/server/agent/providers/claude/models.ts b/packages/server/src/server/agent/providers/claude/models.ts
index 2a9b801fdb..80f5a38e68 100644
--- a/packages/server/src/server/agent/providers/claude/models.ts
+++ b/packages/server/src/server/agent/providers/claude/models.ts
@@ -83,7 +83,7 @@ export async function getClaudeModelsWithSettings(
     const manifestModel = getClaudeModels(claudeCodeVersion).find(
       (candidate) => candidate.id === model.id,
     );
-    models.push({ ...manifestModel, ...model });
+    models.push(resolveConfiguredClaudeModel({ ...manifestModel, ...model }));
   }
 
   return models;
diff --git a/packages/server/src/server/agent/providers/claude/options.ts b/packages/server/src/server/agent/providers/claude/options.ts
index 591accce19..3159a960cd 100644
--- a/packages/server/src/server/agent/providers/claude/options.ts
+++ b/packages/server/src/server/agent/providers/claude/options.ts
@@ -45,6 +45,8 @@ const SandboxFilesystemSchema = z
 // Claude Agent SDK Options, maintained against @anthropic-ai/claude-agent-sdk 0.3.246.
 export const ClaudeProviderOptionsSchema = z
   .object({
+    /** Composer control, not a Claude SDK option: the provider reads it and keeps it out of the SDK options. */
+    fast_mode: z.boolean().optional(),
     allowedTools: z.array(z.string()).optional(),
     disallowedTools: z.array(z.string()).optional(),
     additionalDirectories: z.array(z.string()).optional(),
diff --git a/packages/server/src/server/agent/providers/claude/rewind.test.ts b/packages/server/src/server/agent/providers/claude/rewind.test.ts
index 2d6d3853c2..226f41d39c 100644
--- a/packages/server/src/server/agent/providers/claude/rewind.test.ts
+++ b/packages/server/src/server/agent/providers/claude/rewind.test.ts
@@ -1,11 +1,20 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, test } from "vitest";
 import type { Query } from "@anthropic-ai/claude-agent-sdk";
 
 import {
+  findSteeredMessageParent,
   revertClaudeConversation,
   revertClaudeConversationAndFiles,
   revertClaudeFiles,
@@ -217,4 +226,96 @@ describe("Claude rewind against the Claude SDK", () => {
       "first reply",
     ]);
   });
+
+  test("forks just before a message steered into a running turn", async () => {
+    tempRoot = mkdtempSync(path.join(tmpdir(), "claude-rewind-steer-"));
+    delete process.env.CLAUDE_CONFIG_DIR;
+    const projectDir = path.join(tempRoot, "projects", "-repo");
+    mkdirSync(projectDir, { recursive: true });
+    const sessionId = randomUUID();
+    const firstUser = randomUUID();
+    const toolUse = randomUUID();
+    const toolResult = randomUUID();
+    const steeredMessage = randomUUID();
+    const queuedCommand = randomUUID();
+    const transcriptPath = path.join(projectDir, `${sessionId}.jsonl`);
+    writeTranscript(transcriptPath, sessionId, [
+      { type: "user", uuid: firstUser, parentUuid: null, text: "first" },
+      { type: "assistant", uuid: toolUse, parentUuid: firstUser, text: "running a tool" },
+      { type: "user", uuid: toolResult, parentUuid: toolUse, text: "tool output" },
+      // What Claude Code writes when it reads a steered message between two tool calls.
+      JSON.stringify({
+        type: "attachment",
+        uuid: queuedCommand,
+        parentUuid: toolResult,
+        sessionId,
+        attachment: {
+          type: "queued_command",
+          prompt: [{ type: "text", text: "steered" }],
+          source_uuid: steeredMessage,
+        },
+      }),
+      { type: "assistant", uuid: randomUUID(), parentUuid: queuedCommand, text: "reply to steer" },
+    ]);
+
+    const parent = await findSteeredMessageParent(transcriptPath, steeredMessage);
+    expect(parent).toBe(toolResult);
+    expect(await findSteeredMessageParent(transcriptPath, randomUUID())).toBeNull();
+
+    let currentSessionId = sessionId;
+    await revertClaudeConversation({
+      sdk: realClaudeRewindSdk,
+      sessionId,
+      transcriptPath,
+      messageId: parent!,
+      setSessionId: (nextSessionId) => {
+        currentSessionId = nextSessionId;
+      },
+    });
+    expect(readMessageTexts(path.join(projectDir, `${currentSessionId}.jsonl`))).toEqual([
+      "first",
+      "running a tool",
+      "tool output",
+    ]);
+  });
 });
+
+test.runIf(process.platform === "linux")(
+  "releases the transcript descriptor after an early steer match",
+  async () => {
+    const artifacts = path.resolve(".artifacts");
+    mkdirSync(artifacts, { recursive: true });
+    const root = mkdtempSync(path.join(artifacts, "claude-rewind-descriptor-"));
+    const transcriptPath = path.join(root, "session.jsonl");
+    const matchingEntry = {
+      type: "attachment",
+      parentUuid: "before-steer",
+      attachment: { type: "queued_command", source_uuid: "steered-message" },
+    };
+    const unreadEntry = JSON.stringify({ type: "assistant", message: "x".repeat(1024) });
+    writeFileSync(
+      transcriptPath,
+      JSON.stringify(matchingEntry) + "\n" + (unreadEntry + "\n").repeat(1200),
+    );
+    const openDescriptors = () =>
+      readdirSync("/proc/self/fd").filter((descriptor) => {
+        try {
+          return readlinkSync(path.join("/proc/self/fd", descriptor)) === transcriptPath;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+          throw error;
+        }
+      }).length;
+    try {
+      expect(openDescriptors()).toBe(0);
+      for (let attempt = 0; attempt < 5; attempt++) {
+        await expect(findSteeredMessageParent(transcriptPath, "steered-message")).resolves.toBe(
+          "before-steer",
+        );
+      }
+      await expect.poll(openDescriptors, { timeout: 1000 }).toBe(0);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/packages/server/src/server/agent/providers/claude/rewind.ts b/packages/server/src/server/agent/providers/claude/rewind.ts
index 91183687e0..75607c184b 100644
--- a/packages/server/src/server/agent/providers/claude/rewind.ts
+++ b/packages/server/src/server/agent/providers/claude/rewind.ts
@@ -1,5 +1,7 @@
+import { createReadStream } from "node:fs";
 import { appendFile, readFile } from "node:fs/promises";
 import path from "node:path";
+import { createInterface } from "node:readline";
 import {
   forkSession as claudeForkSession,
   type Query,
@@ -70,6 +72,54 @@ function isSessionStoreEntry(value: unknown): value is SessionStoreEntry {
   );
 }
 
+/**
+ * The entry a message steered into a running turn follows. Claude Code gives such a message no
+ * entry of its own: it records a queued_command attachment, under the uuid Paseo minted for the
+ * message, hung off the entry it was read after. Forking at that entry drops the message and
+ * everything after it. Null when the transcript holds no such attachment.
+ */
+export async function findSteeredMessageParent(
+  transcriptPath: string,
+  messageId: string,
+): Promise<string | null> {
+  const input = createReadStream(transcriptPath, { encoding: "utf8" });
+  const lines = createInterface({
+    input,
+    crlfDelay: Infinity,
+  });
+  try {
+    for await (const line of lines) {
+      if (!line.includes(messageId) || !line.includes('"queued_command"')) continue;
+      let entry: unknown;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const record = entry as {
+        type?: unknown;
+        parentUuid?: unknown;
+        attachment?: { type?: unknown; source_uuid?: unknown };
+      };
+      if (
+        record.type === "attachment" &&
+        record.attachment?.type === "queued_command" &&
+        record.attachment.source_uuid === messageId &&
+        typeof record.parentUuid === "string"
+      ) {
+        return record.parentUuid;
+      }
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  } finally {
+    lines.close();
+    input.destroy();
+  }
+  return null;
+}
+
 export async function revertClaudeConversation(input: {
   sdk: ClaudeRewindSdk;
   sessionId: string | null;
diff --git a/packages/server/src/server/agent/providers/claude/runtime-safety.test.ts b/packages/server/src/server/agent/providers/claude/runtime-safety.test.ts
new file mode 100644
index 0000000000..6651f3e909
--- /dev/null
+++ b/packages/server/src/server/agent/providers/claude/runtime-safety.test.ts
@@ -0,0 +1,48 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { expect, test } from "vitest";
+import { ClaudeRuntimeSafety } from "./runtime-safety.js";
+
+const message = (value: unknown) => value as SDKMessage;
+
+test("enriches only live tasks with their correlated launch metadata", () => {
+  const runtime = new ClaudeRuntimeSafety();
+  runtime.observe(
+    message({
+      type: "assistant",
+      message: {
+        content: [
+          {
+            type: "tool_use",
+            id: "tool-1",
+            name: "Monitor",
+            input: { description: "Watch build", command: "tail -f build.log" },
+          },
+          { type: "tool_use", id: "old", name: "Bash", input: { command: "old command" } },
+        ],
+      },
+    }),
+  );
+  runtime.observe(
+    message({ type: "system", subtype: "task_started", task_id: "task-1", tool_use_id: "tool-1" }),
+  );
+  expect(
+    runtime.observe(
+      message({
+        type: "system",
+        subtype: "background_tasks_changed",
+        tasks: [{ task_id: "task-1", task_type: "local_bash", description: "Watch build" }],
+      }),
+    ),
+  ).toEqual([
+    {
+      id: "task-1",
+      kind: "monitor",
+      description: "Watch build",
+      command: "tail -f build.log",
+      canStop: true,
+    },
+  ]);
+  expect(
+    runtime.observe(message({ type: "system", subtype: "background_tasks_changed", tasks: [] })),
+  ).toEqual([]);
+});
diff --git a/packages/server/src/server/agent/providers/claude/runtime-safety.ts b/packages/server/src/server/agent/providers/claude/runtime-safety.ts
index 0c32804a57..8688e93f45 100644
--- a/packages/server/src/server/agent/providers/claude/runtime-safety.ts
+++ b/packages/server/src/server/agent/providers/claude/runtime-safety.ts
@@ -1,42 +1,172 @@
 import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentBackgroundWorkInput } from "../../background-work/index.js";
 import { parseClaudeCodeVersion } from "./model-manifest.js";
+import { toBackgroundWorkInputs, type ClaudeBackgroundTask } from "./background-work.js";
 
 /** Process-local background ownership. Completion delivery can follow an empty roster. */
 export class ClaudeRuntimeSafety {
-  private supported = false;
-  private liveTasks = new Set<string>();
+  private inventoryState: "unknown" | "supported" | "retired" = "unknown";
+  // Background work starts inside a turn, and init only arrives with a turn. A process that
+  // has neither been sent a prompt nor reported init (a resumed chat that only answered
+  // control requests) owns no background work.
+  private turnSeen = false;
+  private liveTasks: readonly ClaudeBackgroundTask[] = [];
+  private published: AgentBackgroundWorkInput[] | undefined;
   private readonly awaitingNotifications = new Set<string>();
+  private readonly monitorTools = new Set<string>();
+  private readonly toolInputs = new Map<string, { description?: string; command?: string }>();
+  private readonly taskTools = new Map<string, string>();
 
   reset(): void {
-    this.supported = false;
-    this.liveTasks.clear();
+    this.inventoryState = "unknown";
+    this.turnSeen = false;
+    this.liveTasks = [];
+    this.published = undefined;
     this.awaitingNotifications.clear();
+    this.monitorTools.clear();
+    this.toolInputs.clear();
+    this.taskTools.clear();
   }
 
-  observe(message: SDKMessage): void {
-    if (message.type !== "system") return;
+  retire(): void {
+    this.reset();
+    this.inventoryState = "retired";
+  }
+
+  /** Called before a prompt is written to this process. */
+  notePromptSent(): void {
+    this.turnSeen = true;
+  }
+
+  /** Returns a full replacement only when the visible inventory changes. */
+  observe(message: SDKMessage): AgentBackgroundWorkInput[] | undefined {
+    if (this.inventoryState === "retired") return undefined;
+    const changed = this.observeTools(message);
+    const systemChanged = message.type === "system" ? this.observeSystem(message) : false;
+    if ((!changed && !systemChanged) || this.inventoryState !== "supported") return undefined;
+    const items = this.buildInventory();
+    if (this.published && sameInventory(this.published, items)) return undefined;
+    this.published = items;
+    return items;
+  }
+
+  private observeTools(message: SDKMessage): boolean {
+    if (message.type === "assistant") {
+      let relevant = false;
+      for (const block of message.message.content) {
+        if (block.type === "tool_use" && (block.name === "Monitor" || block.name === "Bash")) {
+          if (block.name === "Monitor") relevant = this.observeMonitor(block.id) || relevant;
+          relevant = this.observeInput(block.id, block.input) || relevant;
+        }
+      }
+      return relevant;
+    }
+    if (message.type === "stream_event" && message.event.type === "content_block_start") {
+      const block = message.event.content_block;
+      if (block.type === "tool_use" && block.name === "Monitor")
+        return this.observeMonitor(block.id);
+    }
+    return false;
+  }
+
+  private observeInput(id: string, value: unknown): boolean {
+    const input = value as Record<string, unknown> | null;
+    const description = typeof input?.description === "string" ? input.description.trim() : "";
+    const command = typeof input?.command === "string" ? input.command.trim() : "";
+    const previous = this.toolInputs.get(id);
+    if (description === (previous?.description ?? "") && command === (previous?.command ?? ""))
+      return false;
+    this.toolInputs.set(id, {
+      ...(description ? { description } : {}),
+      ...(command ? { command } : {}),
+    });
+    return this.liveTasks.some((task) => this.taskTools.get(task.task_id) === id);
+  }
+
+  private observeMonitor(id: string): boolean {
+    if (this.monitorTools.has(id)) return false;
+    this.monitorTools.add(id);
+    return this.liveTasks.some((task) => this.taskTools.get(task.task_id) === id);
+  }
+
+  private observeSystem(message: Extract<SDKMessage, { type: "system" }>): boolean {
+    if (message.subtype === "task_started" && message.tool_use_id) {
+      const previous = this.taskTools.get(message.task_id);
+      this.taskTools.set(message.task_id, message.tool_use_id);
+      return (
+        previous !== message.tool_use_id &&
+        (this.monitorTools.has(message.tool_use_id) ||
+          this.toolInputs.has(message.tool_use_id) ||
+          (previous !== undefined &&
+            (this.monitorTools.has(previous) || this.toolInputs.has(previous)))) &&
+        this.liveTasks.some((task) => task.task_id === message.task_id)
+      );
+    }
     if (message.subtype === "init") {
-      // 2.1.292 is a known roster-capable release. Older binaries can demonstrate
-      // support by sending a roster; a fresh process starts with an empty roster.
+      this.turnSeen = true;
       const version = parseClaudeCodeVersion(message.claude_code_version ?? "");
       if (
         version &&
         (version[0] > 2 ||
           (version[0] === 2 && (version[1] > 1 || (version[1] === 1 && version[2] >= 292))))
-      )
-        this.supported = true;
+      ) {
+        const changed = this.inventoryState !== "supported";
+        this.inventoryState = "supported";
+        return changed;
+      }
     }
     if (message.subtype === "background_tasks_changed") {
-      this.supported = true;
-      this.liveTasks = new Set(message.tasks.map((task) => task.task_id));
-      for (const id of this.liveTasks) this.awaitingNotifications.add(id);
-    }
-    if (message.subtype === "task_notification") {
-      this.awaitingNotifications.delete(message.task_id);
+      this.inventoryState = "supported";
+      this.liveTasks = message.tasks;
+      for (const task of this.liveTasks) this.awaitingNotifications.add(task.task_id);
+      return true;
     }
+    if (message.subtype === "task_notification") this.awaitingNotifications.delete(message.task_id);
+    return false;
   }
 
   canStopRuntime(): boolean {
-    return this.supported && this.liveTasks.size === 0 && this.awaitingNotifications.size === 0;
+    if (this.inventoryState === "unknown" && !this.turnSeen) return true;
+    return (
+      this.inventoryState === "supported" &&
+      this.liveTasks.length === 0 &&
+      this.awaitingNotifications.size === 0
+    );
+  }
+
+  canStop(id: string): boolean {
+    return this.buildInventory().some((item) => item.id === id && item.canStop);
+  }
+
+  isCurrentInventory(items: AgentBackgroundWorkInput[]): boolean {
+    return this.inventoryState === "supported" && this.published === items;
+  }
+
+  private buildInventory(): AgentBackgroundWorkInput[] {
+    return toBackgroundWorkInputs(this.liveTasks).map((item) => {
+      const tool = this.taskTools.get(item.id) ?? "";
+      if (this.monitorTools.has(tool)) item.kind = "monitor";
+      const input = this.toolInputs.get(tool);
+      if (input?.description) item.description = input.description;
+      if (input?.command) item.command = input.command;
+      return item;
+    });
   }
 }
+
+function sameInventory(
+  left: readonly AgentBackgroundWorkInput[],
+  right: readonly AgentBackgroundWorkInput[],
+): boolean {
+  return (
+    left.length === right.length &&
+    left.every(
+      (item, index) =>
+        item.id === right[index].id &&
+        item.kind === right[index].kind &&
+        item.description === right[index].description &&
+        item.command === right[index].command &&
+        item.canStop === right[index].canStop,
+    )
+  );
+}
diff --git a/packages/server/src/server/agent/providers/claude/subagents/live-source.test.ts b/packages/server/src/server/agent/providers/claude/subagents/live-source.test.ts
index b0bfc3d755..b12ab8eb6a 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/live-source.test.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/live-source.test.ts
@@ -156,6 +156,42 @@ describe("ClaudeTaskProtocolSource", () => {
     ]);
   });
 
+  it("resumes a child a reopened session restored on its original row", () => {
+    const source = new ClaudeTaskProtocolSource();
+    source.restore([
+      {
+        taskId: "a1730a6215e1f5cf6",
+        id: "toolu_original",
+        presentation: { title: "general-purpose", model: "claude-sonnet-5", effort: "high" },
+      },
+    ]);
+
+    // Restored is not running: a canceled turn and an unannounced frame leave it alone.
+    expect(source.cancelRunningForegroundTasks()).toEqual([]);
+    expect(source.resolveSubagentId("toolu_original")).toBeUndefined();
+
+    expect(
+      source.observe(taskStarted({ tool_use_id: "toolu_resumed", prompt: "Resumed prompt" })),
+    ).toEqual([
+      { kind: "status", id: "toolu_original", status: "running" },
+      {
+        kind: "timeline",
+        id: "toolu_original",
+        item: { type: "user_message", text: "Resumed prompt" },
+      },
+    ]);
+    expect(source.resolveSubagentId("toolu_original")).toBe("toolu_original");
+    expect(source.resolveSubagentId("toolu_resumed")).toBe("toolu_original");
+    expect(
+      source.observeSidechainFrame(
+        { type: "assistant", message: { model: "claude-opus-5" } } as unknown as SDKMessage,
+        "toolu_original",
+      ),
+    ).toEqual([
+      { kind: "subtitle", id: "toolu_original", subtitle: "general-purpose · Opus 5 · High" },
+    ]);
+  });
+
   it("declares a distinct task separately", () => {
     const source = new ClaudeTaskProtocolSource();
     source.observe(taskStarted({ task_id: "first", tool_use_id: "toolu_first" }));
diff --git a/packages/server/src/server/agent/providers/claude/subagents/live-source.ts b/packages/server/src/server/agent/providers/claude/subagents/live-source.ts
index af941aa24b..f9fa3f8a19 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/live-source.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/live-source.ts
@@ -49,9 +49,9 @@ interface TaskStartedMessage {
 }
 
 /** Task-tool subagents. Backgrounded shell commands announce as `local_bash`. */
-const CLAUDE_SUBAGENT_TASK_TYPE = "local_agent";
+export const CLAUDE_SUBAGENT_TASK_TYPE = "local_agent";
 /** Workflow executions use the same announced task lifecycle as Task-tool subagents. */
-const CLAUDE_WORKFLOW_TASK_TYPE = "local_workflow";
+export const CLAUDE_WORKFLOW_TASK_TYPE = "local_workflow";
 
 /**
  * Not every announced task belongs in the subagents track. Verified on the wire:
@@ -121,6 +121,16 @@ function readString(value: unknown): string | undefined {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
 
+/**
+ * A subagent a reopened session rebuilt from its transcript. Its `taskId` (the transcript's
+ * agentId) is the task id Claude announces again when SendMessage resumes the child.
+ */
+export interface ClaudeRestoredSubagent {
+  taskId: string;
+  id: string;
+  presentation: ClaudeSubagentPresentationFacts;
+}
+
 export interface ClaudeTaskProtocolSourceInput {
   /**
    * The parent's Task tool input, by tool_use id.
@@ -162,6 +172,14 @@ export class ClaudeTaskProtocolSource {
   private readonly backgroundedIds = new Set<string>();
   /** Last status emitted per subagent, so a redundant announcement is not re-broadcast. */
   private readonly lastStatusById = new Map<string, ProviderSubagentStatus>();
+  /**
+   * Children a reopened session restored from its transcript, by task id. Claude resumes one under
+   * its old task id with a new tool id, while its frames keep the original Task call as parent.
+   * Without this the resume reads as a new task: a second row, and every frame dropped as
+   * undeclared. Held apart from the declared table so a restored child is left alone until
+   * Claude announces it again.
+   */
+  private readonly restoredByTaskId = new Map<string, ClaudeRestoredSubagent>();
   /** Claude facts stay inside the provider boundary; clients receive one compact subtitle. */
   private readonly presentationById = new Map<string, ClaudeSubagentPresentationFacts>();
   private readonly lastSubtitleById = new Map<string, string>();
@@ -246,6 +264,14 @@ export class ClaudeTaskProtocolSource {
     }
   }
 
+  /** Remember the children a reopened session restored, for Claude to resume by task id. */
+  restore(subagents: Iterable<ClaudeRestoredSubagent>): void {
+    for (const subagent of subagents) {
+      if (this.subagentIdByTaskId.has(subagent.taskId)) continue;
+      this.restoredByTaskId.set(subagent.taskId, subagent);
+    }
+  }
+
   /**
    * Forget the session.
    *
@@ -259,6 +285,7 @@ export class ClaudeTaskProtocolSource {
     this.ownerSubagentIdByToolUseId.clear();
     this.ownerSubagentIdByTaskId.clear();
     this.declaredIds.clear();
+    this.restoredByTaskId.clear();
     this.workflowTaskIds.clear();
     this.lastWorkflowResultByTaskId.clear();
     this.idsWithExistingParentToolCard.clear();
@@ -315,7 +342,8 @@ export class ClaudeTaskProtocolSource {
     if (!id || message.skip_transcript === true || !isProviderSubagentTask(message)) return [];
 
     this.sawTaskStarted = true;
-    const existingId = this.subagentIdByTaskId.get(message.task_id);
+    const existingId =
+      this.subagentIdByTaskId.get(message.task_id) ?? this.adoptRestored(message.task_id);
     this.recordBackgrounded(existingId ?? id, message.is_backgrounded);
     if (existingId) {
       return this.observeExistingTaskStart(message, id, existingId);
@@ -324,6 +352,20 @@ export class ClaudeTaskProtocolSource {
     return this.observeNewTaskStart(message, id, parentSubagentId);
   }
 
+  /** Declare a restored child under the id its transcript gave it, with what it already showed. */
+  private adoptRestored(taskId: string): string | undefined {
+    const restored = this.restoredByTaskId.get(taskId);
+    if (!restored) return undefined;
+    this.restoredByTaskId.delete(taskId);
+    this.subagentIdByTaskId.set(taskId, restored.id);
+    this.canonicalIdByToolUseId.set(restored.id, restored.id);
+    this.declaredIds.add(restored.id);
+    this.presentationById.set(restored.id, restored.presentation);
+    const subtitle = buildClaudeSubagentSubtitle(restored.presentation);
+    if (subtitle) this.lastSubtitleById.set(restored.id, subtitle);
+    return restored.id;
+  }
+
   private observeExistingTaskStart(
     message: TaskStartedMessage,
     toolUseId: string,
diff --git a/packages/server/src/server/agent/providers/claude/subagents/replay-source.test.ts b/packages/server/src/server/agent/providers/claude/subagents/replay-source.test.ts
index a60feb8ba4..254d6b8905 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/replay-source.test.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/replay-source.test.ts
@@ -88,6 +88,50 @@ describe("parseClaudeSubagentMeta", () => {
 });
 
 describe("observeReplaySubagents", () => {
+  it("restores a resumed child on its original row after consuming async history", async () => {
+    async function* entries(): AsyncGenerator<ClaudeReplayEntry> {
+      yield { type: "assistant", message: { model: "claude-opus-5" } };
+      yield {
+        type: "assistant",
+        effort: "high",
+        message: { model: "claude-sonnet-5", usage: { input_tokens: 10, output_tokens: 2 } },
+      };
+    }
+    const replay = await observeReplaySubagents({
+      subagents: [{ agentId: AGENT_ID, meta: { toolUseId: TOOL_USE_ID }, entries: entries() }],
+      parent: parentWithTaskCall(),
+      convertEntry: async () => [],
+    });
+    expect(replay.restored).toEqual([
+      {
+        taskId: AGENT_ID,
+        id: TOOL_USE_ID,
+        presentation: {
+          title: "general-purpose",
+          model: "claude-sonnet-5",
+          effort: "high",
+          usage: { totalTokens: 12 },
+        },
+      },
+    ]);
+    const live = new ClaudeTaskProtocolSource();
+    live.restore(replay.restored);
+    expect(
+      live.observe({
+        type: "system",
+        subtype: "task_started",
+        task_id: AGENT_ID,
+        tool_use_id: "resumed-tool",
+        description: "Resume the captured task",
+        task_type: "local_agent",
+        is_backgrounded: true,
+        uuid: "00000000-0000-0000-0000-000000000000",
+        session_id: "reopened-session",
+      }),
+    ).toEqual([{ kind: "status", id: TOOL_USE_ID, status: "running" }]);
+    expect(live.resolveSubagentId("resumed-tool")).toBe(TOOL_USE_ID);
+  });
+
   it("links a subagent to its Task call through meta.toolUseId", async () => {
     const observations = (
       await observeReplaySubagents({
@@ -602,7 +646,7 @@ describe("replay usage", () => {
       await store.apply("parent", "claude", event);
     }
 
-    expect(store.get("parent", TOOL_USE_ID)?.subtitle).toBe("general-purpose · 7 tokens");
+    expect((await store.get("parent", TOOL_USE_ID))?.subtitle).toBe("general-purpose · 7 tokens");
   });
 });
 
diff --git a/packages/server/src/server/agent/providers/claude/subagents/replay-source.ts b/packages/server/src/server/agent/providers/claude/subagents/replay-source.ts
index 02cbb783f0..51e5ff9c09 100644
--- a/packages/server/src/server/agent/providers/claude/subagents/replay-source.ts
+++ b/packages/server/src/server/agent/providers/claude/subagents/replay-source.ts
@@ -5,6 +5,7 @@ import { normalizeProviderReplayTimestamp } from "../../../provider-history-time
 import type { ProviderSubagentStatus } from "../../../provider-subagents/store.js";
 import { isClaudeInterruptPlaceholderText } from "../interrupt-placeholder.js";
 import { resolveObservedClaudeModelId } from "../models.js";
+import type { ClaudeRestoredSubagent } from "./live-source.js";
 import type { SubagentObservation } from "./observation.js";
 import { buildClaudeSubagentSubtitle, type ClaudeSubagentUsage } from "./presentation.js";
 
@@ -246,6 +247,7 @@ async function observeSubagent(
   parent: ClaudeReplayParentFacts,
   convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>,
   toolOwners: Map<string, string>,
+  restored: ClaudeRestoredSubagent[],
   parentSubagentId?: string,
 ): Promise<SubagentObservation[]> {
   const link = resolveParentLink(subagent, parent);
@@ -276,13 +278,14 @@ async function observeSubagent(
   const observations = [
     declareSubagent(subagent, link, toolCall, parentSubagentId, firstTimestamp),
   ];
-  const subtitle = observeSubtitle(
-    link,
-    toolCall?.title ?? subagent.meta?.agentType,
-    runtime,
-    usage,
-    lastTimestamp,
-  );
+  const title = toolCall?.title ?? subagent.meta?.agentType;
+  // The agentId is the task_id Claude resumes this child under, so live can find it again.
+  restored.push({
+    taskId: subagent.agentId,
+    id: link.id,
+    presentation: { ...(title ? { title } : {}), ...runtime, ...(usage ? { usage } : {}) },
+  });
+  const subtitle = observeSubtitle(link, title, runtime, usage, lastTimestamp);
   if (subtitle) observations.push(subtitle);
   for (const observation of timeline) observations.push(observation);
   const terminalStatus = link.status ?? childTerminalStatus;
@@ -337,9 +340,14 @@ export async function observeReplaySubagents(input: {
   subagents: readonly ClaudeReplaySubagentInput[];
   parent: ClaudeReplayParentFacts;
   convertEntry: (entry: ClaudeReplayEntry) => AgentTimelineItem[] | Promise<AgentTimelineItem[]>;
-}): Promise<{ observations: SubagentObservation[]; toolOwners: ReadonlyMap<string, string> }> {
+}): Promise<{
+  observations: SubagentObservation[];
+  toolOwners: ReadonlyMap<string, string>;
+  restored: readonly ClaudeRestoredSubagent[];
+}> {
   const observations: SubagentObservation[] = [];
   const toolOwners = new Map<string, string>();
+  const restored: ClaudeRestoredSubagent[] = [];
   const unresolved = [...input.subagents].sort(
     (left, right) => (left.meta?.spawnDepth ?? 1) - (right.meta?.spawnDepth ?? 1),
   );
@@ -364,6 +372,7 @@ export async function observeReplaySubagents(input: {
         parent,
         input.convertEntry,
         toolOwners,
+        restored,
         ownerId,
       )) {
         observations.push(observation);
@@ -373,7 +382,7 @@ export async function observeReplaySubagents(input: {
       madeProgress = true;
     }
   }
-  return { observations, toolOwners };
+  return { observations, toolOwners, restored };
 }
 
 function resolveReplayOwner(
diff --git a/packages/server/src/server/agent/providers/claude/tool-call-detail-parser.ts b/packages/server/src/server/agent/providers/claude/tool-call-detail-parser.ts
index a63e8b715a..aa84f70370 100644
--- a/packages/server/src/server/agent/providers/claude/tool-call-detail-parser.ts
+++ b/packages/server/src/server/agent/providers/claude/tool-call-detail-parser.ts
@@ -23,6 +23,7 @@ import {
   toShellToolDetail,
   toWriteToolDetail,
   toolDetailBranchByName,
+  parseKnownToolDetail,
 } from "../tool-call-detail-primitives.js";
 
 const ClaudeGrepOutputSchema = z
@@ -232,9 +233,9 @@ export function deriveClaudeToolDetail(
     };
   }
 
-  const pass2 = ClaudeToolDetailPass2Schema.safeParse(pass1.data);
-  if (pass2.success && pass2.data) {
-    return pass2.data;
+  const detail = parseKnownToolDetail(ClaudeToolDetailPass2Schema, pass1.data);
+  if (detail) {
+    return detail;
   }
 
   return {
diff --git a/packages/server/src/server/agent/providers/claude/tool-call-mapper.test.ts b/packages/server/src/server/agent/providers/claude/tool-call-mapper.test.ts
index f0b3ea2af1..5aaf4a8220 100644
--- a/packages/server/src/server/agent/providers/claude/tool-call-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/claude/tool-call-mapper.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import { buildToolCallDisplayModel } from "@getpaseo/protocol/tool-call-display";
 import {
   mapClaudeCanceledToolCall,
   mapClaudeCompletedToolCall,
@@ -16,6 +17,69 @@ function expectMapped<T>(item: T | null): T {
 }
 
 describe("claude tool-call mapper", () => {
+  // Claude streams a tool_use block with `input: {}` first, then the arguments as partial JSON.
+  // An optional argument can complete before the identifying one.
+  it.each([
+    {
+      name: "Bash",
+      stages: [
+        { description: "Run a command" },
+        { description: "Run a command", command: "ec" },
+        { description: "Run a command", command: "echo hi" },
+      ],
+      title: "Shell",
+    },
+    {
+      name: "Read",
+      stages: [{ offset: 10 }, { offset: 10, file_path: "/tmp/a" }, { file_path: "/tmp/a.ts" }],
+      title: "Read",
+    },
+    {
+      name: "Write",
+      stages: [{ content: "x" }, { file_path: "/tmp/a.ts", content: "x" }],
+      title: "Write",
+    },
+    {
+      name: "MultiEdit",
+      stages: [
+        { file_path: "/tmp/a.ts" },
+        { file_path: "/tmp/a.ts", old_string: "a", new_string: "b" },
+      ],
+      title: "Edit",
+    },
+    {
+      name: "Grep",
+      stages: [{ output_mode: "content" }, { output_mode: "content", pattern: "foo" }],
+      title: "Search",
+    },
+    {
+      name: "Glob",
+      stages: [{ path: "/tmp" }, { path: "/tmp", pattern: "*.ts" }],
+      title: "Search",
+    },
+    {
+      name: "WebFetch",
+      stages: [{ prompt: "Summarize" }, { prompt: "Summarize", url: "https://example.com" }],
+      title: "Fetch",
+    },
+  ])("keeps the $name title and detail kind while its arguments stream in", (tool) => {
+    const stages = [{}, ...tool.stages].map((input) =>
+      expectMapped(
+        mapClaudeRunningToolCall({
+          callId: "claude-stream-1",
+          name: tool.name,
+          input,
+          output: null,
+        }),
+      ),
+    );
+
+    expect(stages.map((item) => buildToolCallDisplayModel(item).displayName)).toEqual(
+      stages.map(() => tool.title),
+    );
+    expect(new Set(stages.map((item) => item.detail.type)).size).toBe(1);
+  });
+
   it("preserves a plan's original tool identity and outcome for live and replayed results", () => {
     const proposal = { name: "ExitPlanMode", callId: "plan-tool-1", input: { plan: "Ship it" } };
     const pending = expectMapped(mapClaudeRunningToolCall(proposal));
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts
index 8f3f8fc76d..120e877d8e 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts
@@ -1,7 +1,20 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import pino from "pino";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 
-import type { AgentSession, AgentSessionConfig } from "../agent-sdk-types.js";
+import { AgentManager } from "../agent-manager.js";
+import { toAgentPayload } from "../agent-projections.js";
+import { AgentStorage } from "../agent-storage.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
+import { convertLegacyOptions } from "../option-controls.js";
+import type {
+  AgentClient,
+  AgentSession,
+  AgentSessionConfig,
+  AgentStreamEvent,
+} from "../agent-sdk-types.js";
 import { CodexAppServerAgentSession } from "./codex-app-server-agent.js";
 import {
   createFakeCodexAppServer,
@@ -37,23 +50,32 @@ const TEST_SPEED_MODELS = [
   serviceTiers: [{ id: "priority", name: "Fast", description: "Faster processing" }],
 }));
 
-function speedFeature(value: string) {
+function speedControl() {
   return {
     type: "select",
-    id: "service_tier",
+    key: "service_tier",
     label: "Speed",
     description: "Choose processing speed. Faster tiers increase usage.",
     tooltip: "Select speed",
     icon: "zap",
     desktopTrigger: "icon",
-    value,
-    options: [
-      { id: "default", label: "Normal", isDefault: true },
-      { id: "priority", label: "Fast" },
+    defaultValue: "default",
+    choices: [
+      { value: "default", label: "Normal" },
+      { value: "priority", label: "Fast" },
     ],
   };
 }
 
+const PLAN_CONTROL = {
+  type: "toggle",
+  key: "plan_mode",
+  label: "Plan",
+  description: "Switch Codex into planning-only collaboration mode",
+  tooltip: "Toggle plan mode",
+  icon: "list-todo",
+};
+
 const TEST_COLLABORATION_MODES: CollaborationModeRecord[] = [
   {
     name: "Code",
@@ -132,7 +154,7 @@ async function createConnectedSession(
   return harness;
 }
 
-describe("Codex app-server provider features", () => {
+describe("Codex app-server provider controls", () => {
   test("GPT-6.1 Sol offers catalog speed tiers and sends Ultrafast", async () => {
     const { session, appServer } = await createConnectedSession(
       { model: "gpt-6.1-sol" },
@@ -149,19 +171,19 @@ describe("Codex app-server provider features", () => {
       },
     );
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
+          key: "service_tier",
           type: "select",
-          value: "default",
-          options: [
-            { id: "default", label: "Normal", isDefault: true },
-            { id: "priority", label: "Fast" },
-            { id: "ultrafast", label: "Ultrafast" },
+          defaultValue: "default",
+          choices: [
+            { value: "default", label: "Normal" },
+            { value: "priority", label: "Fast" },
+            { value: "ultrafast", label: "Ultrafast" },
           ],
         }),
       );
-      await session.setFeature?.("service_tier", "ultrafast");
+      await session.applyOptions?.({ service_tier: "ultrafast" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         serviceTier: "ultrafast",
@@ -186,16 +208,16 @@ describe("Codex app-server provider features", () => {
       },
     );
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
-          options: [
-            { id: "default", label: "Normal", isDefault: true },
-            { id: "future-tier", label: "Future speed" },
+          key: "service_tier",
+          choices: [
+            { value: "default", label: "Normal" },
+            { value: "future-tier", label: "Future speed" },
           ],
         }),
       );
-      await session.setFeature?.("service_tier", "future-tier");
+      await session.applyOptions?.({ service_tier: "future-tier" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model: "future-codex-model",
@@ -210,7 +232,7 @@ describe("Codex app-server provider features", () => {
     "restores %s and Normal explicitly overrides an existing thread tier",
     async (tier) => {
       const { session, appServer } = await createConnectedSession(
-        { model: "future-model", featureValues: { service_tier: tier } },
+        { model: "future-model", providerOptions: { service_tier: tier } },
         {
           models: [
             {
@@ -224,11 +246,8 @@ describe("Codex app-server provider features", () => {
         },
       );
       try {
-        expect(session.features).toContainEqual(
-          expect.objectContaining({ id: "service_tier", value: tier }),
-        );
         await session.getRuntimeInfo();
-        await session.setFeature?.("service_tier", "default");
+        await session.applyOptions?.({ service_tier: "default" });
         await session.startTurn("hello");
         await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
           serviceTier: "default",
@@ -239,17 +258,40 @@ describe("Codex app-server provider features", () => {
     },
   );
 
-  test("rejects unadvertised tiers and non-string values", async () => {
-    const { session } = await createConnectedSession();
+  test.each(["priority", "ultrafast"])("restores %s from providerOptions", async (tier) => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "future-model", providerOptions: { service_tier: tier } },
+      {
+        models: [
+          {
+            id: "future-model",
+            serviceTiers: [
+              { id: "priority", name: "Fast", description: "Fast processing" },
+              { id: "ultrafast", name: "Ultrafast", description: "Ultra processing" },
+            ],
+          },
+        ],
+      },
+    );
     try {
-      for (const value of ["ultrafast", "bogus", true, null]) {
-        await expect(session.setFeature?.("service_tier", value)).rejects.toThrow(
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: tier });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("rejects unadvertised tiers and non-string values", async () => {
+    const { session, appServer } = await createConnectedSession();
+    try {
+      for (const value of ["ultrafast", "bogus"]) {
+        await expect(session.applyOptions?.({ service_tier: value })).rejects.toThrow(
           "is not available",
         );
       }
-      expect(session.features).toContainEqual(
-        expect.objectContaining({ id: "service_tier", value: "default" }),
-      );
+      await expect(session.applyOptions?.({ service_tier: true })).rejects.toThrow();
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
     } finally {
       await session.close();
     }
@@ -257,7 +299,7 @@ describe("Codex app-server provider features", () => {
 
   test("switching to a model without the selected tier resets speed", async () => {
     const { session, appServer } = await createConnectedSession(
-      { model: "ultra-model", featureValues: { service_tier: "ultrafast" } },
+      { model: "ultra-model", providerOptions: { service_tier: "ultrafast" } },
       {
         models: [
           {
@@ -270,8 +312,14 @@ describe("Codex app-server provider features", () => {
     );
     try {
       await session.setModel("gpt-6.1-sol");
-      expect(session.features).toContainEqual(
-        expect.objectContaining({ id: "service_tier", value: "default" }),
+      expect(session.controls).toContainEqual(
+        expect.objectContaining({
+          key: "service_tier",
+          choices: [
+            { value: "default", label: "Normal" },
+            { value: "priority", label: "Fast" },
+          ],
+        }),
       );
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
@@ -280,10 +328,47 @@ describe("Codex app-server provider features", () => {
     }
   });
 
-  test("maps legacy Fast commands to the catalog's request id", async () => {
+  test("a Fast chosen as `fast` is kept as the catalog's id, so a model with a different Fast id resets it", async () => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "model-a" },
+      {
+        models: [
+          {
+            id: "model-a",
+            isDefault: true,
+            serviceTiers: [{ id: "priority", name: "Fast", description: "Faster" }],
+          },
+          {
+            id: "model-b",
+            serviceTiers: [{ id: "rapid", name: "Fast", description: "Faster" }],
+          },
+        ],
+      },
+    );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    try {
+      await expect(session.applyOptions?.({ service_tier: "fast" })).resolves.toEqual({
+        service_tier: "priority",
+      });
+
+      await session.setModel("model-b");
+
+      // The option the session reports and the tier the turn runs are the same speed.
+      expect(events.filter((event) => event.type === "options_changed")).toEqual([
+        expect.objectContaining({ patch: { service_tier: "default" } }),
+      ]);
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("`fast` maps to the catalog's request id", async () => {
     const { session, appServer } = await createConnectedSession();
     try {
-      await session.setFeature?.("fast_mode", true);
+      await session.applyOptions?.({ service_tier: "fast" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         serviceTier: "priority",
@@ -307,13 +392,13 @@ describe("Codex app-server provider features", () => {
   ])("exposes and sends Fast for %s", async (model) => {
     const { session, appServer } = await createConnectedSession({ model });
     try {
-      expect(session.features).toContainEqual(
+      expect(session.controls).toContainEqual(
         expect.objectContaining({
-          id: "service_tier",
-          value: "default",
+          key: "service_tier",
+          defaultValue: "default",
         }),
       );
-      await session.setFeature?.("service_tier", "priority");
+      await session.applyOptions?.({ service_tier: "priority" });
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model,
@@ -338,12 +423,13 @@ describe("Codex app-server provider features", () => {
   ])("does not expose or restore Fast for %s", async (model) => {
     const { session, appServer } = await createConnectedSession({
       model,
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
+    const fresh = await createConnectedSession({ model });
     try {
-      expect(session.features.map((feature) => feature.id)).toEqual(["plan_mode"]);
-      await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(
-        `Codex fast mode is not available for model '${model}'`,
+      expect(session.controls.map((control) => control.key)).toEqual(["plan_mode"]);
+      await expect(fresh.session.applyOptions?.({ service_tier: "fast" })).rejects.toThrow(
+        `Codex speed 'fast' is not available for model '${model}'`,
       );
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -351,21 +437,16 @@ describe("Codex app-server provider features", () => {
       });
     } finally {
       await session.close();
+      await fresh.session.close();
     }
   });
 
   test("restores Fast on Astra and preserves it when switching supported models", async () => {
     const { session, appServer } = await createConnectedSession({
       model: "gpt-6-astra",
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
     try {
-      expect(session.features).toContainEqual(
-        expect.objectContaining({
-          id: "service_tier",
-          value: "priority",
-        }),
-      );
       await session.setModel("gpt-5.6-sol");
       await session.setModel("gpt-6-astra");
       await session.startTurn("hello");
@@ -378,72 +459,33 @@ describe("Codex app-server provider features", () => {
     }
   });
 
-  test("features returns speed selector and plan toggle when supported", async () => {
-    const { session } = await createConnectedSession();
+  test("controls return the speed selector and plan toggle when supported", async () => {
+    const { session, appServer } = await createConnectedSession();
 
-    expect(session.features).toEqual([
-      speedFeature("default"),
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
+    expect(session.controls).toEqual([speedControl(), PLAN_CONTROL]);
 
-    await session.setFeature?.("service_tier", "priority");
-    await session.setFeature?.("plan_mode", true);
+    await session.applyOptions?.({ service_tier: "priority", plan_mode: true });
+    await session.startTurn("hello");
 
-    expect(session.features).toEqual([
-      speedFeature("priority"),
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: true,
-      },
-    ]);
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "priority",
+      collaborationMode: expect.objectContaining({ mode: "plan" }),
+    });
   });
 
-  test("features returns only plan toggle when model does not support fast mode", async () => {
+  test("controls return only the plan toggle when model does not support fast mode", async () => {
     const { session } = await createConnectedSession({ model: "gpt-3.5-turbo" });
 
-    expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
+    expect(session.controls).toEqual([PLAN_CONTROL]);
   });
 
   test("constructor ignores restored fast mode when model does not support it", async () => {
     const { session, appServer } = await createConnectedSession({
       model: "gpt-3.5-turbo",
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
 
-    expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
+    expect(session.controls).toEqual([PLAN_CONTROL]);
 
     await session.startTurn("hello");
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -454,7 +496,7 @@ describe("Codex app-server provider features", () => {
   test("selecting Fast sends the catalog service tier", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -462,12 +504,12 @@ describe("Codex app-server provider features", () => {
     });
   });
 
-  test("legacy Fast off explicitly selects Normal", async () => {
+  test("selecting Normal after Fast explicitly selects Normal", async () => {
     const { session, appServer } = await createConnectedSession({
-      featureValues: { fast_mode: true },
+      providerOptions: { service_tier: "fast" },
     });
 
-    await session.setFeature?.("fast_mode", false);
+    await session.applyOptions?.({ service_tier: "default" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -475,53 +517,39 @@ describe("Codex app-server provider features", () => {
     });
   });
 
-  test("setFeature('fast_mode', true) rejects models that do not support fast mode", async () => {
+  test('applyOptions({ service_tier: "fast" }) rejects models that do not support fast mode', async () => {
     const { session } = await createConnectedSession({ model: "gpt-3.5-turbo" });
 
-    await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(
-      "Codex fast mode is not available for model 'gpt-3.5-turbo'",
+    await expect(session.applyOptions?.({ service_tier: "fast" })).rejects.toThrow(
+      "Codex speed 'fast' is not available for model 'gpt-3.5-turbo'",
     );
   });
 
-  test("setFeature invalidates runtime info", async () => {
+  test("applyOptions invalidates runtime info", async () => {
     const { session } = await createConnectedSession();
 
     await expect(session.getRuntimeInfo()).resolves.not.toMatchObject({
       extra: { collaborationMode: "Plan" },
     });
 
-    await session.setFeature?.("plan_mode", true);
+    await session.applyOptions?.({ plan_mode: true });
 
     await expect(session.getRuntimeInfo()).resolves.toMatchObject({
       extra: { collaborationMode: "Plan" },
     });
   });
 
-  test("setFeature throws for unknown feature ids", async () => {
-    const { session } = createSessionHarness();
-
-    await expect(session.setFeature?.("unknown_feature", true)).rejects.toThrow(
-      "Unknown Codex feature: unknown_feature",
-    );
-  });
-
-  test("constructor restores feature flags from config.featureValues", async () => {
+  test("constructor restores composer options from config.providerOptions", async () => {
     const { session, appServer } = await createConnectedSession({
-      featureValues: { fast_mode: true, plan_mode: true },
+      providerOptions: { service_tier: "fast", plan_mode: true },
     });
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
 
-    expect(session.features).toEqual([
-      speedFeature("priority"),
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: true,
-      },
-    ]);
+    expect(session.controls).toEqual([speedControl(), PLAN_CONTROL]);
+    // A saved `fast` opens as the model's Fast tier, which the open patch says.
+    expect(session.openOptionsPatch).toEqual({ service_tier: "priority" });
+    expect(events.filter((event) => event.type === "options_changed")).toEqual([]);
 
     await session.startTurn("hello");
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -532,10 +560,36 @@ describe("Codex app-server provider features", () => {
     });
   });
 
+  test("a patch that sets another option keeps the running sandbox and an explicit speed", async () => {
+    const { session, appServer } = await createConnectedSession({
+      providerOptions: { sandbox_mode: "read-only", service_tier: "default" },
+    });
+
+    await session.applyOptions?.({ plan_mode: true });
+    await session.startTurn("hello");
+
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "default",
+      sandboxPolicy: expect.objectContaining({ type: "readOnly" }),
+    });
+  });
+
+  test("rejects a live change to the approval policy or sandbox, which the thread fixed when it started", async () => {
+    const { session } = await createConnectedSession({
+      providerOptions: { sandbox_mode: "workspace-write" },
+    });
+
+    await expect(session.applyOptions?.({ sandbox_mode: "read-only" })).rejects.toThrow(
+      /sandbox_mode.*cannot change on a running session/,
+    );
+    // The same value is not a change.
+    await expect(session.applyOptions?.({ sandbox_mode: "workspace-write" })).resolves.toEqual({});
+  });
+
   test("startTurn includes serviceTier when fast mode is enabled", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -543,11 +597,351 @@ describe("Codex app-server provider features", () => {
     });
   });
 
+  test("opening on a model without the saved tier runs Normal and the open patch says so", async () => {
+    const models = [
+      { id: "plain", isDefault: true, defaultReasoningEffort: "medium", serviceTiers: [] },
+    ];
+    const { session, appServer } = await createConnectedSession(
+      { model: "plain", providerOptions: { service_tier: "priority" } },
+      { models },
+    );
+
+    expect(session.openOptionsPatch).toEqual({ service_tier: "default" });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+  });
+
+  test("a saved service_tier: fast runs as the model's Fast tier and the open patch names that tier", async () => {
+    const { session, appServer } = await createConnectedSession({
+      providerOptions: { service_tier: "fast" },
+    });
+
+    expect(session.openOptionsPatch).toEqual({ service_tier: "priority" });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "priority" });
+  });
+
+  test("a live service_tier: fast is returned as the model's Fast tier", async () => {
+    const { session, appServer } = await createConnectedSession();
+
+    await expect(session.applyOptions?.({ service_tier: "fast" })).resolves.toEqual({
+      service_tier: "priority",
+    });
+
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "priority" });
+  });
+
+  test("switching to a model without the speed tier says Normal and keeps it so on the way back", async () => {
+    const models = [
+      ...TEST_SPEED_MODELS,
+      { id: "plain", isDefault: false, defaultReasoningEffort: "medium", serviceTiers: [] },
+    ];
+    const { session, appServer } = await createConnectedSession(
+      { model: "gpt-5.4", providerOptions: { service_tier: "priority" } },
+      { models },
+    );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
+    await session.setModel?.("plain");
+    await session.setModel?.("gpt-5.4");
+
+    expect(events.filter((event) => event.type === "options_changed")).toEqual([
+      { type: "options_changed", provider: "codex", patch: { service_tier: "default" } },
+    ]);
+    await session.startTurn("hello");
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+  });
+
+  describe("legacy Fast (fast_mode) saved or requested before service_tier", () => {
+    function createLegacyFastHarness(
+      rawDefaults: Record<string, unknown> = {},
+      providerId = CODEX_PROVIDER,
+    ) {
+      // The provider registry converts configured defaults before it merges them.
+      const configDefaults = convertLegacyOptions({
+        provider: CODEX_PROVIDER,
+        options: rawDefaults,
+      });
+      const appServer = createFakeCodexAppServer({
+        "collaborationMode/list": () => ({ data: TEST_COLLABORATION_MODES }),
+        "model/list": () => ({ data: TEST_SPEED_MODELS }),
+      });
+      const logger = createTestLogger();
+      const openSession = async (
+        config: AgentSessionConfig,
+        resumeSessionId: string | null,
+      ): Promise<AgentSession> => {
+        const session = new CodexAppServerAgentSession(
+          // The provider registry hands sessions the `config.json` defaults merged into the agent's own options.
+          {
+            ...config,
+            provider: CODEX_PROVIDER,
+            providerOptions: { ...configDefaults, ...config.providerOptions },
+          },
+          resumeSessionId ? { sessionId: resumeSessionId } : null,
+          logger,
+          async () => appServer.child,
+        );
+        await session.connect();
+        return session;
+      };
+      const client: AgentClient = {
+        provider: providerId,
+        capabilities: {
+          supportsStreaming: true,
+          supportsSessionPersistence: true,
+          supportsDynamicModes: false,
+          supportsMcpServers: false,
+          supportsReasoningStream: false,
+          supportsToolInvocations: false,
+        },
+        isAvailable: async () => true,
+        fetchCatalog: async () => ({ models: [], modes: [] }),
+        // Stands in for the `config.json` provider defaults the registry wrapper merges in.
+        effectiveOptions: (own) => ({ ...configDefaults, ...own }),
+        createSession: (config) => openSession(config, null),
+        resumeSession: (handle, config) =>
+          openSession(
+            { ...config, provider: CODEX_PROVIDER } as AgentSessionConfig,
+            handle.sessionId,
+          ),
+      };
+      const workdir = mkdtempSync(join(tmpdir(), "codex-legacy-fast-"));
+      const storage = new AgentStorage(join(workdir, "agents"), logger);
+      const manager = new AgentManager({
+        clients: { [providerId]: client },
+        // A custom provider that extends Codex runs on the Codex adapter.
+        providerDefinitions:
+          providerId === CODEX_PROVIDER
+            ? {}
+            : { [providerId]: { enabled: true, derivedFromProviderId: CODEX_PROVIDER } },
+        registry: storage,
+        logger,
+      });
+      const turnStarts = () =>
+        appServer
+          .requests()
+          .filter((message) => message.method === "turn/start")
+          .map((message) => message.params);
+
+      async function create(providerOptions?: Record<string, unknown>) {
+        const agent = await manager.createAgent(
+          {
+            provider: providerId,
+            cwd: workdir,
+            model: "gpt-5.4",
+            ...(providerOptions ? { providerOptions } : {}),
+          },
+          undefined,
+          { workspaceId: undefined },
+        );
+        return agent.id;
+      }
+      async function resume(providerOptions: Record<string, unknown>) {
+        const agent = await manager.resumeAgentFromPersistence({
+          provider: providerId,
+          sessionId: "thread-1",
+          metadata: { cwd: workdir, model: "gpt-5.4", providerOptions },
+        });
+        return agent.id;
+      }
+      function shownSpeed(agentId: string) {
+        const payload = toAgentPayload(manager.getAgent(agentId)!);
+        const control = payload.controls?.find((candidate) => candidate.key === "service_tier");
+        const choice =
+          control?.type === "select"
+            ? control.choices.find((candidate) => candidate.value === payload.options?.service_tier)
+            : undefined;
+        return {
+          options: payload.options,
+          own: manager.getAgent(agentId)?.config.providerOptions,
+          // What a client reading `options` + `controls` selects, and what the legacy `features` show.
+          selected:
+            payload.options?.service_tier === undefined && control?.type === "select"
+              ? control.defaultValue
+              : choice?.value,
+          feature: payload.features?.find((feature) => feature.id === "service_tier")?.value,
+        };
+      }
+      async function runTurn(agentId: string, expectedTier: string) {
+        const before = turnStarts().length;
+        await manager.getAgent(agentId)!.session!.startTurn("hello");
+        await vi.waitFor(() => expect(turnStarts()).toHaveLength(before + 1));
+        const turn = turnStarts()[before]!;
+        expect(turn).toMatchObject({ serviceTier: expectedTier });
+        appServer.completeTurn({ threadId: String(turn.threadId) });
+        await vi.waitFor(() => expect(manager.getAgent(agentId)?.lifecycle).toBe("idle"));
+      }
+      return { manager, create, resume, shownSpeed, runTurn };
+    }
+
+    const FAST = { selected: "priority", feature: "priority" };
+
+    test("a saved fast_mode opens as the model's Fast tier and is stored as that tier", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({
+        options: { service_tier: "priority" },
+        own: { service_tier: "priority" },
+        ...FAST,
+      });
+      await runTurn(agentId, "priority");
+    });
+
+    test("is shown as Fast after a stored record is resumed", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("from config.json defaults runs Fast and is shown as Fast", async () => {
+      const { create, shownSpeed, runTurn } = createLegacyFastHarness({ fast_mode: true });
+      const agentId = await create();
+
+      expect(shownSpeed(agentId)).toMatchObject(FAST);
+      await runTurn(agentId, "priority");
+    });
+
+    test("a saved fast_mode beats a configured service_tier default", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness({
+        service_tier: "default",
+      });
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a provider extending Codex opens a saved fast_mode as Fast", async () => {
+      const { manager, resume, shownSpeed, runTurn } = createLegacyFastHarness({}, "my-codex");
+      const agentId = await resume({ fast_mode: true });
+      await manager.flush();
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a provider extending Codex creates with a requested fast_mode and applies a later one", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness({}, "my-codex");
+      const agentId = await create({ fast_mode: false });
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+    });
+
+    test("an older client's fast_mode runs Fast at once, and a later service_tier replaces it", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create();
+      expect(shownSpeed(agentId).selected).toBe("default");
+
+      await manager.setAgentOptions(agentId, { fast_mode: true });
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "priority" }, ...FAST });
+      await runTurn(agentId, "priority");
+
+      await manager.setAgentOptions(agentId, { service_tier: "default" });
+      expect(shownSpeed(agentId)).toMatchObject({
+        own: { service_tier: "default" },
+        selected: "default",
+        feature: "default",
+      });
+      await runTurn(agentId, "default");
+
+      await manager.setAgentOptions(agentId, { service_tier: "priority" });
+      expect(shownSpeed(agentId)).toMatchObject({ selected: "priority" });
+      await runTurn(agentId, "priority");
+    });
+
+    test("a request carrying both speed keys follows service_tier", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+
+      await manager.setAgentOptions(agentId, { service_tier: "default", fast_mode: true });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+      await runTurn(agentId, "default");
+    });
+
+    test.each([
+      [CODEX_PROVIDER, "a requested legacy fast_mode", {}, { fast_mode: true }],
+      ["my-codex", "a requested legacy fast_mode", {}, { fast_mode: true }],
+      [CODEX_PROVIDER, "a configured legacy fast_mode", { fast_mode: true }, undefined],
+      [CODEX_PROVIDER, "a configured Fast alias", { service_tier: "fast" }, undefined],
+    ])(
+      "draft speed for %s with %s is the one the first turn runs with",
+      async (providerId, _name, configured, requested) => {
+        const drafting = createLegacyFastHarness(configured, providerId);
+
+        const draft = await drafting.manager.listDraftControls({
+          provider: providerId,
+          cwd: tmpdir(),
+          model: "gpt-5.4",
+          ...(requested ? { providerOptions: requested } : {}),
+        });
+        const features = featuresFromControls({ controls: draft.controls, options: draft.options });
+
+        expect(draft.options).toEqual({ service_tier: "priority" });
+        expect(draft.controls).toContainEqual(expect.objectContaining({ key: "service_tier" }));
+        expect(features).toContainEqual(
+          expect.objectContaining({ id: "service_tier", value: "priority" }),
+        );
+        // A draft session ends with its app-server; creating runs on a fresh one.
+        const creating = createLegacyFastHarness(configured, providerId);
+        const agentId = await creating.create(requested);
+        await creating.runTurn(agentId, "priority");
+      },
+    );
+
+    test.each([
+      ["a string", "false"],
+      ["a number", 1],
+    ])("a legacy fast_mode that is %s is rejected, not read as Fast", async (_name, value) => {
+      const { manager, create } = createLegacyFastHarness();
+      const agentId = await create({});
+
+      await expect(manager.setAgentOptions(agentId, { fast_mode: value })).rejects.toThrow(
+        /fast_mode must be true, false or null/,
+      );
+    });
+
+    test("an older client turning fast_mode off selects Normal", async () => {
+      const { manager, create, shownSpeed, runTurn } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+
+      await manager.setAgentOptions(agentId, { fast_mode: false });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: { service_tier: "default" } });
+      await runTurn(agentId, "default");
+    });
+
+    test("removing the speed returns the agent to Normal", async () => {
+      const { create, manager, shownSpeed } = createLegacyFastHarness();
+      const agentId = await create({ service_tier: "priority" });
+      expect(shownSpeed(agentId)).toMatchObject(FAST);
+
+      await manager.setAgentOptions(agentId, { service_tier: null });
+
+      expect(shownSpeed(agentId)).toMatchObject({ own: undefined, selected: "default" });
+    });
+  });
+
   test("startTurn logs a sanitized turn/start summary for fast mode observability", async () => {
     const capture = createCapturedLogger();
     const prompt = "secret prompt text should not be logged";
     const { session } = await createConnectedSession(
-      { featureValues: { fast_mode: true } },
+      { providerOptions: { service_tier: "fast" } },
       { logger: capture.logger },
     );
 
@@ -570,20 +964,10 @@ describe("Codex app-server provider features", () => {
   test("setModel clears fast mode when switching to an unsupported model", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("service_tier", "priority");
+    await session.applyOptions?.({ service_tier: "priority" });
     await session.setModel("gpt-3.5-turbo");
 
-    expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "plan_mode",
-        label: "Plan",
-        description: "Switch Codex into planning-only collaboration mode",
-        tooltip: "Toggle plan mode",
-        icon: "list-todo",
-        value: false,
-      },
-    ]);
+    expect(session.controls).toEqual([PLAN_CONTROL]);
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
@@ -594,7 +978,7 @@ describe("Codex app-server provider features", () => {
   test("startTurn switches collaboration mode when plan mode is enabled", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("plan_mode", true);
+    await session.applyOptions?.({ plan_mode: true });
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.local.e2e.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.local.e2e.test.ts
index 78c41bcc39..cc31089753 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.local.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.local.e2e.test.ts
@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { createServer } from "node:http";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { once } from "node:events";
 
 import { AgentManager } from "../agent-manager.js";
@@ -217,6 +217,33 @@ function waitForEvent<TEvent extends AgentStreamEvent>(params: {
 }
 
 describe("Codex app-server provider (local e2e)", () => {
+  test.runIf(isCodexInstalled())(
+    "concurrent import scans initialize successfully in a fresh shared Codex home",
+    async () => {
+      const artifacts = path.resolve(".artifacts");
+      mkdirSync(artifacts, { recursive: true });
+      const root = mkdtempSync(path.join(artifacts, "codex-concurrent-startup-"));
+      try {
+        for (let round = 0; round < 4; round++) {
+          const codexHome = path.join(root, String(round));
+          mkdirSync(codexHome);
+          const provider = new CodexAppServerAgentClient(createTestLogger(), {
+            env: { CODEX_HOME: codexHome },
+          });
+          const results = await Promise.allSettled(
+            Array.from({ length: 24 }, () => provider.listImportableSessions({ limit: 1 })),
+          );
+          expect(results).toEqual(
+            Array.from({ length: 24 }, () => ({ status: "fulfilled", value: [] })),
+          );
+        }
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+    60_000,
+  );
+
   test.runIf(isCodexInstalled())(
     "reloads a persisted idle thread repeatedly without overlapping writers",
     async () => {
@@ -263,6 +290,98 @@ describe("Codex app-server provider (local e2e)", () => {
     30_000,
   );
 
+  test.runIf(isCodexInstalled())(
+    "reopens a promptless agent repeatedly before its first model request",
+    async () => {
+      const cwd = mkdtempSync(path.join(os.tmpdir(), "codex-promptless-cwd-"));
+      const logger = createTestLogger();
+      const storage = new AgentStorage(path.join(cwd, "agents"), logger);
+      const manager = new AgentManager({
+        clients: { codex: new CodexAppServerAgentClient(logger) },
+        registry: storage,
+        logger,
+      });
+      let agentId: string | undefined;
+      try {
+        const created = await manager.createAgent(
+          { provider: "codex", cwd, modeId: "auto", model: "mock-model" },
+          undefined,
+          { workspaceId: undefined },
+        );
+        agentId = created.id;
+        // A real app-server rejects an unsaved thread on resume. No model request is
+        // needed to prove that reopening the agent remains safe before its first turn.
+        for (let i = 0; i < 2; i++) {
+          const reopened = await manager.reloadAgentSession(agentId);
+          expect(reopened.lifecycle).toBe("idle");
+          expect(reopened.persistence).toBeNull();
+        }
+        await storage.flush();
+        expect((await storage.get(agentId))?.persistence).toBeNull();
+      } finally {
+        if (agentId && manager.getAgent(agentId)) await manager.closeAgent(agentId);
+        await storage.flush();
+        rmSync(cwd, { recursive: true, force: true });
+      }
+    },
+    30_000,
+  );
+
+  test.runIf(isCodexInstalled())(
+    "reopens an agent that was never prompted without resuming its unsaved thread",
+    async () => {
+      const cwd = mkdtempSync(path.join(os.tmpdir(), "codex-unprompted-cwd-"));
+      const codexHome = mkdtempSync(path.join(os.tmpdir(), "codex-unprompted-home-"));
+      const mockServer = await startMockResponsesServer([
+        assistantMessageSse("first"),
+        assistantMessageSse("second"),
+      ]);
+      const logger = createTestLogger();
+      const storage = new AgentStorage(path.join(cwd, "agents"), logger);
+      const manager = new AgentManager({
+        clients: { codex: new CodexAppServerAgentClient(logger) },
+        registry: storage,
+        logger,
+      });
+      let agentId: string | undefined;
+      try {
+        writeMockCodexConfig(codexHome, mockServer.url);
+        vi.stubEnv("CODEX_HOME", codexHome);
+        const created = await manager.createAgent(
+          { provider: "codex", cwd, modeId: "auto", model: "mock-model" },
+          undefined,
+          { workspaceId: undefined },
+        );
+        agentId = created.id;
+        // Codex writes a thread's rollout at its first turn, so there is nothing to resume yet.
+        expect(manager.getAgent(agentId)?.persistence).toBeNull();
+        await storage.flush();
+        expect((await storage.get(agentId))?.persistence).toBeNull();
+
+        await manager.reloadAgentSession(agentId);
+        await manager.runAgent(agentId, "first prompt after reopening");
+        const threadId = manager.getAgent(agentId)?.persistence?.sessionId;
+        expect(threadId).toEqual(expect.any(String));
+        await storage.flush();
+        expect((await storage.get(agentId))?.persistence?.sessionId).toBe(threadId);
+
+        const reloaded = await manager.reloadAgentSession(agentId);
+        expect(reloaded.persistence?.sessionId).toBe(threadId);
+        await manager.runAgent(agentId, "continue the saved thread");
+        expect(manager.getAgent(agentId)?.lifecycle).toBe("idle");
+        expect(mockServer.requestBodies.at(-1)).toContain("first prompt after reopening");
+      } finally {
+        if (agentId && manager.getAgent(agentId)) await manager.closeAgent(agentId);
+        await storage.flush();
+        vi.unstubAllEnvs();
+        await mockServer.close();
+        rmSync(cwd, { recursive: true, force: true });
+        rmSync(codexHome, { recursive: true, force: true });
+      }
+    },
+    30_000,
+  );
+
   test.runIf(isCodexInstalled())(
     "surfaces request_user_input from the app-server as question permissions and timeline tool calls",
     async () => {
@@ -293,7 +412,7 @@ describe("Codex app-server provider (local e2e)", () => {
         );
 
         try {
-          await session.setFeature?.("plan_mode", true);
+          await session.applyOptions!({ plan_mode: true });
 
           const events: AgentStreamEvent[] = [];
           session.subscribe((event) => {
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.process-exit.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.process-exit.test.ts
index 9cfeca60d3..e0fa956786 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.process-exit.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.process-exit.test.ts
@@ -38,7 +38,7 @@ async function withPendingPlan(
     cwd: workdir,
     modeId: "auto",
     model: "gpt-5.4",
-    featureValues: { plan_mode: true },
+    providerOptions: { plan_mode: true },
   });
   const events: AgentStreamEvent[] = [];
   session.subscribe((event) => events.push(event));
@@ -526,7 +526,7 @@ test("idle provider exit preserves a synthetic plan approval across reconnect",
         cwd: workdir,
         modeId: "auto",
         model: "gpt-5.4",
-        featureValues: { plan_mode: true },
+        providerOptions: { plan_mode: true },
       },
       undefined,
       { workspaceId: undefined },
@@ -587,6 +587,10 @@ test("concurrent session APIs share one reconnect after an idle provider exit",
     createFakeCodexAppServer(),
   ];
   let spawnCount = 0;
+  let markReconnectStarted!: () => void;
+  const reconnectStarted = new Promise<void>((resolve) => {
+    markReconnectStarted = resolve;
+  });
   let releaseReconnect: (() => void) | undefined;
   const reconnectGate = new Promise<void>((resolve) => {
     releaseReconnect = resolve;
@@ -602,6 +606,7 @@ test("concurrent session APIs share one reconnect after an idle provider exit",
       }
       spawnCount += 1;
       if (spawnCount > 1) {
+        markReconnectStarted();
         await reconnectGate;
       }
       return appServer.child;
@@ -614,12 +619,14 @@ test("concurrent session APIs share one reconnect after an idle provider exit",
 
     const runtimeInfo = session.getRuntimeInfo();
     const turnStart = session.startTurn("continue after reconnect");
+    await reconnectStarted;
     const reconnectSpawnCount = spawnCount - 1;
     releaseReconnect?.();
 
     await expect(runtimeInfo).resolves.toMatchObject({ provider: "codex" });
     await expect(turnStart).resolves.toMatchObject({ turnId: expect.any(String) });
     expect(reconnectSpawnCount).toBe(1);
+    expect(spawnCount).toBe(2);
   } finally {
     releaseReconnect?.();
     await session.close();
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.spawn-error.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.spawn-error.test.ts
index bff992e2ff..8cb8649e26 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.spawn-error.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.spawn-error.test.ts
@@ -35,15 +35,14 @@ describe("CodexAppServerAgentClient spawn error handling", () => {
   });
 
   test("fetchCatalog settles when the refresh deadline aborts an unanswered initialize", async () => {
-    const client = new CodexAppServerAgentClient(logger, {
-      command: {
-        mode: "replace",
-        argv: ["/nonexistent/codex-binary-that-does-not-exist"],
-      },
-    });
     const child = createCodexAppServerChildProcess();
     const kill = vi.spyOn(child, "kill");
-    Object.assign(client, { spawnAppServer: async () => child });
+    const client = new CodexAppServerAgentClient(logger, undefined, {
+      appServerProcess: {
+        resolvePrefix: async () => ({ command: "codex", args: [] }),
+        spawn: () => child,
+      },
+    });
 
     await expect(
       runProviderRefreshWithDeadline({
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.test.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.test.ts
index 22941ed2fc..08e883fad5 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.test.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.test.ts
@@ -87,9 +87,11 @@ describe("Codex executable discovery", () => {
 
 import { CodexAppServerClient } from "./codex/app-server-transport.js";
 import {
+  createCodexAppServerChildProcess,
   createFakeCodexAppServer,
   fakeCodexThreadHistory,
   type FakeCodexAppServer,
+  waitForNextEvent,
   waitForNextPermission,
   waitForNextTimelineItem,
   waitForProviderSubagent,
@@ -184,18 +186,24 @@ function createProviderWithFakeAppServer(
 ): CodexAppServerAgentClient {
   const provider = new CodexAppServerAgentClient(createTestLogger(), options?.runtimeSettings, {
     customProvider: options?.customProvider,
+    appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
   });
   const internals = castInternals<{
     goalsEnabledPromise: Promise<boolean> | null;
     autoReviewEnabledPromise: Promise<boolean> | null;
-    spawnAppServer: () => Promise<ChildProcessWithoutNullStreams>;
   }>(provider);
   internals.goalsEnabledPromise = Promise.resolve(false);
   internals.autoReviewEnabledPromise = Promise.resolve(false);
-  internals.spawnAppServer = async () => appServer.child;
   return provider;
 }
 
+function createFakeCodexAppServerProcess(spawn: () => ChildProcessWithoutNullStreams) {
+  return {
+    resolvePrefix: async () => ({ command: "codex", args: [] }),
+    spawn: () => spawn(),
+  };
+}
+
 async function startPublicSteeringSession(
   appServer: FakeCodexAppServer,
   resolveSlashCommandInvocation?: (prompt: AgentPromptInput) => Promise<{
@@ -226,6 +234,57 @@ function deferred<T>() {
   return { promise, resolve };
 }
 
+describe("Codex file-change approvals", () => {
+  test("file-change approval includes the matching patch when notifications are still queued", async () => {
+    const appServer = createFakeCodexAppServer();
+    const { session } = await startPublicSteeringSession(appServer);
+    try {
+      for (const [id, filePath, diff] of [
+        ["file-alpha", "/workspace/project/alpha.txt", "@@ -1 +1 @@\n-blue\n+green\n"],
+        ["file-beta", "/workspace/project/beta.txt", "@@ -1 +1 @@\n-small\n+large\n"],
+      ]) {
+        appServer.startsFileChange({
+          threadId: "thread-1",
+          turnId: "native-A",
+          callId: id,
+          path: filePath,
+          diff,
+        });
+      }
+      const permission = waitForNextPermission(session);
+      appServer.requestFileChangeApproval({
+        itemId: "file-alpha",
+        threadId: "thread-1",
+        turnId: "native-A",
+        reason: "Apply the patch",
+      });
+
+      expect((await permission).request).toEqual({
+        id: "permission-file-alpha",
+        provider: "codex",
+        name: "CodexFileChange",
+        kind: "tool",
+        title: "Apply file changes: alpha.txt",
+        description: "Apply the patch",
+        detail: {
+          type: "edit",
+          filePath: "alpha.txt",
+          unifiedDiff: "@@ -1 +1 @@\n-blue\n+green\n",
+        },
+        metadata: { itemId: "file-alpha", threadId: "thread-1", turnId: "native-A" },
+      });
+
+      await session.respondToPermission("permission-file-alpha", { behavior: "allow" });
+      await expect(appServer.waitForApprovalDecision("file-alpha")).resolves.toEqual({
+        decision: "accept",
+      });
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+});
+
 describe("Codex active-turn steering admission", () => {
   test("steers an accepted turn whose native id arrives after startTurn returns", async () => {
     const appServer = createFakeCodexAppServer({
@@ -574,24 +633,25 @@ function codexAgentItem(text: string) {
 // app-server serving `threads` from thread/read.
 function createReopenableCodexAgent(threads: Record<string, unknown[]>) {
   const appServers: FakeCodexAppServer[] = [];
-  const provider = new CodexAppServerAgentClient(createTestLogger());
+  const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+    appServerProcess: createFakeCodexAppServerProcess(() => {
+      const appServer = createFakeCodexAppServer({
+        "thread/read": (params) => {
+          const { threadId } = params as { threadId: string };
+          return { thread: { id: threadId, turns: threads[threadId] ?? [] } };
+        },
+      });
+      appServers.push(appServer);
+      return appServer.child;
+    }),
+  });
   const internals = castInternals<{
     goalsEnabledPromise: Promise<boolean> | null;
     autoReviewEnabledPromise: Promise<boolean> | null;
-    spawnAppServer: () => Promise<ChildProcessWithoutNullStreams>;
   }>(provider);
   internals.goalsEnabledPromise = Promise.resolve(false);
   internals.autoReviewEnabledPromise = Promise.resolve(false);
-  internals.spawnAppServer = async () => {
-    const appServer = createFakeCodexAppServer({
-      "thread/read": (params) => {
-        const { threadId } = params as { threadId: string };
-        return { thread: { id: threadId, turns: threads[threadId] ?? [] } };
-      },
-    });
-    appServers.push(appServer);
-    return appServer.child;
-  };
+
   // The fake app-server stands in for the Codex CLI, which test machines may not have.
   const client: AgentClient = {
     provider: "codex",
@@ -649,6 +709,20 @@ function markdownImageSource(markdown: string): string {
   return source.startsWith("file://") ? fileURLToPath(source) : source;
 }
 
+function latestBackgroundWork(events: AgentStreamEvent[]) {
+  return events.findLast((event) => event.type === "background_work");
+}
+
+function hasBackgroundListRequest(appServer: FakeCodexAppServer, threadId: string) {
+  return appServer
+    .requests()
+    .some(
+      (request) =>
+        request.method === "thread/backgroundTerminals/list" &&
+        (request.params as { threadId: string }).threadId === threadId,
+    );
+}
+
 function emitCodexUserMessage(
   appServer: FakeCodexAppServer,
   input: { id: string; text: string; threadId?: string; turnId?: string },
@@ -1284,8 +1358,11 @@ describe("Codex app-server provider", () => {
     const firstSession = await createProviderWithFakeAppServer(beforeRestart).createSession(
       createConfig({ thinkingOptionId: undefined }),
     );
-    await firstSession.startTurn("first turn");
+    const firstTurn = await firstSession.startTurn("first turn");
     await expect(beforeRestart.waitForTurnStart()).resolves.toMatchObject({ effort: "medium" });
+    const saved = waitForNextEvent(firstSession, "thread_started");
+    beforeRestart.startsTurn({ threadId: "thread-1" });
+    await saved;
     const handle = firstSession.describePersistence()!;
     await firstSession.close();
 
@@ -1300,7 +1377,8 @@ describe("Codex app-server provider", () => {
       await expect(resumed.getRuntimeInfo()).resolves.toMatchObject({
         thinkingOptionId: "medium",
       });
-      await resumed.startTurn("turn after restart");
+      const resumedTurn = await resumed.startTurn("turn after restart");
+      expect(resumedTurn.turnId).not.toBe(firstTurn.turnId);
       await expect(afterRestart.waitForTurnStart()).resolves.toMatchObject({ effort: "medium" });
       beforeRestart.assertNoErrors();
       afterRestart.assertNoErrors();
@@ -1309,6 +1387,42 @@ describe("Codex app-server provider", () => {
     }
   });
 
+  test.each([undefined, "configured-model"])(
+    "import resolves model %s before the first collaboration turn",
+    async (configuredModel) => {
+      const appServer = createFakeCodexAppServer({
+        "config/read": () => ({
+          config: { model: configuredModel, model_reasoning_effort: "low" },
+        }),
+        "collaborationMode/list": () => ({
+          data: [{ name: "Code", mode: "default", model: null, reasoning_effort: null }],
+        }),
+      });
+      const provider = createProviderWithFakeAppServer(appServer);
+      const config = createConfig({ model: undefined, thinkingOptionId: undefined });
+      const imported = await provider.importSession(
+        { providerHandleId: "native-thread", cwd: config.cwd! },
+        { config, storedConfig: config },
+      );
+
+      try {
+        await imported.session.startTurn("first follow-up after import");
+        await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+          threadId: "native-thread",
+          model: configuredModel ?? "gpt-5.4",
+          effort: "low",
+          collaborationMode: {
+            mode: "default",
+            settings: { model: configuredModel ?? "gpt-5.4", reasoning_effort: "low" },
+          },
+        });
+        appServer.assertNoErrors();
+      } finally {
+        await imported.session.close();
+      }
+    },
+  );
+
   test("provider persistence leaves options owned by the stored agent config", async () => {
     const appServer = createFakeCodexAppServer();
     const provider = createProviderWithFakeAppServer(appServer);
@@ -1318,6 +1432,9 @@ describe("Codex app-server provider", () => {
     try {
       await session.startTurn("persist the configured session");
       await appServer.waitForTurnStart();
+      const saved = waitForNextEvent(session, "thread_started");
+      appServer.startsTurn({ threadId: "thread-1" });
+      await saved;
       const handle = session.describePersistence()!;
       expect(handle.metadata).not.toHaveProperty("providerOptions");
       appServer.assertNoErrors();
@@ -1326,6 +1443,55 @@ describe("Codex app-server provider", () => {
     }
   });
 
+  test("reports a new thread only after Codex announces its first turn", async () => {
+    const appServer = createFakeCodexAppServer();
+    const session = await createProviderWithFakeAppServer(appServer).createSession(createConfig());
+    try {
+      // Codex has started the thread but writes its rollout at the first turn, so another
+      // app-server could not resume it yet.
+      await expect(session.getRuntimeInfo()).resolves.toMatchObject({ sessionId: null });
+      expect(session.describePersistence()).toBeNull();
+      expect(
+        appServer.requests().filter((request) => request.method === "thread/start"),
+      ).toHaveLength(1);
+
+      await session.startTurn("first prompt");
+      await appServer.waitForTurnStart();
+      expect(session.describePersistence()).toBeNull();
+
+      const saved = waitForNextEvent(session, "thread_started");
+      appServer.startsTurn({ threadId: "thread-1" });
+      await expect(saved).resolves.toMatchObject({
+        type: "thread_started",
+        provider: "codex",
+        sessionId: "thread-1",
+      });
+      expect(session.describePersistence()).toMatchObject({
+        sessionId: "thread-1",
+        nativeHandle: "thread-1",
+      });
+      await expect(session.getRuntimeInfo()).resolves.toMatchObject({ sessionId: "thread-1" });
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("reports a resumed thread before its next turn", async () => {
+    const appServer = createFakeCodexAppServer();
+    const session = await createProviderWithFakeAppServer(appServer).resumeSession(
+      { provider: "codex", sessionId: "saved-thread" },
+      createConfig(),
+    );
+    try {
+      expect(session.describePersistence()).toMatchObject({ sessionId: "saved-thread" });
+      await expect(session.getRuntimeInfo()).resolves.toMatchObject({ sessionId: "saved-thread" });
+      appServer.assertNoErrors();
+    } finally {
+      await session.close();
+    }
+  });
+
   test("preapproves only granted tools on the injected Codex MCP server", async () => {
     const session = createSession({
       modeId: undefined,
@@ -2064,13 +2230,16 @@ describe("Codex app-server provider", () => {
         expect.objectContaining({ type: "user_message", messageId: "user-1", text: "Hello" }),
         expect.objectContaining({ type: "assistant_message", text: "Hi there." }),
       ]);
-      expect(codex.threadMethods(0)).toEqual([
+      // Background terminal observation is independent of conversation history loading.
+      const historyMethods = (index: number) =>
+        codex.threadMethods(index).filter((method) => method !== "thread/backgroundTerminals/list");
+      expect(historyMethods(0)).toEqual([
         "thread/loaded/list",
         "thread/resume",
         "thread/read",
         "thread/read",
       ]);
-      expect(codex.threadMethods(1)).toEqual(["thread/loaded/list", "thread/resume"]);
+      expect(historyMethods(1)).toEqual(["thread/loaded/list", "thread/resume"]);
       expect(await codex.manager.getTimeline(codex.agentId)).toEqual(projected);
     } finally {
       await codex.close();
@@ -2212,10 +2381,9 @@ describe("Codex app-server provider", () => {
         return { thread: { id: "native-thread-id" } };
       },
     });
-    const provider = new CodexAppServerAgentClient(createTestLogger());
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => appServer.child;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
+    });
 
     await provider.unarchiveNativeSession({
       provider: "codex",
@@ -2237,10 +2405,9 @@ describe("Codex app-server provider", () => {
         return { thread: { id: "native-thread-id" } };
       },
     });
-    const provider = new CodexAppServerAgentClient(createTestLogger());
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => appServer.child;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
+    });
 
     await provider.archiveNativeSession({
       provider: "codex",
@@ -2262,10 +2429,9 @@ describe("Codex app-server provider", () => {
         return { thread: { id: "persisted-thread-id" } };
       },
     });
-    const provider = new CodexAppServerAgentClient(createTestLogger());
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => appServer.child;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
+    });
 
     await provider.unarchiveNativeSession({
       provider: "codex",
@@ -2294,10 +2460,9 @@ describe("Codex app-server provider", () => {
         return { thread: { id: "active-thread-id", turns: [] } };
       },
     });
-    const provider = new CodexAppServerAgentClient(createTestLogger());
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => appServer.child;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
+    });
 
     await provider.unarchiveNativeSession({
       provider: "codex",
@@ -2327,10 +2492,9 @@ describe("Codex app-server provider", () => {
         return Promise.reject(new Error("thread not found"));
       },
     });
-    const provider = new CodexAppServerAgentClient(createTestLogger());
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => appServer.child;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => appServer.child),
+    });
 
     await expect(
       provider.unarchiveNativeSession({
@@ -2440,6 +2604,77 @@ describe("Codex app-server provider", () => {
     await session.close();
   });
 
+  test("keeps a background terminal controllable on its original thread after rewind", async () => {
+    let live = true;
+    const appServer = createFakeCodexAppServer({
+      initialize: () => ({ userAgent: "paseo/0.159.0 (Ubuntu 26.4.0; x86_64) (paseo; 0)" }),
+      "thread/read": () => ({ thread: { id: "thread-1", historyMode: "legacy", turns: [] } }),
+      "thread/backgroundTerminals/list": (params) => {
+        const threadId = (params as { threadId: string }).threadId;
+        if (threadId === "thread-1" && live)
+          return { data: [{ processId: "12", command: "sleep 180" }], nextCursor: null };
+        if (threadId === "forked-thread")
+          return { data: [{ processId: "12", command: "sleep 99" }], nextCursor: null };
+        return { data: [], nextCursor: null };
+      },
+      "thread/backgroundTerminals/terminate": (params) => {
+        expect(params).toMatchObject({ threadId: "thread-1", processId: "12" });
+        live = false;
+        return { terminated: true };
+      },
+    });
+    const session = new CodexAppServerAgentSession(
+      createConfig({ cwd: "/workspace/project" }),
+      null,
+      createTestLogger(),
+      async () => appServer.child,
+    );
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+    try {
+      await session.startTurn("first");
+      emitCodexUserMessage(appServer, { id: "first", text: "first", turnId: "turn-first" });
+      appServer.completeTurn();
+      await vi.waitFor(() =>
+        expect(latestBackgroundWork(events)).toMatchObject({
+          items: [{ command: "sleep 180" }],
+        }),
+      );
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await session.startTurn("second");
+      emitCodexUserMessage(appServer, { id: "second", text: "second", turnId: "turn-second" });
+      appServer.completeTurn();
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      await session.revertConversation({ messageId: "second" });
+      await session.startTurn("continue");
+      appServer.startsTerminalCommand({
+        threadId: "forked-thread",
+        turnId: "turn-next",
+        itemId: "new",
+        processId: "12",
+        command: "echo hello",
+      });
+      await vi.waitFor(() =>
+        expect(hasBackgroundListRequest(appServer, "forked-thread")).toBe(true),
+      );
+      await vi.waitFor(() =>
+        expect(latestBackgroundWork(events)).toMatchObject({
+          items: [{ command: "sleep 180" }, { command: "sleep 99" }],
+        }),
+      );
+      const items = latestBackgroundWork(events)?.items;
+      expect(items).toHaveLength(2);
+      expect(items![0].id).not.toBe(items![1].id);
+      await session.stopBackgroundWork(items![0].id);
+      expect(latestBackgroundWork(events)).toMatchObject({
+        items: [{ command: "sleep 99" }],
+      });
+    } finally {
+      await session.close();
+    }
+  });
+
   test("rewinds a paginated conversation through the public session capability", async () => {
     const appServer = createFakeCodexAppServer({
       ...fakeCodexThreadHistory({
@@ -2603,7 +2838,12 @@ describe("Codex app-server provider", () => {
         clientMessageId: "client-message",
       },
     });
-    expect(events.slice(0, 2).map((event) => event.type)).toEqual(["turn_started", "timeline"]);
+    // The first turn of a new thread also reports the thread, now that Codex has saved it.
+    expect(events.slice(0, 3).map((event) => event.type)).toEqual([
+      "thread_started",
+      "turn_started",
+      "timeline",
+    ]);
     appServer.completeTurn();
     await new Promise<void>((resolve) => setImmediate(resolve));
     await new Promise<void>((resolve) => setImmediate(resolve));
@@ -3323,6 +3563,87 @@ describe("Codex app-server provider", () => {
     }
   });
 
+  test.each([
+    ["patch_apply_begin", undefined, "running", null],
+    ["patch_apply_end", true, "completed", null],
+    ["patch_apply_end", false, "failed", { message: "Cannot apply patch" }],
+  ] as const)(
+    "maps both files from legacy %s notifications (success: %s)",
+    async (type, success, status, error) => {
+      const appServer = createFakeCodexAppServer();
+      const session = new CodexAppServerAgentSession(
+        createConfig({ cwd: "/tmp/repo" }),
+        null,
+        createTestLogger(),
+        async () => appServer.child,
+      );
+      try {
+        await session.connect();
+        const nextTimelineItem = waitForNextTimelineItem(session);
+        appServer.child.stdout.write(
+          `${JSON.stringify({
+            method: `codex/event/${type}`,
+            params: {
+              conversationId: "thread-1",
+              msg: {
+                type,
+                call_id: "patch-array-alias",
+                changes: [
+                  {
+                    path: "/tmp/repo/src/array-alias.ts",
+                    kind: "modify",
+                    unified_diff: "@@\n-old\n+new\n",
+                  },
+                  {
+                    path: "/tmp/repo/src/second.ts",
+                    kind: "modify",
+                    unified_diff: "@@\n-before\n+after\n",
+                  },
+                ],
+                success,
+                stderr: "Cannot apply patch",
+              },
+            },
+          })}\n`,
+        );
+
+        await expect(nextTimelineItem).resolves.toEqual({
+          type: "timeline",
+          provider: "codex",
+          item: {
+            type: "tool_call",
+            callId: "patch-array-alias",
+            name: "apply_patch",
+            status,
+            error,
+            detail: {
+              type: "edit",
+              filePath: "src/array-alias.ts",
+              unifiedDiff: [
+                "diff --git a/src/array-alias.ts b/src/array-alias.ts",
+                "--- a/src/array-alias.ts",
+                "+++ b/src/array-alias.ts",
+                "@@",
+                "-old",
+                "+new",
+                "",
+                "diff --git a/src/second.ts b/src/second.ts",
+                "--- a/src/second.ts",
+                "+++ b/src/second.ts",
+                "@@",
+                "-before",
+                "+after",
+              ].join("\n"),
+            },
+          },
+        });
+        appServer.assertNoErrors();
+      } finally {
+        await session.close();
+      }
+    },
+  );
+
   test("maps Codex plan markdown to a synthetic plan tool call", () => {
     const item = mapCodexPlanToToolCall({
       callId: "plan-turn-1",
@@ -4532,6 +4853,7 @@ describe("Codex app-server provider", () => {
     );
 
     try {
+      const started = waitForNextEvent(session, "turn_started");
       const resultPromise = session.run("Delegate the investigation.");
       await appServer.waitForTurnStart();
       const child = waitForProviderSubagent(session, "legacy-only-child-thread");
@@ -4549,7 +4871,7 @@ describe("Codex app-server provider", () => {
       await expect(child).resolves.toMatchObject({
         type: "provider_subagent",
         provider: "codex",
-        turnId: "codex-turn-0",
+        turnId: (await started).turnId,
         event: {
           type: "upsert",
           id: "legacy-only-child-thread",
@@ -4559,7 +4881,7 @@ describe("Codex app-server provider", () => {
       await expect(spawn).resolves.toMatchObject({
         type: "timeline",
         provider: "codex",
-        turnId: "codex-turn-0",
+        turnId: (await started).turnId,
         item: {
           type: "tool_call",
           callId: "spawn-legacy-only-child",
@@ -6126,7 +6448,7 @@ describe("Codex app-server provider", () => {
 
   test("emits a synthetic plan approval permission after a successful Codex plan turn", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6196,7 +6518,7 @@ describe("Codex app-server provider", () => {
 
   test("does not complete Codex plan timeline cards while plan approval is pending", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6242,7 +6564,7 @@ describe("Codex app-server provider", () => {
 
   test("replaces a pending synthetic plan approval when a later plan completes", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6275,7 +6597,7 @@ describe("Codex app-server provider", () => {
 
   test("dismisses a pending synthetic plan approval after a new prompt is accepted", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -6317,7 +6639,7 @@ describe("Codex app-server provider", () => {
 
   test("makes the old plan non-actionable while a new prompt is being prepared", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6371,7 +6693,7 @@ describe("Codex app-server provider", () => {
 
   test("does not dismiss a new plan approval emitted while a prompt is being accepted", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -6421,7 +6743,7 @@ describe("Codex app-server provider", () => {
 
   test("keeps a synthetic plan dismissed when a new prompt is rejected", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true },
+      providerOptions: { plan_mode: true },
     });
 
     await asInternals(session).handleNotification("turn/started", {
@@ -7045,7 +7367,7 @@ describe("Codex app-server provider", () => {
 
   test("approving a synthetic Codex plan permission disables plan mode, preserves fast mode, and returns follow-up prompt", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -7076,9 +7398,10 @@ describe("Codex app-server provider", () => {
 
     expect(asInternals(session).serviceTier).toBe("fast");
     expect(asInternals(session).planModeEnabled).toBe(false);
-    expect(asInternals(session).config.featureValues).toEqual({
-      plan_mode: false,
-      fast_mode: true,
+    expect(events).toContainEqual({
+      type: "options_changed",
+      provider: "codex",
+      patch: { plan_mode: false },
     });
     // The session returns the follow-up prompt instead of calling startTurn directly.
     // The caller (session/agent-manager) is responsible for sending it through streamAgent.
@@ -7099,7 +7422,7 @@ describe("Codex app-server provider", () => {
 
   test("approving a synthetic Codex plan permission keeps fast mode disabled when it started disabled", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: false },
+      providerOptions: { plan_mode: true, service_tier: "default" },
     });
     const events: AgentStreamEvent[] = [];
     session.subscribe((event) => events.push(event));
@@ -7128,11 +7451,12 @@ describe("Codex app-server provider", () => {
       selectedActionId: "implement",
     });
 
-    expect(asInternals(session).serviceTier).toBeNull();
+    expect(asInternals(session).serviceTier).toBe("default");
     expect(asInternals(session).planModeEnabled).toBe(false);
-    expect(asInternals(session).config.featureValues).toEqual({
-      plan_mode: false,
-      fast_mode: false,
+    expect(events).toContainEqual({
+      type: "options_changed",
+      provider: "codex",
+      patch: { plan_mode: false },
     });
     expect(result?.followUpPrompt).toEqual(
       expect.stringContaining("The user approved the plan. Implement it now."),
@@ -7141,7 +7465,7 @@ describe("Codex app-server provider", () => {
 
   test("follow-up implementation turn keeps fast service tier and switches back to code collaboration mode", async () => {
     const session = createSession({
-      featureValues: { plan_mode: true, fast_mode: true },
+      providerOptions: { plan_mode: true, service_tier: "fast" },
     });
     asInternals(session).collaborationModes = [
       {
@@ -7212,6 +7536,52 @@ describe("Codex app-server provider", () => {
 });
 
 describe("Codex importable sessions", () => {
+  test("serializes concurrent app-server startups while allowing all scans to complete", async () => {
+    const firstEntered = deferred<void>();
+    const releaseFirst = deferred<void>();
+    let spawned = 0;
+    let activeInitializations = 0;
+    let maxActiveInitializations = 0;
+    let disposed = 0;
+    const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
+      appServerProcess: createFakeCodexAppServerProcess(() => {
+        spawned++;
+        return createCodexAppServerChildProcess();
+      }),
+      _createCodexClient: () => ({
+        request: async (method) => {
+          if (method === "initialize") {
+            activeInitializations++;
+            maxActiveInitializations = Math.max(maxActiveInitializations, activeInitializations);
+            if (spawned === 1) {
+              firstEntered.resolve();
+              await releaseFirst.promise;
+            }
+            activeInitializations--;
+            return {};
+          }
+          if (method === "thread/list") return { data: [] };
+          throw new Error(`Unexpected Codex method: ${method}`);
+        },
+        notify: () => {},
+        dispose: async () => {
+          disposed++;
+        },
+      }),
+    });
+
+    const scans = Array.from({ length: 24 }, () => provider.listImportableSessions({ limit: 1 }));
+    await firstEntered.promise;
+    expect(spawned).toBe(1);
+    releaseFirst.resolve();
+    const results = await Promise.all(scans);
+
+    expect(results).toEqual(Array.from({ length: 24 }, () => []));
+    expect(spawned).toBe(24);
+    expect(maxActiveInitializations).toBe(1);
+    expect(disposed).toBe(24);
+  });
+
   const CODEX_THREAD_PAGE_CAP = 100;
 
   // Codex answers thread/list with at most 100 rows per response whatever limit
@@ -7474,19 +7844,8 @@ describe("Codex importable sessions", () => {
 
     const provider = new CodexAppServerAgentClient(createTestLogger(), undefined, {
       _createCodexClient: () => fakeClient,
+      appServerProcess: createFakeCodexAppServerProcess(createCodexAppServerChildProcess),
     });
-    castInternals<{ spawnAppServer: () => Promise<ChildProcessWithoutNullStreams> }>(
-      provider,
-    ).spawnAppServer = async () => {
-      const child = new EventEmitter() as ChildProcessWithoutNullStreams;
-      child.exitCode = 0;
-      child.signalCode = null;
-      child.stdin = new PassThrough();
-      child.stdout = new PassThrough();
-      child.stderr = new PassThrough();
-      child.kill = vi.fn(() => true) as ChildProcessWithoutNullStreams["kill"];
-      return child;
-    };
 
     const sessions = await provider.listImportableSessions({ cwd: "/workspace/project-a" });
 
@@ -7622,7 +7981,7 @@ describe("Codex interactive resume startup", () => {
       unsubscribe();
       const laterEvents: AgentStreamEvent[] = [];
       session.subscribe((event) => laterEvents.push(event));
-      expect(laterEvents).toEqual([]);
+      expect(laterEvents.filter((event) => event.type !== "background_work")).toEqual([]);
     } finally {
       await session.close();
       appServer.assertNoErrors();
@@ -7766,3 +8125,93 @@ test("publishes a materialized image before dispatching the following turn compl
     await session.close();
   }
 });
+
+describe("legacy multi-file diff budget", () => {
+  test.each([true, false])(
+    "retains later file diffs when a large patch is running: %s",
+    (running) => {
+      const item = mapCodexPatchNotificationToToolCall({
+        callId: "large-legacy-patch",
+        cwd: "/repo",
+        running,
+        success: true,
+        changes: [
+          {
+            path: "/repo/alpha.txt",
+            kind: "modify",
+            unified_diff: "@@ -1 +1 @@\n-old\n+" + "a".repeat(14000),
+          },
+          { path: "/repo/beta.txt", kind: "modify", unified_diff: "@@ -1 +1 @@\n-small\n+large\n" },
+        ],
+      });
+      expect(item?.detail.type).toBe("edit");
+      if (item?.detail.type !== "edit") throw new Error("Expected edit detail");
+      expect(item.detail.unifiedDiff).toContain("diff --git a/beta.txt b/beta.txt");
+      expect(item.detail.unifiedDiff).toContain("+large");
+      expect(item.detail.unifiedDiff!.length).toBeLessThanOrEqual(12000);
+    },
+  );
+});
+
+describe("legacy multi-file move metadata", () => {
+  test.each([true, false])("preserves path-keyed moves while running: %s", (running) => {
+    const item = mapCodexPatchNotificationToToolCall({
+      callId: "legacy-move",
+      cwd: "/repo",
+      running,
+      success: true,
+      changes: {
+        "/repo/old.txt": {
+          type: "update",
+          move_path: "/repo/new.txt",
+          unified_diff: "@@ -1 +1 @@\n-old\n+new\n",
+        },
+        "/repo/other.txt": { type: "update", unified_diff: "@@ -1 +1 @@\n-before\n+after\n" },
+      },
+    });
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/old.txt b/new.txt");
+    expect(item.detail.unifiedDiff).toContain("+++ b/new.txt");
+  });
+});
+
+describe("legacy move-only entries", () => {
+  test.each([true, false])(
+    "keeps a move-only file alongside another edit while running: %s",
+    (running) => {
+      const item = mapCodexPatchNotificationToToolCall({
+        callId: "legacy-move-only",
+        cwd: "/repo",
+        running,
+        success: true,
+        changes: {
+          "/repo/old.txt": { type: "update", move_path: "/repo/new.txt", unified_diff: "" },
+          "/repo/second.txt": { type: "update", unified_diff: "@@ -1 +1 @@\n-small\n+large\n" },
+        },
+      });
+      if (item?.detail.type !== "edit") throw new Error("Expected edit");
+      expect(item.detail.unifiedDiff).toContain("rename from old.txt\nrename to new.txt");
+      expect(item.detail.unifiedDiff).toContain("diff --git a/second.txt b/second.txt");
+    },
+  );
+});
+
+describe("legacy empty additions", () => {
+  test.each([true, false])("keeps an empty new file while running: %s", (running) => {
+    const item = mapCodexPatchNotificationToToolCall({
+      callId: "legacy-empty",
+      cwd: "/repo",
+      running,
+      success: true,
+      changes: {
+        "/repo/empty.txt": { type: "add", content: "" },
+        "/repo/second.txt": { type: "update", unified_diff: "@@ -1 +1 @@\n-old\n+new\n" },
+      },
+    });
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    expect(item.detail.unifiedDiff).toContain(
+      "diff --git a/empty.txt b/empty.txt\n--- /dev/null\n+++ b/empty.txt",
+    );
+    expect(item.detail.unifiedDiff).toContain("diff --git a/second.txt b/second.txt");
+  });
+});
diff --git a/packages/server/src/server/agent/providers/codex-app-server-agent.ts b/packages/server/src/server/agent/providers/codex-app-server-agent.ts
index b575847d06..045590c4ff 100644
--- a/packages/server/src/server/agent/providers/codex-app-server-agent.ts
+++ b/packages/server/src/server/agent/providers/codex-app-server-agent.ts
@@ -1,11 +1,14 @@
-import { validateProviderOptions } from "../provider-options.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../provider-options.js";
+import { CodexBackgroundInventory } from "./codex/background-inventory.js";
 import {
   getAgentStreamEventTurnId,
   type AgentPermissionAction,
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateSessionOptions,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentResumeSessionOptions,
   type AgentMode,
@@ -57,11 +60,13 @@ import { renderPromptAttachmentAsText } from "../prompt-attachments.js";
 import { composeSystemPromptParts } from "../system-prompt.js";
 import { CodexAsyncQuestions, codexAsyncQuestionToTimeline } from "./codex/async-questions.js";
 import {
+  fileChangesToPreview,
   mapCodexToolCallEnvelope,
   mapCodexToolCallFromThreadItem,
   normalizeCommandExecutionCommand,
   splitCodexMcpToolResultImages,
 } from "./codex/tool-call-mapper.js";
+import { normalizeCodexFilePath } from "./codex/tool-call-detail-parser.js";
 import {
   checkProviderLaunchAvailable,
   createProviderEnv,
@@ -74,10 +79,10 @@ import {
   probeExecutable,
 } from "../../../executable-resolution/executable-resolution.js";
 import { createPathEquivalenceMatcher } from "../../../utils/path.js";
-import { spawnProcess } from "../../../utils/spawn.js";
+import { spawnProcess, type SpawnProcessOptions } from "../../../utils/spawn.js";
 import { extractCodexTerminalSessionId, nonEmptyString } from "./tool-call-mapper-utils.js";
 import {
-  buildCodexFeatures,
+  buildCodexControls,
   CodexServiceTierSchema,
   readCodexServiceTier,
   type CodexServiceTier,
@@ -93,6 +98,7 @@ import {
   type CodexThreadRollbackResponse,
   type CodexAppServerTraceContext,
 } from "./codex/app-server-transport.js";
+import { codexAppServerStartup } from "./codex/app-server-startup.js";
 import { type CodexUserMessageTurnIndex, revertCodexConversation } from "./codex/rewind.js";
 import {
   type CodexHistoryRow,
@@ -152,6 +158,15 @@ function isCodexAlreadyUnarchivedError(error: unknown, threadId: string): boolea
 
 const TURN_START_TIMEOUT_MS = 90 * 1000;
 const INTERRUPT_TIMEOUT_MS = 2_000;
+// `turn/interrupt` ends a turn but leaves the shell commands it started running.
+// Each terminate is bounded by the first constant. A turn start waits for the
+// interrupted turn's commands to end, at most the interrupt's own bound plus one
+// terminate's and a margin, so it gives up only when a request outlives its timeout.
+const INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS = 2_000;
+const INTERRUPTED_TURN_CLEANUP_WAIT_MS =
+  INTERRUPT_TIMEOUT_MS + INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS + 500;
+// Turns whose commands are remembered; older turns are forgotten first.
+const INTERRUPTED_TURN_TRACKED_TURNS = 16;
 const CODEX_PROVIDER = "codex" as const;
 // These native provider identities belong to Codex, not to an older custom
 // Paseo provider. Never include them in a custom provider's legacy import scan.
@@ -281,14 +296,31 @@ const CODEX_MODES: AgentMode[] = [
 const DEFAULT_CODEX_MODE_ID = "auto";
 
 interface CodexAppServerClientLike {
-  request(method: string, params?: unknown): Promise<unknown>;
+  request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
   forkThread?(params: CodexThreadForkParams): Promise<CodexThreadForkResponse>;
   rollbackThread?(params: CodexThreadRollbackParams): Promise<CodexThreadRollbackResponse>;
   notify(method: string, params?: unknown): void;
   dispose(): Promise<void>;
 }
 
+interface CodexAppServerLaunchPrefix {
+  command: string;
+  args: string[];
+}
+
+interface CodexAppServerProcessSpawnInput extends CodexAppServerLaunchPrefix {
+  options: SpawnProcessOptions;
+}
+
+interface CodexAppServerProcessPort {
+  resolvePrefix(options: {
+    runtimeSettings?: ProviderRuntimeSettings;
+  }): Promise<CodexAppServerLaunchPrefix>;
+  spawn(input: CodexAppServerProcessSpawnInput): ChildProcess;
+}
+
 interface CodexAppServerAgentDeps {
+  appServerProcess?: CodexAppServerProcessPort;
   environment?: Record<string, string>;
   workspaceGitService?: Pick<WorkspaceGitService, "resolveRepoRoot">;
   customProvider?: {
@@ -600,10 +632,9 @@ export async function findDefaultCodexBinary(): Promise<string | null> {
   return await findCodexMicrosoftStoreBinary();
 }
 
-async function resolveCodexLaunchPrefix(runtimeSettings?: ProviderRuntimeSettings): Promise<{
-  command: string;
-  args: string[];
-}> {
+async function resolveCodexLaunchPrefix(
+  runtimeSettings?: ProviderRuntimeSettings,
+): Promise<CodexAppServerLaunchPrefix> {
   const launch = await resolveCodexLaunch(runtimeSettings);
   const availability = await checkCodexLaunchAvailable(launch);
   if (!availability.available) {
@@ -618,6 +649,11 @@ async function resolveCodexLaunchPrefix(runtimeSettings?: ProviderRuntimeSetting
   };
 }
 
+const defaultCodexAppServerProcess: CodexAppServerProcessPort = {
+  resolvePrefix: ({ runtimeSettings }) => resolveCodexLaunchPrefix(runtimeSettings),
+  spawn: ({ command, args, options }) => spawnProcess(command, args, options),
+};
+
 async function resolveCodexLaunch(
   runtimeSettings?: ProviderRuntimeSettings,
 ): Promise<ResolvedProviderLaunch> {
@@ -1395,6 +1431,15 @@ interface CodexPatchFileChange {
   path: string;
   kind?: string;
   content?: string;
+  movePath?: string;
+}
+
+function codexPatchMovePath(value: unknown): string | undefined {
+  const record = toObjectRecord(value);
+  if (!record) return undefined;
+  const kind = toObjectRecord(record.kind);
+  const destination = record.move_path ?? kind?.move_path;
+  return typeof destination === "string" ? destination : undefined;
 }
 
 function extractPatchLikeText(value: unknown): string | undefined {
@@ -1527,6 +1572,7 @@ function parseCodexPatchChanges(changes: unknown): CodexPatchFileChange[] {
             (typeof record.type === "string" && record.type) ||
             undefined,
           content: extractPatchLikeText(record),
+          movePath: codexPatchMovePath(record),
         };
       })
       .filter((entry): entry is CodexPatchFileChange => entry !== null);
@@ -1546,6 +1592,7 @@ function parseCodexPatchChanges(changes: unknown): CodexPatchFileChange[] {
           (typeof recordChanges.type === "string" && recordChanges.type) ||
           undefined,
         content: extractPatchLikeText(recordChanges),
+        movePath: codexPatchMovePath(recordChanges),
       },
     ];
   }
@@ -1565,6 +1612,7 @@ function parseCodexPatchChanges(changes: unknown): CodexPatchFileChange[] {
             ? ((value as { type?: string }).type ?? undefined)
             : undefined,
         content: extractPatchLikeText(value),
+        movePath: codexPatchMovePath(value),
       };
     })
     .filter((entry): entry is CodexPatchFileChange => entry !== null);
@@ -1673,6 +1721,31 @@ function mapCodexExecNotificationToToolCall(params: {
   return params.running ? toRunningToolCall(mapped) : mapped;
 }
 
+function codexPatchPreview(
+  files: CodexPatchFileChange[],
+  cwd?: string | null,
+): {
+  filePath: string | undefined;
+  patchText: string | undefined;
+} {
+  const preview =
+    files.length > 1
+      ? fileChangesToPreview(
+          files.map((file) => ({
+            path: normalizeCodexFilePath(file.path, cwd) ?? file.path,
+            kind: file.kind,
+            diff: file.content,
+            movePath: file.movePath ? normalizeCodexFilePath(file.movePath, cwd) : undefined,
+          })),
+        )
+      : undefined;
+  const firstPath = preview?.filePath ?? files[0]?.path;
+  const firstPatchText = files
+    .map((file) => file.content?.trim())
+    .find((value): value is string => typeof value === "string" && value.length > 0);
+  return { filePath: firstPath, patchText: preview?.unifiedDiff ?? firstPatchText };
+}
+
 export function mapCodexPatchNotificationToToolCall(params: {
   callId?: string | null;
   changes: unknown;
@@ -1683,11 +1756,7 @@ export function mapCodexPatchNotificationToToolCall(params: {
   running: boolean;
 }): ToolCallTimelineItem | null {
   const files = parseCodexPatchChanges(params.changes);
-  const firstPath = files[0]?.path;
-  const firstPatchText = files
-    .map((file) => file.content?.trim())
-    .find((value): value is string => typeof value === "string" && value.length > 0);
-  const patchText = firstPatchText;
+  const { filePath: firstPath, patchText } = codexPatchPreview(files, params.cwd);
   const patchFields = codexPatchTextFields(patchText);
   const mapped = mapCodexToolCallEnvelope({
     callId: params.callId ?? null,
@@ -3326,6 +3395,14 @@ export function buildCodexAppServerEnv(
   });
 }
 
+function codexStartupStateDirKey(environment: NodeJS.ProcessEnv): string {
+  const home =
+    process.platform === "win32"
+      ? environment.USERPROFILE || os.homedir()
+      : environment.HOME || os.homedir();
+  return path.resolve(environment.CODEX_HOME || path.join(home, ".codex"));
+}
+
 function buildCodexAppServerInitializeParams(): {
   clientInfo: { name: string; title: string; version: string };
   capabilities: { experimentalApi: true; mcpServerOpenaiFormElicitation: true };
@@ -3431,12 +3508,15 @@ export class CodexAppServerAgentSession implements AgentSession {
   private readonly codexHome: string;
   private currentMode: string;
   private hasWorkflowModeOverride: boolean;
-  private readonly providerOptions: CodexProviderOptions;
+  private providerOptions: CodexProviderOptions;
   private resolvedWorkspaceWrite: NonNullable<
     CodexProviderOptions["sandbox_workspace_write"]
   > | null = null;
   private resolvedSandboxPolicy: Record<string, unknown> | null = null;
   private currentThreadId: string | null = null;
+  // Codex writes a new thread's rollout at its first turn. Until then the thread exists only
+  // in this app-server, so no other app-server can resume it and it is not reported.
+  private savedThreadId: string | null = null;
   private currentTurnId: string | null = null;
   private pendingForegroundTurnIdentification: {
     foregroundTurnId: string;
@@ -3449,14 +3529,19 @@ export class CodexAppServerAgentSession implements AgentSession {
     cancelRequested: boolean;
   } | null = null;
   private client: CodexAppServerClient | null = null;
+  private readonly background = new CodexBackgroundInventory((event) => this.emitEvent(event));
   private threadRollbackAvailable = true;
   private readonly subscribers = new Set<(event: AgentStreamEvent) => void>();
   private startupEvents: AgentStreamEvent[] | null = null;
+  /** How the opened session differs from the options it was given; reported at first subscribe. */
+  openOptionsPatch: Record<string, unknown> = {};
+  private readonly turnNamespace = randomUUID();
   private nextTurnOrdinal = 0;
   private activeForegroundTurnId: string | null = null;
   private activeClientMessageId: string | null = null;
   private cachedRuntimeInfo: AgentRuntimeInfo | null = null;
-  private serviceTier: string | null = null;
+  /** The tier the options ask for; `serviceTier` is what the current model can honor. */
+  private requestedServiceTier: string | null = null;
   private speedModels: CodexModel[] = [];
   private planModeEnabled = false;
   // History read by rewind or an archived resume, held until streamHistory consumes it.
@@ -3473,8 +3558,17 @@ export class CodexAppServerAgentSession implements AgentSession {
   private pendingReasoning = new Map<string, string[]>();
   private pendingCommandOutputDeltas = new Map<string, string[]>();
   private pendingFileChangeOutputDeltas = new Map<string, string[]>();
+  private pendingToolCallDetails = new Map<string, ToolCallTimelineItem["detail"]>();
   private pendingAssistantMessageBoundary = false;
   private terminalCommandByProcessId = new Map<string, string>();
+  // The root thread's still-running command process ids, keyed by the native turn that
+  // started them. Codex's `thread/backgroundTerminals/list` carries no turn, so
+  // `item/started` is the only record of which turn owns a process.
+  private terminalProcessIdsByTurnId = new Map<
+    string,
+    { processIds: Set<string>; terminatedProcessIds: Set<string>; interruptAccepted: boolean }
+  >();
+  private interruptedTurnCleanup: Promise<void> | null = null;
   private pendingUnlabeledTerminalInteractions = new Map<
     string,
     Array<{ callId: string; stdin: string | null }>
@@ -3510,6 +3604,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private unpairedCompactionItemCompletions = 0;
   private connectionState: "disconnected" | "history-ready" | "connected" = "disconnected";
   private connectionPromise: Promise<void> | null = null;
+  private readonly startupAbort = new AbortController();
   private closed = false;
   private collaborationModes: Array<{
     name: string;
@@ -3567,13 +3662,12 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.asyncQuestions = new CodexAsyncQuestions(resumeHandle?.metadata?.asyncQuestions);
     this.codexHome = deps.codexHome ?? resolveCodexHomeDir(process.env);
     this.config.thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
-    this.serviceTier = readCodexServiceTier(this.config.featureValues);
-    if (this.config.featureValues?.plan_mode) {
-      this.planModeEnabled = true;
-    }
+    this.requestedServiceTier = readCodexServiceTier(this.providerOptions);
+    this.planModeEnabled = this.providerOptions.plan_mode === true;
 
     if (this.resumeHandle?.sessionId) {
       this.currentThreadId = this.resumeHandle.sessionId;
+      this.savedThreadId = this.resumeHandle.sessionId;
       this.historyIndexed = false;
       // Resuming can start a goal before the caller receives the session.
       if (this.initialResumePurpose === "interactive") this.startupEvents = [];
@@ -3584,11 +3678,9 @@ export class CodexAppServerAgentSession implements AgentSession {
     return this.currentThreadId;
   }
 
-  get features(): AgentFeature[] {
-    return buildCodexFeatures({
+  get controls(): AgentOptionControl[] {
+    return buildCodexControls({
       serviceTiers: this.currentServiceTiers(),
-      serviceTier: this.serviceTier ?? "default",
-      planModeEnabled: this.planModeEnabled,
       planModeAvailable: this.hasPlanCollaborationMode(),
     });
   }
@@ -3626,8 +3718,15 @@ export class CodexAppServerAgentSession implements AgentSession {
       this.connectionState = "history-ready";
       return;
     }
-    const child = await this.spawnAppServer();
-    const client = new CodexAppServerClient(child, this.logger, () => this.traceContext());
+    const { client, initialized } = await codexAppServerStartup.start({
+      stateDirKey: codexStartupStateDirKey(this.harnessEnvironment),
+      spawn: this.spawnAppServer,
+      createClient: (child) =>
+        new CodexAppServerClient(child, this.logger, () => this.traceContext()),
+      initializeParams: buildCodexAppServerInitializeParams(),
+      logger: this.logger,
+      signal: this.startupAbort.signal,
+    });
     if (this.closed) {
       await client.dispose();
       throw this.createClosedError();
@@ -3640,15 +3739,13 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.registerRequestHandlers();
 
     try {
-      const initialized = toObjectRecord(
-        await client.request("initialize", buildCodexAppServerInitializeParams()),
+      this.threadRollbackAvailable = codexServerHasThreadRollback(
+        toObjectRecord(initialized)?.userAgent,
       );
-      this.threadRollbackAvailable = codexServerHasThreadRollback(initialized?.userAgent);
-      client.notify("initialized", {});
 
       this.speedModels =
         CodexModelListResponseSchema.parse(await client.request("model/list", {})).data ?? [];
-      this.reconcileServiceTier();
+      this.normalizeSpeed();
       await this.loadResolvedWorkspaceWrite();
       await this.loadCollaborationModes();
       await this.loadSkills();
@@ -3662,6 +3759,7 @@ export class CodexAppServerAgentSession implements AgentSession {
         throw this.createClosedError();
       }
       this.connectionState = "connected";
+      this.background.start({ client, thread: this.currentThreadId });
     } catch (error) {
       try {
         if (this.client === client) {
@@ -3713,6 +3811,7 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private handleUnexpectedTermination(error: Error): void {
     this.connectionState = "disconnected";
+    this.background.stop();
     const hasActiveRootTurn = this.activeForegroundTurnId !== null || this.currentTurnId !== null;
     this.clearPendingPermissions({ preservePlanApprovals: !hasActiveRootTurn });
     if (hasActiveRootTurn) {
@@ -3861,24 +3960,34 @@ export class CodexAppServerAgentSession implements AgentSession {
     return selectedModel?.serviceTiers ?? [];
   }
 
-  private reconcileServiceTier(): void {
-    const tiers = this.currentServiceTiers();
-    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
-    if (this.serviceTier === "fast" && !tiers.some((tier) => tier.id === "fast")) {
-      this.serviceTier = tiers.find((tier) => tier.name.toLowerCase() === "fast")?.id ?? null;
-    }
-    if (this.serviceTier !== "default" && !tiers.some((tier) => tier.id === this.serviceTier)) {
-      this.serviceTier = null;
-    }
-    const { fast_mode: _legacyFast, ...values } = this.config.featureValues ?? {};
-    this.config.featureValues = { ...values, service_tier: this.serviceTier ?? "default" };
+  /**
+   * A saved `service_tier: "fast"` runs as the model's Fast tier, and a tier the opening model
+   * lacks runs as Normal; the session says so in `openOptionsPatch`, so the options and the
+   * control agree (as when the model is switched later).
+   */
+  private normalizeSpeed(): void {
+    const requested = this.requestedServiceTier;
+    const resolved = this.resolveServiceTier(requested);
+    if (requested === resolved) return;
+    const runs = resolved ?? "default";
+    this.providerOptions = { ...this.providerOptions, service_tier: runs };
+    this.requestedServiceTier = runs;
+    this.openOptionsPatch = { service_tier: runs };
   }
 
-  private applyFeatureValue(featureId: "plan_mode", value: boolean): void {
-    this.config.featureValues = { ...this.config.featureValues, [featureId]: value };
-    this.planModeEnabled = value;
-    this.refreshResolvedCollaborationMode();
-    this.cachedRuntimeInfo = null;
+  private get serviceTier(): string | null {
+    return this.resolveServiceTier(this.requestedServiceTier);
+  }
+
+  private resolveServiceTier(requested: string | null): string | null {
+    // Until the model list arrives there is nothing to check the request against.
+    if (this.speedModels.length === 0 || requested === "default") return requested;
+    const tiers = this.currentServiceTiers();
+    // `fast` names whichever tier the model calls Fast.
+    if (requested === "fast" && !tiers.some((tier) => tier.id === "fast")) {
+      return tiers.find((tier) => tier.name.toLowerCase() === "fast")?.id ?? null;
+    }
+    return tiers.some((tier) => tier.id === requested) ? requested : null;
   }
 
   private rememberPlanResult(item: ToolCallTimelineItem): void {
@@ -3943,7 +4052,13 @@ export class CodexAppServerAgentSession implements AgentSession {
     const planText =
       typeof params.planText === "string" ? normalizePlanMarkdown(params.planText) : "";
 
-    this.applyFeatureValue("plan_mode", false);
+    this.setPlanMode(false);
+    // The user left plan mode; their options follow so controls and reopened sessions agree.
+    this.emitEvent({
+      type: "options_changed",
+      provider: CODEX_PROVIDER,
+      patch: { plan_mode: false },
+    });
 
     return buildCodexPlanImplementationPrompt(planText);
   }
@@ -3970,11 +4085,16 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   private async readArchivedHistory(): Promise<CodexThreadHistory> {
-    const child = await this.spawnAppServer();
-    const client = new CodexAppServerClient(child, this.logger, () => this.traceContext());
+    const { client } = await codexAppServerStartup.start({
+      stateDirKey: codexStartupStateDirKey(this.harnessEnvironment),
+      spawn: this.spawnAppServer,
+      createClient: (child) =>
+        new CodexAppServerClient(child, this.logger, () => this.traceContext()),
+      initializeParams: buildCodexAppServerInitializeParams(),
+      logger: this.logger,
+      signal: this.startupAbort.signal,
+    });
     try {
-      await client.request("initialize", buildCodexAppServerInitializeParams());
-      client.notify("initialized", {});
       return await this.readThreadHistory(client);
     } finally {
       await client.dispose();
@@ -4429,6 +4549,9 @@ export class CodexAppServerAgentSession implements AgentSession {
         hasDeveloperInstructions: turnStart.hasDeveloperInstructions,
         hasCodexConfig: turnStart.hasCodexConfig,
       });
+      // The interrupted turn's commands end before this turn begins, so none of them
+      // outlives it into the new turn.
+      await this.waitForInterruptedTurnCleanup();
       if (pendingStart.cancelRequested) {
         throw new Error("Codex turn start was interrupted before reaching Codex");
       }
@@ -4576,6 +4699,8 @@ export class CodexAppServerAgentSession implements AgentSession {
     const startupEvents = this.startupEvents;
     this.startupEvents = null;
     for (const event of startupEvents ?? []) this.notifySubscribers(event);
+    const background = this.background.snapshot();
+    if (background) callback(background);
     return () => {
       this.subscribers.delete(callback);
     };
@@ -4607,7 +4732,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
     const info: AgentRuntimeInfo = {
       provider: CODEX_PROVIDER,
-      sessionId: this.currentThreadId,
+      sessionId: this.savedCurrentThreadId(),
       model: this.config.model ?? null,
       thinkingOptionId: normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null,
       modeId: this.currentMode ?? null,
@@ -4643,9 +4768,27 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   async setModel(modelId: string | null): Promise<void> {
     this.config.model = modelId ?? undefined;
-    this.reconcileServiceTier();
     this.refreshResolvedCollaborationMode();
     this.cachedRuntimeInfo = null;
+    this.dropUnavailableServiceTier();
+  }
+
+  /**
+   * A speed the new model does not offer turns into Normal and is reported, so choosing a model
+   * that does offer it again does not bring the paid tier back. It is reported as Normal rather
+   * than removed so a configured default cannot fill the old speed back in.
+   */
+  private dropUnavailableServiceTier(): void {
+    const requested = this.requestedServiceTier;
+    if (requested === null || this.speedModels.length === 0) return;
+    if (this.isServiceTierAvailable(requested)) return;
+    this.requestedServiceTier = "default";
+    this.providerOptions = { ...this.providerOptions, service_tier: "default" };
+    this.emitEvent({
+      type: "options_changed",
+      provider: CODEX_PROVIDER,
+      patch: { service_tier: "default" },
+    });
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void | AgentProviderNotice> {
@@ -4657,35 +4800,53 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once clients use service_tier.
-    if (featureId === "fast_mode") {
-      const fast = this.currentServiceTiers().find((tier) => tier.name.toLowerCase() === "fast");
-      if (value && !fast)
+  /** Applies only the options the patch sets; the rest of the running options stay as they are. */
+  async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+    // The approval policy and sandbox are sent when the thread starts, not with each turn.
+    assertChangesAreLive({
+      provider: "codex",
+      patch: options,
+      current: this.providerOptions,
+      live: ["service_tier", "plan_mode"],
+    });
+    const valid =
+      validateProviderOptions(
+        "codex",
+        CodexProviderOptionsSchema,
+        applyProviderOptionsPatch({ options: this.providerOptions, patch: options }),
+      ) ?? {};
+    const requested = "service_tier" in options ? readCodexServiceTier(options) : null;
+    let accepted = this.requestedServiceTier;
+    if ("service_tier" in options) {
+      if (requested !== accepted && !this.isServiceTierAvailable(requested)) {
         throw new Error(
-          `Codex fast mode is not available for model '${this.config.model ?? "default"}'`,
-        );
-      return this.setFeature("service_tier", value ? fast!.id : "default");
-    }
-    if (featureId === "service_tier") {
-      if (
-        typeof value !== "string" ||
-        (value !== "default" && !this.currentServiceTiers().some((tier) => tier.id === value))
-      ) {
-        throw new Error(
-          `Codex speed '${String(value)}' is not available for model '${this.config.model ?? "default"}'`,
+          `Codex speed '${String(requested)}' is not available for model '${this.config.model ?? "default"}'`,
         );
       }
-      this.serviceTier = value;
-      this.reconcileServiceTier();
-      this.cachedRuntimeInfo = null;
-      return;
+      // The session keeps the catalog's id for the tier, so a later model switch sees what runs.
+      accepted = requested && (this.resolveServiceTier(requested) ?? requested);
     }
-    if (featureId === "plan_mode") {
-      this.applyFeatureValue("plan_mode", Boolean(value));
-      return;
-    }
-    throw new Error(`Unknown Codex feature: ${featureId}`);
+    this.providerOptions = { ...valid, ...(accepted ? { service_tier: accepted } : {}) };
+    this.requestedServiceTier = accepted || null;
+    if ("plan_mode" in options) this.setPlanMode(options.plan_mode === true);
+    this.cachedRuntimeInfo = null;
+    // The catalog may name the tier differently from the request (`fast` is the Fast tier's id).
+    const tier = this.serviceTier;
+    return tier !== null && requested !== null && tier !== requested ? { service_tier: tier } : {};
+  }
+
+  private isServiceTierAvailable(tier: string | null): boolean {
+    if (tier === null || tier === "default") return true;
+    const tiers = this.currentServiceTiers();
+    const namesFast = tier === "fast" && tiers.some((entry) => entry.name.toLowerCase() === "fast");
+    return namesFast || tiers.some((entry) => entry.id === tier);
+  }
+
+  private setPlanMode(enabled: boolean): void {
+    if (this.planModeEnabled === enabled) return;
+    this.planModeEnabled = enabled;
+    this.refreshResolvedCollaborationMode();
+    this.cachedRuntimeInfo = null;
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
@@ -4938,17 +5099,18 @@ export class CodexAppServerAgentSession implements AgentSession {
     nativeHandle: string;
     metadata: Record<string, unknown>;
   } | null {
-    if (!this.currentThreadId) return null;
+    const threadId = this.savedCurrentThreadId();
+    if (!threadId) return null;
     const thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId) ?? null;
     return {
       provider: CODEX_PROVIDER,
-      sessionId: this.currentThreadId,
-      nativeHandle: this.currentThreadId,
+      sessionId: threadId,
+      nativeHandle: threadId,
       metadata: {
         provider: CODEX_PROVIDER,
         cwd: this.config.cwd,
         title: this.config.title ?? null,
-        threadId: this.currentThreadId,
+        threadId,
         modeId: this.config.modeId,
         model: this.config.model ?? null,
         thinkingOptionId,
@@ -4960,6 +5122,12 @@ export class CodexAppServerAgentSession implements AgentSession {
     };
   }
 
+  private savedCurrentThreadId(): string | null {
+    return this.currentThreadId !== null && this.currentThreadId === this.savedThreadId
+      ? this.currentThreadId
+      : null;
+  }
+
   async revertConversation(input: { messageId: string }): Promise<ConversationRewindCut> {
     let threadBefore: string | null;
     let client: CodexAppServerClient;
@@ -4996,6 +5164,8 @@ export class CodexAppServerAgentSession implements AgentSession {
         threadRollbackAvailable: this.threadRollbackAvailable,
         setThreadId: async (threadId) => {
           this.currentThreadId = threadId;
+          // Codex writes a forked thread's rollout when it forks it, even before any turn.
+          this.savedThreadId = threadId;
           this.cachedRuntimeInfo = null;
           this.stagedHistory = await this.readThreadHistory(client);
           this.reconcileAsyncQuestionsAfterRewind(this.stagedHistory.timeline);
@@ -5049,15 +5219,27 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (!turnId || (foregroundTurnId && this.activeForegroundTurnId !== foregroundTurnId)) {
       throw new Error("Cannot interrupt Codex before turn/started identifies the active turn");
     }
+    const client = this.client;
+    const threadId = this.currentThreadId;
+    const interruptRequest = client.request(
+      "turn/interrupt",
+      {
+        threadId,
+        turnId,
+      },
+      INTERRUPT_TIMEOUT_MS,
+    );
+    // Once Codex accepts the interrupt, end the commands this turn started. Registered
+    // before the await, so a turn start racing this interrupt waits for it. An already-idle
+    // turn was not interrupted, and what it left running stays.
+    this.trackInterruptedTurnCleanup(
+      interruptRequest.then(
+        () => this.endInterruptedTurnProcesses(client, threadId, turnId),
+        () => undefined,
+      ),
+    );
     try {
-      await this.client.request(
-        "turn/interrupt",
-        {
-          threadId: this.currentThreadId,
-          turnId,
-        },
-        INTERRUPT_TIMEOUT_MS,
-      );
+      await interruptRequest;
     } catch (error) {
       if (!isCodexAlreadyIdleInterrupt(error)) {
         throw error;
@@ -5070,6 +5252,10 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
+  stopBackgroundWork(id: string): Promise<void> {
+    return this.background.stopItem(id);
+  }
+
   async canStopRuntime(): Promise<boolean> {
     if (
       !this.client ||
@@ -5098,9 +5284,143 @@ export class CodexAppServerAgentSession implements AgentSession {
     return !this.client.hasPendingRequests();
   }
 
+  // Remember which turn started a command, so an interrupt ends that turn's commands and
+  // no other turn's. Only the root thread's: a subagent's commands live on its own thread.
+  // A command that starts after its turn's interrupt was accepted is ended as soon as it
+  // is seen.
+  private recordTurnTerminalProcess(
+    parsed: Extract<ParsedCodexNotification, { kind: "item_started" | "item_completed" }>,
+  ): void {
+    const processId = parsed.item.processId;
+    if (
+      parsed.source !== "item" ||
+      !parsed.turnId ||
+      !parsed.threadId ||
+      parsed.threadId !== this.currentThreadId ||
+      typeof processId !== "string" ||
+      !processId ||
+      normalizeCodexThreadItemType(
+        typeof parsed.item.type === "string" ? parsed.item.type : undefined,
+      ) !== "commandExecution"
+    ) {
+      return;
+    }
+    const record = this.terminalProcessIdsByTurnId.get(parsed.turnId);
+    if (parsed.kind === "item_completed") {
+      // Only a completed command has exited. A failed one can still be running:
+      // Codex reports an interrupted turn's live command as failed.
+      if (parsed.item.status === "completed") record?.processIds.delete(processId);
+      return;
+    }
+    const current = record ?? this.getTurnTerminalRecord(parsed.turnId);
+    current.processIds.add(processId);
+    if (current.interruptAccepted && this.client) {
+      this.trackInterruptedTurnCleanup(
+        this.endInterruptedTurnProcesses(this.client, parsed.threadId, parsed.turnId),
+      );
+    }
+  }
+
+  // An accepted interrupt needs a record even before any of its turn's commands is seen:
+  // an `item/started` can still be queued behind an earlier notification's conversion.
+  private getTurnTerminalRecord(turnId: string) {
+    const existing = this.terminalProcessIdsByTurnId.get(turnId);
+    if (existing) return existing;
+    const record = {
+      processIds: new Set<string>(),
+      terminatedProcessIds: new Set<string>(),
+      interruptAccepted: false,
+    };
+    this.terminalProcessIdsByTurnId.set(turnId, record);
+    for (const oldestTurnId of this.terminalProcessIdsByTurnId.keys()) {
+      if (this.terminalProcessIdsByTurnId.size <= INTERRUPTED_TURN_TRACKED_TURNS) break;
+      this.terminalProcessIdsByTurnId.delete(oldestTurnId);
+    }
+    return record;
+  }
+
+  // A later sweep joins the pending one, so a turn start waits for both.
+  private trackInterruptedTurnCleanup(cleanup: Promise<void>): void {
+    const tracked = Promise.all([this.interruptedTurnCleanup, cleanup])
+      .then(() => undefined)
+      .finally(() => {
+        if (this.interruptedTurnCleanup === tracked) this.interruptedTurnCleanup = null;
+      });
+    this.interruptedTurnCleanup = tracked;
+  }
+
+  // Terminate each process the interrupted turn started, by its own id, once each.
+  // `thread/backgroundTerminals/clean` is never used: it ends every terminal on the thread,
+  // an earlier turn's included. A process already gone answers `terminated: false`. Never
+  // rejects; failures are logged.
+  private async endInterruptedTurnProcesses(
+    client: CodexAppServerClient,
+    threadId: string | null,
+    turnId: string,
+  ): Promise<void> {
+    if (!threadId) return;
+    const record = this.getTurnTerminalRecord(turnId);
+    record.interruptAccepted = true;
+    const processIds = [...record.processIds].filter(
+      (processId) => !record.terminatedProcessIds.has(processId),
+    );
+    for (const processId of processIds) record.terminatedProcessIds.add(processId);
+    const logContext = { agentId: this.agentId, provider: CODEX_PROVIDER, threadId, turnId };
+    await Promise.all(
+      processIds.map(async (processId) => {
+        try {
+          const response = await client.request(
+            "thread/backgroundTerminals/terminate",
+            { threadId, processId },
+            INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS,
+          );
+          this.logger.info(
+            { ...logContext, processId, terminated: toObjectRecord(response)?.terminated ?? null },
+            "provider.codex.interrupt.terminal_terminated",
+          );
+        } catch (error) {
+          this.logger.warn(
+            { ...logContext, processId, err: error },
+            "provider.codex.interrupt.terminal_terminate_failed",
+          );
+        }
+      }),
+    );
+  }
+
+  // A new turn starts only after every pending sweep of interrupted turns' commands has
+  // ended, or after the bound, whichever is first.
+  private async waitForInterruptedTurnCleanup(): Promise<void> {
+    if (!this.interruptedTurnCleanup) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timedOut = await Promise.race([
+      (async () => {
+        while (this.interruptedTurnCleanup) await this.interruptedTurnCleanup;
+        return false;
+      })(),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(true), INTERRUPTED_TURN_CLEANUP_WAIT_MS);
+      }),
+    ]);
+    clearTimeout(timer);
+    if (timedOut) {
+      this.logger.warn(
+        {
+          agentId: this.agentId,
+          provider: CODEX_PROVIDER,
+          waitMs: INTERRUPTED_TURN_CLEANUP_WAIT_MS,
+        },
+        "provider.codex.interrupt.terminal_cleanup_timed_out",
+      );
+    }
+  }
+
   async close(): Promise<void> {
     this.closed = true;
+    this.startupAbort.abort(this.createClosedError());
+    this.background.stop();
     this.clearPendingPermissions();
+    this.pendingToolCallDetails.clear();
     this.pendingSubAgentNotificationsByThreadId.clear();
     this.subscribers.clear();
     this.startupEvents = null;
@@ -5129,6 +5449,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   private async disposeClient(): Promise<void> {
+    this.background.stop();
     const client = this.client;
     this.connectionState = "disconnected";
     this.currentTurnId = null;
@@ -5353,8 +5674,8 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async applyDefaultModelAndThinking(): Promise<string> {
     const { model, thinkingOptionId } = await this.resolveModelAndThinking();
     this.config.model = model;
-    this.reconcileServiceTier();
     this.config.thinkingOptionId = thinkingOptionId;
+    this.refreshResolvedCollaborationMode();
     return model;
   }
 
@@ -5420,7 +5741,8 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   private buildCodexInnerConfig(): Record<string, unknown> | null {
     const innerConfig: Record<string, unknown> = {};
-    Object.assign(innerConfig, this.providerOptions);
+    const { service_tier: _tier, plan_mode: _plan, ...codexConfig } = this.providerOptions;
+    Object.assign(innerConfig, codexConfig);
     if (this.deps.customCodexConfig) {
       Object.assign(innerConfig, this.deps.customCodexConfig);
     }
@@ -5477,7 +5799,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   private createTurnId(): string {
-    return `codex-turn-${this.nextTurnOrdinal++}`;
+    return `codex-turn-${this.turnNamespace}-${this.nextTurnOrdinal++}`;
   }
 
   private pendingNotifications: Promise<void> = Promise.resolve();
@@ -5527,6 +5849,14 @@ export class CodexAppServerAgentSession implements AgentSession {
       await this.dispatchSubAgentNotification(parsed, route.callId);
       return;
     }
+    if (
+      parsed.kind === "turn_completed" ||
+      parsed.kind === "exec_command_started" ||
+      parsed.kind === "exec_command_completed" ||
+      ((parsed.kind === "item_started" || parsed.kind === "item_completed") &&
+        normalizeCodexThreadItemType(parsed.item.type) === "commandExecution")
+    )
+      this.background.changed(this.currentThreadId);
     await this.dispatchParsedNotification(parsed);
   }
 
@@ -6166,6 +6496,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     parsed: Extract<ParsedCodexNotification, { kind: "thread_started" }>,
   ): void {
     this.currentThreadId = parsed.threadId;
+    this.background.changed(this.currentThreadId);
     this.emitEvent({
       type: "thread_started",
       provider: CODEX_PROVIDER,
@@ -6181,6 +6512,7 @@ export class CodexAppServerAgentSession implements AgentSession {
       this.emitSubAgentActivityUpdate(subAgentCallId, "running", { reopen: true });
       return;
     }
+    this.markCurrentThreadSaved(parsed.threadId);
     this.currentTurnId = parsed.turnId;
     const pendingIdentification = this.pendingForegroundTurnIdentification;
     if (
@@ -6194,6 +6526,17 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.emitEvent({ type: "turn_started", provider: CODEX_PROVIDER });
   }
 
+  // Codex has written the rollout by the time it announces a thread's turn, including a
+  // goal's or a compaction's. From here on the thread can be reported and resumed.
+  private markCurrentThreadSaved(threadId: string | null): void {
+    const current = this.currentThreadId;
+    if (!current || (threadId !== null && threadId !== current)) return;
+    if (this.savedThreadId === current) return;
+    this.savedThreadId = current;
+    this.cachedRuntimeInfo = null;
+    this.emitEvent({ type: "thread_started", provider: CODEX_PROVIDER, sessionId: current });
+  }
+
   private handleTurnCompletedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "turn_completed" }>,
   ): void {
@@ -6210,6 +6553,11 @@ export class CodexAppServerAgentSession implements AgentSession {
       return;
     }
     this.completePendingRootCompactions();
+    // What a turn that was not interrupted leaves running, it left on purpose; no later
+    // interrupt may end it.
+    if (parsed.status !== "interrupted" && this.currentTurnId) {
+      this.terminalProcessIdsByTurnId.delete(this.currentTurnId);
+    }
     if (parsed.status === "failed") {
       this.emitEvent({
         type: "turn_failed",
@@ -6249,6 +6597,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.pendingReasoning.clear();
     this.pendingCommandOutputDeltas.clear();
     this.pendingFileChangeOutputDeltas.clear();
+    this.pendingToolCallDetails.clear();
     this.pendingAssistantMessageBoundary = false;
     this.warnedIncompleteEditToolCallIds.clear();
     this.pendingRootCompactionItemIds.clear();
@@ -6614,6 +6963,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async handleItemCompletedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_completed" }>,
   ): Promise<void> {
+    this.recordTurnTerminalProcess(parsed);
     // Codex emits mirrored lifecycle notifications via both `codex/event/item_*`
     // and canonical `item/*`. Render ordinary items only from the canonical
     // channel, but accept a legacy-only child announcement so it can establish
@@ -6621,6 +6971,9 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (shouldIgnoreMirroredLifecycleItem(parsed.source, parsed.item)) {
       return;
     }
+    if (parsed.item.id) {
+      this.pendingToolCallDetails.delete(parsed.item.id);
+    }
     this.receiveAsyncQuestion(parsed.threadId, parsed.item);
     if (this.isUserMessageItem(parsed.item)) {
       await this.handleUserMessageItem(parsed);
@@ -6668,10 +7021,8 @@ export class CodexAppServerAgentSession implements AgentSession {
       if (timelineItem.type === "assistant_message") {
         this.pendingAssistantMessageBoundary = true;
       }
-      if (itemId) {
-        this.emittedItemCompletedIds.add(itemId);
-        this.emittedItemStartedIds.delete(itemId);
-      }
+      this.emittedItemCompletedIds.add(itemId);
+      this.emittedItemStartedIds.delete(itemId);
       await this.replayPendingSubAgentNotifications(registeredChildThreadIds);
       return;
     }
@@ -6707,7 +7058,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private consumeStreamedTextCompletion(
     timelineItem: AgentTimelineItem,
     itemId: string | null | undefined,
-  ): boolean {
+  ): itemId is string {
     if (!itemId) {
       return false;
     }
@@ -6776,6 +7127,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async handleItemStartedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_started" }>,
   ): Promise<void> {
+    this.recordTurnTerminalProcess(parsed);
     if (shouldIgnoreMirroredLifecycleItem(parsed.source, parsed.item)) {
       return;
     }
@@ -6815,6 +7167,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (!timelineItem || timelineItem.type !== "tool_call") {
       return;
     }
+    this.pendingToolCallDetails.set(timelineItem.callId, timelineItem.detail);
     const registeredChildThreadIds = this.registerSubAgentToolCall({
       timelineItem,
       rawItem: parsed.item,
@@ -7084,7 +7437,8 @@ export class CodexAppServerAgentSession implements AgentSession {
     });
   }
 
-  private handleFileChangeApprovalRequest(params: unknown): Promise<unknown> {
+  private async handleFileChangeApprovalRequest(params: unknown): Promise<unknown> {
+    await this.pendingNotifications;
     const parsed = z
       .object({
         itemId: z.string(),
@@ -7094,20 +7448,25 @@ export class CodexAppServerAgentSession implements AgentSession {
       })
       .parse(params);
     const requestId = `permission-${parsed.itemId}`;
+    const detail: ToolCallTimelineItem["detail"] = this.pendingToolCallDetails.get(
+      parsed.itemId,
+    ) ?? {
+      type: "unknown",
+      input: { reason: parsed.reason ?? null },
+      output: null,
+    };
+    const title =
+      detail.type === "edit" && detail.filePath
+        ? `Apply file changes: ${detail.filePath}`
+        : "Apply file changes";
     const request: AgentPermissionRequest = {
       id: requestId,
       provider: CODEX_PROVIDER,
       name: "CodexFileChange",
       kind: "tool",
-      title: "Apply file changes",
+      title,
       description: parsed.reason ?? undefined,
-      detail: {
-        type: "unknown",
-        input: {
-          reason: parsed.reason ?? null,
-        },
-        output: null,
-      },
+      detail,
       metadata: {
         itemId: parsed.itemId,
         threadId: parsed.threadId,
@@ -7297,31 +7656,55 @@ export class CodexAppServerAgentClient implements AgentClient {
     }
   }
 
-  private async spawnAppServer(
-    launchEnv?: Record<string, string>,
-    options?: { goalsEnabled?: boolean; agentId?: string; environment?: Record<string, string> },
-  ): Promise<ChildProcessWithoutNullStreams> {
-    const launchPrefix = await resolveCodexLaunchPrefix(this.runtimeSettings);
+  private async prepareAppServerSpawn(options: {
+    environment: Record<string, string>;
+    goalsEnabled?: boolean;
+    agentId?: string;
+  }): Promise<() => ChildProcessWithoutNullStreams> {
+    const processPort = this.deps.appServerProcess ?? defaultCodexAppServerProcess;
+    const launchPrefix = await processPort.resolvePrefix({ runtimeSettings: this.runtimeSettings });
     const args = [...launchPrefix.args, "app-server"];
-    if (options?.goalsEnabled) {
+    if (options.goalsEnabled) {
       args.push("--enable", "goals");
     }
-    this.logger.trace(
-      {
-        agentId: options?.agentId,
-        provider: CODEX_PROVIDER,
-        launchPrefix,
-        goalsEnabled: options?.goalsEnabled === true,
-      },
-      "provider.codex.spawn",
-    );
-    const child = spawnProcess(launchPrefix.command, args, {
-      detached: process.platform !== "win32",
-      stdio: ["pipe", "pipe", "pipe"],
-      baseEnv: options?.environment ?? buildCodexAppServerEnv(this.runtimeSettings, launchEnv),
+    return () => {
+      this.logger.trace(
+        {
+          agentId: options.agentId,
+          provider: CODEX_PROVIDER,
+          launchPrefix,
+          goalsEnabled: options.goalsEnabled === true,
+        },
+        "provider.codex.spawn",
+      );
+      const child = processPort.spawn({
+        command: launchPrefix.command,
+        args,
+        options: {
+          detached: process.platform !== "win32",
+          stdio: ["pipe", "pipe", "pipe"],
+          baseEnv: options.environment,
+        },
+      });
+      assertChildWithPipes(child);
+      return child;
+    };
+  }
+
+  private async startAppServer(
+    options: { signal?: AbortSignal } = {},
+  ): Promise<CodexAppServerClient> {
+    const environment = buildCodexAppServerEnv(this.runtimeSettings);
+    const spawn = await this.prepareAppServerSpawn({ environment });
+    const { client } = await codexAppServerStartup.start({
+      stateDirKey: codexStartupStateDirKey(environment),
+      spawn,
+      createClient: (child) => new CodexAppServerClient(child, this.logger),
+      initializeParams: buildCodexAppServerInitializeParams(),
+      logger: this.logger,
+      signal: options.signal,
     });
-    assertChildWithPipes(child);
-    return child;
+    return client;
   }
 
   async createSession(
@@ -7340,16 +7723,16 @@ export class CodexAppServerAgentClient implements AgentClient {
     const goalsEnabled = await this.resolveGoalsEnabled();
     const autoReviewEnabled = await this.resolveAutoReviewEnabled();
     const environment = buildCodexAppServerEnv(this.runtimeSettings, launchContext?.env);
+    const spawn = await this.prepareAppServerSpawn({
+      environment,
+      goalsEnabled,
+      agentId: launchContext?.agentId,
+    });
     const session = new CodexAppServerAgentSession(
       sessionConfig,
       null,
       this.logger,
-      () =>
-        this.spawnAppServer(launchContext?.env, {
-          goalsEnabled,
-          agentId: launchContext?.agentId,
-          environment,
-        }),
+      async () => spawn(),
       { ...this.sessionDeps(launchContext?.env), environment },
       options?.persistSession === false,
       goalsEnabled,
@@ -7377,16 +7760,16 @@ export class CodexAppServerAgentClient implements AgentClient {
     const goalsEnabled = await this.resolveGoalsEnabled();
     const autoReviewEnabled = await this.resolveAutoReviewEnabled();
     const environment = buildCodexAppServerEnv(this.runtimeSettings, launchContext?.env);
+    const spawn = await this.prepareAppServerSpawn({
+      environment,
+      goalsEnabled,
+      agentId: launchContext?.agentId,
+    });
     const session = new CodexAppServerAgentSession(
       merged,
       handle,
       this.logger,
-      () =>
-        this.spawnAppServer(launchContext?.env, {
-          goalsEnabled,
-          agentId: launchContext?.agentId,
-          environment,
-        }),
+      async () => spawn(),
       { ...this.sessionDeps(launchContext?.env), environment },
       false,
       goalsEnabled,
@@ -7401,15 +7784,19 @@ export class CodexAppServerAgentClient implements AgentClient {
   async listImportableSessions(
     options?: ListImportableSessionsOptions,
   ): Promise<ImportableProviderSession[]> {
-    const child = await this.spawnAppServer();
-    const client =
-      this.deps._createCodexClient?.(child, this.logger, () => ({})) ??
-      new CodexAppServerClient(child, this.logger);
+    const environment = buildCodexAppServerEnv(this.runtimeSettings);
+    const spawn = await this.prepareAppServerSpawn({ environment });
+    const { client } = await codexAppServerStartup.start({
+      stateDirKey: codexStartupStateDirKey(environment),
+      spawn,
+      createClient: (child) =>
+        this.deps._createCodexClient?.(child, this.logger, () => ({})) ??
+        new CodexAppServerClient(child, this.logger),
+      initializeParams: buildCodexAppServerInitializeParams(),
+      logger: this.logger,
+    });
 
     try {
-      await client.request("initialize", buildCodexAppServerInitializeParams());
-      client.notify("initialized", {});
-
       const limit = options?.limit ?? 20;
       const scanLimit = Math.min(options?.scanLimit ?? limit, 500);
       // thread/list returns the cheap `cwd` field. Fetch a wider window when
@@ -7512,15 +7899,10 @@ export class CodexAppServerAgentClient implements AgentClient {
 
     try {
       await runProviderRefreshActivity(context, "app-server.start", async () => {
-        const child = await this.spawnAppServer();
-        client = new CodexAppServerClient(child, this.logger);
+        client = await this.startAppServer({ signal: context?.signal });
         if (context?.signal.aborted) await dispose();
       });
       if (!client) throw new Error("Codex app-server did not start");
-      await runProviderRefreshActivity(context, "initialize", () =>
-        client!.request("initialize", buildCodexAppServerInitializeParams()),
-      );
-      client.notify("initialized", {});
 
       const rawResponse = await runProviderRefreshActivity(context, "model/list", () =>
         client!.request("model/list", {}),
@@ -7564,12 +7946,9 @@ export class CodexAppServerAgentClient implements AgentClient {
     const threadId = handle.nativeHandle ?? handle.sessionId;
     if (!threadId) return;
 
-    const child = await this.spawnAppServer();
-    const client = new CodexAppServerClient(child, this.logger);
+    const client = await this.startAppServer();
 
     try {
-      await client.request("initialize", buildCodexAppServerInitializeParams());
-      client.notify("initialized", {});
       if (state === "archive") {
         await client.request("thread/archive", { threadId });
         return;
diff --git a/packages/server/src/server/agent/providers/codex-feature-definitions.ts b/packages/server/src/server/agent/providers/codex-feature-definitions.ts
index 5eb11d8a0c..096ffc6c64 100644
--- a/packages/server/src/server/agent/providers/codex-feature-definitions.ts
+++ b/packages/server/src/server/agent/providers/codex-feature-definitions.ts
@@ -1,4 +1,4 @@
-import type { AgentFeature, AgentFeatureToggle } from "../agent-sdk-types.js";
+import type { AgentOptionControl, AgentOptionToggleControl } from "../agent-sdk-types.js";
 
 import { z } from "zod";
 
@@ -9,51 +9,47 @@ export const CodexServiceTierSchema = z.object({
 });
 export type CodexServiceTier = z.infer<typeof CodexServiceTierSchema>;
 
-function buildCodexSpeedFeature(tiers: CodexServiceTier[], value: string): AgentFeature[] {
+function buildCodexSpeedControl(tiers: CodexServiceTier[]): AgentOptionControl[] {
   if (tiers.length === 0) return [];
   return [
     {
       type: "select",
-      id: "service_tier",
+      key: "service_tier",
       label: "Speed",
       description: "Choose processing speed. Faster tiers increase usage.",
       tooltip: "Select speed",
       icon: "zap",
       desktopTrigger: "icon",
-      value,
-      options: [
-        { id: "default", label: "Normal", isDefault: true },
-        ...tiers.map((tier) => ({ id: tier.id, label: tier.name })),
+      defaultValue: "default",
+      choices: [
+        { value: "default", label: "Normal" },
+        ...tiers.map((tier) => ({ value: tier.id, label: tier.name })),
       ],
     },
   ];
 }
 
-export const CODEX_PLAN_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
+export const CODEX_PLAN_MODE_CONTROL: AgentOptionToggleControl = {
   type: "toggle",
-  id: "plan_mode",
+  key: "plan_mode",
   label: "Plan",
   description: "Switch Codex into planning-only collaboration mode",
   tooltip: "Toggle plan mode",
   icon: "list-todo",
 };
 
-export function buildCodexFeatures(input: {
+export function buildCodexControls(input: {
   serviceTiers: CodexServiceTier[];
-  serviceTier: string;
-  planModeEnabled: boolean;
   planModeAvailable?: boolean;
-}): AgentFeature[] {
-  const features = buildCodexSpeedFeature(input.serviceTiers, input.serviceTier);
+}): AgentOptionControl[] {
+  const controls = buildCodexSpeedControl(input.serviceTiers);
   if (input.planModeAvailable !== false) {
-    features.push({ ...CODEX_PLAN_MODE_FEATURE, value: input.planModeEnabled });
+    controls.push({ ...CODEX_PLAN_MODE_CONTROL });
   }
-  return features;
+  return controls;
 }
 
-export function readCodexServiceTier(values: Record<string, unknown> | undefined): string | null {
-  const tier = values?.service_tier;
-  if (typeof tier === "string") return tier;
-  // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
-  return values?.fast_mode ? "fast" : null;
+export function readCodexServiceTier(options: Record<string, unknown> | undefined): string | null {
+  const tier = options?.service_tier;
+  return typeof tier === "string" ? tier : null;
 }
diff --git a/packages/server/src/server/agent/providers/codex-interrupted-turn-terminals.test.ts b/packages/server/src/server/agent/providers/codex-interrupted-turn-terminals.test.ts
new file mode 100644
index 0000000000..d089bc0445
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex-interrupted-turn-terminals.test.ts
@@ -0,0 +1,704 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import type { AgentSession } from "../agent-sdk-types.js";
+import { createTestLogger } from "../../../test-utils/test-logger.js";
+import { CodexAppServerAgentSession } from "./codex-app-server-agent.js";
+import {
+  createFakeCodexAppServer,
+  type FakeCodexAppServer,
+  waitForNextEvent,
+  waitForTimelineToolCall,
+} from "./codex/test-utils/fake-app-server.js";
+
+const THREAD = "thread-1";
+const TERMINATE = "thread/backgroundTerminals/terminate";
+
+type Handler = (params: unknown) => unknown;
+
+function deferred<T = void>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+function paramsOf(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+}
+
+let sessions: AgentSession[] = [];
+
+afterEach(async () => {
+  for (const session of sessions) await session.close().catch(() => undefined);
+  sessions = [];
+});
+
+/**
+ * A Codex app-server whose interrupt ends the turn the way Codex does: an `interrupted`
+ * turn completion, then the response. `terminate` answers per process.
+ */
+function createHarness(
+  options: {
+    terminate?: (processId: string) => unknown;
+    interruptResponse?: (completeTurn: () => void) => unknown;
+  } = {},
+) {
+  const handlers: Record<string, Handler> = {
+    "thread/backgroundTerminals/list": () => ({ data: [], nextCursor: null }),
+    "turn/interrupt": () => {
+      const completeTurn = () =>
+        appServer.completeTurn({ threadId: THREAD, status: "interrupted" });
+      if (options.interruptResponse) return options.interruptResponse(completeTurn);
+      completeTurn();
+      return {};
+    },
+    [TERMINATE]: (params) =>
+      options.terminate?.(String(paramsOf(params).processId)) ?? { terminated: true },
+  };
+  const appServer: FakeCodexAppServer = createFakeCodexAppServer(handlers);
+  const session = new CodexAppServerAgentSession(
+    {
+      provider: "codex",
+      cwd: "/workspace/project",
+      modeId: "auto",
+      model: "gpt-5.4",
+    },
+    null,
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+
+  function requests(method: string): Record<string, unknown>[] {
+    return appServer
+      .requests()
+      .filter((message) => message.method === method && "id" in message)
+      .map((message) => paramsOf(message.params));
+  }
+
+  function terminated(): string[] {
+    return requests(TERMINATE)
+      .map((params) => String(params.processId))
+      .sort();
+  }
+
+  // Starts a turn and lets Codex identify it as `nativeTurnId`.
+  async function startTurn(prompt: string, nativeTurnId: string): Promise<void> {
+    const before = requests("turn/start").length;
+    const started = session.startTurn(prompt);
+    await vi.waitFor(() => expect(requests("turn/start")).toHaveLength(before + 1), {
+      timeout: 5_000,
+    });
+    const turnStarted = waitForNextEvent(session, "turn_started");
+    appServer.startsTurn({ threadId: THREAD, turnId: nativeTurnId });
+    await started;
+    await turnStarted;
+  }
+
+  async function runsCommand(params: { turnId: string; processId: string }): Promise<void> {
+    const itemId = `exec-${params.processId}`;
+    const shown = waitForTimelineToolCall(session, itemId);
+    appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: params.turnId,
+      itemId,
+      processId: params.processId,
+      command: `sleep ${params.processId}`,
+    });
+    await shown;
+  }
+
+  async function completesTurn(): Promise<void> {
+    const completed = waitForNextEvent(session, "turn_completed");
+    appServer.completeTurn({ threadId: THREAD });
+    await completed;
+  }
+
+  // Interrupts the running turn and waits for the session to report it canceled, as a
+  // caller does before it starts the next turn: Codex notifications are handled in order
+  // but asynchronously, so the interrupt's answer can arrive before the turn has ended.
+  async function interrupts(): Promise<void> {
+    const canceled = waitForNextEvent(session, "turn_canceled");
+    await session.interrupt();
+    await canceled;
+  }
+
+  return {
+    appServer,
+    session,
+    requests,
+    terminated,
+    startTurn,
+    runsCommand,
+    completesTurn,
+    interrupts,
+  };
+}
+
+// Turn A leaves a server running on purpose and completes. Turn B starts two
+// commands, and a subagent on its own thread starts a third, then B is interrupted.
+async function interruptTurnB(harness: ReturnType<typeof createHarness>): Promise<void> {
+  await harness.startTurn("start a server", "native-A");
+  await harness.runsCommand({ turnId: "native-A", processId: "101" });
+  await harness.completesTurn();
+
+  await harness.startTurn("run two commands", "native-B");
+  await harness.runsCommand({ turnId: "native-B", processId: "201" });
+  // A subagent thread's command shows no row here; the next command's row shows it
+  // was read, because notifications are read in order.
+  harness.appServer.startsTerminalCommand({
+    threadId: "child-thread",
+    turnId: "native-B",
+    itemId: "exec-209",
+    processId: "209",
+    command: "sleep 209",
+  });
+  await harness.runsCommand({ turnId: "native-B", processId: "202" });
+  await harness.interrupts();
+}
+
+describe("an interrupted Codex turn's commands end before the next turn", () => {
+  test("terminates exactly the processes the interrupted turn started, by id, and never cleans", async () => {
+    const harness = createHarness();
+    await interruptTurnB(harness);
+    await harness.startTurn("correction", "native-C");
+
+    expect(harness.terminated()).toEqual(["201", "202"]);
+    expect(harness.requests(TERMINATE).every((params) => params.threadId === THREAD)).toBe(true);
+    // `clean` would end every terminal on the thread, an earlier turn's included.
+    expect(
+      harness.appServer
+        .requests()
+        .filter(
+          (message) =>
+            String(message.method).startsWith("thread/backgroundTerminals/") &&
+            message.method !== "thread/backgroundTerminals/list",
+        )
+        .map((message) => message.method),
+    ).toEqual([TERMINATE, TERMINATE]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("leaves the next turn's commands running when Codex starts that turn before acknowledging the interrupt", async () => {
+    const acknowledge = deferred();
+    const harness = createHarness({
+      // Codex ends B, starts a turn of its own (a goal continuation), and only then
+      // answers the interrupt.
+      interruptResponse: (completeTurn) => {
+        completeTurn();
+        return acknowledge.promise.then(() => ({}));
+      },
+    });
+    await harness.startTurn("run two commands", "native-B");
+    await harness.runsCommand({ turnId: "native-B", processId: "201" });
+    await harness.runsCommand({ turnId: "native-B", processId: "202" });
+    const interrupting = harness.session.interrupt();
+    await vi.waitFor(() => expect(harness.requests("turn/interrupt")).toHaveLength(1));
+    const autonomousTurn = waitForNextEvent(harness.session, "turn_started");
+    harness.appServer.startsTurn({ threadId: THREAD, turnId: "native-C" });
+    await autonomousTurn;
+    await harness.runsCommand({ turnId: "native-C", processId: "301" });
+
+    acknowledge.resolve();
+    await interrupting;
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(harness.terminated()).toEqual(["201", "202"]);
+  });
+
+  test("sends the next turn/start only after the terminates are answered", async () => {
+    const answer = deferred();
+    const harness = createHarness({
+      terminate: () => answer.promise.then(() => ({ terminated: true })),
+    });
+    await interruptTurnB(harness);
+    const next = harness.startTurn("correction", "native-C");
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(harness.requests("turn/start")).toHaveLength(2);
+
+    answer.resolve();
+    await next;
+    expect(harness.requests("turn/start")).toHaveLength(3);
+  });
+
+  test.each(["initial", "late"] as const)(
+    "tracks both cleanup sweeps when the %s answer arrives first",
+    async (answeredFirst) => {
+      const first = deferred();
+      const second = deferred();
+      const harness = createHarness({
+        terminate: (processId) =>
+          (processId === "201" ? first : second).promise.then(() => ({ terminated: true })),
+      });
+      await harness.startTurn("run commands", "native-B");
+      await harness.runsCommand({ turnId: "native-B", processId: "201" });
+      await harness.interrupts();
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201"]));
+      const next = harness.startTurn("correction", "native-C");
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(harness.requests("turn/start")).toHaveLength(1);
+      // The next turn is already waiting when another process is announced.
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "late-202",
+        processId: "202",
+        command: "sleep 202",
+      });
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "duplicate-202",
+        processId: "202",
+        command: "sleep 202",
+      });
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+      (answeredFirst === "initial" ? first : second).resolve();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(harness.requests("turn/start")).toHaveLength(1);
+      (answeredFirst === "initial" ? second : first).resolve();
+      await next;
+      expect(harness.terminated()).toEqual(["201", "202"]);
+      // Accepted state survives the completed sweep and a newer foreground turn.
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "late-203",
+        processId: "203",
+        command: "sleep 203",
+      });
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202", "203"]));
+      harness.appServer.assertNoErrors();
+    },
+  );
+
+  test("keeps the first sweep pending when a late sweep answers before the next start", async () => {
+    const first = deferred();
+    const harness = createHarness({
+      terminate: (processId) =>
+        processId === "201"
+          ? first.promise.then(() => ({ terminated: true }))
+          : { terminated: true },
+    });
+    await harness.startTurn("run commands", "native-B");
+    await harness.runsCommand({ turnId: "native-B", processId: "201" });
+    await harness.interrupts();
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-B",
+      itemId: "late-202",
+      processId: "202",
+      command: "sleep 202",
+    });
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    const next = harness.startTurn("correction", "native-C");
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(harness.requests("turn/start")).toHaveLength(1);
+    first.resolve();
+    await next;
+    harness.appServer.assertNoErrors();
+  });
+
+  test("forgets completed commands but retains failed commands at interrupt", async () => {
+    const harness = createHarness();
+    await harness.startTurn("run commands", "native-B");
+    for (const processId of ["201", "202"]) {
+      await harness.runsCommand({ turnId: "native-B", processId });
+      harness.appServer.child.stdout.write(
+        JSON.stringify({
+          method: "item/completed",
+          params: {
+            threadId: THREAD,
+            turnId: "native-B",
+            item: {
+              id: `exec-${processId}`,
+              type: "commandExecution",
+              processId,
+              command: `sleep ${processId}`,
+              status: processId === "201" ? "completed" : "failed",
+              exitCode: processId === "201" ? 0 : null,
+            },
+          },
+        }) + "\n",
+      );
+    }
+    // A following command's row is a barrier for both completion handlers.
+    await harness.runsCommand({ turnId: "native-B", processId: "203" });
+    await harness.interrupts();
+    await harness.startTurn("correction", "native-C");
+    expect(harness.terminated()).toEqual(["202", "203"]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("retains accepted interrupts for only the latest sixteen turns", async () => {
+    const harness = createHarness();
+    for (let index = 0; index < 17; index++) {
+      await harness.startTurn("run a command", `native-${index}`);
+      await harness.interrupts();
+    }
+    await harness.startTurn("correction", "native-current");
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-0",
+      itemId: "evicted-201",
+      processId: "201",
+      command: "sleep 201",
+    });
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-16",
+      itemId: "retained-202",
+      processId: "202",
+      command: "sleep 202",
+    });
+    await harness.runsCommand({ turnId: "native-current", processId: "301" });
+    expect(harness.terminated()).toEqual(["202"]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("a failing or unanswered terminate does not block or fail the next turn", async () => {
+    const harness = createHarness({
+      // 201 is refused while the next turn waits; 202 is never answered.
+      terminate: (processId) =>
+        processId === "201"
+          ? new Promise((resolve) => setTimeout(resolve, 300)).then(() => ({
+              __jsonRpcError: { code: -32600, message: "invalid background terminal process id" },
+            }))
+          : new Promise(() => {}),
+    });
+    await interruptTurnB(harness);
+    const startedAt = Date.now();
+    await harness.startTurn("correction", "native-C");
+
+    expect(Date.now() - startedAt).toBeLessThan(5_000);
+    expect(harness.requests("turn/start")).toHaveLength(3);
+    expect(harness.terminated()).toEqual(["201", "202"]);
+  }, 15_000);
+});
+
+test("publishes every page of the current thread's live background terminals", async () => {
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": (params) => {
+      const cursor = paramsOf(params).cursor;
+      return cursor
+        ? { data: [{ itemId: "item-2", processId: "2", command: "sleep 2" }], nextCursor: null }
+        : { data: [{ itemId: "item-1", processId: "1", command: "sleep 1" }], nextCursor: "next" };
+    },
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", modeId: "auto", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [
+        { kind: "shell", description: null, command: "sleep 1" },
+        { kind: "shell", description: null, command: "sleep 2" },
+      ],
+    }),
+  );
+});
+
+test("discards a terminal list overtaken by a command event", async () => {
+  const first = deferred<unknown>();
+  let lists = 0;
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () =>
+      ++lists === 1 ? first.promise : { data: [], nextCursor: null },
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", modeId: "auto", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await vi.waitFor(() => expect(lists).toBe(1));
+  const shown = waitForTimelineToolCall(session, "item-new");
+  appServer.startsTerminalCommand({
+    threadId: THREAD,
+    turnId: "turn",
+    itemId: "item-new",
+    processId: "new",
+    command: "sleep 1",
+  });
+  await shown;
+  first.resolve({
+    data: [{ itemId: "old", processId: "old", command: "sleep 2" }],
+    nextCursor: null,
+  });
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [],
+    }),
+  );
+  expect(events.filter((event) => event.type === "background_work")).not.toContainEqual(
+    expect.objectContaining({ items: [expect.objectContaining({ command: "sleep 2" })] }),
+  );
+});
+
+test("does not publish a terminal response from a lost runtime", async () => {
+  const first = deferred<unknown>();
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => first.promise,
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", modeId: "auto", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await appServer.waitForRequest("thread/backgroundTerminals/list");
+  appServer.disconnect();
+  first.resolve({
+    data: [{ itemId: "old", processId: "old", command: "sleep 2" }],
+    nextCursor: null,
+  });
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  expect(events.filter((event) => event.type === "background_work")).not.toContainEqual(
+    expect.objectContaining({ items: [expect.objectContaining({ command: "sleep 2" })] }),
+  );
+});
+
+test("accepts a slow terminal snapshot after the polling interval", async () => {
+  const pending = deferred<unknown>();
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => pending.promise,
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await appServer.waitForRequest("thread/backgroundTerminals/list");
+  await new Promise((resolve) => setTimeout(resolve, 5200));
+  expect(
+    appServer.requests().filter((message) => message.method === "thread/backgroundTerminals/list"),
+  ).toHaveLength(1);
+  pending.resolve({ data: [{ processId: "slow", command: "sleep 120" }], nextCursor: null });
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ command: "sleep 120" }],
+    }),
+  );
+  expect(
+    appServer.requests().filter((message) => message.method === "thread/backgroundTerminals/list"),
+  ).toHaveLength(1);
+}, 12000);
+
+test("does not retry an unsupported inventory on later command events", async () => {
+  let calls = 0;
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => {
+      calls++;
+      return { __jsonRpcError: { code: -32601, message: "Method not found" } };
+    },
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  await session.connect();
+  await vi.waitFor(() => expect(calls).toBe(1));
+  const shown = waitForTimelineToolCall(session, "unsupported-item");
+  appServer.startsTerminalCommand({
+    threadId: THREAD,
+    turnId: "turn",
+    itemId: "unsupported-item",
+    processId: "1",
+    command: "sleep 1",
+  });
+  await shown;
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  expect(calls).toBe(1);
+});
+
+test("retries transient inventory failures and cancels retries on stop", async () => {
+  vi.useFakeTimers();
+  try {
+    const { CodexBackgroundInventory } = await import("./codex/background-inventory.js");
+    let calls = 0;
+    let fail = true;
+    const inventory = new CodexBackgroundInventory(() => {});
+    inventory.start({
+      client: {
+        request: async () => {
+          calls++;
+          if (fail) throw new Error("temporary");
+          return { data: [{ processId: "live", command: "sleep 120" }], nextCursor: null };
+        },
+      },
+      thread: THREAD,
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(inventory.snapshot()).toBeNull();
+    inventory.changed(THREAD);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(calls).toBe(1);
+    fail = false;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(inventory.snapshot()?.items).toMatchObject([{ command: "sleep 120" }]);
+    fail = true;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(inventory.snapshot()?.items).toMatchObject([{ command: "sleep 120" }]);
+    inventory.stop();
+    const stoppedCalls = calls;
+    await vi.advanceTimersByTimeAsync(15000);
+    expect(calls).toBe(stoppedCalls);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("does not retry a failure from a stopped inventory generation", async () => {
+  vi.useFakeTimers();
+  try {
+    const { CodexBackgroundInventory } = await import("./codex/background-inventory.js");
+    let reject!: (error: Error) => void;
+    let calls = 0;
+    const response = new Promise<unknown>((_, fail) => {
+      reject = fail;
+    });
+    const inventory = new CodexBackgroundInventory(() => {});
+    inventory.start({
+      client: {
+        request: () => {
+          calls++;
+          return response;
+        },
+      },
+      thread: THREAD,
+    });
+    inventory.stop();
+    reject(new Error("late failure"));
+    await vi.advanceTimersByTimeAsync(15000);
+    expect(calls).toBe(1);
+    expect(inventory.snapshot()).toBeNull();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("stops only the selected live background terminal and confirms the roster", async () => {
+  const live = new Set(["1", "2"]);
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => ({
+      data: [...live].map((processId) => ({ processId, command: `sleep ${processId}` })),
+      nextCursor: null,
+    }),
+    "thread/backgroundTerminals/terminate": (params) => ({
+      terminated: live.delete(String(paramsOf(params).processId)),
+    }),
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ command: "sleep 1" }, { command: "sleep 2" }],
+    }),
+  );
+  const item = events
+    .findLast((event) => event.type === "background_work")
+    ?.items?.find((entry) => entry.command === "sleep 1");
+  expect(item).toBeDefined();
+  await session.stopBackgroundWork(item!.id);
+  expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+    items: [{ command: "sleep 2" }],
+  });
+  await expect(session.stopBackgroundWork(item!.id)).rejects.toThrow();
+});
+
+test("reports a rejected background stop and keeps the item available", async () => {
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => ({
+      data: [{ processId: "1", command: "sleep 1" }],
+      nextCursor: null,
+    }),
+    "thread/backgroundTerminals/terminate": () => ({ terminated: false }),
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ command: "sleep 1" }],
+    }),
+  );
+  const item = events.findLast((event) => event.type === "background_work")?.items?.[0];
+  expect(item).toBeDefined();
+  await expect(session.stopBackgroundWork(item!.id)).rejects.toThrow("not terminated");
+  expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+    items: [{ command: "sleep 1" }],
+  });
+});
+
+test("does not confirm a stop after the provider connection is lost", async () => {
+  const response = deferred<unknown>();
+  const appServer = createFakeCodexAppServer({
+    "thread/backgroundTerminals/list": () => ({
+      data: [{ processId: "1", command: "sleep 1" }],
+      nextCursor: null,
+    }),
+    "thread/backgroundTerminals/terminate": () => response.promise,
+  });
+  const session = new CodexAppServerAgentSession(
+    { provider: "codex", cwd: "/workspace/project", model: "gpt-5.4" },
+    { sessionId: THREAD },
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+  const events: import("../agent-sdk-types.js").AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await session.connect();
+  await vi.waitFor(() =>
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ command: "sleep 1" }],
+    }),
+  );
+  const item = events.findLast((event) => event.type === "background_work")?.items?.[0];
+  expect(item).toBeDefined();
+  const pending = session.stopBackgroundWork(item!.id);
+  await appServer.waitForRequest("thread/backgroundTerminals/terminate");
+  appServer.disconnect();
+  response.resolve({ terminated: true });
+  await expect(pending).rejects.toThrow();
+});
diff --git a/packages/server/src/server/agent/providers/codex-plan-mode.real.e2e.test.ts b/packages/server/src/server/agent/providers/codex-plan-mode.real.e2e.test.ts
index 7c55a5f0f7..1582e6101f 100644
--- a/packages/server/src/server/agent/providers/codex-plan-mode.real.e2e.test.ts
+++ b/packages/server/src/server/agent/providers/codex-plan-mode.real.e2e.test.ts
@@ -40,7 +40,7 @@ describe("Codex app-server provider (real) plan mode", () => {
       });
 
       try {
-        await session.setFeature?.("plan_mode", true);
+        await session.applyOptions!({ plan_mode: true });
 
         const result = await session.run(
           "You are in plan mode. Produce a markdown plan with a short heading and exactly 3 bullets for implementing a login screen. Do not ask questions.",
diff --git a/packages/server/src/server/agent/providers/codex/app-server-startup.test.ts b/packages/server/src/server/agent/providers/codex/app-server-startup.test.ts
new file mode 100644
index 0000000000..9ff257343b
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex/app-server-startup.test.ts
@@ -0,0 +1,347 @@
+import { describe, expect, test, vi } from "vitest";
+
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import { createCodexAppServerChildProcess } from "./test-utils/fake-app-server.js";
+import { CodexAppServerStartupCoordinator } from "./app-server-startup.js";
+import { CodexAppServerExitError } from "./app-server-transport.js";
+
+function sqliteStartupError(): CodexAppServerExitError {
+  return new CodexAppServerExitError({
+    exitCode: 1,
+    exitSignal: null,
+    stderr: "failed to initialize sqlite state runtime",
+  });
+}
+
+function deferred<T = void>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+describe("Codex app-server startup coordinator", () => {
+  test("returns initialize metadata so sessions retain server capabilities", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    const client = {
+      request: async () => ({ userAgent: "codex/0.164.0" }),
+      notify: () => {},
+      dispose: async () => {},
+    };
+    const started = await coordinator.start({
+      stateDirKey: "/codex/metadata",
+      spawn: createCodexAppServerChildProcess,
+      createClient: () => client,
+      initializeParams: {},
+      logger: createTestLogger(),
+    });
+    expect(started).toEqual({ client, initialized: { userAgent: "codex/0.164.0" } });
+  });
+
+  test("serializes a burst through initialize but retains all initialized clients", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    const firstEntered = deferred();
+    const releaseFirst = deferred();
+    let spawned = 0;
+    let activeInitializations = 0;
+    let maxActiveInitializations = 0;
+    let disposed = 0;
+
+    const starts = Array.from({ length: 24 }, () =>
+      coordinator.start({
+        stateDirKey: "/codex/shared",
+        spawn: () => {
+          spawned++;
+          return createCodexAppServerChildProcess();
+        },
+        createClient: () => ({
+          request: async (method: string) => {
+            expect(method).toBe("initialize");
+            activeInitializations++;
+            maxActiveInitializations = Math.max(maxActiveInitializations, activeInitializations);
+            if (spawned === 1) {
+              firstEntered.resolve();
+              await releaseFirst.promise;
+            }
+            activeInitializations--;
+            return {};
+          },
+          notify: vi.fn(),
+          dispose: async () => {
+            disposed++;
+          },
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      }),
+    );
+
+    await firstEntered.promise;
+    expect(spawned).toBe(1);
+    releaseFirst.resolve();
+    const clients = await Promise.all(starts);
+
+    expect(clients).toHaveLength(24);
+    expect(spawned).toBe(24);
+    expect(maxActiveInitializations).toBe(1);
+    expect(disposed).toBe(0);
+  });
+
+  test("allows different Codex homes to initialize concurrently", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    const bothEntered = deferred();
+    const release = deferred();
+    let entered = 0;
+    const start = (stateDirKey: string) =>
+      coordinator.start({
+        stateDirKey,
+        spawn: createCodexAppServerChildProcess,
+        createClient: () => ({
+          request: async () => {
+            entered++;
+            if (entered === 2) bothEntered.resolve();
+            await release.promise;
+            return {};
+          },
+          notify: vi.fn(),
+          dispose: vi.fn(async () => {}),
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      });
+
+    const first = start("/codex/one");
+    const second = start("/codex/two");
+    await bothEntered.promise;
+    expect(entered).toBe(2);
+    release.resolve();
+    await Promise.all([first, second]);
+  });
+
+  test("retries only SQLite startup failures after disposing the failed child", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    const events: string[] = [];
+    let attempt = 0;
+    const client = await coordinator.start({
+      stateDirKey: "/codex/shared",
+      spawn: () => {
+        attempt++;
+        events.push(`spawn ${attempt}`);
+        return createCodexAppServerChildProcess();
+      },
+      createClient: () => {
+        const number = attempt;
+        return {
+          request: async () => {
+            events.push(`initialize ${number}`);
+            if (number === 1) throw sqliteStartupError();
+            return {};
+          },
+          notify: () => events.push(`initialized ${number}`),
+          dispose: async () => {
+            events.push(`dispose ${number}`);
+          },
+        };
+      },
+      initializeParams: {},
+      logger: createTestLogger(),
+    });
+
+    expect(client.client).toEqual(expect.objectContaining({ request: expect.any(Function) }));
+    expect(events).toEqual([
+      "spawn 1",
+      "initialize 1",
+      "dispose 1",
+      "spawn 2",
+      "initialize 2",
+      "initialized 2",
+    ]);
+  });
+
+  test("does not retry unrelated startup failures", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    let spawned = 0;
+    let disposed = 0;
+    await expect(
+      coordinator.start({
+        stateDirKey: "/codex/shared",
+        spawn: () => {
+          spawned++;
+          return createCodexAppServerChildProcess();
+        },
+        createClient: () => ({
+          request: async () => {
+            throw new Error("database is locked while reading unrelated configuration");
+          },
+          notify: vi.fn(),
+          dispose: async () => {
+            disposed++;
+          },
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      }),
+    ).rejects.toThrow("database is locked while reading unrelated configuration");
+    expect(spawned).toBe(1);
+    expect(disposed).toBe(1);
+  });
+
+  test("bounds persistent SQLite failures and leaves the lane usable", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    let spawned = 0;
+    let disposed = 0;
+    let locked = true;
+    const start = () =>
+      coordinator.start({
+        stateDirKey: "/codex/shared",
+        spawn: () => {
+          spawned++;
+          return createCodexAppServerChildProcess();
+        },
+        createClient: () => ({
+          request: async () => {
+            if (locked) throw sqliteStartupError();
+            return {};
+          },
+          notify: vi.fn(),
+          dispose: async () => {
+            disposed++;
+          },
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      });
+
+    await expect(start()).rejects.toThrow("failed to initialize sqlite state runtime");
+    expect(spawned).toBe(3);
+    expect(disposed).toBe(3);
+    locked = false;
+    await expect(start()).resolves.toEqual(
+      expect.objectContaining({
+        client: expect.objectContaining({ request: expect.any(Function) }),
+      }),
+    );
+    expect(spawned).toBe(4);
+    expect(disposed).toBe(3);
+  });
+
+  test("a cancelled waiter never spawns or overtakes the active startup", async () => {
+    const coordinator = new CodexAppServerStartupCoordinator();
+    const firstEntered = deferred();
+    const releaseFirst = deferred();
+    const events: string[] = [];
+    const first = coordinator.start({
+      stateDirKey: "/codex/shared",
+      spawn: () => {
+        events.push("spawn first");
+        return createCodexAppServerChildProcess();
+      },
+      createClient: () => ({
+        request: async () => {
+          firstEntered.resolve();
+          await releaseFirst.promise;
+          return {};
+        },
+        notify: vi.fn(),
+        dispose: vi.fn(async () => {}),
+      }),
+      initializeParams: {},
+      logger: createTestLogger(),
+    });
+    await firstEntered.promise;
+
+    const controller = new AbortController();
+    const queued = coordinator.start({
+      stateDirKey: "/codex/shared",
+      spawn: () => {
+        events.push("spawn cancelled");
+        return createCodexAppServerChildProcess();
+      },
+      createClient: () => ({
+        request: async () => ({}),
+        notify: vi.fn(),
+        dispose: vi.fn(async () => {}),
+      }),
+      initializeParams: {},
+      logger: createTestLogger(),
+      signal: controller.signal,
+    });
+    controller.abort(new Error("cancelled"));
+    await expect(queued).rejects.toThrow("cancelled");
+    const next = coordinator.start({
+      stateDirKey: "/codex/shared",
+      spawn: () => {
+        events.push("spawn next");
+        return createCodexAppServerChildProcess();
+      },
+      createClient: () => ({
+        request: async () => ({}),
+        notify: vi.fn(),
+        dispose: vi.fn(async () => {}),
+      }),
+      initializeParams: {},
+      logger: createTestLogger(),
+    });
+
+    expect(events).toEqual(["spawn first"]);
+    releaseFirst.resolve();
+    await Promise.all([first, next]);
+    expect(events).toEqual(["spawn first", "spawn next"]);
+  });
+
+  test("a timed-out initialize disposes its child and releases the next waiter", async () => {
+    vi.useFakeTimers();
+    try {
+      const coordinator = new CodexAppServerStartupCoordinator({
+        attemptTimeoutMs: 10,
+        queueTimeoutMs: 100,
+      });
+      const firstEntered = deferred();
+      const events: string[] = [];
+      const first = coordinator.start({
+        stateDirKey: "/codex/shared",
+        spawn: createCodexAppServerChildProcess,
+        createClient: () => ({
+          request: () => {
+            firstEntered.resolve();
+            return new Promise<never>(() => {});
+          },
+          notify: vi.fn(),
+          dispose: async () => {
+            events.push("dispose first");
+          },
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      });
+      await firstEntered.promise;
+      const next = coordinator.start({
+        stateDirKey: "/codex/shared",
+        spawn: () => {
+          events.push("spawn next");
+          return createCodexAppServerChildProcess();
+        },
+        createClient: () => ({
+          request: async () => ({}),
+          notify: vi.fn(),
+          dispose: vi.fn(async () => {}),
+        }),
+        initializeParams: {},
+        logger: createTestLogger(),
+      });
+
+      const firstResult = expect(first).rejects.toThrow("Timed out initializing Codex app-server");
+      await vi.advanceTimersByTimeAsync(10);
+      await firstResult;
+      await expect(next).resolves.toEqual(
+        expect.objectContaining({
+          client: expect.objectContaining({ request: expect.any(Function) }),
+        }),
+      );
+      expect(events).toEqual(["dispose first", "spawn next"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/packages/server/src/server/agent/providers/codex/app-server-startup.ts b/packages/server/src/server/agent/providers/codex/app-server-startup.ts
new file mode 100644
index 0000000000..9453e9ffb9
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex/app-server-startup.ts
@@ -0,0 +1,189 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Logger } from "pino";
+
+import { terminateWithTreeKill } from "../../../../utils/tree-kill.js";
+import { CodexAppServerExitError } from "./app-server-transport.js";
+
+const DEFAULT_QUEUE_TIMEOUT_MS = 60_000;
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+interface InitializableAppServerClient {
+  request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+  notify(method: string, params?: unknown): void;
+  dispose(): Promise<void>;
+}
+
+interface StartupOptions<TClient extends InitializableAppServerClient> {
+  stateDirKey: string;
+  spawn: () => ChildProcessWithoutNullStreams | Promise<ChildProcessWithoutNullStreams>;
+  createClient: (child: ChildProcessWithoutNullStreams) => TClient;
+  initializeParams: unknown;
+  logger: Pick<Logger, "warn" | "debug">;
+  signal?: AbortSignal;
+}
+
+interface StartedAppServer<TClient> {
+  client: TClient;
+  initialized: unknown;
+}
+
+interface CoordinatorOptions {
+  queueTimeoutMs?: number;
+  attemptTimeoutMs?: number;
+  maxAttempts?: number;
+}
+
+async function waitForSignal<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([operation, aborted]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+
+async function disposeUnownedChild(child: ChildProcessWithoutNullStreams): Promise<void> {
+  const result = await terminateWithTreeKill(child, {
+    gracefulTimeoutMs: 2_000,
+    forceTimeoutMs: 1_000,
+  });
+  if (result === "kill-timeout") {
+    throw new Error("Codex app-server did not report exit after SIGKILL");
+  }
+}
+
+export class CodexAppServerStartupCoordinator {
+  private readonly tails = new Map<string, Promise<void>>();
+  private readonly queueTimeoutMs: number;
+  private readonly attemptTimeoutMs: number;
+  private readonly maxAttempts: number;
+
+  constructor(options: CoordinatorOptions = {}) {
+    this.queueTimeoutMs = options.queueTimeoutMs ?? DEFAULT_QUEUE_TIMEOUT_MS;
+    this.attemptTimeoutMs = options.attemptTimeoutMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS;
+    this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  }
+
+  async start<TClient extends InitializableAppServerClient>(
+    options: StartupOptions<TClient>,
+  ): Promise<StartedAppServer<TClient>> {
+    options.signal?.throwIfAborted();
+    const previous = this.tails.get(options.stateDirKey) ?? Promise.resolve();
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    // An aborted waiter must not let later waiters pass the current owner.
+    const tail = previous.then(() => gate);
+    this.tails.set(options.stateDirKey, tail);
+    void tail.then(
+      () => this.tails.get(options.stateDirKey) === tail && this.tails.delete(options.stateDirKey),
+    );
+
+    const queueAbort = new AbortController();
+    const onAbort = () => queueAbort.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const queueTimer = setTimeout(
+      () => queueAbort.abort(new Error("Timed out waiting to start Codex app-server")),
+      this.queueTimeoutMs,
+    );
+    try {
+      await waitForSignal(previous, queueAbort.signal);
+      clearTimeout(queueTimer);
+      options.signal?.throwIfAborted();
+      for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+        try {
+          return await this.startAttempt(options);
+        } catch (error) {
+          const isRetryableStartupFailure =
+            error instanceof CodexAppServerExitError &&
+            error.reason === "sqlite_state_initialization";
+          if (
+            options.signal?.aborted ||
+            attempt === this.maxAttempts ||
+            !isRetryableStartupFailure
+          ) {
+            throw error;
+          }
+          options.logger.warn(
+            { err: error, attempt, maxAttempts: this.maxAttempts },
+            "Codex app-server SQLite startup failed; retrying with a fresh process",
+          );
+        }
+      }
+      throw new Error("Codex app-server startup attempts exhausted");
+    } finally {
+      clearTimeout(queueTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+      release();
+    }
+  }
+
+  private async startAttempt<TClient extends InitializableAppServerClient>(
+    options: StartupOptions<TClient>,
+  ): Promise<StartedAppServer<TClient>> {
+    const attemptAbort = new AbortController();
+    const onAbort = () => attemptAbort.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const attemptTimer = setTimeout(
+      () => attemptAbort.abort(new Error("Timed out initializing Codex app-server")),
+      this.attemptTimeoutMs,
+    );
+    let child: ChildProcessWithoutNullStreams | undefined;
+    let client: TClient | undefined;
+    try {
+      attemptAbort.signal.throwIfAborted();
+      // Production hands in a synchronous spawn closure. Resolve the binary
+      // before entering the lane, then create the child while holding it.
+      const spawnPromise = Promise.resolve(options.spawn());
+      try {
+        child = await waitForSignal(spawnPromise, attemptAbort.signal);
+      } catch (error) {
+        if (attemptAbort.signal.aborted) {
+          // A future asynchronous spawner may finish after cancellation.
+          void spawnPromise
+            .then((lateChild) => disposeUnownedChild(lateChild))
+            .catch((cleanupError) =>
+              options.logger.warn({ err: cleanupError }, "Failed to clean up late Codex spawn"),
+            );
+        }
+        throw error;
+      }
+      attemptAbort.signal.throwIfAborted();
+      client = options.createClient(child);
+      const initialized = await waitForSignal(
+        client.request("initialize", options.initializeParams, this.attemptTimeoutMs),
+        attemptAbort.signal,
+      );
+      attemptAbort.signal.throwIfAborted();
+      client.notify("initialized", {});
+      return { client, initialized };
+    } catch (error) {
+      try {
+        if (client) {
+          await client.dispose();
+        } else if (child) {
+          await disposeUnownedChild(child);
+        }
+      } catch (cleanupError) {
+        options.logger.warn(
+          { err: cleanupError, startupError: error },
+          "Failed to clean up Codex app-server after startup failure",
+        );
+        throw new Error("Codex app-server startup cleanup failed", { cause: cleanupError });
+      }
+      throw error;
+    } finally {
+      clearTimeout(attemptTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+export const codexAppServerStartup = new CodexAppServerStartupCoordinator();
diff --git a/packages/server/src/server/agent/providers/codex/app-server-transport.test.ts b/packages/server/src/server/agent/providers/codex/app-server-transport.test.ts
index 84b82b431b..859409ec5b 100644
--- a/packages/server/src/server/agent/providers/codex/app-server-transport.test.ts
+++ b/packages/server/src/server/agent/providers/codex/app-server-transport.test.ts
@@ -5,9 +5,57 @@ import {
   createCodexAppServerChildProcess,
   createFakeCodexAppServer,
 } from "./test-utils/fake-app-server.js";
-import { CodexAppServerClient } from "./app-server-transport.js";
+import { CodexAppServerClient, CodexAppServerExitError } from "./app-server-transport.js";
 
 describe("Codex app-server transport", () => {
+  test("classifies startup diagnostics delivered after the child exits", async () => {
+    const child = createCodexAppServerChildProcess();
+    const client = new CodexAppServerClient(child, createTestLogger());
+    const request = client.request("initialize", {});
+    const result = expect(request).rejects.toMatchObject({
+      name: "CodexAppServerExitError",
+      reason: "sqlite_state_initialization",
+      stderr: "failed to initialize sqlite state runtime",
+    });
+    child.exitCode = 1;
+    child.emit("exit", 1, null);
+    child.stderr.write("failed to initialize sqlite state runtime");
+    child.emit("close", 1, null);
+    try {
+      await result;
+    } finally {
+      child.stdout.end();
+      child.stderr.end();
+      child.stdin.end();
+    }
+  });
+
+  test.each([
+    {
+      stderr: "Error: failed to initialize sqlite state runtime under /isolated/.codex",
+      reason: "sqlite_state_initialization",
+    },
+    { stderr: "database is locked while loading configuration", reason: "other" },
+  ] as const)("classifies a failed startup from child stderr as $reason", async (entry) => {
+    const child = createCodexAppServerChildProcess();
+    const client = new CodexAppServerClient(child, createTestLogger());
+    const request = client.request("initialize", {});
+    child.stderr.write(entry.stderr);
+    child.exitCode = 1;
+    child.emit("exit", 1, null);
+
+    await expect(request).rejects.toMatchObject({
+      name: "CodexAppServerExitError",
+      reason: entry.reason,
+      exitCode: 1,
+      exitSignal: null,
+      stderr: entry.stderr,
+    } satisfies Partial<CodexAppServerExitError>);
+    child.stdout.end();
+    child.stderr.end();
+    child.stdin.end();
+  });
+
   test("ignores non-JSON stdout lines without dropping pending requests", async () => {
     const child = createCodexAppServerChildProcess();
     const client = new CodexAppServerClient(child, createTestLogger());
diff --git a/packages/server/src/server/agent/providers/codex/app-server-transport.ts b/packages/server/src/server/agent/providers/codex/app-server-transport.ts
index 5a218e2edb..04793e011a 100644
--- a/packages/server/src/server/agent/providers/codex/app-server-transport.ts
+++ b/packages/server/src/server/agent/providers/codex/app-server-transport.ts
@@ -64,6 +64,39 @@ export class CodexAppServerRpcError extends Error {
   }
 }
 
+interface CodexAppServerExitDetails {
+  exitCode: number | null;
+  exitSignal: NodeJS.Signals | null;
+  stderr: string;
+}
+
+export class CodexAppServerExitError extends Error {
+  readonly reason: "sqlite_state_initialization" | "other";
+  readonly exitCode: number | null;
+  readonly exitSignal: NodeJS.Signals | null;
+  readonly stderr: string;
+
+  constructor(details: CodexAppServerExitDetails) {
+    const message =
+      details.exitCode === 0 && !details.exitSignal
+        ? "Codex app-server exited"
+        : `Codex app-server exited with code ${details.exitCode ?? "null"} and signal ${details.exitSignal ?? "null"}`;
+    super(`${message}\n${details.stderr}`.trim());
+    this.name = "CodexAppServerExitError";
+    this.exitCode = details.exitCode;
+    this.exitSignal = details.exitSignal;
+    this.stderr = details.stderr;
+    // Codex reports this pre-initialize failure only on stderr, not as a
+    // JSON-RPC error. Classify it here so callers branch on a typed reason.
+    this.reason =
+      details.exitCode === 1 &&
+      !details.exitSignal &&
+      details.stderr.includes("failed to initialize sqlite state runtime")
+        ? "sqlite_state_initialization"
+        : "other";
+  }
+}
+
 type RequestHandler = (params: unknown, requestId: number) => unknown;
 type NotificationHandler = (method: string, params: unknown) => void;
 type UnexpectedTerminationHandler = (error: Error) => void;
@@ -234,14 +267,24 @@ export class CodexAppServerClient {
       this.handleUnexpectedTermination(err);
     });
 
+    const reportExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      this.handleUnexpectedTermination(
+        new CodexAppServerExitError({
+          exitCode: code,
+          exitSignal: signal,
+          stderr: this.stderrBuffer,
+        }),
+      );
+    };
     child.on("exit", (code, signal) => {
-      const message =
-        code === 0 && !signal
-          ? "Codex app-server exited"
-          : `Codex app-server exited with code ${code ?? "null"} and signal ${signal ?? "null"}`;
-      const error = new Error(`${message}\n${this.stderrBuffer}`.trim());
-      this.handleUnexpectedTermination(error);
+      // Startup retries need complete diagnostics. Node drains the child's
+      // stdio before close, but exit can precede the final stderr data.
+      const initializing = Array.from(this.pending.values()).some(
+        (request) => request.method === "initialize",
+      );
+      if (!initializing) reportExit(code, signal);
     });
+    child.on("close", reportExit);
   }
 
   setUnexpectedTerminationHandler(handler: UnexpectedTerminationHandler): void {
diff --git a/packages/server/src/server/agent/providers/codex/background-inventory.ts b/packages/server/src/server/agent/providers/codex/background-inventory.ts
new file mode 100644
index 0000000000..856634dbcb
--- /dev/null
+++ b/packages/server/src/server/agent/providers/codex/background-inventory.ts
@@ -0,0 +1,187 @@
+import { z } from "zod";
+import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import { CodexAppServerRpcError } from "./app-server-transport.js";
+
+type InventoryEvent = Extract<AgentStreamEvent, { type: "background_work" }>;
+interface Client {
+  request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+
+export class CodexBackgroundInventory {
+  private generation = 0;
+  private client: Client | null = null;
+  private thread: string | null = null;
+  private readonly threads = new Set<string>();
+  private origins = new Map<string, { threadId: string; processId: string }>();
+  private pending = false;
+  private dirty = false;
+  private unsupported = false;
+  private retrying = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private current: InventoryEvent | null = null;
+  private readonly listeners = new Set<() => void>();
+
+  async stopItem(id: string): Promise<void> {
+    const client = this.client;
+    const origin = this.origins.get(id);
+    const generation = this.generation;
+    if (!client || !origin || !this.current?.items?.some((item) => item.id === id))
+      throw new Error("Background terminal is no longer available");
+    const result = z
+      .object({ terminated: z.boolean() })
+      .parse(
+        await client.request(
+          "thread/backgroundTerminals/terminate",
+          { threadId: origin.threadId, processId: origin.processId },
+          10000,
+        ),
+      );
+    if (generation !== this.generation) throw new Error("Background terminal connection changed");
+    if (!result.terminated) throw new Error("Background terminal was not terminated");
+    await this.waitUntilAbsent(id, generation);
+  }
+
+  private waitUntilAbsent(id: string, generation: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => finish(new Error("Background terminal confirmation timed out")),
+        15000,
+      );
+      const finish = (error?: Error) => {
+        clearTimeout(timer);
+        this.listeners.delete(check);
+        if (error) reject(error);
+        else resolve();
+      };
+      const check = () => {
+        if (generation !== this.generation)
+          finish(new Error("Background terminal connection changed"));
+        else if (this.current?.items && !this.current.items.some((item) => item.id === id))
+          finish();
+      };
+      this.listeners.add(check);
+      this.changed(this.thread);
+    });
+  }
+  private notify() {
+    for (const listener of this.listeners) listener();
+  }
+
+  constructor(private readonly emit: (event: InventoryEvent) => void) {}
+
+  snapshot() {
+    return this.current;
+  }
+  start({ client, thread }: { client: Client; thread: string | null }) {
+    this.stop();
+    this.client = client;
+    this.thread = thread;
+    this.unsupported = false;
+    this.changed(thread);
+  }
+  stop() {
+    this.generation++;
+    this.notify();
+    this.client = null;
+    this.thread = null;
+    this.threads.clear();
+    this.origins.clear();
+    this.pending = false;
+    this.dirty = false;
+    this.retrying = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    if (this.current) this.emit({ type: "background_work", provider: "codex", items: null });
+    this.current = null;
+  }
+  changed(thread: string | null) {
+    this.thread = thread;
+    if (thread) this.threads.add(thread);
+    if (!this.client || !thread || this.unsupported) return;
+    this.dirty = true;
+    if (!this.retrying) this.refresh();
+  }
+  private refresh() {
+    if (this.pending || !this.client || !this.thread || this.unsupported) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.pending = true;
+    this.dirty = false;
+    const generation = this.generation;
+    const client = this.client;
+    const threads = [...this.threads];
+    void (async () => {
+      let failed = false;
+      try {
+        const { items, origins, activeThreads } = await readInventories(client, threads);
+        if (generation !== this.generation || this.dirty) return;
+        this.origins = origins;
+        this.threads.clear();
+        for (const threadId of activeThreads) this.threads.add(threadId);
+        if (this.thread) this.threads.add(this.thread);
+        this.current = { type: "background_work", provider: "codex", items };
+        this.emit(this.current);
+        this.notify();
+      } catch (error) {
+        failed = true;
+        if (
+          generation === this.generation &&
+          error instanceof CodexAppServerRpcError &&
+          error.code === -32601
+        )
+          this.unsupported = true;
+      } finally {
+        if (generation === this.generation) {
+          this.pending = false;
+          if (this.dirty && !failed && !this.unsupported) this.refresh();
+          else if (!this.unsupported && (failed || this.current?.items?.length)) {
+            this.retrying = failed;
+            this.timer = setTimeout(() => {
+              this.timer = null;
+              this.retrying = false;
+              this.refresh();
+            }, 5000);
+            this.timer.unref();
+          }
+        }
+      }
+    })();
+  }
+}
+
+async function readInventories(client: Client, threads: string[]) {
+  const items: NonNullable<InventoryEvent["items"]> = [];
+  const origins = new Map<string, { threadId: string; processId: string }>();
+  const activeThreads = new Set<string>();
+  for (const threadId of threads) {
+    let cursor: string | null = null;
+    do {
+      const page = z
+        .object({
+          data: z.array(z.object({ processId: z.string(), command: z.string() })),
+          nextCursor: z.string().nullable(),
+        })
+        .parse(
+          await client.request(
+            "thread/backgroundTerminals/list",
+            { threadId, ...(cursor ? { cursor } : {}) },
+            10_000,
+          ),
+        );
+      for (const row of page.data) {
+        const id = JSON.stringify([threadId, row.processId]);
+        origins.set(id, { threadId, processId: row.processId });
+        activeThreads.add(threadId);
+        items.push({
+          id,
+          kind: "shell",
+          canStop: true,
+          description: null,
+          ...(row.command ? { command: row.command } : {}),
+        });
+      }
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+  return { items, origins, activeThreads };
+}
diff --git a/packages/server/src/server/agent/providers/codex/options.ts b/packages/server/src/server/agent/providers/codex/options.ts
index 8efd42d783..83e9b15017 100644
--- a/packages/server/src/server/agent/providers/codex/options.ts
+++ b/packages/server/src/server/agent/providers/codex/options.ts
@@ -37,6 +37,9 @@ const NetworkPolicySchema = z
 // Codex config reference, maintained against Codex CLI 0.143+.
 export const CodexProviderOptionsSchema = z
   .object({
+    // Composer controls, not Codex config: the provider reads them and keeps them out of `config`.
+    service_tier: z.string().optional(),
+    plan_mode: z.boolean().optional(),
     approval_policy: ApprovalPolicySchema.optional(),
     sandbox_mode: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
     sandbox_workspace_write: z
diff --git a/packages/server/src/server/agent/providers/codex/test-utils/fake-app-server.ts b/packages/server/src/server/agent/providers/codex/test-utils/fake-app-server.ts
index 99e6a73050..195d924654 100644
--- a/packages/server/src/server/agent/providers/codex/test-utils/fake-app-server.ts
+++ b/packages/server/src/server/agent/providers/codex/test-utils/fake-app-server.ts
@@ -43,6 +43,13 @@ interface FakeTerminalInput {
   processId: string;
   text: string;
 }
+interface FakeFileChange {
+  threadId: string;
+  turnId: string;
+  callId: string;
+  path: string;
+  diff: string;
+}
 interface FakeLegacyPatch {
   threadId: string;
   callId: string;
@@ -88,6 +95,7 @@ export interface FakeCodexAppServer {
   completesSubAgentActivity(params: FakeSubAgentActivity): void;
   completesCompaction(params: { threadId: string; itemId: string }): void;
   runsLegacyCommand(params: FakeLegacyCommand): void;
+  startsFileChange(params: FakeFileChange): void;
   appliesLegacyPatch(params: FakeLegacyPatch): void;
   completesCommand(params: FakeLegacyCommand): void;
   completesSilentCommand(params: FakeSilentCommand): void;
@@ -138,6 +146,10 @@ export function createCodexAppServerChildProcess(): CodexAppServerChildProcess {
     exitCode: null,
     signalCode: null,
   }) as CodexAppServerChildProcess;
+  // A real ChildProcess closes its stdio after exit, then emits close.
+  child.once("exit", (code, signal) => {
+    queueMicrotask(() => child.emit("close", code, signal));
+  });
   child.kill = ((signal?: NodeJS.Signals | number) => {
     queueMicrotask(() => child.emit("exit", null, signal ?? null));
     return true;
@@ -167,6 +179,7 @@ export function createFakeCodexAppServer(
     "skills/list": () => ({ data: [] }),
     "thread/start": () => ({ thread: { id: "thread-1" } }),
     "thread/loaded/list": () => ({ data: [] }),
+    "thread/backgroundTerminals/list": () => ({ data: [], nextCursor: null }),
     "thread/resume": () => ({}),
     "turn/start": () => ({}),
     "thread/fork": (params) => ({
@@ -467,6 +480,20 @@ export function createFakeCodexAppServer(
         success: true,
       });
     },
+    startsFileChange(params) {
+      writeNotification("item/started", {
+        threadId: params.threadId,
+        turnId: params.turnId,
+        item: {
+          type: "fileChange",
+          id: params.callId,
+          status: "inProgress",
+          changes: [
+            { path: params.path, kind: { type: "update", move_path: null }, diff: params.diff },
+          ],
+        },
+      });
+    },
     appliesLegacyPatch(params) {
       const changes = [
         {
diff --git a/packages/server/src/server/agent/providers/codex/thread-history.test.ts b/packages/server/src/server/agent/providers/codex/thread-history.test.ts
index 8d3d8fce3d..3feb737aa8 100644
--- a/packages/server/src/server/agent/providers/codex/thread-history.test.ts
+++ b/packages/server/src/server/agent/providers/codex/thread-history.test.ts
@@ -1,4 +1,3 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { describe, expect, test } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
@@ -27,15 +26,24 @@ async function openCodexThread(
   const appServer = createFakeCodexAppServer(
     fakeCodexThreadHistory({ "saved-thread": thread }, options),
   );
-  const provider = new CodexAppServerAgentClient(createTestLogger());
+  const provider = new CodexAppServerAgentClient(
+    createTestLogger(),
+    {
+      command: { mode: "replace", argv: ["codex-must-not-run-in-this-test"] },
+    },
+    {
+      appServerProcess: {
+        resolvePrefix: async () => ({ command: "codex", args: [] }),
+        spawn: () => appServer.child,
+      },
+    },
+  );
   const internals = provider as unknown as {
     goalsEnabledPromise: Promise<boolean> | null;
     autoReviewEnabledPromise: Promise<boolean> | null;
-    spawnAppServer: () => Promise<ChildProcessWithoutNullStreams>;
   };
   internals.goalsEnabledPromise = Promise.resolve(false);
   internals.autoReviewEnabledPromise = Promise.resolve(false);
-  internals.spawnAppServer = async () => appServer.child;
   const session = await provider.resumeSession({ sessionId: "saved-thread" });
   return { appServer, session };
 }
diff --git a/packages/server/src/server/agent/providers/codex/tool-call-detail-parser.ts b/packages/server/src/server/agent/providers/codex/tool-call-detail-parser.ts
index df650e865c..e09c66beb6 100644
--- a/packages/server/src/server/agent/providers/codex/tool-call-detail-parser.ts
+++ b/packages/server/src/server/agent/providers/codex/tool-call-detail-parser.ts
@@ -18,6 +18,7 @@ import {
   toShellToolDetail,
   toWriteToolDetail,
   toolDetailBranchByNameWithCwd,
+  parseKnownToolDetail,
 } from "../tool-call-detail-primitives.js";
 
 export interface CodexToolDetailContext {
@@ -205,9 +206,9 @@ export function deriveCodexToolDetail(params: {
     };
   }
 
-  const pass2 = CodexToolDetailPass2Schema.safeParse(pass1.data);
-  if (pass2.success && pass2.data) {
-    return pass2.data;
+  const detail = parseKnownToolDetail(CodexToolDetailPass2Schema, pass1.data);
+  if (detail) {
+    return detail;
   }
 
   return {
diff --git a/packages/server/src/server/agent/providers/codex/tool-call-mapper.test.ts b/packages/server/src/server/agent/providers/codex/tool-call-mapper.test.ts
index 566fd10083..423aa08c76 100644
--- a/packages/server/src/server/agent/providers/codex/tool-call-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/codex/tool-call-mapper.test.ts
@@ -528,6 +528,165 @@ describe("codex tool-call mapper", () => {
     });
   });
 
+  it.each([
+    ["inProgress", "running"],
+    ["completed", "completed"],
+  ])("keeps both fileChange diffs when the patch is %s", (status, expectedStatus) => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "codex-two-files",
+        status,
+        changes: [
+          {
+            path: "/tmp/repo/alpha.txt",
+            kind: { type: "update", move_path: null },
+            diff: "@@ -1 +1 @@\n-color = blue\n+color = green\n",
+          },
+          {
+            path: "/tmp/repo/beta.txt",
+            kind: { type: "update", move_path: null },
+            diff: "@@ -1 +1 @@\n-size = small\n+size = large\n",
+          },
+        ],
+      },
+      { cwd: "/tmp/repo" },
+    );
+
+    expect(item).toEqual({
+      type: "tool_call",
+      callId: "codex-two-files",
+      name: "apply_patch",
+      status: expectedStatus,
+      error: null,
+      detail: {
+        type: "edit",
+        filePath: "alpha.txt",
+        unifiedDiff: [
+          "diff --git a/alpha.txt b/alpha.txt",
+          "--- a/alpha.txt",
+          "+++ b/alpha.txt",
+          "@@ -1 +1 @@",
+          "-color = blue",
+          "+color = green",
+          "",
+          "diff --git a/beta.txt b/beta.txt",
+          "--- a/beta.txt",
+          "+++ b/beta.txt",
+          "@@ -1 +1 @@",
+          "-size = small",
+          "+size = large",
+        ].join("\n"),
+      },
+    });
+  });
+
+  it("uses the move destination in generated multi-file diff headers", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "codex-moved-file",
+        status: "completed",
+        changes: [
+          {
+            path: "/tmp/repo/old.txt",
+            kind: { type: "update", move_path: "/tmp/repo/new.txt" },
+            diff: "@@ -1 +1 @@\n-old\n+new\n",
+          },
+          {
+            path: "/tmp/repo/other.txt",
+            kind: { type: "update", move_path: null },
+            diff: "@@ -1 +1 @@\n-before\n+after\n",
+          },
+        ],
+      },
+      { cwd: "/tmp/repo" },
+    );
+
+    expect(item).toEqual({
+      type: "tool_call",
+      callId: "codex-moved-file",
+      name: "apply_patch",
+      status: "completed",
+      error: null,
+      detail: {
+        type: "edit",
+        filePath: "old.txt",
+        unifiedDiff: [
+          "diff --git a/old.txt b/new.txt",
+          "--- a/old.txt",
+          "+++ b/new.txt",
+          "@@ -1 +1 @@",
+          "-old",
+          "+new",
+          "",
+          "diff --git a/other.txt b/other.txt",
+          "--- a/other.txt",
+          "+++ b/other.txt",
+          "@@ -1 +1 @@",
+          "-before",
+          "+after",
+        ].join("\n"),
+      },
+    });
+  });
+
+  it("keeps update, add, and delete changes in one fileChange diff", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "codex-mixed-files",
+        status: "completed",
+        changes: [
+          {
+            path: "/tmp/repo/alpha.txt",
+            kind: { type: "update", move_path: null },
+            diff: "--- a/alpha.txt\n+++ b/alpha.txt\n@@ -1 +1 @@\n-blue\n+green\n",
+          },
+          { path: "/tmp/repo/new.txt", kind: { type: "add" }, diff: "new\n\nvalue\n" },
+          { path: "/tmp/repo/old.txt", kind: { type: "delete" }, diff: "old\n\nvalue\n" },
+        ],
+      },
+      { cwd: "/tmp/repo" },
+    );
+
+    expect(item).toEqual({
+      type: "tool_call",
+      callId: "codex-mixed-files",
+      name: "apply_patch",
+      status: "completed",
+      error: null,
+      detail: {
+        type: "edit",
+        filePath: "alpha.txt",
+        unifiedDiff: [
+          "diff --git a/alpha.txt b/alpha.txt",
+          "--- a/alpha.txt",
+          "+++ b/alpha.txt",
+          "@@ -1 +1 @@",
+          "-blue",
+          "+green",
+          "",
+          "diff --git a/new.txt b/new.txt",
+          "--- /dev/null",
+          "+++ b/new.txt",
+          "@@ -0,0 +1,3 @@",
+          "+new",
+          "+",
+          "+value",
+          "",
+          "diff --git a/old.txt b/old.txt",
+          "--- a/old.txt",
+          "+++ /dev/null",
+          "@@ -1,3 +0,0 @@",
+          "-old",
+          "-",
+          "-value",
+        ].join("\n"),
+      },
+    });
+  });
+
   it("maps fileChange object-style change payloads keyed by path", () => {
     const item = expectMapped(
       mapCodexToolCallFromThreadItem(
@@ -827,6 +986,44 @@ describe("codex tool-call mapper", () => {
     });
   });
 
+  it("maps multi-file path-only updates to unknown detail", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "codex-multi-file-path-only",
+        status: "completed",
+        changes: [
+          { path: "/tmp/repo/first.ts", kind: "modify" },
+          { path: "/tmp/repo/second.ts", kind: { type: "update", move_path: null } },
+        ],
+      },
+      { cwd: "/tmp/repo" },
+    );
+
+    expect(item).toEqual({
+      type: "tool_call",
+      callId: "codex-multi-file-path-only",
+      name: "apply_patch",
+      status: "completed",
+      error: null,
+      detail: {
+        type: "unknown",
+        input: {
+          files: [
+            { path: "first.ts", kind: "modify" },
+            { path: "second.ts", kind: "update" },
+          ],
+        },
+        output: {
+          files: [
+            { path: "first.ts", kind: "modify" },
+            { path: "second.ts", kind: "update" },
+          ],
+        },
+      },
+    });
+  });
+
   it("maps path-only apply_patch tool-call payloads to unknown detail instead of empty edit detail", () => {
     const item = expectMapped(
       mapCodexToolCallEnvelope({
@@ -1102,3 +1299,186 @@ describe("codex tool-call mapper", () => {
     `);
   });
 });
+
+describe("multi-file diff budget", () => {
+  it("retains a labeled diff for later files when the first diff exceeds the detail limit", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "large-multi-file",
+        status: "completed",
+        changes: [
+          {
+            path: "/repo/alpha.txt",
+            kind: "modify",
+            diff: "@@ -1 +1 @@\n-old\n+" + "a".repeat(14000),
+          },
+          { path: "/repo/beta.txt", kind: "modify", diff: "@@ -1 +1 @@\n-small\n+large\n" },
+        ],
+      },
+      { cwd: "/repo" },
+    );
+    expect(item?.detail.type).toBe("edit");
+    if (item?.detail.type !== "edit") throw new Error("Expected edit detail");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/alpha.txt b/alpha.txt");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/beta.txt b/beta.txt");
+    expect(item.detail.unifiedDiff).toContain("+large");
+    expect(item.detail.unifiedDiff!.length).toBeLessThanOrEqual(12000);
+  });
+});
+
+describe("multi-file preview metadata", () => {
+  it("preserves a path-keyed move destination", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "moved-keyed",
+        status: "completed",
+        changes: {
+          "/repo/old.txt": {
+            type: "update",
+            move_path: "/repo/new.txt",
+            unified_diff: "@@ -1 +1 @@\n-old\n+new\n",
+          },
+          "/repo/other.txt": { type: "update", unified_diff: "@@ -1 +1 @@\n-before\n+after\n" },
+        },
+      },
+      { cwd: "/repo" },
+    );
+    expect(item?.detail.type).toBe("edit");
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/old.txt b/new.txt");
+    expect(item.detail.unifiedDiff).toContain("+++ b/new.txt");
+  });
+  it("names the file whose diff is shown when the first entry has no content", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "partial-content",
+        status: "completed",
+        changes: [
+          { path: "/repo/first.txt", kind: "modify" },
+          { path: "/repo/second.txt", kind: "modify", diff: "@@ -1 +1 @@\n-old\n+new\n" },
+        ],
+      },
+      { cwd: "/repo" },
+    );
+    expect(item?.detail).toMatchObject({ type: "edit", filePath: "second.txt" });
+  });
+  it("keeps whole labels and marks omitted files when many long paths exceed the preview", () => {
+    const paths = Array.from(
+      { length: 50 },
+      (_, index) => `src/${String(index).padStart(2, "0")}-${"x".repeat(108)}.txt`,
+    );
+    const item = mapCodexToolCallFromThreadItem({
+      type: "fileChange",
+      id: "many-files",
+      status: "completed",
+      changes: paths.map((path) => ({ path, kind: "modify", diff: "@@ -1 +1 @@\n-old\n+new\n" })),
+    });
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    const diff = item.detail.unifiedDiff!;
+    const headers = diff.split("\n").filter((line) => line.startsWith("diff --git "));
+    expect(headers.length).toBeGreaterThan(0);
+    const expectedHeaders = paths.map((path) => `diff --git a/${path} b/${path}`);
+    expect(expectedHeaders).toEqual(expect.arrayContaining(headers));
+    expect(diff).toContain("-old\n+new");
+    expect(diff).toContain(`${paths.length - headers.length} more files omitted`);
+    expect(diff.length).toBeLessThanOrEqual(12000);
+  });
+});
+
+describe("large multi-file additions", () => {
+  it("bounds a generated addition without throwing before later files are mapped", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "large-addition",
+        status: "completed",
+        changes: [
+          { path: "/repo/generated.txt", kind: { type: "add" }, diff: "x\n".repeat(150000) },
+          { path: "/repo/second.txt", kind: { type: "add" }, diff: "second\n" },
+        ],
+      },
+      { cwd: "/repo" },
+    );
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    expect(item.status).toBe("completed");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/generated.txt b/generated.txt");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/second.txt b/second.txt");
+    expect(item.detail.unifiedDiff).toContain("+second");
+    expect(item.detail.unifiedDiff!.length).toBeLessThanOrEqual(12000);
+  });
+});
+
+describe("move-only entries in multi-file previews", () => {
+  it("shows a move without manufacturing added file contents from provider metadata", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "move-only",
+        status: "completed",
+        changes: [
+          {
+            path: "/repo/old.txt",
+            kind: { type: "update", move_path: "/repo/new.txt" },
+            diff: "\n\nMoved to: /repo/new.txt",
+          },
+          { path: "/repo/second.txt", kind: "modify", diff: "@@ -1 +1 @@\n-small\n+large\n" },
+        ],
+      },
+      { cwd: "/repo" },
+    );
+    if (item?.detail.type !== "edit") throw new Error("Expected edit");
+    expect(item.detail.unifiedDiff).toContain("rename from old.txt\nrename to new.txt");
+    expect(item.detail.unifiedDiff).toContain("diff --git a/second.txt b/second.txt");
+    expect(item.detail.unifiedDiff).not.toContain("+Moved to:");
+    expect(item.detail.unifiedDiff).not.toContain("@@ -0,0");
+  });
+});
+
+describe("single-file move compatibility", () => {
+  it("retains the destination outside the multi-file preview path", () => {
+    const item = mapCodexToolCallFromThreadItem(
+      {
+        type: "fileChange",
+        id: "single-move",
+        status: "completed",
+        changes: [
+          {
+            path: "/repo/old.txt",
+            kind: { type: "update", move_path: "/repo/new.txt" },
+            diff: "\n\nMoved to: /repo/new.txt",
+          },
+        ],
+      },
+      { cwd: "/repo" },
+    );
+    expect(JSON.stringify(item)).toContain("new.txt");
+  });
+});
+
+describe("empty additions in multi-file previews", () => {
+  it.each(["inProgress", "completed"])(
+    "keeps an empty created file when the patch is %s",
+    (status) => {
+      const item = mapCodexToolCallFromThreadItem(
+        {
+          type: "fileChange",
+          id: "empty-addition",
+          status,
+          changes: [
+            { path: "/repo/empty.txt", kind: { type: "add" }, diff: "" },
+            { path: "/repo/second.txt", kind: "modify", diff: "@@ -1 +1 @@\n-old\n+new\n" },
+          ],
+        },
+        { cwd: "/repo" },
+      );
+      if (item?.detail.type !== "edit") throw new Error("Expected edit");
+      expect(item.detail.unifiedDiff).toContain(
+        "diff --git a/empty.txt b/empty.txt\n--- /dev/null\n+++ b/empty.txt",
+      );
+      expect(item.detail.unifiedDiff).toContain("diff --git a/second.txt b/second.txt");
+    },
+  );
+});
diff --git a/packages/server/src/server/agent/providers/codex/tool-call-mapper.ts b/packages/server/src/server/agent/providers/codex/tool-call-mapper.ts
index 4e77dc9367..8c0f8b9558 100644
--- a/packages/server/src/server/agent/providers/codex/tool-call-mapper.ts
+++ b/packages/server/src/server/agent/providers/codex/tool-call-mapper.ts
@@ -4,6 +4,7 @@ import type { ToolCallTimelineItem } from "../../agent-sdk-types.js";
 import {
   extractCodexShellOutput,
   normalizeToolCallStatus,
+  TOOL_CALL_DIFF_MAX_CHARS,
   truncateDiffText,
 } from "../tool-call-mapper-utils.js";
 import { deriveCodexToolDetail, normalizeCodexFilePath } from "./tool-call-detail-parser.js";
@@ -400,7 +401,7 @@ function contentToDeletionDiff(filePath: string, content: string): string {
   output.push(`diff --git a/${filePath} b/${filePath}`);
   output.push(`--- a/${filePath}`);
   output.push(`+++ /dev/null`);
-  const nonEmpty = lines.filter((l) => l.length > 0 || lines.indexOf(l) < lines.length - 1);
+  const nonEmpty = lines.slice(0, lines.at(-1) === "" ? -1 : undefined);
   if (nonEmpty.length > 0) {
     output.push(`@@ -1,${nonEmpty.length} +0,0 @@`);
     for (const line of nonEmpty) {
@@ -713,6 +714,7 @@ interface CodexFileChangeEntry {
   path: string;
   kind?: string;
   diff?: string;
+  movePath?: string;
 }
 
 function parseFileChangePath(
@@ -740,6 +742,9 @@ function parseFileChangePath(
 }
 
 function parseFileChangeKind(entry: Record<string, unknown>): string | undefined {
+  if (isRecord(entry.kind) && typeof entry.kind.type === "string") {
+    return entry.kind.type;
+  }
   return (
     (typeof entry.kind === "string" && entry.kind) ||
     (typeof entry.type === "string" && entry.type) ||
@@ -767,10 +772,14 @@ function toFileChangeEntry(
   if (!path) {
     return null;
   }
+  const kind = isRecord(entry.kind) ? entry.kind : undefined;
+  const movePath = entry.move_path ?? kind?.move_path;
   return {
     path,
     kind: parseFileChangeKind(entry),
     diff: parseFileChangeDiff(entry),
+    movePath:
+      typeof movePath === "string" ? normalizeCodexFilePath(movePath, options?.cwd) : undefined,
   };
 }
 
@@ -839,6 +848,105 @@ function resolveFileChangeTextFields(file: CodexFileChangeEntry | undefined): {
   return asEditTextFields(file.diff);
 }
 
+function fileChangeToUnifiedDiff(file: CodexFileChangeEntry): string {
+  // Codex formats a content-preserving move as a notice, not added file text.
+  const isMoveOnlyNotice = file.movePath && file.diff?.startsWith("\n\nMoved to: ");
+  const { unifiedDiff, newString } = isMoveOnlyNotice ? {} : resolveFileChangeTextFields(file);
+  if (!unifiedDiff && !newString) {
+    if (file.kind === "add") {
+      return [
+        `diff --git a/${file.path} b/${file.path}`,
+        "--- /dev/null",
+        `+++ b/${file.path}`,
+      ].join("\n");
+    }
+    return file.movePath
+      ? [
+          `diff --git a/${file.path} b/${file.movePath}`,
+          `rename from ${file.path}`,
+          `rename to ${file.movePath}`,
+        ].join("\n")
+      : "";
+  }
+  if (unifiedDiff?.startsWith("diff --git")) {
+    return unifiedDiff.replace(/\r?\n$/, "");
+  }
+  const destination = file.movePath ?? file.path;
+  const header = `diff --git a/${file.path} b/${destination}`;
+  if (unifiedDiff?.startsWith("--- ")) {
+    return `${header}\n${unifiedDiff.replace(/\r?\n$/, "")}`;
+  }
+  const left = file.kind === "add" ? "/dev/null" : `a/${file.path}`;
+  const right = file.kind === "delete" ? "/dev/null" : `b/${destination}`;
+  const lines = [header, `--- ${left}`, `+++ ${right}`];
+  if (unifiedDiff) {
+    lines.push(unifiedDiff.replace(/\r?\n$/, ""));
+  } else if (newString) {
+    const contentLines = newString.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+    lines.push(`@@ -0,0 +1,${contentLines.length} @@`);
+    for (const line of contentLines) lines.push(`+${line}`);
+  }
+  return lines.join("\n");
+}
+
+function splitFileDiffPreview(diff: string): { header: string; body: string } {
+  const hunk = diff.indexOf("\n@@");
+  const bodyStart = hunk < 0 ? -1 : diff.indexOf("\n", hunk + 1);
+  return bodyStart < 0
+    ? { header: diff, body: "" }
+    : { header: diff.slice(0, bodyStart + 1), body: diff.slice(bodyStart + 1) };
+}
+
+export function fileChangesToPreview(files: CodexFileChangeEntry[]): {
+  filePath: string | undefined;
+  unifiedDiff: string;
+} {
+  const diffs = files
+    .map((file) => ({ filePath: file.path, diff: fileChangeToUnifiedDiff(file) }))
+    .filter((file) => file.diff.length > 0);
+  const filePath = diffs[0]?.filePath ?? files[0]?.path;
+  const combined = diffs.map((file) => file.diff).join("\n\n");
+  if (combined.length <= TOOL_CALL_DIFF_MAX_CHARS) return { filePath, unifiedDiff: combined };
+
+  const marker = "\n...[truncated]";
+  const omittedNotice = (count: number) =>
+    count > 0 ? `\n\n...[${count} more files omitted]` : "";
+  const previews = diffs.map((file) => splitFileDiffPreview(file.diff));
+  const visible: typeof previews = [];
+  let minimumSize = 0;
+  for (const preview of previews) {
+    // Keep whole labels and a useful body excerpt, or explicitly omit the file.
+    const required =
+      preview.header.length + Math.max(marker.length, Math.min(80, preview.body.length));
+    const nextSize = minimumSize + required + (visible.length > 0 ? 2 : 0);
+    if (
+      nextSize + omittedNotice(previews.length - visible.length - 1).length >
+      TOOL_CALL_DIFF_MAX_CHARS
+    )
+      break;
+    visible.push(preview);
+    minimumSize = nextSize;
+  }
+  const omitted = omittedNotice(previews.length - visible.length);
+  const headersSize = visible.reduce((size, preview) => size + preview.header.length, 0);
+  const bodyBudget = Math.floor(
+    (TOOL_CALL_DIFF_MAX_CHARS -
+      headersSize -
+      Math.max(0, visible.length - 1) * 2 -
+      omitted.length) /
+      Math.max(1, visible.length),
+  );
+  const unifiedDiff =
+    visible
+      .map(
+        ({ header, body }) =>
+          header +
+          (body.length <= bodyBudget ? body : body.slice(0, bodyBudget - marker.length) + marker),
+      )
+      .join("\n\n") + omitted;
+  return { filePath, unifiedDiff };
+}
+
 function mapFileChangeItem(
   item: z.infer<typeof CodexFileChangeItemSchema>,
   options?: CodexMapperOptions,
@@ -873,17 +981,17 @@ function mapFileChangeItem(
   const error = item.error ?? null;
   const status = normalizeToolCallStatus(item.status, error, output);
   const firstFile = files[0];
-  const firstTextFields = resolveFileChangeTextFields(firstFile);
-  const hasFirstTextFields = Object.keys(firstTextFields).length > 0;
+  const preview = files.length > 1 ? fileChangesToPreview(files) : undefined;
+  const filePath = preview?.filePath ?? firstFile?.path;
+  const textFields = preview
+    ? { unifiedDiff: preview.unifiedDiff }
+    : resolveFileChangeTextFields(firstFile);
+  const hasTextFields = Boolean(textFields.unifiedDiff || textFields.newString);
   const input = toNullableObject({
     ...inputBase,
-    ...(firstFile?.path && hasFirstTextFields ? { path: firstFile.path } : {}),
-    ...(hasFirstTextFields && firstTextFields.unifiedDiff
-      ? { patch: firstTextFields.unifiedDiff }
-      : {}),
-    ...(hasFirstTextFields && firstTextFields.newString
-      ? { content: firstTextFields.newString }
-      : {}),
+    ...(filePath && hasTextFields ? { path: filePath } : {}),
+    ...(hasTextFields && textFields.unifiedDiff ? { patch: textFields.unifiedDiff } : {}),
+    ...(hasTextFields && textFields.newString ? { content: textFields.newString } : {}),
   });
 
   return {
diff --git a/packages/server/src/server/agent/providers/cursor-acp-agent.test.ts b/packages/server/src/server/agent/providers/cursor-acp-agent.test.ts
index 97b4c1cc86..f858e965aa 100644
--- a/packages/server/src/server/agent/providers/cursor-acp-agent.test.ts
+++ b/packages/server/src/server/agent/providers/cursor-acp-agent.test.ts
@@ -155,7 +155,7 @@ describe("CursorACPAgentClient model discovery", () => {
     });
   });
 
-  test("exposes Cursor fast mode through provider features", async () => {
+  test("exposes Cursor fast mode through provider controls", async () => {
     const client = new TestCursorACPAgentClient({
       sessionId: "session-1",
       models: null,
@@ -163,46 +163,35 @@ describe("CursorACPAgentClient model discovery", () => {
     });
 
     await expect(
-      client.listFeatures({
+      client.listControls({
         provider: "acp",
         cwd: "/tmp/cursor",
       }),
-    ).resolves.toEqual([
-      {
-        type: "toggle",
-        id: "auto_accept",
-        label: "Auto Accept",
-        description: "Automatically approves ACP permission prompts.",
-        tooltip: "Auto accept permission prompts",
-        icon: "shield-check",
-        value: false,
-      },
-      {
-        type: "select",
-        id: CURSOR_FAST_FEATURE_OPTION.id,
-        label: "Fast",
-        description: "Cursor fast mode",
-        tooltip: "Select Cursor fast mode",
-        icon: "zap",
-        value: "false",
-        options: [
-          {
-            id: "false",
-            label: "Off",
-            isDefault: true,
-            description: undefined,
-            metadata: undefined,
-          },
-          {
-            id: "true",
-            label: "Fast",
-            isDefault: false,
-            description: undefined,
-            metadata: undefined,
-          },
-        ],
-      },
-    ]);
+    ).resolves.toEqual({
+      controls: [
+        {
+          type: "toggle",
+          key: "auto_accept",
+          label: "Auto Accept",
+          description: "Automatically approves ACP permission prompts.",
+          tooltip: "Auto accept permission prompts",
+          icon: "shield-check",
+        },
+        {
+          type: "select",
+          key: CURSOR_FAST_FEATURE_OPTION.id,
+          label: "Fast",
+          description: "Cursor fast mode",
+          tooltip: "Select Cursor fast mode",
+          icon: "zap",
+          choices: [
+            { value: "false", label: "Off" },
+            { value: "true", label: "Fast" },
+          ],
+        },
+      ],
+      options: { fast: "false" },
+    });
   });
 });
 
@@ -228,7 +217,9 @@ describe("CursorACPAgentClient session start", () => {
     session: {
       currentModelId: string;
       configOptions: SessionConfigOption[];
-      setSessionConfigOption?: () => Promise<{ configOptions: SessionConfigOption[] }>;
+      setSessionConfigOption?: (request: {
+        value: string;
+      }) => Promise<{ configOptions: SessionConfigOption[] }>;
     } = { currentModelId: "kimi-k3", configOptions: KIMI_K3_CONFIG_OPTIONS },
     logger = createTestLogger(),
   ): ACPAgentSession {
@@ -277,7 +268,7 @@ describe("CursorACPAgentClient session start", () => {
     // still stored after the draft moved to a model that has no fast variant.
     const warn = captureWarnings();
     const session = createCursorSession(
-      { model: "kimi-k3", featureValues: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
+      { model: "kimi-k3", providerOptions: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
       { currentModelId: "kimi-k3", configOptions: KIMI_K3_CONFIG_OPTIONS },
       warn.logger,
     );
@@ -295,7 +286,7 @@ describe("CursorACPAgentClient session start", () => {
     // still listed after the model moves to one that has no fast variant.
     const warn = captureWarnings();
     const session = createCursorSession(
-      { model: "kimi-k3", featureValues: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
+      { model: "kimi-k3", providerOptions: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
       {
         currentModelId: "composer-2.5",
         configOptions: [fastConfigOption("false"), ...KIMI_K3_CONFIG_OPTIONS],
@@ -319,7 +310,7 @@ describe("CursorACPAgentClient session start", () => {
 
   test("still fails session start when a stored feature write fails for another reason", async () => {
     const session = createCursorSession(
-      { model: "kimi-k3", featureValues: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
+      { model: "kimi-k3", providerOptions: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
       {
         currentModelId: "composer-2.5",
         configOptions: [fastConfigOption("false"), ...KIMI_K3_CONFIG_OPTIONS],
@@ -334,16 +325,71 @@ describe("CursorACPAgentClient session start", () => {
     const session = createCursorSession({ model: "kimi-k3" });
     await session.initializeNewSession();
 
-    await expect(session.setFeature(CURSOR_FAST_FEATURE_OPTION.id, "true")).rejects.toThrow(
+    await expect(session.applyOptions({ [CURSOR_FAST_FEATURE_OPTION.id]: "true" })).rejects.toThrow(
       "acp does not expose ACP feature 'fast'",
     );
   });
 
+  test("removing auto_accept returns the session to asking for permission", async () => {
+    const session = createCursorSession({ model: "composer-2.5" });
+    await session.initializeNewSession();
+    const request = {
+      sessionId: "session-1",
+      toolCall: { toolCallId: "tool-1", title: "Run command", kind: "execute", status: "pending" },
+      options: [{ optionId: "allow-always", name: "Always allow", kind: "allow_always" }],
+    } as const;
+
+    await session.applyOptions({ auto_accept: true });
+    await expect(session.requestPermission({ ...request })).resolves.toEqual({
+      outcome: { outcome: "selected", optionId: "allow-always" },
+    });
+    await expect(session.applyOptions({ auto_accept: null })).resolves.toEqual({});
+
+    void session.requestPermission({ ...request });
+    await vi.waitFor(() => expect(session.getPendingPermissions()).toHaveLength(1));
+  });
+
+  test("a rejected patch leaves auto_accept as it was", async () => {
+    const session = createCursorSession({ model: "kimi-k3" });
+    await session.initializeNewSession();
+
+    await expect(
+      session.applyOptions({ auto_accept: true, [CURSOR_FAST_FEATURE_OPTION.id]: "true" }),
+    ).rejects.toThrow("acp does not expose ACP feature 'fast'");
+
+    void session.requestPermission({
+      sessionId: "session-1",
+      toolCall: { toolCallId: "tool-1", title: "Run command", kind: "execute", status: "pending" },
+      options: [{ optionId: "allow-always", name: "Always allow", kind: "allow_always" }],
+    });
+    await vi.waitFor(() => expect(session.getPendingPermissions()).toHaveLength(1));
+  });
+
+  test("applies only the selects the patch sets", async () => {
+    const setSessionConfigOption = vi.fn(async (request: { value: string }) => ({
+      configOptions: [fastConfigOption(request.value === "true" ? "true" : "false")],
+    }));
+    const session = createCursorSession(
+      { model: "composer-2.5" },
+      {
+        currentModelId: "composer-2.5",
+        configOptions: [fastConfigOption("false")],
+        setSessionConfigOption,
+      },
+    );
+    await session.initializeNewSession();
+
+    await session.applyOptions({ [CURSOR_FAST_FEATURE_OPTION.id]: "true" });
+    await session.applyOptions({});
+
+    expect(setSessionConfigOption.mock.calls.map(([request]) => request.value)).toEqual(["true"]);
+  });
+
   test("still fails session start when the provider rejects a write it should accept", async () => {
     // No model switch, so the session's options came straight from session/new and the
     // provider disagreeing about a feature it just advertised is a real failure.
     const session = createCursorSession(
-      { model: "composer-2.5", featureValues: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
+      { model: "composer-2.5", providerOptions: { [CURSOR_FAST_FEATURE_OPTION.id]: "true" } },
       {
         currentModelId: "composer-2.5",
         configOptions: [fastConfigOption("false")],
diff --git a/packages/server/src/server/agent/providers/generic-acp-agent.permission-turn-failure.test.ts b/packages/server/src/server/agent/providers/generic-acp-agent.permission-turn-failure.test.ts
index aaa6a5110e..f64c719c6d 100644
--- a/packages/server/src/server/agent/providers/generic-acp-agent.permission-turn-failure.test.ts
+++ b/packages/server/src/server/agent/providers/generic-acp-agent.permission-turn-failure.test.ts
@@ -5,6 +5,7 @@ import path from "node:path";
 import { describe, expect, test } from "vitest";
 
 import { createTestLogger } from "../../../test-utils/test-logger.js";
+import { AgentManager } from "../agent-manager.js";
 import type { AgentSession, AgentStreamEvent } from "../agent-sdk-types.js";
 import { GenericACPAgentClient } from "./generic-acp-agent.js";
 
@@ -12,6 +13,7 @@ describe("GenericACPAgentClient permission requests when a turn ends early", ()
   test.each([
     { ending: "fail", terminalEvent: "turn_failed" },
     { ending: "cancel", terminalEvent: "turn_canceled" },
+    { ending: "end_turn", terminalEvent: "turn_completed" },
   ] as const)(
     "answers a permission request left open by a $terminalEvent turn with cancelled",
     async ({ ending, terminalEvent }) => {
@@ -25,6 +27,16 @@ describe("GenericACPAgentClient permission requests when a turn ends early", ()
           await waitForEvent(events, terminalEvent);
           expect(hasEvent(events, "permission_requested")).toBe(true);
           expect(session.getPendingPermissions()).toEqual([]);
+          const requested = permissionRequests(events)[0]!;
+          expect(resolvedEvents(events)).toEqual([
+            {
+              type: "permission_resolved",
+              provider: "acp",
+              requestId: requested.request.id,
+              resolution: { behavior: "deny", message: "Permission request canceled" },
+              turnId: requested.turnId,
+            },
+          ]);
 
           const replyStart = events.length;
           await session.startTurn("turn two");
@@ -39,6 +51,84 @@ describe("GenericACPAgentClient permission requests when a turn ends early", ()
       });
     },
   );
+
+  test.each(["completed", "failed"] as const)(
+    "cancels only the matching permission when its tool becomes %s",
+    async (status) => {
+      await withFakeACPAgent(status, async (command, cwd) => {
+        const client = new GenericACPAgentClient({ logger: createTestLogger(), command });
+        const session = await client.createSession({ provider: "acp", cwd });
+        try {
+          const events = collectEvents(session);
+          await session.startTurn("turn one");
+          await waitForToolUpdate(events);
+          expect(pendingToolIds(session)).toEqual(["tool-2"]);
+          expect(resolvedEvents(events)).toEqual([
+            expect.objectContaining({ requestId: permissionRequests(events)[0]!.request.id }),
+          ]);
+        } finally {
+          await session.close();
+        }
+      });
+    },
+  );
+
+  test("keeps a permission raised outside a turn answerable after another turn completes", async () => {
+    await withFakeACPAgent("outside_turn", async (command, cwd) => {
+      const client = new GenericACPAgentClient({ logger: createTestLogger(), command });
+      const session = await client.createSession({ provider: "acp", cwd });
+      try {
+        const outside = session.getPendingPermissions();
+        expect(pendingToolIds(session)).toEqual(["tool-outside"]);
+        const events = collectEvents(session);
+        await session.startTurn("turn one");
+        await waitForEvent(events, "turn_completed");
+        expect(session.getPendingPermissions()).toEqual(outside);
+        await session.respondToPermission(outside[0]!.id, { behavior: "allow" });
+        expect(session.getPendingPermissions()).toEqual([]);
+      } finally {
+        await session.close();
+      }
+    });
+  });
+
+  test.each(["fail", "cancel"] as const)(
+    "settles an outside-turn permission that the manager clears when a turn ends with %s",
+    async (ending) => {
+      await withFakeACPAgent(`outside_${ending}`, async (command, cwd) => {
+        const logger = createTestLogger();
+        const client = new GenericACPAgentClient({
+          logger,
+          command,
+          waitForInitialCommands: false,
+        });
+        const manager = new AgentManager({ clients: { acp: client }, logger });
+        const agent = await manager.createAgent({ provider: "acp", cwd }, undefined, {
+          workspaceId: undefined,
+        });
+        try {
+          await waitForManagedPermission(manager, agent.id);
+          if (ending === "fail") {
+            await expect(manager.runAgent(agent.id, "turn one")).rejects.toThrow(
+              "turn failed with a permission open",
+            );
+          } else {
+            await expect(manager.runAgent(agent.id, "turn one")).resolves.toMatchObject({
+              canceled: true,
+            });
+          }
+          expect(manager.getPendingPermissions(agent.id)).toEqual([]);
+          const result = await manager.runAgent(agent.id, "turn two");
+          expect(result.finalText).toBe(
+            'perm-outside answered: {"outcome":{"outcome":"cancelled"}}',
+          );
+        } finally {
+          await manager.closeAgent(agent.id);
+          await manager.flush();
+        }
+      });
+    },
+  );
 });
 
 function collectEvents(session: AgentSession): AgentStreamEvent[] {
@@ -47,6 +137,10 @@ function collectEvents(session: AgentSession): AgentStreamEvent[] {
   return events;
 }
 
+async function waitForManagedPermission(manager: AgentManager, agentId: string): Promise<void> {
+  await expect.poll(() => manager.getPendingPermissions(agentId).length).toBe(1);
+}
+
 function hasEvent(
   events: AgentStreamEvent[],
   type: AgentStreamEvent["type"],
@@ -77,8 +171,32 @@ function assistantText(events: AgentStreamEvent[]): string {
     .join("");
 }
 
+function permissionRequests(events: AgentStreamEvent[]) {
+  return events.filter((event) => event.type === "permission_requested");
+}
+
+function resolvedEvents(events: AgentStreamEvent[]) {
+  return events.filter((event) => event.type === "permission_resolved");
+}
+
+function pendingToolIds(session: AgentSession) {
+  return session.getPendingPermissions().map((request) => request.metadata?.toolCallId);
+}
+
+async function waitForToolUpdate(events: AgentStreamEvent[]): Promise<void> {
+  await expect.poll(() => assistantText(events)).toBe("tool terminal");
+}
+
 async function withFakeACPAgent(
-  ending: "fail" | "cancel",
+  ending:
+    | "fail"
+    | "cancel"
+    | "end_turn"
+    | "completed"
+    | "failed"
+    | "outside_turn"
+    | "outside_fail"
+    | "outside_cancel",
   run: (command: [string, ...string[]], cwd: string) => Promise<void>,
 ): Promise<void> {
   const testDir = await mkdtemp(path.join(tmpdir(), "paseo-acp-permission-turn-failure-"));
@@ -91,8 +209,7 @@ async function withFakeACPAgent(
   }
 }
 
-// Turn one asks for permission, then fails or is cancelled while the request is
-// still open.
+// Turn one ends while its permission request is still open.
 // Later turns report whether that request was ever answered.
 const fakeACPAgentScript = `
 const readline = require("node:readline");
@@ -101,15 +218,34 @@ const ending = process.argv[2];
 const rl = readline.createInterface({ input: process.stdin });
 let promptCount = 0;
 let permissionAnswer = null;
+let outsidePermissionAnswer = null;
 
 function write(message) {
   process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...message }) + "\\n");
 }
 
+function ask(sessionId, requestId, toolCallId) {
+  const toolCall = { toolCallId, title: "echo hello", kind: "execute", status: "pending" };
+  write({ method: "session/update", params: { sessionId, update: { sessionUpdate: "tool_call", ...toolCall } } });
+  write({
+    id: requestId,
+    method: "session/request_permission",
+    params: {
+      sessionId,
+      toolCall,
+      options: [
+        { optionId: "allow", name: "Allow once", kind: "allow_once" },
+        { optionId: "reject", name: "Reject", kind: "reject_once" },
+      ],
+    },
+  });
+}
+
 rl.on("line", (line) => {
   const message = JSON.parse(line);
-  if (message.method === undefined && message.id === "perm-1") {
-    permissionAnswer = message.result ?? { error: message.error };
+  if (message.method === undefined) {
+    if (message.id === "perm-1") permissionAnswer = message.result ?? { error: message.error };
+    if (message.id === "perm-outside") outsidePermissionAnswer = message.result ?? { error: message.error };
     return;
   }
   if (message.method === "initialize") {
@@ -117,6 +253,7 @@ rl.on("line", (line) => {
     return;
   }
   if (message.method === "session/new") {
+    if (ending.startsWith("outside_")) ask("session-1", "perm-outside", "tool-outside");
     write({ id: message.id, result: { sessionId: "session-1" } });
     return;
   }
@@ -124,35 +261,32 @@ rl.on("line", (line) => {
     const sessionId = message.params.sessionId;
     promptCount += 1;
     if (promptCount === 1) {
-      const toolCall = { toolCallId: "tool-1", title: "echo hello", kind: "execute", status: "pending" };
-      write({ method: "session/update", params: { sessionId, update: { sessionUpdate: "tool_call", ...toolCall } } });
-      write({
-        id: "perm-1",
-        method: "session/request_permission",
-        params: {
-          sessionId,
-          toolCall,
-          options: [
-            { optionId: "allow", name: "Allow once", kind: "allow_once" },
-            { optionId: "reject", name: "Reject", kind: "reject_once" },
-          ],
-        },
-      });
+      ask(sessionId, "perm-1", "tool-1");
+      if (ending === "completed" || ending === "failed") {
+        ask(sessionId, "perm-2", "tool-2");
+        write({ method: "session/update", params: { sessionId, update: { sessionUpdate: "tool_call_update", toolCallId: "tool-1", status: ending } } });
+        write({ method: "session/update", params: { sessionId, update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "tool terminal" } } } });
+        return;
+      }
       setTimeout(() => {
-        if (ending === "cancel") {
+        if (ending === "cancel" || ending === "outside_cancel") {
           write({ id: message.id, result: { stopReason: "cancelled" } });
+        } else if (ending === "end_turn" || ending === "outside_turn") {
+          write({ id: message.id, result: { stopReason: "end_turn" } });
         } else {
           write({ id: message.id, error: { code: -32603, message: "turn failed with a permission open" } });
         }
       }, 50);
       return;
     }
-    const state = permissionAnswer === null ? "unanswered" : "answered: " + JSON.stringify(permissionAnswer);
+    const answer = ending.startsWith("outside_") ? outsidePermissionAnswer : permissionAnswer;
+    const requestId = ending.startsWith("outside_") ? "perm-outside" : "perm-1";
+    const state = answer === null ? "unanswered" : "answered: " + JSON.stringify(answer);
     write({
       method: "session/update",
       params: {
         sessionId,
-        update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "perm-1 " + state } },
+        update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: requestId + " " + state } },
       },
     });
     write({ id: message.id, result: { stopReason: "end_turn" } });
diff --git a/packages/server/src/server/agent/providers/mock-load-test-agent.test.ts b/packages/server/src/server/agent/providers/mock-load-test-agent.test.ts
index 396e7876af..0b08b9694f 100644
--- a/packages/server/src/server/agent/providers/mock-load-test-agent.test.ts
+++ b/packages/server/src/server/agent/providers/mock-load-test-agent.test.ts
@@ -68,7 +68,7 @@ describe("MockLoadTestAgentClient", () => {
       provider: "mock",
       cwd: process.cwd(),
       model: "ten-second-stream",
-      featureValues: { mockPromptRejections: 1 },
+      providerOptions: { mockPromptRejections: 1 },
     });
 
     await expect(session.startTurn("Reject this prompt.")).rejects.toThrow(
@@ -95,7 +95,7 @@ describe("MockLoadTestAgentClient", () => {
       provider: "mock",
       cwd: process.cwd(),
       model: "ten-second-stream",
-      featureValues: {
+      providerOptions: {
         mockStreamingAssistantResponse: response,
         mockStreamingAssistantIntervalMs: 20,
       },
@@ -467,7 +467,7 @@ describe("MockLoadTestAgentClient", () => {
       provider: "mock",
       cwd: process.cwd(),
       model: "e2e-fast-stream",
-      featureValues: { mockAssistantResponses: ["First response", "![Second](second.png)"] },
+      providerOptions: { mockAssistantResponses: ["First response", "![Second](second.png)"] },
     });
     await session.run("Emit a synthetic turn failure.");
     expect((await session.run("First prompt")).finalText).toBe("First response");
diff --git a/packages/server/src/server/agent/providers/mock-load-test-agent.ts b/packages/server/src/server/agent/providers/mock-load-test-agent.ts
index 42abf5e3d7..8b66dceb8d 100644
--- a/packages/server/src/server/agent/providers/mock-load-test-agent.ts
+++ b/packages/server/src/server/agent/providers/mock-load-test-agent.ts
@@ -3,7 +3,7 @@ import type { Logger } from "pino";
 import type {
   AgentCapabilityFlags,
   AgentClient,
-  AgentFeature,
+  AgentOptionControl,
   AgentLaunchContext,
   AgentMode,
   AgentModelDefinition,
@@ -789,7 +789,7 @@ function getConfiguredAssistantResponses(value: unknown): string[] {
 export class MockLoadTestAgentSession implements AgentSession {
   readonly provider: AgentProvider = MOCK_LOAD_TEST_PROVIDER_ID;
   readonly capabilities = CAPABILITIES;
-  readonly features: AgentFeature[] = [];
+  readonly controls: AgentOptionControl[] = [];
   readonly id: string;
   private readonly usageSessionKey = randomUUID();
 
@@ -814,18 +814,18 @@ export class MockLoadTestAgentSession implements AgentSession {
     this.modeId = options.config.modeId ?? MOCK_LOAD_TEST_MODE_ID;
     this.modelId = options.config.model ?? MOCK_LOAD_TEST_DEFAULT_MODEL_ID;
     this.assistantResponse =
-      typeof options.config.featureValues?.mockAssistantResponse === "string"
-        ? options.config.featureValues.mockAssistantResponse
+      typeof options.config.providerOptions?.mockAssistantResponse === "string"
+        ? options.config.providerOptions.mockAssistantResponse
         : null;
     this.assistantResponses = getConfiguredAssistantResponses(
-      options.config.featureValues?.mockAssistantResponses,
+      options.config.providerOptions?.mockAssistantResponses,
     );
     this.streamingAssistantResponse =
-      typeof options.config.featureValues?.mockStreamingAssistantResponse === "string"
-        ? options.config.featureValues.mockStreamingAssistantResponse
+      typeof options.config.providerOptions?.mockStreamingAssistantResponse === "string"
+        ? options.config.providerOptions.mockStreamingAssistantResponse
         : null;
     const requestedStreamingInterval =
-      options.config.featureValues?.mockStreamingAssistantIntervalMs;
+      options.config.providerOptions?.mockStreamingAssistantIntervalMs;
     this.streamingAssistantIntervalMs =
       typeof requestedStreamingInterval === "number" &&
       Number.isFinite(requestedStreamingInterval) &&
@@ -833,10 +833,10 @@ export class MockLoadTestAgentSession implements AgentSession {
         ? Math.min(requestedStreamingInterval, 1_000)
         : MOCK_LOAD_TEST_INTERVAL_MS;
     this.rewindError =
-      typeof options.config.featureValues?.mockRewindError === "string"
-        ? options.config.featureValues.mockRewindError
+      typeof options.config.providerOptions?.mockRewindError === "string"
+        ? options.config.providerOptions.mockRewindError
         : null;
-    const requestedPromptRejections = options.config.featureValues?.mockPromptRejections;
+    const requestedPromptRejections = options.config.providerOptions?.mockPromptRejections;
     this.remainingPromptRejections =
       typeof requestedPromptRejections === "number" &&
       Number.isSafeInteger(requestedPromptRejections) &&
@@ -844,7 +844,7 @@ export class MockLoadTestAgentSession implements AgentSession {
         ? requestedPromptRejections
         : 0;
     this.remainingSteerFailures = getPositiveFeatureInteger(
-      options.config.featureValues?.mockSteerAmbiguousFailures,
+      options.config.providerOptions?.mockSteerAmbiguousFailures,
     );
   }
 
diff --git a/packages/server/src/server/agent/providers/omp/agent.test.ts b/packages/server/src/server/agent/providers/omp/agent.test.ts
index 15392fc07c..832bd208a8 100644
--- a/packages/server/src/server/agent/providers/omp/agent.test.ts
+++ b/packages/server/src/server/agent/providers/omp/agent.test.ts
@@ -613,9 +613,9 @@ describe("OMP agent client and session", () => {
     expect(omp.requireSession().describePersistence()?.metadata?.model).toBe(
       "openrouter/google/gemini-3.8-flash",
     );
-    expect(omp.requireSession().features).toEqual([
+    expect(omp.requireSession().controls).toEqual([
       expect.objectContaining({
-        value: true,
+        key: "fast_mode",
         description: expect.stringMatching(/does not apply/i),
       }),
     ]);
@@ -626,18 +626,90 @@ describe("OMP agent client and session", () => {
     await omp.start({ model: "openrouter/google/gemini-3.8-flash" });
     const session = omp.requireSession();
     omp.runtime().fastModeResult = { enabled: true, active: false };
-    await session.setFeature?.("fast_mode", true);
+    await session.applyOptions?.({ fast_mode: true });
     expect(omp.runtime().setFastModeRequests).toEqual([true]);
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
       expect.objectContaining({
-        id: "fast_mode",
-        value: true,
+        key: "fast_mode",
         description: expect.stringMatching(/does not apply to this model/i),
         tooltip: expect.stringMatching(/does not apply to this model/i),
       }),
     ]);
   });
 
+  test("applies only the options it is given and leaves the runtime alone otherwise", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+
+    omp.runtime().fastModeResult = { enabled: true, active: true };
+    await session.applyOptions?.({ fast_mode: true });
+    expect(omp.runtime().setFastModeRequests).toEqual([true]);
+
+    // A patch without the key leaves the runtime alone.
+    await session.applyOptions?.({});
+    expect(omp.runtime().setFastModeRequests).toEqual([true]);
+  });
+
+  test("rejects a live option the creation schema would reject, and sends nothing", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+
+    await expect(session.applyOptions?.({ sandbox_mode: "read-only" })).rejects.toThrow(/omp/i);
+    await expect(session.applyOptions?.({ fast_mode: "yes" })).rejects.toThrow(/omp/i);
+    expect(omp.runtime().setFastModeRequests).toEqual([]);
+  });
+
+  test("a removal turns Fast off, and a Fast the runtime keeps is returned", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    omp.runtime().fastModeResult = { enabled: true, active: true };
+    await session.applyOptions?.({ fast_mode: true });
+
+    omp.runtime().fastModeResult = { enabled: false, active: false };
+    await expect(session.applyOptions?.({ fast_mode: null })).resolves.toEqual({});
+    expect(omp.runtime().setFastModeRequests).toEqual([true, false]);
+
+    omp.runtime().fastModeResult = { enabled: false, active: false };
+    await expect(session.applyOptions?.({ fast_mode: true })).resolves.toEqual({
+      fast_mode: false,
+    });
+    expect(omp.eventTypes()).not.toContain("options_changed");
+  });
+
+  test("a session opened without the Fast it was given says so in its open patch", async () => {
+    const omp = new OmpHarness();
+    // The fake runtime answers the open-time Fast request with Fast off.
+    await omp.start({ providerOptions: { fast_mode: true } });
+
+    expect(omp.requireSession().openOptionsPatch).toEqual({ fast_mode: false });
+    expect(omp.eventTypes()).not.toContain("options_changed");
+  });
+
+  test("reports a Fast change the runtime made on its own", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    omp.runtime().fastModeResult = { enabled: true, active: true };
+    await session.applyOptions?.({ fast_mode: true });
+    expect(omp.eventTypes()).not.toContain("options_changed");
+
+    omp.runtime().setModelResult = { provider: "openrouter", id: "other/model" };
+    omp.runtime().queueStateReports([
+      {
+        ...omp.runtime().state,
+        model: omp.runtime().setModelResult,
+        fastModeEnabled: false,
+        fastModeActive: false,
+      },
+    ]);
+    await session.setModel?.("openrouter/other/model");
+
+    expect(omp.eventTypes().filter((type) => type === "options_changed")).toHaveLength(1);
+  });
+
   test("shows Fast only when OMP reports its state fields", async () => {
     const omp = new OmpHarness();
     await omp.start();
@@ -649,11 +721,11 @@ describe("OMP agent client and session", () => {
     } = omp.runtime().state;
     omp.runtime().state = olderState;
     await session.getRuntimeInfo();
-    expect(session.features).toEqual([]);
-    await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(/unavailable/i);
+    expect(session.controls).toEqual([]);
+    await expect(session.applyOptions?.({ fast_mode: true })).rejects.toThrow(/unavailable/i);
     omp.runtime().state = { ...olderState, fastModeEnabled: false, fastModeActive: false };
     await session.getRuntimeInfo();
-    expect(session.features).toHaveLength(1);
+    expect(session.controls).toHaveLength(1);
   });
 
   test("switching model refreshes whether Fast applies", async () => {
@@ -661,8 +733,7 @@ describe("OMP agent client and session", () => {
     await omp.start({ model: "openrouter/google/gemini-3.8-flash" });
     const session = omp.requireSession();
     omp.runtime().fastModeResult = { enabled: true, active: true };
-    await session.setFeature?.("fast_mode", true);
-    expect(session.features).toEqual([expect.objectContaining({ value: true })]);
+    await session.applyOptions?.({ fast_mode: true });
 
     omp.runtime().setModelResult = { provider: "openrouter", id: "other/model" };
     omp.runtime().queueStateReports([
@@ -674,24 +745,79 @@ describe("OMP agent client and session", () => {
       },
     ]);
     await session.setModel?.("openrouter/other/model");
-    expect(session.features).toEqual([
+    expect(session.controls).toEqual([
       expect.objectContaining({
-        value: true,
+        key: "fast_mode",
         description: expect.stringMatching(/does not apply/i),
       }),
     ]);
   });
 
+  test("a replacement runtime starts with the Fast the session has now, not the one it opened with", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ modeId: "full", providerOptions: { fast_mode: true } });
+    const session = omp.requireSession();
+    omp.runtime().fastModeResult = { enabled: false, active: false };
+    await session.applyOptions?.({ fast_mode: false });
+
+    await omp.setMode("ask");
+
+    // The approval-mode restart starts a second runtime; it must not turn Fast back on.
+    expect(omp.runtimeLaunches()).toHaveLength(2);
+    expect(omp.runtime().setFastModeRequests).toEqual([]);
+  });
+
+  test("a replacement runtime starts with the Fast the session opened with, not the one it was asked for", async () => {
+    const omp = new OmpHarness();
+    // The fake runtime answers the open-time Fast request with Fast off.
+    await omp.start({ modeId: "full", providerOptions: { fast_mode: true } });
+    expect(omp.requireSession().openOptionsPatch).toEqual({ fast_mode: false });
+    omp.runtime().fastModeResult = { enabled: true, active: true };
+
+    await omp.setMode("ask");
+
+    expect(omp.runtimeLaunches()).toHaveLength(2);
+    expect(omp.runtime().setFastModeRequests).toEqual([]);
+  });
+
+  test("a replacement runtime that refuses the Fast the session had publishes what it accepted", async () => {
+    const omp = new OmpHarness();
+    omp.acceptFastOnNextRuntime();
+    await omp.start({ modeId: "full", providerOptions: { fast_mode: true } });
+    expect(omp.requireSession().openOptionsPatch).toEqual({});
+
+    // The approval-mode restart starts a second runtime, which refuses Fast.
+    await omp.setMode("ask");
+
+    expect(omp.optionsChanges()).toEqual([{ fast_mode: false }]);
+  });
+
+  test("a Fast change the runtime reports when a turn completes is published", async () => {
+    const omp = new OmpHarness();
+    omp.acceptFastOnNextRuntime();
+    await omp.start({ modeId: "full", providerOptions: { fast_mode: true } });
+    omp.runtime().state = { ...omp.runtime().state, fastModeEnabled: false, fastModeActive: false };
+
+    const { completion } = await omp.startPromptUntilProviderIdle("hello", "done", {
+      isStreaming: false,
+      isCompacting: false,
+    });
+    await completion;
+    await omp.requireSession().getRuntimeInfo();
+
+    expect(omp.optionsChanges()).toEqual([{ fast_mode: false }]);
+  });
+
   test("restores Fast from the initial OMP state on create and resume", async () => {
     const created = new OmpHarness();
-    await created.start({ featureValues: { fast_mode: true } });
+    await created.start({ providerOptions: { fast_mode: true } });
     expect(created.runtime().setFastModeRequests).toEqual([true]);
     expect(created.runtime().getStateRequestCount).toBe(1);
 
     const resumed = new OmpHarness();
     await resumed.resume(
       { user: { id: "user-1", text: "hello" }, assistant: { id: "assistant-1", text: "hi" } },
-      { featureValues: { fast_mode: true } },
+      { providerOptions: { fast_mode: true } },
     );
     expect(resumed.runtime().setFastModeRequests).toEqual([true]);
     expect(resumed.runtime().getStateRequestCount).toBe(1);
diff --git a/packages/server/src/server/agent/providers/omp/agent.ts b/packages/server/src/server/agent/providers/omp/agent.ts
index 333b966b58..3139d279fc 100644
--- a/packages/server/src/server/agent/providers/omp/agent.ts
+++ b/packages/server/src/server/agent/providers/omp/agent.ts
@@ -1,3 +1,4 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { mapCustomMessageToToolCall } from "../custom-message.js";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -9,7 +10,8 @@ import stripAnsi from "strip-ansi";
 import {
   type AgentCapabilityFlags,
   type AgentClient,
-  type AgentFeature,
+  type AgentDraftControls,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -68,9 +70,12 @@ import {
   resolveOmpLaunchMode,
   resolveOmpProviderOptions,
   OMP_MODES,
+  OmpProviderOptionsSchema,
   type OmpRuntimeOptions,
 } from "./provider-config.js";
 export { formatOmpVersionSupport, resolveOmpDiagnosticPaths } from "./provider-config.js";
+import { applyProviderOptionsPatch } from "../../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../../provider-options.js";
 import { OmpSubagentCardTracker } from "./subagent-card-tracker.js";
 import { ompSkillPromptUserText, shouldDisplayOmpCustomMessage } from "./custom-message.js";
 import { getUserMessageText } from "./message-history.js";
@@ -752,6 +757,10 @@ export class OmpAgentSession implements AgentSession {
     this.restartRuntime = options.restartRuntime;
     this.config = options.config;
     this.state = options.initialState;
+    this.openOptionsPatch = this.fastModeDifference(options.config.providerOptions?.fast_mode);
+    // A replacement runtime starts from the Fast this one opened with, not the one it was asked for.
+    if (typeof this.openOptionsPatch.fast_mode === "boolean")
+      this.rememberFastMode(this.openOptionsPatch.fast_mode);
     this.currentModeId = options.currentModeId ?? null;
     this.logger = options.logger;
     this.live = options.live ?? true;
@@ -806,15 +815,14 @@ export class OmpAgentSession implements AgentSession {
     return this.state.sessionId;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
     if (!hasOmpFastMode(this.state)) return [];
     return [
       {
         type: "toggle",
-        id: "fast_mode",
+        key: "fast_mode",
         label: "Fast",
         icon: "zap",
-        value: this.state.fastModeEnabled === true,
         ...(this.state.fastModeEnabled && !this.state.fastModeActive
           ? { description: OMP_FAST_INACTIVE_MESSAGE, tooltip: OMP_FAST_INACTIVE_MESSAGE }
           : {}),
@@ -822,19 +830,50 @@ export class OmpAgentSession implements AgentSession {
     ];
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    if (featureId !== "fast_mode") throw new Error(`Unknown OMP feature: ${featureId}`);
-    if (typeof value !== "boolean") throw new Error("OMP fast mode requires a boolean");
+  async applyOptions(options: ProviderOptions): Promise<Record<string, unknown>> {
+    assertChangesAreLive({
+      provider: "omp",
+      patch: options,
+      current: this.config.providerOptions,
+      live: ["fast_mode"],
+    });
+    const next = validateProviderOptions(
+      "omp",
+      OmpProviderOptionsSchema,
+      applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+    );
+    if (options.fast_mode === undefined) return {};
+    const requested = next?.fast_mode ?? false;
     if (!hasOmpFastMode(this.state)) throw new Error("OMP fast mode is unavailable");
-    const result = await this.runtimeSession.setFastMode(value);
-    this.state = {
-      ...this.state,
-      fastModeEnabled: result.enabled,
-      fastModeActive: result.active,
-    };
-    this.config.featureValues = { ...this.config.featureValues, fast_mode: result.enabled };
+    if (requested !== this.state.fastModeEnabled) {
+      const result = await this.runtimeSession.setFastMode(requested);
+      this.state = {
+        ...this.state,
+        fastModeEnabled: result.enabled,
+        fastModeActive: result.active,
+      };
+    }
+    if (typeof this.state.fastModeEnabled === "boolean") {
+      this.rememberFastMode(this.state.fastModeEnabled);
+    }
+    return this.fastModeDifference(requested);
   }
 
+  /** A replacement runtime starts from the Fast the session has now, not the one it opened with. */
+  private rememberFastMode(enabled: boolean): void {
+    this.config.providerOptions = { ...this.config.providerOptions, fast_mode: enabled };
+  }
+
+  /** The option patch when the runtime's fast mode is not what `given` stands for; unset is off. */
+  private fastModeDifference(given: unknown): Record<string, unknown> {
+    if (!hasOmpFastMode(this.state)) return {};
+    const enabled = this.state.fastModeEnabled === true;
+    return (given ?? false) === enabled ? {} : { fast_mode: enabled };
+  }
+
+  /** How the opened session differs from the options it was given. */
+  readonly openOptionsPatch: Record<string, unknown>;
+
   async run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult> {
     return runProviderTurn({
       prompt,
@@ -1074,7 +1113,7 @@ export class OmpAgentSession implements AgentSession {
         this.pendingPromptResults.clear();
         this.runtimeSession = next;
         this.hostTools = restarted.hostTools;
-        this.state = state;
+        this.installState(state);
         this.currentModeId = modeId;
         this.config.modeId = modeId;
         this.runtimeDead = false;
@@ -1308,10 +1347,10 @@ export class OmpAgentSession implements AgentSession {
     return null;
   }
 
-  async setModel(modelId: string | null): Promise<void> {
+  async setModel(modelId: string | null): Promise<{ model: string | null }> {
     const parsedReference = parseModelReference(modelId);
     if (!parsedReference) {
-      return;
+      return { model: modelToId(this.state.model) };
     }
     if (!parsedReference.provider) {
       throw new Error(`OMP model id must include a provider: ${modelId}`);
@@ -1320,6 +1359,7 @@ export class OmpAgentSession implements AgentSession {
     const model = await this.runtimeSession.setModel(parsedReference.provider, parsedReference.id);
     this.config.model = `${model.provider}/${model.id}`;
     await this.refreshState();
+    return { model: modelToId(this.state.model) };
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void> {
@@ -2216,7 +2256,7 @@ export class OmpAgentSession implements AgentSession {
       }
       try {
         const state = await this.runtimeSession.getState();
-        this.state = state;
+        this.installState(state);
         if (this.closed || !this.activeTurnStarted || this.currentTurnIdForEvent() !== turnId) {
           // An interrupt settled this turn while the state check was in flight.
           return;
@@ -2233,7 +2273,22 @@ export class OmpAgentSession implements AgentSession {
   }
 
   private async refreshState(): Promise<void> {
-    this.state = await this.runtimeSession.getState();
+    this.installState(await this.runtimeSession.getState());
+  }
+
+  // The runtime owns Fast: whatever it reports is what the session now runs with, so every state
+  // read from the runtime is installed here and a difference is published once.
+  private installState(state: OmpSessionState): void {
+    const before = this.state.fastModeEnabled;
+    this.state = state;
+    if (this.state.fastModeEnabled !== before && typeof this.state.fastModeEnabled === "boolean") {
+      this.rememberFastMode(this.state.fastModeEnabled);
+      this.emit({
+        type: "options_changed",
+        provider: this.provider,
+        patch: { fast_mode: this.state.fastModeEnabled },
+      });
+    }
   }
 
   private async refreshAfterTurn(finalUsage: Promise<void>): Promise<void> {
@@ -2301,7 +2356,7 @@ export class OmpAgentClient implements AgentClient {
     config: AgentSessionConfig,
     state: OmpSessionState,
   ): Promise<OmpSessionState> {
-    const value = config.featureValues?.fast_mode;
+    const value = config.providerOptions?.fast_mode;
     if (typeof value !== "boolean" || !hasOmpFastMode(state) || value === state.fastModeEnabled)
       return state;
     const result = await runtimeSession.setFastMode(value);
@@ -2536,8 +2591,8 @@ export class OmpAgentClient implements AgentClient {
     }
   }
 
-  async listFeatures(_config: AgentSessionConfig): Promise<AgentFeature[]> {
-    return [];
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    return { controls: [], options: config.providerOptions ?? {} };
   }
 
   async listImportableSessions(
diff --git a/packages/server/src/server/agent/providers/omp/provider-config.ts b/packages/server/src/server/agent/providers/omp/provider-config.ts
index 0bcd369a1c..85da5068e3 100644
--- a/packages/server/src/server/agent/providers/omp/provider-config.ts
+++ b/packages/server/src/server/agent/providers/omp/provider-config.ts
@@ -15,6 +15,8 @@ export { OMP_MODES };
 
 export const OmpProviderOptionsSchema = z
   .object({
+    // Composer control, not a runtime option: the session reads it and asks OMP to match.
+    fast_mode: z.boolean().optional(),
     sessionDir: z.string().min(1).optional(),
     rpcTimeoutMs: z.number().int().positive().optional(),
     smolModel: z.string().min(1).optional(),
diff --git a/packages/server/src/server/agent/providers/omp/test-utils/omp-harness.ts b/packages/server/src/server/agent/providers/omp/test-utils/omp-harness.ts
index 8be53f1742..8aeaa50312 100644
--- a/packages/server/src/server/agent/providers/omp/test-utils/omp-harness.ts
+++ b/packages/server/src/server/agent/providers/omp/test-utils/omp-harness.ts
@@ -467,6 +467,16 @@ export class OmpHarness {
     return this.events.map((event) => event.type);
   }
 
+  acceptFastOnNextRuntime(): void {
+    this.omp.queueSessionSetup((runtime) => {
+      runtime.fastModeResult = { enabled: true, active: true };
+    });
+  }
+
+  optionsChanges(): Record<string, unknown>[] {
+    return this.events.flatMap((event) => (event.type === "options_changed" ? [event.patch] : []));
+  }
+
   async history(): Promise<AgentTimelineItem[]> {
     const items: AgentTimelineItem[] = [];
     for await (const event of this.requireSession().streamHistory()) {
diff --git a/packages/server/src/server/agent/providers/opencode-agent.full-access.test.ts b/packages/server/src/server/agent/providers/opencode-agent.full-access.test.ts
index d1a5de6f8b..e785695b77 100644
--- a/packages/server/src/server/agent/providers/opencode-agent.full-access.test.ts
+++ b/packages/server/src/server/agent/providers/opencode-agent.full-access.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../test-utils/test-logger.js";
 import type { AgentStreamEvent } from "../agent-sdk-types.js";
@@ -108,33 +108,25 @@ describe("OpenCode auto_accept feature", () => {
     expect(modes).toEqual([]);
   });
 
-  test("lists auto accept as a provider feature", async () => {
+  test("lists auto accept as a provider control", async () => {
     const { runtime } = mockOpenCodeClient();
 
     const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
       serverManager: runtime,
       createClient: runtime.createClient,
     });
-    const enabledFeatures = await client.listFeatures({
-      provider: "opencode",
-      cwd: "/tmp/project",
-      featureValues: { auto_accept: true },
-    });
-    const legacyFeatures = await client.listFeatures({
-      provider: "opencode",
-      cwd: "/tmp/project",
-      modeId: "full-access",
-    });
-
-    expect(enabledFeatures).toEqual([
-      expect.objectContaining({
-        type: "toggle",
-        id: "auto_accept",
-        label: "Auto Accept",
-        value: true,
+    await expect(
+      client.listControls({
+        provider: "opencode",
+        cwd: "/tmp/project",
+        providerOptions: { auto_accept: true },
       }),
-    ]);
-    expect(legacyFeatures).toEqual([expect.objectContaining({ id: "auto_accept", value: true })]);
+    ).resolves.toEqual({
+      controls: [
+        expect.objectContaining({ type: "toggle", key: "auto_accept", label: "Auto Accept" }),
+      ],
+      options: { auto_accept: true },
+    });
   });
 
   test("keeps legacy full-access as an alias for build plus auto accept", async () => {
@@ -151,7 +143,7 @@ describe("OpenCode auto_accept feature", () => {
     });
 
     expect(await session.getCurrentMode()).toBe("build");
-    expect(session.features).toEqual([expect.objectContaining({ id: "auto_accept", value: true })]);
+    expect(session.controls).toEqual([expect.objectContaining({ key: "auto_accept" })]);
 
     await session.run("Implement the change");
 
@@ -163,6 +155,48 @@ describe("OpenCode auto_accept feature", () => {
     await session.close();
   });
 
+  test("reports the Auto Accept that legacy full-access turned on, when it opens or resumes", async () => {
+    const { openCodeClient, runtime } = mockOpenCodeClient();
+    runtime.enqueueClient(openCodeClient);
+    const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
+      serverManager: runtime,
+      createClient: runtime.createClient,
+    });
+
+    const created = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      modeId: "full-access",
+    });
+    expect(created.openOptionsPatch).toEqual({ auto_accept: true });
+    await created.close();
+
+    const resumed = await client.resumeSession(
+      { provider: "opencode", sessionId: "session-1" },
+      { cwd: "/tmp/project", modeId: "full-access" },
+    );
+    expect(resumed.openOptionsPatch).toEqual({ auto_accept: true });
+    await resumed.close();
+  });
+
+  test("reports nothing when Auto Accept was already on", async () => {
+    const { runtime } = mockOpenCodeClient();
+    const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
+      serverManager: runtime,
+      createClient: runtime.createClient,
+    });
+
+    const session = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      modeId: "full-access",
+      providerOptions: { auto_accept: true },
+    });
+
+    expect(session.openOptionsPatch).toEqual({});
+    await session.close();
+  });
+
   test("resolves legacy full-access for provider-driven child creation", () => {
     const client = new OpenCodeAgentClient(createTestLogger());
 
@@ -170,7 +204,7 @@ describe("OpenCode auto_accept feature", () => {
       client.resolveCreateConfig({
         provider: "opencode",
         requestedMode: "full-access",
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: null,
         unattended: false,
         availableModes: [
@@ -178,7 +212,7 @@ describe("OpenCode auto_accept feature", () => {
           { id: "plan", label: "Plan" },
         ],
       }),
-    ).toEqual({ modeId: "build", featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: "build", providerOptions: { auto_accept: true } });
   });
 
   test("inherits unattended callers as auto accept with OpenCode's default agent", () => {
@@ -191,7 +225,7 @@ describe("OpenCode auto_accept feature", () => {
       client.resolveCreateConfig({
         provider: "opencode",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: {
           provider: "claude",
           modeId: "bypassPermissions",
@@ -203,7 +237,7 @@ describe("OpenCode auto_accept feature", () => {
           { id: "plan", label: "Plan" },
         ],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: true } });
   });
 
   test("defaults unattended creation without a parent to auto accept with OpenCode's default agent", () => {
@@ -213,7 +247,7 @@ describe("OpenCode auto_accept feature", () => {
       client.resolveCreateConfig({
         provider: "opencode",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: null,
         unattended: true,
         availableModes: [
@@ -221,7 +255,7 @@ describe("OpenCode auto_accept feature", () => {
           { id: "plan", label: "Plan" },
         ],
       }),
-    ).toEqual({ modeId: undefined, featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: undefined, providerOptions: { auto_accept: true } });
   });
 
   test("preserves the selected OpenCode agent when inheriting auto accept from an OpenCode parent", () => {
@@ -231,7 +265,7 @@ describe("OpenCode auto_accept feature", () => {
       client.resolveCreateConfig({
         provider: "opencode",
         requestedMode: undefined,
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: {
           provider: "opencode",
           modeId: "paseo-custom",
@@ -244,7 +278,7 @@ describe("OpenCode auto_accept feature", () => {
           { id: "paseo-custom", label: "Paseo Custom" },
         ],
       }),
-    ).toEqual({ modeId: "paseo-custom", featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: "paseo-custom", providerOptions: { auto_accept: true } });
   });
 
   test("inherits auto accept from an OpenCode parent when the child chooses a mode", () => {
@@ -254,7 +288,7 @@ describe("OpenCode auto_accept feature", () => {
       client.resolveCreateConfig({
         provider: "opencode",
         requestedMode: "base",
-        featureValues: undefined,
+        providerOptions: undefined,
         parent: {
           provider: "opencode",
           modeId: "orchestrator",
@@ -267,7 +301,7 @@ describe("OpenCode auto_accept feature", () => {
           { id: "orchestrator", label: "Orchestrator" },
         ],
       }),
-    ).toEqual({ modeId: "base", featureValues: { auto_accept: true } });
+    ).toEqual({ modeId: "base", providerOptions: { auto_accept: true } });
   });
 
   test("auto-approves tool permissions when auto accept is enabled", async () => {
@@ -283,7 +317,7 @@ describe("OpenCode auto_accept feature", () => {
     const session = await client.createSession({
       provider: "opencode",
       cwd: "/tmp/project",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     session.subscribe((event) => receivedEvents.push(event));
 
@@ -301,6 +335,72 @@ describe("OpenCode auto_accept feature", () => {
     await session.close();
   });
 
+  test("rejects a live auto_accept the creation schema would reject, and keeps approving", async () => {
+    const { openCodeClient, runtime } = mockOpenCodeClient({
+      events: [toolPermissionEvent(), idleEvent()],
+    });
+    const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
+      serverManager: runtime,
+      createClient: runtime.createClient,
+    });
+    const session = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      providerOptions: { auto_accept: true },
+    });
+
+    await expect(session.applyOptions?.({ auto_accept: "yes" })).rejects.toThrow(/auto_accept/);
+    await session.run("Run verification");
+
+    expect(openCodeClient.calls.permissionReply).toHaveLength(1);
+    await session.close();
+  });
+
+  test("rejects a live permission change the running session cannot apply", async () => {
+    const { runtime } = mockOpenCodeClient({ events: [idleEvent()] });
+    const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
+      serverManager: runtime,
+      createClient: runtime.createClient,
+    });
+    const session = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      providerOptions: { permission: "allow" },
+    });
+
+    await expect(session.applyOptions?.({ permission: "deny" })).rejects.toThrow(
+      /permission.*cannot change on a running session/,
+    );
+    await expect(
+      session.applyOptions?.({ permission: "allow", auto_accept: true }),
+    ).resolves.toBeUndefined();
+    await session.close();
+  });
+
+  test("stops auto-approving once auto_accept is removed", async () => {
+    const { openCodeClient, runtime } = mockOpenCodeClient({
+      events: [toolPermissionEvent(), idleEvent()],
+    });
+
+    const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
+      serverManager: runtime,
+      createClient: runtime.createClient,
+    });
+    const session = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      providerOptions: { auto_accept: true },
+    });
+
+    await session.applyOptions?.({ auto_accept: null });
+    await session.startTurn("Run verification");
+    await vi.waitFor(() => expect(session.getPendingPermissions()).toHaveLength(1));
+
+    expect(openCodeClient.calls.permissionReply).toHaveLength(0);
+
+    await session.close();
+  });
+
   test("keeps questions separate from auto accept tool approval", async () => {
     const { openCodeClient, runtime } = mockOpenCodeClient({
       events: [questionEvent(), idleEvent()],
@@ -314,7 +414,7 @@ describe("OpenCode auto_accept feature", () => {
     const session = await client.createSession({
       provider: "opencode",
       cwd: "/tmp/project",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     session.subscribe((event) => receivedEvents.push(event));
 
diff --git a/packages/server/src/server/agent/providers/opencode-agent.test.ts b/packages/server/src/server/agent/providers/opencode-agent.test.ts
index 8beed24be0..8b8b0d491d 100644
--- a/packages/server/src/server/agent/providers/opencode-agent.test.ts
+++ b/packages/server/src/server/agent/providers/opencode-agent.test.ts
@@ -32,6 +32,16 @@ import type {
 const EXPECTED_STARTUP_BUDGET_MS = 30_000;
 const EXPECTED_EVENT_READINESS_BUDGET_MS = 45_000;
 
+// Keep event correlation and turn ordering assertions exact while accepting a fresh namespace.
+function turnIdAt(events: AgentStreamEvent[], ordinal: number): string {
+  const started = events.find((event) => event.type === "turn_started");
+  if (!started || started.type !== "turn_started" || typeof started.turnId !== "string") {
+    throw new Error("Expected a turn_started event with a turn ID");
+  }
+  const namespace = started.turnId.slice(0, started.turnId.lastIndexOf("-"));
+  return `${namespace}-${ordinal}`;
+}
+
 function tmpCwd(): string {
   const dir = mkdtempSync(path.join(os.tmpdir(), "opencode-agent-test-"));
   try {
@@ -757,6 +767,19 @@ describe("OpenCodeAgentClient adapter smoke tests", () => {
     }
   });
 
+  test("keeps turn identities distinct for the same persisted session", async () => {
+    const first = await createParentSession("ses_persisted");
+    const firstTurn = await first.parent.startTurn("first");
+    await first.parent.close();
+    const resumed = await createParentSession("ses_persisted");
+    try {
+      const nextTurn = await resumed.parent.startTurn("second");
+      expect(nextTurn.turnId).not.toBe(firstTurn.turnId);
+    } finally {
+      await resumed.parent.close();
+    }
+  });
+
   test.each([
     { saved: "default", variant: undefined },
     { saved: "high", variant: "high" },
@@ -1638,10 +1661,10 @@ describe("OpenCode adapter startTurn error handling", () => {
       item: { type: "user_message", clientMessageId: "client-message-1" },
     });
     expect(turn.events.map((event) => ("turnId" in event ? event.turnId : undefined))).toEqual([
-      "opencode-turn-0",
-      "opencode-turn-0",
-      "opencode-turn-0",
-      "opencode-turn-0",
+      turnIdAt(turn.events, 0),
+      turnIdAt(turn.events, 0),
+      turnIdAt(turn.events, 0),
+      turnIdAt(turn.events, 0),
     ]);
   });
 
@@ -1833,7 +1856,7 @@ describe("OpenCode adapter startTurn error handling", () => {
           type: "error",
           message: "Provider retry (attempt 1): model does not exist",
         },
-        turnId: "opencode-turn-0",
+        turnId: turnIdAt(events, 0),
       });
       expect(events.some((event) => event.type === "turn_failed")).toBe(false);
       await session.close();
@@ -2641,11 +2664,11 @@ describe("OpenCode adapter startTurn error handling", () => {
       expect(
         turnEventSignatures(events.filter((event) => event.type !== "provider_subagent")),
       ).toEqual([
-        ["turn_started", "opencode-turn-0"],
-        ["turn_canceled", "opencode-turn-0"],
-        ["turn_started", "opencode-turn-1"],
-        ["timeline", "opencode-turn-1"],
-        ["turn_completed", "opencode-turn-1"],
+        ["turn_started", turnIdAt(events, 0)],
+        ["turn_canceled", turnIdAt(events, 0)],
+        ["turn_started", turnIdAt(events, 1)],
+        ["timeline", turnIdAt(events, 1)],
+        ["turn_completed", turnIdAt(events, 1)],
       ]);
     } finally {
       settleRetry.resolve();
@@ -2706,7 +2729,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         expect(events).toContainEqual(
           expect.objectContaining({
             type: "timeline",
-            turnId: "opencode-turn-1",
+            turnId: turnIdAt(events, 1),
             item: expect.objectContaining({ text: "Wake output streams live." }),
           }),
         ),
@@ -2726,11 +2749,11 @@ describe("OpenCode adapter startTurn error handling", () => {
       });
       await vi.waitFor(() =>
         expect(events).toContainEqual(
-          expect.objectContaining({ type: "turn_completed", turnId: "opencode-turn-1" }),
+          expect.objectContaining({ type: "turn_completed", turnId: turnIdAt(events, 1) }),
         ),
       );
       await expect(session.startTurn("after the wake")).resolves.toEqual({
-        turnId: "opencode-turn-2",
+        turnId: turnIdAt(events, 2),
       });
     } finally {
       settleAbort.resolve();
@@ -2843,13 +2866,13 @@ describe("OpenCode adapter startTurn error handling", () => {
       expect(events).toContainEqual({
         type: "turn_started",
         provider: "opencode",
-        turnId: "opencode-turn-1",
+        turnId: turnIdAt(events, 1),
       });
       await vi.waitFor(() =>
         expect(events).toContainEqual({
           type: "turn_completed",
           provider: "opencode",
-          turnId: "opencode-turn-1",
+          turnId: turnIdAt(events, 1),
           usage: expect.objectContaining({
             inputTokens: 7,
             outputTokens: 3,
@@ -2858,7 +2881,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         }),
       );
       const autonomousCompletion = events.find(
-        (event) => event.type === "turn_completed" && event.turnId === "opencode-turn-1",
+        (event) => event.type === "turn_completed" && event.turnId === turnIdAt(events, 1),
       );
       expect(autonomousCompletion?.type).toBe("turn_completed");
       if (autonomousCompletion?.type === "turn_completed") {
@@ -2867,7 +2890,7 @@ describe("OpenCode adapter startTurn error handling", () => {
       expect(events).toContainEqual(
         expect.objectContaining({
           type: "timeline",
-          turnId: "opencode-turn-1",
+          turnId: turnIdAt(events, 1),
           item: expect.objectContaining({
             type: "assistant_message",
             text: "Autonomous wake completed.",
@@ -2875,7 +2898,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         }),
       );
       await expect(session.startTurn("after autonomous wake")).resolves.toEqual({
-        turnId: "opencode-turn-2",
+        turnId: turnIdAt(events, 2),
       });
     } finally {
       settleAbort.resolve();
@@ -2954,7 +2977,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         type: "turn_canceled",
         provider: "opencode",
         reason: "interrupted",
-        turnId: "opencode-turn-0",
+        turnId: turnIdAt(events, 0),
       });
 
       openCode.emitEvent({
@@ -2962,7 +2985,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         properties: { sessionID: "ses_retried_stop" },
       });
       await expect(session.startTurn("replacement")).resolves.toEqual({
-        turnId: "opencode-turn-1",
+        turnId: turnIdAt(events, 1),
       });
       expect(openCode.calls.sessionPromptAsync).toHaveLength(2);
     } finally {
@@ -3058,7 +3081,7 @@ describe("OpenCode adapter startTurn error handling", () => {
         expect(events).toContainEqual({
           type: "turn_started",
           provider: "opencode",
-          turnId: "opencode-turn-1",
+          turnId: turnIdAt(events, 1),
         }),
       );
 
@@ -3767,7 +3790,7 @@ describe("OpenCode adapter startTurn error handling", () => {
       ];
       const replacement = session.startTurn("second");
       await vi.advanceTimersByTimeAsync(10_000);
-      await expect(replacement).resolves.toEqual({ turnId: "opencode-turn-1" });
+      await expect(replacement).resolves.toEqual({ turnId: turnIdAt(events, 1) });
       expect(countEvents(events, "turn_canceled")).toBe(1);
     } finally {
       vi.useRealTimers();
@@ -4009,6 +4032,9 @@ describe("OpenCode adapter startTurn error handling", () => {
       return { data: true };
     };
 
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => events.push(event));
+
     try {
       await session.startTurn("first");
       const interrupt = session.interrupt();
@@ -4022,7 +4048,7 @@ describe("OpenCode adapter startTurn error handling", () => {
       expect(openCode.calls.sessionStatus).toHaveLength(1);
 
       releaseIdle.resolve();
-      await expect(replacement).resolves.toEqual({ turnId: "opencode-turn-1" });
+      await expect(replacement).resolves.toEqual({ turnId: turnIdAt(events, 1) });
       expect(openCode.calls.sessionPromptAsync).toHaveLength(2);
       expect(openCode.calls.sessionStatus.length).toBeGreaterThanOrEqual(2);
     } finally {
@@ -4722,9 +4748,9 @@ describe("OpenCode provider subagent contract", () => {
       "turn_completed",
     ]);
     expect(events.map((event) => ("turnId" in event ? event.turnId : undefined))).toEqual([
-      "opencode-turn-0",
-      "opencode-turn-0",
-      "opencode-turn-0",
+      turnIdAt(events, 0),
+      turnIdAt(events, 0),
+      turnIdAt(events, 0),
     ]);
     expect(events).toContainEqual(
       expect.objectContaining({
@@ -4760,7 +4786,7 @@ describe("OpenCode provider subagent contract", () => {
           expect(events).toContainEqual({
             type: "turn_started",
             provider: "opencode",
-            turnId: "opencode-turn-0",
+            turnId: turnIdAt(events, 0),
           });
         });
         for (const event of assistantTurnEvents({
@@ -4774,9 +4800,9 @@ describe("OpenCode provider subagent contract", () => {
 
         expect(childClient.calls.sessionStatus).toEqual([{ directory: "/workspace/repo" }]);
         expect(turnEventSignatures(events)).toEqual([
-          ["turn_started", "opencode-turn-0"],
-          ["timeline", "opencode-turn-0"],
-          ["turn_completed", "opencode-turn-0"],
+          ["turn_started", turnIdAt(events, 0)],
+          ["timeline", turnIdAt(events, 0)],
+          ["turn_completed", turnIdAt(events, 0)],
         ]);
         expect(events).toContainEqual(
           expect.objectContaining({
@@ -4881,9 +4907,9 @@ describe("OpenCode provider subagent contract", () => {
 
       await vi.waitFor(() => {
         expect(turnEventSignatures(events)).toEqual([
-          ["turn_started", "opencode-turn-0"],
-          ["timeline", "opencode-turn-0"],
-          ["turn_completed", "opencode-turn-0"],
+          ["turn_started", turnIdAt(events, 0)],
+          ["timeline", turnIdAt(events, 0)],
+          ["turn_completed", turnIdAt(events, 0)],
         ]);
       });
       expect(events).toContainEqual(
@@ -4927,9 +4953,9 @@ describe("OpenCode provider subagent contract", () => {
 
       await vi.waitFor(() => {
         expect(turnEventSignatures(events)).toEqual([
-          ["turn_started", "opencode-turn-0"],
-          ["timeline", "opencode-turn-0"],
-          ["turn_completed", "opencode-turn-0"],
+          ["turn_started", turnIdAt(events, 0)],
+          ["timeline", turnIdAt(events, 0)],
+          ["turn_completed", turnIdAt(events, 0)],
         ]);
       });
     } finally {
@@ -5003,7 +5029,7 @@ describe("OpenCode provider subagent contract", () => {
       });
       await vi.waitFor(() => {
         expect(events).toEqual([
-          { type: "turn_started", provider: "opencode", turnId: "opencode-turn-0" },
+          { type: "turn_started", provider: "opencode", turnId: turnIdAt(events, 0) },
         ]);
       });
 
@@ -5118,12 +5144,12 @@ describe("OpenCode provider subagent contract", () => {
 
       await streamDrained.promise;
       expect(events.filter((event) => event.type !== "provider_subagent")).toEqual([
-        { type: "turn_started", provider: "opencode", turnId: "opencode-turn-0" },
+        { type: "turn_started", provider: "opencode", turnId: turnIdAt(events, 0) },
         {
           type: "turn_canceled",
           provider: "opencode",
           reason: "interrupted",
-          turnId: "opencode-turn-0",
+          turnId: turnIdAt(events, 0),
         },
       ]);
     } finally {
@@ -5174,7 +5200,7 @@ describe("OpenCode provider subagent contract", () => {
       expect.objectContaining({
         type: "permission_requested",
         request: expect.objectContaining({ id: "perm_child_external" }),
-        turnId: "opencode-turn-0",
+        turnId: turnIdAt(events, 0),
       }),
     );
   });
@@ -5274,7 +5300,7 @@ describe("OpenCode provider subagent contract", () => {
     const parent = await client.createSession({
       provider: "opencode",
       cwd: "/workspace/repo",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
     parent.subscribe(() => undefined);
 
diff --git a/packages/server/src/server/agent/providers/opencode-agent.ts b/packages/server/src/server/agent/providers/opencode-agent.ts
index e6ee17e17d..cb9a6c327b 100644
--- a/packages/server/src/server/agent/providers/opencode-agent.ts
+++ b/packages/server/src/server/agent/providers/opencode-agent.ts
@@ -1,4 +1,6 @@
-import { validateProviderOptions } from "../provider-options.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../provider-options.js";
 import {
   createOpencodeClient,
   type AssistantMessage as OpenCodeAssistantMessage,
@@ -25,7 +27,8 @@ import {
   type AgentCapabilityFlags,
   type AgentClient,
   type AgentCreateSessionOptions,
-  type AgentFeature,
+  type AgentDraftControls,
+  type AgentOptionControl,
   type AgentLaunchContext,
   type AgentMode,
   type AgentModelDefinition,
@@ -234,15 +237,25 @@ const DEFAULT_MODES: AgentMode[] = [
 ];
 
 function isOpenCodeAutoAcceptEnabled(config: AgentSessionConfig): boolean {
-  return config.featureValues?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === true;
+  return config.providerOptions?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === true;
 }
 
-function withOpenCodeAutoAcceptFeature(
-  featureValues: Record<string, unknown> | undefined,
+/** What opening changed in the options the caller gave: legacy `full-access` turns Auto Accept on. */
+function openCodeOpenOptionsPatch(input: {
+  given: AgentSessionConfig;
+  opened: OpenCodeAgentConfig;
+}): Record<string, unknown> {
+  return isOpenCodeAutoAcceptEnabled(input.opened) && !isOpenCodeAutoAcceptEnabled(input.given)
+    ? { [OPENCODE_AUTO_ACCEPT_FEATURE_ID]: true }
+    : {};
+}
+
+function withOpenCodeAutoAccept(
+  providerOptions: ProviderOptions | undefined,
   enabled: boolean,
-): Record<string, unknown> {
+): ProviderOptions {
   return {
-    ...featureValues,
+    ...providerOptions,
     [OPENCODE_AUTO_ACCEPT_FEATURE_ID]: enabled,
   };
 }
@@ -261,25 +274,25 @@ function resolveOpenCodeCreateConfig(
   const requestedMode = legacyFullAccess
     ? OPENCODE_BUILD_MODE_ID
     : (input.requestedMode ?? inheritedOpenCodeMode);
-  const featureValues =
+  const providerOptions =
     legacyFullAccess ||
-    (isUnattendedCreate && input.featureValues?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === undefined)
-      ? withOpenCodeAutoAcceptFeature(input.featureValues, true)
-      : input.featureValues;
+    (isUnattendedCreate && input.providerOptions?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === undefined)
+      ? withOpenCodeAutoAccept(input.providerOptions, true)
+      : input.providerOptions;
 
   if (inheritsUnattended && requestedMode === undefined) {
     // Unattendedness for OpenCode is carried by auto_accept (set above), not
     // by any particular agent. Leave the mode unset so OpenCode uses its own
     // default agent — `build` may not exist in the user's OpenCode config.
-    return { modeId: undefined, featureValues };
+    return { modeId: undefined, providerOptions };
   }
 
   const resolved = resolveDefaultAgentCreateConfig({
     ...input,
     requestedMode,
-    featureValues,
+    providerOptions,
   });
-  return { ...resolved, featureValues };
+  return { ...resolved, providerOptions };
 }
 
 function isOpenCodeCreateConfigUnattended(
@@ -287,26 +300,18 @@ function isOpenCodeCreateConfigUnattended(
 ): boolean {
   return (
     isDefaultAgentCreateConfigUnattended(input) ||
-    input.config.featureValues?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === true ||
-    input.features?.some(
-      (feature) =>
-        feature.id === OPENCODE_AUTO_ACCEPT_FEATURE_ID &&
-        (feature.value === true || feature.value === "true"),
-    ) === true
+    input.config.providerOptions?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === true
   );
 }
 
-function buildOpenCodeAutoAcceptFeature(config: AgentSessionConfig): AgentFeature {
-  return {
-    type: "toggle",
-    id: OPENCODE_AUTO_ACCEPT_FEATURE_ID,
-    label: "Auto Accept",
-    description: "Automatically approves OpenCode tool permission prompts.",
-    tooltip: "Auto accept permission prompts",
-    icon: "shield-check",
-    value: isOpenCodeAutoAcceptEnabled(config),
-  };
-}
+const OPENCODE_AUTO_ACCEPT_CONTROL: AgentOptionControl = {
+  type: "toggle",
+  key: OPENCODE_AUTO_ACCEPT_FEATURE_ID,
+  label: "Auto Accept",
+  description: "Automatically approves OpenCode tool permission prompts.",
+  tooltip: "Auto accept permission prompts",
+  icon: "shield-check",
+};
 
 function buildOpenCodePermissionActions(): AgentPermissionAction[] {
   return [
@@ -351,7 +356,11 @@ type OpenCodeAgentConfig = Omit<AgentSessionConfig, "providerOptions"> & {
   providerOptions: OpenCodeProviderOptions;
 };
 
-const OPENCODE_SESSION_ENV_KEYS = new Set(["PASEO_AGENT_ID", "PASEO_AGENT_CWD"]);
+const OPENCODE_SESSION_ENV_KEYS = new Set([
+  "PASEO_AGENT_ID",
+  "PASEO_AGENT_CWD",
+  "PASEO_WORKSPACE_ID",
+]);
 
 function requiresDedicatedOpenCodeServer(
   config: OpenCodeAgentConfig,
@@ -684,10 +693,7 @@ function normalizeOpenCodeConfig(config: OpenCodeAgentConfig): OpenCodeAgentConf
   return {
     ...normalized,
     modeId: OPENCODE_BUILD_MODE_ID,
-    featureValues: {
-      ...normalized.featureValues,
-      [OPENCODE_AUTO_ACCEPT_FEATURE_ID]: true,
-    },
+    providerOptions: withOpenCodeAutoAccept(normalized.providerOptions, true),
   };
 }
 
@@ -1505,6 +1511,7 @@ export class OpenCodeAgentClient implements AgentClient {
         false,
         unbindBridge,
         connectServer,
+        openCodeOpenOptionsPatch({ given: config, opened: openCodeConfig }),
       );
     } catch (error) {
       await connection.release();
@@ -1560,6 +1567,7 @@ export class OpenCodeAgentClient implements AgentClient {
         registeredAcquisition !== null,
         unbindBridge,
         connectServer,
+        openCodeOpenOptionsPatch({ given: config, opened: openCodeConfig }),
       );
     } catch (error) {
       await connection.release();
@@ -1681,8 +1689,9 @@ export class OpenCodeAgentClient implements AgentClient {
     }
   }
 
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
-    return [buildOpenCodeAutoAcceptFeature(this.assertConfig(config))];
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    this.assertConfig(config);
+    return { controls: [OPENCODE_AUTO_ACCEPT_CONTROL], options: config.providerOptions ?? {} };
   }
 
   async listImportableSessions(
@@ -3373,6 +3382,7 @@ interface OpenCodeServerConnection {
 class OpenCodeAgentSession implements AgentSession {
   readonly provider = "opencode" as const;
   readonly capabilities = OPENCODE_CAPABILITIES;
+  readonly openOptionsPatch: Record<string, unknown>;
 
   private readonly config: OpenCodeAgentConfig;
   private server: OpenCodeServerConnection;
@@ -3407,6 +3417,7 @@ class OpenCodeAgentSession implements AgentSession {
   private partTypes = new Map<string, string>();
   private availableModesCache: AgentMode[] | null = null;
   private readonly subscribers = new Set<(event: AgentStreamEvent) => void>();
+  private readonly turnNamespace = randomUUID();
   private nextTurnOrdinal = 0;
   private turnState: OpenCodeTurnState = { status: "idle" };
   /**
@@ -3460,8 +3471,10 @@ class OpenCodeAgentSession implements AgentSession {
     private readonly externallyDriven = false,
     releaseBridge?: () => void,
     connectServer?: () => Promise<OpenCodeServerConnection>,
+    openOptionsPatch: Record<string, unknown> = {},
   ) {
     this.config = config;
+    this.openOptionsPatch = openOptionsPatch;
     this.server = {
       client,
       events,
@@ -3567,8 +3580,8 @@ class OpenCodeAgentSession implements AgentSession {
     return this.turnState.status === "running" ? this.turnState.turnId : null;
   }
 
-  get features(): AgentFeature[] {
-    return [buildOpenCodeAutoAcceptFeature(this.config)];
+  get controls(): AgentOptionControl[] {
+    return [OPENCODE_AUTO_ACCEPT_CONTROL];
   }
 
   async getRuntimeInfo(): Promise<AgentRuntimeInfo> {
@@ -4888,7 +4901,7 @@ class OpenCodeAgentSession implements AgentSession {
 
   private createTurnId(): string {
     this.gapRepairRevision += 1;
-    return `opencode-turn-${this.nextTurnOrdinal++}`;
+    return `opencode-turn-${this.turnNamespace}-${this.nextTurnOrdinal++}`;
   }
 
   private traceOpenCode(msg: OpenCodeTraceMessage, data: OpenCodeTraceData = {}): void {
@@ -4962,7 +4975,15 @@ class OpenCodeAgentSession implements AgentSession {
     const normalizedModeId = normalizeOpenCodeModeId(modeId);
     if (normalizedModeId === OPENCODE_LEGACY_FULL_ACCESS_MODE_ID) {
       this.currentMode = OPENCODE_BUILD_MODE_ID;
-      await this.setFeature(OPENCODE_AUTO_ACCEPT_FEATURE_ID, true);
+      this.setAutoAccept(true);
+      this.notifySubscribers(
+        {
+          type: "options_changed",
+          provider: "opencode",
+          patch: { [OPENCODE_AUTO_ACCEPT_FEATURE_ID]: true },
+        },
+        null,
+      );
       return;
     }
 
@@ -4970,17 +4991,26 @@ class OpenCodeAgentSession implements AgentSession {
     this.config.modeId = normalizedModeId ?? undefined;
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    if (featureId !== OPENCODE_AUTO_ACCEPT_FEATURE_ID) {
-      throw new Error(`Unsupported OpenCode feature '${featureId}'`);
+  async applyOptions(options: ProviderOptions): Promise<void> {
+    assertChangesAreLive({
+      provider: "opencode",
+      patch: options,
+      current: this.config.providerOptions,
+      live: [OPENCODE_AUTO_ACCEPT_FEATURE_ID],
+    });
+    const next = validateProviderOptions(
+      "opencode",
+      OpenCodeProviderOptionsSchema,
+      applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+    );
+    if (OPENCODE_AUTO_ACCEPT_FEATURE_ID in options) {
+      this.setAutoAccept(next?.[OPENCODE_AUTO_ACCEPT_FEATURE_ID] === true);
     }
+  }
 
-    const enabled = value === true;
+  private setAutoAccept(enabled: boolean): void {
     this.autoAcceptEnabled = enabled;
-    this.config.featureValues = {
-      ...this.config.featureValues,
-      [OPENCODE_AUTO_ACCEPT_FEATURE_ID]: enabled,
-    };
+    this.config.providerOptions = withOpenCodeAutoAccept(this.config.providerOptions, enabled);
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
diff --git a/packages/server/src/server/agent/providers/opencode-bridge-adapter.test.ts b/packages/server/src/server/agent/providers/opencode-bridge-adapter.test.ts
index 133ac3c992..6cb15ccb6d 100644
--- a/packages/server/src/server/agent/providers/opencode-bridge-adapter.test.ts
+++ b/packages/server/src/server/agent/providers/opencode-bridge-adapter.test.ts
@@ -80,8 +80,12 @@ describe("OpenCode bridge adapter", () => {
       await rm(paseoHome, { recursive: true, force: true });
     });
     const runtime = new TestOpenCodeHarness();
-    runtime.enqueueClient(new TestOpenCodeClient());
-    runtime.enqueueClient(new TestOpenCodeClient());
+    const envClient = new TestOpenCodeClient();
+    const mcpClient = new TestOpenCodeClient();
+    envClient.sessionCreateResponse = { data: { id: "ses_env" } };
+    mcpClient.sessionCreateResponse = { data: { id: "ses_mcp" } };
+    runtime.enqueueClient(envClient);
+    runtime.enqueueClient(mcpClient);
     const client = new OpenCodeAgentClient(createTestLogger(), undefined, {
       serverManager: runtime,
       createClient: runtime.createClient,
@@ -102,6 +106,12 @@ describe("OpenCode bridge adapter", () => {
     );
 
     expect(runtime.acquisitions.map(({ kind }) => kind)).toEqual(["dedicated", "dedicated"]);
+    await expect(readBridgeContext(bridge, "ses_env")).resolves.toEqual({
+      env: { PASEO_AGENT_ID: "one", CUSTOM_TOKEN: "secret" },
+    });
+    await expect(readBridgeContext(bridge, "ses_mcp")).resolves.toEqual({
+      env: { PASEO_AGENT_ID: "two" },
+    });
     await customEnv.close();
     await customMcp.close();
   });
diff --git a/packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts b/packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts
index 277cad58fe..0960f9ca62 100644
--- a/packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts
@@ -94,7 +94,7 @@ test("bridge preserves tool failure messages and classifies invalid requests as
     const { tools } = await manifest.json();
     expect(
       tools.find((tool: { name: string }) => tool.name === "create_agent").inputSchema.properties,
-    ).not.toHaveProperty("background");
+    ).toHaveProperty("background");
     expect(
       tools.find((tool: { name: string }) => tool.name === "update_schedule").inputSchema
         .properties,
diff --git a/packages/server/src/server/agent/providers/opencode/bridge.test.ts b/packages/server/src/server/agent/providers/opencode/bridge.test.ts
index 33f43c4f79..aa7acb830c 100644
--- a/packages/server/src/server/agent/providers/opencode/bridge.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/bridge.test.ts
@@ -20,6 +20,7 @@ import { createPaseoAgentToolManifest, createPaseoToolCatalog } from "../../tool
 import { serializePaseoToolInputParameters } from "../../tools/paseo-tool-serialization.js";
 import {
   OpenCodeBridge,
+  decorateOpenCodeV2Env,
   loadOpenCodeBridgePluginArtifact,
   materializeOpenCodeV2Plugin,
 } from "./bridge.js";
@@ -137,33 +138,28 @@ describe("OpenCodeBridge", () => {
       };
       expect(ajv.compile(createDefinition.inputSchema)(createInput)).toBe(true);
 
-      const v2Config = z
-        .object({ plugins: z.array(z.object({ package: z.string() })) })
-        .parse(JSON.parse((await bridge.decorateV2ServerEnv({})).OPENCODE_CONFIG_CONTENT));
-      const v2Module: {
-        default: { setup(context: V2TestPluginContext): Promise<() => Promise<void>> };
-      } = await import(
-        pathToFileURL(path.join(fileURLToPath(v2Config.plugins[0]!.package), "server.js")).href
-      );
       const tools = new Map<string, V2TestTool>();
-      const dispose = await v2Module.default.setup({
-        options: plugin,
-        tool: {
-          transform: async (transform) => {
-            transform({
-              add: (tool) => {
-                tools.set(tool.name, tool);
-              },
-            });
-            return { dispose: async () => undefined };
+      const dispose = await setupBoundV2Plugin(
+        bridge,
+        {
+          tool: {
+            transform: async (transform) => {
+              transform({
+                add: (tool) => {
+                  tools.set(tool.name, tool);
+                },
+              });
+              return { dispose: async () => undefined };
+            },
+          },
+          session: {
+            context: async () => [],
+            get: async () => ({ parentID: "bound" }),
+            hook: async () => ({ dispose: async () => undefined }),
           },
         },
-        session: {
-          context: async () => [],
-          get: async () => ({ parentID: "bound" }),
-          hook: async () => ({ dispose: async () => undefined }),
-        },
-      });
+        ["bound"],
+      );
       try {
         const created = await tools
           .get("paseo_create_agent")!
@@ -185,13 +181,18 @@ describe("OpenCodeBridge", () => {
         expect(createDefinition.inputSchema).toMatchObject({
           properties: { notifyOnFinish: { default: true } },
         });
-        expect(createDefinition.inputSchema.properties).not.toHaveProperty("background");
+        expect(createDefinition.inputSchema.properties).toHaveProperty("background");
         expect(sendDefinition.inputSchema).toMatchObject({
           properties: { notifyOnFinish: { default: true } },
         });
-        await expect(
-          catalog.executeTool("create_agent", { ...createInput, background: true }),
-        ).rejects.toThrow("background");
+        await catalog.executeTool("create_agent", {
+          ...createInput,
+          title: "Background child",
+          background: true,
+        });
+        expect(
+          agentManager.listAgents().find((agent) => agent.config.title === "Background child"),
+        ).toMatchObject({ background: true });
 
         const v1Module = await import(plugin.pluginUrl);
         const hooks = await v1Module.default({}, plugin);
@@ -402,45 +403,35 @@ describe("OpenCodeBridge", () => {
     const release = bridge.bindSession({ sessionId: "parent", env: {}, tools: catalog });
     const releaseDisabled = bridge.bindSession({ sessionId: "disabled", env: {} });
     try {
-      const env = await bridge.decorateV2ServerEnv({});
-      const config = z
-        .object({
-          plugins: z.array(
-            z.object({
-              package: z.string(),
-              options: z.object({ baseUrl: z.string(), token: z.string() }),
-            }),
-          ),
-        })
-        .parse(JSON.parse(env.OPENCODE_CONFIG_CONTENT));
-      expect(await bridge.decorateV2ServerEnv(env)).toEqual(env);
-      const plugin = config.plugins[0]!;
+      const pluginUrl = await bridge.materializeV2Plugin();
+      const env = decorateOpenCodeV2Env({}, pluginUrl);
+      expect(decorateOpenCodeV2Env(env, pluginUrl)).toEqual(env);
       const tools = new Map<string, V2TestTool>();
       let filter!: (input: V2TestContext) => Promise<void>;
-      const module: {
-        default: { setup(context: V2TestPluginContext): Promise<() => Promise<void>> };
-      } = await import(pathToFileURL(path.join(fileURLToPath(plugin.package), "server.js")).href);
-      const dispose = await module.default.setup({
-        options: plugin.options,
-        tool: {
-          transform: async (transform) => {
-            transform({
-              add: (tool) => {
-                tools.set(tool.name, tool);
-              },
-            });
-            return { dispose: async () => undefined };
+      const dispose = await setupBoundV2Plugin(
+        bridge,
+        {
+          tool: {
+            transform: async (transform) => {
+              transform({
+                add: (tool) => {
+                  tools.set(tool.name, tool);
+                },
+              });
+              return { dispose: async () => undefined };
+            },
+          },
+          session: {
+            context: async () => [],
+            get: async ({ sessionID }) => ({ parentID: sessionID === "child" ? "parent" : "" }),
+            hook: async (_name, callback) => {
+              filter = callback;
+              return { dispose: async () => undefined };
+            },
           },
         },
-        session: {
-          context: async () => [],
-          get: async () => ({ parentID: "parent" }),
-          hook: async (_name, callback) => {
-            filter = callback;
-            return { dispose: async () => undefined };
-          },
-        },
-      });
+        ["parent", "disabled"],
+      );
       const allowed: V2TestContext = {
         sessionID: "child",
         tools: { paseo_echo_context: {}, native: {} },
@@ -453,6 +444,12 @@ describe("OpenCodeBridge", () => {
       };
       await filter(disabled);
       expect(Object.keys(disabled.tools)).toEqual(["native"]);
+      const unrelated: V2TestContext = {
+        sessionID: "unrelated",
+        tools: { paseo_echo_context: {}, native: {} },
+      };
+      await filter(unrelated);
+      expect(Object.keys(unrelated.tools)).toEqual(["native"]);
       await expect(
         tools.get("paseo_echo_context")!.execute({ value: "child result" }, { sessionID: "child" }),
       ).resolves.toMatchObject({ content: [{ type: "text", text: "child result" }] });
@@ -486,35 +483,33 @@ describe("OpenCodeBridge", () => {
     await bridge.start();
     const release = bridge.bindSession({ sessionId: "caller", env: {}, tools: catalog });
     try {
-      const env = await bridge.decorateV2ServerEnv({});
-      const { plugins } = JSON.parse(env.OPENCODE_CONFIG_CONTENT);
-      const plugin = plugins[0];
-      const module = await import(
-        pathToFileURL(path.join(fileURLToPath(plugin.package), "server.js")).href
-      );
+      const options = bridge.sharedV2Connection();
       const tools = new Map<string, V2TestTool>();
-      const dispose = await module.default.setup({
-        options: plugin.options,
-        tool: {
-          transform: async (transform: (editor: { add(tool: V2TestTool): void }) => void) => {
-            transform({ add: (tool) => tools.set(tool.name, tool) });
-            return { dispose: async () => undefined };
+      const dispose = await setupBoundV2Plugin(
+        bridge,
+        {
+          tool: {
+            transform: async (transform: (editor: { add(tool: V2TestTool): void }) => void) => {
+              transform({ add: (tool) => tools.set(tool.name, tool) });
+              return { dispose: async () => undefined };
+            },
+          },
+          session: {
+            context: async () => [],
+            get: async () => ({ parentID: "" }),
+            hook: async () => ({ dispose: async () => undefined }),
           },
         },
-        session: {
-          context: async () => [],
-          get: async () => ({ parentID: "" }),
-          hook: async () => ({ dispose: async () => undefined }),
-        },
-      } satisfies V2TestPluginContext);
+        ["caller"],
+      );
       try {
         const input = { provider: "codex", title: "Invalid provider", initialPrompt: "Hello" };
         const response = await fetch(
-          `${plugin.options.baseUrl}/_internal/opencode/sessions/caller/tools/create_agent`,
+          `${options.baseUrl}/_internal/opencode/sessions/caller/tools/create_agent`,
           {
             method: "POST",
             headers: {
-              Authorization: `Bearer ${plugin.options.token}`,
+              Authorization: `Bearer ${options.token}`,
               "Content-Type": "application/json",
             },
             body: JSON.stringify(input),
@@ -572,35 +567,24 @@ describe("OpenCodeBridge", () => {
     await bridge.start();
     const release = bridge.bindSession({ sessionId: "session", env: {}, tools: catalog });
     try {
-      const env = await bridge.decorateV2ServerEnv({});
-      const plugin = z
-        .object({
-          plugins: z.array(
-            z.object({
-              package: z.string(),
-              options: z.object({ baseUrl: z.string(), token: z.string() }),
-            }),
-          ),
-        })
-        .parse(JSON.parse(env.OPENCODE_CONFIG_CONTENT)).plugins[0]!;
       const pluginTools = new Map<string, V2TestTool>();
-      const module: {
-        default: { setup(context: V2TestPluginContext): Promise<() => Promise<void>> };
-      } = await import(pathToFileURL(path.join(fileURLToPath(plugin.package), "server.js")).href);
-      const dispose = await module.default.setup({
-        options: plugin.options,
-        tool: {
-          transform: async (transform) => {
-            transform({ add: (tool) => pluginTools.set(tool.name, tool) });
-            return { dispose: async () => undefined };
+      const dispose = await setupBoundV2Plugin(
+        bridge,
+        {
+          tool: {
+            transform: async (transform) => {
+              transform({ add: (tool) => pluginTools.set(tool.name, tool) });
+              return { dispose: async () => undefined };
+            },
+          },
+          session: {
+            context: async () => [],
+            get: async () => ({ parentID: undefined }),
+            hook: async () => ({ dispose: async () => undefined }),
           },
         },
-        session: {
-          context: async () => [],
-          get: async () => ({ parentID: undefined }),
-          hook: async () => ({ dispose: async () => undefined }),
-        },
-      });
+        ["session"],
+      );
       const result = await pluginTools
         .get("paseo_browser_screenshot")!
         .execute({}, { sessionID: "session" });
@@ -642,7 +626,8 @@ describe("OpenCodeBridge", () => {
     const tools = new Map<string, V2TestTool>();
     let hook!: (input: V2TestContext) => Promise<void>;
     const dispose = await module.default.setup({
-      options: { baseUrl: "", token: "" },
+      options: { mode: "structured-only" },
+      location: { directory: root },
       tool: {
         transform: async (transform) => {
           transform({
@@ -657,7 +642,7 @@ describe("OpenCodeBridge", () => {
         context: async () => history,
         get: async () => ({ parentID: "parent" }),
         hook: async (_name, callback) => {
-          hook = callback;
+          hook ??= callback;
           return { dispose: async () => undefined };
         },
       },
@@ -701,9 +686,13 @@ describe("OpenCodeBridge", () => {
           name.startsWith("paseo-v2-"),
         ),
       ).toEqual([]);
-      const env = await bridge.decorateV2ServerEnv({
-        OPENCODE_CONFIG_CONTENT: JSON.stringify({ plugins: ["user-plugin"] }),
-      });
+      const pluginUrl = await bridge.materializeV2Plugin();
+      const env = decorateOpenCodeV2Env(
+        {
+          OPENCODE_CONFIG_CONTENT: JSON.stringify({ plugins: ["user-plugin"] }),
+        },
+        pluginUrl,
+      );
       const config = z
         .object({ plugins: z.tuple([z.literal("user-plugin"), z.object({ package: z.string() })]) })
         .parse(JSON.parse(env.OPENCODE_CONFIG_CONTENT));
@@ -711,6 +700,9 @@ describe("OpenCodeBridge", () => {
       expect((await stat(directory)).isDirectory()).toBe(true);
       const entry = await readFile(path.join(directory, "server.js"), "utf8");
       expect(entry).toContain('id: "paseo"');
+      expect(await readFile(path.join(directory, "state.mjs"), "utf8")).toBe(
+        await readFile(new URL("./v2/state.mjs", import.meta.url), "utf8"),
+      );
       const manifest = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"));
       expect(manifest).toMatchObject({ type: "module", exports: { "./server": "./server.js" } });
     } finally {
@@ -856,7 +848,8 @@ interface V2TestContext {
   system?: Array<{ type: "text"; text: string }>;
 }
 interface V2TestPluginContext {
-  options: { baseUrl: string; token: string };
+  options: Record<string, string>;
+  location?: { directory: string };
   tool: {
     transform(
       callback: (editor: { add(tool: V2TestTool): void }) => void,
@@ -864,10 +857,33 @@ interface V2TestPluginContext {
   };
   session: {
     context(input: { sessionID: string }): Promise<SessionMessageInfo[]>;
-    get(input: { sessionID: string }): Promise<{ parentID: string }>;
+    get(input: { sessionID: string }): Promise<{ parentID: string | undefined }>;
     hook(
       name: string,
       callback: (input: V2TestContext) => Promise<void>,
     ): Promise<{ dispose(): Promise<void> }>;
   };
 }
+
+async function setupBoundV2Plugin(
+  bridge: OpenCodeBridge,
+  context: Pick<V2TestPluginContext, "tool" | "session">,
+  sessionIds: string[],
+): Promise<() => Promise<void>> {
+  const directory = fileURLToPath(await bridge.materializeV2Plugin());
+  const module = await import(pathToFileURL(path.join(directory, "server.js")).href);
+  let bind!: (input: { sessionID: string; baseUrl: string; token: string }) => Promise<unknown>;
+  const dispose: () => Promise<void> = await module.default.setup({
+    ...context,
+    options: {},
+    location: { directory },
+    rpc: {
+      register: async (_definition: unknown, handlers: { bind: typeof bind }) => {
+        bind = handlers.bind;
+        return { dispose: async () => undefined };
+      },
+    },
+  });
+  for (const sessionID of sessionIds) await bind({ sessionID, ...bridge.sharedV2Connection() });
+  return dispose;
+}
diff --git a/packages/server/src/server/agent/providers/opencode/bridge.ts b/packages/server/src/server/agent/providers/opencode/bridge.ts
index 7abe34475d..87ee07798b 100644
--- a/packages/server/src/server/agent/providers/opencode/bridge.ts
+++ b/packages/server/src/server/agent/providers/opencode/bridge.ts
@@ -30,6 +30,7 @@ class OpenCodeBridgeClientError extends Error {
 interface OpenCodeBridgeOptions {
   paseoHome: string;
   logger: Logger;
+  port?: number;
 }
 
 interface OpenCodeSessionBinding {
@@ -54,6 +55,7 @@ interface OpenCodeConfig {
 export class OpenCodeBridge {
   private readonly paseoHome: string;
   private readonly logger: Logger;
+  private readonly port: number;
   private readonly token = randomBytes(32).toString("hex");
   private readonly sessions = new Map<string, OpenCodeSessionBinding>();
   private server: Server | null = null;
@@ -65,6 +67,7 @@ export class OpenCodeBridge {
   constructor(options: OpenCodeBridgeOptions) {
     this.paseoHome = options.paseoHome;
     this.logger = options.logger.child({ module: "agent", component: "opencode-bridge" });
+    this.port = options.port ?? 0;
   }
 
   async start(): Promise<void> {
@@ -75,7 +78,7 @@ export class OpenCodeBridge {
     });
     await new Promise<void>((resolve, reject) => {
       server.once("error", reject);
-      server.listen(0, "127.0.0.1", () => {
+      server.listen(this.port, "127.0.0.1", () => {
         server.off("error", reject);
         resolve();
       });
@@ -94,6 +97,8 @@ export class OpenCodeBridge {
   }
 
   bindSession(input: BindOpenCodeSessionInput): () => void {
+    if (this.sessions.has(input.sessionId))
+      throw new Error(`OpenCode session ${input.sessionId} is already bound to a Paseo agent`);
     const binding: OpenCodeSessionBinding = {
       env: { ...input.env },
       ...(input.tools ? { tools: input.tools } : {}),
@@ -127,12 +132,13 @@ export class OpenCodeBridge {
     };
   }
 
-  async decorateV2ServerEnv(env: Record<string, string>): Promise<Record<string, string>> {
+  async materializeV2Plugin(): Promise<string> {
     this.v2PluginUrl ??= await this.materializePlugin(2);
-    return decorateOpenCodeV2Env(env, this.v2PluginUrl, {
-      baseUrl: this.requireBaseUrl(),
-      token: this.token,
-    });
+    return this.v2PluginUrl;
+  }
+
+  sharedV2Connection(baseUrl = this.requireBaseUrl()): OpenCodePluginOptions {
+    return { baseUrl, token: this.token };
   }
 
   async close(): Promise<void> {
@@ -282,6 +288,8 @@ export async function materializeOpenCodeV2Plugin(paseoHome: string): Promise<st
   // V2 ignores configured file paths; it loads a package directory's server entry point.
   const directory = path.join(paseoHome, "runtime", "opencode", `paseo-v2-${digest}`);
   await writeFileAtomic(path.join(directory, "server.js"), artifact);
+  const state = await readFile(new URL("./v2/state.mjs", import.meta.url));
+  await writeFileAtomic(path.join(directory, "state.mjs"), state);
   await writeFileAtomic(
     path.join(directory, "package.json"),
     JSON.stringify({
diff --git a/packages/server/src/server/agent/providers/opencode/options.ts b/packages/server/src/server/agent/providers/opencode/options.ts
index df55bedc0b..bbd05620fc 100644
--- a/packages/server/src/server/agent/providers/opencode/options.ts
+++ b/packages/server/src/server/agent/providers/opencode/options.ts
@@ -10,6 +10,8 @@ const PermissionRuleSchema = z.union([
 // OpenCode Config.permission, maintained against @opencode-ai/sdk 1.14.46.
 export const OpenCodeProviderOptionsSchema = z
   .object({
+    // Composer control: approves permission prompts without asking.
+    auto_accept: z.boolean().optional(),
     permission: z
       .union([
         PermissionActionSchema,
diff --git a/packages/server/src/server/agent/providers/opencode/runtime-client.test.ts b/packages/server/src/server/agent/providers/opencode/runtime-client.test.ts
index b1ee5be697..910a68cfef 100644
--- a/packages/server/src/server/agent/providers/opencode/runtime-client.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/runtime-client.test.ts
@@ -66,6 +66,7 @@ test("retries a rejected version probe after the configured binary changes", asy
   const script = join(root, "version.cjs");
   const client = new OpenCodeRuntimeClient(createTestLogger(), {
     command: { mode: "replace", argv: [process.execPath, script] },
+    env: { XDG_STATE_HOME: root },
   });
   try {
     await writeFile(script, 'console.log("opencode v2.0.3")');
@@ -95,16 +96,17 @@ test.each([
   const script = join(root, "version.cjs");
   const client = new OpenCodeRuntimeClient(createTestLogger(), {
     command: { mode: "replace", argv: [process.execPath, script] },
+    env: { XDG_STATE_HOME: root },
   });
   try {
     await writeFile(script, initialSource);
-    expect((await client.listFeatures({ provider: "opencode", cwd: root }))[0]?.label).toBe(
-      "Auto Accept",
-    );
+    expect(
+      (await client.listControls({ provider: "opencode", cwd: root })).controls[0]?.label,
+    ).toBe("Auto Accept");
     await writeFile(script, 'console.log("opencode v2.0.10")');
-    expect((await client.listFeatures({ provider: "opencode", cwd: root }))[0]?.label).toBe(
-      "Auto-accept",
-    );
+    expect(
+      (await client.listControls({ provider: "opencode", cwd: root })).controls[0]?.label,
+    ).toBe("Auto-accept");
   } finally {
     await client.shutdown();
     await rm(root, { recursive: true, force: true });
@@ -193,13 +195,14 @@ test.each([
       logger,
       {
         command: { mode: "replace", argv: [process.execPath, script] },
+        env: { XDG_STATE_HOME: root },
       },
       { serverManager: new TrackedServerManager({ logger }) },
     );
     const legacy = new OpenCodeAgentClient(logger);
     const config = { provider: "opencode", cwd: root };
     try {
-      expect(await client.listFeatures(config)).toEqual(await legacy.listFeatures(config));
+      expect(await client.listControls(config)).toEqual(await legacy.listControls(config));
     } finally {
       await client.shutdown();
       await legacy.shutdown();
@@ -209,3 +212,38 @@ test.each([
   },
   10000,
 );
+
+test("selects v2 without probing the binary when an external server is configured", async () => {
+  const { OpenCodeRuntimeClient } = await import("./runtime-client.js");
+  const { createTestLogger } = await import("../../../../test-utils/test-logger.js");
+  const client = new OpenCodeRuntimeClient(createTestLogger(), {
+    command: { mode: "replace", argv: [process.execPath, "-e", "process.exit(1)"] },
+    env: { PASEO_OPENCODE_SERVER_URL: "http://127.0.0.1:4096" },
+  });
+  try {
+    const { controls } = await client.listControls({ provider: "opencode", cwd: "/tmp/project" });
+    expect(controls.map((control) => control.label)).toEqual(["Auto-accept"]);
+  } finally {
+    await client.shutdown();
+  }
+});
+
+test("keeps native Paseo tools available when an external server is configured", async () => {
+  const { OpenCodeRuntimeClient } = await import("./runtime-client.js");
+  const { createTestLogger } = await import("../../../../test-utils/test-logger.js");
+  const { OpenCodeBridge } = await import("./bridge.js");
+  const bridge = new OpenCodeBridge({ paseoHome: "/tmp", logger: createTestLogger() });
+  const external = new OpenCodeRuntimeClient(
+    createTestLogger(),
+    { env: { PASEO_OPENCODE_SERVER_URL: "http://127.0.0.1:4096" } },
+    { bridge },
+  );
+  const local = new OpenCodeRuntimeClient(createTestLogger(), undefined, { bridge });
+  try {
+    expect(external.capabilities.supportsNativePaseoTools).toBe(true);
+    expect(local.capabilities.supportsNativePaseoTools).toBe(true);
+  } finally {
+    await external.shutdown();
+    await local.shutdown();
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/runtime-client.ts b/packages/server/src/server/agent/providers/opencode/runtime-client.ts
index 2a34abe35d..6e65c7637e 100644
--- a/packages/server/src/server/agent/providers/opencode/runtime-client.ts
+++ b/packages/server/src/server/agent/providers/opencode/runtime-client.ts
@@ -19,7 +19,9 @@ import {
 import { execCommand } from "../../../../utils/spawn.js";
 import { OpenCodeAgentClient } from "../opencode-agent.js";
 import type { OpenCodeV2AgentClient } from "./v2/agent.js";
+import { resolveExternalOpenCodeServer } from "./v2/external-server.js";
 import { withOpenCodeRuntimeNotice } from "./runtime-notice.js";
+import { selectOpenCodeService } from "./v2/service-selection.js";
 
 // Keep the minimum aligned with the SDK and binary exercised by CI.
 const MINIMUM_V2: readonly [number, number] = [0, 10];
@@ -67,8 +69,25 @@ export class OpenCodeRuntimeClient implements AgentClient {
     this.resolveCreateConfig = this.legacy.resolveCreateConfig;
     this.isCreateConfigUnattended = this.legacy.isCreateConfigUnattended;
   }
+  private selectService() {
+    return selectOpenCodeService({
+      explicit: resolveExternalOpenCodeServer({ ...globalThis.process.env, ...this.settings?.env }),
+      env: this.settings?.env,
+    });
+  }
   private client(): Promise<OpenCodeAgentClient | OpenCodeV2AgentClient> {
     this.selected ??= (async () => {
+      const selection = await this.selectService();
+      if (selection.kind !== "owned") {
+        const { OpenCodeV2AgentClient } = await import("./v2/agent.js");
+        return new OpenCodeV2AgentClient({
+          logger: this.logger,
+          settings: this.settings,
+          managedProcesses: this.options.managedProcesses,
+          bridge: this.options.bridge,
+          selection,
+        });
+      }
       let output: string;
       try {
         const launch = await resolveProviderLaunch({
@@ -97,6 +116,7 @@ export class OpenCodeRuntimeClient implements AgentClient {
         settings: this.settings,
         managedProcesses: this.options.managedProcesses,
         bridge: this.options.bridge,
+        selection,
       });
     })().catch((error: unknown) => {
       // A failed probe must not poison refresh after the user updates the binary.
@@ -106,9 +126,14 @@ export class OpenCodeRuntimeClient implements AgentClient {
     return this.selected;
   }
   async isAvailable() {
+    const selection = await this.selectService();
+    if (selection.kind !== "owned") return true;
     return this.legacy.isAvailable();
   }
   async getDiagnostic() {
+    const selection = await this.selectService();
+    if (selection.kind !== "owned")
+      return { diagnostic: `OpenCode server: ${selection.server.url}` };
     return this.legacy.getDiagnostic();
   }
   async createSession(
@@ -135,8 +160,8 @@ export class OpenCodeRuntimeClient implements AgentClient {
   async listCommands(config: AgentSessionConfig) {
     return (await this.client()).listCommands(config);
   }
-  async listFeatures(config: AgentSessionConfig) {
-    return (await this.client()).listFeatures(config);
+  async listControls(config: AgentSessionConfig) {
+    return (await this.client()).listControls(config);
   }
   async listImportableSessions(options?: ListImportableSessionsOptions) {
     return (await this.client()).listImportableSessions(options);
diff --git a/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts b/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts
index 505955f64c..66ee191707 100644
--- a/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts
+++ b/packages/server/src/server/agent/providers/opencode/test-utils/v2-harness.ts
@@ -91,6 +91,7 @@ export class V2Harness {
   readonly api: V2Api = {
     server: { info: unexpected },
     shell: {
+      remove: unexpected,
       list: async () => ({ location: { directory: this.info.location.directory }, data: [] }),
     },
     plugin: {
@@ -172,6 +173,9 @@ export class V2Harness {
     event: { subscribe: (options) => this.events(options?.signal) },
   };
   readonly connection: V2Connection = {
+    bindSession: async () => {},
+    unbindSession: async () => {},
+    refreshLocation: async () => {},
     client: this.api,
     release: async () => {
       this.releases += 1;
diff --git a/packages/server/src/server/agent/providers/opencode/tool-call-detail-parser.ts b/packages/server/src/server/agent/providers/opencode/tool-call-detail-parser.ts
index b3eb432f86..990c5713c6 100644
--- a/packages/server/src/server/agent/providers/opencode/tool-call-detail-parser.ts
+++ b/packages/server/src/server/agent/providers/opencode/tool-call-detail-parser.ts
@@ -20,6 +20,7 @@ import {
   toShellToolDetail,
   toWriteToolDetail,
   toolDetailBranchByToolName,
+  parseKnownToolDetail,
 } from "../tool-call-detail-primitives.js";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -366,13 +367,13 @@ export function deriveOpencodeToolDetail(
     }
   }
 
-  const parsed = OpencodeKnownToolDetailSchema.safeParse({
+  const detail = parseKnownToolDetail(OpencodeKnownToolDetailSchema, {
     toolName,
-    input,
+    input: input ?? null,
     output,
   });
-  if (parsed.success && parsed.data) {
-    return parsed.data;
+  if (detail) {
+    return detail;
   }
   return {
     type: "unknown",
diff --git a/packages/server/src/server/agent/providers/opencode/tool-call-mapper.test.ts b/packages/server/src/server/agent/providers/opencode/tool-call-mapper.test.ts
index eb38a04ac6..236ec53b5d 100644
--- a/packages/server/src/server/agent/providers/opencode/tool-call-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/tool-call-mapper.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import { buildToolCallDisplayModel } from "@getpaseo/protocol/tool-call-display";
 import { mapOpencodeToolCall } from "./tool-call-mapper.js";
 
 function expectMapped<T>(item: T | null): T {
@@ -11,6 +12,33 @@ function expectMapped<T>(item: T | null): T {
 }
 
 describe("opencode tool-call mapper", () => {
+  // OpenCode reports a tool part as `pending` with `input: {}` before the running part carries input.
+  it.each([
+    { toolName: "bash", input: { command: "echo hi" }, title: "Shell" },
+    { toolName: "read", input: { filePath: "/tmp/a.ts" }, title: "Read" },
+    { toolName: "grep", input: { pattern: "foo" }, title: "Search" },
+  ])("keeps the $toolName title and detail kind from the pending part", (tool) => {
+    const stages = [
+      { status: "pending", input: {} },
+      { status: "running", input: tool.input },
+    ].map((stage) =>
+      expectMapped(
+        mapOpencodeToolCall({
+          toolName: tool.toolName,
+          callId: "opencode-stream-1",
+          ...stage,
+          output: null,
+        }),
+      ),
+    );
+
+    expect(stages.map((item) => buildToolCallDisplayModel(item).displayName)).toEqual([
+      tool.title,
+      tool.title,
+    ]);
+    expect(new Set(stages.map((item) => item.detail.type)).size).toBe(1);
+  });
+
   it("maps running shell calls", () => {
     const item = expectMapped(
       mapOpencodeToolCall({
diff --git a/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts b/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts
index 564e1f46c5..58e9ffaefb 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/agent.test.ts
@@ -17,6 +17,98 @@ function terminalEvents(events: AgentStreamEvent[]) {
 }
 
 describe("OpenCode v2 session lifecycle", () => {
+  test("refreshes the existing location before reading a forced catalog", async () => {
+    const harness = new V2Harness();
+    const refreshed: string[] = [];
+    harness.connection.refreshLocation = async (directory) => {
+      refreshed.push(directory);
+    };
+    harness.api.model.list = async () => ({ location: harness.info.location, data: [] });
+    harness.api.provider.list = async () => ({
+      location: harness.info.location,
+      data: [{ id: "test", name: "Test", activation: "enabled", package: "test" }],
+    });
+    const client = new OpenCodeV2AgentClient({
+      logger: createTestLogger(),
+      runtime: harness.runtime,
+    });
+    await client.fetchCatalog({ scope: "workspace", cwd: "/tmp/project", force: true });
+    await client.fetchCatalog({ scope: "workspace", cwd: "/tmp/project", force: false });
+    expect(refreshed).toEqual(["/tmp/project"]);
+    await client.shutdown();
+  });
+  test("rejects a live auto_accept the creation schema would reject", async () => {
+    const harness = new V2Harness();
+    const client = new OpenCodeV2AgentClient({
+      logger: createTestLogger(),
+      runtime: harness.runtime,
+    });
+    const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+
+    await expect(session.applyOptions?.({ auto_accept: "yes" })).rejects.toThrow(/auto_accept/);
+    await expect(session.applyOptions?.({ auto_accept: true })).resolves.toBeUndefined();
+    await session.close();
+  });
+
+  test("a rejected auto_accept leaves the running session asking for permission", async () => {
+    const harness = new V2Harness();
+    const permissions = [
+      { id: "approval", sessionID: "session", action: "shell", resources: ["pwd"] },
+    ];
+    harness.api.permission.list = async () => permissions;
+    const replies: string[] = [];
+    harness.api.permission.reply = async (input) => {
+      replies.push(input.requestID);
+      throw new Error("upstream refused");
+    };
+    const client = new OpenCodeV2AgentClient({
+      logger: createTestLogger(),
+      runtime: harness.runtime,
+    });
+    const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+    try {
+      await expect(session.applyOptions?.({ auto_accept: true })).rejects.toThrow(
+        "upstream refused",
+      );
+
+      const next = {
+        id: "next",
+        sessionID: "session",
+        action: "shell",
+        resources: ["ls"],
+      };
+      permissions.push(next);
+      harness.push({ id: "asked", created: 2, type: "permission.asked", data: next });
+
+      const pendingIds = () => session.getPendingPermissions().map(({ id }) => id);
+      await expect.poll(pendingIds).toContain("next");
+      expect(replies).not.toContain("next");
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("rejects a live permission change the running session cannot apply", async () => {
+    const harness = new V2Harness();
+    const client = new OpenCodeV2AgentClient({
+      logger: createTestLogger(),
+      runtime: harness.runtime,
+    });
+    const session = await client.createSession({
+      provider: "opencode",
+      cwd: "/tmp/project",
+      providerOptions: { permission: "allow" },
+    });
+
+    await expect(session.applyOptions?.({ permission: "deny" })).rejects.toThrow(
+      /permission.*cannot change on a running session/,
+    );
+    await expect(
+      session.applyOptions?.({ permission: "allow", auto_accept: true }),
+    ).resolves.toBeUndefined();
+    await session.close();
+  });
+
   test("completes from execution events without a long-lived HTTP wait", async () => {
     const harness = new V2Harness();
     harness.prompt = async (input) => {
@@ -1181,3 +1273,773 @@ test("OpenCode v2 runtime safety follows descendant locations before releasing t
     await session.close();
   }
 });
+
+test("reconstructs only promoted session-owned running shells and reconciles exits", async () => {
+  const harness = new V2Harness();
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: [
+      {
+        type: "tool",
+        id: "tool",
+        name: "shell",
+        time: { created: 1 },
+        state: {
+          status: "completed",
+          input: { description: "Watch tests", command: "sleep ours" },
+          content: [{ type: "text", text: "" }],
+          metadata: { status: "running", shellID: "ours" },
+        },
+      },
+    ],
+  });
+  harness.api.message.list = async (input) =>
+    input.cursor
+      ? { data: [...harness.history], cursor: {} }
+      : { data: [], cursor: { next: "second-page" } };
+  let live = ["ours", "other"];
+  harness.api.shell.list = async () => ({
+    location: harness.info.location,
+    data: live.map((id) => ({
+      id,
+      status: "running" as const,
+      command: `sleep ${id}`,
+      cwd: "/tmp/project",
+      shell: "sh",
+      file: "sh",
+      metadata: { sessionID: id === "ours" ? harness.info.id : "other" },
+      time: { started: 1 },
+    })),
+  });
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({
+        items: [{ id: "ours", kind: "shell", description: "Watch tests", command: "sleep ours" }],
+      });
+    live = [];
+    harness.push({ id: "reconnect", created: 2, type: "server.connected", data: {} });
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [] });
+  } finally {
+    await session.close();
+  }
+});
+
+test("an exit received during shell listing cannot restore an old row", async () => {
+  const harness = new V2Harness();
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: [
+      {
+        type: "tool",
+        id: "tool",
+        name: "shell",
+        time: { created: 1 },
+        state: {
+          status: "completed",
+          input: {},
+          content: [{ type: "text", text: "" }],
+          metadata: { status: "running", shellID: "shell" },
+        },
+      },
+    ],
+  });
+  const shell = {
+    id: "shell",
+    status: "running" as const,
+    command: "sleep 120",
+    cwd: "/tmp/project",
+    shell: "sh",
+    file: "sh",
+    metadata: { sessionID: harness.info.id },
+    time: { started: 1 },
+  };
+  let listCount = 0;
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  harness.api.shell.list = async () => {
+    listCount++;
+    if (listCount === 2) {
+      await gate;
+      return { location: harness.info.location, data: [shell] };
+    }
+    return { location: harness.info.location, data: [] };
+  };
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    harness.push({ id: "created", created: 2, type: "shell.created", data: { info: shell } });
+    await expect.poll(() => listCount).toBe(2);
+    harness.push({
+      id: "exited",
+      created: 3,
+      type: "shell.exited",
+      data: { id: "shell", status: "exited" },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    release();
+    await expect.poll(() => listCount).toBeGreaterThan(2);
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [] });
+    expect(events.filter((event) => event.type === "background_work")).not.toContainEqual(
+      expect.objectContaining({ items: [expect.objectContaining({ id: "shell" })] }),
+    );
+  } finally {
+    release();
+    await session.close();
+  }
+});
+
+test("does not publish a shell list from a lost server generation", async () => {
+  const harness = new V2Harness();
+  let exit!: (error: Error) => void;
+  Object.assign(harness.connection, {
+    exited: new Promise<Error>((resolve) => {
+      exit = resolve;
+    }),
+  });
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: [
+      {
+        type: "tool",
+        id: "tool",
+        name: "shell",
+        time: { created: 1 },
+        state: {
+          status: "completed",
+          input: {},
+          content: [{ type: "text", text: "" }],
+          metadata: { status: "running", shellID: "old" },
+        },
+      },
+    ],
+  });
+  const shell = {
+    id: "old",
+    status: "running" as const,
+    command: "sleep 120",
+    cwd: "/tmp/project",
+    shell: "sh",
+    file: "sh",
+    metadata: { sessionID: harness.info.id },
+    time: { started: 1 },
+  };
+  let reads = 0;
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  harness.api.shell.list = async () => {
+    reads++;
+    if (reads === 2) {
+      await gate;
+      return { location: harness.info.location, data: [shell] };
+    }
+    return { location: harness.info.location, data: [] };
+  };
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    harness.push({ id: "created", created: 2, type: "shell.created", data: { info: shell } });
+    await expect.poll(() => reads).toBe(2);
+    exit(new Error("server exited"));
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: null });
+    release();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(events.filter((event) => event.type === "background_work")).not.toContainEqual(
+      expect.objectContaining({ items: [expect.objectContaining({ id: "old" })] }),
+    );
+  } finally {
+    release();
+    await session.close();
+  }
+});
+
+test("polls a live shell without rereading conversation history", async () => {
+  const harness = new V2Harness();
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: [
+      {
+        type: "tool",
+        id: "tool",
+        name: "shell",
+        time: { created: 1 },
+        state: {
+          status: "completed",
+          input: {},
+          content: [{ type: "text", text: "" }],
+          metadata: { status: "running", shellID: "live" },
+        },
+      },
+    ],
+  });
+  let historyReads = 0;
+  let shellReads = 0;
+  const readHistory = harness.api.message.list;
+  harness.api.message.list = async (...args) => {
+    historyReads++;
+    return readHistory(...args);
+  };
+  harness.api.shell.list = async () => {
+    shellReads++;
+    return {
+      location: harness.info.location,
+      data: [
+        {
+          id: "live",
+          status: "running",
+          command: "sleep 120",
+          cwd: "/tmp/project",
+          shell: "sh",
+          file: "sh",
+          metadata: { sessionID: harness.info.id },
+          time: { started: 1 },
+        },
+      ],
+    };
+  };
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [{ id: "live" }] });
+    const initialHistoryReads = historyReads;
+    const initialShellReads = shellReads;
+    await expect.poll(() => shellReads, { timeout: 7000 }).toBeGreaterThan(initialShellReads);
+    expect(historyReads).toBe(initialHistoryReads);
+  } finally {
+    await session.close();
+  }
+}, 12000);
+
+test("buffers tool promotion and shell events during background history bootstrap", async () => {
+  const harness = new V2Harness();
+  let historyReads = 0;
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  harness.api.message.list = async () => {
+    historyReads++;
+    if (historyReads === 3) await gate;
+    return { data: [], cursor: {} };
+  };
+  const shell = {
+    id: "promoted",
+    status: "running" as const,
+    command: "sleep 120",
+    cwd: "/tmp/project",
+    shell: "sh",
+    file: "sh",
+    metadata: { sessionID: harness.info.id },
+    time: { started: 1 },
+  };
+  harness.api.shell.list = async () => ({ location: harness.info.location, data: [shell] });
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await expect.poll(() => historyReads).toBeGreaterThanOrEqual(3);
+    harness.push({
+      id: "input",
+      created: 2,
+      type: "session.tool.input.started",
+      durable: { aggregateID: harness.info.id, seq: 1, version: 1 },
+      data: { sessionID: harness.info.id, assistantMessageID: "msg", id: "tool", name: "shell" },
+    });
+    harness.push({
+      id: "input-ended",
+      created: 3,
+      type: "session.tool.input.ended",
+      durable: { aggregateID: harness.info.id, seq: 2, version: 1 },
+      data: {
+        sessionID: harness.info.id,
+        assistantMessageID: "msg",
+        id: "tool",
+        text: JSON.stringify({ description: "Watch tests", command: "sleep 120" }),
+      },
+    });
+    harness.push({ id: "created", created: 3, type: "shell.created", data: { info: shell } });
+    harness.push({
+      id: "success",
+      created: 4,
+      type: "session.tool.success",
+      durable: { aggregateID: harness.info.id, seq: 3, version: 2 },
+      data: {
+        sessionID: harness.info.id,
+        assistantMessageID: "msg",
+        id: "tool",
+        executed: true,
+        content: [{ type: "text", text: "" }],
+        metadata: { status: "running", shellID: "promoted" },
+      },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(events.filter((event) => event.type === "background_work")).toEqual([]);
+    release();
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({
+        items: [{ id: "promoted", description: "Watch tests", command: "sleep 120" }],
+      });
+    harness.push({
+      id: "next-input",
+      created: 5,
+      type: "session.tool.input.started",
+      durable: { aggregateID: harness.info.id, seq: 4, version: 1 },
+      data: { sessionID: harness.info.id, assistantMessageID: "next", id: "tool", name: "shell" },
+    });
+    harness.push({
+      id: "next-success",
+      created: 6,
+      type: "session.tool.success",
+      durable: { aggregateID: harness.info.id, seq: 5, version: 2 },
+      data: {
+        sessionID: harness.info.id,
+        assistantMessageID: "next",
+        id: "tool",
+        executed: true,
+        content: [{ type: "text", text: "" }],
+        metadata: { status: "running", shellID: "second" },
+      },
+    });
+    harness.api.shell.list = async () => ({
+      location: harness.info.location,
+      data: [shell, { ...shell, id: "second" }],
+    });
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [{ id: "promoted" }, { id: "second" }] });
+  } finally {
+    release();
+    await session.close();
+  }
+});
+
+test("retries failed background bootstrap and roster without losing stale work", async () => {
+  const { vi } = await import("vitest");
+  vi.useFakeTimers();
+  try {
+    const { OpenCodeBackgroundInventory } = await import("./background-inventory.js");
+    const harness = new V2Harness();
+    harness.history.push({
+      id: "assistant",
+      type: "assistant",
+      agent: "build",
+      model: { providerID: "test", modelID: "test" },
+      time: { created: 1 },
+      content: [
+        {
+          type: "tool",
+          id: "tool",
+          name: "shell",
+          time: { created: 1 },
+          state: {
+            status: "completed",
+            input: {},
+            content: [{ type: "text", text: "" }],
+            metadata: { status: "running", shellID: "live" },
+          },
+        },
+      ],
+    });
+    let historyCalls = 0;
+    let shellCalls = 0;
+    let historyFails = true;
+    let shellFails = true;
+    harness.api.message.list = async () => {
+      historyCalls++;
+      if (historyFails) throw new Error("history unavailable");
+      return { data: harness.history, cursor: {} };
+    };
+    harness.api.shell.list = async () => {
+      shellCalls++;
+      if (shellFails) throw new Error("roster unavailable");
+      return {
+        location: harness.info.location,
+        data: [
+          {
+            id: "live",
+            status: "running",
+            command: "sleep 120",
+            cwd: "/tmp/project",
+            shell: "sh",
+            file: "sh",
+            metadata: { sessionID: harness.info.id },
+            time: { started: 1 },
+          },
+        ],
+      };
+    };
+    const inventory = new OpenCodeBackgroundInventory({
+      id: harness.info.id,
+      cwd: "/tmp/project",
+      emit: () => {},
+      report: () => {},
+    });
+    inventory.start(harness.api);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(inventory.snapshot()).toBeNull();
+    historyFails = false;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(historyCalls).toBe(2);
+    expect(shellCalls).toBe(1);
+    expect(inventory.snapshot()).toBeNull();
+    inventory.observe({ id: "deleted", created: 1, type: "shell.deleted", data: { id: "other" } });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(shellCalls).toBe(1);
+    shellFails = false;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(historyCalls).toBe(2);
+    expect(inventory.snapshot()?.items).toMatchObject([{ id: "live", canStop: true }]);
+    historyFails = true;
+    inventory.start(harness.api);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(inventory.snapshot()?.items).toEqual([
+      { id: "live", kind: "shell", description: null, command: "sleep 120" },
+    ]);
+    await expect(inventory.stopItem("live")).rejects.toThrow("no longer available");
+    historyFails = false;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(historyCalls).toBe(4);
+    expect(inventory.snapshot()?.items).toMatchObject([{ id: "live", canStop: true }]);
+    shellFails = true;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(inventory.snapshot()?.items).toMatchObject([{ id: "live" }]);
+    inventory.disconnect();
+    const stoppedCalls = shellCalls;
+    await vi.advanceTimersByTimeAsync(15000);
+    expect(shellCalls).toBe(stoppedCalls);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("does not retry a failed bootstrap from a disconnected generation", async () => {
+  const { vi } = await import("vitest");
+  vi.useFakeTimers();
+  try {
+    const { OpenCodeBackgroundInventory } = await import("./background-inventory.js");
+    const harness = new V2Harness();
+    let reject!: (error: Error) => void;
+    let calls = 0;
+    const response = new Promise<Awaited<ReturnType<typeof harness.api.message.list>>>(
+      (_, fail) => {
+        reject = fail;
+      },
+    );
+    harness.api.message.list = () => {
+      calls++;
+      return response;
+    };
+    const inventory = new OpenCodeBackgroundInventory({
+      id: harness.info.id,
+      cwd: "/tmp/project",
+      emit: () => {},
+      report: () => {},
+    });
+    inventory.start(harness.api);
+    inventory.disconnect();
+    reject(new Error("late failure"));
+    await vi.advanceTimersByTimeAsync(15000);
+    expect(calls).toBe(1);
+    expect(inventory.snapshot()).toBeNull();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("stops a selected promoted shell and retains its sibling", async () => {
+  const harness = new V2Harness();
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: ["one", "two"].map((id) => ({
+      type: "tool" as const,
+      id,
+      name: "shell",
+      time: { created: 1 },
+      state: {
+        status: "completed" as const,
+        input: {},
+        content: [{ type: "text" as const, text: "" }],
+        metadata: { status: "running", shellID: id },
+      },
+    })),
+  });
+  let live = ["one", "two"];
+  harness.api.shell.list = async () => ({
+    location: harness.info.location,
+    data: live.map((id) => ({
+      id,
+      status: "running" as const,
+      command: `sleep ${id}`,
+      cwd: "/tmp/project",
+      shell: "sh",
+      file: "sh",
+      metadata: { sessionID: harness.info.id },
+      time: { started: 1 },
+    })),
+  });
+  harness.api.shell.remove = async ({ id }) => {
+    live = live.filter((entry) => entry !== id);
+    return { data: true };
+  };
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [{ id: "one" }, { id: "two" }] });
+    await session.stopBackgroundWork!("one");
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ id: "two" }],
+    });
+    await expect(session.stopBackgroundWork!("one")).rejects.toThrow();
+  } finally {
+    await session.close();
+  }
+});
+
+test("closing during reconnect does not restart the background inventory", async () => {
+  const harness = new V2Harness();
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  await expect
+    .poll(() => events.findLast((event) => event.type === "background_work"))
+    .toMatchObject({ items: [] });
+  let unblock!: () => void;
+  let entered = false;
+  const blocked = new Promise<void>((resolve) => {
+    unblock = resolve;
+  });
+  harness.connection.bindSession = async () => {
+    entered = true;
+    await blocked;
+  };
+  let reads = 0;
+  const original = harness.api.message.list;
+  harness.api.message.list = (...args) => {
+    reads++;
+    return original(...args);
+  };
+  harness.push({ id: "reconnect-close", created: 2, type: "server.connected", data: {} });
+  await expect.poll(() => entered).toBe(true);
+  const closing = session.close();
+  unblock();
+  await closing;
+  expect(reads).toBe(0);
+});
+
+test("keeps a shell available when its stop request times out", async () => {
+  const { vi } = await import("vitest");
+  vi.useFakeTimers();
+  try {
+    const { OpenCodeBackgroundInventory } = await import("./background-inventory.js");
+    const harness = new V2Harness();
+    harness.history.push({
+      id: "assistant",
+      type: "assistant",
+      agent: "build",
+      model: { providerID: "test", modelID: "test" },
+      time: { created: 1 },
+      content: [
+        {
+          type: "tool",
+          id: "tool",
+          name: "shell",
+          time: { created: 1 },
+          state: {
+            status: "completed",
+            input: {},
+            content: [{ type: "text", text: "" }],
+            metadata: { status: "running", shellID: "live" },
+          },
+        },
+      ],
+    });
+    harness.api.shell.list = async () => ({
+      location: harness.info.location,
+      data: [
+        {
+          id: "live",
+          status: "running",
+          command: "sleep 120",
+          cwd: "/tmp/project",
+          shell: "sh",
+          file: "sh",
+          metadata: { sessionID: harness.info.id },
+          time: { started: 1 },
+        },
+      ],
+    });
+    harness.api.shell.remove = () => new Promise(() => {});
+    const inventory = new OpenCodeBackgroundInventory({
+      id: harness.info.id,
+      cwd: "/tmp/project",
+      emit: () => {},
+      report: () => {},
+    });
+    inventory.start(harness.api);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(inventory.snapshot()?.items).toMatchObject([{ id: "live", canStop: true }]);
+    const result = expect(inventory.stopItem("live")).rejects.toThrow("timed out");
+    await vi.advanceTimersByTimeAsync(10000);
+    await result;
+    expect(inventory.snapshot()?.items).toMatchObject([{ id: "live" }]);
+    inventory.disconnect();
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("keeps a live background shell visible and stoppable after its launch is rewound", async () => {
+  const harness = new V2Harness();
+  harness.history.push({
+    id: "assistant",
+    type: "assistant",
+    agent: "build",
+    model: { providerID: "test", modelID: "test" },
+    time: { created: 1 },
+    content: [
+      {
+        type: "tool",
+        id: "tool",
+        name: "shell",
+        time: { created: 1 },
+        state: {
+          status: "completed",
+          input: {},
+          content: [{ type: "text", text: "" }],
+          metadata: { status: "running", shellID: "live" },
+        },
+      },
+    ],
+  });
+  let live = true;
+  harness.api.shell.list = async () => ({
+    location: harness.info.location,
+    data: live
+      ? [
+          {
+            id: "live",
+            status: "running",
+            command: "sleep 180",
+            cwd: "/tmp/project",
+            shell: "sh",
+            file: "sh",
+            metadata: { sessionID: harness.info.id },
+            time: { started: 1 },
+          },
+        ]
+      : [],
+  });
+  harness.api.shell.remove = async () => {
+    live = false;
+    return { data: true };
+  };
+  const client = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: harness.runtime,
+  });
+  const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+  const events: AgentStreamEvent[] = [];
+  session.subscribe((event) => events.push(event));
+  try {
+    await expect
+      .poll(() => events.findLast((event) => event.type === "background_work"))
+      .toMatchObject({ items: [{ id: "live", canStop: true }] });
+    harness.history.length = 0;
+    harness.push({
+      id: "revert",
+      created: 2,
+      type: "session.revert.committed",
+      durable: { aggregateID: harness.info.id, seq: 1, version: 1 },
+      data: { sessionID: harness.info.id, to: "earlier" },
+    });
+    await expect
+      .poll(() => events.filter((event) => event.type === "background_work").length)
+      .toBeGreaterThanOrEqual(3);
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ id: "live", canStop: true }],
+    });
+    harness.push({ id: "reconnect-after-rewind", created: 3, type: "server.connected", data: {} });
+    await expect
+      .poll(() => events.filter((event) => event.type === "background_work").length)
+      .toBeGreaterThanOrEqual(5);
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [{ id: "live", canStop: true }],
+    });
+    await session.stopBackgroundWork!("live");
+    expect(events.findLast((event) => event.type === "background_work")).toMatchObject({
+      items: [],
+    });
+  } finally {
+    await session.close();
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/agent.ts b/packages/server/src/server/agent/providers/opencode/v2/agent.ts
index 2e50e759bd..44b4647955 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/agent.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/agent.ts
@@ -1,14 +1,14 @@
 import { OpenCodeV2Session } from "./session.js";
 import { V2_CAPABILITIES } from "./capabilities.js";
 import {
-  features,
+  controls,
   permissionRules,
   applyResumeOverrides,
   requiresDedicatedV2Server,
 } from "./configuration.js";
 import { commands } from "./commands.js";
 
-import { waitForLocationReady, awaitPaseoPlugin } from "./readiness.js";
+import { waitForLocationReady } from "./readiness.js";
 
 import type { SessionInfo } from "@opencode/client";
 
@@ -17,7 +17,7 @@ import type {
   AgentCapabilityFlags,
   AgentClient,
   AgentCreateSessionOptions,
-  AgentFeature,
+  AgentDraftControls,
   AgentLaunchContext,
   AgentPersistenceHandle,
   AgentSession,
@@ -40,6 +40,7 @@ import { importSessionFromPersistence } from "../../../provider-session-import.j
 import type { OpenCodeBridge } from "../bridge.js";
 import { resolveOpenCodeHomeDir } from "../paths.js";
 import { V2Runtime, type V2Connection } from "./runtime.js";
+import type { OpenCodeServiceSelection } from "./service-selection.js";
 import { modelRef, modesFromV2, modelsFromV2 } from "./mapping.js";
 
 interface V2AgentOptions {
@@ -48,6 +49,7 @@ interface V2AgentOptions {
   managedProcesses?: ManagedProcessRegistry;
   bridge?: OpenCodeBridge;
   runtime?: Pick<V2Runtime, "acquire" | "shutdown">;
+  selection?: OpenCodeServiceSelection;
 }
 
 export class OpenCodeV2AgentClient implements AgentClient {
@@ -56,12 +58,12 @@ export class OpenCodeV2AgentClient implements AgentClient {
   private readonly runtime: Pick<V2Runtime, "acquire" | "shutdown">;
   private readonly connections = new Map<string, V2Connection>();
   constructor(private readonly options: V2AgentOptions) {
-    this.capabilities = { ...V2_CAPABILITIES, supportsNativePaseoTools: Boolean(options.bridge) };
+    const bridge = options.bridge;
+    this.capabilities = { ...V2_CAPABILITIES, supportsNativePaseoTools: Boolean(bridge) };
     this.runtime =
       options.runtime ??
       new V2Runtime({
         ...options,
-        decorateEnv: options.bridge ? (env) => options.bridge!.decorateV2ServerEnv(env) : undefined,
       });
   }
   async isAvailable() {
@@ -85,6 +87,10 @@ export class OpenCodeV2AgentClient implements AgentClient {
       await activity("plugin.list", () =>
         waitForLocationReady({ client: connection.client, location, signal: request.signal }),
       );
+      if (options.force)
+        await activity("paseo.bridge.refresh", () =>
+          connection.refreshLocation(location.directory, request.signal),
+        );
       const [models, agents, providers] = await Promise.all([
         activity("model.list", () => connection.client.model.list({ location }, request)),
         activity("agent.list", () => connection.client.agent.list({ location }, request)),
@@ -163,7 +169,8 @@ export class OpenCodeV2AgentClient implements AgentClient {
         requiresDedicatedV2Server(config, launch) ? { env: launch?.env, dedicated: true } : {},
       );
     let ownedConnection = connection;
-    const unbind = this.options.bridge?.bindSession({
+    const bridge = this.options.bridge;
+    const unbind = bridge?.bindSession({
       sessionId: info.id,
       env: launch?.env ?? {},
       tools: launch?.paseoTools,
@@ -172,7 +179,7 @@ export class OpenCodeV2AgentClient implements AgentClient {
     const bindChild = (childId: string) => {
       this.connections.set(childId, ownedConnection);
       if (bound.has(childId)) return;
-      const childUnbind = this.options.bridge?.bindSession({
+      const childUnbind = bridge?.bindSession({
         sessionId: childId,
         env: launch?.env ?? {},
         tools: launch?.paseoTools,
@@ -204,10 +211,6 @@ export class OpenCodeV2AgentClient implements AgentClient {
       moved,
     );
     try {
-      if (this.options.bridge) {
-        const location = { directory: config.cwd };
-        await awaitPaseoPlugin({ client: connection.client, location });
-      }
       await session.initialize(
         launch?.env
           ? createProviderEnv({ runtimeSettings: this.options.settings, overlays: [launch.env] })
@@ -219,8 +222,8 @@ export class OpenCodeV2AgentClient implements AgentClient {
       throw error;
     }
   }
-  async listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]> {
-    return features(config);
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    return { controls, options: config.providerOptions ?? {} };
   }
   async listCommands(config: AgentSessionConfig) {
     const connection = await this.runtime.acquire();
diff --git a/packages/server/src/server/agent/providers/opencode/v2/api.ts b/packages/server/src/server/agent/providers/opencode/v2/api.ts
index bec40ffbcb..31754eb468 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/api.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/api.ts
@@ -2,7 +2,7 @@ import type { OpenCodeClient } from "@opencode/client";
 
 export interface V2Api {
   server: OpenCodeClient["server"];
-  shell: Pick<OpenCodeClient["shell"], "list">;
+  shell: Pick<OpenCodeClient["shell"], "list" | "remove">;
   session: Pick<
     OpenCodeClient["session"],
     | "create"
diff --git a/packages/server/src/server/agent/providers/opencode/v2/background-inventory.ts b/packages/server/src/server/agent/providers/opencode/v2/background-inventory.ts
new file mode 100644
index 0000000000..9c10a1ce86
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/background-inventory.ts
@@ -0,0 +1,308 @@
+import type { OpenCodeEvent, SessionMessageInfo, ShellInfo } from "@opencode/client";
+import type { AgentStreamEvent } from "../../../agent-sdk-types.js";
+import type { V2Api } from "./api.js";
+import { messages } from "./history.js";
+
+type InventoryEvent = Extract<AgentStreamEvent, { type: "background_work" }>;
+type RelevantEvent = Extract<
+  OpenCodeEvent,
+  {
+    type:
+      | "session.tool.input.started"
+      | "session.tool.input.ended"
+      | "session.tool.success"
+      | "shell.created"
+      | "shell.exited"
+      | "shell.deleted";
+  }
+>;
+
+export class OpenCodeBackgroundInventory {
+  private generation = 0;
+  private client: V2Api | null = null;
+  private loading = false;
+  private pending = false;
+  private dirty = false;
+  private retrying = false;
+  private events: RelevantEvent[] = [];
+  private names = new Map<string, string>();
+  private inputs = new Map<string, unknown>();
+  private descriptions = new Map<string, string>();
+  private promoted = new Set<string>();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private current: InventoryEvent | null = null;
+  private readonly listeners = new Set<() => void>();
+  async stopItem(id: string): Promise<void> {
+    const client = this.client;
+    const generation = this.generation;
+    if (!client || !this.current?.items?.some((item) => item.id === id && item.canStop))
+      throw new Error("Background shell is no longer available");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let disconnected!: () => void;
+    const lost = new Promise<never>((_, reject) => {
+      disconnected = () => {
+        if (generation !== this.generation)
+          reject(new Error("Background shell connection changed"));
+      };
+      this.listeners.add(disconnected);
+      timer = setTimeout(() => reject(new Error("Background shell stop timed out")), 10000);
+    });
+    try {
+      await Promise.race([client.shell.remove({ id, location: { directory: this.cwd } }), lost]);
+    } finally {
+      clearTimeout(timer);
+      this.listeners.delete(disconnected);
+    }
+    if (generation !== this.generation) throw new Error("Background shell connection changed");
+    await new Promise<void>((resolve, reject) => {
+      const confirmationTimer = setTimeout(
+        () => finish(new Error("Background shell confirmation timed out")),
+        15000,
+      );
+      const finish = (error?: Error) => {
+        clearTimeout(confirmationTimer);
+        this.listeners.delete(check);
+        if (error) reject(error);
+        else resolve();
+      };
+      const check = () => {
+        if (generation !== this.generation)
+          finish(new Error("Background shell connection changed"));
+        else if (this.current?.items && !this.current.items.some((item) => item.id === id))
+          finish();
+      };
+      this.listeners.add(check);
+      this.dirty = true;
+      this.refresh();
+    });
+  }
+  private notify() {
+    for (const listener of this.listeners) listener();
+  }
+  constructor(options: {
+    id: string;
+    cwd: string;
+    emit: (event: InventoryEvent) => void;
+    report: (error: unknown) => void;
+  }) {
+    this.id = options.id;
+    this.cwd = options.cwd;
+    this.emit = options.emit;
+    this.report = options.report;
+  }
+  private readonly id: string;
+  private readonly cwd: string;
+  private readonly emit: (event: InventoryEvent) => void;
+  private readonly report: (error: unknown) => void;
+  snapshot() {
+    return this.current;
+  }
+  start(client: V2Api) {
+    this.disconnect();
+    this.client = client;
+    this.loading = true;
+    this.events = [];
+    const generation = this.generation;
+    void this.bootstrap(client, generation);
+  }
+  disconnect(lost = false) {
+    this.generation++;
+    this.notify();
+    this.client = null;
+    this.loading = false;
+    this.pending = false;
+    this.dirty = false;
+    this.retrying = false;
+    this.events = [];
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    if (lost) {
+      this.promoted.clear();
+      this.descriptions.clear();
+      this.current = null;
+      this.emit({ type: "background_work", provider: "opencode", items: null });
+    } else if (this.current?.items?.some((item) => item.canStop)) {
+      // Keep stale rows visible, but revoke their stop tokens until this generation's
+      // roster confirms ownership again.
+      const items = this.current.items.map((item) => ({
+        id: item.id,
+        kind: item.kind,
+        description: item.description,
+        ...(item.command ? { command: item.command } : {}),
+      }));
+      this.current = { type: "background_work", provider: "opencode", items };
+      this.emit(this.current);
+    }
+  }
+  private async bootstrap(client: V2Api, generation: number) {
+    try {
+      const history = await messages(client, this.id);
+      if (generation !== this.generation) return;
+      this.names = new Map();
+      this.inputs = new Map();
+      // Rewinds can remove launch messages without stopping the shell. Keep known
+      // promotions until the current provider roster confirms they are gone.
+      this.readHistory(history);
+      for (const event of this.events) this.apply(event);
+      this.events = [];
+      this.loading = false;
+      this.dirty = true;
+      this.refresh();
+    } catch (error) {
+      if (generation === this.generation) {
+        this.report(error);
+        this.schedule(() => void this.bootstrap(client, generation), true);
+      }
+    }
+  }
+  private readHistory(history: readonly SessionMessageInfo[]) {
+    for (const message of history) {
+      if (message.type !== "assistant") continue;
+      for (const part of message.content) {
+        if (part.type !== "tool") continue;
+        if (part.state.status === "completed") {
+          if (part.name === "shell") this.promote(part.state.metadata, part.state.input);
+        } else if (part.state.status !== "error") {
+          const key = `${message.id}:${part.id}`;
+          this.names.set(key, part.name);
+          if (part.name === "shell") this.inputs.set(key, part.state.input);
+        }
+      }
+    }
+  }
+  private promote(metadata: { [key: string]: unknown } | undefined, input?: unknown) {
+    if (metadata?.status === "running" && typeof metadata.shellID === "string") {
+      this.promoted.add(metadata.shellID);
+      if (
+        input &&
+        typeof input === "object" &&
+        "description" in input &&
+        typeof input.description === "string" &&
+        input.description.trim()
+      )
+        this.descriptions.set(metadata.shellID, input.description.trim());
+    }
+  }
+  observe(event: OpenCodeEvent) {
+    if (event.type === "session.revert.committed" && event.data.sessionID === this.id) {
+      if (this.client) this.start(this.client);
+      return;
+    }
+    if (
+      event.type !== "shell.created" &&
+      event.type !== "shell.exited" &&
+      event.type !== "shell.deleted" &&
+      event.type !== "session.tool.input.started" &&
+      event.type !== "session.tool.input.ended" &&
+      event.type !== "session.tool.success"
+    )
+      return;
+    if ("sessionID" in event.data && event.data.sessionID !== this.id) return;
+    if (!this.client) return;
+    if (this.loading) {
+      this.events.push(event);
+      return;
+    }
+    this.apply(event);
+    if (event.type !== "session.tool.input.started" && event.type !== "session.tool.input.ended") {
+      this.dirty = true;
+      if (!this.retrying) this.refresh();
+    }
+  }
+  private apply(event: RelevantEvent) {
+    if (event.type === "session.tool.input.started")
+      this.names.set(`${event.data.assistantMessageID}:${event.data.id}`, event.data.name);
+    if (
+      event.type === "session.tool.input.ended" &&
+      this.names.get(`${event.data.assistantMessageID}:${event.data.id}`) === "shell"
+    ) {
+      try {
+        this.inputs.set(
+          `${event.data.assistantMessageID}:${event.data.id}`,
+          JSON.parse(event.data.text),
+        );
+      } catch {
+        /* A malformed tool input supplies no presentation metadata. */
+      }
+    }
+    if (
+      event.type === "session.tool.success" &&
+      this.names.get(`${event.data.assistantMessageID}:${event.data.id}`) === "shell"
+    )
+      this.promote(
+        event.data.metadata,
+        this.inputs.get(`${event.data.assistantMessageID}:${event.data.id}`),
+      );
+    if (event.type === "session.tool.success") {
+      this.names.delete(`${event.data.assistantMessageID}:${event.data.id}`);
+      this.inputs.delete(`${event.data.assistantMessageID}:${event.data.id}`);
+    }
+  }
+  private refresh() {
+    if (!this.client || this.loading || this.pending) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.pending = true;
+    this.dirty = false;
+    const generation = this.generation;
+    const client = this.client;
+    let failed = false;
+    void client.shell
+      .list({ location: { directory: this.cwd } })
+      .then((result) => {
+        if (generation !== this.generation || this.dirty) return undefined;
+        this.publish(result.data);
+        return undefined;
+      })
+      .catch((error: unknown) => {
+        if (generation === this.generation) {
+          failed = true;
+          this.report(error);
+        }
+      })
+      .finally(() => {
+        if (generation !== this.generation) return;
+        this.pending = false;
+        if (this.dirty && !failed) this.refresh();
+        else if (failed || this.current?.items?.length) this.schedule(() => this.refresh(), failed);
+      });
+  }
+  private schedule(callback: () => void, retry = false) {
+    this.retrying = retry;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.retrying = false;
+      callback();
+    }, 5000);
+    this.timer.unref();
+  }
+  private publish(shells: ShellInfo[]) {
+    const live = new Set(
+      shells
+        .filter((shell) => shell.status === "running" && shell.metadata.sessionID === this.id)
+        .map((shell) => shell.id),
+    );
+    this.promoted = new Set([...this.promoted].filter((id) => live.has(id)));
+    for (const id of this.descriptions.keys()) if (!live.has(id)) this.descriptions.delete(id);
+    this.current = {
+      type: "background_work",
+      provider: "opencode",
+      items: shells
+        .filter(
+          (shell) =>
+            shell.status === "running" &&
+            shell.metadata.sessionID === this.id &&
+            this.promoted.has(shell.id),
+        )
+        .map((shell) => ({
+          id: shell.id,
+          kind: "shell",
+          description: this.descriptions.get(shell.id) ?? null,
+          command: shell.command || undefined,
+          canStop: true,
+        })),
+    };
+    this.emit(this.current);
+    this.notify();
+  }
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs b/packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs
index 1664c0b59f..6971a5b323 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs
+++ b/packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs
@@ -1,100 +1,15 @@
-import { registerStructuredOutput, STRUCTURED_OUTPUT_TOOL } from "./structured-output-plugin.mjs";
+import { registerStructuredOutput } from "./structured-output-plugin.mjs";
+import { registerSharedBridge } from "./shared-bridge-plugin.mjs";
 
 export default {
   id: "paseo",
   async setup(context) {
     const disposeStructuredOutput = await registerStructuredOutput(context);
-    const { baseUrl, token } = context.options;
-    if (!baseUrl || !token) return disposeStructuredOutput;
-    async function request(pathname, body, allowMissing = false) {
-      const response = await fetch(new URL(`/_internal/opencode${pathname}`, baseUrl), {
-        method: body === undefined ? "GET" : "POST",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      });
-      if (allowMissing && response.status === 404) return null;
-      if (!response.ok) {
-        const payload = await response.json().catch(() => null);
-        const detail = formatErrorDetail(payload?.issues ?? payload?.details);
-        const message =
-          typeof payload?.error === "string" && payload.error
-            ? payload.error
-            : `Paseo tool bridge returned HTTP ${response.status}`;
-        const error = new Error(detail ? `${message}: ${detail}` : message);
-        error.status = response.status;
-        if (detail) error.details = detail;
-        throw error;
-      }
-      return response.json();
-    }
-    async function scope(sessionID) {
-      const visited = new Set();
-      while (sessionID && !visited.has(sessionID)) {
-        visited.add(sessionID);
-        const binding = await request(
-          `/sessions/${encodeURIComponent(sessionID)}/context?tools`,
-          undefined,
-          true,
-        );
-        if (binding) return { ...binding, sessionID };
-        const session = await context.session.get({ sessionID });
-        sessionID = session.parentID;
-      }
-      throw new Error("OpenCode session is not bound to a Paseo agent");
-    }
-    const manifest = await request("/tools");
-    const registration = await context.tool.transform((editor) => {
-      for (const definition of manifest.tools) {
-        editor.add({
-          name: `paseo_${definition.name}`,
-          description: definition.description,
-          input: definition.inputSchema,
-          options: { codemode: false },
-          async execute(input, call) {
-            const binding = await scope(call.sessionID);
-            const result = await request(
-              `/sessions/${encodeURIComponent(binding.sessionID)}/tools/${encodeURIComponent(definition.name)}`,
-              input,
-            );
-            return {
-              content: result.content.map(toOpenCodeContent),
-              metadata: { paseoTool: definition.name },
-            };
-          },
-        });
-      }
-    });
-    const filtering = await context.session.hook("context", async (input) => {
-      const binding = await scope(input.sessionID);
-      const allowed = new Set(binding.tools.map((name) => `paseo_${name}`));
-      for (const name of Object.keys(input.tools)) {
-        if (name !== STRUCTURED_OUTPUT_TOOL && name.startsWith("paseo_") && !allowed.has(name))
-          delete input.tools[name];
-      }
-    });
+    if (context.options.mode === "structured-only") return disposeStructuredOutput;
+    const disposeBridge = await registerSharedBridge(context);
     return async () => {
+      await disposeBridge();
       await disposeStructuredOutput();
-      await filtering.dispose();
-      await registration.dispose();
     };
   },
 };
-
-function formatErrorDetail(details) {
-  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
-  return details
-    .map((issue) => {
-      const path =
-        Array.isArray(issue?.path) && issue.path.length > 0 ? issue.path.join(".") : "input";
-      return `${path}: ${issue?.message ?? "Invalid value"}`;
-    })
-    .join("; ");
-}
-
-// OpenCode tool content is text or a file; MCP images arrive as base64 data.
-function toOpenCodeContent(part) {
-  if (part.type === "image") {
-    return { type: "file", uri: `data:${part.mimeType};base64,${part.data}`, mime: part.mimeType };
-  }
-  return part;
-}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.test.ts b/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.test.ts
new file mode 100644
index 0000000000..52b483cca3
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.test.ts
@@ -0,0 +1,37 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { hasManagedBridge, provisionLocalBridge } from "./bridge-provisioning.js";
+
+test("installs a watched plugin without changing existing OpenCode configuration", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-opencode-provision-"));
+  const source = path.join(root, "source.js");
+  const config = path.join(root, "opencode.json");
+  await writeFile(source, "export default { id: 'paseo' };");
+  await writeFile(path.join(root, "state.mjs"), "export const state = new Map();");
+  await writeFile(config, '{"plugins":["existing"]}\n');
+  try {
+    expect(await hasManagedBridge(root)).toBe(false);
+    await Promise.all([
+      provisionLocalBridge({ configDirectory: root, artifact: source }),
+      provisionLocalBridge({ configDirectory: root, artifact: source }),
+    ]);
+    expect(await hasManagedBridge(root)).toBe(true);
+    const manifest = path.join(root, "plugins/paseo-managed-bridge/package.json");
+    const formatted = `${JSON.stringify(JSON.parse(await readFile(manifest, "utf8")), null, 2)}\n`;
+    await writeFile(manifest, formatted);
+    expect(await hasManagedBridge(root)).toBe(true);
+    await provisionLocalBridge({ configDirectory: root, artifact: source });
+    expect(await readFile(manifest, "utf8")).toBe(formatted);
+    expect(await readFile(config, "utf8")).toBe('{"plugins":["existing"]}\n');
+    expect(await readFile(path.join(root, "plugins/paseo-managed-bridge/state.mjs"), "utf8")).toBe(
+      "export const state = new Map();",
+    );
+    expect(
+      await readFile(path.join(root, "plugins/paseo-managed-bridge/server.js"), "utf8"),
+    ).toContain("id: 'paseo'");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.ts b/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.ts
new file mode 100644
index 0000000000..ce2626c38b
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/bridge-provisioning.ts
@@ -0,0 +1,89 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { writeFileAtomic } from "../../../../atomic-file.js";
+
+const PACKAGE = JSON.stringify({
+  name: "paseo-managed-bridge",
+  private: true,
+  type: "module",
+  exports: { "./server": "./server.js" },
+});
+
+export function openCodeConfigDirectory(env: NodeJS.ProcessEnv): string {
+  return (
+    env.OPENCODE_CONFIG_DIR ??
+    path.join(env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config"), "opencode")
+  );
+}
+
+export async function hasManagedBridge(configDirectory: string): Promise<boolean> {
+  const directory = path.join(configDirectory, "plugins", "paseo-managed-bridge");
+  const [manifest, artifact] = await Promise.all([
+    readFile(path.join(directory, "package.json"), "utf8").catch(() => ""),
+    readFile(path.join(directory, "server.js")).catch(() => undefined),
+  ]);
+  return isManagedPackage(manifest) && Boolean(artifact?.length);
+}
+
+export async function provisionLocalBridge(input: {
+  configDirectory: string;
+  artifact: string;
+}): Promise<void> {
+  const directory = path.join(input.configDirectory, "plugins", "paseo-managed-bridge");
+  await mkdir(path.dirname(directory), { recursive: true });
+  let created = false;
+  try {
+    await mkdir(directory);
+    created = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const manifest = path.join(directory, "package.json");
+  if (created) await writeFileAtomic(manifest, PACKAGE);
+  else if (!isManagedPackage(await readManagedManifest(manifest)))
+    throw new Error(`Cannot install OpenCode bridge: ${directory} is not managed by Paseo`);
+  const artifact = await readFile(input.artifact);
+  const state = await readFile(path.join(path.dirname(input.artifact), "state.mjs"));
+  const stateTarget = path.join(directory, "state.mjs");
+  const existingState = await readFile(stateTarget).catch(() => undefined);
+  if (!existingState) await writeFileAtomic(stateTarget, state);
+  else if (!existingState.equals(state))
+    throw new Error(`Cannot update OpenCode bridge state module at ${stateTarget}`);
+  const target = path.join(directory, "server.js");
+  const existing = await readFile(target).catch(() => undefined);
+  if (!existing?.equals(artifact)) await writeFileAtomic(target, artifact);
+}
+
+function isManagedPackage(content: string): boolean {
+  let value: unknown;
+  try {
+    value = JSON.parse(content);
+  } catch {
+    return false;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const manifest = value as Record<string, unknown>;
+  if (!manifest.exports || typeof manifest.exports !== "object" || Array.isArray(manifest.exports))
+    return false;
+  const exports = manifest.exports as Record<string, unknown>;
+  return (
+    manifest.name === "paseo-managed-bridge" &&
+    manifest.private === true &&
+    manifest.type === "module" &&
+    exports["./server"] === "./server.js"
+  );
+}
+
+async function readManagedManifest(file: string): Promise<string> {
+  for (let attempt = 0; attempt < 20; attempt++) {
+    try {
+      return await readFile(file, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      await delay(25);
+    }
+  }
+  return "";
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/configuration.test.ts b/packages/server/src/server/agent/providers/opencode/v2/configuration.test.ts
index 6479ca3851..a5b26c7336 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/configuration.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/configuration.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 
-import { features, permissionRules, requiresDedicatedV2Server } from "./configuration.js";
+import { controls, permissionRules, requiresDedicatedV2Server } from "./configuration.js";
 
 describe("OpenCode v2 permission rules", () => {
   test("maps authored native permissions and exact injected MCP grants", () => {
@@ -24,7 +24,14 @@ describe("OpenCode v2 helper isolation", () => {
     expect(
       requiresDedicatedV2Server(
         { provider: "opencode", cwd: "/tmp/project" },
-        { agentId: "agent", env: { PASEO_AGENT_ID: "agent", PASEO_AGENT_CWD: "/tmp/project" } },
+        {
+          agentId: "agent",
+          env: {
+            PASEO_AGENT_ID: "agent",
+            PASEO_AGENT_CWD: "/tmp/project",
+            PASEO_WORKSPACE_ID: "ws-1",
+          },
+        },
       ),
     ).toBe(false);
   });
@@ -49,17 +56,8 @@ describe("OpenCode v2 helper isolation", () => {
   });
 });
 
-describe("OpenCode v2 features", () => {
-  test("reports the auto-accept toggle from the session value", () => {
-    expect(features({ provider: "opencode", cwd: "/tmp/project" })).toEqual([
-      { type: "toggle", id: "auto_accept", label: "Auto-accept", value: false },
-    ]);
-    expect(
-      features({
-        provider: "opencode",
-        cwd: "/tmp/project",
-        featureValues: { auto_accept: true },
-      }),
-    ).toEqual([{ type: "toggle", id: "auto_accept", label: "Auto-accept", value: true }]);
+describe("OpenCode v2 controls", () => {
+  test("describes the auto-accept toggle over the auto_accept option", () => {
+    expect(controls).toEqual([{ type: "toggle", key: "auto_accept", label: "Auto-accept" }]);
   });
 });
diff --git a/packages/server/src/server/agent/providers/opencode/v2/configuration.ts b/packages/server/src/server/agent/providers/opencode/v2/configuration.ts
index 9a565e6fca..a2a27e6fc6 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/configuration.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/configuration.ts
@@ -2,8 +2,8 @@ import type { SessionInfo, PermissionRuleset } from "@opencode/client";
 import type { V2Api } from "./api.js";
 
 import type {
-  AgentFeature,
   AgentLaunchContext,
+  AgentOptionControl,
   AgentSessionConfig,
 } from "../../../agent-sdk-types.js";
 
@@ -11,16 +11,9 @@ import { OpenCodeProviderOptionsSchema, buildOpenCodePermissionRules } from "../
 
 import { modelRef } from "./mapping.js";
 
-export function features(config: AgentSessionConfig): AgentFeature[] {
-  return [
-    {
-      type: "toggle",
-      id: "auto_accept",
-      label: "Auto-accept",
-      value: config.featureValues?.["auto_accept"] === true,
-    },
-  ];
-}
+export const controls: AgentOptionControl[] = [
+  { type: "toggle", key: "auto_accept", label: "Auto-accept" },
+];
 export function permissionRules(config: AgentSessionConfig): PermissionRuleset {
   const rules =
     buildOpenCodePermissionRules(
@@ -72,7 +65,7 @@ export async function applyResumeOverrides(
 // it must not force a dedicated server. Custom MCP is location-scoped, and any
 // other env key belongs to the process, so both need isolation. Mirrors the v1
 // adapter's `requiresDedicatedOpenCodeServer`.
-const V2_SESSION_ENV_KEYS = new Set(["PASEO_AGENT_ID", "PASEO_AGENT_CWD"]);
+const V2_SESSION_ENV_KEYS = new Set(["PASEO_AGENT_ID", "PASEO_AGENT_CWD", "PASEO_WORKSPACE_ID"]);
 
 export function requiresDedicatedV2Server(
   config: AgentSessionConfig,
diff --git a/packages/server/src/server/agent/providers/opencode/v2/external-runtime.test.ts b/packages/server/src/server/agent/providers/opencode/v2/external-runtime.test.ts
new file mode 100644
index 0000000000..f4f39f4aeb
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/external-runtime.test.ts
@@ -0,0 +1,180 @@
+import { createServer, type Server } from "node:http";
+import { createServer as createNetServer } from "node:net";
+
+import { afterEach, describe, expect, test } from "vitest";
+
+import { createTestLogger } from "../../../../../test-utils/test-logger.js";
+import { V2Runtime } from "./runtime.js";
+import { EXTERNAL_SERVER_PASSWORD_ENV, EXTERNAL_SERVER_URL_ENV } from "./external-server.js";
+
+function listen(server: Server): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Test server did not expose a TCP address"));
+        return;
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+function close(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+    server.closeAllConnections();
+  });
+}
+
+function reserveClosedPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createNetServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close();
+        reject(new Error("Could not reserve a test port"));
+        return;
+      }
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });
+}
+
+describe("V2Runtime against an external server", () => {
+  let server: Server | undefined;
+
+  afterEach(async () => {
+    if (server) await close(server);
+    server = undefined;
+  });
+
+  test("reuses the configured server and never spawns a local one", async () => {
+    const requests: Array<{ url: string | undefined; authorization: string | undefined }> = [];
+    server = createServer((request, response) => {
+      requests.push({ url: request.url, authorization: request.headers.authorization });
+      if (request.url !== "/api/info") {
+        response.writeHead(404);
+        response.end();
+        return;
+      }
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify({ version: "2.0.10", pid: 1, urls: [], paths: { tmp: "/tmp" } }));
+    });
+    const port = await listen(server);
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      externalServer: { url: `http://127.0.0.1:${port}`, password: "secret" },
+    });
+
+    const first = await runtime.acquire();
+    const second = await runtime.acquire();
+    expect(first.client).toBe(second.client);
+    expect(requests).toEqual([
+      {
+        url: "/api/info",
+        authorization: `Basic ${Buffer.from("opencode:secret").toString("base64")}`,
+      },
+    ]);
+
+    await first.release();
+    await second.release();
+    const refreshed = await runtime.acquire({ fresh: true });
+    expect(refreshed.client).toBe(first.client);
+    await refreshed.release();
+    await runtime.shutdown();
+    expect(requests).toHaveLength(1);
+  });
+
+  test("selects the external server from provider environment", async () => {
+    const paths: Array<string | undefined> = [];
+    server = createServer((request, response) => {
+      paths.push(request.url);
+      if (request.url !== "/api/info") {
+        response.writeHead(404);
+        response.end();
+        return;
+      }
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify({ version: "2.0.10", pid: 1, urls: [], paths: { tmp: "/tmp" } }));
+    });
+    const port = await listen(server);
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      settings: {
+        env: {
+          [EXTERNAL_SERVER_URL_ENV]: `http://127.0.0.1:${port}`,
+          [EXTERNAL_SERVER_PASSWORD_ENV]: "",
+        },
+      },
+    });
+
+    const connection = await runtime.acquire();
+    expect(paths).toEqual(["/api/info"]);
+    await connection.release();
+    await runtime.shutdown();
+  });
+
+  test("reports an unreachable configured server", async () => {
+    const port = await reserveClosedPort();
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      externalServer: { url: `http://127.0.0.1:${port}` },
+    });
+
+    await expect(runtime.acquire()).rejects.toThrow(
+      `Cannot reach OpenCode v2 server at http://127.0.0.1:${port}`,
+    );
+    await runtime.shutdown();
+  });
+
+  test("rejects session configuration that requires process isolation", async () => {
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      externalServer: { url: "http://127.0.0.1:1" },
+    });
+    await expect(runtime.acquire({ dedicated: true })).rejects.toThrow(
+      "require an isolated server",
+    );
+    await runtime.shutdown();
+  });
+
+  test("rejects provider process environment on an explicit server", async () => {
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      externalServer: { url: "http://127.0.0.1:1" },
+      settings: { env: { XDG_CONFIG_HOME: "/custom", PROVIDER_KEY: "secret" } },
+    });
+    await expect(runtime.acquire()).rejects.toThrow("XDG_CONFIG_HOME, PROVIDER_KEY");
+    await runtime.shutdown();
+  });
+
+  test("rejects an unsupported explicit server version", async () => {
+    server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify({ version: "2.0.9", pid: 1, urls: [], paths: { tmp: "/tmp" } }));
+    });
+    const port = await listen(server);
+    const runtime = new V2Runtime({
+      logger: createTestLogger(),
+      externalServer: { url: `http://127.0.0.1:${port}` },
+    });
+    await expect(runtime.acquire()).rejects.toThrow("Unsupported OpenCode version 2.0.9");
+    await runtime.shutdown();
+  });
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/external-server.test.ts b/packages/server/src/server/agent/providers/opencode/v2/external-server.test.ts
new file mode 100644
index 0000000000..f9986215ad
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/external-server.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  EXTERNAL_SERVER_PASSWORD_ENV,
+  EXTERNAL_SERVER_URL_ENV,
+  resolveExternalOpenCodeServer,
+} from "./external-server.js";
+
+describe("resolveExternalOpenCodeServer", () => {
+  test("returns undefined when no URL is configured", () => {
+    expect(resolveExternalOpenCodeServer(undefined)).toBeUndefined();
+    expect(resolveExternalOpenCodeServer({ [EXTERNAL_SERVER_URL_ENV]: "   " })).toBeUndefined();
+  });
+
+  test("reads the URL and password and removes a trailing slash", () => {
+    expect(
+      resolveExternalOpenCodeServer({
+        [EXTERNAL_SERVER_URL_ENV]: " http://127.0.0.1:4096/ ",
+        [EXTERNAL_SERVER_PASSWORD_ENV]: "secret",
+      }),
+    ).toEqual({ url: "http://127.0.0.1:4096", password: "secret" });
+  });
+
+  test("omits an empty password", () => {
+    expect(
+      resolveExternalOpenCodeServer({
+        [EXTERNAL_SERVER_URL_ENV]: "https://opencode.example.com",
+        [EXTERNAL_SERVER_PASSWORD_ENV]: "",
+      }),
+    ).toEqual({ url: "https://opencode.example.com" });
+  });
+
+  test("preserves spaces in the password", () => {
+    expect(
+      resolveExternalOpenCodeServer({
+        [EXTERNAL_SERVER_URL_ENV]: "https://opencode.example.com",
+        [EXTERNAL_SERVER_PASSWORD_ENV]: " secret ",
+      }),
+    ).toEqual({ url: "https://opencode.example.com", password: " secret " });
+  });
+
+  test("rejects relative and non-HTTP URLs", () => {
+    expect(() =>
+      resolveExternalOpenCodeServer({ [EXTERNAL_SERVER_URL_ENV]: "127.0.0.1:4096" }),
+    ).toThrow(`${EXTERNAL_SERVER_URL_ENV} must be an absolute URL, received "127.0.0.1:4096"`);
+    expect(() =>
+      resolveExternalOpenCodeServer({ [EXTERNAL_SERVER_URL_ENV]: "unix:/tmp/opencode.sock" }),
+    ).toThrow(
+      `${EXTERNAL_SERVER_URL_ENV} must use http or https, received "unix:/tmp/opencode.sock"`,
+    );
+  });
+
+  test("rejects credentials embedded in URLs", () => {
+    expect(() =>
+      resolveExternalOpenCodeServer({
+        [EXTERNAL_SERVER_URL_ENV]: "https://user:password@opencode.example.com",
+      }),
+    ).toThrow("must not contain credentials");
+  });
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/external-server.ts b/packages/server/src/server/agent/providers/opencode/v2/external-server.ts
new file mode 100644
index 0000000000..c00b158ce3
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/external-server.ts
@@ -0,0 +1,38 @@
+export const EXTERNAL_SERVER_URL_ENV = "PASEO_OPENCODE_SERVER_URL";
+export const EXTERNAL_SERVER_PASSWORD_ENV = "PASEO_OPENCODE_SERVER_PASSWORD";
+
+export interface ExternalOpenCodeServer {
+  url: string;
+  password?: string;
+}
+
+/**
+ * Reads the optional connection to a user-managed OpenCode v2 server from
+ * provider environment. When absent, Paseo keeps spawning its own server.
+ */
+export function resolveExternalOpenCodeServer(
+  env: Record<string, string | undefined> | undefined,
+): ExternalOpenCodeServer | undefined {
+  const rawUrl = env?.[EXTERNAL_SERVER_URL_ENV]?.trim();
+  if (!rawUrl) return undefined;
+
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`${EXTERNAL_SERVER_URL_ENV} must be an absolute URL, received "${rawUrl}"`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`${EXTERNAL_SERVER_URL_ENV} must use http or https, received "${rawUrl}"`);
+  }
+  if (url.username || url.password)
+    throw new Error(
+      `${EXTERNAL_SERVER_URL_ENV} must not contain credentials; use ${EXTERNAL_SERVER_PASSWORD_ENV}`,
+    );
+
+  const password = env?.[EXTERNAL_SERVER_PASSWORD_ENV];
+  return {
+    url: url.toString().replace(/\/$/, ""),
+    ...(password ? { password } : {}),
+  };
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/owned-runtime.test.ts b/packages/server/src/server/agent/providers/opencode/v2/owned-runtime.test.ts
new file mode 100644
index 0000000000..d60535889b
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/owned-runtime.test.ts
@@ -0,0 +1,77 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vitest";
+import { createTestLogger } from "../../../../../test-utils/test-logger.js";
+import { OpenCodeBridge } from "../bridge.js";
+import { provisionLocalBridge } from "./bridge-provisioning.js";
+import { V2Runtime } from "./runtime.js";
+
+test("an owned helper uses an installed bridge once and survives catalog refresh", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-owned-opencode-"));
+  const config = path.join(root, "config", "opencode");
+  const script = path.join(root, "server.cjs");
+  const record = path.join(root, "env.json");
+  const bridge = new OpenCodeBridge({ paseoHome: root, logger: createTestLogger() });
+  await bridge.start();
+  const artifact = fileURLToPath(await bridge.materializeV2Plugin());
+  await provisionLocalBridge({
+    configDirectory: config,
+    artifact: path.join(artifact, "server.js"),
+  });
+  await writeFile(
+    script,
+    `
+    const http = require('node:http');
+    require('node:fs').writeFileSync(${JSON.stringify(record)}, process.env.OPENCODE_CONFIG_CONTENT);
+    const server = http.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' });
+      response.end(JSON.stringify({ version: '2.0.10', pid: process.pid, urls: [], paths: { tmp: '/tmp' } }));
+    });
+    server.listen(0, '127.0.0.1', () => console.log('server listening on http://127.0.0.1:' + server.address().port));
+  `,
+  );
+  const runtime = new V2Runtime({
+    logger: createTestLogger(),
+    bridge,
+    selection: { kind: "owned" },
+    settings: {
+      command: { mode: "replace", argv: [process.execPath, script] },
+      env: { XDG_CONFIG_HOME: path.join(root, "config"), OPENCODE_CONFIG_CONTENT: "{}" },
+    },
+  });
+  try {
+    const first = await runtime.acquire();
+    const pid = (await first.client.server.info()).pid;
+    expect(JSON.parse(await readFile(record, "utf8"))).toEqual({});
+    await first.release();
+    const refreshed = await runtime.acquire({ fresh: true });
+    expect((await refreshed.client.server.info()).pid).toBe(pid);
+    await refreshed.release();
+  } finally {
+    await runtime.shutdown();
+    await bridge.close();
+    await rm(root, { recursive: true, force: true });
+  }
+}, 15_000);
+
+test("reports a bridge port change that has not been applied", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-opencode-port-"));
+  const bridge = new OpenCodeBridge({ paseoHome: root, logger: createTestLogger() });
+  await bridge.start();
+  const actual = Number(new URL(bridge.sharedV2Connection().baseUrl).port);
+  const runtime = new V2Runtime({
+    logger: createTestLogger(),
+    bridge,
+    selection: { kind: "explicit", server: { url: "http://127.0.0.1:1" } },
+    settings: { env: { PASEO_OPENCODE_BRIDGE_PORT: actual === 1 ? "2" : "1" } },
+  });
+  try {
+    await expect(runtime.acquire()).rejects.toThrow("restart Paseo to apply the bridge port");
+  } finally {
+    await runtime.shutdown();
+    await bridge.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/permissions.test.ts b/packages/server/src/server/agent/providers/opencode/v2/permissions.test.ts
index 69da960c5c..2bf197c88d 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/permissions.test.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/permissions.test.ts
@@ -4,6 +4,102 @@ import { createTestLogger } from "../../../../../test-utils/test-logger.js";
 import type { V2Api } from "./api.js";
 import { OpenCodeV2AgentClient } from "./agent.js";
 import { V2Harness } from "../test-utils/v2-harness.js";
+import type { AgentPermissionResponse } from "../../../agent-sdk-types.js";
+
+describe("OpenCode v2 denial reasons", () => {
+  test.each<{
+    response: AgentPermissionResponse;
+    decision: "reject" | "once" | "always";
+    message?: string;
+  }>([
+    {
+      response: { behavior: "deny", message: "Use the existing file instead." },
+      decision: "reject",
+      message: "Use the existing file instead.",
+    },
+    { response: { behavior: "deny" }, decision: "reject" },
+    { response: { behavior: "allow" }, decision: "once" },
+    { response: { behavior: "allow", selectedActionId: "always" }, decision: "always" },
+  ])("preserves a permission response: $response", async ({ response, decision, message }) => {
+    const harness = new V2Harness();
+    let pending = true;
+    harness.api.permission.list = async () =>
+      pending
+        ? [{ id: "approval", sessionID: "session", action: "shell", resources: ["pwd"] }]
+        : [];
+    const replies: Parameters<V2Api["permission"]["reply"]>[0][] = [];
+    harness.api.permission.reply = async (input) => {
+      replies.push(input);
+      pending = false;
+    };
+    const client = new OpenCodeV2AgentClient({
+      logger: createTestLogger(),
+      runtime: harness.runtime,
+    });
+    const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+    try {
+      await session.respondToPermission("approval", response);
+      expect(replies).toEqual([
+        {
+          sessionID: "session",
+          requestID: "approval",
+          decision,
+          ...(message === undefined ? {} : { message }),
+        },
+      ]);
+      expect(session.getPendingPermissions()).toEqual([]);
+    } finally {
+      await session.close();
+    }
+  });
+
+  test.each([true, false])(
+    "explains cards superseded by a steer when clearing is %s",
+    async (clearPendingPermissions) => {
+      const harness = new V2Harness();
+      harness.autoComplete = false;
+      let pending = true;
+      harness.api.permission.list = async () =>
+        pending
+          ? [{ id: "approval", sessionID: "session", action: "shell", resources: ["pwd"] }]
+          : [];
+      const replies: Parameters<V2Api["permission"]["reply"]>[0][] = [];
+      harness.api.permission.reply = async (input) => {
+        replies.push(input);
+        pending = false;
+      };
+      const client = new OpenCodeV2AgentClient({
+        logger: createTestLogger(),
+        runtime: harness.runtime,
+      });
+      const session = await client.createSession({ provider: "opencode", cwd: "/tmp/project" });
+      try {
+        const { turnId } = await session.startTurn("Run pwd");
+        await expect.poll(() => harness.prompts).toEqual(["Run pwd"]);
+        await expect(
+          session.steerActiveTurn!("go ahead", { expectedTurnId: turnId, clearPendingPermissions }),
+        ).resolves.toEqual({ status: "accepted" });
+        expect(harness.prompts).toEqual(["Run pwd", "go ahead"]);
+        expect(replies).toEqual(
+          clearPendingPermissions
+            ? [
+                {
+                  sessionID: "session",
+                  requestID: "approval",
+                  decision: "reject",
+                  message:
+                    "The user answered with a message instead of approving. Their message follows.",
+                },
+              ]
+            : [],
+        );
+        expect(session.getPendingPermissions()).toHaveLength(clearPendingPermissions ? 0 : 1);
+      } finally {
+        await session.close();
+      }
+    },
+  );
+});
 
 describe("OpenCode v2 questions", () => {
   test("maps selected labels to native values and parses numeric and boolean answers", async () => {
diff --git a/packages/server/src/server/agent/providers/opencode/v2/permissions.ts b/packages/server/src/server/agent/providers/opencode/v2/permissions.ts
index cb33e0652e..6a8a6ad56c 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/permissions.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/permissions.ts
@@ -68,6 +68,9 @@ export class SessionPermissions {
         sessionID: this.permissionOwners.get(requestId) ?? this.id,
         requestID: requestId,
         decision: permissionReply(response),
+        ...(response.behavior === "deny" && response.message !== undefined
+          ? { message: response.message }
+          : {}),
       });
     }
     this.resolvePending(requestId, response);
@@ -93,7 +96,7 @@ export class SessionPermissions {
       };
       this.pending.set(request.id, pending);
       this.permissionOwners.set(request.id, sessionID);
-      if (!this.config.toolPolicy && this.config.featureValues?.["auto_accept"] === true)
+      if (!this.config.toolPolicy && this.config.providerOptions?.["auto_accept"] === true)
         await this.respondToPermission(request.id, { behavior: "allow" });
       else this.emit({ type: "permission_requested", provider: "opencode", request: pending });
     }
diff --git a/packages/server/src/server/agent/providers/opencode/v2/runtime.ts b/packages/server/src/server/agent/providers/opencode/v2/runtime.ts
index cab5544582..0fe830fe45 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/runtime.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/runtime.ts
@@ -16,11 +16,25 @@ import type { ManagedProcessRegistry } from "../../../../managed-processes/manag
 import { resolveOpenCodeHomeDir } from "../paths.js";
 import { OpenCodeHttpError } from "../http-error.js";
 import { raceProviderRefreshAbort } from "../../../provider-refresh-deadline.js";
+import { resolveExternalOpenCodeServer, type ExternalOpenCodeServer } from "./external-server.js";
+import { selectOpenCodeService, type OpenCodeServiceSelection } from "./service-selection.js";
+import { bridgeBindings, connectSharedService } from "./shared-service.js";
+import {
+  hasManagedBridge,
+  openCodeConfigDirectory,
+  provisionLocalBridge,
+} from "./bridge-provisioning.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { OpenCodeBridge } from "../bridge.js";
 
 export interface V2Connection {
   client: V2Api;
   release(): Promise<void>;
   retain(): V2Connection;
+  bindSession(sessionId: string, cwd: string): Promise<void>;
+  unbindSession(sessionId: string, cwd: string): Promise<void>;
+  refreshLocation(cwd: string, signal?: AbortSignal): Promise<void>;
   readonly exited: Promise<Error>;
 }
 interface Generation {
@@ -28,12 +42,17 @@ interface Generation {
   users: number;
   stop(): Promise<void>;
   exited: Promise<Error>;
+  bindSession(sessionId: string, cwd: string): Promise<void>;
+  unbindSession(sessionId: string, cwd: string): Promise<void>;
+  refreshLocation(cwd: string, signal?: AbortSignal): Promise<void>;
 }
 export interface V2RuntimeOptions {
   logger: Logger;
   settings?: ProviderRuntimeSettings;
   managedProcesses?: ManagedProcessRegistry;
-  decorateEnv?: (env: Record<string, string>) => Promise<Record<string, string>>;
+  externalServer?: ExternalOpenCodeServer;
+  selection?: OpenCodeServiceSelection;
+  bridge?: OpenCodeBridge;
 }
 
 export interface V2RuntimeAcquireOptions {
@@ -49,17 +68,36 @@ export class V2Runtime {
   private generations = new Set<Generation>();
   private starts = new Set<Promise<Generation>>();
   private closed = false;
+  private readonly selection: Promise<OpenCodeServiceSelection>;
 
-  constructor(private readonly options: V2RuntimeOptions) {}
+  constructor(private readonly options: V2RuntimeOptions) {
+    this.selection = options.selection
+      ? Promise.resolve(options.selection)
+      : selectOpenCodeService({
+          explicit:
+            options.externalServer ??
+            resolveExternalOpenCodeServer({
+              ...globalThis.process.env,
+              ...options.settings?.env,
+            }),
+          env: options.settings?.env,
+        });
+  }
 
   async acquire(input: V2RuntimeAcquireOptions = {}): Promise<V2Connection> {
     if (this.closed) throw new Error("OpenCode runtime is closed");
     input.signal?.throwIfAborted();
+    this.assertBridgePort();
+    const selection = await raceProviderRefreshAbort(input.signal, this.selection);
     let pending: Promise<Generation>;
-    if (input.env || input.dedicated) {
+    if (selection.kind !== "owned") {
+      this.assertSharedConfiguration(input, selection);
+      this.current ??= this.startTracked();
+      pending = this.current;
+    } else if (input.env || input.dedicated) {
       pending = this.startTracked(input.env);
     } else {
-      if (input.fresh || !this.current) this.current = this.startTracked();
+      if (!this.current) this.current = this.startTracked();
       pending = this.current;
     }
     let generation: Generation;
@@ -97,6 +135,39 @@ export class V2Runtime {
     return connection;
   }
 
+  private assertBridgePort(): void {
+    const port = this.options.settings?.env?.PASEO_OPENCODE_BRIDGE_PORT;
+    if (!port || !this.options.bridge) return;
+    const actual = new URL(this.options.bridge.sharedV2Connection().baseUrl).port;
+    if (Number(port) !== Number(actual))
+      throw new Error("PASEO_OPENCODE_BRIDGE_PORT changed; restart Paseo to apply the bridge port");
+  }
+
+  private assertSharedConfiguration(
+    input: V2RuntimeAcquireOptions,
+    selection: OpenCodeServiceSelection,
+  ): void {
+    const connectionEnv = new Set([
+      "PASEO_OPENCODE_SERVER_URL",
+      "PASEO_OPENCODE_SERVER_PASSWORD",
+      "PASEO_OPENCODE_BRIDGE_URL",
+      "PASEO_OPENCODE_BRIDGE_PORT",
+    ]);
+    if (selection.kind === "discovered") {
+      connectionEnv.add("XDG_CONFIG_HOME");
+      connectionEnv.add("XDG_STATE_HOME");
+      connectionEnv.add("OPENCODE_CONFIG_DIR");
+    }
+    const processOverrides = Object.keys(this.options.settings?.env ?? {}).filter(
+      (key) => !connectionEnv.has(key),
+    );
+    if (input.env || input.dedicated || processOverrides.length) {
+      throw new Error(
+        `Custom OpenCode MCP servers or process environment require an isolated server and cannot be used with a shared OpenCode service${processOverrides.length ? `: ${processOverrides.join(", ")}` : ""}.`,
+      );
+    }
+  }
+
   private lease(generation: Generation, pending: Promise<Generation>): V2Connection {
     if (this.closed || !this.generations.has(generation))
       throw new Error("OpenCode helper server is no longer running");
@@ -107,7 +178,7 @@ export class V2Runtime {
       released = true;
       generation.users -= 1;
       if (generation.users !== 0) return;
-      if (this.current === pending) this.current = null;
+      if (this.current === pending) return;
       this.generations.delete(generation);
       await generation.stop();
     };
@@ -115,6 +186,9 @@ export class V2Runtime {
       client: generation.client,
       release,
       retain: () => this.lease(generation, pending),
+      bindSession: generation.bindSession,
+      unbindSession: generation.unbindSession,
+      refreshLocation: generation.refreshLocation,
       exited: generation.exited,
     };
   }
@@ -146,6 +220,16 @@ export class V2Runtime {
   }
 
   private async start(env: Record<string, string> = {}): Promise<Generation> {
+    const selection = await this.selection;
+    if (selection.kind !== "owned") {
+      const generation: Generation = {
+        ...(await connectSharedService(selection, this.options)),
+        users: 0,
+      };
+      this.generations.add(generation);
+      return generation;
+    }
+
     const { settings, managedProcesses, logger } = this.options;
     const launch = await resolveProviderLaunch({
       commandConfig: settings?.command,
@@ -160,9 +244,20 @@ export class V2Runtime {
       ...settings?.env,
       ...env,
     };
-    const decorated = this.options.decorateEnv
-      ? await this.options.decorateEnv(configured)
-      : decorateOpenCodeV2Env(configured, await materializeOpenCodeV2Plugin(resolvePaseoHome()));
+    const bridge = this.options.bridge;
+    const plugin = bridge
+      ? await bridge.materializeV2Plugin()
+      : await materializeOpenCodeV2Plugin(resolvePaseoHome());
+    const globalConfig = openCodeConfigDirectory({ ...globalThis.process.env, ...configured });
+    const managed = await hasManagedBridge(globalConfig);
+    if (managed && bridge)
+      await provisionLocalBridge({
+        configDirectory: globalConfig,
+        artifact: path.join(fileURLToPath(plugin), "server.js"),
+      });
+    const decorated = managed
+      ? configured
+      : decorateOpenCodeV2Env(configured, plugin, bridge ? {} : { mode: "structured-only" });
     const args = [...launch.args, "serve", "--hostname", "127.0.0.1", "--port", "0"];
     const process = spawnProcess(launch.command, args, {
       cwd,
@@ -253,7 +348,13 @@ export class V2Runtime {
         },
       });
       await client.server.info({ signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())) });
-      const generation: Generation = { client, users: 0, stop, exited };
+      const generation: Generation = {
+        client,
+        users: 0,
+        stop,
+        exited,
+        ...bridgeBindings(client, bridge),
+      };
       this.generations.add(generation);
       process.once("exit", () => {
         this.generations.delete(generation);
diff --git a/packages/server/src/server/agent/providers/opencode/v2/service-selection.test.ts b/packages/server/src/server/agent/providers/opencode/v2/service-selection.test.ts
new file mode 100644
index 0000000000..876582fb9c
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/service-selection.test.ts
@@ -0,0 +1,55 @@
+import { createServer } from "node:http";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { expect, test } from "vitest";
+import { selectOpenCodeService } from "./service-selection.js";
+
+test("selects the registered service with its credential and ignores stale registration", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-service-"));
+  const file = path.join(directory, "service.json");
+  let requests = 0;
+  const server = createServer((request, response) => {
+    requests++;
+    if (
+      request.headers.authorization !== `Basic ${Buffer.from("opencode:secret").toString("base64")}`
+    ) {
+      response.writeHead(401).end();
+      return;
+    }
+    response.writeHead(200, { "Content-Type": "application/json" });
+    response.end(JSON.stringify({ version: "2.0.10", pid: process.pid }));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("No test address");
+  const url = `http://127.0.0.1:${address.port}`;
+  try {
+    await writeFile(
+      file,
+      JSON.stringify({ url, password: "secret", pid: process.pid, version: "2.0.10" }),
+    );
+    expect(await selectOpenCodeService({ file })).toEqual({
+      kind: "discovered",
+      server: { url, password: "secret" },
+    });
+    expect(requests).toBe(1);
+    expect(
+      await selectOpenCodeService({ file, explicit: { url: "http://explicit.test" } }),
+    ).toEqual({ kind: "explicit", server: { url: "http://explicit.test" } });
+    expect(requests).toBe(1);
+    await writeFile(file, JSON.stringify({ url, password: "secret", pid: process.pid + 1 }));
+    expect(await selectOpenCodeService({ file })).toEqual({ kind: "owned" });
+  } finally {
+    await new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+    await rm(directory, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/service-selection.ts b/packages/server/src/server/agent/providers/opencode/v2/service-selection.ts
new file mode 100644
index 0000000000..eeb2cb0994
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/service-selection.ts
@@ -0,0 +1,43 @@
+import { Service } from "@opencode/client/service";
+import { homedir, networkInterfaces } from "node:os";
+import path from "node:path";
+import type { ExternalOpenCodeServer } from "./external-server.js";
+
+export type OpenCodeServiceSelection =
+  | { kind: "owned" }
+  | { kind: "explicit" | "discovered"; server: ExternalOpenCodeServer };
+
+export async function selectOpenCodeService(input: {
+  explicit?: ExternalOpenCodeServer;
+  file?: string;
+  env?: Record<string, string | undefined>;
+}): Promise<OpenCodeServiceSelection> {
+  if (input.explicit) return { kind: "explicit", server: input.explicit };
+  const state =
+    input.env?.XDG_STATE_HOME ??
+    process.env.XDG_STATE_HOME ??
+    path.join(homedir(), ".local", "state");
+  const endpoint = await Service.discover({
+    file: input.file ?? path.join(state, "opencode", "service.json"),
+    version: compatibleVersion,
+  }).catch(() => undefined);
+  if (!endpoint) return { kind: "owned" };
+  if (!isLocalOpenCodeHost(new URL(endpoint.url).hostname)) return { kind: "owned" };
+  return {
+    kind: "discovered",
+    server: { url: endpoint.url, ...(endpoint.auth ? { password: endpoint.auth.password } : {}) },
+  };
+}
+
+export function isLocalOpenCodeHost(input: string): boolean {
+  const hostname = input.replace(/^\[|\]$/g, "");
+  const localAddresses = Object.values(networkInterfaces()).flatMap((items) =>
+    (items ?? []).map((item) => item.address),
+  );
+  return ["localhost", "127.0.0.1", "::1", "0.0.0.0", "::", ...localAddresses].includes(hostname);
+}
+
+export function compatibleVersion(version: string): boolean {
+  const match = /^2\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+  return Boolean(match && (Number(match[1]) > 0 || Number(match[2]) >= 10));
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/session.ts b/packages/server/src/server/agent/providers/opencode/v2/session.ts
index 79add6d05f..841a91d580 100644
--- a/packages/server/src/server/agent/providers/opencode/v2/session.ts
+++ b/packages/server/src/server/agent/providers/opencode/v2/session.ts
@@ -1,3 +1,8 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
+import { applyProviderOptionsPatch } from "../../../option-controls.js";
+import { assertChangesAreLive, validateProviderOptions } from "../../../provider-options.js";
+import { OpenCodeProviderOptionsSchema } from "../options.js";
+import { OpenCodeBackgroundInventory } from "./background-inventory.js";
 import { SessionChildren } from "./children.js";
 import { SessionTurns } from "./turns.js";
 import { V2Timeline } from "./timeline.js";
@@ -33,7 +38,7 @@ import { type V2Connection } from "./runtime.js";
 import { modelRef, modesFromV2 } from "./mapping.js";
 
 import { V2_CAPABILITIES } from "./capabilities.js";
-import { features } from "./configuration.js";
+import { controls } from "./configuration.js";
 import { commands } from "./commands.js";
 import { messages } from "./history.js";
 import { SessionPermissions } from "./permissions.js";
@@ -59,6 +64,7 @@ export class OpenCodeV2Session implements AgentSession {
   private refreshTimer: ReturnType<typeof setTimeout> | null = null;
   private closed = false;
   private history: SessionMessageInfo[] = [];
+  private readonly background: OpenCodeBackgroundInventory;
   private modes: AgentMode[] = [];
   constructor(
     private connection: V2Connection,
@@ -72,6 +78,16 @@ export class OpenCodeV2Session implements AgentSession {
     private readonly acquire?: () => Promise<V2Connection>,
     private readonly moved?: (connection: V2Connection) => void,
   ) {
+    this.background = new OpenCodeBackgroundInventory({
+      id: info.id,
+      cwd: config.cwd,
+      emit: (event) => this.emit(event),
+      report: (error) =>
+        this.logger.warn(
+          { error: toDiagnosticErrorMessage(error) },
+          "OpenCode background inventory failed",
+        ),
+    });
     this.permissions = new SessionPermissions(
       () => this.client,
       info.id,
@@ -102,7 +118,11 @@ export class OpenCodeV2Session implements AgentSession {
         ),
       clearPermissions: async () => {
         for (const request of this.permissions.list())
-          await this.permissions.respondToPermission(request.id, { behavior: "deny" });
+          await this.permissions.respondToPermission(request.id, {
+            behavior: "deny",
+            message:
+              "The user answered with a message instead of approving. Their message follows.",
+          });
       },
     });
     this.usage = new SessionUsage({
@@ -120,8 +140,8 @@ export class OpenCodeV2Session implements AgentSession {
   get id() {
     return this.info.id;
   }
-  get features() {
-    return features(this.config);
+  get controls() {
+    return controls;
   }
   private get client() {
     return this.connection.client;
@@ -141,6 +161,7 @@ export class OpenCodeV2Session implements AgentSession {
     void connection.exited.then((error) => {
       if (this.closed || this.connection !== connection) return undefined;
       this.exited = true;
+      this.background.disconnect(true);
       this.streamAbort.abort(error);
       this.turns.fail(error);
       return undefined;
@@ -148,6 +169,7 @@ export class OpenCodeV2Session implements AgentSession {
   }
   private async configureConnection() {
     const location = { directory: this.config.cwd };
+    await this.connection.bindSession(this.id, this.config.cwd);
     await waitForLocationReady({ client: this.client, location, signal: this.abort.signal });
     if (this.requiresPaseoPlugin)
       await awaitPaseoPlugin({ client: this.client, location, signal: this.abort.signal });
@@ -209,6 +231,11 @@ export class OpenCodeV2Session implements AgentSession {
     if (!this.acquire) throw new Error("OpenCode helper server exited");
     await this.stream;
     await this.sync.catch(() => undefined);
+    await this.connection
+      .unbindSession(this.id, this.config.cwd)
+      .catch((error: unknown) =>
+        this.logger.warn({ error }, "Could not unbind the OpenCode Paseo bridge"),
+      );
     const next = await this.acquire();
     if (this.closed) {
       await next.release();
@@ -234,6 +261,12 @@ export class OpenCodeV2Session implements AgentSession {
   }
   subscribe(callback: (event: AgentStreamEvent) => void) {
     this.listeners.add(callback);
+    const background = this.background.snapshot();
+    if (background) callback(background);
+    // Reopening can adopt an execution during initialization, before its caller
+    // can subscribe. Deliver that live turn so it remains visible and interruptible.
+    if (this.turns.id)
+      callback({ type: "turn_started", provider: "opencode", turnId: this.turns.id });
     return () => {
       this.listeners.delete(callback);
     };
@@ -340,6 +373,7 @@ export class OpenCodeV2Session implements AgentSession {
         thinkingOptionId: variant ?? null,
       },
     });
+    return { model: `${selected.providerID}/${selected.id}` };
   }
 
   async setThinkingOption(variant: string | null) {
@@ -354,14 +388,33 @@ export class OpenCodeV2Session implements AgentSession {
     this.info = await this.client.session.get({ sessionID: this.id });
     this.emit({ type: "thinking_option_changed", provider: "opencode", thinkingOptionId: variant });
   }
-  async setFeature(id: string, value: unknown) {
-    if (id !== "auto_accept" || typeof value !== "boolean")
-      throw new Error("Unknown OpenCode feature");
-    this.config.featureValues = { ...this.config.featureValues, [id]: value };
-    if (value && !this.config.toolPolicy)
-      for (const request of this.permissions.list())
-        if (request.kind !== "question")
-          await this.respondToPermission(request.id, { behavior: "allow" });
+  /** The agent manager sends one apply at a time, so a failed one restores exactly what it changed. */
+  async applyOptions(options: ProviderOptions): Promise<void> {
+    assertChangesAreLive({
+      provider: "opencode",
+      patch: options,
+      current: this.config.providerOptions,
+      live: ["auto_accept"],
+    });
+    const next = validateProviderOptions(
+      "opencode",
+      OpenCodeProviderOptionsSchema,
+      applyProviderOptionsPatch({ options: this.config.providerOptions, patch: options }),
+    );
+    if (!("auto_accept" in options)) return;
+    const value = next?.auto_accept === true;
+    const previous = this.config.providerOptions;
+    this.config.providerOptions = { ...previous, auto_accept: value };
+    try {
+      if (value && !this.config.toolPolicy)
+        for (const request of this.permissions.list())
+          if (request.kind !== "question")
+            await this.respondToPermission(request.id, { behavior: "allow" });
+    } catch (error) {
+      // A rejected apply stores nothing, so the running session keeps asking as it did.
+      this.config.providerOptions = previous;
+      throw error;
+    }
   }
   async listCommands() {
     await this.reconnectIfExited();
@@ -388,11 +441,15 @@ export class OpenCodeV2Session implements AgentSession {
   }
   async startTurn(prompt: AgentPromptInput, options?: AgentRunOptions) {
     await this.reconnectIfExited();
+    await this.connection.bindSession(this.id, this.config.cwd);
     return this.turns.startTurn(prompt, options);
   }
   steerActiveTurn(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult> {
     return this.turns.steerActiveTurn(prompt, options);
   }
+  stopBackgroundWork(id: string) {
+    return this.background.stopItem(id);
+  }
   interrupt() {
     return this.turns.interrupt();
   }
@@ -444,6 +501,7 @@ export class OpenCodeV2Session implements AgentSession {
     }
   }
   private async reconcileConnection() {
+    await this.connection.bindSession(this.id, this.config.cwd);
     // Session environments are process-local. Reapply this agent's snapshot before
     // reconciling a new connection, including event-stream reconnections.
     if (this.launchEnv)
@@ -507,9 +565,12 @@ export class OpenCodeV2Session implements AgentSession {
           if (event.type === "server.connected") {
             this.timeline.resetStreams();
             await this.reconcileConnection();
+            signal.throwIfAborted();
+            this.background.start(this.client);
             connected = true;
             ready();
           }
+          this.background.observe(event);
           await this.children.observe(event);
           this.observeOwnEvent(event);
         }
@@ -525,6 +586,7 @@ export class OpenCodeV2Session implements AgentSession {
           "OpenCode event stream interrupted; reconciling on reconnect",
         );
       }
+      this.background.disconnect();
       await delay(100, undefined, { signal }).catch(() => undefined);
     }
   }
@@ -565,9 +627,15 @@ export class OpenCodeV2Session implements AgentSession {
     this.turns.close();
     this.streamAbort.abort();
     if (this.refreshTimer) clearTimeout(this.refreshTimer);
+    this.background.disconnect();
     await this.stream;
     await this.reconnecting?.catch(() => undefined);
     await this.sync.catch(() => undefined);
+    await this.connection
+      .unbindSession(this.id, this.config.cwd)
+      .catch((error: unknown) =>
+        this.logger.warn({ error }, "Could not unbind the OpenCode Paseo bridge"),
+      );
     this.unbind?.();
     try {
       if (!this.persist) await this.client.session.remove({ sessionID: this.id });
diff --git a/packages/server/src/server/agent/providers/opencode/v2/shared-bridge-plugin.mjs b/packages/server/src/server/agent/providers/opencode/v2/shared-bridge-plugin.mjs
new file mode 100644
index 0000000000..4be98bfba9
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/shared-bridge-plugin.mjs
@@ -0,0 +1,207 @@
+import { STRUCTURED_OUTPUT_TOOL } from "./structured-output-plugin.mjs";
+
+// OpenCode owns this plugin for the lifetime of a location. Paseo supplies only
+// live, per-session bindings over the authenticated OpenCode RPC channel.
+export async function registerSharedBridge(context) {
+  const state = await import(new URL("./state.mjs", import.meta.url).href);
+  const { bindings, definitions } = state.stateFor(context.location);
+  const registrations = new Map();
+  let updating = Promise.resolve();
+  async function request(binding, pathname, body, allowMissing = false, signal) {
+    const requestSignal = body === undefined ? AbortSignal.timeout(5_000) : signal;
+    const response = await fetch(new URL(`/_internal/opencode${pathname}`, binding.baseUrl), {
+      method: body === undefined ? "GET" : "POST",
+      headers: { Authorization: `Bearer ${binding.token}`, "Content-Type": "application/json" },
+      signal: requestSignal,
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (allowMissing && response.status === 404) return null;
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const detail = formatErrorDetail(payload?.issues ?? payload?.details);
+      const message = payload?.error ?? `Paseo tool bridge returned HTTP ${response.status}`;
+      const error = new Error(detail ? `${message}: ${detail}` : message);
+      error.status = response.status;
+      if (detail) error.details = detail;
+      throw error;
+    }
+    return payload;
+  }
+  async function find(sessionID) {
+    const seen = new Set();
+    while (sessionID && !seen.has(sessionID)) {
+      seen.add(sessionID);
+      const binding = bindings.get(sessionID);
+      if (binding) return { ...binding, sessionID };
+      sessionID = (await context.session.get({ sessionID })).parentID;
+    }
+    return null;
+  }
+  async function install(binding) {
+    const manifest = await request(binding, "/tools");
+    for (const definition of manifest.tools) await installDefinition(definition);
+  }
+  async function installDefinition(definition) {
+    const signature = JSON.stringify(definition);
+    const known = definitions.get(definition.name);
+    if (known && JSON.stringify(known) !== signature)
+      throw new Error(`Conflicting Paseo tool definition: ${definition.name}`);
+    const old = registrations.get(definition.name);
+    if (old) {
+      if (old.signature !== signature)
+        throw new Error(`Conflicting Paseo tool definition: ${definition.name}`);
+      return;
+    }
+    const registration = await context.tool.transform((editor) => {
+      editor.add({
+        name: `paseo_${definition.name}`,
+        description: definition.description,
+        input: definition.inputSchema,
+        options: { codemode: false },
+        async execute(input, call) {
+          const scope = await find(call.sessionID);
+          if (!scope) throw new Error("OpenCode session is not bound to a Paseo agent");
+          const result = await request(
+            scope,
+            `/sessions/${encodeURIComponent(scope.sessionID)}/tools/${encodeURIComponent(definition.name)}`,
+            input,
+            false,
+            call.signal,
+          );
+          return {
+            content: result.content.map(toOpenCodeContent),
+            metadata: { paseoTool: definition.name },
+          };
+        },
+      });
+    });
+    registrations.set(definition.name, { signature, registration });
+    definitions.set(definition.name, definition);
+  }
+  async function clearUnusedDefinitions() {
+    if (bindings.size) return;
+    await Promise.all(
+      [...registrations.values()].map(({ registration }) => registration.dispose()),
+    );
+    registrations.clear();
+    definitions.clear();
+  }
+  // Reinstall live tools before this plugin generation is made visible.
+  // Definitions are kept in memory, so unavailable owners cannot delay reload.
+  for (const definition of definitions.values()) await installDefinition(definition);
+  const object = { type: "object", additionalProperties: true };
+  const rpc = await context.rpc.register(
+    {
+      id: "paseo.bridge",
+      methods: {
+        bind: { input: object, output: object },
+        unbind: { input: object, output: object },
+        refresh: { input: object, output: object },
+      },
+      events: {},
+    },
+    {
+      bind: async (input) => {
+        if (
+          typeof input.sessionID !== "string" ||
+          typeof input.baseUrl !== "string" ||
+          typeof input.token !== "string"
+        )
+          throw new Error("Invalid Paseo bridge binding");
+        const next = updating
+          .catch(() => undefined)
+          .then(async () => {
+            const previous = bindings.get(input.sessionID);
+            if (
+              previous &&
+              (previous.baseUrl !== input.baseUrl || previous.token !== input.token)
+            ) {
+              let active;
+              try {
+                active = await request(
+                  previous,
+                  `/sessions/${encodeURIComponent(input.sessionID)}/context`,
+                  undefined,
+                  true,
+                );
+              } catch (error) {
+                // Refusal or rejected credentials mean this endpoint no longer
+                // serves the previous binding. Other failures are inconclusive.
+                if (
+                  error?.status !== 401 &&
+                  error?.cause?.code !== "ECONNREFUSED" &&
+                  error?.code !== "ConnectionRefused"
+                )
+                  throw error;
+              }
+              if (active)
+                return { error: "OpenCode session is already bound to another Paseo bridge" };
+              bindings.delete(input.sessionID);
+              await clearUnusedDefinitions();
+            }
+            await install(input);
+            bindings.set(input.sessionID, { baseUrl: input.baseUrl, token: input.token });
+            return {};
+          });
+        updating = next;
+        return await next;
+      },
+      unbind: async (input) => {
+        const next = updating
+          .catch(() => undefined)
+          .then(async () => {
+            const binding = bindings.get(input.sessionID);
+            if (binding && binding.token === input.token && binding.baseUrl === input.baseUrl)
+              bindings.delete(input.sessionID);
+            await clearUnusedDefinitions();
+            return {};
+          });
+        updating = next;
+        await next;
+        return {};
+      },
+      refresh: async () => {
+        await context.provider.reload();
+        await context.model.reload();
+        await context.agent.reload();
+        await context.command.reload();
+        await context.skill.reload();
+        return {};
+      },
+    },
+  );
+  const filter = await context.session.hook("context", async (input) => {
+    const binding = await find(input.sessionID);
+    const scope =
+      binding &&
+      (await request(binding, `/sessions/${encodeURIComponent(binding.sessionID)}/context?tools`));
+    const allowed = new Set((scope?.tools ?? []).map((name) => `paseo_${name}`));
+    for (const name of Object.keys(input.tools)) {
+      if (name.startsWith("paseo_") && name !== STRUCTURED_OUTPUT_TOOL && !allowed.has(name))
+        delete input.tools[name];
+    }
+  });
+  return async () => {
+    await filter.dispose();
+    await rpc.dispose();
+    await Promise.all(
+      [...registrations.values()].map(({ registration }) => registration.dispose()),
+    );
+  };
+}
+
+function toOpenCodeContent(part) {
+  if (part.type === "image")
+    return { type: "file", uri: `data:${part.mimeType};base64,${part.data}`, mime: part.mimeType };
+  return part;
+}
+
+function formatErrorDetail(details) {
+  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
+  return details
+    .map((issue) => {
+      const path = Array.isArray(issue?.path) && issue.path.length ? issue.path.join(".") : "input";
+      return `${path}: ${issue?.message ?? "Invalid value"}`;
+    })
+    .join("; ");
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/shared-bridge.test.ts b/packages/server/src/server/agent/providers/opencode/v2/shared-bridge.test.ts
new file mode 100644
index 0000000000..c560fa6558
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/shared-bridge.test.ts
@@ -0,0 +1,168 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { expect, test } from "vitest";
+import { z } from "zod";
+import { createTestLogger } from "../../../../../test-utils/test-logger.js";
+import { OpenCodeBridge } from "../bridge.js";
+
+interface Binding {
+  sessionID: string;
+  baseUrl: string;
+  token: string;
+}
+interface TestTool {
+  name: string;
+  execute(input: { value: string }, call: { sessionID: string }): Promise<unknown>;
+}
+interface TestContext {
+  sessionID: string;
+  tools: Record<string, unknown>;
+  system: unknown[];
+}
+
+test("a shared plugin binds Paseo sessions without involving unrelated sessions", async () => {
+  const home = await mkdtemp(path.join(tmpdir(), "paseo-shared-bridge-"));
+  const bridge = new OpenCodeBridge({ paseoHome: home, logger: createTestLogger() });
+  const tool = { name: "echo", description: "echo", inputSchema: { value: z.string() } };
+  const tools = new Map([[tool.name, tool]]);
+  bridge.setManifestCatalog({ tools });
+  await bridge.start();
+  const unbind = bridge.bindSession({
+    sessionId: "paseo",
+    env: {},
+    tools: {
+      tools,
+      getTool: (name) => tools.get(name),
+      executeTool: async (_name, input) => ({
+        content: [{ type: "text", text: String((input as { value: string }).value) }],
+      }),
+    },
+  });
+  expect(() => bridge.bindSession({ sessionId: "paseo", env: {} })).toThrow("already bound");
+  try {
+    const plugin = {
+      package: await bridge.materializeV2Plugin(),
+      options: bridge.sharedV2Connection(),
+    };
+    const module = await import(
+      pathToFileURL(path.join(fileURLToPath(plugin.package), "server.js")).href
+    );
+    const installed = new Map<string, TestTool>();
+    const hooks: Array<(input: TestContext) => Promise<void>> = [];
+    const refreshed: string[] = [];
+    let structured = false;
+    let rpc: Record<string, (input: Binding) => Promise<unknown>> = {};
+    const context = {
+      options: {},
+      location: { directory: home },
+      provider: {
+        reload: async () => {
+          refreshed.push("provider");
+        },
+      },
+      model: {
+        reload: async () => {
+          refreshed.push("model");
+        },
+      },
+      agent: {
+        reload: async () => {
+          refreshed.push("agent");
+        },
+      },
+      command: {
+        reload: async () => {
+          refreshed.push("command");
+        },
+      },
+      skill: {
+        reload: async () => {
+          refreshed.push("skill");
+        },
+      },
+      rpc: {
+        register: async (_definition: unknown, handlers: typeof rpc) => {
+          rpc = handlers;
+          return { dispose: async () => {} };
+        },
+      },
+      tool: {
+        transform: async (fn: (editor: { add(item: TestTool): void }) => void) => {
+          fn({ add: (item) => installed.set(item.name, item) });
+          return { dispose: async () => {} };
+        },
+      },
+      session: {
+        context: async () =>
+          structured ? [{ type: "user", metadata: { paseoOutputSchema: { type: "string" } } }] : [],
+        get: async () => ({ parentID: "" }),
+        hook: async (_name: string, fn: (input: TestContext) => Promise<void>) => {
+          hooks.push(fn);
+          return { dispose: async () => {} };
+        },
+      },
+    };
+    let dispose = await module.default.setup(context);
+    await rpc.bind({ sessionID: "paseo", ...plugin.options });
+    await rpc.refresh({ sessionID: "paseo", ...plugin.options });
+    expect(refreshed).toEqual(["provider", "model", "agent", "command", "skill"]);
+    await expect(
+      rpc.bind({ sessionID: "paseo", ...plugin.options, token: "another-daemon" }),
+    ).resolves.toEqual({ error: "OpenCode session is already bound to another Paseo bridge" });
+    const own = { sessionID: "paseo", tools: { paseo_echo: {}, native: {} }, system: [] };
+    for (const hook of hooks) await hook(own);
+    expect(Object.keys(own.tools)).toEqual(["paseo_echo", "native"]);
+    expect(
+      await installed.get("paseo_echo")!.execute({ value: "ok" }, { sessionID: "paseo" }),
+    ).toMatchObject({ content: [{ type: "text", text: "ok" }] });
+    await dispose();
+    hooks.length = 0;
+    installed.clear();
+    dispose = await module.default.setup(context);
+    const afterReload = { sessionID: "paseo", tools: { paseo_echo: {}, native: {} }, system: [] };
+    for (const hook of hooks) await hook(afterReload);
+    expect(Object.keys(afterReload.tools)).toEqual(["paseo_echo", "native"]);
+    expect(
+      await installed.get("paseo_echo")!.execute({ value: "reloaded" }, { sessionID: "paseo" }),
+    ).toMatchObject({ content: [{ type: "text", text: "reloaded" }] });
+    await bridge.close();
+    await dispose();
+    hooks.length = 0;
+    installed.clear();
+    dispose = await module.default.setup(context);
+    const unrelated = { sessionID: "other", tools: { paseo_echo: {}, native: {} }, system: [] };
+    for (const hook of hooks) await hook(unrelated);
+    expect(Object.keys(unrelated.tools)).toEqual(["native"]);
+    structured = true;
+    const structuredOnly = {
+      sessionID: "other",
+      tools: { paseo_structured_output: {} },
+      system: [],
+    };
+    for (const hook of hooks) await hook(structuredOnly);
+    expect(Object.keys(structuredOnly.tools)).toEqual(["paseo_structured_output"]);
+    const restarted = new OpenCodeBridge({
+      paseoHome: home,
+      logger: createTestLogger(),
+      port: Number(new URL(plugin.options.baseUrl).port),
+    });
+    restarted.setManifestCatalog({ tools });
+    await restarted.start();
+    const releaseRestarted = restarted.bindSession({ sessionId: "paseo", env: {} });
+    try {
+      await expect(
+        rpc.bind({ sessionID: "paseo", ...restarted.sharedV2Connection() }),
+      ).resolves.toEqual({});
+    } finally {
+      releaseRestarted();
+      await restarted.close();
+    }
+    await dispose();
+  } finally {
+    unbind();
+    await bridge.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/opencode/v2/shared-service.ts b/packages/server/src/server/agent/providers/opencode/v2/shared-service.ts
new file mode 100644
index 0000000000..26fcbb7d26
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/shared-service.ts
@@ -0,0 +1,192 @@
+import { OpenCode } from "@opencode/client";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Logger } from "pino";
+import type { ProviderRuntimeSettings } from "../../../provider-launch-config.js";
+import type { OpenCodeBridge } from "../bridge.js";
+import { OpenCodeHttpError } from "../http-error.js";
+import { resolveOpenCodeHomeDir } from "../paths.js";
+import { openCodeConfigDirectory, provisionLocalBridge } from "./bridge-provisioning.js";
+import { awaitPaseoPlugin } from "./readiness.js";
+import {
+  compatibleVersion,
+  isLocalOpenCodeHost,
+  type OpenCodeServiceSelection,
+} from "./service-selection.js";
+import type { V2Api } from "./api.js";
+
+interface SharedServiceOptions {
+  logger: Logger;
+  settings?: ProviderRuntimeSettings;
+  bridge?: OpenCodeBridge;
+}
+
+export interface SharedService {
+  client: V2Api;
+  exited: Promise<Error>;
+  stop(): Promise<void>;
+  bindSession(sessionId: string, cwd: string): Promise<void>;
+  unbindSession(sessionId: string, cwd: string): Promise<void>;
+  refreshLocation(cwd: string, signal?: AbortSignal): Promise<void>;
+}
+
+export async function connectSharedService(
+  selection: Extract<OpenCodeServiceSelection, { kind: "explicit" | "discovered" }>,
+  options: SharedServiceOptions,
+): Promise<SharedService> {
+  const server = selection.server;
+  const { logger } = options;
+  const lifetime = new AbortController();
+  const closed = new Error(`OpenCode external server connection closed (${server.url})`);
+  let resolveExited!: (error: Error) => void;
+  const exited = new Promise<Error>((resolve) => {
+    resolveExited = resolve;
+  });
+  const authorization = server.password
+    ? `Basic ${Buffer.from(`opencode:${server.password}`).toString("base64")}`
+    : undefined;
+  const client = OpenCode.make({
+    baseUrl: server.url,
+    ...(authorization ? { headers: { Authorization: authorization } } : {}),
+    fetch: async (request, init) => {
+      const signal = init?.signal
+        ? AbortSignal.any([init.signal, lifetime.signal])
+        : lifetime.signal;
+      const response = await fetch(request, { ...init, signal });
+      const html = response.headers.get("content-type")?.includes("text/html") ?? false;
+      if (!response.ok || html) {
+        const requestUrl = request instanceof Request ? request.url : String(request);
+        throw new OpenCodeHttpError(new URL(requestUrl).pathname, response.status, html);
+      }
+      return response;
+    },
+  });
+  let info: Awaited<ReturnType<typeof client.server.info>>;
+  try {
+    info = await client.server.info({
+      signal: AbortSignal.any([lifetime.signal, AbortSignal.timeout(30_000)]),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cannot reach OpenCode v2 server at ${server.url}: ${message}`, {
+      cause: error,
+    });
+  }
+  if (!compatibleVersion(info.version))
+    throw new Error(
+      `Unsupported OpenCode version ${info.version}; version 2.0.10 or newer is required`,
+    );
+  const bridge = options.bridge;
+  const pluginDirectory = bridge ? fileURLToPath(await bridge.materializeV2Plugin()) : undefined;
+  if (selection.kind === "discovered" && pluginDirectory) {
+    const env = { ...globalThis.process.env, ...options.settings?.env };
+    const configDirectory = openCodeConfigDirectory(env);
+    const home = resolveOpenCodeHomeDir();
+    await mkdir(home, { recursive: true });
+    const entries = await client.config.get({ location: { directory: home } });
+    if (
+      !entries.some(
+        (entry) =>
+          entry.type === "directory" && path.resolve(entry.path) === path.resolve(configDirectory),
+      )
+    )
+      throw new Error(
+        `OpenCode service does not use the expected configuration directory ${configDirectory}; configure the bridge on that service explicitly`,
+      );
+    await provisionLocalBridge({
+      configDirectory,
+      artifact: path.join(pluginDirectory, "server.js"),
+    });
+  }
+  const advertised =
+    options.settings?.env?.PASEO_OPENCODE_BRIDGE_URL ??
+    globalThis.process.env.PASEO_OPENCODE_BRIDGE_URL;
+  validateBridgeAddress(selection, bridge, advertised);
+  const generation: SharedService = {
+    client,
+    stop: async () => {
+      if (lifetime.signal.aborted) return;
+      lifetime.abort(closed);
+      resolveExited(closed);
+    },
+    exited,
+    ...bridgeBindings(client, bridge, advertised, pluginDirectory),
+  };
+  logger.info({ url: server.url }, "Using existing OpenCode v2 server");
+  return generation;
+}
+
+function validateBridgeAddress(
+  selection: Extract<OpenCodeServiceSelection, { kind: "explicit" | "discovered" }>,
+  bridge: OpenCodeBridge | undefined,
+  advertised: string | undefined,
+): void {
+  if (advertised) {
+    let bridgeUrl: URL;
+    try {
+      bridgeUrl = new URL(advertised);
+    } catch {
+      throw new Error("PASEO_OPENCODE_BRIDGE_URL must be an absolute HTTP or HTTPS URL");
+    }
+    if (bridgeUrl.protocol !== "http:" && bridgeUrl.protocol !== "https:")
+      throw new Error("PASEO_OPENCODE_BRIDGE_URL must be an absolute HTTP or HTTPS URL");
+  }
+  const hostname = new URL(selection.server.url).hostname;
+  if (bridge && selection.kind === "explicit" && !advertised && !isLocalOpenCodeHost(hostname))
+    throw new Error(
+      "Remote OpenCode requires PASEO_OPENCODE_BRIDGE_URL pointing to a reachable Paseo bridge tunnel and the Paseo plugin installed on the server",
+    );
+}
+
+export function bridgeBindings(
+  client: ReturnType<typeof OpenCode.make>,
+  bridge: OpenCodeBridge | undefined,
+  advertised?: string,
+  pluginDirectory?: string,
+): Pick<SharedService, "bindSession" | "unbindSession" | "refreshLocation"> {
+  return {
+    bindSession: async (sessionId, cwd) => {
+      if (!bridge) return;
+      const location = { directory: cwd };
+      let result: Awaited<ReturnType<typeof client.rpc.call>>;
+      try {
+        await awaitPaseoPlugin({ client, location });
+        result = await client.rpc.call({
+          location,
+          rpcID: "paseo.bridge",
+          method: "bind",
+          input: { sessionID: sessionId, ...bridge.sharedV2Connection(advertised) },
+        });
+      } catch (error) {
+        throw new Error(
+          `Cannot connect the Paseo tool bridge to OpenCode. Install the plugin from ${pluginDirectory ?? "Paseo's runtime directory"} and configure a reachable bridge URL: ${error instanceof Error ? error.message : String(error)}`,
+          { cause: error },
+        );
+      }
+      if (result.output && typeof result.output === "object" && "error" in result.output)
+        throw new Error(String(result.output.error));
+    },
+    unbindSession: async (sessionId, cwd) => {
+      if (bridge)
+        await client.rpc.call(
+          {
+            location: { directory: cwd },
+            rpcID: "paseo.bridge",
+            method: "unbind",
+            input: { sessionID: sessionId, ...bridge.sharedV2Connection(advertised) },
+          },
+          { signal: AbortSignal.timeout(2_000) },
+        );
+    },
+    refreshLocation: async (cwd, signal) => {
+      if (!bridge) return;
+      const location = { directory: cwd };
+      await awaitPaseoPlugin({ client, location, signal });
+      await client.rpc.call(
+        { location, rpcID: "paseo.bridge", method: "refresh", input: {} },
+        { signal },
+      );
+    },
+  };
+}
diff --git a/packages/server/src/server/agent/providers/opencode/v2/state.mjs b/packages/server/src/server/agent/providers/opencode/v2/state.mjs
new file mode 100644
index 0000000000..858be8f14a
--- /dev/null
+++ b/packages/server/src/server/agent/providers/opencode/v2/state.mjs
@@ -0,0 +1,11 @@
+// OpenCode reloads the plugin entry point independently from this module.
+// Keep live bindings and tool definitions in memory across those reloads.
+const locations = new Map();
+
+export function stateFor(location) {
+  const key = JSON.stringify([location.directory, location.workspaceID ?? null]);
+  if (!locations.has(key)) {
+    locations.set(key, { bindings: new Map(), definitions: new Map() });
+  }
+  return locations.get(key);
+}
diff --git a/packages/server/src/server/agent/providers/pi/agent.test.ts b/packages/server/src/server/agent/providers/pi/agent.test.ts
index 936bdbc973..d152810a92 100644
--- a/packages/server/src/server/agent/providers/pi/agent.test.ts
+++ b/packages/server/src/server/agent/providers/pi/agent.test.ts
@@ -5,11 +5,13 @@ import {
   mkdirSync,
   mkdtempSync,
   openSync,
+  readFileSync,
   readSync,
+  realpathSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import pino from "pino";
 import { setImmediate as waitForImmediate } from "node:timers/promises";
@@ -23,6 +25,7 @@ import {
   PiRpcAgentSession,
   transformPiModels,
 } from "./agent.js";
+import { PiCliRuntime } from "./cli-runtime.js";
 import { FakePi } from "./test-utils/fake-pi.js";
 import { createPiExtensionHost } from "./extensions/index.js";
 import { PiExtensionHost } from "./extensions/host.js";
@@ -142,16 +145,6 @@ function piAssistantEntry(id: string, parentId: string): PiSessionEntry {
   return { type: "message", id, parentId, message: { role: "assistant", content: [] } };
 }
 
-// Pi's context path: the entries from the root to the leaf.
-function piBranchTo(entries: PiSessionEntry[], leafId: string): PiSessionEntry[] {
-  const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  const branch: PiSessionEntry[] = [];
-  for (let entry = byId.get(leafId); entry; entry = byId.get(entry.parentId ?? "")) {
-    branch.unshift(entry);
-  }
-  return branch;
-}
-
 function parseEntryCapture(notification: string): unknown {
   const prefix = "PASEO_ENTRY_CAPTURE ";
   expect(notification.startsWith(prefix)).toBe(true);
@@ -1015,7 +1008,7 @@ describe("PiRpcAgentSession", () => {
     const events = new SessionEvents(session);
     const fakeSession = pi.latestSession();
     fakeSession.treeUserEntries = [{ id: "entry-old", parentId: null, text: "old prompt" }];
-    fakeSession.contextUserEntries = fakeSession.treeUserEntries;
+    fakeSession.historyUserEntries = fakeSession.treeUserEntries;
 
     await session.startTurn("new prompt", { clientMessageId: "client-new" });
     fakeSession.finishSubmittedUserMessage({
@@ -1597,6 +1590,111 @@ describe("PiRpcAgentSession", () => {
     ]);
   });
 
+  test("closes a history-only Pi runtime after replaying its timeline", async () => {
+    const pi = new FakePi();
+    pi.queueSessionSetup((runtimeSession) => {
+      runtimeSession.messages = [
+        { role: "user", content: "Old question" },
+        { role: "assistant", content: [{ type: "text", text: "Old answer" }] },
+      ];
+    });
+
+    const client: import("../../agent-sdk-types.js").AgentClient = createClient(pi);
+    const session = await client.resumeSession(
+      {
+        provider: "pi",
+        sessionId: "pi-session-1",
+        nativeHandle: "/tmp/native-pi-session",
+        metadata: { cwd: tmpdir() },
+      },
+      {},
+      undefined,
+      { purpose: "history" },
+    );
+
+    onTestFinished(() => session.close());
+    const history: AgentStreamEvent[] = [];
+    for await (const event of session.streamHistory()) history.push(event);
+
+    expect(history).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          type: "timeline",
+          provider: "pi",
+          item: expect.objectContaining({ type: "assistant_message", text: "Old answer" }),
+        }),
+      ]),
+    );
+    expect(pi.latestSession().closeCalls).toBe(1);
+
+    await session.close();
+    expect(pi.latestSession().closeCalls).toBe(1);
+  });
+
+  test("closes a history-only Pi runtime when replay is stopped", async () => {
+    const pi = new FakePi();
+    pi.queueSessionSetup((runtimeSession) => {
+      runtimeSession.messages = [
+        { role: "user", content: "Old question" },
+        { role: "assistant", content: [{ type: "text", text: "Old answer" }] },
+      ];
+    });
+    const session = await createClient(pi).resumeSession(
+      {
+        provider: "pi",
+        sessionId: "pi-session-1",
+        nativeHandle: "/tmp/native-pi-session",
+        metadata: { cwd: tmpdir() },
+      },
+      {},
+      undefined,
+      { purpose: "history" },
+    );
+    onTestFinished(() => session.close());
+    const history = session.streamHistory();
+    expect((await history.next()).done).toBe(false);
+    await history.return();
+    expect(pi.latestSession().closeCalls).toBe(1);
+  });
+
+  test("closes a history-only Pi runtime when replay fails", async () => {
+    const pi = new FakePi();
+    pi.queueSessionSetup((runtimeSession) => {
+      runtimeSession.getHistoryError = new Error("History unavailable");
+    });
+    const session = await createClient(pi).resumeSession(
+      {
+        provider: "pi",
+        sessionId: "pi-session-1",
+        nativeHandle: "/tmp/native-pi-session",
+        metadata: { cwd: tmpdir() },
+      },
+      {},
+      undefined,
+      { purpose: "history" },
+    );
+    onTestFinished(() => session.close());
+    const history = session.streamHistory();
+    await expect(history.next()).rejects.toThrow("History unavailable");
+    expect(pi.latestSession().closeCalls).toBe(1);
+  });
+
+  test("keeps an interactive Pi runtime open after replaying history", async () => {
+    const pi = new FakePi();
+    const session = await createClient(pi).resumeSession({
+      provider: "pi",
+      sessionId: "pi-session-1",
+      nativeHandle: "/tmp/native-pi-session",
+      metadata: { cwd: tmpdir() },
+    });
+    onTestFinished(() => session.close());
+    for await (const _event of session.streamHistory()) {
+      // Hydrate the session before its next interactive prompt.
+    }
+    expect(pi.latestSession().closeCalls).toBe(0);
+    await expect(session.getRuntimeInfo()).resolves.toMatchObject({ provider: "pi" });
+  });
+
   test("resumes a session whose model was removed on the model Pi falls back to", async () => {
     const pi = new FakePi();
     pi.removeModel("9router/deepseek-v4-flash");
@@ -1750,7 +1848,7 @@ describe("PiRpcAgentSession", () => {
     await session.close();
   });
 
-  test("captures the session's user entries apart from the ones on the current branch", async () => {
+  test("captures all session user entries as rewind targets, including abandoned branches", async () => {
     const pi = new FakePi();
     const session = await createClient(pi).createSession(createConfig());
     onTestFinished(() => session.close());
@@ -1768,7 +1866,6 @@ describe("PiRpcAgentSession", () => {
     const context = {
       sessionManager: {
         getEntries: () => entries,
-        buildContextEntries: () => piBranchTo(entries, "two-reply"),
       },
       ui: { notify: (message: string) => notifications.push(message) },
     };
@@ -1783,10 +1880,6 @@ describe("PiRpcAgentSession", () => {
           { id: "abandoned", parentId: "one-reply", text: "rewound away" },
           { id: "two", parentId: "one-reply", text: "second" },
         ],
-        contextEntries: [
-          { id: "one", parentId: null, text: "first" },
-          { id: "two", parentId: "one-reply", text: "second" },
-        ],
       },
     ]);
   });
@@ -2101,6 +2194,33 @@ describe("PiRpcAgentSession", () => {
     });
   });
 
+  test.each([false, true])(
+    "rejects new turns with Reload guidance after the Pi process exits (active: %s)",
+    async (active) => {
+      const { pi, session, events } = await createSession();
+      try {
+        if (active) {
+          await session.startTurn("before crash");
+        }
+        const runtime = pi.latestSession();
+        runtime.emit({ type: "process_exit", error: "Pi exited" });
+        if (active) {
+          await expect(events.nextTurnFailure()).resolves.toMatchObject({ error: "Pi exited" });
+        }
+        const promptCount = runtime.prompts.length;
+
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+          await expect(session.startTurn("after crash")).rejects.toThrow(
+            "Pi process exited. Reload agent before sending another message.",
+          );
+        }
+        expect(runtime.prompts).toHaveLength(promptCount);
+      } finally {
+        await session.close();
+      }
+    },
+  );
+
   test("fails an autonomous turn when the Pi process exits before settlement", async () => {
     const { pi, events } = await createSession();
     const fakeSession = pi.latestSession();
@@ -2719,6 +2839,7 @@ describe("PiRpcAgentClient", () => {
     const root = mkdtempSync(path.join(tmpdir(), "paseo-pi-import-config-"));
     const cwd = path.join(root, "workspace");
     const sessionsDir = path.join(root, "sessions");
+    mkdirSync(cwd, { recursive: true });
     mkdirSync(sessionsDir, { recursive: true });
     const sessionFile = path.join(sessionsDir, "20260103_session.jsonl");
     writeFileSync(
@@ -2957,13 +3078,13 @@ describe("PiRpcAgentClient", () => {
     },
   );
 
-  test("lists no draft features without starting a Pi session", async () => {
+  test("lists no draft controls without starting a Pi session", async () => {
     const pi = new FakePi();
     const client = createClient(pi);
 
     await expect(
-      client.listFeatures(createConfig({ model: "openrouter/test/model" })),
-    ).resolves.toEqual([]);
+      client.listControls(createConfig({ model: "openrouter/test/model" })),
+    ).resolves.toEqual({ controls: [], options: {} });
 
     expect(pi.recordedLaunches).toHaveLength(0);
   });
@@ -3260,7 +3381,7 @@ describe("PiRpcAgentClient", () => {
       { id: "entry-1", parentId: null, text: "first prompt" },
       { id: "entry-3", parentId: "entry-2", text: "second prompt" },
     ];
-    pi.latestSession().contextUserEntries = pi.latestSession().treeUserEntries;
+    pi.latestSession().historyUserEntries = pi.latestSession().treeUserEntries;
 
     await session.startTurn("first prompt");
     pi.latestSession().finishTurn({ role: "assistant", content: [] });
@@ -3284,7 +3405,7 @@ describe("PiRpcAgentClient", () => {
       { id: "entry-1", parentId: null, text: "first prompt" },
       { id: "entry-3", parentId: "entry-2", text: "second prompt" },
     ];
-    fakeSession.contextUserEntries = [
+    fakeSession.historyUserEntries = [
       { id: "entry-3", parentId: "entry-2", text: "second prompt" },
     ];
 
@@ -3532,6 +3653,323 @@ describe("PiRpcAgentClient", () => {
   });
 });
 
+describe("PiRpcAgentClient history resume", () => {
+  const BUILTIN_MCP_COMMAND = {
+    name: "mcp",
+    source: "extension",
+    sourceInfo: { path: "builtin:mcp" },
+  } as const;
+  const PASEO_MCP_SERVERS = {
+    paseo: { type: "http", url: "http://127.0.0.1:6767/mcp/agents" },
+  } as const;
+
+  interface ArchivedPiSession {
+    handle: {
+      provider: string;
+      sessionId: string;
+      nativeHandle: string;
+      metadata: { cwd: string; model?: string };
+    };
+    sessionFile: string;
+    header: Record<string, unknown>;
+    body: string;
+    originalBytes: Buffer;
+  }
+
+  function createDeletedFolder(): string {
+    const folder = mkdtempSync(path.join(tmpdir(), "paseo-pi-deleted-cwd-"));
+    rmSync(folder, { recursive: true, force: true });
+    return folder;
+  }
+
+  function createFileWhereFolderWas(): string {
+    const folder = createDeletedFolder();
+    writeFileSync(folder, "not a directory");
+    onTestFinished(() => rmSync(folder, { force: true }));
+    return folder;
+  }
+
+  function createExistingFolder(): string {
+    const folder = mkdtempSync(path.join(tmpdir(), "paseo-pi-existing-cwd-"));
+    onTestFinished(() => rmSync(folder, { recursive: true, force: true }));
+    return folder;
+  }
+
+  function writeArchivedSession(cwd: string, metadata: { model?: string } = {}): ArchivedPiSession {
+    const dir = mkdtempSync(path.join(tmpdir(), "paseo-pi-archived-session-"));
+    onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
+    const sessionFile = path.join(dir, "2026-01-01_pi-session-1.jsonl");
+    const header = {
+      type: "session",
+      version: 3,
+      id: "pi-session-1",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      cwd,
+    };
+    const body = [
+      JSON.stringify({
+        type: "message",
+        id: "entry-1",
+        parentId: null,
+        message: { role: "user", content: "Où est le café ☕ ?" },
+      }),
+      JSON.stringify({
+        type: "message",
+        id: "entry-2",
+        parentId: "entry-1",
+        message: { role: "assistant", content: [{ type: "text", text: "Dans la cuisine." }] },
+      }),
+    ]
+      .map((line) => `${line}\n`)
+      .join("");
+    writeFileSync(sessionFile, `${JSON.stringify(header)}\n${body}`);
+    return {
+      handle: {
+        provider: "pi",
+        sessionId: "pi-session-1",
+        nativeHandle: sessionFile,
+        metadata: { cwd, ...metadata },
+      },
+      sessionFile,
+      header,
+      body,
+      originalBytes: readFileSync(sessionFile),
+    };
+  }
+
+  function readSessionCopy(sessionFile: string): { header: unknown; body: string } {
+    const content = readUtf8File(sessionFile);
+    const headerEnd = content.indexOf("\n");
+    return {
+      header: JSON.parse(content.slice(0, headerEnd)),
+      body: content.slice(headerEnd + 1),
+    };
+  }
+
+  function resumeArchived(
+    client: PiRpcAgentClient,
+    archived: ArchivedPiSession,
+    purpose: "history" | "interactive",
+    overrides: Partial<AgentSessionConfig> = {},
+  ): Promise<AgentSession> {
+    return client.resumeSession(archived.handle, overrides, undefined, { purpose });
+  }
+
+  function writeFakePiProcess(): {
+    command: [string, ...string[]];
+    readLaunches: () => Array<{ cwd: string; session: string | null }>;
+  } {
+    const dir = mkdtempSync(path.join(tmpdir(), "paseo-pi-process-"));
+    onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
+    const scriptPath = path.join(dir, "fake-pi.cjs");
+    const launchesPath = path.join(dir, "launches.jsonl");
+    writeFileSync(
+      scriptPath,
+      `
+const fs = require("node:fs");
+const readline = require("node:readline");
+const [launchesPath, ...piArgs] = process.argv.slice(2);
+const sessionFlag = piArgs.indexOf("--session");
+const sessionFile = sessionFlag === -1 ? null : piArgs[sessionFlag + 1];
+fs.appendFileSync(launchesPath, JSON.stringify({ cwd: process.cwd(), session: sessionFile }) + "\\n");
+if (sessionFile) {
+  const header = JSON.parse(fs.readFileSync(sessionFile, "utf8").split("\\n", 1)[0]);
+  if (header.cwd && !fs.existsSync(header.cwd)) {
+    fs.writeSync(
+      2,
+      "Stored session working directory does not exist: " + header.cwd + "\\nSession file: " + sessionFile + "\\nCurrent working directory: " + process.cwd() + "\\n",
+    );
+    process.exit(1);
+  }
+}
+const models = [
+  { provider: "openrouter", id: "a" },
+  { provider: "openrouter", id: "b" },
+];
+const state = {
+  sessionId: "pi-session-1",
+  sessionFile,
+  model: models[0],
+  thinkingLevel: "medium",
+  isStreaming: false,
+  isCompacting: false,
+  messageCount: 0,
+  pendingMessageCount: 0,
+};
+const commands = [${JSON.stringify(BUILTIN_MCP_COMMAND)}];
+function handle(request) {
+  switch (request.type) {
+    case "get_state":
+      return state;
+    case "get_commands":
+      return { commands };
+    case "get_available_models":
+      return { models };
+    case "set_model":
+      fs.appendFileSync(
+        sessionFile,
+        JSON.stringify({ type: "model_change", id: "model-1", provider: request.provider, modelId: request.modelId }) + "\\n",
+      );
+      state.model = models.find((model) => model.id === request.modelId);
+      return state.model;
+    default:
+      return {};
+  }
+}
+readline.createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line);
+  process.stdout.write(
+    JSON.stringify({ id: request.id, type: "response", command: request.type, success: true, data: handle(request) }) + "\\n",
+  );
+});
+`,
+    );
+    return {
+      command: [process.execPath, scriptPath, launchesPath],
+      readLaunches: () =>
+        readUtf8File(launchesPath)
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line) as { cwd: string; session: string | null }),
+    };
+  }
+
+  test.each([
+    ["is gone", createDeletedFolder],
+    ["is now a file", createFileWhereFolderWas],
+  ])(
+    "a history resume of an agent whose folder %s starts Pi from the home directory on a copy of its session",
+    async (_folderState, createFolder) => {
+      const archived = writeArchivedSession(createFolder());
+      const pi = new FakePi();
+
+      const session = await resumeArchived(createClient(pi), archived, "history");
+      onTestFinished(() => session.close());
+
+      expect(pi.recordedLaunches).toHaveLength(1);
+      const launch = pi.recordedLaunches[0]!;
+      expect(launch.cwd).toBe(homedir());
+      expect(launch.session).not.toBe(archived.sessionFile);
+      expect(readSessionCopy(launch.session!)).toEqual({
+        header: { ...archived.header, cwd: homedir() },
+        body: archived.body,
+      });
+    },
+  );
+
+  test("a history resume of an agent whose folder is gone removes its session copy after replay and leaves the original unchanged", async () => {
+    const archived = writeArchivedSession(createDeletedFolder());
+    const pi = new FakePi();
+
+    const session = await resumeArchived(createClient(pi), archived, "history");
+    const sessionCopy = pi.recordedLaunches[0]!.session!;
+    expect(existsSync(sessionCopy)).toBe(true);
+    for await (const _event of session.streamHistory()) {
+      // Completion releases both the runtime and its temporary session copy.
+    }
+    expect(pi.latestSession().closeCalls).toBe(1);
+
+    expect(existsSync(path.dirname(sessionCopy))).toBe(false);
+    expect(readFileSync(archived.sessionFile)).toEqual(archived.originalBytes);
+  });
+
+  test("a history resume of an agent whose folder is gone persists the original session file while Pi reports the copy", async () => {
+    const storedCwd = createDeletedFolder();
+    const archived = writeArchivedSession(storedCwd);
+    const pi = new FakePi();
+
+    const session = await resumeArchived(createClient(pi), archived, "history");
+    onTestFinished(() => session.close());
+    await session.getRuntimeInfo();
+
+    expect(pi.latestSession().state.sessionFile).toBe(pi.recordedLaunches[0]!.session);
+    expect(session.describePersistence()).toMatchObject({
+      nativeHandle: archived.sessionFile,
+      metadata: { cwd: storedCwd },
+    });
+  });
+
+  test("a history resume of an agent whose folder is gone removes its session copy when Pi fails to start", async () => {
+    const archived = writeArchivedSession(createDeletedFolder());
+    const pi = new FakePi();
+    pi.queueSessionSetup((session) => {
+      session.getStateError = new Error("Pi RPC process exited with code 1 and signal null");
+    });
+
+    await expect(resumeArchived(createClient(pi), archived, "history")).rejects.toThrow(
+      "Pi RPC process exited with code 1",
+    );
+
+    expect(pi.recordedLaunches).toHaveLength(1);
+    expect(pi.recordedLaunches[0]!.session).not.toBe(archived.sessionFile);
+    expect(existsSync(path.dirname(pi.recordedLaunches[0]!.session!))).toBe(false);
+  });
+
+  test("a history resume of an agent whose folder is gone checks MCP support from the home directory", async () => {
+    const archived = writeArchivedSession(createDeletedFolder());
+    const pi = new FakePi();
+    pi.queueCommands([BUILTIN_MCP_COMMAND]);
+
+    const session = await resumeArchived(createClient(pi), archived, "history", {
+      mcpServers: PASEO_MCP_SERVERS,
+    });
+    onTestFinished(() => session.close());
+
+    expect(pi.recordedLaunches.map((launch) => launch.cwd)).toEqual([homedir(), homedir()]);
+    expect(session.capabilities.supportsMcpServers).toBe(true);
+  });
+
+  test("an interactive resume of an agent whose folder is gone still fails in its stored folder", async () => {
+    const storedCwd = createDeletedFolder();
+    const archived = writeArchivedSession(storedCwd);
+    const pi = new FakePi();
+
+    await expect(resumeArchived(createClient(pi), archived, "interactive")).rejects.toThrow(
+      `Stored session working directory does not exist: ${storedCwd}`,
+    );
+
+    expect(pi.recordedLaunches).toMatchObject([{ cwd: storedCwd, session: archived.sessionFile }]);
+  });
+
+  test("a history resume of an agent whose folder exists keeps the stored folder and session file", async () => {
+    const storedCwd = createExistingFolder();
+    const archived = writeArchivedSession(storedCwd);
+    const pi = new FakePi();
+
+    const session = await resumeArchived(createClient(pi), archived, "history");
+    onTestFinished(() => session.close());
+
+    expect(pi.recordedLaunches).toMatchObject([{ cwd: storedCwd, session: archived.sessionFile }]);
+  });
+
+  test("a history resume of an agent whose folder is gone opens its session in a real Pi process started from the home directory", async () => {
+    const archived = writeArchivedSession(createDeletedFolder(), { model: "openrouter/b" });
+    const fakePiProcess = writeFakePiProcess();
+    const logger = pino({ level: "silent" });
+    const client = new PiRpcAgentClient({
+      logger,
+      runtime: new PiCliRuntime({ logger, command: fakePiProcess.command }),
+    });
+
+    const session = await resumeArchived(client, archived, "history", {
+      mcpServers: PASEO_MCP_SERVERS,
+    });
+    onTestFinished(() => session.close());
+
+    const launches = fakePiProcess.readLaunches();
+    const home = realpathSync.native(homedir());
+    expect(launches.map((launch) => realpathSync.native(launch.cwd))).toEqual([home, home]);
+    expect(session.capabilities.supportsMcpServers).toBe(true);
+    const sessionCopy = launches[1]!.session!;
+    expect(readUtf8File(sessionCopy)).toContain('"type":"model_change"');
+    expect(session.describePersistence()?.nativeHandle).toBe(archived.sessionFile);
+
+    await session.close();
+    expect(existsSync(path.dirname(sessionCopy))).toBe(false);
+    expect(readFileSync(archived.sessionFile)).toEqual(archived.originalBytes);
+  });
+});
+
 describe("transformPiModels", () => {
   test("normalizes labels that include the upstream provider prefix", () => {
     expect(
diff --git a/packages/server/src/server/agent/providers/pi/agent.ts b/packages/server/src/server/agent/providers/pi/agent.ts
index 95323ba310..faf3d0e6f3 100644
--- a/packages/server/src/server/agent/providers/pi/agent.ts
+++ b/packages/server/src/server/agent/providers/pi/agent.ts
@@ -2,7 +2,7 @@ import { mapCustomMessageToToolCall } from "../custom-message.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve as resolvePath } from "node:path";
+import { basename, join, resolve as resolvePath } from "node:path";
 import type { Logger } from "pino";
 import stripAnsi from "strip-ansi";
 import { z } from "zod";
@@ -10,7 +10,7 @@ import { z } from "zod";
 import {
   type AgentCapabilityFlags,
   type AgentClient,
-  type AgentFeature,
+  type AgentDraftControls,
   type AgentLaunchContext,
   type AgentMetadata,
   type AgentMode,
@@ -22,6 +22,7 @@ import {
   type AgentPersistenceHandle,
   type AgentPromptInput,
   type AgentProvider,
+  type AgentResumeSessionOptions,
   type AgentRunOptions,
   type AgentRunResult,
   type AgentRuntimeInfo,
@@ -77,8 +78,13 @@ import {
   piExtensionRuntimeBridge,
   type PiExtensionEventOutput,
 } from "./extensions/index.js";
+import { resolveResumeProcessCwd } from "../resume-process-cwd.js";
 import { revertPiConversation } from "./rewind.js";
-import { listPiImportableSessions, readPiImportSessionConfig } from "./session-descriptor.js";
+import {
+  copyPiSessionFileWithCwd,
+  listPiImportableSessions,
+  readPiImportSessionConfig,
+} from "./session-descriptor.js";
 import type { PiRuntime, PiRuntimeSession, PiStartSessionInput } from "./runtime.js";
 import type {
   PiAgentSessionEvent,
@@ -247,7 +253,9 @@ interface PiRpcAgentSessionOptions {
   initialState: PiSessionState;
   capabilities: AgentCapabilityFlags;
   currentModeId?: string | null;
+  persistedSessionFile?: string;
   cleanup?: () => void;
+  closeAfterHistory?: boolean;
   extensionTimeoutMs?: number;
   logger: Logger;
   usagePollScheduler?: PiUsagePollScheduler;
@@ -494,13 +502,14 @@ function buildResumeConfig(
 
 function buildResumeStartInput(input: {
   resumeConfig: PiResumeConfig;
+  processCwd: string;
   sessionFile: string;
   launchContext: AgentLaunchContext | undefined;
   mcpConfigFile: PiTempFile | null;
   paseoExtension: PiTempFile | null;
 }): PiStartSessionInput {
   return {
-    cwd: input.resumeConfig.cwd,
+    cwd: input.processCwd,
     env: input.launchContext?.env,
     session: input.sessionFile,
     thinkingOptionId: normalizePiThinkingOption(input.resumeConfig.thinkingOptionId) ?? undefined,
@@ -620,6 +629,19 @@ function createPiMcpConfigFile(
   };
 }
 
+async function createPiSessionCopy(sessionFile: string, cwd: string): Promise<PiTempFile> {
+  const dir = mkdtempSync(join(tmpdir(), "paseo-pi-session-"));
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  const filePath = join(dir, basename(sessionFile));
+  try {
+    await copyPiSessionFileWithCwd({ sourceFile: sessionFile, targetFile: filePath, cwd });
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  return { path: filePath, cleanup };
+}
+
 function createPiPaseoExtensionFile({
   systemPrompt,
   mcpServers = {},
@@ -668,8 +690,6 @@ function createPiPaseoExtensionFile({
 	        requestId,
 	        // Rewind targets: rows can still show entries that a rewind or compaction left off the branch.
 	        treeEntries: toCapturedUserEntries(ctx.sessionManager.getEntries()),
-	        // The entries getMessages() replays, so the nth one is the nth replayed user message.
-	        contextEntries: toCapturedUserEntries(ctx.sessionManager.buildContextEntries()),
 	      }),
 	    "info",
 	  );
@@ -1193,7 +1213,6 @@ export class PiRpcAgentSession implements AgentSession {
   private readonly pendingPromptResults = new Map<string, boolean>();
   private readonly pendingSteerSubmissions: PiPendingSteerSubmission[] = [];
   currentLeafOverrideId: string | null | undefined;
-  private readonly contextUserEntries: PiCapturedEntry[] = [];
   private readonly treeUserEntriesById = new Map<string, PiCapturedEntry>();
   private readonly pendingExtensionResults = new Map<string, PendingExtensionResult>();
   private compactionPromise: Promise<void> | null = null;
@@ -1206,6 +1225,7 @@ export class PiRpcAgentSession implements AgentSession {
   private readonly logger: Logger;
   private readonly usagePoller: PiUsagePoller;
   private closed = false;
+  private runtimeDead = false;
   private readonly closeController = new AbortController();
   private readonly pendingExtensionHydrations = new Set<Promise<void>>();
   private pendingOutput: Promise<void> | null = null;
@@ -1234,7 +1254,9 @@ export class PiRpcAgentSession implements AgentSession {
     this.capabilities = options.capabilities;
     this.provider = PI_PROVIDER;
     this.currentModeId = options.currentModeId ?? null;
+    this.persistedSessionFile = options.persistedSessionFile;
     this.cleanup = options.cleanup;
+    this.closeAfterHistory = options.closeAfterHistory ?? false;
     this.extensionTimeoutMs = options.extensionTimeoutMs ?? DEFAULT_PI_EXTENSION_RESULT_TIMEOUT_MS;
     this.logger = options.logger;
     this.extensionHost = createPiExtensionHost(this.logger);
@@ -1264,7 +1286,9 @@ export class PiRpcAgentSession implements AgentSession {
 
   private readonly runtimeSession: PiRuntimeSession;
   private readonly config: AgentSessionConfig;
+  private readonly persistedSessionFile?: string;
   private readonly cleanup?: () => void;
+  private readonly closeAfterHistory: boolean;
   private readonly extensionTimeoutMs: number;
 
   get id(): string | null {
@@ -1284,6 +1308,9 @@ export class PiRpcAgentSession implements AgentSession {
   }
 
   async startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<StartTurnResult> {
+    if (this.runtimeDead) {
+      throw new Error("Pi process exited. Reload agent before sending another message.");
+    }
     if (this.activeTurnId) {
       throw new Error("A Pi turn is already active");
     }
@@ -1433,16 +1460,21 @@ export class PiRpcAgentSession implements AgentSession {
   }
 
   async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
-    await this.requestEntryCapture("history");
-    yield* streamPiHistory(
-      this.provider,
-      await this.runtimeSession.getMessages(),
-      this.contextUserEntries,
-      {},
-      // At most eight 2 MiB child files per replay; later cards retain their summaries.
-      createPiExtensionHost(this.logger, undefined, 16 * 1024 * 1024),
-      this.closeController.signal,
-    );
+    try {
+      await this.requestEntryCapture("history");
+      const history = await this.runtimeSession.getHistory();
+      yield* streamPiHistory(
+        this.provider,
+        history.messages,
+        history.userEntries,
+        {},
+        // At most eight 2 MiB child files per replay; later cards retain their summaries.
+        createPiExtensionHost(this.logger, undefined, 16 * 1024 * 1024),
+        this.closeController.signal,
+      );
+    } finally {
+      if (this.closeAfterHistory) await this.close();
+    }
   }
 
   async getRuntimeInfo(): Promise<AgentRuntimeInfo> {
@@ -1498,7 +1530,7 @@ export class PiRpcAgentSession implements AgentSession {
     return {
       provider: this.provider,
       sessionId: this.state.sessionId,
-      nativeHandle: this.state.sessionFile,
+      nativeHandle: this.persistedSessionFile ?? this.state.sessionFile,
       metadata: {
         cwd: this.config.cwd,
         ...(this.config.model ? { model: this.config.model } : {}),
@@ -1684,10 +1716,10 @@ export class PiRpcAgentSession implements AgentSession {
     return null;
   }
 
-  async setModel(modelId: string | null): Promise<void> {
+  async setModel(modelId: string | null): Promise<{ model: string | null }> {
     const parsedReference = parseModelReference(modelId);
     if (!parsedReference) {
-      return;
+      return { model: modelToId(this.state.model) };
     }
     if (!parsedReference.provider) {
       throw new Error(`Pi model id must include a provider: ${modelId}`);
@@ -1696,6 +1728,7 @@ export class PiRpcAgentSession implements AgentSession {
     const model = await this.runtimeSession.setModel(parsedReference.provider, parsedReference.id);
     await this.refreshState();
     this.config.model = `${model.provider}/${model.id}`;
+    return { model: modelToId(this.state.model) };
   }
 
   async setThinkingOption(thinkingOptionId: string | null): Promise<void> {
@@ -1999,13 +2032,9 @@ export class PiRpcAgentSession implements AgentSession {
     }
   }
 
-  private recordCapturedUserEntries(input: {
-    treeEntries: PiCapturedEntry[];
-    contextEntries: PiCapturedEntry[];
-  }): void {
-    this.contextUserEntries.splice(0, this.contextUserEntries.length, ...input.contextEntries);
+  private recordCapturedUserEntries(entries: PiCapturedEntry[]): void {
     this.treeUserEntriesById.clear();
-    for (const entry of input.treeEntries) {
+    for (const entry of entries) {
       this.treeUserEntriesById.set(entry.id, entry);
     }
   }
@@ -2042,10 +2071,7 @@ export class PiRpcAgentSession implements AgentSession {
     if (!payload) {
       return false;
     }
-    this.recordCapturedUserEntries({
-      treeEntries: parseCapturedEntries(payload.treeEntries),
-      contextEntries: parseCapturedEntries(payload.contextEntries),
-    });
+    this.recordCapturedUserEntries(parseCapturedEntries(payload.treeEntries));
     if (typeof payload.requestId === "string") {
       this.resolveExtensionResult(payload.requestId, undefined);
     }
@@ -2181,6 +2207,7 @@ export class PiRpcAgentSession implements AgentSession {
   }
 
   private handleProcessExit(error: string): void {
+    this.runtimeDead = true;
     this.rejectAllExtensionResults(new Error(error));
     this.interruptingTurn = null;
     if (!this.activeTurnId && !this.activeTurnStarted) {
@@ -2657,6 +2684,7 @@ export class PiRpcAgentClient implements AgentClient {
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
     launchContext?: AgentLaunchContext,
+    options?: AgentResumeSessionOptions,
   ): Promise<AgentSession> {
     const sessionFile = handle.nativeHandle;
     if (!sessionFile) {
@@ -2665,6 +2693,7 @@ export class PiRpcAgentClient implements AgentClient {
 
     const persistenceMetadata = parsePersistenceMetadata(handle.metadata);
     const resumeConfig = buildResumeConfig(persistenceMetadata, overrides, this.provider);
+    const processCwd = await resolveResumeProcessCwd(resumeConfig.cwd, options?.purpose);
 
     const providerOptions = PiProviderOptionsSchema.parse(
       resumeConfig.config.providerOptions ?? {},
@@ -2675,7 +2704,7 @@ export class PiRpcAgentClient implements AgentClient {
       ...launchContext?.env,
     };
     const mcp = await this.prepareMcpInjection(
-      resumeConfig.cwd,
+      processCwd,
       resumeConfig.config.mcpServers,
       mcpEnv,
       runtime,
@@ -2688,20 +2717,29 @@ export class PiRpcAgentClient implements AgentClient {
       ),
       mcpServers: mcp?.kind === "builtin" ? mcp.servers : undefined,
     });
+    const tempFiles = mcpConfigFile ? [mcpConfigFile, paseoExtension] : [paseoExtension];
+    const cleanupTempFiles = () => {
+      for (const tempFile of tempFiles) tempFile.cleanup();
+    };
+    let sessionCopy: PiTempFile | null = null;
     let runtimeSession: PiRuntimeSession;
     try {
+      if (processCwd !== resumeConfig.cwd) {
+        sessionCopy = await createPiSessionCopy(sessionFile, processCwd);
+        tempFiles.push(sessionCopy);
+      }
       runtimeSession = await runtime.startSession(
         buildResumeStartInput({
           resumeConfig,
-          sessionFile,
+          processCwd,
+          sessionFile: sessionCopy?.path ?? sessionFile,
           launchContext,
           mcpConfigFile,
           paseoExtension,
         }),
       );
     } catch (error) {
-      mcpConfigFile?.cleanup();
-      paseoExtension?.cleanup();
+      cleanupTempFiles();
       throw error;
     }
     try {
@@ -2714,15 +2752,16 @@ export class PiRpcAgentClient implements AgentClient {
         },
         initialState,
         capabilities: capabilitiesForSession(mcp !== null),
-        cleanup: combineCleanup([mcpConfigFile?.cleanup, paseoExtension?.cleanup]),
+        persistedSessionFile: sessionCopy ? sessionFile : undefined,
+        cleanup: cleanupTempFiles,
+        closeAfterHistory: options?.purpose === "history",
         extensionTimeoutMs: providerOptions.extensionTimeoutMs,
         logger: this.logger,
         usagePollScheduler: this.usagePollScheduler,
       });
     } catch (error) {
       await runtimeSession.close().catch(() => undefined);
-      mcpConfigFile?.cleanup();
-      paseoExtension?.cleanup();
+      cleanupTempFiles();
       throw error;
     }
   }
@@ -2806,8 +2845,8 @@ export class PiRpcAgentClient implements AgentClient {
     }
   }
 
-  async listFeatures(_config: AgentSessionConfig): Promise<AgentFeature[]> {
-    return [];
+  async listControls(config: AgentSessionConfig): Promise<AgentDraftControls> {
+    return { controls: [], options: config.providerOptions ?? {} };
   }
 
   async listImportableSessions(
diff --git a/packages/server/src/server/agent/providers/pi/cli-runtime.test.ts b/packages/server/src/server/agent/providers/pi/cli-runtime.test.ts
index 463870760f..8a838d74d9 100644
--- a/packages/server/src/server/agent/providers/pi/cli-runtime.test.ts
+++ b/packages/server/src/server/agent/providers/pi/cli-runtime.test.ts
@@ -1,3 +1,5 @@
+import { mkdir, mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import path from "node:path";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
@@ -545,3 +547,102 @@ describe("PiCliRuntime", () => {
     await expect(session.abort()).resolves.toBeUndefined();
   });
 });
+
+async function createHistoryTestDirectory(prefix: string): Promise<string> {
+  const artifacts = path.resolve(".artifacts/pi-timeline");
+  await mkdir(artifacts, { recursive: true });
+  return mkdtemp(path.join(artifacts, prefix));
+}
+
+test("reads complete persisted history instead of compacted RPC context", async () => {
+  const root = await createHistoryTestDirectory("runtime-");
+  const file = path.join(root, "session.jsonl");
+  const records = [
+    { type: "session", version: 3, id: "session" },
+    {
+      type: "message",
+      id: "old-user",
+      parentId: "system",
+      message: { role: "user", content: "before compaction" },
+    },
+    {
+      type: "message",
+      id: "old-answer",
+      parentId: "old-user",
+      message: { role: "assistant", content: [{ type: "text", text: "old answer" }] },
+    },
+    { type: "compaction", id: "compact", parentId: "old-answer", summary: "summary" },
+    {
+      type: "message",
+      id: "new-user",
+      parentId: "compact",
+      message: { role: "user", content: "after compaction" },
+    },
+  ];
+  records.splice(1, 0, {
+    type: "message",
+    id: "system",
+    parentId: null,
+    message: { role: "system", content: "private instructions" },
+  });
+  const contents = records.map((row) => JSON.stringify(row)).join("\n");
+  await writeFile(file, contents);
+  const child = createPiChild();
+  onPiCommand(child, (command) =>
+    writePiResponse(
+      child,
+      command,
+      command.type === "get_state" ? { sessionFile: file } : { messages: [records[5].message] },
+    ),
+  );
+  const runtime = await createRuntime(child).startSession({ cwd: root });
+  try {
+    const history = await runtime.getHistory();
+    expect(history.userEntries.map((entry) => entry.id)).toEqual(["old-user", "new-user"]);
+    expect(history.messages).toEqual([records[2].message, records[3].message, records[5].message]);
+    expect(await readFile(file, "utf8")).toBe(contents);
+    await writeFile(
+      file,
+      contents +
+        '\n{"type":"custom","id":"rewind","parentId":"old-answer","customType":"paseo_rewind"}',
+    );
+    expect((await runtime.getHistory()).userEntries.map((entry) => entry.id)).toEqual(["old-user"]);
+    await writeFile(
+      file,
+      contents + '\n{"type":"custom","id":"rewind","parentId":null,"customType":"paseo_rewind"}',
+    );
+    expect((await runtime.getHistory()).messages).toEqual([]);
+    await writeFile(file, contents + '\n{"type":"custom","id":"bad","parentId":"missing"}');
+    await expect(runtime.getHistory()).rejects.toThrow("Missing Pi transcript ancestor");
+  } finally {
+    await runtime.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("permits the unpersisted empty new session but refuses a missing resumed transcript", async () => {
+  const root = await createHistoryTestDirectory("empty-");
+  const file = path.join(root, "not-created.jsonl");
+  const child = createPiChild();
+  onPiCommand(child, (command) =>
+    writePiResponse(child, command, { sessionFile: file, messageCount: 0 }),
+  );
+  const runtime = createRuntime(child);
+  const fresh = await runtime.startSession({ cwd: root });
+  try {
+    expect(await fresh.getHistory()).toEqual({ messages: [], userEntries: [] });
+  } finally {
+    await fresh.close();
+  }
+  const resumedChild = createPiChild();
+  onPiCommand(resumedChild, (command) =>
+    writePiResponse(resumedChild, command, { sessionFile: file, messageCount: 0 }),
+  );
+  const resumed = await createRuntime(resumedChild).startSession({ cwd: root, session: file });
+  try {
+    await expect(resumed.getHistory()).rejects.toThrow("ENOENT");
+  } finally {
+    await resumed.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/agent/providers/pi/cli-runtime.ts b/packages/server/src/server/agent/providers/pi/cli-runtime.ts
index 62ee01c503..78c1fc7cf6 100644
--- a/packages/server/src/server/agent/providers/pi/cli-runtime.ts
+++ b/packages/server/src/server/agent/providers/pi/cli-runtime.ts
@@ -1,3 +1,5 @@
+import { readFile } from "node:fs/promises";
+import { readPiTranscript, type PiTranscript } from "./transcript.js";
 import { createExternalProcessEnv } from "../../../paseo-env.js";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { Logger } from "pino";
@@ -16,7 +18,6 @@ import {
   type PiStartSessionInput,
 } from "./runtime.js";
 import type {
-  PiAgentMessage,
   PiModel,
   PiPromptAck,
   PiRpcCommand,
@@ -78,18 +79,27 @@ export class PiCliRuntime implements PiRuntime {
       await process.close(input.signal.reason);
       input.signal.throwIfAborted();
     }
-    return new PiCliRuntimeSession(process, this.commandsRpcName, launch.env);
+    return new PiCliRuntimeSession({
+      process,
+      commandsRpcName: this.commandsRpcName,
+      launchEnvironment: launch.env,
+      newSession: input.session === undefined,
+    });
   }
 }
 
+interface PiCliRuntimeSessionOptions {
+  process: JsonlRpcProcess;
+  commandsRpcName: string;
+  launchEnvironment: Record<string, string>;
+  newSession: boolean;
+}
+
 class PiCliRuntimeSession implements PiRuntimeSession {
   private readonly subscribers = new Set<(event: PiRuntimeEvent) => void>();
 
-  constructor(
-    private readonly process: JsonlRpcProcess,
-    private readonly commandsRpcName: string,
-    private readonly launchEnvironment: Record<string, string>,
-  ) {
+  constructor(private readonly options: PiCliRuntimeSessionOptions) {
+    const { process } = options;
     process.onMessage((message) => {
       this.emit(message as PiRuntimeEvent);
     });
@@ -99,7 +109,7 @@ class PiCliRuntimeSession implements PiRuntimeSession {
   }
 
   get environment(): Record<string, string> {
-    return this.launchEnvironment;
+    return this.options.launchEnvironment;
   }
 
   onEvent(callback: (event: PiRuntimeEvent) => void): () => void {
@@ -113,7 +123,7 @@ class PiCliRuntimeSession implements PiRuntimeSession {
     message: string,
     images?: Array<{ type: "image"; data: string; mimeType: string }>,
   ): Promise<PiPromptAck> {
-    const { id: requestId, promise } = this.process.startRequest({
+    const { id: requestId, promise } = this.options.process.startRequest({
       type: "prompt",
       message,
       ...(images?.length ? { images } : {}),
@@ -162,9 +172,23 @@ class PiCliRuntimeSession implements PiRuntimeSession {
     return (await this.request({ type: "get_state" })) as PiSessionState;
   }
 
-  async getMessages(): Promise<PiAgentMessage[]> {
-    const data = (await this.request({ type: "get_messages" })) as { messages?: PiAgentMessage[] };
-    return data.messages ?? [];
+  async getHistory(): Promise<PiTranscript> {
+    const state = await this.getState();
+    if (!state.sessionFile) throw new Error("Pi history requires a persisted session file");
+    try {
+      return readPiTranscript(await readFile(state.sessionFile, "utf8"));
+    } catch (error) {
+      // Pi does not create the file until the first conversation message is saved.
+      if (
+        this.options.newSession &&
+        state.messageCount === 0 &&
+        error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT"
+      )
+        return { messages: [], userEntries: [] };
+      throw error;
+    }
   }
 
   async getAvailableModels(timeoutMs?: number | null): Promise<PiModel[]> {
@@ -215,21 +239,21 @@ class PiCliRuntimeSession implements PiRuntimeSession {
   }
 
   async getCommands(): Promise<PiRpcSlashCommand[]> {
-    const data = (await this.request({ type: this.commandsRpcName })) as {
+    const data = (await this.request({ type: this.options.commandsRpcName })) as {
       commands?: PiRpcSlashCommand[];
     };
     return data.commands ?? [];
   }
 
   sendRawFrame(frame: object & { type: string }): void {
-    this.process.send(frame);
+    this.options.process.send(frame);
   }
 
   respondToExtensionUiRequest(
     id: string,
     response: { value?: string; confirmed?: boolean; cancelled?: boolean },
   ): void {
-    this.process.send({ type: "extension_ui_response", id, ...response });
+    this.options.process.send({ type: "extension_ui_response", id, ...response });
   }
 
   cancelExtensionUiRequest(id: string): void {
@@ -237,22 +261,22 @@ class PiCliRuntimeSession implements PiRuntimeSession {
   }
 
   async close(): Promise<void> {
-    await this.process.close(new Error("Pi RPC session is closed"));
+    await this.options.process.close(new Error("Pi RPC session is closed"));
   }
 
   request(command: PiRpcCommand, timeoutMs?: number | null): Promise<unknown> {
-    return this.process.request(command, timeoutMs);
+    return this.options.process.request(command, timeoutMs);
   }
 
   private requestStopWork(command: PiRpcCommand): Promise<void> {
-    return this.process.requestStopWork(command);
+    return this.options.process.requestStopWork(command);
   }
 
   private async waitForCompletion(command: PiRpcCommand): Promise<void> {
     // Pi only replies after its compaction work is durable. Its child process and
     // session close paths already reject pending RPCs, so no elapsed-time failure
     // is useful here.
-    await this.process.request(command, JSONL_RPC_NO_TIMEOUT);
+    await this.options.process.request(command, JSONL_RPC_NO_TIMEOUT);
   }
 
   private emit(event: PiRuntimeEvent): void {
diff --git a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.test.ts b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.test.ts
index a0d5d2512f..7ebe158613 100644
--- a/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.test.ts
+++ b/packages/server/src/server/agent/providers/pi/extensions/edxeth-pi-subagents/index.test.ts
@@ -279,7 +279,7 @@ describe("edxeth/pi-subagents adapter", () => {
       for await (const event of streamPiHistory("pi", fixture.messages)) {
         if (event.type === "provider_subagent") await store.apply("parent", "pi", event.event);
       }
-      const children = store.list("parent");
+      const children = await store.list("parent");
       expect(children).toEqual([expect.objectContaining({ status: "completed", title: "marker" })]);
       const transcript = await store.fetchTimeline("parent", children[0]!.id);
       expect(transcript.rows).toContainEqual(
diff --git a/packages/server/src/server/agent/providers/pi/history-mapper.test.ts b/packages/server/src/server/agent/providers/pi/history-mapper.test.ts
index f4136956eb..b6f4349f47 100644
--- a/packages/server/src/server/agent/providers/pi/history-mapper.test.ts
+++ b/packages/server/src/server/agent/providers/pi/history-mapper.test.ts
@@ -1,3 +1,5 @@
+import { buildAgentForkContextAttachment } from "../../activity-curator.js";
+import { readPiTranscript } from "./transcript.js";
 import { describe, expect, test } from "vitest";
 
 import type { AgentStreamEvent } from "../../agent-sdk-types.js";
@@ -293,3 +295,235 @@ test("replayed Pi images keep their position before the following reply", async
     ),
   ).toEqual(["tool_call", expect.stringContaining("![Image]("), "Image read complete."]);
 });
+
+test("replays both sides of compaction with native IDs and isolates rewound branches", async () => {
+  const records = [
+    { type: "session", version: 3, id: "session" },
+    {
+      type: "message",
+      id: "u1",
+      parentId: null,
+      message: { role: "user", content: "old question" },
+    },
+    {
+      type: "message",
+      id: "a1",
+      parentId: "u1",
+      message: { role: "assistant", content: [{ type: "text", text: "old answer" }] },
+    },
+    { type: "compaction", id: "c1", parentId: "a1", summary: "summary", firstKeptEntryId: "a1" },
+    { type: "message", id: "u2", parentId: "c1", message: { role: "user", content: "follow up" } },
+  ];
+  const decode = (rows: unknown[]) =>
+    readPiTranscript(rows.map((row) => JSON.stringify(row)).join("\n"));
+  const history = decode(records);
+  expect(history.userEntries.map((entry) => entry.id)).toEqual(["u1", "u2"]);
+  expect(history.messages.map((message) => message.role)).toEqual(["user", "assistant", "user"]);
+  expect(await collectHistory(history.messages, history.userEntries)).toHaveLength(3);
+  const rewound = [
+    ...records,
+    { type: "custom", id: "r1", parentId: null, customType: "paseo_rewind" },
+  ];
+  expect(decode(rewound).messages).toEqual([]);
+  const replacement = [
+    ...rewound,
+    {
+      type: "message",
+      id: "u3",
+      parentId: "r1",
+      message: { role: "user", content: "replacement" },
+    },
+  ];
+  expect(decode(replacement).userEntries.map((entry) => entry.id)).toEqual(["u3"]);
+  expect(
+    decode([
+      ...replacement,
+      { type: "custom", id: "r2", parentId: "a1", customType: "paseo_rewind" },
+    ]).userEntries.map((entry) => entry.id),
+  ).toEqual(["u1"]);
+});
+
+test("preserves native custom entries and legacy linear messages without inventing native IDs", async () => {
+  const custom = {
+    type: "custom_message",
+    id: "custom",
+    parentId: null,
+    customType: "notice",
+    content: "visible notice",
+    display: true,
+    details: { key: 1 },
+  };
+  const history = readPiTranscript(
+    [JSON.stringify({ type: "session", version: 3 }), JSON.stringify(custom)].join("\n"),
+  );
+  expect(history.messages).toEqual([{ ...custom, role: "custom" }]);
+  expect(await collectHistory(history.messages, history.userEntries)).toHaveLength(1);
+  const legacy = readPiTranscript(
+    '{"type":"session","version":1}\n{"type":"message","message":{"role":"user","content":"legacy"}}',
+  );
+  expect(legacy.messages).toEqual([{ role: "user", content: "legacy" }]);
+  expect(legacy.userEntries).toEqual([]);
+});
+
+test.each([
+  [{ type: "message", id: "x", parentId: "x", message: { role: "user", content: "cycle" } }],
+  [{ type: "message", id: "x", parentId: "missing", message: { role: "user", content: "orphan" } }],
+  [
+    { type: "custom", id: "x", parentId: null },
+    { type: "custom", id: "x", parentId: null },
+  ],
+  [{ type: "custom", id: "x" }],
+])("rejects corrupt ancestry rather than replaying a plausible branch: %j", (...entries) => {
+  expect(() =>
+    readPiTranscript(
+      [
+        JSON.stringify({ type: "session", version: 3 }),
+        ...entries.map((entry) => JSON.stringify(entry)),
+      ].join("\n"),
+    ),
+  ).toThrow();
+});
+
+test("Fork chat stops at a restored pre-compaction reply on the active branch", async () => {
+  const entries = [
+    { type: "session", version: 3 },
+    {
+      type: "message",
+      id: "u1",
+      parentId: null,
+      message: { role: "user", content: "retained question" },
+    },
+    {
+      type: "message",
+      id: "a1",
+      parentId: "u1",
+      message: { role: "assistant", content: [{ type: "text", text: "retained answer" }] },
+    },
+    {
+      type: "message",
+      id: "abandoned",
+      parentId: "a1",
+      message: { role: "user", content: "abandoned branch" },
+    },
+    { type: "compaction", id: "c1", parentId: "a1", summary: "summary" },
+    {
+      type: "message",
+      id: "later",
+      parentId: "c1",
+      message: { role: "user", content: "later question" },
+    },
+  ];
+  const transcript = readPiTranscript(entries.map((entry) => JSON.stringify(entry)).join("\n"));
+  const events = await collectHistory(transcript.messages, transcript.userEntries);
+  const rows = events
+    .filter((event) => event.type === "timeline")
+    .map((event, index) => ({
+      seq: index + 1,
+      timestamp: "2026-10-31T00:00:00.000Z",
+      item: event.item,
+    }));
+  const fork = buildAgentForkContextAttachment({
+    rows,
+    cursorBoundary: { cursor: { epoch: "test", seq: 2 }, timelineEpoch: "test" },
+  });
+  expect(fork.attachment.text).toContain("retained question");
+  expect(fork.attachment.text).toContain("retained answer");
+  expect(fork.attachment.text).not.toContain("abandoned branch");
+  expect(fork.attachment.text).not.toContain("later question");
+  expect(transcript.userEntries.map((entry) => entry.id)).toEqual(["u1", "later"]);
+});
+
+test("keeps reasoning, image content and tool results across structural entries", async () => {
+  const messages: PiAgentMessage[] = [
+    {
+      role: "user",
+      content: [
+        { type: "image", data: "aGVsbG8=", mimeType: "image/png" },
+        { type: "text", text: "inspect" },
+      ],
+    },
+    {
+      role: "assistant",
+      content: [
+        { type: "thinking", thinking: "consider" },
+        { type: "toolCall", id: "call", name: "read", arguments: { path: "a.txt" } },
+      ],
+    },
+    {
+      role: "toolResult",
+      toolCallId: "call",
+      toolName: "read",
+      content: [{ type: "text", text: "file contents" }],
+    },
+    { role: "assistant", content: [{ type: "text", text: "answer" }] },
+  ];
+  const records = [
+    { type: "session", version: 3 },
+    ...messages.map((message, index) => ({
+      type: "message",
+      id: String(index),
+      parentId: index === 0 ? null : String(index - 1),
+      message,
+    })),
+    { type: "compaction", id: "compact", parentId: "3", summary: "summary" },
+  ];
+  const history = readPiTranscript(records.map((record) => JSON.stringify(record)).join("\n"));
+  expect(history.messages).toEqual(messages);
+  expect(history.userEntries).toEqual([{ id: "0", text: "inspect" }]);
+  expect(await collectHistory(history.messages, history.userEntries)).toEqual(
+    await collectHistory(messages, [{ id: "0", text: "inspect" }]),
+  );
+});
+
+test("traverses native system and summary messages without displaying private context", () => {
+  const roles = [
+    { role: "system", content: "private instructions" },
+    { role: "user", content: "question" },
+    { role: "branchSummary", summary: "branch context" },
+    { role: "compactionSummary", summary: "compacted context" },
+    { role: "system", content: null },
+  ];
+  const rows = [
+    { type: "session", version: 3 },
+    ...roles.map((message, index) => ({
+      type: "message",
+      id: String(index),
+      parentId: index === 0 ? null : String(index - 1),
+      message,
+    })),
+  ];
+  expect(readPiTranscript(rows.map((row) => JSON.stringify(row)).join("\n"))).toEqual({
+    messages: [{ role: "user", content: "question" }],
+    userEntries: [{ id: "1", text: "question" }],
+  });
+});
+
+test("restores surrounding chat when native system content uses text blocks", async () => {
+  const records = [
+    { type: "session", version: 3 },
+    { type: "message", id: "u", parentId: null, message: { role: "user", content: "question" } },
+    {
+      type: "message",
+      id: "s",
+      parentId: "u",
+      message: { role: "system", content: [{ type: "text", text: "private instructions" }] },
+    },
+    {
+      type: "message",
+      id: "a",
+      parentId: "s",
+      message: { role: "assistant", content: [{ type: "text", text: "answer" }] },
+    },
+  ];
+  const history = readPiTranscript(records.map((record) => JSON.stringify(record)).join("\n"));
+  expect(history.messages).toEqual([
+    { role: "user", content: "question" },
+    { role: "assistant", content: [{ type: "text", text: "answer" }] },
+  ]);
+  expect(history.userEntries).toEqual([{ id: "u", text: "question" }]);
+  const events = await collectHistory(history.messages, history.userEntries);
+  expect(events.map((event) => event.item)).toEqual([
+    { type: "user_message", text: "question", messageId: "u" },
+    { type: "assistant_message", text: "answer", messageId: "pi-history-assistant-1" },
+  ]);
+});
diff --git a/packages/server/src/server/agent/providers/pi/runtime.ts b/packages/server/src/server/agent/providers/pi/runtime.ts
index 1064952e6d..42399d3275 100644
--- a/packages/server/src/server/agent/providers/pi/runtime.ts
+++ b/packages/server/src/server/agent/providers/pi/runtime.ts
@@ -1,5 +1,5 @@
+import type { PiTranscript } from "./transcript.js";
 import type {
-  PiAgentMessage,
   PiModel,
   PiPromptAck,
   PiRpcSlashCommand,
@@ -55,7 +55,7 @@ export interface PiRuntimeSession {
   setAutoCompaction(enabled: boolean): Promise<void>;
   abort(): Promise<void>;
   getState(): Promise<PiSessionState>;
-  getMessages(): Promise<PiAgentMessage[]>;
+  getHistory(): Promise<PiTranscript>;
   getAvailableModels(timeoutMs?: number | null): Promise<PiModel[]>;
   setModel(provider: string, modelId: string): Promise<PiModel>;
   setThinkingLevel(level: string): Promise<void>;
diff --git a/packages/server/src/server/agent/providers/pi/session-descriptor.test.ts b/packages/server/src/server/agent/providers/pi/session-descriptor.test.ts
index 280b558739..c6b0df5dbf 100644
--- a/packages/server/src/server/agent/providers/pi/session-descriptor.test.ts
+++ b/packages/server/src/server/agent/providers/pi/session-descriptor.test.ts
@@ -1,9 +1,13 @@
-import { mkdtemp, mkdir, utimes, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, rm, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { expect, test } from "vitest";
+import { expect, onTestFinished, test } from "vitest";
 
-import { listPiImportableSessions, readPiImportSessionConfig } from "./session-descriptor.js";
+import {
+  copyPiSessionFileWithCwd,
+  listPiImportableSessions,
+  readPiImportSessionConfig,
+} from "./session-descriptor.js";
 
 async function writeSession(root: string, lines: unknown[]): Promise<string> {
   const sessionsDir = path.join(root, "sessions", "project");
@@ -216,3 +220,97 @@ test("Pi import config preserves thinking before a later model in large sessions
     thinkingOptionId: "low",
   });
 });
+
+test("a Pi session copy names the new cwd in its header and keeps every later byte", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-pi-session-copy-"));
+  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  const header = {
+    type: "session",
+    version: 3,
+    id: "pi-session-1",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    cwd: path.join(root, "removed-worktree"),
+  };
+  const body = Buffer.from(
+    Array.from(
+      { length: 2_000 },
+      (_, index) =>
+        `${JSON.stringify({ type: "message", id: `entry-${index}`, message: { role: "user", content: `café ☕ ${index}` } })}\n`,
+    ).join(""),
+  );
+  expect(body.length).toBeGreaterThan(64 * 1024);
+  const sourceFile = path.join(root, "source.jsonl");
+  const targetFile = path.join(root, "copy.jsonl");
+  await writeFile(sourceFile, Buffer.concat([Buffer.from(`${JSON.stringify(header)}\n`), body]));
+
+  await copyPiSessionFileWithCwd({ sourceFile, targetFile, cwd: "/home/user" });
+
+  const copy = await readFile(targetFile);
+  const headerEnd = copy.indexOf(0x0a);
+  expect(JSON.parse(copy.subarray(0, headerEnd).toString("utf8"))).toEqual({
+    ...header,
+    cwd: "/home/user",
+  });
+  expect(copy.subarray(headerEnd + 1).equals(body)).toBe(true);
+});
+
+test("a Pi session copy refuses a file without a session header", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-pi-session-copy-"));
+  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  const sourceFile = path.join(root, "source.jsonl");
+  await writeFile(sourceFile, `${JSON.stringify({ type: "message", id: "entry-1" })}\n`);
+
+  await expect(
+    copyPiSessionFileWithCwd({ sourceFile, targetFile: path.join(root, "copy.jsonl"), cwd: "/" }),
+  ).rejects.toThrow(`Pi session file has no session header: ${sourceFile}`);
+});
+
+const COPY_BODY = [
+  { type: "message", id: "entry-1", message: { role: "user", content: "café ☕" } },
+  { type: "message", id: "entry-2", message: { role: "assistant", content: "Dans la cuisine." } },
+]
+  .map((entry) => `${JSON.stringify(entry)}\n`)
+  .join("");
+
+const COPY_HEADER = {
+  type: "session",
+  version: 3,
+  id: "pi-session-1",
+  timestamp: "2026-01-01T00:00:00.000Z",
+  cwd: "/removed-worktree",
+};
+
+async function copySessionContent(content: string): Promise<Buffer> {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-pi-session-copy-"));
+  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  const sourceFile = path.join(root, "source.jsonl");
+  const targetFile = path.join(root, "copy.jsonl");
+  await writeFile(sourceFile, content);
+  await copyPiSessionFileWithCwd({ sourceFile, targetFile, cwd: "/home/user" });
+  return readFile(targetFile);
+}
+
+test.each([
+  ["a header line longer than 64 KiB", "", { ...COPY_HEADER, padding: "x".repeat(70 * 1024) }],
+  ["a header with an empty cwd", "", { ...COPY_HEADER, cwd: "" }],
+  ["blank lines before the header", "\n\r\n", COPY_HEADER],
+])("a Pi session copy accepts %s", async (_headerShape, prefix, header) => {
+  const copy = await copySessionContent(`${prefix}${JSON.stringify(header)}\n${COPY_BODY}`);
+
+  const headerEnd = copy.indexOf(0x0a);
+  expect(JSON.parse(copy.subarray(0, headerEnd).toString("utf8"))).toEqual({
+    ...header,
+    cwd: "/home/user",
+  });
+  expect(copy.subarray(headerEnd + 1).equals(Buffer.from(COPY_BODY))).toBe(true);
+});
+
+test("a Pi session copy reports a missing session file", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-pi-session-copy-"));
+  onTestFinished(() => rm(root, { recursive: true, force: true }));
+  const sourceFile = path.join(root, "missing.jsonl");
+
+  await expect(
+    copyPiSessionFileWithCwd({ sourceFile, targetFile: path.join(root, "copy.jsonl"), cwd: "/" }),
+  ).rejects.toThrow(`Pi session file is missing: ${sourceFile}`);
+});
diff --git a/packages/server/src/server/agent/providers/pi/session-descriptor.ts b/packages/server/src/server/agent/providers/pi/session-descriptor.ts
index 01f55bc0ce..6c0cc300f2 100644
--- a/packages/server/src/server/agent/providers/pi/session-descriptor.ts
+++ b/packages/server/src/server/agent/providers/pi/session-descriptor.ts
@@ -1,7 +1,8 @@
-import type { Dirent } from "node:fs";
-import { open, readdir, readFile, stat } from "node:fs/promises";
+import { createReadStream, createWriteStream, type Dirent } from "node:fs";
+import { open, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { pipeline } from "node:stream/promises";
 
 import type {
   ImportableProviderSession,
@@ -18,6 +19,7 @@ const PI_SESSION_DIR_ENV = "PI_CODING_AGENT_SESSION_DIR";
 const HEAD_BYTES = 64 * 1024;
 const TAIL_BYTES = 256 * 1024;
 const FULL_SCAN_LINE_LIMIT = 2_000;
+const PI_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;
 // Rank all discovered files cheaply, then parse only a bounded recent window.
 const IMPORT_CANDIDATE_OVERSCAN = 40;
 const IMPORT_CANDIDATE_MIN = 400;
@@ -100,6 +102,59 @@ export async function listPiImportableSessions(
   );
 }
 
+export async function copyPiSessionFileWithCwd(input: {
+  sourceFile: string;
+  targetFile: string;
+  cwd: string;
+}): Promise<void> {
+  const found = findSessionHeaderLine(
+    await readSessionFileStart(input.sourceFile, PI_SESSION_HEADER_SCAN_BYTES),
+  );
+  if (!found) {
+    throw new Error(`Pi session file has no session header: ${input.sourceFile}`);
+  }
+  await writeFile(input.targetFile, `${JSON.stringify({ ...found.header, cwd: input.cwd })}\n`, {
+    mode: 0o600,
+  });
+  await pipeline(
+    createReadStream(input.sourceFile, { start: found.bodyStart }),
+    createWriteStream(input.targetFile, { flags: "a" }),
+  );
+}
+
+function findSessionHeaderLine(
+  scanned: Buffer,
+): { header: Record<string, unknown>; bodyStart: number } | null {
+  let lineStart = 0;
+  while (lineStart < scanned.length) {
+    const newline = scanned.indexOf(0x0a, lineStart);
+    const bodyStart = newline === -1 ? scanned.length : newline + 1;
+    const line = scanned.subarray(lineStart, bodyStart).toString("utf8").trim();
+    if (line) {
+      const header = parseJsonRecord(line);
+      return header?.type === "session" ? { header, bodyStart } : null;
+    }
+    lineStart = bodyStart;
+  }
+  return null;
+}
+
+async function readSessionFileStart(filePath: string, maxBytes: number): Promise<Buffer> {
+  const handle = await open(filePath, "r").catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Pi session file is missing: ${filePath}`);
+    }
+    throw error;
+  });
+  try {
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+}
+
 export async function readPiImportSessionConfig(filePath: string): Promise<PiImportSessionConfig> {
   const descriptor = await readPiSessionDescriptor(filePath);
   if (!descriptor) return {};
diff --git a/packages/server/src/server/agent/providers/pi/test-utils/fake-pi.ts b/packages/server/src/server/agent/providers/pi/test-utils/fake-pi.ts
index 983b86c19d..770f24625c 100644
--- a/packages/server/src/server/agent/providers/pi/test-utils/fake-pi.ts
+++ b/packages/server/src/server/agent/providers/pi/test-utils/fake-pi.ts
@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import type {
   PiRuntime,
   PiRuntimeLaunch,
@@ -75,6 +77,12 @@ export class FakePi implements PiRuntime {
     const session = new FakePiSession(launch, this.removedModels);
     session.commands = this.queuedCommands.shift() ?? [];
     this.queuedSessionSetups.shift()?.(session);
+    const missingSessionCwd = launch.noSession ? null : readMissingSessionCwd(launch.session);
+    if (missingSessionCwd !== null) {
+      session.getStateError = new Error(
+        `Pi RPC process exited with code 1 and signal null\nStored session working directory does not exist: ${missingSessionCwd}\nSession file: ${launch.session}\nCurrent working directory: ${launch.cwd}`,
+      );
+    }
     this.sessions.push(session);
     return session;
   }
@@ -101,6 +109,27 @@ export class FakePi implements PiRuntime {
   }
 }
 
+function readMissingSessionCwd(sessionFile: string | undefined): string | null {
+  if (!sessionFile || !existsSync(sessionFile)) {
+    return null;
+  }
+  const [headerLine = ""] = readFileSync(sessionFile, "utf8").split("\n", 1);
+  let header: unknown;
+  try {
+    header = JSON.parse(headerLine);
+  } catch {
+    return null;
+  }
+  if (typeof header !== "object" || header === null || !("cwd" in header)) {
+    return null;
+  }
+  const { type, cwd } = header as { type?: unknown; cwd?: unknown };
+  if (type !== "session" || typeof cwd !== "string" || !cwd || existsSync(cwd)) {
+    return null;
+  }
+  return cwd;
+}
+
 export class FakePiSession implements PiRuntimeSession {
   readonly environment: Record<string, string>;
   readonly prompts: Array<{ message: string; imageCount: number }> = [];
@@ -121,9 +150,10 @@ export class FakePiSession implements PiRuntimeSession {
   readonly rawFrames: Array<object & { type: string }> = [];
   // Every user entry in the session file, including rewound and compacted ones.
   treeUserEntries: FakePiUserEntry[] = [];
-  // The user entries on the current branch that getMessages() replays.
-  contextUserEntries: FakePiUserEntry[] = [];
+  // Native user entries paired with the complete active-branch history.
+  historyUserEntries: FakePiUserEntry[] = [];
   abortRequested = false;
+  closeCalls = 0;
   readonly canceledExtensionUiRequests: string[] = [];
   readonly extensionUiResponses: Array<{
     id: string;
@@ -132,6 +162,7 @@ export class FakePiSession implements PiRuntimeSession {
   setModelResult: PiModel | null = null;
   models: PiModel[] = [];
   messages: PiAgentMessage[] = [];
+  getHistoryError: Error | null = null;
   stats: PiSessionStats = {
     tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
     cost: 0,
@@ -273,8 +304,9 @@ export class FakePiSession implements PiRuntimeSession {
     return this.state;
   }
 
-  async getMessages(): Promise<PiAgentMessage[]> {
-    return this.messages;
+  async getHistory() {
+    if (this.getHistoryError) throw this.getHistoryError;
+    return { messages: this.messages, userEntries: this.historyUserEntries };
   }
 
   async getAvailableModels(_timeoutMs?: number | null): Promise<PiModel[]> {
@@ -393,7 +425,9 @@ export class FakePiSession implements PiRuntimeSession {
     this.respondToExtensionUiRequest(id, { cancelled: true });
   }
 
-  async close(): Promise<void> {}
+  async close(): Promise<void> {
+    this.closeCalls += 1;
+  }
 
   emit(event: PiRuntimeEvent): void {
     for (const subscriber of this.subscribers) {
@@ -479,7 +513,6 @@ export class FakePiSession implements PiRuntimeSession {
         reason,
         requestId,
         treeEntries: this.treeUserEntries,
-        contextEntries: this.contextUserEntries,
       })}`,
     });
   }
diff --git a/packages/server/src/server/agent/providers/pi/transcript.ts b/packages/server/src/server/agent/providers/pi/transcript.ts
new file mode 100644
index 0000000000..b4ead7bc5c
--- /dev/null
+++ b/packages/server/src/server/agent/providers/pi/transcript.ts
@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { getUserMessageText, type PiCapturedUserMessageEntry } from "./history-mapper.js";
+import type { PiAgentMessage } from "./rpc-types.js";
+
+export interface PiTranscript {
+  messages: PiAgentMessage[];
+  userEntries: PiCapturedUserMessageEntry[];
+}
+
+const text = z.object({ type: z.literal("text"), text: z.string() }).passthrough();
+const image = z
+  .object({ type: z.literal("image"), data: z.string(), mimeType: z.string() })
+  .passthrough();
+const content = z.union([z.string(), z.array(z.union([text, image]))]);
+const message = z.discriminatedUnion("role", [
+  z
+    .object({ role: z.literal("system"), content: z.union([z.string(), z.array(text)]).nullish() })
+    .passthrough(),
+  z.object({ role: z.literal("branchSummary"), summary: z.string() }).passthrough(),
+  z.object({ role: z.literal("compactionSummary"), summary: z.string() }).passthrough(),
+  z.object({ role: z.literal("user"), content }).passthrough(),
+  z
+    .object({
+      role: z.literal("custom"),
+      content,
+      customType: z.string().optional(),
+      display: z.boolean().optional(),
+      details: z.unknown().optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      role: z.literal("assistant"),
+      content: z.array(
+        z.union([
+          text,
+          z.object({ type: z.literal("thinking"), thinking: z.string() }).passthrough(),
+          z
+            .object({
+              type: z.literal("toolCall"),
+              id: z.string(),
+              name: z.string(),
+              arguments: z.unknown(),
+            })
+            .passthrough(),
+        ]),
+      ),
+    })
+    .passthrough(),
+  z
+    .object({
+      role: z.literal("toolResult"),
+      toolCallId: z.string(),
+      toolName: z.string(),
+      content: z.unknown(),
+      isError: z.boolean().optional(),
+      details: z.unknown().optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      role: z.literal("bashExecution"),
+      command: z.string(),
+      output: z.string().optional(),
+      exitCode: z.number().nullable().optional(),
+      cancelled: z.boolean().optional(),
+      timestamp: z.number(),
+    })
+    .passthrough(),
+]);
+const record = z
+  .object({
+    type: z.string(),
+    id: z.string().optional(),
+    parentId: z.string().nullable().optional(),
+    message: z.unknown().optional(),
+  })
+  .passthrough();
+
+/** Select the persisted active ancestry, retaining structural links across compaction. */
+export function readPiTranscript(contents: string): PiTranscript {
+  const records = contents
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => record.parse(JSON.parse(line)));
+  const header = records.shift();
+  if (header?.type !== "session") throw new Error("Pi transcript is missing its session header");
+  const legacy = header.version === 1;
+  const branch = legacy ? records : activeBranch(records);
+  const result: PiTranscript = { messages: [], userEntries: [] };
+  for (const entry of branch) {
+    if (entry.type !== "message" && entry.type !== "custom_message") continue;
+    const parsed = message.parse(
+      entry.type === "custom_message" ? { ...entry, role: "custom" } : entry.message,
+    );
+    // These native context messages had no display mapping in get_messages replay.
+    if (
+      parsed.role === "system" ||
+      parsed.role === "branchSummary" ||
+      parsed.role === "compactionSummary"
+    )
+      continue;
+    result.messages.push(parsed);
+    if (parsed.role === "user" && entry.id)
+      result.userEntries.push({
+        id: entry.id,
+        text: getUserMessageText(parsed.content),
+      });
+  }
+  return result;
+}
+
+function activeBranch(records: z.infer<typeof record>[]): z.infer<typeof record>[] {
+  const byId = new Map<string, (typeof records)[number]>();
+  for (const entry of records) {
+    if (!entry.id || entry.parentId === undefined || byId.has(entry.id))
+      throw new Error("Invalid Pi transcript tree entry");
+    byId.set(entry.id, entry);
+  }
+  const branch: z.infer<typeof record>[] = [];
+  const seen = new Set<string>();
+  let entry = records.at(-1);
+  while (entry) {
+    const id = entry.id!;
+    if (seen.has(id)) throw new Error("Cycle in Pi transcript ancestry");
+    seen.add(id);
+    branch.push(entry);
+    if (entry.parentId === null) break;
+    entry = byId.get(entry.parentId!);
+    if (!entry) throw new Error("Missing Pi transcript ancestor");
+  }
+  branch.reverse();
+  return branch;
+}
diff --git a/packages/server/src/server/agent/providers/provider-availability.test.ts b/packages/server/src/server/agent/providers/provider-availability.test.ts
index baf0cf7f9b..419b5f1cf6 100644
--- a/packages/server/src/server/agent/providers/provider-availability.test.ts
+++ b/packages/server/src/server/agent/providers/provider-availability.test.ts
@@ -48,7 +48,8 @@ afterEach(() => {
   process.env.PATH = originalEnv.PATH;
   process.env.PATHEXT = originalEnv.PATHEXT;
   for (const dir of tempDirs.splice(0)) {
-    rmSync(dir, { recursive: true, force: true });
+    // Windows can briefly retain a lock on the copied executable after its probe exits.
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
   }
 });
 
diff --git a/packages/server/src/server/agent/providers/resume-process-cwd.ts b/packages/server/src/server/agent/providers/resume-process-cwd.ts
new file mode 100644
index 0000000000..d32637a9a6
--- /dev/null
+++ b/packages/server/src/server/agent/providers/resume-process-cwd.ts
@@ -0,0 +1,26 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+
+import type { AgentResumePurpose } from "../agent-sdk-types.js";
+
+export async function resolveResumeProcessCwd(
+  cwd: string,
+  purpose: AgentResumePurpose | undefined,
+): Promise<string> {
+  if (purpose !== "history" || (await isDirectory(cwd))) {
+    return cwd;
+  }
+  return homedir();
+}
+
+async function isDirectory(target: string): Promise<boolean> {
+  try {
+    return (await stat(target)).isDirectory();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return false;
+    }
+    throw error;
+  }
+}
diff --git a/packages/server/src/server/agent/providers/test-utils/fake-acp-agent.mjs b/packages/server/src/server/agent/providers/test-utils/fake-acp-agent.mjs
new file mode 100644
index 0000000000..e284a326da
--- /dev/null
+++ b/packages/server/src/server/agent/providers/test-utils/fake-acp-agent.mjs
@@ -0,0 +1,60 @@
+// A stdio ACP agent for tests. argv[2] is a JSON scenario:
+//   options: the session's config options
+//   answers: { [configId]: value } the agent ends up with instead of the requested value
+//   onWrite: "notify-first" sends config_option_update before answering the write;
+//            "notify-then-reject" does the same and then fails the write
+//   moves:   { [configId]: { [id]: value } } writes that also move another select, announced
+//            by a config_option_update after the write is answered
+//   adds:    { [configId]: option[] } writes that make more selects appear, announced the same way
+import { Readable, Writable } from "node:stream";
+import { AgentSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
+
+const scenario = JSON.parse(process.argv[2] ?? "{}");
+let options = scenario.options ?? [];
+
+function set(id, value) {
+  options = options.map((option) =>
+    option.id === id ? { ...option, currentValue: value } : option,
+  );
+}
+
+const stream = ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+export const connection = new AgentSideConnection(
+  (agentConnection) => ({
+    async initialize() {
+      return { protocolVersion: 1, agentCapabilities: {} };
+    },
+    async newSession() {
+      return { sessionId: "session-1", modes: null, models: null, configOptions: options };
+    },
+    async setSessionConfigOption({ sessionId, configId, value }) {
+      set(configId, scenario.answers?.[configId] ?? value);
+      const announce = () =>
+        agentConnection.sessionUpdate({
+          sessionId,
+          update: { sessionUpdate: "config_option_update", configOptions: options },
+        });
+      if (scenario.onWrite === "notify-first" || scenario.onWrite === "notify-then-reject") {
+        await announce();
+        if (scenario.onWrite === "notify-then-reject") throw new Error("write refused");
+        return { configOptions: options };
+      }
+      const moves = scenario.moves?.[configId];
+      const adds = scenario.adds?.[configId];
+      if (moves || adds) {
+        for (const [id, moved] of Object.entries(moves ?? {})) set(id, moved);
+        options = [...options, ...(adds ?? [])];
+        setTimeout(() => void announce(), 20);
+      }
+      return { configOptions: options };
+    },
+    async authenticate() {
+      return {};
+    },
+    async prompt() {
+      return { stopReason: "end_turn" };
+    },
+    async cancel() {},
+  }),
+  stream,
+);
diff --git a/packages/server/src/server/agent/providers/tool-call-detail-primitives.ts b/packages/server/src/server/agent/providers/tool-call-detail-primitives.ts
index 6d31961cb5..a2c49d2f27 100644
--- a/packages/server/src/server/agent/providers/tool-call-detail-primitives.ts
+++ b/packages/server/src/server/agent/providers/tool-call-detail-primitives.ts
@@ -12,6 +12,13 @@ import {
 export const CommandValueSchema = z.union([z.string(), z.array(z.string())]);
 
 type ToolDetailSchema = z.ZodType;
+
+// Neither arguments nor output have arrived: the detail keeps its kind with empty fields,
+// which clients render as loading until the arguments fill it in.
+function isAwaitingArguments(input: unknown, output: unknown): boolean {
+  return input === null && (output === null || output === undefined);
+}
+
 // Zod 4 loses the generic output type when these branch helpers constrain
 // schemas through z.ZodType, so the paired shape/value interfaces preserve the
 // transform callback types without changing runtime parsing.
@@ -701,7 +708,7 @@ export const ToolGrepOutputSchema = z
 export const ToolWebFetchInputSchema = z
   .object({
     url: z.string(),
-    prompt: z.string(),
+    prompt: z.string().optional(),
   })
   .passthrough();
 
@@ -812,7 +819,7 @@ export function toShellToolDetail(
 ): ToolCallDetail | undefined {
   const command = input?.command ?? output?.command;
   if (!command) {
-    return undefined;
+    return isAwaitingArguments(input, output) ? { type: "shell", command: "" } : undefined;
   }
 
   return {
@@ -831,7 +838,7 @@ export function toReadToolDetail(
 ): ToolCallDetail | undefined {
   const filePath = normalizeDetailPath(input?.filePath ?? output?.filePath, options?.normalizePath);
   if (!filePath) {
-    return undefined;
+    return isAwaitingArguments(input, output) ? { type: "read", filePath: "" } : undefined;
   }
 
   const stripped = output?.content ? stripReadLineNumberGutter(output.content) : undefined;
@@ -854,7 +861,7 @@ export function toWriteToolDetail(
 ): ToolCallDetail | undefined {
   const filePath = normalizeDetailPath(input?.filePath ?? output?.filePath, options?.normalizePath);
   if (!filePath) {
-    return undefined;
+    return isAwaitingArguments(input, output) ? { type: "write", filePath: "" } : undefined;
   }
 
   const content = input?.content ?? output?.content;
@@ -872,7 +879,7 @@ export function toEditToolDetail(
 ): ToolCallDetail | undefined {
   const filePath = normalizeDetailPath(input?.filePath ?? output?.filePath, options?.normalizePath);
   if (!filePath) {
-    return undefined;
+    return isAwaitingArguments(input, output) ? { type: "edit", filePath: "" } : undefined;
   }
 
   const newString = input?.newString ?? output?.newString;
@@ -941,7 +948,9 @@ export function toSearchToolDetail(params: {
 }): ToolCallDetail | undefined {
   const { input, output, toolName } = params;
   if (!input?.query) {
-    return undefined;
+    return isAwaitingArguments(input, output)
+      ? { type: "search", query: "", ...(toolName ? { toolName } : {}) }
+      : undefined;
   }
 
   return {
@@ -958,7 +967,7 @@ export function toFetchToolDetail(
 ): ToolCallDetail | undefined {
   const url = input?.url ?? output?.url;
   if (!url) {
-    return undefined;
+    return isAwaitingArguments(input, output) ? { type: "fetch", url: "" } : undefined;
   }
 
   return {
@@ -1050,3 +1059,28 @@ export function toolDetailBranchByNameWithCwd<
     return mapper(parsedValue.input, parsedValue.output, parsedValue.cwd ?? null);
   });
 }
+
+interface ToolDetailEnvelope {
+  input: unknown;
+  output: unknown;
+}
+
+// A tool call streams before its arguments are complete: Claude's tool_use block opens with
+// `input: {}` and fills in field by field, in whatever order the model writes them, and
+// OpenCode's pending part carries `input: {}`. Until the call has output, arguments that do not
+// yet satisfy the tool's schema are parsed as absent, so a known tool keeps its canonical detail
+// kind (and its title and icon) from its first state.
+export function parseKnownToolDetail<Envelope extends ToolDetailEnvelope>(
+  branches: z.ZodType<ToolCallDetail | null | undefined>,
+  envelope: Envelope,
+): ToolCallDetail | undefined {
+  const parsed = branches.safeParse(envelope);
+  if (parsed.success && parsed.data) {
+    return parsed.data;
+  }
+  if (envelope.input === null || (envelope.output !== null && envelope.output !== undefined)) {
+    return undefined;
+  }
+  const awaiting = branches.safeParse({ ...envelope, input: null });
+  return awaiting.success && awaiting.data ? awaiting.data : undefined;
+}
diff --git a/packages/server/src/server/agent/providers/tool-call-mapper-utils.ts b/packages/server/src/server/agent/providers/tool-call-mapper-utils.ts
index cd0e4776b7..704e2b5d32 100644
--- a/packages/server/src/server/agent/providers/tool-call-mapper-utils.ts
+++ b/packages/server/src/server/agent/providers/tool-call-mapper-utils.ts
@@ -224,9 +224,11 @@ export function stripReadLineNumberGutter(
   return { content: stripped.join("\n"), startLine };
 }
 
+export const TOOL_CALL_DIFF_MAX_CHARS = 12_000;
+
 export function truncateDiffText(
   text: string | undefined,
-  maxChars: number = 12_000,
+  maxChars: number = TOOL_CALL_DIFF_MAX_CHARS,
 ): string | undefined {
   if (typeof text !== "string") {
     return undefined;
diff --git a/packages/server/src/server/agent/restart-recovery/index.test.ts b/packages/server/src/server/agent/restart-recovery/index.test.ts
index 0b1658b47d..77adf359c4 100644
--- a/packages/server/src/server/agent/restart-recovery/index.test.ts
+++ b/packages/server/src/server/agent/restart-recovery/index.test.ts
@@ -98,7 +98,7 @@ test("opt-out consumes pending recovery and excludes archived, private, owned an
     enabled = true;
     recovery.resumePending();
     expect(dispatched).toEqual([]);
-    expect((await storage.list()).every((record) => !record.resumeOnStartup)).toBe(true);
+    expect((await storage.listAll()).every((record) => !record.resumeOnStartup)).toBe(true);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
diff --git a/packages/server/src/server/agent/restart-recovery/index.ts b/packages/server/src/server/agent/restart-recovery/index.ts
index dc4e7d90c7..fe558b0219 100644
--- a/packages/server/src/server/agent/restart-recovery/index.ts
+++ b/packages/server/src/server/agent/restart-recovery/index.ts
@@ -21,7 +21,8 @@ export function createRestartRecovery(deps: Dependencies) {
   return {
     /** Choose candidates before anything else reads or repairs persisted running status. */
     async prepareStartup() {
-      for (const record of await deps.storage.list()) {
+      // Startup recovery repairs persisted running status once before agents are restored.
+      for (const record of await deps.storage.listAll()) {
         const pending =
           deps.settings().enabled &&
           (record.resumeOnStartup === true || record.lastStatus === "running") &&
@@ -45,7 +46,8 @@ export function createRestartRecovery(deps: Dependencies) {
     },
     async captureRunningAgents() {
       await deps.storage.flush();
-      for (const record of await deps.storage.list()) {
+      // Shutdown recovery captures running state once before the daemon exits.
+      for (const record of await deps.storage.listAll()) {
         if (record.lastStatus === "running" && (await eligible(record)))
           await deps.storage.upsert({ ...record, resumeOnStartup: deps.settings().enabled });
       }
diff --git a/packages/server/src/server/agent/rewind/rewind.test.ts b/packages/server/src/server/agent/rewind/rewind.test.ts
index 8e31a2c40b..1bea50d9cf 100644
--- a/packages/server/src/server/agent/rewind/rewind.test.ts
+++ b/packages/server/src/server/agent/rewind/rewind.test.ts
@@ -720,7 +720,7 @@ describe("AgentManager rewind run ownership", () => {
     });
   });
 
-  test("blocks new prompts until the rewind settles", async () => {
+  test("blocks new prompts immediately and until the rewind settles", async () => {
     let release!: () => void;
     const gate = new Promise<void>((resolve) => {
       release = resolve;
diff --git a/packages/server/src/server/agent/tools/paseo-tools.ts b/packages/server/src/server/agent/tools/paseo-tools.ts
index e306f93a43..aae31229d7 100644
--- a/packages/server/src/server/agent/tools/paseo-tools.ts
+++ b/packages/server/src/server/agent/tools/paseo-tools.ts
@@ -18,6 +18,7 @@ import type { AgentMode, AgentProvider, AgentSessionConfig } from "../agent-sdk-
 import type { AgentManager } from "../agent-manager.js";
 import { ActiveTurnBehaviorSchema, AgentProfileSchema } from "@getpaseo/protocol/messages";
 import type { DaemonConfigStore } from "../../daemon-config-store.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
 import {
   AgentFeatureSchema,
   AgentPermissionRequestPayloadSchema,
@@ -42,6 +43,7 @@ import {
   type ArchiveDependencies,
 } from "../../workspace-archive-service.js";
 import { createAgentCommand } from "../create-agent/create.js";
+import { inheritWorkspaceBackground } from "../create-agent/intent.js";
 import type { VoiceCallerContext, VoiceSpeakHandler } from "../../voice-types.js";
 import type { FirstAgentContext } from "../../messages.js";
 import { everyMsToFiveFieldCron } from "@getpaseo/protocol/schedule/cadence";
@@ -137,7 +139,7 @@ export interface PaseoToolHostDependencies {
   listActiveWorkspaces?: ArchiveDependencies["listActiveWorkspaces"];
   archiveWorkspaceRecord?: ArchiveDependencies["archiveWorkspaceRecord"];
   emitWorkspaceUpdatesForWorkspaceIds?: ArchiveDependencies["emitWorkspaceUpdatesForWorkspaceIds"];
-  workspaceRegistry?: Pick<WorkspaceRegistry, "get" | "list" | "upsert">;
+  workspaceRegistry?: Pick<WorkspaceRegistry, "get" | "listActive" | "upsert">;
   projectRegistry?: Pick<ProjectRegistry, "get" | "list">;
   createDirectoryWorkspace?: (
     cwd: string,
@@ -153,7 +155,7 @@ export interface PaseoToolHostDependencies {
   ensureWorkspaceForCreate?: (
     cwd: string,
     firstAgentContext?: FirstAgentContext,
-    context?: { callerWorkspaceId?: string },
+    context?: { background?: boolean; callerWorkspaceId?: string },
   ) => Promise<string>;
   browserToolsEnabled?: boolean;
   browserToolsBroker?: BrowserToolsBroker | null;
@@ -187,6 +189,7 @@ interface ProviderSummary {
 }
 
 const WorkspaceAutomationSummarySchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -205,6 +208,7 @@ function toWorkspaceAutomationSummary(workspace: PersistedWorkspaceRecord) {
     kind: workspace.kind,
     title: workspace.title,
     background: workspace.background,
+    parentWorkspaceId: workspace.parentWorkspaceId,
   };
 }
 
@@ -718,6 +722,7 @@ function createToolCatalog(
   const hostResolver = createHostResolver({
     serverId: options.serverId ?? "self",
     callerAgentId,
+    caller: () => resolveCallerAgent(),
     lockedCwd: callerContext?.lockedCwd,
     hosts: () => {
       if (!options.hosts) throw new Error("Connected hosts are not configured");
@@ -860,6 +865,14 @@ function createToolCatalog(
     return parentAgent;
   };
 
+  const workspaceBackgroundIntent = (background: boolean | undefined) => {
+    const caller = resolveCallerAgent();
+    return {
+      background: inheritWorkspaceBackground(background, caller),
+      callerWorkspaceId: caller?.workspaceId,
+    };
+  };
+
   const resolveInheritedProviderConfig = (
     selectedProvider: string,
   ): Pick<AgentSessionConfig, "providerOptions"> | undefined => {
@@ -939,9 +952,6 @@ function createToolCatalog(
       ...(callerAgent.provider === resolvedProvider && callerAgent.config.providerOptions
         ? { providerOptions: callerAgent.config.providerOptions }
         : {}),
-      ...(callerAgent.config.featureValues
-        ? { featureValues: callerAgent.config.featureValues }
-        : {}),
       ...(callerAgent.config.systemPrompt ? { systemPrompt: callerAgent.config.systemPrompt } : {}),
       ...(callerAgent.config.mcpServers ? { mcpServers: callerAgent.config.mcpServers } : {}),
     };
@@ -1191,6 +1201,12 @@ function createToolCatalog(
       .trim()
       .min(1, "initialPrompt is required")
       .describe("Required first task to run immediately after creation."),
+    background: z
+      .boolean()
+      .optional()
+      .describe(
+        "True creates a background agent: hidden from tabs, default lists, your subagent track and notifications. You still get its finish notification and can address it by id. Omit to inherit your own value (false without a caller); use it for helpers the user does not need to watch.",
+      ),
   };
   const legacyCreateAgentPlacementFields = {
     relationship: AgentRelationshipInputSchema.describe(
@@ -1397,7 +1413,7 @@ function createToolCatalog(
           .boolean()
           .optional()
           .describe(
-            "True hides the workspace from default lists and the sidebar while its contents remain durable and accessible; omit background to inherit your current workspace’s value (false without a caller), and override it only when the user explicitly asks.",
+            "True hides the workspace from default lists and the sidebar while its contents remain durable and accessible; omit background to inherit your own visibility (true when you or your current workspace are background, false without a caller), and override it only when the user explicitly asks.",
           ),
         mode: z
           .enum(["branch-off", "checkout-branch", "checkout-pr"])
@@ -1467,10 +1483,12 @@ function createToolCatalog(
         if (!options.createDirectoryWorkspace) {
           throw new Error("Workspace provisioning is not configured");
         }
-        workspace = await options.createDirectoryWorkspace(cwd, title, projectId, {
-          background,
-          callerWorkspaceId: resolveCallerAgent()?.workspaceId,
-        });
+        workspace = await options.createDirectoryWorkspace(
+          cwd,
+          title,
+          projectId,
+          workspaceBackgroundIntent(background),
+        );
       } else {
         let cwd =
           path !== undefined || !projectId ? resolveScopedCwd(path, { required: true }) : null;
@@ -1501,8 +1519,7 @@ function createToolCatalog(
             ...(worktreeSlug ? { worktreeSlug } : {}),
             ...worktreeTarget,
             ...(title ? { title } : {}),
-            background,
-            callerWorkspaceId: resolveCallerAgent()?.workspaceId,
+            ...workspaceBackgroundIntent(background),
           },
         );
         if (!result.ok) {
@@ -1530,7 +1547,7 @@ function createToolCatalog(
       if (!options.workspaceRegistry) {
         throw new Error("Workspace registry is not configured");
       }
-      const workspaces = (await options.workspaceRegistry.list())
+      const workspaces = (await options.workspaceRegistry.listActive())
         .filter(
           (workspace) => !workspace.archivedAt && (includeBackground || !workspace.background),
         )
@@ -1590,7 +1607,7 @@ function createToolCatalog(
     {
       title: "Create agent",
       description:
-        "Create an agent. Agent-scoped creation defaults to your workspace and creates your subagent. Top-level creation without workspaceId creates a new local workspace. Requires provider/model (for example codex/gpt-5.4) and an initial prompt. Do not guess; call list_providers and list_models first if uncertain.",
+        "Create an agent. Agent-scoped creation defaults to your workspace and creates your subagent. Top-level creation without workspaceId creates a new local workspace. Requires provider/model (for example codex/gpt-5.4) and an initial prompt. For a different provider, set settings.modeId from inspect_provider; omission is accepted for targets with no modes and for unattended execution supported by the target. Do not guess; call list_providers and list_models first if uncertain.",
       inputSchema: createAgentInputSchema,
       outputSchema: {
         agentId: z.string(),
@@ -1638,7 +1655,7 @@ function createToolCatalog(
           cwd: resolvedArgs.cwd,
           workspaceId: resolvedArgs.workspaceId,
           thinking: parsedArgs.settings?.thinkingOptionId,
-          features: parsedArgs.settings?.features,
+          providerOptions: parsedArgs.settings?.features,
           labels: {
             ...parsedArgs.labels,
             ...(callerAgentId && !resolvedArgs.detached && options.serverId
@@ -1648,6 +1665,7 @@ function createToolCatalog(
           mode: parsedArgs.settings?.modeId,
           promptFailure: "throw",
           notifyOnFinish,
+          background: parsedArgs.background,
           detached: resolvedArgs.detached,
           callerAgentId,
           callerContext,
@@ -1821,9 +1839,11 @@ function createToolCatalog(
       const cwd = process.cwd();
       return {
         cwd,
-        workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext, {
-          callerWorkspaceId: resolveCallerAgent()?.workspaceId,
-        }),
+        workspaceId: await options.ensureWorkspaceForCreate(
+          cwd,
+          firstAgentContext,
+          workspaceBackgroundIntent(undefined),
+        ),
       };
     }
     const caller = resolveCallerAgent();
@@ -1927,9 +1947,11 @@ function createToolCatalog(
       }
       return {
         cwd,
-        workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext, {
-          callerWorkspaceId: resolveCallerAgent()?.workspaceId,
-        }),
+        workspaceId: await options.ensureWorkspaceForCreate(
+          cwd,
+          firstAgentContext,
+          workspaceBackgroundIntent(undefined),
+        ),
       };
     }
 
@@ -2113,6 +2135,7 @@ function createToolCatalog(
       const structuredSnapshot = buildStoredAgentPayload(
         record,
         new Set(providerSnapshotManager.listRegisteredProviderIds()),
+        (provider, own) => agentManager.effectiveOptionsFor(provider, own),
       );
       return {
         content: [],
@@ -2168,6 +2191,7 @@ function createToolCatalog(
           buildStoredAgentPayload(
             record,
             new Set(providerSnapshotManager.listRegisteredProviderIds()),
+            (provider, own) => agentManager.effectiveOptionsFor(provider, own),
           ),
         isProviderVisible: () => true,
         isStoredProviderAvailable: (record) =>
@@ -2290,9 +2314,7 @@ function createToolCatalog(
         await agentManager.setAgentThinkingOption(agentId, settings.thinkingOptionId);
       }
       if (settings?.features) {
-        for (const [featureId, value] of Object.entries(settings.features)) {
-          await agentManager.setAgentFeature(agentId, featureId, value);
-        }
+        await agentManager.setAgentOptions(agentId, settings.features);
       }
 
       await updateAgentCommand({ agentManager }, { agentId, name, labels });
@@ -3070,8 +3092,8 @@ function createToolCatalog(
         "List agent profiles: named provider/model/mode bundles a human configured for specific " +
         "kinds of work. Read each profile's `notes` to pick the one that fits the task you're " +
         "delegating, then copy its `provider`, `model`, `modeId`, `thinkingOptionId`, and " +
-        "`featureValues` into create_agent (there is no `profile` parameter). Returns an empty " +
-        "list if none are configured.",
+        "`options` into create_agent as `settings.features` (there is no `profile` parameter). " +
+        "Returns an empty list if none are configured.",
       inputSchema: {},
       outputSchema: {
         profiles: z.array(AgentProfileSchema),
@@ -3124,13 +3146,13 @@ function createToolCatalog(
         throw new PaseoToolInputError(entry.error ?? `Provider '${providerId}' is unavailable`);
       }
       const selectedModel = settings?.model ?? resolvedProviderModel.model;
-      const features = await agentManager.listDraftFeatures({
+      const { controls, options: effectiveOptions } = await agentManager.listDraftControls({
         provider: providerId,
         cwd: resolvedCwd,
         ...(settings?.modeId ? { modeId: settings.modeId } : {}),
         ...(selectedModel ? { model: selectedModel } : {}),
         ...(settings?.thinkingOptionId ? { thinkingOptionId: settings.thinkingOptionId } : {}),
-        ...(settings?.features ? { featureValues: settings.features } : {}),
+        ...(settings?.features ? { providerOptions: settings.features } : {}),
       });
       return {
         content: [],
@@ -3142,7 +3164,7 @@ function createToolCatalog(
           status: summary.status,
           modes: summary.modes,
           selectedModel: selectedModel ?? null,
-          features,
+          features: featuresFromControls({ controls, options: effectiveOptions }),
         }),
       };
     },
diff --git a/packages/server/src/server/authorization/operation-permissions.ts b/packages/server/src/server/authorization/operation-permissions.ts
index 8e20279f13..f778cc0b84 100644
--- a/packages/server/src/server/authorization/operation-permissions.ts
+++ b/packages/server/src/server/authorization/operation-permissions.ts
@@ -11,6 +11,7 @@ const INBOUND_PERMISSION = {
   "hosts.update.request": "tunnel.manage",
   "hosts.remove.request": "tunnel.manage",
   "hosts.link.open.request": null,
+  "hosts.link.ack.request": null,
   "hosts.route.open.request": null,
   "hosts.route.frame.request": null,
   "hosts.route.close.request": null,
@@ -19,6 +20,8 @@ const INBOUND_PERMISSION = {
   "agent.detach.request": "workspace.write",
   "agent.fork_context.request": "workspace.read",
   "agent.provider_subagents.list.request": "workspace.read",
+  "agent.background_work.list.request": "workspace.read",
+  "agent.background_work.stop.request": ["workspace.write", "hub.execute"],
   "agent.provider_subagents.timeline.get.request": "workspace.read",
   "agent.rewind.request": "workspace.write",
   "agent.skills.get_status.request": "daemon.read",
@@ -119,6 +122,7 @@ const INBOUND_PERMISSION = {
   list_available_providers_request: "daemon.read",
   list_commands_request: "daemon.read",
   list_provider_features_request: "daemon.read",
+  "provider.controls.list.request": "daemon.read",
   list_provider_models_request: "daemon.read",
   list_provider_modes_request: "daemon.read",
   list_terminals_request: "workspace.read",
@@ -142,6 +146,7 @@ const INBOUND_PERMISSION = {
   "plugin.reload.request": "daemon.manage",
   "plugin.remove.request": "daemon.manage",
   "plugin.rpc.invoke.request": "daemon.manage",
+  "plugin.rpc.subscribe.request": "daemon.manage",
   "plugin.source.install.request": "daemon.manage",
   "plugin.source.status.request": "daemon.manage",
   "plugin.source.update.request": "daemon.manage",
@@ -153,6 +158,7 @@ const INBOUND_PERMISSION = {
   "project.icon.get.request": "workspace.read",
   "project.icon.set.request": "workspace.manage",
   "project.list.request": "workspace.read",
+  "project.suggestions.request": "workspace.read",
   "project.remove.request": "workspace.manage",
   "project.rename.request": "workspace.manage",
   project_icon_request: "workspace.read",
@@ -192,6 +198,8 @@ const INBOUND_PERMISSION = {
   stash_pop_request: "workspace.write",
   stash_save_request: "workspace.write",
   "checkout.diff.get.request": "workspace.read",
+  "diff.subscribe.request": "workspace.read",
+  "diff.unsubscribe.request": "workspace.read",
   subscribe_checkout_diff_request: "workspace.read",
   subscribe_terminal_request: "workspace.read",
   subscribe_terminals_request: "workspace.read",
@@ -213,9 +221,13 @@ const INBOUND_PERMISSION = {
   "workspace.label.delete.request": "workspace.manage",
   "workspace.label.list.request": "workspace.read",
   "workspace.label.update.request": "workspace.manage",
+  "agent.metadata.update.request": "workspace.write",
+  "workspace.metadata.update.request": "workspace.manage",
   "workspace.pin.set.request": "workspace.manage",
+  "workspace.base_branch.set.request": "workspace.write",
   "workspace.recovery.inspect.request": ["workspace.read", "hub.execute"],
   "workspace.recovery.restore.request": ["workspace.manage", "hub.execute"],
+  "workspace.archive.undo.request": ["workspace.manage", "hub.execute"],
   "workspace.script.list.request": "workspace.read",
   "workspace.script.start.request": "workspace.write",
   "workspace.script.stop.request": "workspace.write",
@@ -247,6 +259,9 @@ const OUTBOUND_PERMISSION = {
   "agent.provider_subagents.list.response": "workspace.read",
   "agent.provider_subagents.timeline.get.response": "workspace.read",
   "agent.provider_subagents.update": "workspace.read",
+  "agent.background_work.list.response": "workspace.read",
+  "agent.background_work.stop.response": ["workspace.write", "hub.execute"],
+  "agent.background_work.update": "workspace.read",
   "agent.rewind.response": "workspace.write",
   "agent.skills.get_status.response": "daemon.read",
   "agent.skills.import_legacy_selection.response": "daemon.manage",
@@ -357,6 +372,7 @@ const OUTBOUND_PERMISSION = {
   list_available_providers_response: "daemon.read",
   list_commands_response: "daemon.read",
   list_provider_features_response: "daemon.read",
+  "provider.controls.list.response": "daemon.read",
   list_provider_models_response: "daemon.read",
   list_provider_modes_response: "daemon.read",
   list_terminals_response: "workspace.read",
@@ -379,6 +395,9 @@ const OUTBOUND_PERMISSION = {
   "plugin.reload.response": "daemon.manage",
   "plugin.remove.response": "daemon.manage",
   "plugin.rpc.invoke.response": "daemon.manage",
+  "plugin.rpc.subscribe.response": "daemon.manage",
+  "plugin.rpc.event": "daemon.manage",
+  "plugin.rpc.closed": "daemon.manage",
   "plugin.source.install.response": "daemon.manage",
   "plugin.source.status.response": "daemon.manage",
   "plugin.source.update.response": "daemon.manage",
@@ -391,6 +410,7 @@ const OUTBOUND_PERMISSION = {
   "project.icon.get.response": "workspace.read",
   "project.icon.set.response": "workspace.manage",
   "project.list.response": "workspace.read",
+  "project.suggestions.response": "workspace.read",
   "project.remove.response": "workspace.manage",
   "project.rename.response": "workspace.manage",
   "project.update": "workspace.read",
@@ -431,6 +451,7 @@ const OUTBOUND_PERMISSION = {
   stash_save_response: "workspace.read",
   status: "daemon.read",
   "checkout.diff.get.response": "workspace.read",
+  "diff.subscribe.response": "workspace.read",
   subscribe_checkout_diff_response: "workspace.read",
   subscribe_terminal_response: "workspace.read",
   "terminal.rename.response": "workspace.write",
@@ -452,9 +473,13 @@ const OUTBOUND_PERMISSION = {
   "workspace.label.list.response": "workspace.read",
   "workspace.label.update": "workspace.read",
   "workspace.label.update.response": "workspace.manage",
+  "agent.metadata.update.response": "workspace.write",
+  "workspace.metadata.update.response": "workspace.manage",
   "workspace.pin.set.response": "workspace.manage",
+  "workspace.base_branch.set.response": "workspace.write",
   "workspace.recovery.inspect.response": ["workspace.read", "hub.execute"],
   "workspace.recovery.restore.response": ["workspace.manage", "hub.execute"],
+  "workspace.archive.undo.response": ["workspace.manage", "hub.execute"],
   "workspace.script.list.response": "workspace.read",
   "workspace.script.start.response": "workspace.write",
   "workspace.script.stop.response": "workspace.write",
diff --git a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.test.ts b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.test.ts
index f050237620..f30966af2f 100644
--- a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.test.ts
+++ b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.test.ts
@@ -30,6 +30,7 @@ function createPullRequest(
     state: "open",
     baseRefName: "main",
     headRefName: "feature",
+    headSha: "same-head",
     isMerged: true,
     ...overrides,
   };
@@ -46,6 +47,7 @@ function createSnapshot(overrides?: {
       repoRoot: "/tmp/repo",
       mainRepoRoot: "/tmp/repo",
       currentBranch: "feature",
+      headSha: "same-head",
       remoteUrl: "https://github.com/acme/repo.git",
       isPaseoOwnedWorktree: true,
       isDirty: false,
@@ -346,6 +348,25 @@ afterEach(() => {
 });
 
 describe("archiveIfSafe", () => {
+  test("denies archive when checkout facts do not establish safety", async () => {
+    for (const git of [{ headSha: undefined }, { behindOfOrigin: 1 }, { isDirty: null }]) {
+      const harness = createHarness({ snapshot: createSnapshot({ git }) });
+      await runArchiveIfSafe(harness);
+      expect(harness.deps.archiveByScope).not.toHaveBeenCalled();
+    }
+    const harness = createHarness({
+      snapshot: createSnapshot({ pullRequest: createPullRequest({ headSha: undefined }) }),
+    });
+    await runArchiveIfSafe(harness);
+    expect(harness.deps.archiveByScope).not.toHaveBeenCalled();
+  });
+
+  test("keeps the workspace active when the merged PR head differs from checkout", async () => {
+    const harness = createHarness({ snapshot: createSnapshot({ git: { headSha: "local-head" } }) });
+    await runArchiveIfSafe(harness);
+    expect(harness.deps.archiveByScope).not.toHaveBeenCalled();
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
   });
diff --git a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts
index be8a6f4cea..da94c5931b 100644
--- a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts
+++ b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts
@@ -59,13 +59,21 @@ export async function archiveIfSafe(input: {
   const cwd = snapshot.cwd;
   const pullRequest = snapshot.forge.pullRequest;
 
-  if (!pullRequest?.isMerged) {
+  if (
+    !pullRequest?.isMerged ||
+    !snapshot.git.headSha ||
+    snapshot.git.headSha !== pullRequest.headSha ||
+    snapshot.forge.error
+  ) {
     return;
   }
-  if (snapshot.git.isDirty === true) {
+  if (snapshot.git.isDirty !== false) {
     return;
   }
-  if (typeof snapshot.git.aheadOfOrigin === "number" && snapshot.git.aheadOfOrigin > 0) {
+  if (
+    (snapshot.git.aheadOfOrigin !== null && snapshot.git.aheadOfOrigin !== 0) ||
+    (snapshot.git.behindOfOrigin !== null && snapshot.git.behindOfOrigin !== 0)
+  ) {
     return;
   }
 
diff --git a/packages/server/src/server/auto-archive-on-merge/behavior.test.ts b/packages/server/src/server/auto-archive-on-merge/behavior.test.ts
index be952b8efa..6d24506d36 100644
--- a/packages/server/src/server/auto-archive-on-merge/behavior.test.ts
+++ b/packages/server/src/server/auto-archive-on-merge/behavior.test.ts
@@ -161,7 +161,12 @@ async function createWorkspaceJourney() {
   };
 }
 
-async function createUnobservedWorkspace(archiveBarrier?: Promise<void>) {
+async function createUnobservedWorkspace(journeyOptions?: {
+  archiveBarrier?: Promise<void>;
+  changeBeforeArchiveRead?: boolean;
+}) {
+  const { archiveBarrier, changeBeforeArchiveRead: shouldChange = false } = journeyOptions ?? {};
+  let changeBeforeArchiveRead = shouldChange;
   const { repoDir, paseoHome, worktree } = await createWorkspaceFiles();
   const cwd = worktree.worktreePath;
   run(repoDir, ["remote", "add", "origin", "https://github.com/acme/repo.git"]);
@@ -173,8 +178,10 @@ async function createUnobservedWorkspace(archiveBarrier?: Promise<void>) {
     runner: async () => ({ stdout: "", stderr: "" }),
   });
   let observation: PullRequestObservation | null = null;
+  let remoteHeadSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim();
   const reads: Array<string | undefined> = [];
   const archives: string[] = [];
+  let archiveDecisions = 0;
   let active = true;
   const service = new WorkspaceGitServiceImpl({
     logger,
@@ -186,6 +193,7 @@ async function createUnobservedWorkspace(archiveBarrier?: Promise<void>) {
         return {
           status: observation && {
             ...observation,
+            headSha: remoteHeadSha,
             title: observation.headRefName,
             baseRefName: "main",
             isMerged: observation.state === "merged",
@@ -202,15 +210,29 @@ async function createUnobservedWorkspace(archiveBarrier?: Promise<void>) {
     logger,
     paseoHome,
     daemonConfigStore: { get: () => ({ autoArchiveAfterMerge: true }) },
-    workspaceGitService: service,
+    workspaceGitService: {
+      onSnapshotUpdated: service.onSnapshotUpdated.bind(service),
+      getSnapshot: async (
+        snapshotCwd: string,
+        readOptions: { force: true; afterInFlight?: boolean; reason: string },
+      ) => {
+        if (changeBeforeArchiveRead && readOptions.reason === "auto-archive-on-merge") {
+          changeBeforeArchiveRead = false;
+          writeFileSync(path.join(cwd, "README.md"), "changed before archive\n");
+          run(cwd, ["add", "README.md"]);
+          run(cwd, ["-c", "commit.gpgsign=false", "commit", "-m", "new commit"]);
+        }
+        return service.getSnapshot(snapshotCwd, readOptions);
+      },
+    },
     getAutoArchivedChangeRequestUrl: async () => null,
     listActiveWorkspaces: async () =>
       active ? [{ workspaceId: "workspace-under-test", cwd, kind: "worktree" }] : [],
   } as unknown as AutoArchiveOnMergeOptions;
   setupAutoArchiveOnMerge(options, {
     resolvePath: path.resolve,
-    archiveIfSafe: async (input) =>
-      archiveIfSafe({
+    archiveIfSafe: async (input) => {
+      await archiveIfSafe({
         ...input,
         deps: {
           isPaseoOwnedWorktreeCwd,
@@ -227,13 +249,19 @@ async function createUnobservedWorkspace(archiveBarrier?: Promise<void>) {
             };
           },
         },
-      }),
+      });
+      archiveDecisions++;
+    },
   });
   return {
     archives,
+    archiveDecisions: () => archiveDecisions,
     reads,
     metrics: () => service.getMetrics(),
     isActive: () => active,
+    advanceRemoteHead: () => {
+      remoteHeadSha = "a".repeat(40);
+    },
     makeDirty: () => writeFileSync(path.join(cwd, "README.md"), "uncommitted work\n"),
     commitUnpushed: () => {
       writeFileSync(path.join(cwd, "README.md"), "unpushed work\n");
@@ -270,12 +298,33 @@ afterEach(async () => {
 });
 
 describe("workspace auto-archive behavior", () => {
+  test("rechecks checkout changes made after the merge notification", async () => {
+    const workspace = await createUnobservedWorkspace({ changeBeforeArchiveRead: true });
+    await workspace.observe("open");
+    await workspace.observe("merged");
+    await vi.waitFor(() => expect(workspace.archiveDecisions()).toBe(1));
+    expect(workspace.archives).toEqual([]);
+    expect(workspace.isActive()).toBe(true);
+  });
+
+  test("keeps a merged PR visible and the workspace active when its remote head advances", async () => {
+    const workspace = await createUnobservedWorkspace();
+    const open = await workspace.observe("open");
+    workspace.advanceRemoteHead();
+    const merged = await workspace.observe("merged");
+    await vi.waitFor(() => expect(workspace.archiveDecisions()).toBe(1));
+    expect(merged.forge.pullRequest?.url).toBe(open.forge.pullRequest?.url);
+    expect(merged.forge.pullRequest?.headSha).not.toBe(merged.git.headSha);
+    expect(workspace.isActive()).toBe(true);
+    expect(workspace.archives).toEqual([]);
+  });
+
   test("archives a clean owned workspace on an unobserved open-to-merged transition only once", async () => {
     let releaseArchive!: () => void;
     const archiveBarrier = new Promise<void>((resolve) => {
       releaseArchive = resolve;
     });
-    const workspace = await createUnobservedWorkspace(archiveBarrier);
+    const workspace = await createUnobservedWorkspace({ archiveBarrier });
     try {
       await workspace.observe("open");
       expect(workspace.archives).toEqual([]);
@@ -292,10 +341,10 @@ describe("workspace auto-archive behavior", () => {
 
       expect(workspace.metrics().workspaceListenerCount).toBe(0);
       expect(workspace.archives).toEqual(["workspace-under-test"]);
-      // Confirmation reads the completed snapshot cache; it does not shell out again.
       expect(workspace.reads).toEqual([
         "workspace-journey",
         "workspace-journey",
+        "auto-archive-on-merge",
         "workspace-journey",
       ]);
     } finally {
diff --git a/packages/server/src/server/auto-archive-on-merge/index.test.ts b/packages/server/src/server/auto-archive-on-merge/index.test.ts
index 885d8250e8..8956407493 100644
--- a/packages/server/src/server/auto-archive-on-merge/index.test.ts
+++ b/packages/server/src/server/auto-archive-on-merge/index.test.ts
@@ -90,6 +90,11 @@ test("fans one fresh observation out to every workspace attached to its exact cw
   await finished;
 
   expect(getSnapshot).toHaveBeenCalledTimes(1);
+  expect(getSnapshot).toHaveBeenCalledWith("/repo/worktree/.", {
+    force: true,
+    afterInFlight: true,
+    reason: "auto-archive-on-merge",
+  });
   expect(calls).toEqual([
     { workspaceId: "workspace-a", pullRequest: freshSnapshot.forge.pullRequest },
     { workspaceId: "workspace-b", pullRequest: freshSnapshot.forge.pullRequest },
diff --git a/packages/server/src/server/auto-archive-on-merge/index.ts b/packages/server/src/server/auto-archive-on-merge/index.ts
index be950bf367..5e2cc5c269 100644
--- a/packages/server/src/server/auto-archive-on-merge/index.ts
+++ b/packages/server/src/server/auto-archive-on-merge/index.ts
@@ -63,6 +63,8 @@ export function setupAutoArchiveOnMerge(
       let freshSnapshot: WorkspaceGitRuntimeSnapshot | null;
       try {
         freshSnapshot = await options.workspaceGitService.getSnapshot(snapshot.cwd, {
+          force: true,
+          afterInFlight: true,
           reason: "auto-archive-on-merge",
         });
       } catch (error) {
diff --git a/packages/server/src/server/bootstrap-provider-availability.test.ts b/packages/server/src/server/bootstrap-provider-availability.test.ts
index be431e0dc5..1a0deb5012 100644
--- a/packages/server/src/server/bootstrap-provider-availability.test.ts
+++ b/packages/server/src/server/bootstrap-provider-availability.test.ts
@@ -95,7 +95,7 @@ describe("bootstrap provider availability", () => {
 
     const daemon = await createPaseoDaemon(config, pino({ level: "silent" }));
     try {
-      await expect(daemon.agentStorage.list()).resolves.toHaveLength(1);
+      await expect(daemon.agentStorage.listAll()).resolves.toHaveLength(1);
       await expect(daemon.agentManager.listProviderAvailability()).resolves.toContainEqual({
         provider: "codex",
         available: false,
diff --git a/packages/server/src/server/bootstrap-web-ui.test.ts b/packages/server/src/server/bootstrap-web-ui.test.ts
index 81afc3c166..5669e23b6d 100644
--- a/packages/server/src/server/bootstrap-web-ui.test.ts
+++ b/packages/server/src/server/bootstrap-web-ui.test.ts
@@ -84,6 +84,23 @@ describe("daemon web UI bootstrap", () => {
     }
   });
 
+  test("returns 404 for missing metadata while serving web UI deep links", async () => {
+    const distDir = await createWebUiDist();
+    daemonHandle = await createTestPaseoDaemon({
+      mcpEnabled: true,
+      webUi: { enabled: true, distDir },
+    });
+    const origin = `http://127.0.0.1:${daemonHandle.port}`;
+    const metadata = await fetch(`${origin}/.well-known/oauth-protected-resource/mcp/agents`);
+    expect(metadata.status).toBe(404);
+    expect(metadata.headers.get("content-type")).toBe("application/json; charset=utf-8");
+    expect(await metadata.json()).toEqual({ error: "Not found" });
+
+    const deepLink = await fetch(`${origin}/h/example/agent/123`);
+    expect(deepLink.status).toBe(200);
+    expect(await deepLink.text()).toContain("<body>app</body>");
+  });
+
   test("advertises ComputerName as the hostname over HTTP and WebSocket", async () => {
     daemonHandle = await createTestPaseoDaemon({ mcpEnabled: false });
     const response = await fetch(`http://127.0.0.1:${daemonHandle.port}/api/status`);
diff --git a/packages/server/src/server/bootstrap.smoke.test.ts b/packages/server/src/server/bootstrap.smoke.test.ts
index 76fa8cc7d1..d7d41916ca 100644
--- a/packages/server/src/server/bootstrap.smoke.test.ts
+++ b/packages/server/src/server/bootstrap.smoke.test.ts
@@ -670,11 +670,11 @@ describe("paseo daemon bootstrap", () => {
 
   test("rolls back standalone listener without starting plugins when main listen fails", async () => {
     const mainPort = await findFreePort();
-    const standalonePort = await findFreePort();
     const occupiedMain = http.createServer((_req, res) => {
       res.end("occupied-main");
     });
     await new Promise<void>((resolve) => occupiedMain.listen(mainPort, "127.0.0.1", resolve));
+    const standalonePort = await findFreePort();
 
     const paseoHomeRoot = await mkdtemp(path.join(os.tmpdir(), "paseo-main-rollback-"));
     const paseoHome = path.join(paseoHomeRoot, ".paseo");
@@ -1109,6 +1109,7 @@ test("disabled recovery closes stale active records without resuming sessions",
       lastStatus: status as StoredAgentRecord["lastStatus"],
       title: `Keep ${status}`,
       labels: { "paseo.parent-agent-id": "parent", custom: "keep" },
+      metadata: {},
       persistence: { provider: "codex", sessionId: `session-${index}` },
       config: { modeId: "full-access" },
       requiresAttention: true,
@@ -1139,11 +1140,13 @@ test("disabled recovery closes stale active records without resuming sessions",
           : record.lastStatus,
     }));
     expect(
-      (await handle.daemon.agentStorage.list()).sort((a, b) => a.id.localeCompare(b.id)),
+      (await handle.daemon.agentStorage.listAll()).sort((a, b) => a.id.localeCompare(b.id)),
     ).toEqual(expected.sort((a, b) => a.id.localeCompare(b.id)));
     // A fresh reader proves the repaired states were written, rather than projected only in memory.
     expect(
-      (await new AgentStorage(storagePath, logger).list()).sort((a, b) => a.id.localeCompare(b.id)),
+      (await new AgentStorage(storagePath, logger).listAll()).sort((a, b) =>
+        a.id.localeCompare(b.id),
+      ),
     ).toEqual(expected);
     expect(handle.daemon.agentManager.listAgents()).toEqual([]);
     expect(sessionsCreated).toBe(0);
diff --git a/packages/server/src/server/bootstrap.ts b/packages/server/src/server/bootstrap.ts
index fa896ef898..59990f817f 100644
--- a/packages/server/src/server/bootstrap.ts
+++ b/packages/server/src/server/bootstrap.ts
@@ -600,7 +600,7 @@ function createInitialMutableDaemonConfig(config: ResolvedDaemonSettings): Mutab
     autoArchiveAfterMerge: config.autoArchiveAfterMerge ?? false,
     enableTerminalAgentHooks: config.enableTerminalAgentHooks ?? false,
     idleRuntimeCleanup: config.idleRuntimeCleanup !== false,
-    resumeOnStartup: config.resumeOnStartup !== false,
+    resumeOnStartup: config.resumeOnStartup === true,
     resumePrompt: config.resumePrompt ?? "Resume working.",
     appendSystemPrompt: config.appendSystemPrompt ?? "",
     pluginsEnabled: config.pluginsEnabled ?? false,
@@ -964,7 +964,7 @@ export async function createPaseoDaemon(
   workspaceRegistry.subscribeToMutations(async (mutation) => {
     if (mutation.kind === "remove" && mutation.workspace) {
       const cwd = path.resolve(mutation.workspace.cwd);
-      const workspaces = await workspaceRegistry.list();
+      const workspaces = await workspaceRegistry.listActive();
       const hasActiveWorkspace = workspaces.some(
         (workspace) => !workspace.archivedAt && path.resolve(workspace.cwd) === cwd,
       );
@@ -1047,7 +1047,7 @@ export async function createPaseoDaemon(
   const restartRecovery = createRestartRecovery({
     storage: agentStorage,
     settings: () => ({
-      enabled: daemonConfigStore.get().resumeOnStartup !== false,
+      enabled: daemonConfigStore.get().resumeOnStartup === true,
       prompt: daemonConfigStore.get().resumePrompt ?? "Resume working.",
     }),
     eligible: async (record) =>
@@ -1114,12 +1114,13 @@ export async function createPaseoDaemon(
   // external path→workspace adapter, not ownership: archive-by-path requests that
   // arrive with a worktree path and no workspaceId (old clients / CLI).
   const findWorkspaceIdForCwdExternal = async (cwd: string): Promise<string | null> => {
-    return resolveWorkspaceIdForPath(cwd, await workspaceRegistry.list());
+    // Explicit archive administration must prefer an archived exact match to an active ancestor.
+    return resolveWorkspaceIdForPath(cwd, await workspaceRegistry.listAll());
   };
   const ensureWorkspaceForCreateExternal = async (
     cwd: string,
     firstAgentContext?: FirstAgentContext,
-    context?: { callerWorkspaceId?: string },
+    context?: { background?: boolean; callerWorkspaceId?: string },
   ): Promise<string> => {
     const workspace = await workspaceProvisioning.createWorkspaceForDirectory(
       cwd,
@@ -1137,7 +1138,7 @@ export async function createPaseoDaemon(
     return workspace.workspaceId;
   };
   const listActiveWorkspacesExternal = async (): Promise<ActiveWorkspaceRef[]> => {
-    const workspaces = await workspaceRegistry.list();
+    const workspaces = await workspaceRegistry.listActive();
     return workspaces
       .filter((workspace) => !workspace.archivedAt)
       .map((workspace) => ({
@@ -1172,14 +1173,14 @@ export async function createPaseoDaemon(
   const ensureWorkspaceForCreateAndBroadcastExternal = async (
     cwd: string,
     firstAgentContext?: FirstAgentContext,
-    context?: { callerWorkspaceId?: string },
+    context?: { background?: boolean; callerWorkspaceId?: string },
   ): Promise<string> => {
     const workspaceId = await ensureWorkspaceForCreateExternal(cwd, firstAgentContext, context);
     await emitWorkspaceUpdatesExternal([workspaceId]);
     return workspaceId;
   };
   const emitWorkspaceUpdateForCwdExternal = async (cwd: string) => {
-    const workspaceIds = workspaceIdsOnCheckout(await workspaceRegistry.list(), cwd);
+    const workspaceIds = workspaceIdsOnCheckout(await workspaceRegistry.listActive(), cwd);
     await emitWorkspaceUpdatesExternal(workspaceIds);
   };
   const emitExternalSessionMessage = (message: SessionOutboundMessage) => {
@@ -1465,7 +1466,8 @@ export async function createPaseoDaemon(
   });
   logger.info({ elapsed: elapsed() }, "Schedule service initialized");
   logger.info({ elapsed: elapsed() }, "Loading persisted agent registry");
-  const persistedRecords = await agentStorage.list();
+  // Startup loads persisted agent history once before restoring the registry.
+  const persistedRecords = await agentStorage.listAll();
   logger.info(
     { elapsed: elapsed() },
     `Agent registry loaded (${persistedRecords.length} record${persistedRecords.length === 1 ? "" : "s"}); agents will initialize on demand`,
diff --git a/packages/server/src/server/checkout-diff-manager.test.ts b/packages/server/src/server/checkout-diff-manager.test.ts
index d55171831b..da2947c24d 100644
--- a/packages/server/src/server/checkout-diff-manager.test.ts
+++ b/packages/server/src/server/checkout-diff-manager.test.ts
@@ -1,488 +1,253 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import pino from "pino";
+import { expect, test } from "vitest";
+import { CheckoutDiffManager, type CheckoutDiffSnapshotPayload } from "./checkout-diff-manager.js";
 import { createWorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createFileObserver } from "./file-observer/index.js";
 
-const { toCheckoutErrorMock } = vi.hoisted(() => ({
-  toCheckoutErrorMock: vi.fn((error: unknown) => ({
-    message: error instanceof Error ? error.message : String(error),
-  })),
-}));
-
-vi.mock("./checkout-git-utils.js", () => ({
-  toCheckoutError: toCheckoutErrorMock,
-}));
-
-import type pino from "pino";
-import { CheckoutDiffManager } from "./checkout-diff-manager.js";
-import type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.js";
-
-interface Deferred<T> {
-  promise: Promise<T>;
-  resolve(value: T): void;
-}
-
-function createDeferred<T>(): Deferred<T> {
-  let resolve!: (value: T) => void;
-  const promise = new Promise<T>((resolvePromise) => {
-    resolve = resolvePromise;
-  });
-  return { promise, resolve };
-}
-
-function createWorkspaceSnapshot(
-  overrides?: Partial<WorkspaceGitRuntimeSnapshot["git"]>,
-): WorkspaceGitRuntimeSnapshot {
-  return {
-    cwd: "/tmp/repo",
-    git: {
-      isGit: true,
-      repoRoot: "/tmp/repo",
-      mainRepoRoot: null,
-      currentBranch: "feature",
-      remoteUrl: "https://github.com/acme/repo.git",
-      isPaseoOwnedWorktree: false,
-      isDirty: false,
-      baseRef: "main",
-      aheadBehind: { ahead: 1, behind: 0 },
-      aheadOfOrigin: 1,
-      behindOfOrigin: 0,
-      hasRemote: true,
-      diffStat: { additions: 1, deletions: 0 },
-      ...overrides,
-    },
-    forge: {
-      featuresEnabled: false,
-      authState: "no_remote",
-      pullRequest: null,
-      error: null,
-    },
-  };
-}
-
-function createPendingManager() {
-  const watches: Array<{
+async function withCheckout(
+  run: (input: {
     cwd: string;
-    onChange: () => void;
-    unsubscribeCalls: number;
-    resolve(): void;
-  }> = [];
-  const workspaceGitService = {
-    getCheckoutDiff: async () => ({ diff: "", structured: [] }),
-    getSnapshot: async () => createWorkspaceSnapshot(),
-
-    registerWorkspace: () => ({ unsubscribe: () => {} }),
-    requestWorkingTreeWatch: (cwd: string, onChange: () => void) => {
-      const pending = createDeferred<{ repoRoot: string | null; unsubscribe: () => void }>();
-      const watch = {
-        cwd,
-        onChange,
-        unsubscribeCalls: 0,
-        resolve: () => {
-          pending.resolve({
-            repoRoot: "/tmp/repo",
-            unsubscribe: () => {
-              watch.unsubscribeCalls += 1;
-            },
-          });
-        },
-      };
-      watches.push(watch);
-      return pending.promise;
-    },
-  };
-  const logger = { child: () => logger, warn: () => {} };
+    manager: CheckoutDiffManager;
+    git(...args: string[]): string;
+  }) => Promise<void>,
+): Promise<void> {
+  const cwd = await mkdtemp(join(tmpdir(), "legacy-diff-adapter-"));
+  const observer = createFileObserver();
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
   const manager = new CheckoutDiffManager({
+    logger: pino({ level: "silent" }),
+    paseoHome: cwd,
     workspaceRuntimeStore: createWorkspaceRuntimeStore(),
-    logger: logger as unknown as pino.Logger,
-    paseoHome: "/tmp/paseo-test",
-    workspaceGitService,
+    workspaceGitService: {
+      async requestWorkingTreeWatch(root, onChange) {
+        const subscription = await observer.subscribe(root, () => onChange(), {
+          ignore: [join(root, ".git")],
+        });
+        return {
+          repoRoot: root,
+          unsubscribe: async () => {
+            await subscription.unsubscribe();
+          },
+        };
+      },
+    },
   });
-  return { manager, watches };
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await run({ cwd, manager, git });
+  } finally {
+    await manager.dispose();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
 }
 
-describe("CheckoutDiffManager", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    toCheckoutErrorMock.mockClear();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  function createManager(options?: {
-    repoRoot?: string | null;
-    getCheckoutDiffImplementation?: ReturnType<typeof vi.fn>;
-  }) {
-    const unsubscribe = vi.fn();
-    const workspaceUnsubscribe = vi.fn();
-    let onChange: (() => void) | null = null;
-    let onWorkspaceSnapshot: ((snapshot: WorkspaceGitRuntimeSnapshot) => void) | null = null;
-    const mockRequestWorkingTreeWatch = vi.fn(async (_cwd: string, listener: () => void) => {
-      onChange = listener;
-      return {
-        repoRoot: options?.repoRoot === undefined ? "/tmp/repo" : options.repoRoot,
-        unsubscribe,
-      };
-    });
-
-    const workspaceGitService = {
-      subscribe: vi.fn(),
-
-      registerWorkspace: vi.fn(
-        (_params: { cwd: string }, listener: (snapshot: WorkspaceGitRuntimeSnapshot) => void) => {
-          onWorkspaceSnapshot = listener;
-          return { unsubscribe: workspaceUnsubscribe };
-        },
+test("legacy callers share one live comparison, receive edits, and release it", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await mkdir(join(cwd, "sub"));
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    const first: CheckoutDiffSnapshotPayload[] = [];
+    const second: CheckoutDiffSnapshotPayload[] = [];
+    const [a, b] = await Promise.all([
+      manager.subscribe({ cwd: join(cwd, "sub"), compare: { mode: "uncommitted" } }, (snapshot) =>
+        first.push(snapshot),
       ),
-      getSnapshot: vi.fn(async () => createWorkspaceSnapshot()),
-      getCheckoutDiff:
-        options?.getCheckoutDiffImplementation ?? vi.fn(async () => ({ diff: "", structured: [] })),
-      refresh: vi.fn(),
-      scheduleRefreshForCwd: vi.fn(),
-      requestWorkingTreeWatch: mockRequestWorkingTreeWatch,
-      dispose: vi.fn(),
-    };
-
-    const logger = {
-      child: () => logger,
-      warn: vi.fn(),
-    };
-
-    const manager = new CheckoutDiffManager({
-      workspaceRuntimeStore: createWorkspaceRuntimeStore(),
-      logger: logger as unknown as pino.Logger,
-      paseoHome: "/tmp/paseo-test",
-      workspaceGitService: workspaceGitService as unknown as WorkspaceGitService,
+      manager.subscribe({ cwd, compare: { mode: "uncommitted" } }, (snapshot) =>
+        second.push(snapshot),
+      ),
+    ]);
+    expect(a.initial.cwd).toBe(join(cwd, "sub"));
+    expect(a.initial.files).toEqual(b.initial.files);
+    expect(a.initial.files.map((file) => file.path)).toEqual(["x.ts"]);
+    expect(manager.getMetrics()).toMatchObject({
+      checkoutDiffTargetCount: 1,
+      checkoutDiffSubscriptionCount: 2,
     });
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    await expect.poll(() => first.length, { timeout: 10000 }).toBeGreaterThan(0);
+    expect(first.at(-1)?.files).toEqual(second.at(-1)?.files);
+    await a.unsubscribe();
+    await b.unsubscribe();
+    expect(manager.getMetrics().checkoutDiffTargetCount).toBe(0);
+  });
+}, 30_000);
 
-    return {
-      manager,
-      workspaceGitService,
-      mockRequestWorkingTreeWatch,
-      unsubscribe,
-      getOnChange: () => onChange,
-      getOnWorkspaceSnapshot: () => onWorkspaceSnapshot,
-      workspaceUnsubscribe,
-    };
-  }
-
-  test("subscribe requests a working tree watch with the correct cwd", async () => {
-    const { manager, mockRequestWorkingTreeWatch } = createManager();
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
+test("Committed ignores working-tree edits while All and Uncommitted include them", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("checkout", "-b", "feature");
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "feature");
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    const committed = await manager.read({ cwd, compare: { mode: "base", baseRef: "main" } });
+    const all = await manager.read({ cwd, compare: { mode: "all", baseRef: "main" } });
+    const uncommitted = await manager.read({ cwd, compare: { mode: "uncommitted" } });
+    expect(committed.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "add", content: "const value = 1;" }),
     );
-
-    expect(mockRequestWorkingTreeWatch).toHaveBeenCalledWith(
-      "/tmp/repo/packages/server",
-      expect.any(Function),
+    expect(all.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "add", content: "const value = 2;" }),
+    );
+    expect(uncommitted.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "remove", content: "const value = 1;" }),
     );
   });
+}, 30_000);
 
-  test("unsubscribe calls the working tree watch unsubscribe", async () => {
-    const { manager, unsubscribe } = createManager();
-
-    const subscription = await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
-    );
-
-    subscription.unsubscribe();
-
-    expect(unsubscribe).toHaveBeenCalledTimes(1);
-  });
-
-  test("cancels a subscription while its working tree watch is still opening", async () => {
-    const { manager, watches } = createPendingManager();
+test("cancelling a legacy subscriber during a shared revision does not revive it", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await writeFile(join(cwd, "x.ts"), "export const value = 1;\n");
     const abort = new AbortController();
-
-    const pendingSubscription = manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-        signal: abort.signal,
+    let cancelled = false;
+    const modern = await manager.streams.subscribe(
+      { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "worktree" } },
+      async (frame) => {
+        if (frame.opcode !== 0x40 || cancelled) return;
+        await waitForSubscriberCount(manager, 2);
+        cancelled = true;
+        abort.abort();
       },
-      () => {},
     );
-    abort.abort();
-    watches[0].resolve();
-    await pendingSubscription;
-
-    expect(watches[0].unsubscribeCalls).toBe(1);
-    expect(manager.getMetrics()).toEqual({
-      checkoutDiffTargetCount: 0,
-      checkoutDiffSubscriptionCount: 0,
-      checkoutDiffWatcherCount: 0,
-      checkoutDiffFallbackRefreshTargetCount: 0,
-    });
-  });
-
-  test("shares one opening target between concurrent subscriptions", async () => {
-    const { manager, watches } = createPendingManager();
-
-    const firstSubscription = manager.subscribe(
-      { cwd: "/tmp/repo/packages/server", compare: { mode: "uncommitted" } },
-      () => {},
-    );
-    const secondSubscription = manager.subscribe(
-      { cwd: "/tmp/repo/packages/server", compare: { mode: "uncommitted" } },
-      () => {},
-    );
-
-    expect(watches).toHaveLength(1);
-    watches[0].resolve();
-    const [first, second] = await Promise.all([firstSubscription, secondSubscription]);
-    expect(manager.getMetrics().checkoutDiffSubscriptionCount).toBe(2);
-
-    first.unsubscribe();
-    expect(watches[0].unsubscribeCalls).toBe(0);
-    second.unsubscribe();
-    expect(watches[0].unsubscribeCalls).toBe(1);
-  });
-
-  test("diffCwd uses repoRoot from the working tree watch result", async () => {
-    const { manager, workspaceGitService } = createManager({ repoRoot: "/tmp/repo" });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
+    const legacy = manager.subscribe(
+      { cwd, compare: { mode: "uncommitted" }, signal: abort.signal },
+      () => {
+        throw new Error("Cancelled subscriber received an update");
       },
-      () => {},
     );
-
-    expect(workspaceGitService.getCheckoutDiff).toHaveBeenCalledWith(
-      "/tmp/repo",
-      expect.objectContaining({ mode: "uncommitted", includeStructured: true }),
-      undefined,
-    );
-  });
-
-  test("diff refresh is triggered when the working tree watch callback fires", async () => {
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "a.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
+    try {
+      await modern.start();
+      const result = await legacy;
+      expect(result.initial).toMatchObject({
+        files: [],
+        error: { message: "Diff subscription cancelled" },
       });
-
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-    const listener = vi.fn();
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      listener,
-    );
-
-    const onChange = getOnChange();
-    expect(onChange).toBeTypeOf("function");
-
-    onChange?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(listener).toHaveBeenCalledTimes(1);
-    expect(listener).toHaveBeenCalledWith({
-      cwd: "/tmp/repo/packages/server",
-      files: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
-      error: null,
-    });
-  });
-
-  test("watch-triggered refresh forces a cache bypass on getCheckoutDiff", async () => {
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "a.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
-      });
-
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      vi.fn(),
-    );
-
-    expect(getCheckoutDiff).toHaveBeenNthCalledWith(
-      1,
-      "/tmp/repo",
-      expect.objectContaining({ mode: "uncommitted" }),
-      undefined,
-    );
-
-    const onChange = getOnChange();
-    onChange?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-    const watchFiredCall = getCheckoutDiff.mock.calls[1];
-    expect(watchFiredCall[2]).toEqual({
-      force: true,
-      reason: expect.stringContaining("working-tree"),
-    });
-  });
-
-  test("an edit during an in-flight diff refresh produces one final follow-up", async () => {
-    const inFlightDiff = createDeferred<{
-      diff: string;
-      structured: Array<{
-        path: string;
-        additions: number;
-        deletions: number;
-        status: "modified";
-      }>;
-    }>();
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "tracked.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockImplementationOnce(() => inFlightDiff.promise)
-      .mockResolvedValue({
-        diff: "",
-        structured: [{ path: "tracked.ts", additions: 100, deletions: 25, status: "modified" }],
-      });
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-    const listener = vi.fn();
-
-    await manager.subscribe({ cwd: "/tmp/repo", compare: { mode: "uncommitted" } }, listener);
-    getOnChange()?.();
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-
-    for (let event = 0; event < 100; event += 1) {
-      getOnChange()?.();
+      await result.unsubscribe();
+    } finally {
+      await modern.release();
     }
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-
-    inFlightDiff.resolve({
-      diff: "",
-      structured: [{ path: "tracked.ts", additions: 2, deletions: 1, status: "modified" }],
-    });
-    await vi.waitFor(() => {
-      expect(getCheckoutDiff).toHaveBeenCalledTimes(3);
-      expect(listener).toHaveBeenLastCalledWith({
-        cwd: "/tmp/repo",
-        files: [{ path: "tracked.ts", additions: 100, deletions: 25, status: "modified" }],
-        error: null,
-      });
-    });
   });
+}, 30_000);
 
-  test("base diff subscriptions ignore ordinary working tree edits", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({
-      diff: "",
-      structured: [{ path: "committed.ts", additions: 1, deletions: 0, status: "modified" }],
-    }));
-    const { manager, getOnChange, mockRequestWorkingTreeWatch } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
+async function waitForSubscriberCount(manager: CheckoutDiffManager, count: number): Promise<void> {
+  await expect
+    .poll(() => manager.getMetrics().checkoutDiffSubscriptionCount, { timeout: 10_000 })
+    .toBe(count);
+}
+
+test("moving a tag refreshes binary file metadata even though binary files have no bodies", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("tag", "v1");
+    await writeFile(join(cwd, "image.bin"), Buffer.from([0, 1]));
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "binary");
+    await writeFile(join(cwd, "image.bin"), Buffer.from([0, 2]));
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const subscription = await manager.subscribe(
+      { cwd, compare: { mode: "all", baseRef: "v1" } },
+      (snapshot) => updates.push(snapshot),
+    );
+    expect(subscription.initial.files[0]).toMatchObject({
+      path: "image.bin",
+      isNew: true,
+      status: "binary",
     });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-    getOnChange()?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
-    expect(mockRequestWorkingTreeWatch).not.toHaveBeenCalled();
+    git("update-ref", "refs/tags/v1", "HEAD");
+    await expect.poll(() => updates.at(-1)?.files[0]?.isNew, { timeout: 10000 }).toBe(false);
+    await subscription.unsubscribe();
   });
+}, 30000);
 
-  test("base diff subscriptions ignore worktree-only workspace snapshot updates", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [] }));
-    const { manager, getOnWorkspaceSnapshot } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
+test("legacy diffs retain successful bodies when an oversized sibling is removed", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await writeFile(join(cwd, "a.ts"), "const value = 1;\n");
+    await writeFile(join(cwd, "b.txt"), "x".repeat(1024 * 1024 + 1));
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const subscription = await manager.subscribe(
+      { cwd, compare: { mode: "uncommitted" } },
+      (snapshot) => updates.push(snapshot),
+    );
+    expect(subscription.initial.files).toMatchObject([
+      { path: "a.ts", status: "ok" },
+      { path: "b.txt", status: "too_large" },
+    ]);
+    await rm(join(cwd, "b.txt"));
+    await manager.scheduleRefreshForCwd(cwd);
+    await expect.poll(() => updates.at(-1)?.error).toBeNull();
+    expect(updates.at(-1)?.files[0]).toMatchObject({
+      path: "a.ts",
+      hunks: [
+        {
+          lines: expect.arrayContaining([expect.objectContaining({ content: "const value = 1;" })]),
+        },
+      ],
     });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-
-    getOnWorkspaceSnapshot()?.(
-      createWorkspaceSnapshot({
-        isDirty: true,
-        diffStat: { additions: 5, deletions: 2 },
-      }),
-    );
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
-  });
-
-  test("base diff subscriptions refresh for structural workspace changes", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [] }));
-    const { manager, getOnWorkspaceSnapshot, workspaceGitService } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-
-    expect(workspaceGitService.registerWorkspace).toHaveBeenCalledTimes(1);
-    getOnWorkspaceSnapshot()?.(
-      createWorkspaceSnapshot({
-        currentBranch: "feature-2",
-        isDirty: true,
-        diffStat: { additions: 5, deletions: 2 },
-      }),
-    );
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-    expect(getCheckoutDiff.mock.calls[1]?.[2]).toBeUndefined();
-
-    getOnWorkspaceSnapshot()?.(createWorkspaceSnapshot({ aheadBehind: { ahead: 2, behind: 0 } }));
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(3);
-  });
-
-  test("falls back to cwd when the working tree watch returns no repo root", async () => {
-    const { manager, workspaceGitService } = createManager({ repoRoot: null });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/plain",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
-    );
-
-    expect(workspaceGitService.getCheckoutDiff).toHaveBeenCalledWith(
-      "/tmp/plain",
-      expect.objectContaining({ mode: "uncommitted", includeStructured: true }),
-      undefined,
-    );
+    subscription.unsubscribe();
   });
 });
+
+test("legacy subscriptions reselect the preferred base when a remote ref appears", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("checkout", "-b", "feature");
+    await writeFile(join(cwd, "b.ts"), "export const b = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "feature");
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const params = { cwd, compare: { mode: "base" as const, baseRef: "main" } };
+    const subscription = await manager.subscribe(params, (snapshot) => updates.push(snapshot));
+    try {
+      expect(subscription.initial.files.map((file) => file.path)).toEqual(["b.ts"]);
+      git("update-ref", "refs/remotes/origin/main", "HEAD");
+      await manager.scheduleRefreshForCwd(cwd);
+      await expect.poll(() => updates.at(-1)?.files.length, { timeout: 5000 }).toBe(0);
+      expect(updates.at(-1)).toEqual(await manager.read(params));
+    } finally {
+      await subscription.unsubscribe();
+    }
+  });
+});
+
+test("cold many-file reads batch Git patches while matching the legacy reader", async () => {
+  const { getCheckoutDiff } = await import("../utils/checkout-git.js");
+  const { startGitCommandMetrics, stopGitCommandMetrics } =
+    await import("../utils/run-git-command.js");
+  await withCheckout(async ({ cwd, manager, git }) => {
+    const count = 1000;
+    for (let index = 0; index < count; index++)
+      await writeFile(join(cwd, `file-${index}.ts`), "export const value = 0;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "many files");
+    for (let index = 0; index < count; index++)
+      await writeFile(join(cwd, `file-${index}.ts`), "export const value = 1;\n");
+    const legacyStart = performance.now();
+    const legacy = await getCheckoutDiff(cwd, { mode: "uncommitted", includeStructured: true });
+    const legacyMs = performance.now() - legacyStart;
+    startGitCommandMetrics();
+    const streamedStart = performance.now();
+    const streamed = await manager.read({ cwd, compare: { mode: "uncommitted" } });
+    const streamedMs = performance.now() - streamedStart;
+    const metrics = stopGitCommandMetrics();
+    const patches = metrics.commands.filter((command) => command.args.includes("--patch"));
+    const artifactDirectory = join(import.meta.dirname, "../../../../.artifacts/diff-subscription");
+    await mkdir(artifactDirectory, { recursive: true });
+    await writeFile(
+      join(artifactDirectory, "cold-many-file-metrics.json"),
+      JSON.stringify({ count, legacyMs, streamedMs, patchCommands: patches.length }, null, 2),
+    );
+    expect(streamed.error).toBeNull();
+    expect(streamed.files).toHaveLength(count);
+    expect(legacy.structured).toHaveLength(count);
+    expect(streamed.files.map((file) => [file.path, file.hunks])).toEqual(
+      legacy.structured?.map((file) => [file.path, file.hunks]),
+    );
+    expect(patches.length).toBeLessThanOrEqual(Math.ceil(count / 64));
+  });
+}, 60000);
diff --git a/packages/server/src/server/checkout-diff-manager.ts b/packages/server/src/server/checkout-diff-manager.ts
index 917813d587..921934e70e 100644
--- a/packages/server/src/server/checkout-diff-manager.ts
+++ b/packages/server/src/server/checkout-diff-manager.ts
@@ -1,399 +1,201 @@
-import { type WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import type pino from "pino";
 import type { SubscribeCheckoutDiffRequest, SessionOutboundMessage } from "./messages.js";
-import type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.js";
+import type { WorkspaceGitService } from "./workspace-git-service.js";
+import type { WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
+import { DiffSubscriptions, type CommitFileRead } from "./diff/index.js";
+import {
+  DiffOpcode,
+  materializeDiffFile,
+  type DiffFrame,
+  type DiffBegin,
+  type DiffBody,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import {
+  CHECKOUT_DIFF_MAX_STRUCTURED_BYTES,
+  resolveCheckoutDiffBase,
+} from "../utils/checkout-git.js";
 import { expandTilde } from "../utils/path.js";
 import { toCheckoutError } from "./checkout-git-utils.js";
 
-const CHECKOUT_DIFF_WATCH_DEBOUNCE_MS = 150;
-
-type CheckoutDiffWorkspace = Pick<
-  WorkspaceGitService,
-  "getCheckoutDiff" | "getSnapshot" | "registerWorkspace" | "requestWorkingTreeWatch"
->;
-
 export type CheckoutDiffCompareInput = SubscribeCheckoutDiffRequest["compare"];
-
 export type CheckoutDiffSnapshotPayload = Omit<
   Extract<SessionOutboundMessage, { type: "checkout_diff_update" }>["payload"],
   "subscriptionId"
 >;
-
 export interface CheckoutDiffMetrics {
   checkoutDiffTargetCount: number;
   checkoutDiffSubscriptionCount: number;
   checkoutDiffWatcherCount: number;
   checkoutDiffFallbackRefreshTargetCount: number;
 }
-
-interface CheckoutDiffWatchTarget {
-  key: string;
-  cwd: string;
-  diffCwd: string;
-  compare: CheckoutDiffCompareInput;
-  listeners: Set<(snapshot: CheckoutDiffSnapshotPayload) => void>;
-  workingTreeWatchUnsubscribe: (() => void) | null;
-  workspaceGitUnsubscribe: (() => void) | null;
-  latestWorkspaceStructureFingerprint: string | null;
-  latestWorkspaceWorktreeFingerprint: string | null;
-  latestWorkspaceForgeFingerprint: string | null;
-  debounceTimer: NodeJS.Timeout | null;
-  pendingDebounceForce: boolean;
-  refreshPromise: Promise<void> | null;
-  refreshQueued: boolean;
-  refreshQueuedForce: boolean;
-  latestPayload: CheckoutDiffSnapshotPayload | null;
-  latestFingerprint: string | null;
-  openPromise: Promise<void> | null;
-}
-
 export interface CheckoutDiffSubscriptionRequest {
   cwd: string;
   compare: CheckoutDiffCompareInput;
   signal?: AbortSignal;
 }
-
 export interface CheckoutDiffSubscription {
   initial: CheckoutDiffSnapshotPayload;
-  unsubscribe: () => void;
+  unsubscribe(): void;
 }
 
+// COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+// Old clients receive the same JSON snapshot while the shared engine owns reads and observation.
 export class CheckoutDiffManager {
-  private readonly workspaceGitService: CheckoutDiffWorkspace;
-  private readonly workspaceRuntimeStore: WorkspaceRuntimeStore;
-  private readonly targets = new Map<string, CheckoutDiffWatchTarget>();
-
+  readonly streams: DiffSubscriptions;
+  private readonly paseoHome: string;
   constructor(options: {
     logger: pino.Logger;
     paseoHome: string;
-    workspaceGitService: CheckoutDiffWorkspace;
+    workspaceGitService: Pick<WorkspaceGitService, "requestWorkingTreeWatch">;
     workspaceRuntimeStore: WorkspaceRuntimeStore;
   }) {
-    this.workspaceGitService = options.workspaceGitService;
-    this.workspaceRuntimeStore = options.workspaceRuntimeStore;
+    this.streams = new DiffSubscriptions(options.workspaceGitService);
+    this.paseoHome = options.paseoHome;
+  }
+  readCommitFile(input: CommitFileRead) {
+    return this.streams.readCommitFile(input);
   }
-
   async read(
     params: Omit<CheckoutDiffSubscriptionRequest, "signal">,
   ): Promise<CheckoutDiffSnapshotPayload> {
-    return this.computeCheckoutDiffSnapshot(params.cwd, this.normalizeCompare(params.compare));
+    const subscription = await this.subscribe(params, () => {});
+    await subscription.unsubscribe();
+    return subscription.initial;
   }
-
   async subscribe(
     params: CheckoutDiffSubscriptionRequest,
     listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
   ): Promise<CheckoutDiffSubscription> {
-    const cwd = params.cwd;
-    const compare = this.normalizeCompare(params.compare);
-    const target = this.ensureTarget(cwd, compare);
-    target.listeners.add(listener);
-    target.openPromise ??= this.openTarget(target);
-
-    let isSubscribed = true;
-    const unsubscribe = () => {
-      if (!isSubscribed) {
+    const cwd = expandTilde(params.cwd);
+    let resolveInitial!: (snapshot: CheckoutDiffSnapshotPayload) => void;
+    const initial = new Promise<CheckoutDiffSnapshotPayload>((resolve) => {
+      resolveInitial = resolve;
+    });
+    let delivered = false;
+    let pending: DiffBegin | null = null;
+    let files = new Map<string, ParsedDiffFile>();
+    let bodies = new Map<string, DiffBody>();
+    const receive = async (frame: DiffFrame) => {
+      if (params.signal?.aborted) return;
+      if (frame.opcode === DiffOpcode.Begin) {
+        pending = frame;
+        bodies = new Map();
         return;
       }
-      isSubscribed = false;
-      params.signal?.removeEventListener("abort", unsubscribe);
-      this.removeListener(target, listener);
-    };
-    params.signal?.addEventListener("abort", unsubscribe, { once: true });
-    if (params.signal?.aborted) {
-      unsubscribe();
-    }
-
-    try {
-      await target.openPromise;
-      const initial =
-        target.latestPayload ??
-        (await this.computeCheckoutDiffSnapshot(target.cwd, target.compare, {
-          diffCwd: target.diffCwd,
-        }));
-      target.latestPayload = initial;
-      target.latestFingerprint = JSON.stringify(initial);
-      return { initial, unsubscribe };
-    } catch (error) {
-      unsubscribe();
-      throw error;
-    }
-  }
-
-  scheduleRefreshForCwd(cwd: string): void {
-    const resolvedCwd = expandTilde(cwd);
-    for (const target of this.targets.values()) {
-      if (target.cwd !== resolvedCwd && target.diffCwd !== resolvedCwd) {
-        continue;
+      if (!pending || frame.revision !== pending.revision) return;
+      if (frame.opcode === DiffOpcode.Bodies) {
+        for (const body of frame.files) bodies.set(body.path, body);
+        return;
       }
-      this.scheduleTargetRefresh(target);
+      let payload: CheckoutDiffSnapshotPayload;
+      if (frame.error) {
+        const message = frame.error.message;
+        payload = {
+          cwd,
+          files: [],
+          error: toCheckoutError(new Error(message)),
+          diffTooLarge: frame.diffTooLarge,
+        };
+        files.clear();
+      } else {
+        const next = new Map<string, ParsedDiffFile>();
+        const omitted = new Set(frame.omitted);
+        for (const entry of pending.entries) {
+          const previous = pending.baseRevision ? files.get(entry.path) : undefined;
+          const body = bodies.get(entry.path) ?? null;
+          const file = materializeDiffFile(entry, body, omitted.has(entry.path));
+          if (!entry.body && previous && entry.content === "text" && !omitted.has(entry.path))
+            file.hunks = previous.hunks;
+          next.set(entry.path, file);
+        }
+        files = next;
+        // Stream omissions remain file placeholders; the JSON budget rejects a legacy snapshot.
+        payload = legacySnapshot(cwd, [...next.values()]);
+      }
+      pending = null;
+      if (delivered) listener(payload);
+      else {
+        delivered = true;
+        resolveInitial(payload);
+      }
+    };
+    try {
+      const baseRef = await resolveCheckoutDiffBase(cwd, params.compare, {
+        paseoHome: this.paseoHome,
+      });
+      if (!baseRef) return { initial: { cwd, files: [], error: null }, unsubscribe() {} };
+      const subscription = await this.streams.subscribe(
+        {
+          cwd,
+          base: { kind: "rev", rev: baseRef },
+          checkoutBase:
+            params.compare.mode === "uncommitted"
+              ? undefined
+              : { compare: params.compare, paseoHome: this.paseoHome },
+          head:
+            params.compare.mode === "base" ? { kind: "rev", rev: "HEAD" } : { kind: "worktree" },
+          mergeBase: params.compare.mode !== "uncommitted",
+          ignoreWhitespace: params.compare.ignoreWhitespace,
+        },
+        receive,
+      );
+      const unsubscribe = async () => {
+        if (!delivered) {
+          delivered = true;
+          resolveInitial({
+            cwd,
+            files: [],
+            error: toCheckoutError(new Error("Diff subscription cancelled")),
+          });
+        }
+        params.signal?.removeEventListener("abort", unsubscribe);
+        await subscription.release();
+      };
+      params.signal?.addEventListener("abort", unsubscribe, { once: true });
+      if (params.signal?.aborted) {
+        await subscription.release();
+        throw new Error("Diff subscription cancelled");
+      }
+      await subscription.start();
+      return { initial: await initial, unsubscribe };
+    } catch (error) {
+      return { initial: { cwd, files: [], error: toCheckoutError(error) }, unsubscribe() {} };
     }
   }
-
+  scheduleRefreshForCwd(cwd: string): Promise<void> {
+    return this.streams.invalidateForCwd(expandTilde(cwd));
+  }
   getMetrics(): CheckoutDiffMetrics {
-    let checkoutDiffSubscriptionCount = 0;
-
-    for (const target of this.targets.values()) {
-      checkoutDiffSubscriptionCount += target.listeners.size;
-    }
-
+    const metrics = this.streams.getMetrics();
     return {
-      checkoutDiffTargetCount: this.targets.size,
-      checkoutDiffSubscriptionCount,
-      checkoutDiffWatcherCount: 0,
+      checkoutDiffTargetCount: metrics.targets,
+      checkoutDiffSubscriptionCount: metrics.subscriptions,
+      checkoutDiffWatcherCount: metrics.metadataObservers,
       checkoutDiffFallbackRefreshTargetCount: 0,
     };
   }
-
-  dispose(): void {
-    for (const target of this.targets.values()) {
-      this.closeTarget(target);
-    }
-    this.targets.clear();
-  }
-
-  private normalizeCompare(compare: CheckoutDiffCompareInput): CheckoutDiffCompareInput {
-    const ignoreWhitespace = compare.ignoreWhitespace === true;
-    if (compare.mode === "uncommitted") {
-      return { mode: "uncommitted", ignoreWhitespace };
-    }
-    const trimmedBaseRef = compare.baseRef?.trim();
-    return trimmedBaseRef
-      ? { mode: compare.mode, baseRef: trimmedBaseRef, ignoreWhitespace }
-      : { mode: compare.mode, ignoreWhitespace };
-  }
-
-  private buildTargetKey(cwd: string, compare: CheckoutDiffCompareInput): string {
-    return JSON.stringify([
-      cwd,
-      compare.mode,
-      compare.mode !== "uncommitted" ? (compare.baseRef ?? "") : "",
-      compare.ignoreWhitespace === true,
-    ]);
-  }
-
-  private closeTarget(target: CheckoutDiffWatchTarget): void {
-    if (target.debounceTimer) {
-      clearTimeout(target.debounceTimer);
-      target.debounceTimer = null;
-    }
-    target.workingTreeWatchUnsubscribe?.();
-    target.workingTreeWatchUnsubscribe = null;
-    target.workspaceGitUnsubscribe?.();
-    target.workspaceGitUnsubscribe = null;
-    target.listeners.clear();
-  }
-
-  private rememberWorkspaceSnapshot(
-    target: CheckoutDiffWatchTarget,
-    snapshot: WorkspaceGitRuntimeSnapshot,
-  ): void {
-    const structureFingerprint = JSON.stringify({
-      isGit: snapshot.git.isGit,
-      repoRoot: snapshot.git.repoRoot,
-      mainRepoRoot: snapshot.git.mainRepoRoot,
-      currentBranch: snapshot.git.currentBranch,
-      remoteUrl: snapshot.git.remoteUrl,
-      isPaseoOwnedWorktree: snapshot.git.isPaseoOwnedWorktree,
-      baseRef: snapshot.git.baseRef,
-      aheadBehind: snapshot.git.aheadBehind,
-      aheadOfOrigin: snapshot.git.aheadOfOrigin,
-      behindOfOrigin: snapshot.git.behindOfOrigin,
-      hasRemote: snapshot.git.hasRemote,
-    });
-    const worktreeFingerprint = JSON.stringify({
-      isDirty: snapshot.git.isDirty,
-      diffStat: snapshot.git.diffStat,
-    });
-    const forgeFingerprint = JSON.stringify(snapshot.forge);
-    const previousStructureFingerprint = target.latestWorkspaceStructureFingerprint;
-    const previousWorktreeFingerprint = target.latestWorkspaceWorktreeFingerprint;
-    const previousForgeFingerprint = target.latestWorkspaceForgeFingerprint;
-    target.latestWorkspaceStructureFingerprint = structureFingerprint;
-    target.latestWorkspaceWorktreeFingerprint = worktreeFingerprint;
-    target.latestWorkspaceForgeFingerprint = forgeFingerprint;
-
-    if (previousStructureFingerprint === null) {
-      return;
-    }
-    const structureChanged = structureFingerprint !== previousStructureFingerprint;
-    const worktreeChanged = worktreeFingerprint !== previousWorktreeFingerprint;
-    const forgeChanged = forgeFingerprint !== previousForgeFingerprint;
-    if (structureChanged || (!worktreeChanged && !forgeChanged)) {
-      this.scheduleTargetRefresh(target, false);
-    }
-  }
-
-  private removeListener(
-    target: CheckoutDiffWatchTarget,
-    listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
-  ): void {
-    target.listeners.delete(listener);
-    if (target.listeners.size > 0) {
-      return;
-    }
-    this.closeTarget(target);
-    if (this.targets.get(target.key) === target) {
-      this.targets.delete(target.key);
-    }
-  }
-
-  private scheduleTargetRefresh(target: CheckoutDiffWatchTarget, force = true): void {
-    target.pendingDebounceForce ||= force;
-    if (target.debounceTimer) {
-      clearTimeout(target.debounceTimer);
-    }
-    target.debounceTimer = setTimeout(() => {
-      target.debounceTimer = null;
-      const pendingForce = target.pendingDebounceForce;
-      target.pendingDebounceForce = false;
-      void this.refreshTarget(target, pendingForce);
-    }, CHECKOUT_DIFF_WATCH_DEBOUNCE_MS);
-  }
-
-  private async computeCheckoutDiffSnapshot(
-    cwd: string,
-    compare: CheckoutDiffCompareInput,
-    options?: { diffCwd?: string; force?: boolean; reason?: string },
-  ): Promise<CheckoutDiffSnapshotPayload> {
-    const diffCwd = options?.diffCwd ?? cwd;
-    try {
-      const diffResult = await this.workspaceGitService.getCheckoutDiff(
-        diffCwd,
-        {
-          mode: compare.mode,
-          baseRef: compare.baseRef,
-          ignoreWhitespace: compare.ignoreWhitespace,
-          includeStructured: true,
-        },
-        options?.force
-          ? { force: true, reason: options.reason ?? "checkout-diff-refresh" }
-          : undefined,
-      );
-      if (diffResult.diffTooLarge) {
-        return {
-          cwd,
-          files: [],
-          diffTooLarge: true,
-          error: toCheckoutError(new Error("Diff too large to display")),
-        };
-      }
-      const files = [...(diffResult.structured ?? [])];
-      files.sort((a, b) => {
-        if (a.path === b.path) return 0;
-        return a.path < b.path ? -1 : 1;
-      });
-      return {
-        cwd,
-        files,
-        error: null,
-      };
-    } catch (error) {
-      return {
-        cwd,
-        files: [],
-        error: toCheckoutError(error),
-      };
-    }
-  }
-
-  private async refreshTarget(target: CheckoutDiffWatchTarget, force: boolean): Promise<void> {
-    if (target.refreshPromise) {
-      target.refreshQueued = true;
-      target.refreshQueuedForce ||= force;
-      return;
-    }
-
-    target.refreshPromise = (async () => {
-      let currentForce = force;
-      do {
-        target.refreshQueued = false;
-        target.refreshQueuedForce = false;
-        const snapshot = await this.computeCheckoutDiffSnapshot(target.cwd, target.compare, {
-          diffCwd: target.diffCwd,
-          force: currentForce,
-          ...(currentForce ? { reason: "working-tree-watch" } : {}),
-        });
-        target.latestPayload = snapshot;
-        const fingerprint = JSON.stringify(snapshot);
-        if (fingerprint !== target.latestFingerprint) {
-          target.latestFingerprint = fingerprint;
-          for (const listener of target.listeners) {
-            listener(snapshot);
-          }
-        }
-        currentForce = target.refreshQueuedForce;
-      } while (target.refreshQueued);
-    })();
-
-    try {
-      await target.refreshPromise;
-    } finally {
-      target.refreshPromise = null;
-    }
-  }
-
-  private ensureTarget(cwd: string, compare: CheckoutDiffCompareInput): CheckoutDiffWatchTarget {
-    const targetKey = this.buildTargetKey(cwd, compare);
-    const existing = this.targets.get(targetKey);
-    if (existing) {
-      return existing;
-    }
-
-    const target: CheckoutDiffWatchTarget = {
-      key: targetKey,
-      cwd,
-      diffCwd: cwd,
-      compare,
-      listeners: new Set(),
-      workingTreeWatchUnsubscribe: null,
-      workspaceGitUnsubscribe: null,
-      latestWorkspaceStructureFingerprint: null,
-      latestWorkspaceWorktreeFingerprint: null,
-      latestWorkspaceForgeFingerprint: null,
-      debounceTimer: null,
-      pendingDebounceForce: false,
-      refreshPromise: null,
-      refreshQueued: false,
-      refreshQueuedForce: false,
-      latestPayload: null,
-      latestFingerprint: null,
-      openPromise: null,
-    };
-    this.targets.set(targetKey, target);
-    return target;
-  }
-
-  private async openTarget(target: CheckoutDiffWatchTarget): Promise<void> {
-    if (target.compare.mode !== "uncommitted") {
-      const snapshot =
-        this.workspaceRuntimeStore.get(target.cwd) ??
-        (await this.workspaceGitService.getSnapshot(target.cwd, { includeForge: false }));
-      target.diffCwd = snapshot.git.repoRoot ?? target.cwd;
-      if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-        return;
-      }
-      this.rememberWorkspaceSnapshot(target, snapshot);
-      const workspaceSubscription = this.workspaceGitService.registerWorkspace(
-        { cwd: target.cwd },
-        (nextSnapshot) => this.rememberWorkspaceSnapshot(target, nextSnapshot),
-      );
-      if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-        workspaceSubscription.unsubscribe();
-        return;
-      }
-      target.workspaceGitUnsubscribe = workspaceSubscription.unsubscribe;
-      if (target.compare.mode === "base") return;
-    }
-
-    const { repoRoot, unsubscribe } = await this.workspaceGitService.requestWorkingTreeWatch(
-      target.cwd,
-      () => this.scheduleTargetRefresh(target),
-    );
-    target.diffCwd = repoRoot ?? target.cwd;
-    if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-      unsubscribe();
-      return;
-    }
-    target.workingTreeWatchUnsubscribe = unsubscribe;
+  async dispose(): Promise<void> {
+    await this.streams.close();
   }
 }
+
+function legacySnapshot(cwd: string, files: ParsedDiffFile[]): CheckoutDiffSnapshotPayload {
+  let bytes = 2;
+  for (let index = 0; index < files.length; index++) {
+    bytes += Buffer.byteLength(JSON.stringify(files[index])) + Number(index > 0);
+    if (bytes > CHECKOUT_DIFF_MAX_STRUCTURED_BYTES) {
+      return legacyTooLarge(cwd);
+    }
+  }
+  return { cwd, files, error: null };
+}
+
+function legacyTooLarge(cwd: string): CheckoutDiffSnapshotPayload {
+  return {
+    cwd,
+    files: [],
+    diffTooLarge: true,
+    error: toCheckoutError(new Error("Diff too large to display")),
+  };
+}
diff --git a/packages/server/src/server/checkout/status-projection.ts b/packages/server/src/server/checkout/status-projection.ts
index 7f7365efca..93242cb941 100644
--- a/packages/server/src/server/checkout/status-projection.ts
+++ b/packages/server/src/server/checkout/status-projection.ts
@@ -61,6 +61,8 @@ export function buildCheckoutStatusPayloadFromSnapshot({
       currentBranch: snapshot.git.currentBranch ?? null,
       isDirty: snapshot.git.isDirty,
       baseRef: snapshot.git.baseRef,
+      baseRefExact: snapshot.git.baseRefExact,
+      comparisonBaseRef: snapshot.git.comparisonBaseRef,
       aheadBehind: snapshot.git.aheadBehind ?? null,
       upstreamRef: snapshot.git.upstreamRef ?? null,
       aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
@@ -81,6 +83,8 @@ export function buildCheckoutStatusPayloadFromSnapshot({
     currentBranch: snapshot.git.currentBranch ?? null,
     isDirty: snapshot.git.isDirty,
     baseRef: snapshot.git.baseRef ?? null,
+    baseRefExact: snapshot.git.baseRefExact,
+    comparisonBaseRef: snapshot.git.comparisonBaseRef,
     aheadBehind: snapshot.git.aheadBehind ?? null,
     upstreamRef: snapshot.git.upstreamRef ?? null,
     aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
diff --git a/packages/server/src/server/config.test.ts b/packages/server/src/server/config.test.ts
index 53a77338b6..f453da7812 100644
--- a/packages/server/src/server/config.test.ts
+++ b/packages/server/src/server/config.test.ts
@@ -40,6 +40,24 @@ describe("server config", () => {
     expect(blockingMs).toBeLessThan(50);
   });
 
+  test.each([undefined, false, true])(
+    "restart recovery requires explicit opt-in (%s)",
+    async (enabled) => {
+      const paseoHome = await mkdtemp(path.join(os.tmpdir(), "paseo-config-recovery-"));
+      roots.push(paseoHome);
+      await writeFile(
+        path.join(paseoHome, "config.json"),
+        JSON.stringify({
+          version: 1,
+          agents: { resumeOnStartup: enabled, resumePrompt: "Continue exactly.\n" },
+        }),
+      );
+      const config = loadConfig(paseoHome, { env: {} });
+      expect(config.resumeOnStartup).toBe(enabled === true);
+      expect(config.resumePrompt).toBe("Continue exactly.\n");
+    },
+  );
+
   test("records when the daemon is managed by Paseo Desktop", async () => {
     const paseoHome = await mkdtemp(path.join(os.tmpdir(), "paseo-config-desktop-managed-"));
     roots.push(paseoHome);
diff --git a/packages/server/src/server/config.ts b/packages/server/src/server/config.ts
index 07c5c287b8..5340bbbcd3 100644
--- a/packages/server/src/server/config.ts
+++ b/packages/server/src/server/config.ts
@@ -839,7 +839,7 @@ function resolveSpeechOverrideControlledPaths(
 
 function resolveRestartRecoveryConfig(agents: PersistedConfig["agents"]) {
   return {
-    resumeOnStartup: agents?.resumeOnStartup ?? true,
+    resumeOnStartup: agents?.resumeOnStartup ?? false,
     resumePrompt: agents?.resumePrompt ?? "Resume working.",
   };
 }
diff --git a/packages/server/src/server/connected-hosts/flow-control.ts b/packages/server/src/server/connected-hosts/flow-control.ts
new file mode 100644
index 0000000000..eafc52e9e0
--- /dev/null
+++ b/packages/server/src/server/connected-hosts/flow-control.ts
@@ -0,0 +1,51 @@
+export class HostChannelOutputLimitError extends Error {
+  constructor() {
+    super("Host channel output limit reached");
+  }
+}
+
+/** Completion belongs to the receiver's forwarding write, not just our physical socket. */
+export class HostChannelFlowControl {
+  private sequence = 0;
+  private bytes = 0;
+  private closed = false;
+  private readonly pending = new Map<
+    number,
+    {
+      resolve(): void;
+      reject(error: Error): void;
+    }
+  >();
+
+  constructor(private readonly reserveShared: (bytes: number) => () => void) {}
+
+  async send(bytes: number, write: () => Promise<void>): Promise<void> {
+    if (this.closed) throw new Error("Host channel closed");
+    // Bound both payload retention and metadata for a producer of tiny frames.
+    if (this.bytes + bytes > 32 * 1024 * 1024 || this.pending.size >= 4096)
+      throw new HostChannelOutputLimitError();
+    const release = this.reserveShared(bytes);
+    this.bytes += bytes;
+    const sequence = ++this.sequence;
+    const acknowledgment = new Promise<void>((resolve, reject) => {
+      this.pending.set(sequence, { resolve, reject });
+    });
+    try {
+      await Promise.all([acknowledgment, write()]);
+    } finally {
+      this.pending.delete(sequence);
+      this.bytes -= bytes;
+      release();
+    }
+  }
+
+  acknowledge(sequence: number): void {
+    this.pending.get(sequence)?.resolve();
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const pending of this.pending.values()) pending.reject(new Error("Host channel closed"));
+    this.pending.clear();
+  }
+}
diff --git a/packages/server/src/server/connected-hosts/hosts.e2e.test.ts b/packages/server/src/server/connected-hosts/hosts.e2e.test.ts
index 4c6d79aced..5b618f0670 100644
--- a/packages/server/src/server/connected-hosts/hosts.e2e.test.ts
+++ b/packages/server/src/server/connected-hosts/hosts.e2e.test.ts
@@ -183,7 +183,7 @@ test("ordinary routed APIs isolate scopes and enforce one-hop, disable and origi
   await paseo.dispose();
 });
 
-test("routed authority is bounded by the caller, with isolated simultaneous sessions", async () => {
+test("routed authority isolates simultaneous sessions and preserves ordinary permission RPC errors", async () => {
   const b = await daemon();
   const a = await daemon();
   const owner = await api(a);
@@ -210,33 +210,16 @@ test("routed authority is bounded by the caller, with isolated simultaneous sess
     code: "permission_denied",
   });
   expect((await owner.paseo.hosts.list()).hosts).toHaveLength(1);
-  await remote.dispose();
-});
-
-test("SDK host clients preserve ordinary permission RPC errors", async () => {
-  const b = await daemon();
-  const a = await daemon();
-  const owner = await api(a);
-  await owner.paseo.hosts.add({ connection: `127.0.0.1:${b.port}` });
-  const serverId = (await online(owner.paseo)).hosts[0]!.serverId!;
-  const clients = [a, b].map((host) =>
-    createHostClient(`127.0.0.1:${host.port}`, {
-      clientId: crypto.randomUUID(),
-      sessionPermissions: ["daemon.read", "workspace.read"],
-      reconnect: { enabled: false },
-    }),
-  );
-  for (const client of clients) {
-    cleanup.push(() => client.close());
-    await client.connect();
-  }
-  const origin = createPaseoApi(clients[0]!);
-  const direct = createPaseoApi(clients[1]!);
-  const remote = await origin.hosts.client(serverId);
+  const directClient = createHostClient(`127.0.0.1:${b.port}`, {
+    clientId: crypto.randomUUID(),
+    sessionPermissions: ["daemon.read", "workspace.read"],
+    reconnect: { enabled: false },
+  });
+  await directClient.connect();
+  const direct = createPaseoApi(directClient);
   cleanup.push(async () => {
-    await remote.dispose();
     await direct.dispose();
-    await origin.dispose();
+    await directClient.close();
   });
   const input = { source: { kind: "directory" as const, path: b.staticDir } };
   const directError = (await direct.workspaces.create(input).catch((error: unknown) => error)) as {
@@ -247,6 +230,7 @@ test("SDK host clients preserve ordinary permission RPC errors", async () => {
   };
   expect(directError.code).toBe("access_denied");
   expect(remoteError.code).toBe(directError.code);
+  await remote.dispose();
 });
 
 test("distinct origin sessions cannot collide through a caller-selected route scope, including terminal binary output", async () => {
@@ -784,6 +768,211 @@ test("old capabilities fail before execution and authentication errors recover t
   expect((await online(paseo)).hosts[0]!.serverId).toBe(b.daemon.getServerId());
 });
 
+async function updatableDestination() {
+  let features: { connectedHosts: boolean; hostMultiplexing: boolean } | undefined;
+  let holding = false;
+  const held: (() => void)[] = [];
+  let connections = 0;
+  const http = createServer();
+  const ws = new WebSocketServer({ server: http });
+  ws.on("connection", (socket) => {
+    connections++;
+    socket.on("message", (data) => {
+      const frame = JSON.parse(data.toString());
+      if (frame.type === "ping") socket.send(JSON.stringify({ type: "pong" }));
+      if (frame.type !== "hello") return;
+      const reply = () =>
+        socket.send(
+          JSON.stringify({
+            type: "session",
+            message: {
+              type: "status",
+              payload: {
+                status: "server_info",
+                serverId: "srv_updated",
+                hostname: "updated",
+                version: "0.12.0",
+                ...(features ? { features } : {}),
+              },
+            },
+          }),
+        );
+      if (holding) held.push(reply);
+      else reply();
+    });
+  });
+  http.listen(0, "127.0.0.1");
+  await once(http, "listening");
+  cleanup.push(async () => {
+    for (const socket of ws.clients) socket.terminate();
+    await new Promise<void>((resolve) => ws.close(() => resolve()));
+    await new Promise<void>((resolve) => http.close(() => resolve()));
+  });
+  const address = http.address();
+  if (!address || typeof address === "string") throw new Error("Missing destination port");
+  return {
+    port: address.port,
+    connections: () => connections,
+    hold: () => {
+      holding = true;
+    },
+    update: () => {
+      features = { connectedHosts: true, hostMultiplexing: true };
+      holding = false;
+      for (const reply of held.splice(0)) reply();
+    },
+  };
+}
+async function capabilityRetry(paseo: ReturnType<typeof createPaseoApi>): Promise<number> {
+  let retryAt = "";
+  await expect
+    .poll(
+      async () => {
+        const row = (await paseo.hosts.list()).hosts[0];
+        retryAt = row?.nextRetryAt ?? "";
+        return row;
+      },
+      { timeout: 5000 },
+    )
+    .toMatchObject({
+      status: "offline",
+      nextRetryAt: expect.any(String),
+      error: { code: "unsupported_capability" },
+    });
+  return Date.parse(retryAt);
+}
+
+test("a destination updated past unsupported_capability keeps its guidance while retrying and comes online, while duplicate_host stays terminal", async () => {
+  const destination = await updatableDestination();
+  const a = await daemon();
+  const { paseo } = await api(a);
+  const host = await paseo.hosts.add({ connection: `127.0.0.1:${destination.port}` });
+  await capabilityRetry(paseo);
+  destination.hold();
+  await expect
+    .poll(async () => (await paseo.hosts.list()).hosts[0], { timeout: 5000 })
+    .toMatchObject({ status: "connecting", error: { code: "unsupported_capability" } });
+  await expect(paseo.hosts.client("srv_updated")).rejects.toMatchObject({
+    code: "unsupported_capability",
+  });
+  destination.update();
+  expect((await online(paseo)).hosts[0]).toMatchObject({
+    registrationId: host.registrationId,
+    serverId: "srv_updated",
+    nextRetryAt: null,
+    error: null,
+  });
+  await paseo.hosts.add({ connection: `ws://127.0.0.1:${destination.port}/ws` });
+  await expect
+    .poll(async () => (await paseo.hosts.list()).hosts[1], { timeout: 5000 })
+    .toMatchObject({ status: "error", nextRetryAt: null, error: { code: "duplicate_host" } });
+});
+
+test("disabling or removing a host cancels its pending capability retry", async () => {
+  const destination = await updatableDestination();
+  const a = await daemon();
+  const { paseo } = await api(a);
+  const host = await paseo.hosts.add({ connection: `127.0.0.1:${destination.port}` });
+  let retryAt = await capabilityRetry(paseo);
+  let connections = destination.connections();
+  await paseo.hosts.update(host.registrationId, { enabled: false });
+  await new Promise((resolve) => setTimeout(resolve, retryAt - Date.now() + 500));
+  expect(destination.connections()).toBe(connections);
+  await paseo.hosts.update(host.registrationId, { enabled: true });
+  retryAt = await capabilityRetry(paseo);
+  connections = destination.connections();
+  await paseo.hosts.remove(host.registrationId);
+  await new Promise((resolve) => setTimeout(resolve, retryAt - Date.now() + 500));
+  expect(destination.connections()).toBe(connections);
+});
+
+import {
+  createDaemonChannel,
+  exportPublicKey,
+  generateKeyPair,
+  openDaemonSecureChannel,
+  type Transport,
+} from "@getpaseo/relay/e2ee";
+test("a capability retry over a relay keeps the protected endpoint security it negotiated", async () => {
+  const keys = generateKeyPair();
+  const legacyReceived: unknown[] = [];
+  let connections = 0;
+  let retryClosed = false;
+  const http = createServer();
+  const ws = new WebSocketServer({ server: http });
+  ws.on("connection", (socket) => {
+    connections++;
+    const wire: Transport = {
+      send: (data) => socket.send(data),
+      close: (code, reason) => socket.close(code, reason),
+      onmessage: null,
+      onclose: null,
+      onerror: null,
+    };
+    socket.on("message", (data, isBinary) => {
+      const bytes = Buffer.from(data as Buffer);
+      wire.onmessage?.({
+        data: isBinary
+          ? bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+          : bytes.toString(),
+        isBinary,
+      });
+    });
+    socket.on("close", (code, reason) => wire.onclose?.(code, reason.toString()));
+    if (connections > 1) {
+      socket.on("close", () => {
+        retryClosed = true;
+      });
+      void createDaemonChannel(wire, keys, {
+        onmessage: (data) => legacyReceived.push(data),
+      }).catch(() => {});
+      return;
+    }
+    const channel = openDaemonSecureChannel(wire, {
+      daemonKeyPair: keys,
+      events: {
+        onmessage: (data) => {
+          if (typeof data !== "string" || JSON.parse(data).type !== "hello") return;
+          void channel.then((secure) =>
+            secure.send(
+              JSON.stringify({
+                type: "session",
+                message: {
+                  type: "status",
+                  payload: {
+                    status: "server_info",
+                    serverId: "srv_relayed",
+                    hostname: "relayed",
+                    version: "0.12.0",
+                  },
+                },
+              }),
+            ),
+          );
+        },
+      },
+    });
+    void channel.catch(() => {});
+  });
+  http.listen(0, "127.0.0.1");
+  await once(http, "listening");
+  cleanup.push(async () => {
+    for (const socket of ws.clients) socket.terminate();
+    await new Promise<void>((resolve) => ws.close(() => resolve()));
+    await new Promise<void>((resolve) => http.close(() => resolve()));
+  });
+  const address = http.address();
+  if (!address || typeof address === "string") throw new Error("Missing relay port");
+  const a = await daemon();
+  const { paseo } = await api(a);
+  await paseo.hosts.add({
+    connection: `relay://127.0.0.1:${address.port}/srv_relayed?key=${encodeURIComponent(exportPublicKey(keys.publicKey))}`,
+  });
+  await capabilityRetry(paseo);
+  await expect.poll(() => retryClosed, { timeout: 15000 }).toBe(true);
+  expect(legacyReceived).toEqual([]);
+});
+
 test("an unreachable saved target becomes online after its daemon starts without being added again", async () => {
   const reservation = createServer();
   reservation.listen(0, "127.0.0.1");
@@ -952,7 +1141,7 @@ test("source-key registration remains idempotent at directory capacity", async (
 });
 
 /** Real WebSocket proxy records the A–B physical wire without replacing either daemon. */
-async function hostWire(b: TestPaseoDaemon) {
+async function hostWire(b: TestPaseoDaemon, options: { legacyFlowControl?: boolean } = {}) {
   const http = createServer();
   const wss = new WebSocketServer({ server: http });
   const frames: { binary: boolean; bytes: Buffer; direction: "toB" | "fromB" }[] = [];
@@ -965,7 +1154,14 @@ async function hostWire(b: TestPaseoDaemon) {
       for (const send of pending.splice(0)) send();
     });
     downstream.on("message", (data, binary) => {
-      const bytes = Buffer.from(data as Buffer);
+      let bytes = Buffer.from(data as Buffer);
+      if (options.legacyFlowControl && !binary) {
+        const envelope = JSON.parse(bytes.toString());
+        if (envelope.message?.type === "hosts.link.open.request") {
+          delete envelope.message.flowControl;
+          bytes = Buffer.from(JSON.stringify(envelope));
+        }
+      }
       frames.push({ binary, bytes, direction: "toB" });
       const send = () => {
         if (upstream.readyState === 1) upstream.send(bytes, { binary });
@@ -1543,6 +1739,77 @@ test(
   },
 );
 
+test(
+  "a background caller's MCP and SDK children and workspaces on B are background unless it overrides",
+  { timeout: 30000 },
+  async () => {
+    const a = await daemon();
+    const b = await daemon();
+    const { paseo } = await api(a);
+    await paseo.hosts.add({ connection: `127.0.0.1:${b.port}`, label: "Fleet B" });
+    const directory = await online(paseo);
+    const workspace = await paseo.workspaces.create({
+      source: { kind: "directory", path: a.staticDir },
+    });
+    const parent = await workspace.agents.create({
+      config: { provider: "claude/claude-test" },
+      title: "Background parent",
+      background: true,
+    });
+    const mcp = new Client({ name: "background-delegation", version: "1" });
+    cleanup.push(() => mcp.close());
+    await mcp.connect(
+      new StreamableHTTPClientTransport(
+        new URL(`http://127.0.0.1:${a.port}/mcp/agents?callerAgentId=${parent.id}`),
+      ),
+    );
+    const call = async (name: string, args: Record<string, unknown>) => {
+      const response = await mcp.callTool({ name, arguments: args });
+      expect(response.isError, JSON.stringify(response)).not.toBe(true);
+      return z.record(z.string(), z.unknown()).parse(response.structuredContent);
+    };
+    const serverId = directory.hosts[0]!.serverId!;
+    const hidden = await call("create_workspace", {
+      serverId,
+      isolation: "local",
+      path: b.staticDir,
+      title: "Inherited workspace",
+    });
+    const helper = await call("create_agent", {
+      serverId,
+      workspaceId: hidden.workspaceId,
+      title: "Inherited helper",
+      provider: "claude/claude-test",
+      initialPrompt: "Summarize",
+    });
+    const visible = await call("create_agent", {
+      serverId,
+      workspaceId: hidden.workspaceId,
+      title: "Visible helper",
+      provider: "claude/claude-test",
+      initialPrompt: "Summarize",
+      background: false,
+    });
+
+    const bApi = await api(b);
+    const workspaces = await bApi.client.fetchWorkspaces({ includeBackground: true });
+    expect(workspaces.entries.find((entry) => entry.id === hidden.workspaceId)).toMatchObject({
+      background: true,
+    });
+    const snapshot = async (agentId: unknown) =>
+      (await bApi.paseo.agents.ref(String(agentId)).refresh())?.agent;
+    expect(await snapshot(helper.agentId)).toMatchObject({ background: true });
+    expect((await snapshot(visible.agentId))?.background).toBeUndefined();
+
+    const sdkChild = await bApi.paseo.workspaces.ref(String(hidden.workspaceId)).agents.create({
+      config: { provider: "claude/claude-test" },
+      title: "SDK helper",
+      parent,
+    });
+    expect(sdkChild.current()).toMatchObject({ background: true });
+  },
+);
+
 test(
   "remote agent reports, local CLI sends and automatic completion reach the same recipient",
   { timeout: 30000 },
@@ -2130,6 +2397,169 @@ test(
   },
 );
 
+test("a host channel waits for its downstream consumer without blocking sibling requests", async () => {
+  const b = await daemon();
+  const destination = await api(b);
+  const workspace = await destination.paseo.workspaces.create({
+    source: { kind: "directory", path: b.staticDir },
+  });
+  const agent = await workspace.agents.create({
+    config: { provider: "claude/claude-test", modeId: "full-access" },
+    title: "Flow-controlled history",
+  });
+  const text = "x".repeat(240 * 1024);
+  for (let index = 0; index < 50; index++)
+    await b.daemon.agentManager.appendTimelineItem(agent.id, { type: "user_message", text });
+
+  const channel = createHostChannelTransport(
+    destination.client,
+    b.daemon.getServerId()!,
+    "held-consumer",
+    null,
+    true,
+  )({ url: "ws://host-link/ws" });
+  const received = Promise.withResolvers<void>();
+  const forward = Promise.withResolvers<void>();
+  let binaryFrames = 0;
+  channel.onMessage((_data, binary) => {
+    if (!binary) return;
+    binaryFrames++;
+    received.resolve();
+    return forward.promise;
+  });
+  const consumer = new DaemonClient({
+    url: "ws://host-link/ws",
+    clientId: "held-consumer",
+    reconnect: { enabled: false },
+    transportFactory: () => channel,
+  });
+  const remote = createPaseoApi(consumer);
+  cleanup.push(async () => {
+    forward.resolve();
+    await remote.dispose();
+    await consumer.close();
+  });
+  await consumer.connect();
+  const history = remote.agents.ref(agent.id).timeline.refetch({ limit: 0 });
+  void history.catch(() => {}); // Cleanup can close the request after an earlier assertion fails.
+  await received.promise;
+  // A round trip on the same physical link must progress while this channel is held.
+  await destination.client.ping();
+  expect(binaryFrames).toBe(1);
+  forward.resolve();
+  const response = await history;
+  const messages = response.entries.flatMap((row) =>
+    row.item.type === "user_message" ? [row.item.text] : [],
+  );
+  expect(messages).toHaveLength(50);
+  expect(messages.every((message) => message === text)).toBe(true);
+  await consumer.ping();
+});
+
+test("small host-channel responses fill the window before earlier forwarding completes", async () => {
+  const b = await daemon();
+  const destination = await api(b);
+  const channel = createHostChannelTransport(
+    destination.client,
+    b.daemon.getServerId()!,
+    "concurrent-consumer",
+    null,
+    true,
+  )({ url: "ws://host-link/ws" });
+  const first = Promise.withResolvers<void>();
+  const forward = Promise.withResolvers<void>();
+  let responses = 0;
+  channel.onMessage((data, binary) => {
+    if (binary || JSON.parse(String(data)).message?.type !== "pong") return;
+    responses++;
+    first.resolve();
+    return forward.promise;
+  });
+  const consumer = new DaemonClient({
+    url: "ws://host-link/ws",
+    clientId: "concurrent-consumer",
+    reconnect: { enabled: false },
+    transportFactory: () => channel,
+  });
+  cleanup.push(async () => {
+    forward.resolve();
+    await consumer.close();
+  });
+  await consumer.connect();
+  const requests = Promise.all(Array.from({ length: 10 }, () => consumer.ping()));
+  void requests.catch(() => {});
+  await first.promise;
+  await destination.client.ping();
+  await destination.client.ping();
+  expect(responses).toBe(10);
+  forward.resolve();
+  await requests;
+});
+
+test("legacy host links receive no acknowledgment messages", async () => {
+  const b = await daemon();
+  const wire = await hostWire(b, { legacyFlowControl: true });
+  const origin = createHostClient(wire.connection, {
+    clientId: "legacy-flow-origin",
+    reconnect: { enabled: false },
+  });
+  cleanup.push(() => origin.close());
+  await origin.connect();
+  const consumer = new DaemonClient({
+    url: "ws://host-link/ws",
+    clientId: "legacy-flow-consumer",
+    reconnect: { enabled: false },
+    transportFactory: createHostChannelTransport(
+      origin,
+      b.daemon.getServerId()!,
+      "legacy",
+      null,
+      true,
+    ),
+  });
+  cleanup.push(() => consumer.close());
+  await consumer.connect();
+  await consumer.ping();
+  await origin.ping();
+  const operations = wire.frames
+    .filter((frame) => !frame.binary && frame.direction === "toB")
+    .map((frame) => JSON.parse(frame.bytes.toString()).message?.type);
+  expect(operations).toContain("hosts.link.open.request");
+  expect(operations).not.toContain("hosts.link.ack.request");
+});
+
+test("mixed asynchronous and synchronous receiver failures close only their host channel", async () => {
+  const b = await daemon();
+  const destination = await api(b);
+  const channel = createHostChannelTransport(
+    destination.client,
+    b.daemon.getServerId()!,
+    "failing-consumer",
+    null,
+    true,
+  )({ url: "ws://host-link/ws" });
+  const failed = Promise.withResolvers<unknown>();
+  channel.onError(failed.resolve);
+  channel.onMessage(async () => {
+    throw new Error("asynchronous receiver failure");
+  });
+  channel.onMessage(() => {
+    throw new Error("synchronous receiver failure");
+  });
+  const consumer = new DaemonClient({
+    url: "ws://host-link/ws",
+    clientId: "failing-consumer",
+    reconnect: { enabled: false },
+    transportFactory: () => channel,
+  });
+  cleanup.push(() => consumer.close());
+  const connecting = consumer.connect().catch((error: unknown) => error);
+  expect(await failed.promise).toBeInstanceOf(Error);
+  await connecting;
+  expect(consumer.isConnected).toBe(false);
+  await destination.client.ping();
+});
+
 test("a pre-write host budget rejection leaves sibling routes connected", async () => {
   const { HostTransportBudget } = await import("@getpaseo/client/node");
   const b = await daemon();
@@ -2168,3 +2598,74 @@ test("a pre-write host budget rejection leaves sibling routes connected", async
     true,
   ]);
 }, 30000);
+
+test.each([false, true])(
+  "remote prompt to a closed agent (archived=%s) reports its new turn instead of stale closure",
+  { timeout: 30000 },
+  async (archived) => {
+    const parentPrompts: string[] = [];
+    const started = Promise.withResolvers<void>();
+    const finish = Promise.withResolvers<void>();
+    const a = await daemon({
+      agentClients: createTestAgentClients({
+        onStartTurn: (prompt) => parentPrompts.push(String(prompt)),
+      }),
+    });
+    const b = await daemon({
+      agentClients: createTestAgentClients({
+        onStartTurn: () => started.resolve(),
+        beforeTurnComplete: () => finish.promise,
+      }),
+    });
+    cleanup.push(async () => finish.resolve());
+    const origin = await api(a);
+    const destination = await api(b);
+    await origin.paseo.hosts.add({ connection: `127.0.0.1:${b.port}` });
+    const remoteId = (await online(origin.paseo)).hosts[0]!.serverId!;
+    const workspace = await origin.paseo.workspaces.create({
+      source: { kind: "directory", path: a.staticDir },
+    });
+    const remoteWorkspace = await destination.paseo.workspaces.create({
+      source: { kind: "directory", path: b.staticDir },
+    });
+    const parent = await workspace.agents.create({
+      config: { provider: "claude/claude-test", modeId: "full-access" },
+      title: "Closed target caller",
+    });
+    const child = await remoteWorkspace.agents.create({
+      config: { provider: "claude/claude-test", modeId: "full-access" },
+      title: "Closed target",
+    });
+    if (archived) await child.archive();
+    else await b.daemon.agentManager.closeAgent(child.id);
+    expect((await destination.client.fetchAgent(child.id))?.agent.status).toBe("closed");
+    const mcp = new Client({ name: "closed-target-caller", version: "1" });
+    await mcp.connect(
+      new StreamableHTTPClientTransport(
+        new URL(`http://127.0.0.1:${a.port}/mcp/agents?callerAgentId=${parent.id}`),
+      ),
+    );
+    cleanup.push(() => mcp.close());
+    const result = await mcp.callTool({
+      name: "send_agent_prompt",
+      arguments: { serverId: remoteId, agentId: child.id, prompt: "Finish the new task" },
+    });
+    expect(result.isError).not.toBe(true);
+    expect(result.structuredContent).toMatchObject({ deliveryStatus: "queued", status: "closed" });
+    await started.promise;
+    expect(parentPrompts).toEqual([]);
+    finish.resolve();
+    await expect.poll(() => parentPrompts, { timeout: 10000 }).toHaveLength(1);
+    expect(parentPrompts[0]).toContain('event="finished"');
+    expect(parentPrompts[0]).not.toContain('event="closed"');
+    expect((await destination.client.fetchAgent(child.id))?.agent).toMatchObject({
+      status: "idle",
+      archivedAt: null,
+    });
+    await expect
+      .poll(async () =>
+        JSON.parse(await readFile(join(a.paseoHome, "finish-subscriptions.json"), "utf8")),
+      )
+      .toEqual([]);
+  },
+);
diff --git a/packages/server/src/server/connected-hosts/index.ts b/packages/server/src/server/connected-hosts/index.ts
index 15b1e16b97..526910f5cc 100644
--- a/packages/server/src/server/connected-hosts/index.ts
+++ b/packages/server/src/server/connected-hosts/index.ts
@@ -7,10 +7,12 @@ import { z } from "zod";
 import {
   createHostClient,
   createHostChannelTransport,
+  createHostTransportFactory,
   parseHostTarget,
   HostTransportBudget,
 } from "@getpaseo/client/node";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { DaemonTransportFactory } from "@getpaseo/client/internal/daemon-client-transport-types";
 import {
   HostSummarySchema,
   HostAddSchema,
@@ -235,23 +237,30 @@ export class ConnectedHosts {
       if (route.registrationId === id)
         route.close(code, "Host access was disabled, replaced or removed");
   }
-  private start(row: Saved): void {
+  private start(
+    row: Saved,
+    resume?: { failures: number; transports: DaemonTransportFactory },
+  ): void {
     if (!row.enabled || this.closed) return;
-    let stopped = false;
-    const client = createHostClient(
-      row.connection,
-      {
-        clientId: `host-link-${this.self.serverId}-${row.registrationId}`,
-        connectTimeoutMs: 10000,
+    const transports =
+      resume?.transports ??
+      createHostTransportFactory(row.connection, this.budget, {
         webSocketAgent: webSocketProxyAgent,
-      },
-      this.budget,
-    );
+      });
+    let stopped = false;
+    let attempts = resume?.failures ?? 0;
+    let retry: ReturnType<typeof setTimeout> | undefined;
+    const client = createHostClient(row.connection, {
+      clientId: `host-link-${this.self.serverId}-${row.registrationId}`,
+      connectTimeoutMs: 10000,
+      transportFactory: transports,
+    });
     const live: Live = {
       client,
       accepted: false,
       stop: () => {
         stopped = true;
+        clearTimeout(retry);
         void client.close();
       },
     };
@@ -285,7 +294,7 @@ export class ConnectedHosts {
         if (info.features?.connectedHosts !== true || info.features?.hostMultiplexing !== true)
           throw new HostError(
             "unsupported_capability",
-            "Update the destination daemon to use connected hosts.",
+            "Update the destination daemon to use connected hosts; retrying automatically.",
           );
         // Pin and persist under the same writer as management to prevent discovery races.
         await this.mutate(async () => {
@@ -304,16 +313,22 @@ export class ConnectedHosts {
           if (stopped || client.getLastServerInfoMessage() !== info || !client.isConnected) return;
           Object.assign(row, next);
           live.accepted = true;
+          attempts = 0;
           this.changed();
         });
       } catch (error) {
         if (stopped) return;
-        row.status = "error";
         row.error = connectionFailure(error, client.authFailureReason !== null) ?? {
           code: "host_offline",
           message: "Host connection failed",
         };
-        row.nextRetryAt = null;
+        if (terminalFailures.has(row.error.code)) {
+          row.status = "error";
+          row.nextRetryAt = null;
+        } else {
+          stopped = true;
+          retry = this.scheduleAcceptanceRetry(row, attempts, transports);
+        }
         this.changed();
         await client.close();
       }
@@ -329,18 +344,17 @@ export class ConnectedHosts {
         if (route.registrationId === row.registrationId) route.close();
       row.status = state.status === "connecting" ? "connecting" : "offline";
       row.nextRetryAt = state.status === "disconnected" ? (state.nextRetryAt ?? null) : null;
-      row.error =
-        state.status === "disconnected"
-          ? (connectionFailure(
-              Object.assign(new Error("Check the SSH configuration and daemon credentials"), {
-                code: state.failureCode,
-              }),
-              client.authFailureReason !== null,
-            ) ?? {
-              code: "host_offline",
-              message: "Cannot reach host. Check the connection; retrying automatically.",
-            })
-          : null;
+      if (state.status === "disconnected")
+        row.error = connectionFailure(
+          Object.assign(new Error("Check the SSH configuration and daemon credentials"), {
+            code: state.failureCode,
+          }),
+          client.authFailureReason !== null,
+        ) ?? {
+          code: "host_offline",
+          message: "Cannot reach host. Check the connection; retrying automatically.",
+        };
+      else if (row.error?.code !== "unsupported_capability") row.error = null;
       if (row.error?.code === "authentication_failed") {
         row.status = "error";
         row.nextRetryAt = null;
@@ -351,6 +365,18 @@ export class ConnectedHosts {
     });
     void client.connect().catch(() => {});
   }
+  private scheduleAcceptanceRetry(
+    row: Saved,
+    failures: number,
+    transports: DaemonTransportFactory,
+  ): ReturnType<typeof setTimeout> {
+    const delay = acceptanceRetryDelayMs(failures);
+    row.status = "offline";
+    row.nextRetryAt = new Date(Date.now() + delay).toISOString();
+    const retry = setTimeout(() => this.start(row, { failures: failures + 1, transports }), delay);
+    retry.unref();
+    return retry;
+  }
   async openRoute(input: {
     serverId: string;
     scopeId: string;
@@ -358,7 +384,7 @@ export class ConnectedHosts {
     originSessionId: string;
     permissions: readonly DaemonPermission[];
     signal: AbortSignal;
-    frame(data: string | Uint8Array): void;
+    frame(data: string | Uint8Array): void | Promise<void>;
     ended(code: string, message: string): void;
   }): Promise<{ send(data: string | Uint8Array): void; close(): void }> {
     await this.ready;
@@ -473,7 +499,7 @@ export class ConnectedHosts {
           return;
         }
       }
-      input.frame(binary ? (data as Uint8Array) : String(data));
+      return input.frame(binary ? (data as Uint8Array) : String(data));
     });
     await ready;
     if (closed) throw new HostError("host_offline", "Host closed during connection");
@@ -531,6 +557,20 @@ export class ConnectedHosts {
   }
 }
 
+const ACCEPTANCE_RETRY_BASE_MS = 1500;
+const ACCEPTANCE_RETRY_MAX_MS = 30_000;
+
+function acceptanceRetryDelayMs(failures: number): number {
+  return Math.min(ACCEPTANCE_RETRY_BASE_MS * 2 ** failures, ACCEPTANCE_RETRY_MAX_MS);
+}
+
+const terminalFailures = new Set([
+  "server_id_mismatch",
+  "self_host",
+  "duplicate_host",
+  "authentication_failed",
+]);
+
 function connectionFailure(error: unknown, authenticationFailed: boolean): HostSummary["error"] {
   if (error instanceof HostError) return { code: error.code, message: error.message };
   if (error instanceof Error && "code" in error && error.code === "authentication_failed")
diff --git a/packages/server/src/server/connected-hosts/link.test.ts b/packages/server/src/server/connected-hosts/link.test.ts
new file mode 100644
index 0000000000..04cecaae3e
--- /dev/null
+++ b/packages/server/src/server/connected-hosts/link.test.ts
@@ -0,0 +1,118 @@
+import { afterEach, expect, test } from "vitest";
+import { DaemonLinkEndpoint, type VirtualHostSocket } from "./index.js";
+import { SessionDelivery } from "../session/owned-subscriptions/index.js";
+import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+
+const cleanup: (() => Promise<void>)[] = [];
+afterEach(async () => {
+  for (const close of cleanup.splice(0).toReversed()) await close();
+});
+
+async function link() {
+  const source = {};
+  const messages: SessionOutboundMessage[] = [];
+  const sockets: VirtualHostSocket[] = [];
+  const delivery = new SessionDelivery((_source, message) => {
+    messages.push(message);
+  });
+  delivery.attach(source, true);
+  const endpoint = new DaemonLinkEndpoint({
+    identity: "physical",
+    permissions: () => ["daemon.read"],
+    routed: () => false,
+    bufferedAmount: () => 0,
+    delivery,
+    admit: async (socket) => {
+      sockets.push(socket);
+    },
+  });
+  cleanup.push(async () => {
+    endpoint.close();
+    await delivery.close();
+  });
+  const dispatch = (message: SessionInboundMessage) =>
+    delivery.request(source, message, () => endpoint.dispatch(message));
+  const open = async (channelId: string, flowControl = true) => {
+    await dispatch({
+      type: "hosts.link.open.request",
+      requestId: channelId,
+      channelId,
+      flowControl,
+    });
+    const response = messages.find(
+      (message) =>
+        message.type === "hosts.link.open.response" && message.payload.requestId === channelId,
+    );
+    expect(response).toMatchObject({
+      type: "hosts.link.open.response",
+      payload: flowControl ? { flowControl: true } : {},
+    });
+    if (response?.type !== "hosts.link.open.response") throw new Error("Missing opened channel");
+    return { socket: sockets.at(-1)!, id: response.payload.routeId };
+  };
+  const ack = (routeId: string, sequence: number) =>
+    dispatch({ type: "hosts.link.ack.request", routeId, sequence });
+  const frames = () =>
+    messages
+      .filter((message) => message.type === "hosts.route.frame")
+      .map((message) => message.payload.data);
+  return { open, ack, frames };
+}
+
+test("a channel waits for forwarding acknowledgments while its sibling keeps sending", async () => {
+  const host = await link();
+  const slow = await host.open("slow");
+  const sibling = await host.open("sibling");
+  let completed = false;
+  const first = slow.socket.send("first").then(() => {
+    completed = true;
+    return undefined;
+  });
+  let secondCompleted = false;
+  const second = slow.socket.send("second").then(() => {
+    secondCompleted = true;
+    return undefined;
+  });
+  await expect.poll(host.frames).toEqual(["first", "second"]);
+  expect(completed).toBe(false);
+  const independent = sibling.socket.send("independent");
+  await expect.poll(host.frames).toEqual(["first", "second", "independent"]);
+  await host.ack(sibling.id, 1);
+  await independent;
+  await host.ack(slow.id, 1);
+  await first;
+  await expect.poll(host.frames).toEqual(["first", "second", "independent"]);
+  await host.ack(slow.id, 1); // A duplicate acknowledgment cannot release the next frame.
+  expect(completed).toBe(true);
+  expect(secondCompleted).toBe(false);
+  await host.ack(slow.id, 2);
+  await second;
+});
+
+test("closing a blocked channel rejects its pending writes and leaves a sibling usable", async () => {
+  const host = await link();
+  const slow = await host.open("slow");
+  const sibling = await host.open("sibling", false);
+  const first = slow.socket.send("first");
+  const second = slow.socket.send("second");
+  const results = Promise.allSettled([first, second]);
+  await expect.poll(host.frames).toEqual(["first", "second"]);
+  slow.socket.close();
+  expect((await results).map((result) => result.status)).toEqual(["rejected", "rejected"]);
+  await sibling.socket.send("legacy sibling");
+  expect(host.frames()).toEqual(["first", "second", "legacy sibling"]);
+});
+
+test("an unpaced producer exhausting its acknowledgment window closes only its channel", async () => {
+  const host = await link();
+  const slow = await host.open("slow");
+  const sibling = await host.open("sibling", false);
+  const writes: Promise<unknown>[] = [];
+  // A producer ignoring send completion must remain bounded even for tiny messages.
+  for (let index = 0; index < 5000; index++)
+    writes.push(slow.socket.send("x").catch((error: unknown) => error));
+  await Promise.all(writes);
+  expect(slow.socket.readyState).toBe(3);
+  await sibling.socket.send("still connected");
+  expect(host.frames().at(-1)).toBe("still connected");
+});
diff --git a/packages/server/src/server/connected-hosts/link.ts b/packages/server/src/server/connected-hosts/link.ts
index a18c89aeb0..7f917ba2d6 100644
--- a/packages/server/src/server/connected-hosts/link.ts
+++ b/packages/server/src/server/connected-hosts/link.ts
@@ -1,3 +1,4 @@
+import { HostChannelFlowControl, HostChannelOutputLimitError } from "./flow-control.js";
 import type { SessionDelivery } from "../session/owned-subscriptions/index.js";
 import { EventEmitter } from "node:events";
 import { createHash } from "node:crypto";
@@ -15,6 +16,7 @@ import type {
 /** A logical socket has no network resources or authority of its own. */
 export class VirtualHostSocket extends EventEmitter {
   readonly maxFrameBytes = MAX_HOST_CHANNEL_FRAME_BYTES;
+  readonly supportsConcurrentWrites = true;
   readyState = 1;
   constructor(
     private readonly output: (data: string | Uint8Array) => Promise<void>,
@@ -61,7 +63,11 @@ export class VirtualHostSocket extends EventEmitter {
 
 /** One authenticated physical source owns all its channels and their admission ceiling. */
 export class DaemonLinkEndpoint {
-  private readonly channels = new Map<string, { scopeId: string; socket: VirtualHostSocket }>();
+  private readonly channels = new Map<
+    string,
+    { scopeId: string; socket: VirtualHostSocket; flowControl?: HostChannelFlowControl }
+  >();
+  private pendingOutputBytes = 0;
   private closed = false;
   constructor(
     private readonly parent: {
@@ -76,6 +82,7 @@ export class DaemonLinkEndpoint {
   handles(message: SessionInboundMessage): boolean {
     return (
       message.type === "hosts.link.open.request" ||
+      message.type === "hosts.link.ack.request" ||
       (message.type === "hosts.route.frame.request" && this.channels.has(message.routeId)) ||
       (message.type === "hosts.route.close.request" &&
         ((!!message.routeId && this.channels.has(message.routeId)) ||
@@ -83,6 +90,10 @@ export class DaemonLinkEndpoint {
     );
   }
   async dispatch(message: SessionInboundMessage): Promise<void> {
+    if (message.type === "hosts.link.ack.request") {
+      this.channels.get(message.routeId)?.flowControl?.acknowledge(message.sequence);
+      return;
+    }
     if (message.type === "hosts.link.open.request") {
       const error = (code: string, text: string) =>
         this.parent.delivery.reply({
@@ -103,8 +114,19 @@ export class DaemonLinkEndpoint {
         return;
       }
       let socket: VirtualHostSocket;
+      const flowControl = message.flowControl
+        ? new HostChannelFlowControl((bytes) => {
+            if (this.pendingOutputBytes + bytes > 256 * 1024 * 1024)
+              throw new HostChannelOutputLimitError();
+            this.pendingOutputBytes += bytes;
+            return () => {
+              this.pendingOutputBytes -= bytes;
+            };
+          })
+        : undefined;
       const owner = this.parent.delivery.begin("host-link", undefined, () => {
         this.channels.delete(owner.id);
+        flowControl?.close();
         socket?.close();
       });
       const id = owner.id;
@@ -130,15 +152,25 @@ export class DaemonLinkEndpoint {
             throw new Error("Host channel output limit reached");
           }
           try {
-            if (output) await owner.emitAndWait(output);
-            else await owner.emitBinaryAndWait(frame!);
+            const write = async () => {
+              if (output) await owner.emitAndWait(output);
+              else await owner.emitBinaryAndWait(frame!);
+            };
+            if (flowControl) await flowControl.send(bytes, write);
+            else await write();
           } catch (failure) {
-            socket.close();
+            socket.close(
+              failure instanceof HostChannelOutputLimitError ? 1009 : 1000,
+              failure instanceof HostChannelOutputLimitError
+                ? failure.message
+                : "Host channel closed",
+            );
             throw failure;
           }
         },
         (code, reason) => {
           this.channels.delete(id);
+          flowControl?.close();
           let failure = "host_offline";
           if (code === 1009) failure = "resource_limit";
           if (code === 1008) failure = "permission_denied";
@@ -167,7 +199,7 @@ export class DaemonLinkEndpoint {
           });
         },
       );
-      this.channels.set(id, { scopeId: message.channelId, socket });
+      this.channels.set(id, { scopeId: message.channelId, socket, flowControl });
       try {
         await this.parent.admit(socket, ceiling);
         if (this.closed || socket.readyState !== 1) {
@@ -176,7 +208,11 @@ export class DaemonLinkEndpoint {
         }
         this.parent.delivery.reply({
           type: "hosts.link.open.response",
-          payload: { requestId: message.requestId, routeId: id },
+          payload: {
+            requestId: message.requestId,
+            routeId: id,
+            ...(flowControl ? { flowControl: true } : {}),
+          },
         });
       } catch {
         socket.close();
diff --git a/packages/server/src/server/connected-hosts/session.test.ts b/packages/server/src/server/connected-hosts/session.test.ts
new file mode 100644
index 0000000000..bbf019f124
--- /dev/null
+++ b/packages/server/src/server/connected-hosts/session.test.ts
@@ -0,0 +1,70 @@
+import { expect, test } from "vitest";
+import { ConnectedHostSession, type ConnectedHosts } from "./index.js";
+import { SessionDelivery } from "../session/owned-subscriptions/index.js";
+
+// The upstream host and final writer are independently controlled transport peers.
+test.each(["text", "binary"] as const)(
+  "routed %s completion waits for the final writer",
+  async (kind) => {
+    const source = {};
+    const writing = Promise.withResolvers<void>();
+    const drain = Promise.withResolvers<void>();
+    const write = () => {
+      writing.resolve();
+      return drain.promise;
+    };
+    const delivery = new SessionDelivery((_source, message) => {
+      if (message.type === "hosts.route.frame") return write();
+    }, write);
+    delivery.attach(source, true);
+    let receive!: Parameters<ConnectedHosts["openRoute"]>[0]["frame"];
+    const unexpected = (): never => {
+      throw new Error("Unexpected host operation");
+    };
+    const session = new ConnectedHostSession(
+      {
+        list: unexpected,
+        observe: unexpected,
+        add: unexpected,
+        update: unexpected,
+        remove: unexpected,
+        openRoute: async (input) => {
+          receive = input.frame;
+          return { send: () => {}, close: () => {} };
+        },
+      },
+      delivery,
+      { sourceId: "owner", manageSources: false },
+      () => [],
+      () => {},
+      () => false,
+      "origin",
+      () => 0,
+    );
+    const request = {
+      type: "hosts.route.open.request" as const,
+      requestId: "open",
+      serverId: "remote",
+      scopeId: "scope",
+    };
+    await delivery.request(source, request, () => session.dispatch(request)!);
+    let completed = false;
+    const forwarded = Promise.resolve(
+      receive(kind === "text" ? "payload" : new Uint8Array([1, 2])),
+    ).then(() => {
+      completed = true;
+      return undefined;
+    });
+    try {
+      await writing.promise;
+      expect(completed).toBe(false);
+      drain.resolve();
+      await forwarded;
+      expect(completed).toBe(true);
+    } finally {
+      drain.resolve();
+      await forwarded;
+      await delivery.close();
+    }
+  },
+);
diff --git a/packages/server/src/server/connected-hosts/session.ts b/packages/server/src/server/connected-hosts/session.ts
index 811daaa723..00d9f10a24 100644
--- a/packages/server/src/server/connected-hosts/session.ts
+++ b/packages/server/src/server/connected-hosts/session.ts
@@ -23,7 +23,10 @@ interface SessionRoute {
 export class ConnectedHostSession {
   private readonly routes = new Map<string, SessionRoute>();
   constructor(
-    private readonly hosts: ConnectedHosts,
+    private readonly hosts: Pick<
+      ConnectedHosts,
+      "list" | "observe" | "add" | "update" | "remove" | "openRoute"
+    >,
     private readonly delivery: SessionDelivery,
     private readonly actor: HostActor,
     private readonly permissions: () => DaemonPermission[],
@@ -206,7 +209,7 @@ export class ConnectedHostSession {
         originSessionId: this.originSessionId,
         permissions: this.permissions(),
         signal: owner.signal,
-        frame: (data) => {
+        frame: async (data) => {
           const output: SessionOutboundMessage | null =
             typeof data === "string"
               ? {
@@ -223,8 +226,8 @@ export class ConnectedHostSession {
             fail("resource_limit", "The receiving client cannot keep up with host output");
             return;
           }
-          if (output) owner.emit(output);
-          else owner.emitBinary(binary!);
+          if (output) await owner.emitAndWait(output);
+          else await owner.emitBinaryAndWait(binary!);
         },
         ended: fail,
       });
diff --git a/packages/server/src/server/daemon-client.e2e.test.ts b/packages/server/src/server/daemon-client.e2e.test.ts
index a442dfe6a9..ad27e8f95c 100644
--- a/packages/server/src/server/daemon-client.e2e.test.ts
+++ b/packages/server/src/server/daemon-client.e2e.test.ts
@@ -18,6 +18,7 @@ import { getFullAccessConfig, getAskModeConfig } from "./daemon-e2e/agent-config
 import { parsePcm16MonoWav, wordSimilarity } from "./test-utils/dictation-e2e.js";
 import type {
   AgentClient,
+  AgentLaunchContext,
   AgentPersistenceHandle,
   AgentRunResult,
   AgentSession,
@@ -180,6 +181,56 @@ test("DaemonClient uploads file bytes to daemon temp storage", async () => {
   }
 });
 
+test("agent.config.apply sets an option that has no control and the next snapshot reports it", async () => {
+  const clients = createTestAgentClients();
+  const codex = clients.codex as AgentClient;
+  const applied: unknown[] = [];
+  // Records what reaches the provider session; behavior is the fake client's.
+  const recordingCodex: AgentClient = Object.create(codex, {
+    createSession: {
+      value: async (...args: Parameters<AgentClient["createSession"]>) => {
+        const session = await codex.createSession(...args);
+        const apply = session.applyOptions?.bind(session);
+        session.applyOptions = async (options) => {
+          applied.push(options);
+          await apply?.(options);
+        };
+        return session;
+      },
+    },
+  });
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { ...clients, codex: recordingCodex },
+  });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.1.82",
+  });
+
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const agent = await client.createAgent({
+      provider: "codex",
+      cwd: tmpCwd(),
+      title: "Options agent",
+      modeId: "full-access",
+      model: "gpt-5.4-mini",
+    });
+    expect(agent.options?.sandbox_mode).toBeUndefined();
+
+    await client.applyAgentConfig(agent.id, { options: { sandbox_mode: "read-only" } });
+
+    expect(applied).toEqual([expect.objectContaining({ sandbox_mode: "read-only" })]);
+    const next = await client.fetchAgent(agent.id);
+    expect(next?.agent.options).toMatchObject({ sandbox_mode: "read-only" });
+    expect(next?.agent.controls?.map((control) => control.key)).not.toContain("sandbox_mode");
+  } finally {
+    await client.close();
+    await daemon.close();
+  }
+});
+
 test("createAgent with background initialPrompt returns a running snapshot before turn completion", async () => {
   const daemon = await createTestPaseoDaemon();
   const client = new DaemonClient({
@@ -324,6 +375,7 @@ class RecordingMcpResumeClient implements AgentClient {
   readonly provider = "codex" as const;
   readonly capabilities;
   readonly resumeOverrides: Array<Partial<AgentSessionConfig> | undefined> = [];
+  readonly resumeLaunchContexts: Array<AgentLaunchContext | undefined> = [];
   private readonly inner = createTestAgentClients({ supportsMcpServers: true }).codex;
 
   constructor() {
@@ -341,8 +393,10 @@ class RecordingMcpResumeClient implements AgentClient {
   resumeSession(
     handle: AgentPersistenceHandle,
     overrides?: Partial<AgentSessionConfig>,
+    launchContext?: AgentLaunchContext,
   ): Promise<AgentSession> {
     this.resumeOverrides.push(overrides);
+    this.resumeLaunchContexts.push(launchContext);
     return this.inner.resumeSession(handle, overrides);
   }
 
@@ -402,7 +456,7 @@ class RejectingMcpResumeClient implements AgentClient {
   }
 }
 
-test("createAgent fails when the initial turn cannot start", async () => {
+test("createAgent preserves the error snapshot when the initial turn cannot start", async () => {
   const testAgent = new StubAgentClient({
     sessionId: "start-turn-failure-session",
     supportsStreaming: false,
@@ -421,16 +475,18 @@ test("createAgent fails when the initial turn cannot start", async () => {
     await client.connect();
     await client.fetchAgents({ subscribe: {} });
 
-    await expect(
-      client.createAgent({
-        provider: "codex",
-        cwd: tmpCwd(),
-        title: "Start failure agent",
-        modeId: "full-access",
-        model: "gpt-5.4-mini",
-        initialPrompt: "Run exactly: sleep 30",
-      }),
-    ).rejects.toThrow("Initial turn failed to start");
+    const created = await client.createAgent({
+      provider: "codex",
+      cwd: tmpCwd(),
+      title: "Start failure agent",
+      modeId: "full-access",
+      model: "gpt-5.4-mini",
+      initialPrompt: "Run exactly: sleep 30",
+    });
+    expect(created.status).toBe("error");
+    expect(created.lastError).toBe("Initial turn failed to start");
+    const fetched = await client.fetchAgent({ agentId: created.id });
+    expect(fetched?.agent.lastError).toBe("Initial turn failed to start");
   } finally {
     await client.close();
     await daemon.close();
@@ -1034,6 +1090,38 @@ test("resume_agent rehydrates the newest private MCP config from a redacted pers
   }
 });
 
+test("resume_agent keeps the workspace of the agent it matches", async () => {
+  const cwd = tmpCwd();
+  const provider = new RecordingMcpResumeClient();
+  const localCtx = await createDaemonTestContext({
+    agentClients: { codex: provider },
+  });
+
+  try {
+    const opened = await localCtx.client.openProject(cwd);
+    if (!opened.workspace) {
+      throw new Error(opened.error ?? "Workspace did not open");
+    }
+    const workspaceId = opened.workspace.id;
+    const created = await localCtx.client.createAgent({
+      config: { provider: "codex", cwd },
+      workspaceId,
+    });
+    if (!created.persistence) {
+      throw new Error("Expected a persistence handle");
+    }
+
+    await localCtx.client.archiveAgent(created.id);
+    const resumed = await localCtx.client.resumeAgent(created.persistence);
+
+    expect(provider.resumeLaunchContexts[0]?.env?.PASEO_WORKSPACE_ID).toBe(workspaceId);
+    expect(resumed.workspaceId).toBe(workspaceId);
+  } finally {
+    await localCtx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
 test("resume_agent restores archive state when an MCP-capable provider returns an unsupported session", async () => {
   const cwd = tmpCwd();
   const provider = new RejectingMcpResumeClient();
@@ -1369,27 +1457,6 @@ test("creates agent and exercises lifecycle", async () => {
   });
 
   const createRequestId = `create-${Date.now()}`;
-  const createdStatusPromise = waitForSignal(15000, (resolve) => {
-    const unsubscribe = ctx.client.on("status", (message) => {
-      if (message.type !== "status") {
-        return;
-      }
-      const payload = message.payload as {
-        status?: string;
-        agentId?: string;
-        requestId?: string;
-      };
-      if (payload.status !== "agent_created") {
-        return;
-      }
-      if (payload.requestId !== createRequestId) {
-        return;
-      }
-      resolve(message);
-    });
-    return unsubscribe;
-  });
-
   const agent = await ctx.client.createAgent({
     ...getFullAccessConfig("codex"),
     cwd,
@@ -1404,30 +1471,8 @@ test("creates agent and exercises lifecycle", async () => {
 
   const agentUpdate = await agentUpdatePromise;
   expect(agentUpdate.payload.agent.id).toBe(agent.id);
-  const createdStatus = await createdStatusPromise;
-  expect((createdStatus.payload as { agentId?: string }).agentId).toBe(agent.id);
 
   const failRequestId = `fail-${Date.now()}`;
-  const failedStatusPromise = waitForSignal(15000, (resolve) => {
-    const unsubscribe = ctx.client.on("status", (message) => {
-      if (message.type !== "status") {
-        return;
-      }
-      const payload = message.payload as {
-        status?: string;
-        requestId?: string;
-      };
-      if (payload.status !== "agent_create_failed") {
-        return;
-      }
-      if (payload.requestId !== failRequestId) {
-        return;
-      }
-      resolve(message);
-    });
-    return unsubscribe;
-  });
-
   await expect(
     ctx.client.createAgent({
       ...getFullAccessConfig("codex"),
@@ -1436,7 +1481,6 @@ test("creates agent and exercises lifecycle", async () => {
       requestId: failRequestId,
     }),
   ).rejects.toThrow("Working directory does not exist");
-  await failedStatusPromise;
 
   let sawRefresh = false;
   const unsubscribe = ctx.client.subscribe((event) => {
@@ -1615,6 +1659,11 @@ test("creates agent and exercises lifecycle", async () => {
 }, 300000);
 
 test("handles permission flow", async () => {
+  const permissionEvents = ctx.client.observeEvents([
+    "agent_permission_request",
+    "agent_permission_resolved",
+  ]);
+  await permissionEvents.ready;
   const cwd = tmpCwd();
   const filePath = path.join(cwd, "permission.txt");
 
@@ -1683,6 +1732,7 @@ test("handles permission flow", async () => {
     // Prevent unhandled rejections if the test fails before promises resolve.
     await permissionRequestPromise.catch(() => {});
     await permissionResolvedPromise.catch(() => {});
+    await permissionEvents.release();
     await ctx.client.deleteAgent(agent.id);
     rmSync(cwd, { recursive: true, force: true });
   }
diff --git a/packages/server/src/server/daemon-config-store.test.ts b/packages/server/src/server/daemon-config-store.test.ts
index d9b2e94181..0478a145c4 100644
--- a/packages/server/src/server/daemon-config-store.test.ts
+++ b/packages/server/src/server/daemon-config-store.test.ts
@@ -3,7 +3,11 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, test } from "vitest";
 
-import { DaemonConfigStore, applyMutableProviderConfigToOverrides } from "./daemon-config-store.js";
+import {
+  DaemonConfigStore,
+  applyMutableProviderConfigToOverrides,
+  toWireDaemonConfig,
+} from "./daemon-config-store.js";
 import { loadConfig } from "./config.js";
 import { loadPersistedConfig } from "./persisted-config.js";
 import { readSpeechSettings } from "./speech/speech-settings.js";
@@ -196,13 +200,326 @@ describe("DaemonConfigStore", () => {
         model: "claude-opus-5",
         modeId: "plan",
         thinkingOptionId: "think-hard",
-        featureValues: { webSearch: true },
+        options: { webSearch: true },
         notes: "Use for components, layout and design tokens.",
       },
     ]);
     expect(store.get().agentProfiles).toHaveLength(1);
   });
 
+  test("a profile written with featureValues is stored as options, and the config API answers with both", async () => {
+    const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
+    tempDirs.push(paseoHome);
+    const store = new DaemonConfigStore(paseoHome, {
+      relay: { enabled: false },
+      mcp: { injectIntoAgents: false },
+      browserTools: { enabled: false },
+      providers: {},
+      metadataGeneration: { providers: [] },
+      autoArchiveAfterMerge: false,
+      enableTerminalAgentHooks: false,
+      appendSystemPrompt: "",
+    });
+    // The unchanged app sends back the `options` it read plus the `featureValues` it edited.
+    await store.patch({
+      agentProfiles: [
+        {
+          id: "p",
+          name: "P",
+          provider: "claude",
+          options: { fast_mode: false },
+          featureValues: { fast_mode: true },
+        },
+      ],
+    });
+
+    expect(loadPersistedConfig(paseoHome).daemon?.agentProfiles).toEqual([
+      { id: "p", name: "P", provider: "claude", options: { fast_mode: true } },
+    ]);
+    expect(store.get().agentProfiles).toEqual([
+      { id: "p", name: "P", provider: "claude", options: { fast_mode: true } },
+    ]);
+    expect(toWireDaemonConfig(store.get()).agentProfiles).toEqual([
+      {
+        id: "p",
+        name: "P",
+        provider: "claude",
+        options: { fast_mode: true },
+        featureValues: { fast_mode: true },
+      },
+    ]);
+  });
+
+  function storeWithProfile(): { store: DaemonConfigStore; paseoHome: string } {
+    const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
+    tempDirs.push(paseoHome);
+    const store = new DaemonConfigStore(paseoHome, {
+      relay: { enabled: false },
+      mcp: { injectIntoAgents: false },
+      browserTools: { enabled: false },
+      providers: {},
+      metadataGeneration: { providers: [] },
+      autoArchiveAfterMerge: false,
+      enableTerminalAgentHooks: false,
+      appendSystemPrompt: "",
+      agentProfiles: [
+        {
+          id: "p",
+          name: "P",
+          provider: "codex",
+          options: { sandbox_mode: "read-only", plan_mode: false },
+        },
+      ],
+    });
+    return { store, paseoHome };
+  }
+
+  test("a profile written with empty options, as the form sends it once the last one is removed, keeps none", async () => {
+    const { store, paseoHome } = storeWithProfile();
+
+    await store.patch({
+      agentProfiles: [{ id: "p", name: "P", provider: "codex", options: {} }],
+    });
+
+    expect(store.get().agentProfiles).toEqual([{ id: "p", name: "P", provider: "codex" }]);
+    expect(loadPersistedConfig(paseoHome).daemon?.agentProfiles).toEqual([
+      { id: "p", name: "P", provider: "codex" },
+    ]);
+  });
+
+  describe("a profile edited by the unchanged app", () => {
+    test("keeps the options its form never shows when it changes a control", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({
+        agentProfiles: [
+          { id: "p", name: "Renamed", provider: "codex", featureValues: { plan_mode: true } },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        {
+          id: "p",
+          name: "Renamed",
+          provider: "codex",
+          options: { sandbox_mode: "read-only", plan_mode: true },
+        },
+      ]);
+    });
+
+    test("keeps every option when it sends no featureValues at all", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({ agentProfiles: [{ id: "p", name: "Renamed", provider: "codex" }] });
+
+      expect(store.get().agentProfiles).toEqual([
+        {
+          id: "p",
+          name: "Renamed",
+          provider: "codex",
+          options: { sandbox_mode: "read-only", plan_mode: false },
+        },
+      ]);
+    });
+
+    test("starts from no options when it moves the profile to another provider", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({
+        agentProfiles: [
+          { id: "p", name: "P", provider: "claude", featureValues: { fast_mode: true } },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        { id: "p", name: "P", provider: "claude", options: { fast_mode: true } },
+      ]);
+    });
+
+    test("drops the old provider's options when it moves the profile with no featureValues", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({ agentProfiles: [{ id: "p", name: "P", provider: "claude" }] });
+
+      expect(store.get().agentProfiles).toEqual([{ id: "p", name: "P", provider: "claude" }]);
+    });
+
+    test("folds featureValues over the options a write carries, not over the stored ones", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({
+        agentProfiles: [
+          {
+            id: "p",
+            name: "P",
+            provider: "codex",
+            options: { sandbox_mode: "workspace-write" },
+            featureValues: { plan_mode: true },
+          },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        {
+          id: "p",
+          name: "P",
+          provider: "codex",
+          options: { sandbox_mode: "workspace-write", plan_mode: true },
+        },
+      ]);
+    });
+
+    test("converts a Codex profile's legacy fast_mode to service_tier", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({
+        agentProfiles: [
+          { id: "p", name: "P", provider: "codex", featureValues: { fast_mode: true } },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        {
+          id: "p",
+          name: "P",
+          provider: "codex",
+          options: { sandbox_mode: "read-only", plan_mode: false, service_tier: "fast" },
+        },
+      ]);
+    });
+
+    test("removes an option whose featureValues entry is null", async () => {
+      const { store } = storeWithProfile();
+
+      await store.patch({
+        agentProfiles: [
+          { id: "p", name: "P", provider: "codex", featureValues: { plan_mode: null } },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        { id: "p", name: "P", provider: "codex", options: { sandbox_mode: "read-only" } },
+      ]);
+    });
+  });
+
+  test("a profile stored with featureValues loads as options", () => {
+    const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
+    tempDirs.push(paseoHome);
+    const store = new DaemonConfigStore(paseoHome, {
+      relay: { enabled: false },
+      mcp: { injectIntoAgents: false },
+      browserTools: { enabled: false },
+      providers: {},
+      metadataGeneration: { providers: [] },
+      autoArchiveAfterMerge: false,
+      enableTerminalAgentHooks: false,
+      appendSystemPrompt: "",
+      agentProfiles: [
+        {
+          id: "legacy",
+          name: "Legacy",
+          provider: "codex",
+          featureValues: { service_tier: "fast" },
+        },
+      ],
+    });
+
+    expect(store.get().agentProfiles).toEqual([
+      { id: "legacy", name: "Legacy", provider: "codex", options: { service_tier: "fast" } },
+    ]);
+  });
+
+  describe("a profile holding Codex's legacy fast_mode", () => {
+    const legacyProfiles = ["codex", "my-codex"].map((provider) => ({
+      id: provider,
+      name: provider,
+      provider,
+      options: { fast_mode: true },
+    }));
+
+    function storeWithLegacyProfiles(agentProfiles: unknown[] = legacyProfiles): DaemonConfigStore {
+      const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
+      tempDirs.push(paseoHome);
+      return new DaemonConfigStore(paseoHome, {
+        relay: { enabled: false },
+        mcp: { injectIntoAgents: false },
+        browserTools: { enabled: false },
+        providers: { "my-codex": { extends: "codex" } },
+        metadataGeneration: { providers: [] },
+        autoArchiveAfterMerge: false,
+        enableTerminalAgentHooks: false,
+        appendSystemPrompt: "",
+        agentProfiles,
+      } as MutableDaemonConfig);
+    }
+
+    test("reads the same for codex and a provider that extends it", () => {
+      const store = storeWithLegacyProfiles();
+
+      expect(store.get().agentProfiles).toEqual([
+        { id: "codex", name: "codex", provider: "codex", options: { service_tier: "fast" } },
+        {
+          id: "my-codex",
+          name: "my-codex",
+          provider: "my-codex",
+          options: { service_tier: "fast" },
+        },
+      ]);
+      expect(toWireDaemonConfig(store.get()).agentProfiles).toEqual([
+        expect.objectContaining({ featureValues: { service_tier: "fast" } }),
+        expect.objectContaining({ featureValues: { service_tier: "fast" } }),
+      ]);
+    });
+
+    test.each(["codex", "my-codex"])("resetting %s's speed removes what was shown", async (id) => {
+      const store = storeWithLegacyProfiles();
+
+      await store.patch({
+        agentProfiles: [{ id, name: id, provider: id, featureValues: { service_tier: null } }],
+      });
+
+      expect(store.get().agentProfiles).toEqual([{ id, name: id, provider: id }]);
+    });
+
+    test("a provider edit in the same write does not hide which adapter a profile runs on", async () => {
+      const store = storeWithLegacyProfiles();
+
+      await store.patch({
+        providers: { "my-codex": { label: "Renamed" } },
+        agentProfiles: [
+          { id: "p", name: "P", provider: "my-codex", featureValues: { fast_mode: false } },
+        ],
+      });
+
+      expect(store.get().agentProfiles).toEqual([
+        { id: "p", name: "P", provider: "my-codex", options: { service_tier: "default" } },
+      ]);
+    });
+
+    test("a malformed value rejects the write and leaves config reads working", async () => {
+      const store = storeWithLegacyProfiles();
+
+      await expect(
+        store.patch({
+          agentProfiles: [
+            { id: "p", name: "P", provider: "my-codex", options: { fast_mode: "false" } },
+          ],
+        }),
+      ).rejects.toThrow(/fast_mode must be true, false or null/);
+
+      expect(toWireDaemonConfig(store.get()).agentProfiles).toHaveLength(2);
+    });
+
+    test("a malformed value in a stored profile does not stop the config from loading", () => {
+      const store = storeWithLegacyProfiles([
+        { id: "p", name: "P", provider: "codex", options: { fast_mode: "false" } },
+      ]);
+
+      expect(store.get().agentProfiles?.[0]?.options).toEqual({ fast_mode: "false" });
+    });
+  });
+
   test("patch replaces the whole agent profile list rather than merging entries", async () => {
     const paseoHome = mkdtempSync(path.join(tmpdir(), "paseo-daemon-config-store-"));
     tempDirs.push(paseoHome);
@@ -1274,6 +1591,35 @@ describe("DaemonConfigStore reload", () => {
     expect(store.get().agentProfiles).toBeUndefined();
   });
 
+  test("reload folds a profile file written with featureValues into options, and saving it persists options", async () => {
+    const { paseoHome, store, persisted } = createReloadableStore();
+    writeConfig(paseoHome, {
+      ...persisted,
+      daemon: {
+        ...persisted.daemon,
+        agentProfiles: [
+          {
+            id: "legacy",
+            name: "Legacy",
+            provider: "codex",
+            featureValues: { service_tier: "fast" },
+          },
+        ],
+      },
+    });
+
+    await store.reload();
+
+    expect(store.get().agentProfiles).toEqual([
+      { id: "legacy", name: "Legacy", provider: "codex", options: { service_tier: "fast" } },
+    ]);
+    // The app reads the profile and writes the list back on its next edit.
+    await store.patch({ agentProfiles: store.get().agentProfiles });
+    expect(loadPersistedConfig(paseoHome).daemon?.agentProfiles).toEqual([
+      { id: "legacy", name: "Legacy", provider: "codex", options: { service_tier: "fast" } },
+    ]);
+  });
+
   test("reports a launch-controlled edit without changing live state", async () => {
     const { paseoHome, store, persisted } = createReloadableStore({
       overrideControlledPaths: ["daemon.relay.enabled"],
diff --git a/packages/server/src/server/daemon-config-store.ts b/packages/server/src/server/daemon-config-store.ts
index e83874235f..c762999458 100644
--- a/packages/server/src/server/daemon-config-store.ts
+++ b/packages/server/src/server/daemon-config-store.ts
@@ -5,6 +5,13 @@ import {
   type PersistedConfig,
 } from "./persisted-config.js";
 import { ProviderOverrideSchema } from "./agent/provider-launch-config.js";
+import {
+  convertLegacyOptions,
+  foldProfileFeatureValues,
+  resolveAdapter,
+  withLegacyProfileFeatureValues,
+} from "./agent/option-controls.js";
+import type { AgentProfile } from "@getpaseo/protocol/agent-profile";
 import {
   MutableDaemonConfigSchema,
   MutableDaemonConfigPatchSchema,
@@ -168,6 +175,54 @@ function omitProvidersFromOverrides(
   return Object.keys(nextOverrides).length > 0 ? nextOverrides : undefined;
 }
 
+/**
+ * Profiles are held and persisted with `options` only, in the current keys: a profile is old
+ * data entering, so it is converted for the adapter its provider runs on, which `config.json`'s
+ * `providers` section names through `extends`.
+ */
+function foldConfigProfiles<T extends { agentProfiles?: AgentProfile[] }>(input: {
+  config: T;
+  providers: Record<string, ProviderOverride> | undefined;
+  source: "stored" | "client write";
+  held?: AgentProfile[];
+}): T {
+  const { config, providers, source, held = [] } = input;
+  if (!config.agentProfiles) return config;
+  const convert = (provider: string, options: Record<string, unknown> | undefined) =>
+    convertLegacyOptions({
+      provider: resolveAdapter({ provider, extendsOf: (id) => providers?.[id]?.extends }),
+      options,
+    });
+  const identity = (_provider: string, options: Record<string, unknown> | undefined) => options;
+  const foldWith = (profile: AgentProfile, convertWith: typeof convert) =>
+    foldProfileFeatureValues({
+      profile,
+      stored: held.find((candidate) => candidate.id === profile.id),
+      source,
+      convert: convertWith,
+    });
+  return {
+    ...config,
+    agentProfiles: config.agentProfiles.map((profile) => {
+      // A malformed value rejects a client write before anything is committed.
+      if (source === "client write") return foldWith(profile, convert);
+      try {
+        return foldWith(profile, convert);
+      } catch {
+        // A hand-edited `config.json` value that cannot convert must not stop the daemon from
+        // starting; it keeps its keys and is rejected when an agent is created from it.
+        return foldWith(profile, identity);
+      }
+    }),
+  };
+}
+
+/** The config API boundary: the unchanged app reads profile options from `featureValues`. */
+export function toWireDaemonConfig(config: MutableDaemonConfig): MutableDaemonConfig {
+  if (!config.agentProfiles) return config;
+  return { ...config, agentProfiles: config.agentProfiles.map(withLegacyProfileFeatureValues) };
+}
+
 function getValueAtPath(config: MutableDaemonConfig, path: string): unknown {
   return path
     .split(".")
@@ -380,7 +435,7 @@ export class DaemonConfigStore {
     this.startupPersisted = options.startupPersisted ?? loadPersistedConfig(paseoHome, this.logger);
     this.lastKnownPersisted = this.startupPersisted;
     this.current = MutableDaemonConfigSchema.parse({
-      ...initial,
+      ...foldConfigProfiles({ config: initial, providers: initial.providers, source: "stored" }),
       relay: initial.relay ?? { enabled: true },
       ...this.readSpeech(this.startupPersisted),
     });
@@ -410,6 +465,18 @@ export class DaemonConfigStore {
     return this.enqueue(() => this.applySupportedPatch({ skills: { selection } }));
   }
 
+  private foldPatchProfiles<
+    T extends { agentProfiles?: AgentProfile[]; providers?: Record<string, ProviderOverride> },
+  >(submittedPatch: T): T {
+    return foldConfigProfiles({
+      config: submittedPatch,
+      // The provider graph this request will commit, so `extends` survives a partial edit.
+      providers: deepMerge(this.current.providers ?? {}, submittedPatch.providers ?? {}),
+      source: "client write",
+      held: this.current.agentProfiles,
+    });
+  }
+
   private async applySupportedPatch(
     parsedPatch: SupportedMutableConfigPatch,
   ): Promise<MutableDaemonConfig> {
@@ -418,7 +485,8 @@ export class DaemonConfigStore {
         "Relay is controlled by a daemon launch override. Remove PASEO_RELAY_ENABLED or the relay CLI flag before changing it here.",
       );
     }
-    const { removeProviders = [], ...patch } = parsedPatch;
+    const { removeProviders = [], ...submittedPatch } = parsedPatch;
+    const patch = this.foldPatchProfiles(submittedPatch);
     const { features: speechPatch, ...configPatch } = patch;
     const removedProviders = Array.from(new Set(removeProviders));
     const merged = deepMerge(this.current, configPatch);
@@ -437,7 +505,16 @@ export class DaemonConfigStore {
     const configChanged = !isEqualValue(this.current, next);
 
     // A replaced API key leaves the speech view unchanged, so a speech patch always persists.
-    if (!configChanged && removedProviders.length === 0 && speechPatch === undefined) {
+    // Profiles held folded in memory may still be on disk with `featureValues`; saving them writes `options`.
+    const profilesStaleOnDisk =
+      patch.agentProfiles !== undefined &&
+      !isEqualValue(patch.agentProfiles, this.lastKnownPersisted.daemon?.agentProfiles);
+    if (
+      !configChanged &&
+      removedProviders.length === 0 &&
+      speechPatch === undefined &&
+      !profilesStaleOnDisk
+    ) {
       return this.current;
     }
 
@@ -495,7 +572,11 @@ export class DaemonConfigStore {
     // Plugin source changes require the plugin lifecycle operation or a daemon
     // restart. The global switch is independently reloadable.
     const desired = MutableDaemonConfigSchema.parse({
-      ...resolved.mutable,
+      ...foldConfigProfiles({
+        config: resolved.mutable,
+        providers: resolved.mutable.providers,
+        source: "stored",
+      }),
       plugins: this.current.plugins,
       ...this.readSpeech(persisted),
     });
diff --git a/packages/server/src/server/daemon-e2e/agent-archive-detach-updates.e2e.test.ts b/packages/server/src/server/daemon-e2e/agent-archive-detach-updates.e2e.test.ts
new file mode 100644
index 0000000000..31e4a828dd
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/agent-archive-detach-updates.e2e.test.ts
@@ -0,0 +1,162 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { expect, test } from "vitest";
+import type { AgentSnapshotPayload, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+
+import { DaemonClient } from "../test-utils/daemon-client.js";
+import { createTestPaseoDaemon, type TestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+
+const CREATED_AT = "2026-11-04T08:00:00.000Z";
+const UPDATED_AT = "2026-11-04T09:00:00.000Z";
+const RUNTIME_INFO = {
+  provider: "codex",
+  sessionId: null,
+  model: "provider-default",
+  thinkingOptionId: "medium",
+};
+
+test.each([false, true])(
+  "parent archive preserves a stored survivor for subscribers (filtered=%s)",
+  async (filtered) => {
+    const fixture = seedFixture();
+    let daemon: TestPaseoDaemon | null = null;
+    let observer: DaemonClient | null = null;
+    let actor: DaemonClient | null = null;
+    try {
+      daemon = await createTestPaseoDaemon({
+        paseoHomeRoot: fixture.paseoHomeRoot,
+        staticDir: fixture.staticDir,
+        cleanup: false,
+      });
+      const url = `ws://127.0.0.1:${daemon.port}/ws`;
+      observer = new DaemonClient({ url });
+      actor = new DaemonClient({ url });
+      await observer.connect();
+      await actor.connect();
+
+      const updates: AgentSnapshotPayload[] = [];
+      const removed: string[] = [];
+      observer.subscribeRawMessages((message: SessionOutboundMessage) => {
+        if (message.type === "agent_update" && message.payload.kind === "upsert") {
+          updates.push(message.payload.agent);
+        } else if (message.type === "agent_update" && message.payload.kind === "remove") {
+          removed.push(message.payload.agentId);
+        }
+      });
+      const initial = await observer.fetchAgents({
+        filter: { includeBackground: true, ...(filtered ? { thinkingOptionId: "medium" } : {}) },
+        subscribe: {},
+      });
+      const initialSurvivor = initial.entries.find(
+        (entry) => entry.agent.id === "child-survivor",
+      )?.agent;
+      expect(initialSurvivor?.runtimeInfo).toEqual(RUNTIME_INFO);
+      expect(initialSurvivor?.effectiveThinkingOptionId).toBe("medium");
+
+      // A child already detached by hand remains independent of the parent archive.
+      await actor.detachAgent("child-manual");
+      await actor.archiveAgent("parent");
+
+      const survivor = await actor.fetchAgent({ agentId: "child-survivor" });
+      expect(survivor?.agent.archivedAt).toBeNull();
+      expect(survivor?.agent.labels).toEqual({});
+      await expect
+        .poll(() => updates.findLast((update) => update.id === "child-survivor")?.labels)
+        .toEqual({});
+      const update = updates.findLast((item) => item.id === "child-survivor");
+      expect(update?.runtimeInfo).toEqual(RUNTIME_INFO);
+      expect(update?.effectiveThinkingOptionId).toBe("medium");
+      expect(removed).not.toContain("child-survivor");
+      const manual = await actor.fetchAgent({ agentId: "child-manual" });
+      expect(manual?.agent.archivedAt).toBeNull();
+      expect(manual?.agent.labels).toEqual({});
+    } finally {
+      await observer?.close().catch(() => undefined);
+      await actor?.close().catch(() => undefined);
+      await daemon?.close().catch(() => undefined);
+      for (const target of fixture.cleanupPaths) rmSync(target, { recursive: true, force: true });
+    }
+  },
+);
+
+function seedFixture() {
+  const artifacts = path.join(process.cwd(), ".artifacts");
+  mkdirSync(artifacts, { recursive: true });
+  const root = mkdtempSync(path.join(artifacts, "archive-detach-"));
+  const parentCwd = path.join(root, "parent");
+  const childCwd = path.join(root, "child");
+  const paseoHomeRoot = path.join(root, "home");
+  const staticDir = path.join(root, "static");
+  mkdirSync(staticDir);
+  mkdirSync(parentCwd);
+  mkdirSync(childCwd);
+  const paseoHome = path.join(paseoHomeRoot, ".paseo");
+  const projectsDir = path.join(paseoHome, "projects");
+  const agentsDir = path.join(paseoHome, "agents");
+  mkdirSync(projectsDir, { recursive: true });
+  mkdirSync(agentsDir, { recursive: true });
+  const project = (projectId: string, rootPath: string) => ({
+    projectId,
+    rootPath,
+    kind: "non_git",
+    displayName: projectId,
+    customName: null,
+    createdAt: CREATED_AT,
+    updatedAt: UPDATED_AT,
+    archivedAt: null,
+  });
+  const workspace = (workspaceId: string, projectId: string, cwd: string) => ({
+    workspaceId,
+    projectId,
+    cwd,
+    kind: "directory",
+    displayName: workspaceId,
+    title: null,
+    branch: null,
+    baseBranch: null,
+    createdAt: CREATED_AT,
+    updatedAt: UPDATED_AT,
+    archivedAt: null,
+  });
+  writeJson(path.join(projectsDir, "projects.json"), [
+    project("proj-parent", parentCwd),
+    project("proj-child", childCwd),
+  ]);
+  writeJson(path.join(projectsDir, "workspaces.json"), [
+    workspace("ws-parent", "proj-parent", parentCwd),
+    workspace("ws-child", "proj-child", childCwd),
+  ]);
+  const agent = (id: string, cwd: string, workspaceId: string, labels: Record<string, string>) => ({
+    id,
+    provider: "codex",
+    cwd,
+    workspaceId,
+    createdAt: CREATED_AT,
+    updatedAt: UPDATED_AT,
+    lastActivityAt: UPDATED_AT,
+    lastUserMessageAt: null,
+    title: id,
+    labels,
+    lastStatus: "closed",
+    lastModeId: "full-access",
+    config: null,
+    ...(id === "child-survivor" ? { runtimeInfo: RUNTIME_INFO } : {}),
+    persistence: null,
+  });
+  // Both children live in another workspace, so the parent's archive detaches rather than archives them.
+  writeJson(path.join(agentsDir, "parent.json"), agent("parent", parentCwd, "ws-parent", {}));
+  writeJson(
+    path.join(agentsDir, "child-survivor.json"),
+    agent("child-survivor", childCwd, "ws-child", { [PARENT_AGENT_ID_LABEL]: "parent" }),
+  );
+  writeJson(
+    path.join(agentsDir, "child-manual.json"),
+    agent("child-manual", childCwd, "ws-child", { [PARENT_AGENT_ID_LABEL]: "parent" }),
+  );
+  return { paseoHomeRoot, staticDir, cleanupPaths: [root] };
+}
+
+function writeJson(filePath: string, value: unknown): void {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
diff --git a/packages/server/src/server/daemon-e2e/checkout-diff-content.e2e.test.ts b/packages/server/src/server/daemon-e2e/checkout-diff-content.e2e.test.ts
index fe83c21305..b297d07b5a 100644
--- a/packages/server/src/server/daemon-e2e/checkout-diff-content.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/checkout-diff-content.e2e.test.ts
@@ -88,13 +88,9 @@ test.each(["uncommitted", "base", "commit"] as const)(
   60_000,
 );
 
-test.each(
-  (["uncommitted", "base"] as const).flatMap((mode) =>
-    (["single", "batch", "rename"] as const).map((shape) => ({ mode, shape })),
-  ),
-)(
-  "$mode $shape diff includes hunks from a repository subdirectory",
-  async ({ mode, shape }) => {
+test.each(["single", "batch", "rename"] as const)(
+  "%s diff includes hunks from a repository subdirectory before and after commit",
+  async (shape) => {
     const ctx = await createDaemonTestContext();
     const cwd = mkdtempSync(join(tmpdir(), "checkout-diff-subdirectory-"));
 
@@ -112,9 +108,7 @@ test.each(
       }
       git(cwd, "add", ".");
       git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "initial");
-      if (mode === "base") {
-        git(cwd, "checkout", "-b", "feature");
-      }
+      git(cwd, "checkout", "-b", "feature");
       const filename = shape === "rename" ? "renamed.txt" : "normal.txt";
       if (shape === "rename") {
         git(cwd, "mv", "sub/normal.txt", `sub/${filename}`);
@@ -123,36 +117,38 @@ test.each(
       if (shape === "batch") {
         writeFileSync(join(cwd, "sibling.txt"), "new sibling\n");
       }
-      if (mode === "base") {
-        git(cwd, "add", ".");
-        git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      async function expectSubdirectoryDiff(mode: "uncommitted" | "base") {
+        const compare = { mode, baseRef: "main" };
+        const rootDiff = await ctx.client.getCheckoutDiff(cwd, compare);
+        const subdirectoryDiff = await ctx.client.getCheckoutDiff(subdirectory, compare);
+        const subscription = ctx.client.observeCheckoutDiff(subdirectory, compare);
+        const liveDiff = await subscription.ready;
+        await subscription.release();
+
+        expect(rootDiff.error).toBeNull();
+        expect(subdirectoryDiff.error).toBeNull();
+        expect(liveDiff.error).toBeNull();
+        expect(liveDiff.files).toEqual(rootDiff.files);
+        expect(rootDiff.files).toHaveLength(shape === "batch" ? 2 : 1);
+        const file = rootDiff.files.find((candidate) => candidate.path === `sub/${filename}`);
+        expect(file).toMatchObject({
+          additions: 1,
+          deletions: 1,
+          ...(shape === "rename" ? { oldPath: "sub/normal.txt" } : {}),
+        });
+        expect(file?.hunks.flatMap((hunk) => hunk.lines)).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({ type: "remove", content: "before" }),
+            expect.objectContaining({ type: "add", content: "after" }),
+          ]),
+        );
+        expect(subdirectoryDiff.files).toEqual(rootDiff.files);
       }
 
-      const compare = { mode, baseRef: "main" };
-      const rootDiff = await ctx.client.getCheckoutDiff(cwd, compare);
-      const subdirectoryDiff = await ctx.client.getCheckoutDiff(subdirectory, compare);
-      const subscription = ctx.client.observeCheckoutDiff(subdirectory, compare);
-      const liveDiff = await subscription.ready;
-      await subscription.release();
-
-      expect(rootDiff.error).toBeNull();
-      expect(subdirectoryDiff.error).toBeNull();
-      expect(liveDiff.error).toBeNull();
-      expect(liveDiff.files).toEqual(rootDiff.files);
-      expect(rootDiff.files).toHaveLength(shape === "batch" ? 2 : 1);
-      const file = rootDiff.files.find((candidate) => candidate.path === `sub/${filename}`);
-      expect(file).toMatchObject({
-        additions: 1,
-        deletions: 1,
-        ...(shape === "rename" ? { oldPath: "sub/normal.txt" } : {}),
-      });
-      expect(file?.hunks.flatMap((hunk) => hunk.lines)).toEqual(
-        expect.arrayContaining([
-          expect.objectContaining({ type: "remove", content: "before" }),
-          expect.objectContaining({ type: "add", content: "after" }),
-        ]),
-      );
-      expect(subdirectoryDiff.files).toEqual(rootDiff.files);
+      await expectSubdirectoryDiff("uncommitted");
+      git(cwd, "add", ".");
+      git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      await expectSubdirectoryDiff("base");
     } finally {
       await ctx.cleanup();
       rmSync(cwd, { recursive: true, force: true });
@@ -297,3 +293,263 @@ test("large source diffs stay renderable for reads, subscriptions, and commit fi
     await rm(cwd, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
   }
 }, 60_000);
+
+test("streams whole-file batches and answers a same-socket ping before the revision ends", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "diff-stream-wire-"));
+  let probe: Awaited<ReturnType<typeof openDiffWireProbe>> | null = null;
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "README"), "base\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    for (let file = 0; file < 252; file++) {
+      const content =
+        Array.from(
+          { length: 80 },
+          (_, line) =>
+            `export const fn${line} = (param: string) => ({ key: param, value: ${file} });`,
+        ).join("\n") + "\n";
+      writeFileSync(join(cwd, `${file}.ts`), content);
+    }
+    expect(ctx.client.getLastServerInfoMessage()).toMatchObject({
+      features: { diffSubscription: true },
+    });
+    const legacy = await ctx.client.getCheckoutDiff(cwd, { mode: "uncommitted" });
+    const legacyJsonBytes = Buffer.byteLength(JSON.stringify(legacy.files));
+    expect(legacyJsonBytes).toBeGreaterThanOrEqual(10 * 1024 * 1024);
+    probe = await openDiffWireProbe(ctx.daemon.port, cwd);
+    const { encodedBytes, bodyFrames, pongDuringRevision, entryCount } = await probe.done;
+    expect(entryCount).toBe(252);
+    expect(bodyFrames).toBeGreaterThan(1);
+    expect(pongDuringRevision).toBe(true);
+    const artifactDirectory = join(
+      import.meta.dirname,
+      "../../../../../.artifacts/diff-subscription",
+    );
+    mkdirSync(artifactDirectory, { recursive: true });
+    writeFileSync(
+      join(artifactDirectory, "wire-metrics.json"),
+      JSON.stringify({ legacyJsonBytes, encodedBytes, bodyFrames, pongDuringRevision }, null, 2),
+    );
+  } finally {
+    probe?.socket.terminate();
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 60_000);
+
+interface DiffWireResult {
+  encodedBytes: number;
+  bodyFrames: number;
+  pongDuringRevision: boolean;
+  entryCount: number;
+}
+async function openDiffWireProbe(port: number, cwd: string) {
+  const { WebSocket } = await import("ws");
+  const { decodeDiffFrame, DiffOpcode } = await import("@getpaseo/protocol/binary-frames/index");
+  const activeSocket = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+  await new Promise<void>((resolve, reject) => {
+    activeSocket.once("open", resolve);
+    activeSocket.once("error", reject);
+  });
+  let encodedBytes = 0;
+  let endReceived = false;
+  let pingSent = false;
+  let pongDuringRevision = false;
+  let bodyFrames = 0;
+  let entryCount = 0;
+  const done = new Promise<DiffWireResult>((resolve, reject) => {
+    activeSocket.on("message", (data, binary) => {
+      try {
+        if (binary) {
+          if (!Buffer.isBuffer(data)) throw new Error("Expected buffer");
+          encodedBytes += data.byteLength;
+          const frame = decodeDiffFrame(new Uint8Array(data));
+          if (frame.opcode === DiffOpcode.Begin) entryCount = frame.entries.length;
+          if (frame.opcode === DiffOpcode.Bodies) {
+            bodyFrames++;
+            if (!pingSent) {
+              pingSent = true;
+              activeSocket.send(
+                JSON.stringify({
+                  type: "session",
+                  message: { type: "ping", requestId: "mid-revision", clientSentAt: 1 },
+                }),
+              );
+            }
+          }
+          if (frame.opcode === DiffOpcode.End) {
+            expect(frame.error).toBeNull();
+            endReceived = true;
+            resolve({ encodedBytes, bodyFrames, pongDuringRevision, entryCount });
+          }
+        } else {
+          const envelope = JSON.parse(data.toString());
+          if (
+            envelope.message?.type === "pong" &&
+            envelope.message.payload.requestId === "mid-revision"
+          )
+            pongDuringRevision = !endReceived;
+          if (envelope.message?.payload?.status === "server_info")
+            activeSocket.send(
+              JSON.stringify({
+                type: "session",
+                message: {
+                  type: "diff.subscribe.request",
+                  requestId: "stream-diff",
+                  cwd,
+                  base: { kind: "rev", rev: "HEAD" },
+                  head: { kind: "worktree" },
+                },
+              }),
+            );
+          if (envelope.message?.type === "diff.subscribe.response")
+            expect(envelope.message.payload.error).toBeNull();
+        }
+      } catch (error) {
+        reject(error);
+      }
+    });
+    activeSocket.once("error", reject);
+  });
+  activeSocket.send(
+    JSON.stringify({
+      type: "hello",
+      clientId: "diff-wire-test",
+      clientType: "browser",
+      protocolVersion: 1,
+      capabilities: { owned_subscriptions: true },
+    }),
+  );
+  return { socket: activeSocket, done };
+}
+
+test("SDK diff journey publishes a tag tree, commits a one-file refresh and shares two sockets", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "sdk-stream-diff-"));
+  const { DaemonClient } = await import("../test-utils/daemon-client.js");
+  const { startGitCommandMetrics, stopGitCommandMetrics } =
+    await import("../../utils/run-git-command.js");
+  const second = new DaemonClient({ url: `ws://127.0.0.1:${ctx.daemon.port}/ws` });
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "a.ts"), "export const a = 1;\n");
+    writeFileSync(join(cwd, "b.ts"), "export const b = 1;\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git(cwd, "tag", "v1");
+    writeFileSync(join(cwd, "a.ts"), "export const a = 2;\n");
+    writeFileSync(join(cwd, "b.ts"), "export const b = 2;\n");
+    const compare = {
+      cwd,
+      base: { kind: "rev", rev: "refs/tags/v1" },
+      head: { kind: "worktree" },
+      mergeBase: true,
+    } as const;
+    const states: import("@getpaseo/client").DiffState[] = [];
+    const observation = ctx.client.observeDiff(compare);
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    await expect.poll(() => states.at(-1)?.phase, { timeout: 15000 }).toBe("ready");
+    expect(states[0]).toMatchObject({
+      phase: "loading",
+      entries: [{ path: "a.ts" }, { path: "b.ts" }],
+    });
+    const initial = states.at(-1);
+    if (initial?.phase !== "ready") throw new Error("Expected ready");
+    const initialStateCount = states.length;
+    await second.connect();
+    startGitCommandMetrics();
+    const duplicateStates: import("@getpaseo/client").DiffState[] = [];
+    const duplicate = second.observeDiff(compare);
+    duplicate.subscribe({ snapshot: (state) => duplicateStates.push(state), update: () => {} });
+    await expect.poll(() => duplicateStates.at(-1)?.phase).toBe("ready");
+    const metrics = stopGitCommandMetrics();
+    expect(duplicateStates.at(-1)).toMatchObject({
+      phase: "ready",
+      files: [{ path: "a.ts" }, { path: "b.ts" }],
+    });
+    expect(metrics.commands.filter((command) => command.args.includes("--raw"))).toHaveLength(0);
+    startGitCommandMetrics();
+    writeFileSync(join(cwd, "a.ts"), "export const a = 3;\n");
+    await expect
+      .poll(() => states.at(-1)?.revision, { timeout: 15000 })
+      .toBeGreaterThan(initial.revision);
+    await expect.poll(() => duplicateStates.at(-1)?.revision).toBeGreaterThan(initial.revision);
+    const refreshMetrics = stopGitCommandMetrics();
+    expect(
+      refreshMetrics.commands.filter((command) => command.args.includes("--raw")),
+    ).toHaveLength(1);
+    const refreshed = states.at(-1);
+    if (refreshed?.phase !== "ready") throw new Error("Expected ready");
+    expect(refreshed.files[0]).not.toBe(initial.files[0]);
+    expect(refreshed.files[1]).toBe(initial.files[1]);
+    expect(states.slice(initialStateCount).map((state) => state.phase)).not.toContain("loading");
+    expect(states.map((state) => state.phase)).not.toContain("error");
+    await duplicate.release();
+    await observation.release();
+  } finally {
+    await second.close();
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 45000);
+
+test("commit-file RPC keeps the existing read ceiling for patches larger than one MiB", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "commit-file-budget-"));
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "large.txt"), "base\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    writeFileSync(join(cwd, "large.txt"), ("x".repeat(100) + "\n").repeat(11000));
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "large change");
+    const sha = git(cwd, "rev-parse", "HEAD").trim();
+    const { getCommitFileDiff } = await import("../../utils/checkout-git.js");
+    const expected = await getCommitFileDiff({ cwd, sha, path: "large.txt" });
+    const actual = await ctx.client.getCommitFileDiff(cwd, sha, "large.txt");
+    expect(expected?.hunks.length).toBeGreaterThan(0);
+    expect(actual.file?.hunks).toEqual(expected?.hunks);
+  } finally {
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test("commit-file RPC selects renamed content when the source path becomes a directory", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "commit-rename-directory-"));
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "a.txt"), "original line\n".repeat(16));
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git(cwd, "mv", "a.txt", "z.txt");
+    writeFileSync(join(cwd, "z.txt"), "original line\n".repeat(16) + "renamed line\n");
+    mkdirSync(join(cwd, "a.txt"));
+    writeFileSync(join(cwd, "a.txt", "child.txt"), "replacement line\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "rename");
+    const sha = git(cwd, "rev-parse", "HEAD").trim();
+    const { getCommitFileDiff } = await import("../../utils/checkout-git.js");
+    const expected = await getCommitFileDiff({ cwd, sha, path: "z.txt" });
+    const actual = await ctx.client.getCommitFileDiff(cwd, sha, "z.txt");
+    expect(expected?.hunks.flatMap((hunk) => hunk.lines.map((line) => line.content))).toContain(
+      "renamed line",
+    );
+    expect(actual.file?.hunks).toEqual(expected?.hunks);
+  } finally {
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 30000);
diff --git a/packages/server/src/server/daemon-e2e/checkout-diff-subscription.e2e.test.ts b/packages/server/src/server/daemon-e2e/checkout-diff-subscription.e2e.test.ts
index 3af53a9133..40d410f6c1 100644
--- a/packages/server/src/server/daemon-e2e/checkout-diff-subscription.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/checkout-diff-subscription.e2e.test.ts
@@ -142,7 +142,8 @@ test("keeps the socket usable after rejecting an oversized structured diff", asy
     commitFile(cwd, "large-b.js", "const value = 0;\n");
     // Short lines stay eligible for highlighting; a giant single line is skipped
     // before token expansion and cannot exercise the structured-payload limit.
-    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(4_000);
+    // Stay below the full-source highlighting budget as well.
+    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(3_500);
     writeFileSync(path.join(cwd, "large-a.js"), denseExpression);
     writeFileSync(path.join(cwd, "large-b.js"), denseExpression);
 
diff --git a/packages/server/src/server/daemon-e2e/cli-logs-follow.e2e.test.ts b/packages/server/src/server/daemon-e2e/cli-logs-follow.e2e.test.ts
index 55750831c8..63cdf2363b 100644
--- a/packages/server/src/server/daemon-e2e/cli-logs-follow.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/cli-logs-follow.e2e.test.ts
@@ -1,7 +1,10 @@
 import { spawn } from "node:child_process";
 import { once } from "node:events";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
+import { WebSocket, WebSocketServer } from "ws";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 import { DaemonClient } from "../test-utils/daemon-client.js";
 
@@ -137,3 +140,225 @@ test("omitted after limit pages forward while explicit zero preserves complete C
     await daemon.close();
   }
 }, 60_000);
+
+test.each([
+  { label: "--json", flags: ["--json"] },
+  { label: "--format json", flags: ["--format", "json"] },
+])(
+  "logs --follow $label keeps history, live items and notices on their channels",
+  async ({ flags }) => {
+    await mkdir(".artifacts", { recursive: true });
+    const paseoHomeRoot = await mkdtemp(resolve(".artifacts/logs-follow-json-"));
+    const staticDir = join(paseoHomeRoot, "static");
+    await mkdir(staticDir);
+    const daemon = await createTestPaseoDaemon({ paseoHomeRoot, staticDir });
+    const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+    let follow: ReturnType<typeof spawn> | undefined;
+    let stdout = "";
+    let stderr = "";
+    try {
+      await client.connect();
+      const agent = await client.createAgent({ provider: "claude", cwd: daemon.paseoHome });
+      const history = [
+        { type: "user_message" as const, text: "Saved JSON prompt" },
+        { type: "assistant_message" as const, text: "Saved JSON reply", messageId: "saved" },
+      ];
+      for (const item of history)
+        await daemon.daemon.agentManager.appendTimelineItem(agent.id, item);
+      follow = spawn(
+        process.execPath,
+        [
+          "--conditions=source",
+          "--import",
+          "tsx",
+          fileURLToPath(new URL("../../../../cli/src/index.ts", import.meta.url)),
+          "--host",
+          `127.0.0.1:${daemon.port}`,
+          "logs",
+          agent.id,
+          "--follow",
+          ...flags,
+        ],
+        {
+          env: { ...process.env, PASEO_HOME: daemon.paseoHome },
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      const exited = once(follow, "exit");
+      follow.stdout?.on("data", (chunk: Buffer) => {
+        stdout += chunk.toString();
+      });
+      follow.stderr?.on("data", (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+      await expect
+        .poll(
+          () => {
+            if (follow?.exitCode !== null)
+              throw new Error(`CLI exited before following logs: ${stderr}`);
+            return stdout + stderr;
+          },
+          { timeout: 20_000 },
+        )
+        .toContain("Following logs");
+      const live = {
+        type: "assistant_message" as const,
+        text: "Live JSON reply",
+        messageId: "live",
+      };
+      await daemon.daemon.agentManager.appendTimelineItem(agent.id, live);
+      await expect.poll(() => stdout, { timeout: 10_000 }).toContain(live.text);
+      follow.kill("SIGINT");
+      await exited;
+      expect(
+        stdout
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line)),
+      ).toEqual([...history, live]);
+      expect(stderr).toContain("Following logs");
+      expect(stdout).not.toContain("Following logs");
+    } finally {
+      follow?.kill("SIGTERM");
+      await client.close();
+      await daemon.close();
+    }
+  },
+  60_000,
+);
+
+test.each([
+  { label: "--json", command: ["logs"], flags: ["--json"] },
+  { label: "--format json", command: ["agent", "logs"], flags: ["--format", "json"] },
+])(
+  "logs --follow $label exits when stdout closes before saved history is written",
+  async ({ command, flags }) => {
+    await mkdir(".artifacts", { recursive: true });
+    const paseoHomeRoot = await mkdtemp(resolve(".artifacts/logs-follow-closed-"));
+    const staticDir = join(paseoHomeRoot, "static");
+    await mkdir(staticDir);
+    const daemon = await createTestPaseoDaemon({ paseoHomeRoot, staticDir });
+    const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+    let follow: ReturnType<typeof spawn> | undefined;
+    let stderr = "";
+    try {
+      await client.connect();
+      // No turn is started: the saved history must trigger shutdown on its own.
+      const agent = await client.createAgent({ provider: "claude", cwd: daemon.paseoHome });
+      await daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+        type: "assistant_message",
+        text: "Saved reply before the reader closes",
+        messageId: "saved",
+      });
+      follow = spawn(
+        process.execPath,
+        [
+          "--conditions=source",
+          "--import",
+          "tsx",
+          fileURLToPath(new URL("../../../../cli/src/index.ts", import.meta.url)),
+          "--host",
+          `127.0.0.1:${daemon.port}`,
+          ...command,
+          agent.id,
+          "--follow",
+          ...flags,
+        ],
+        {
+          env: { ...process.env, PASEO_HOME: daemon.paseoHome },
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      const exited = once(follow, "exit");
+      follow.stderr?.on("data", (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+      follow.stdout?.destroy();
+      await expect.poll(() => follow?.exitCode, { timeout: 10_000 }).toBe(0);
+      expect(await exited, stderr).toEqual([0, null]);
+    } finally {
+      follow?.kill("SIGKILL");
+      await client.close();
+      await daemon.close();
+    }
+  },
+  30_000,
+);
+
+// Windows kill("SIGINT") force-terminates rather than delivering a console interrupt.
+test.skipIf(process.platform === "win32")(
+  "logs --follow stops on SIGINT while subscription startup is waiting",
+  async () => {
+    await mkdir(".artifacts", { recursive: true });
+    const paseoHomeRoot = await mkdtemp(resolve(".artifacts/logs-follow-startup-"));
+    const staticDir = join(paseoHomeRoot, "static");
+    await mkdir(staticDir);
+    const daemon = await createTestPaseoDaemon({ paseoHomeRoot, staticDir });
+    const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+    const proxy = new WebSocketServer({ port: 0, host: "127.0.0.1" });
+    await once(proxy, "listening");
+    const address = proxy.address();
+    if (typeof address === "string" || address === null) throw new Error("Missing proxy port");
+    const upstreams: WebSocket[] = [];
+    let waitingForSubscription = false;
+    proxy.on("connection", (downstream) => {
+      const upstream = new WebSocket(`ws://127.0.0.1:${daemon.port}/ws`);
+      upstreams.push(upstream);
+      const connected = once(upstream, "open");
+      downstream.on("message", async (data, binary) => {
+        await connected;
+        const frame = binary ? undefined : JSON.parse(data.toString());
+        // Hold only the subscription request. All other traffic uses the real daemon.
+        if (frame?.message?.type === "agent.timeline.set_subscription.request") {
+          waitingForSubscription = true;
+          return;
+        }
+        upstream.send(data, { binary });
+      });
+      upstream.on("message", (data, binary) => downstream.send(data, { binary }));
+      downstream.on("close", () => upstream.close());
+    });
+    let follow: ReturnType<typeof spawn> | undefined;
+    try {
+      await client.connect();
+      const agent = await client.createAgent({ provider: "claude", cwd: daemon.paseoHome });
+      follow = spawn(
+        process.execPath,
+        [
+          "--conditions=source",
+          "--import",
+          "tsx",
+          fileURLToPath(new URL("../../../../cli/src/index.ts", import.meta.url)),
+          "--host",
+          `127.0.0.1:${address.port}`,
+          "logs",
+          agent.id,
+          "--follow",
+          "--json",
+        ],
+        {
+          env: { ...process.env, PASEO_HOME: daemon.paseoHome },
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      follow.stdout?.resume();
+      follow.stderr?.resume();
+      const exited = once(follow, "exit");
+      await expect.poll(() => waitingForSubscription, { timeout: 10_000 }).toBe(true);
+      follow.kill("SIGINT");
+      await expect.poll(() => follow?.exitCode, { timeout: 5_000 }).toBe(0);
+      expect(await exited).toEqual([0, null]);
+    } finally {
+      if (follow && follow.exitCode === null && follow.signalCode === null) {
+        follow.kill("SIGKILL");
+        await once(follow, "exit");
+      }
+      for (const upstream of upstreams) upstream.terminate();
+      for (const downstream of proxy.clients) downstream.terminate();
+      await new Promise<void>((done) => proxy.close(() => done()));
+      await client.close();
+      await daemon.close();
+    }
+  },
+  30_000,
+);
diff --git a/packages/server/src/server/daemon-e2e/create-agent-mode.e2e.test.ts b/packages/server/src/server/daemon-e2e/create-agent-mode.e2e.test.ts
new file mode 100644
index 0000000000..e60645c2bf
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/create-agent-mode.e2e.test.ts
@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { expect, test } from "vitest";
+import { createDaemonTestContext } from "../test-utils/index.js";
+
+test("an attended MCP caller can discover and supply a cross-provider child mode", async () => {
+  const artifacts = path.join(process.cwd(), ".artifacts");
+  await mkdir(artifacts, { recursive: true });
+  const root = await mkdtemp(path.join(artifacts, "create-agent-mode-"));
+  const ctx = await createDaemonTestContext({ paseoHomeRoot: root, mcpEnabled: true });
+  const mcp = new Client({ name: "mode-contract-test", version: "1" });
+  try {
+    const parent = await ctx.client.createAgent({
+      provider: "claude",
+      cwd: root,
+      modeId: "default",
+      title: "Attended parent",
+    });
+    await mcp.connect(
+      new StreamableHTTPClientTransport(
+        new URL(`http://127.0.0.1:${ctx.daemon.port}/mcp/agents?callerAgentId=${parent.id}`),
+      ),
+    );
+    const { tools } = await mcp.listTools();
+    const create = tools.find((tool) => tool.name === "create_agent");
+    expect.soft(create?.description).toContain("settings.modeId");
+
+    const args = {
+      provider: "codex/gpt-5.4-mini",
+      title: "Cross-provider child",
+      initialPrompt: "Reply with OK",
+    };
+    const refused = await mcp.callTool({ name: "create_agent", arguments: args });
+    expect(refused.isError).toBe(true);
+    expect.soft(refused.content).toEqual([
+      expect.objectContaining({
+        type: "text",
+        text: expect.stringContaining("Pass an explicit mode in settings.modeId"),
+      }),
+    ]);
+    expect((await ctx.client.fetchAgents({ subscribe: {} })).entries).toHaveLength(1);
+
+    const inspected = await mcp.callTool({
+      name: "inspect_provider",
+      arguments: { provider: "codex" },
+    });
+    expect(inspected.isError).not.toBe(true);
+    expect(inspected.structuredContent).toMatchObject({
+      modes: expect.arrayContaining([expect.objectContaining({ id: "auto" })]),
+    });
+    const created = await mcp.callTool({
+      name: "create_agent",
+      arguments: { ...args, settings: { modeId: "auto" } },
+    });
+    expect(created.isError).not.toBe(true);
+    expect(created.structuredContent).toMatchObject({ type: "codex", currentModeId: "auto" });
+    const childId = (created.structuredContent as { agentId: string }).agentId;
+    expect((await ctx.client.fetchAgent(childId))?.agent.currentModeId).toBe("auto");
+    expect((await ctx.client.waitForFinish(childId, 5000)).status).toBe("idle");
+  } finally {
+    await mcp.close();
+    await ctx.cleanup();
+    await rm(root, { recursive: true, force: true });
+  }
+}, 30_000);
diff --git a/packages/server/src/server/daemon-e2e/creation-status.e2e.test.ts b/packages/server/src/server/daemon-e2e/creation-status.e2e.test.ts
new file mode 100644
index 0000000000..c2293a2bc7
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/creation-status.e2e.test.ts
@@ -0,0 +1,64 @@
+import { expect, test } from "vitest";
+import { createDaemonTestContext } from "../test-utils/index.js";
+import { MockLoadTestAgentClient } from "../agent/providers/mock-load-test-agent.js";
+import type { AgentSnapshotPayload } from "../messages.js";
+
+test("creation never regresses a running subscription to the pre-prompt idle snapshot", async () => {
+  const ctx = await createDaemonTestContext({
+    agentClients: { mock: new MockLoadTestAgentClient() },
+    mcpEnabled: false,
+    isDev: true,
+  });
+  try {
+    const workspace = await ctx.client.createWorkspace({
+      source: { kind: "directory", path: ctx.daemon.staticDir },
+    });
+    if (!workspace.workspace) throw new Error(workspace.error ?? "Missing workspace");
+    const observations: {
+      list: string;
+      kind: string;
+      agent?: AgentSnapshotPayload;
+      agentId?: string;
+    }[] = [];
+    for (const [list, statuses] of [
+      ["running", ["running", "initializing", "error"]],
+      ["done", ["idle", "closed"]],
+    ] as const) {
+      const result = await ctx.client.fetchAgents({
+        filter: { statuses: [...statuses] },
+        subscribe: {},
+      });
+      result.subscription.subscribe({
+        snapshot() {},
+        update(message) {
+          observations.push({ list, ...message.payload });
+        },
+      });
+    }
+    const agent = await ctx.client.createAgent({
+      workspaceId: workspace.workspace.id,
+      provider: "mock",
+      cwd: ctx.daemon.staticDir,
+      initialPrompt: "Work on this task",
+    });
+    await expect
+      .poll(() => observations.filter((row) => row.agent?.id === agent.id).length)
+      .toBeGreaterThan(1);
+    // Fetching provides a round trip after creation so its queued update reaches the client.
+    expect((await ctx.client.fetchAgent({ agentId: agent.id }))?.agent.status).toBe("running");
+    const relevant = observations.filter(
+      (row) => row.agent?.id === agent.id || row.agentId === agent.id,
+    );
+    const firstRunning = relevant.findIndex((row) => row.agent?.status === "running");
+    expect(firstRunning).toBeGreaterThanOrEqual(0);
+    expect(
+      relevant.slice(firstRunning).filter((row) => row.list === "done" && row.kind === "upsert"),
+    ).toEqual([]);
+    const timestamps = relevant.flatMap((row) =>
+      row.agent ? [Date.parse(row.agent.updatedAt)] : [],
+    );
+    expect(timestamps).toEqual([...timestamps].sort((a, b) => a - b));
+  } finally {
+    await ctx.cleanup();
+  }
+}, 60_000);
diff --git a/packages/server/src/server/daemon-e2e/daemon-restart-resume.e2e.test.ts b/packages/server/src/server/daemon-e2e/daemon-restart-resume.e2e.test.ts
index 1658356eed..ebe47893b3 100644
--- a/packages/server/src/server/daemon-e2e/daemon-restart-resume.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/daemon-restart-resume.e2e.test.ts
@@ -134,7 +134,7 @@ test.each([false, true])(
     let client: DaemonClient | undefined;
     let mcp: Client | undefined;
     try {
-      const first = await restartFixture(root);
+      const first = await restartFixture(root, { resumeOnStartup: true });
       processes.push(first.child);
       client = new DaemonClient({ url: `ws://127.0.0.1:${first.port}/ws`, appVersion: "0.13.0" });
       await client.connect();
@@ -182,7 +182,7 @@ test.each([false, true])(
       await client.close();
       client = undefined;
       await stopFixture(first.child, abrupt);
-      const second = await restartFixture(root);
+      const second = await restartFixture(root, { resumeOnStartup: true });
       processes.push(second.child);
       await expect.poll(() => readPrompts(root), { timeout: 15000 }).toHaveLength(1);
       const prompts = await readPrompts(root);
@@ -222,7 +222,7 @@ test.each([false, true])(
       await client.close();
       client = undefined;
       await stopFixture(second.child, false);
-      const third = await restartFixture(root);
+      const third = await restartFixture(root, { resumeOnStartup: true });
       processes.push(third.child);
       expect(await readPrompts(root)).toHaveLength(1);
       expect(
@@ -243,7 +243,7 @@ test.each([false, true])(
   60000,
 );
 
-test.each([false, true])(
+test.each([undefined, false, true])(
   "host restart recovery settings (enabled=%s)",
   async (enabled) => {
     const root = await mkdtemp(path.join(tmpdir(), "resume-settings-process-"));
@@ -314,7 +314,7 @@ test("a provider that is slow to reopen does not hold daemon startup", async ()
   const processes: ChildProcess[] = [];
   let client: DaemonClient | undefined;
   try {
-    const first = await restartFixture(root);
+    const first = await restartFixture(root, { resumeOnStartup: true });
     processes.push(first.child);
     client = new DaemonClient({ url: `ws://127.0.0.1:${first.port}/ws`, appVersion: "0.13.0" });
     await client.connect();
@@ -338,7 +338,7 @@ test("a provider that is slow to reopen does not hold daemon startup", async ()
     client = undefined;
     await stopFixture(first.child, false);
 
-    const second = await restartFixture(root, {}, { holdResume: true });
+    const second = await restartFixture(root, { resumeOnStartup: true }, { holdResume: true });
     processes.push(second.child);
     client = new DaemonClient({ url: `ws://127.0.0.1:${second.port}/ws`, appVersion: "0.13.0" });
     await client.connect();
diff --git a/packages/server/src/server/daemon-e2e/file-download.e2e.test.ts b/packages/server/src/server/daemon-e2e/file-download.e2e.test.ts
index 862923dec6..54ec1964c1 100644
--- a/packages/server/src/server/daemon-e2e/file-download.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/file-download.e2e.test.ts
@@ -102,53 +102,52 @@ describe("daemon E2E", () => {
       },
     );
 
-    test.each([
-      { fileName: "download.txt", disposition: 'attachment; filename="download.txt"' },
-      {
-        fileName: "café.txt",
-        disposition: "attachment; filename=\"caf?.txt\"; filename*=UTF-8''caf%C3%A9.txt",
-      },
-      {
-        fileName: "中文报告 (最终版).txt",
-        disposition:
-          "attachment; filename=\"???? (???).txt\"; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%8A%A5%E5%91%8A%20%28%E6%9C%80%E7%BB%88%E7%89%88%29.txt",
-      },
-      {
-        fileName: "報告書.md",
-        disposition:
-          "attachment; filename=\"???.md\"; filename*=UTF-8''%E5%A0%B1%E5%91%8A%E6%9B%B8.md",
-      },
-      {
-        fileName: "보고서.txt",
-        disposition:
-          "attachment; filename=\"???.txt\"; filename*=UTF-8''%EB%B3%B4%EA%B3%A0%EC%84%9C.txt",
-      },
-      {
-        fileName: "report-📄.txt",
-        disposition:
-          "attachment; filename=\"report-??.txt\"; filename*=UTF-8''report-%F0%9F%93%84.txt",
-      },
-    ])(
-      "issues token over WS and downloads $fileName via HTTP",
-      async ({ fileName, disposition }) => {
-        const cwd = tmpCwd();
-        try {
+    test("downloads ASCII and Unicode filenames through one workspace", async () => {
+      const cwd = tmpCwd();
+      try {
+        const agent = await ctx.client.createAgent({
+          provider: "codex",
+          model: CODEX_TEST_MODEL,
+          thinkingOptionId: CODEX_TEST_THINKING_OPTION_ID,
+          cwd,
+          title: "Download Token Test Agent",
+        });
+
+        expect(agent.id).toMatch(
+          /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+        );
+
+        for (const { fileName, disposition } of [
+          { fileName: "download.txt", disposition: 'attachment; filename="download.txt"' },
+          {
+            fileName: "café.txt",
+            disposition: "attachment; filename=\"caf?.txt\"; filename*=UTF-8''caf%C3%A9.txt",
+          },
+          {
+            fileName: "中文报告 (最终版).txt",
+            disposition:
+              "attachment; filename=\"???? (???).txt\"; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%8A%A5%E5%91%8A%20%28%E6%9C%80%E7%BB%88%E7%89%88%29.txt",
+          },
+          {
+            fileName: "報告書.md",
+            disposition:
+              "attachment; filename=\"???.md\"; filename*=UTF-8''%E5%A0%B1%E5%91%8A%E6%9B%B8.md",
+          },
+          {
+            fileName: "보고서.txt",
+            disposition:
+              "attachment; filename=\"???.txt\"; filename*=UTF-8''%EB%B3%B4%EA%B3%A0%EC%84%9C.txt",
+          },
+          {
+            fileName: "report-📄.txt",
+            disposition:
+              "attachment; filename=\"report-??.txt\"; filename*=UTF-8''report-%F0%9F%93%84.txt",
+          },
+        ]) {
           const filePath = path.join(cwd, fileName);
-          const fileContents = "download test payload";
+          const fileContents = `download test payload: ${fileName}`;
           writeFileSync(filePath, fileContents, "utf-8");
 
-          const agent = await ctx.client.createAgent({
-            provider: "codex",
-            model: CODEX_TEST_MODEL,
-            thinkingOptionId: CODEX_TEST_THINKING_OPTION_ID,
-            cwd,
-            title: "Download Token Test Agent",
-          });
-
-          expect(agent.id).toMatch(
-            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-          );
-
           const tokenResponse = await ctx.client.requestDownloadToken(cwd, fileName);
 
           expect(tokenResponse.error).toBeNull();
@@ -167,12 +166,11 @@ describe("daemon E2E", () => {
 
           const body = await response.text();
           expect(body).toBe(fileContents);
-        } finally {
-          rmSync(cwd, { recursive: true, force: true });
         }
-      },
-      60000,
-    );
+      } finally {
+        rmSync(cwd, { recursive: true, force: true });
+      }
+    }, 60000);
 
     test("rejects invalid token", async () => {
       const response = await fetch(
diff --git a/packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts b/packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts
index da52c4dac4..068e0628d0 100644
--- a/packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts
@@ -690,6 +690,7 @@ describe("commit file diffs", () => {
     expect(result).toEqual({
       file: {
         path: filePath,
+        status: "ok",
         isNew: false,
         isDeleted: false,
         additions: 1,
diff --git a/packages/server/src/server/daemon-e2e/fx-fixture.cjs b/packages/server/src/server/daemon-e2e/fx-fixture.cjs
new file mode 100644
index 0000000000..b702ac6c4f
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/fx-fixture.cjs
@@ -0,0 +1,44 @@
+// Local ACP peer shaped like `fx acp` 0.0.16; no fx install or credentials.
+const fs = require("node:fs");
+const readline = require("node:readline");
+fs.appendFileSync(process.env.FX_TEST_RECORD, "launch\n");
+let model = "fixture-small";
+const modes = {
+  currentModeId: "auto",
+  availableModes: [
+    { id: "auto", name: "Auto" },
+    { id: "ask", name: "Ask" },
+    { id: "full-access", name: "Full access" },
+  ],
+};
+const select = (id, name, category, currentValue, values) => ({
+  id,
+  name,
+  category,
+  type: "select",
+  currentValue,
+  options: values.map((value) => ({ value, name: value })),
+});
+const configOptions = () => [
+  select("provider", "Provider", "model", "gateway", ["gateway", "codex", "grok"]),
+  select("model", "Model", "model", model, ["fixture-small", "fixture-large"]),
+  select("mode", "Session Mode", "mode", modes.currentModeId, ["auto", "ask", "full-access"]),
+  select("fast", "Fast Mode", "model", "false", ["false", "true"]),
+];
+const send = (message) =>
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...message }) + "\n");
+readline.createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line);
+  if (request.id === undefined) return;
+  let result = {};
+  if (request.method === "initialize")
+    result = { protocolVersion: 1, agentCapabilities: {}, authMethods: [] };
+  if (request.method === "session/new")
+    result = { sessionId: "fx-fixture", modes, configOptions: configOptions() };
+  if (request.method === "session/set_config_option") {
+    if (request.params.configId === "model") model = request.params.value;
+    result = { configOptions: configOptions() };
+  }
+  if (request.method === "session/prompt") result = { stopReason: "end_turn" };
+  send({ id: request.id, result });
+});
diff --git a/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts b/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts
index 9eb1ff929a..7ab7abeb83 100644
--- a/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/live-preferences.e2e.test.ts
@@ -2,7 +2,6 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import path from "path";
-import { execFileSync } from "node:child_process";
 import { createDaemonTestContext, type DaemonTestContext } from "../test-utils/index.js";
 import type { AgentSnapshotPayload, SessionOutboundMessage } from "../messages.js";
 
@@ -39,13 +38,13 @@ function waitForAgentUpdate(
   });
 }
 
+// The daemon only switches to a model the provider lists.
 function pickModelSwitchPair(provider: string, models: Array<{ id: string }>): [string, string] {
-  const ids = Array.from(new Set(models.map((m) => m.id))).filter(Boolean);
-  const first = ids[0];
-  if (!first) {
-    throw new Error(`No models returned for provider ${provider}`);
+  const [first, second] = Array.from(new Set(models.map((m) => m.id))).filter(Boolean);
+  if (!first || !second) {
+    throw new Error(`Provider ${provider} lists fewer than two models`);
   }
-  return [first, ids[1] ?? `${first}-switch-target`];
+  return [first, second];
 }
 
 function pickThinkingSwitchOption(
@@ -55,13 +54,10 @@ function pickThinkingSwitchOption(
     defaultThinkingOptionId?: string;
   }>,
 ): { model: (typeof models)[number]; thinkingOptionId: string } {
+  // The daemon only switches to a thinking option the model lists.
   const modelWithOptions = models.find((m) => (m.thinkingOptions?.length ?? 0) > 0);
   if (!modelWithOptions) {
-    const first = models[0];
-    if (!first) {
-      throw new Error(`No ${provider} models returned`);
-    }
-    return { model: first, thinkingOptionId: "test-thinking-option" };
+    throw new Error(`No ${provider} model lists thinking options`);
   }
 
   const defaultThinkingId = modelWithOptions.defaultThinkingOptionId ?? "default";
@@ -74,18 +70,6 @@ function pickThinkingSwitchOption(
   return { model: modelWithOptions, thinkingOptionId };
 }
 
-function isBinaryInstalled(binary: string): boolean {
-  try {
-    const out = execFileSync("which", [binary], { encoding: "utf8" }).trim();
-    return out.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-const hasCodex = isBinaryInstalled("codex");
-const hasOpenCode = isBinaryInstalled("opencode");
-
 let ctx: DaemonTestContext;
 let messages: SessionOutboundMessage[] = [];
 let unsubscribe: (() => void) | null = null;
@@ -105,154 +89,137 @@ afterEach(async () => {
 }, 60000);
 
 describe.each(["claude", "codex", "opencode"] as const)("live model switching (%s)", (provider) => {
-  const shouldRun =
-    provider === "claude" ||
-    (provider === "codex" && hasCodex) ||
-    (provider === "opencode" && hasOpenCode);
-
-  test.runIf(shouldRun)(
-    "updates agent model without restarting",
-    async () => {
-      const cwd = tmpCwd();
-      try {
-        const modelList = await ctx.client.listProviderModels(provider);
-        if (!modelList.models || modelList.models.length === 0) {
-          throw new Error(`No models returned for provider ${provider}`);
-        }
-        const [modelA, modelB] = pickModelSwitchPair(provider, modelList.models);
-
-        const agent = await ctx.client.createAgent({
-          provider,
-          cwd,
-          title: `Model Switch (${provider})`,
-          model: modelA,
-        });
-
-        const startIndex = messages.length;
-        await ctx.client.setAgentModel(agent.id, modelB);
-
-        const updated = await waitForAgentUpdate(
-          messages,
-          startIndex,
-          (a) => a.id === agent.id && a.model === modelB,
-          { timeoutMs: 20000 },
-        );
-
-        expect(updated.model).toBe(modelB);
-      } finally {
-        rmSync(cwd, { recursive: true, force: true });
+  test("updates agent model without restarting", async () => {
+    const cwd = tmpCwd();
+    try {
+      const modelList = await ctx.client.listProviderModels(provider);
+      if (!modelList.models || modelList.models.length === 0) {
+        throw new Error(`No models returned for provider ${provider}`);
       }
-    },
-    180000,
-  );
+      const [modelA, modelB] = pickModelSwitchPair(provider, modelList.models);
+
+      const agent = await ctx.client.createAgent({
+        provider,
+        cwd,
+        title: `Model Switch (${provider})`,
+        model: modelA,
+      });
+
+      const startIndex = messages.length;
+      await ctx.client.setAgentModel(agent.id, modelB);
+
+      const updated = await waitForAgentUpdate(
+        messages,
+        startIndex,
+        (a) => a.id === agent.id && a.model === modelB,
+        { timeoutMs: 20000 },
+      );
+
+      expect(updated.model).toBe(modelB);
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  }, 180000);
 });
 
-test("live thinking switching works for Claude (off -> on)", async () => {
+test("live thinking switching works for Claude (default -> non-default)", async () => {
   const cwd = tmpCwd();
   try {
     const modelList = await ctx.client.listProviderModels("claude");
     if (!modelList.models || modelList.models.length === 0) {
       throw new Error("No Claude models returned");
     }
-    const modelId = modelList.models[0].id;
+    const { model, thinkingOptionId } = pickThinkingSwitchOption("Claude", modelList.models);
 
     const agent = await ctx.client.createAgent({
       provider: "claude",
       cwd,
       title: "Claude Thinking Switch",
-      model: modelId,
+      model: model.id,
     });
 
     const startIndex = messages.length;
-    await ctx.client.setAgentThinkingOption(agent.id, "on");
+    await ctx.client.setAgentThinkingOption(agent.id, thinkingOptionId);
 
     const updated = await waitForAgentUpdate(
       messages,
       startIndex,
-      (a) => a.id === agent.id && a.thinkingOptionId === "on",
+      (a) => a.id === agent.id && a.thinkingOptionId === thinkingOptionId,
       { timeoutMs: 20000 },
     );
 
-    expect(updated.thinkingOptionId).toBe("on");
+    expect(updated.thinkingOptionId).toBe(thinkingOptionId);
   } finally {
     rmSync(cwd, { recursive: true, force: true });
   }
 }, 120000);
 
-test.runIf(hasCodex)(
-  "live thinking switching works for Codex (default -> non-default)",
-  async () => {
-    const cwd = tmpCwd();
-    try {
-      const modelList = await ctx.client.listProviderModels("codex");
-      if (!modelList.models || modelList.models.length === 0) {
-        throw new Error("No Codex models returned");
-      }
-
-      const { model: modelWithOptions, thinkingOptionId } = pickThinkingSwitchOption(
-        "Codex",
-        modelList.models,
-      );
-
-      const agent = await ctx.client.createAgent({
-        provider: "codex",
-        cwd,
-        title: "Codex Thinking Switch",
-        model: modelWithOptions.id,
-      });
-
-      const startIndex = messages.length;
-      await ctx.client.setAgentThinkingOption(agent.id, thinkingOptionId);
-
-      const updated = await waitForAgentUpdate(
-        messages,
-        startIndex,
-        (a) => a.id === agent.id && a.thinkingOptionId === thinkingOptionId,
-        { timeoutMs: 20000 },
-      );
-
-      expect(updated.thinkingOptionId).toBe(thinkingOptionId);
-    } finally {
-      rmSync(cwd, { recursive: true, force: true });
+test("live thinking switching works for Codex (default -> non-default)", async () => {
+  const cwd = tmpCwd();
+  try {
+    const modelList = await ctx.client.listProviderModels("codex");
+    if (!modelList.models || modelList.models.length === 0) {
+      throw new Error("No Codex models returned");
     }
-  },
-  120000,
-);
 
-test.runIf(hasOpenCode)(
-  "live thinking switching works for OpenCode",
-  async () => {
-    const cwd = tmpCwd();
-    try {
-      const modelList = await ctx.client.listProviderModels("opencode");
-      if (!modelList.models || modelList.models.length === 0) {
-        throw new Error("No OpenCode models returned");
-      }
+    const { model: modelWithOptions, thinkingOptionId } = pickThinkingSwitchOption(
+      "Codex",
+      modelList.models,
+    );
 
-      const { model: modelWithThinkingOptions, thinkingOptionId } = pickThinkingSwitchOption(
-        "OpenCode",
-        modelList.models,
-      );
+    const agent = await ctx.client.createAgent({
+      provider: "codex",
+      cwd,
+      title: "Codex Thinking Switch",
+      model: modelWithOptions.id,
+    });
 
-      const agent = await ctx.client.createAgent({
-        provider: "opencode",
-        cwd,
-        title: "OpenCode Preferences Switch",
-        model: modelWithThinkingOptions.id,
-      });
+    const startIndex = messages.length;
+    await ctx.client.setAgentThinkingOption(agent.id, thinkingOptionId);
 
-      const startIndex = messages.length;
-      await ctx.client.setAgentThinkingOption(agent.id, thinkingOptionId);
-      const updatedThinking = await waitForAgentUpdate(
-        messages,
-        startIndex,
-        (a) => a.id === agent.id && a.thinkingOptionId === thinkingOptionId,
-        { timeoutMs: 20000 },
-      );
-      expect(updatedThinking.thinkingOptionId).toBe(thinkingOptionId);
-    } finally {
-      rmSync(cwd, { recursive: true, force: true });
+    const updated = await waitForAgentUpdate(
+      messages,
+      startIndex,
+      (a) => a.id === agent.id && a.thinkingOptionId === thinkingOptionId,
+      { timeoutMs: 20000 },
+    );
+
+    expect(updated.thinkingOptionId).toBe(thinkingOptionId);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 120000);
+
+test("live thinking switching works for OpenCode", async () => {
+  const cwd = tmpCwd();
+  try {
+    const modelList = await ctx.client.listProviderModels("opencode");
+    if (!modelList.models || modelList.models.length === 0) {
+      throw new Error("No OpenCode models returned");
     }
-  },
-  180000,
-);
+
+    const { model: modelWithThinkingOptions, thinkingOptionId } = pickThinkingSwitchOption(
+      "OpenCode",
+      modelList.models,
+    );
+
+    const agent = await ctx.client.createAgent({
+      provider: "opencode",
+      cwd,
+      title: "OpenCode Preferences Switch",
+      model: modelWithThinkingOptions.id,
+    });
+
+    const startIndex = messages.length;
+    await ctx.client.setAgentThinkingOption(agent.id, thinkingOptionId);
+    const updatedThinking = await waitForAgentUpdate(
+      messages,
+      startIndex,
+      (a) => a.id === agent.id && a.thinkingOptionId === thinkingOptionId,
+      { timeoutMs: 20000 },
+    );
+    expect(updatedThinking.thinkingOptionId).toBe(thinkingOptionId);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 180000);
diff --git a/packages/server/src/server/daemon-e2e/models.e2e.test.ts b/packages/server/src/server/daemon-e2e/models.e2e.test.ts
index cfa420654b..a2064da0f1 100644
--- a/packages/server/src/server/daemon-e2e/models.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/models.e2e.test.ts
@@ -164,6 +164,46 @@ test("Antigravity creates an agent and answers a prompt with real agy", async ({
   }
 }, 120000);
 
+test("bundled fx requires a config entry and lists models instead of its providers", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "paseo-fx-optin-"));
+  const record = path.join(root, "launches.txt");
+  await writeFile(record, "");
+  const daemon = await createTestPaseoDaemon({
+    paseoHomeRoot: root,
+    cleanup: false,
+    mcpEnabled: false,
+    builtinPlugins: new BuiltinPluginLoader(undefined, ["fx-provider"]),
+  });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    appVersion: "0.15.3",
+  });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    expect(client.getLastServerInfoMessage()?.features?.fxProvider).toBe(true);
+    const before = await client.getProvidersSnapshot();
+    expect(before.entries.some((entry) => entry.provider === "fx")).toBe(false);
+    expect(await readFile(record, "utf8")).toBe("");
+
+    await client.patchDaemonConfig({
+      providers: {
+        fx: {
+          enabled: true,
+          command: [process.execPath, path.resolve(import.meta.dirname, "fx-fixture.cjs")],
+          env: { FX_TEST_RECORD: record },
+        },
+      },
+    });
+    const { models } = await client.listProviderModels("fx", { cwd: root });
+    expect(models.map((model) => model.id)).toEqual(["fixture-small", "fixture-large"]);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true });
+  }
+}, 60000);
+
 test("bundled Hoplite requires a config entry and removal survives restart", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "paseo-hoplite-optin-"));
   const record = path.join(root, "launches.txt");
diff --git a/packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts b/packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts
index e03c66bca0..db278d0249 100644
--- a/packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts
@@ -46,7 +46,7 @@ describe("daemon E2E (real opencode) - initial prompt wait", () => {
     }
   });
 
-  test("waitForFinish does not resolve before an initial prompt using opencode/big-pickle actually completes", async () => {
+  test("waitForFinish does not resolve before an OpenCode initial prompt completes", async () => {
     const cwd = tmpCwd();
     const { client, daemon } = await createHarness();
 
diff --git a/packages/server/src/server/daemon-e2e/peer-message-permissions.test.ts b/packages/server/src/server/daemon-e2e/peer-message-permissions.test.ts
new file mode 100644
index 0000000000..bc2803a65e
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/peer-message-permissions.test.ts
@@ -0,0 +1,129 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import type { FormInfo } from "@opencode/client";
+import { expect, test } from "vitest";
+
+import { createTestLogger } from "../../test-utils/test-logger.js";
+import { OpenCodeV2AgentClient } from "../agent/providers/opencode/v2/agent.js";
+import { V2Harness } from "../agent/providers/opencode/test-utils/v2-harness.js";
+import { createTestAgentClients } from "../test-utils/fake-agent-client.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+import { DaemonClient } from "../test-utils/daemon-client.js";
+
+async function createQuestionHarness() {
+  const artifacts = path.resolve(".artifacts");
+  await mkdir(artifacts, { recursive: true });
+  const root = await mkdtemp(path.join(artifacts, "peer-permissions-"));
+  const runtime = new V2Harness();
+  runtime.autoComplete = false;
+  runtime.api.model.list = async () => ({ location: runtime.info.location, data: [] });
+  runtime.api.provider.list = async () => ({
+    location: runtime.info.location,
+    data: [{ id: "test", name: "Test", activation: "enabled", package: "test" }],
+  });
+  let form: FormInfo | null = null;
+  const answers: Array<Record<string, unknown>> = [];
+  runtime.api.session.form.list = async () => (form ? [form] : []);
+  runtime.api.session.form.cancel = async () => {
+    form = null;
+    runtime.finishExecution("interrupted");
+  };
+  runtime.api.session.form.reply = async ({ answer }) => {
+    answers.push(answer);
+    form = null;
+    runtime.finishExecution();
+  };
+  // A steer is admitted to the existing execution, rather than starting another one.
+  runtime.prompt = async (input) => {
+    runtime.prompts.push(input.text);
+    if (runtime.prompts.length === 1) runtime.startExecution();
+  };
+  const provider = new OpenCodeV2AgentClient({
+    logger: createTestLogger(),
+    runtime: runtime.runtime,
+  });
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { ...createTestAgentClients(), opencode: provider },
+    paseoHomeRoot: path.join(root, "daemon"),
+    staticDir: path.join(root, "static"),
+    cleanup: false,
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const recipient = await client.createAgent({
+      provider: "opencode",
+      cwd: root,
+      title: "Waiting for a human answer",
+    });
+    const sender = await client.createAgent({ provider: "claude", cwd: root });
+    await client.sendMessage(recipient.id, "Ask which color to use");
+    await expect.poll(() => runtime.prompts).toHaveLength(1);
+    form = {
+      id: "color-question",
+      sessionID: "session",
+      title: "Color",
+      fields: [{ key: "color", title: "Color", type: "string" }],
+    };
+    runtime.push({ id: "question-created", created: 2, type: "form.created", data: { form } });
+    await client.waitForAgentUpsert(recipient.id, (agent) =>
+      (agent.pendingPermissions ?? []).some((request) => request.id === "color-question"),
+    );
+    return {
+      client,
+      recipient,
+      sender,
+      answers,
+      async close() {
+        await client.close();
+        await daemon.close();
+        await rm(root, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+test("an agent-sourced steer leaves the question pending and answerable", async () => {
+  const { client, recipient, sender, answers, close } = await createQuestionHarness();
+  try {
+    await client.sendAgentMessage(recipient.id, "Peer status check", {
+      sourceAgentId: sender.id,
+    });
+    // The public wait includes admitted message delivery before reporting permission status.
+    const waiting = await client.waitForFinish(recipient.id);
+    expect(waiting.status).toBe("permission");
+    expect(waiting.final?.pendingPermissions).toMatchObject([
+      { id: "color-question", kind: "question" },
+    ]);
+    await client.respondToPermission(recipient.id, "color-question", {
+      behavior: "allow",
+      updatedInput: { answers: { Color: "Blue" } },
+    });
+    await client.waitForAgentUpsert(
+      recipient.id,
+      (agent) => (agent.pendingPermissions ?? []).length === 0 && agent.status === "idle",
+    );
+    expect(answers).toEqual([{ color: "Blue" }]);
+  } finally {
+    await close();
+  }
+});
+
+test("a human steer still dismisses the question", async () => {
+  const { client, recipient, answers, close } = await createQuestionHarness();
+  try {
+    await client.sendAgentMessage(recipient.id, "Use red instead", { activeTurnBehavior: "steer" });
+    const finished = await client.waitForFinish(recipient.id);
+    expect(finished.status).toBe("idle");
+    expect(finished.final?.pendingPermissions ?? []).toEqual([]);
+    expect(answers).toEqual([]);
+  } finally {
+    await close();
+  }
+});
diff --git a/packages/server/src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts b/packages/server/src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts
new file mode 100644
index 0000000000..f79abd0c05
--- /dev/null
+++ b/packages/server/src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts
@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import { createDaemonTestContext, type DaemonTestContext } from "../test-utils/index.js";
+
+test.each(["agent", "workspace"] as const)(
+  "%s creation recognizes an unopened persisted caller after restart",
+  async (kind) => {
+    const artifacts = path.resolve(".artifacts");
+    await mkdir(artifacts, { recursive: true });
+    const root = await mkdtemp(path.join(artifacts, "persisted-caller-"));
+    const cwd = path.join(root, "project");
+    await mkdir(cwd);
+    let ctx: DaemonTestContext | undefined;
+    try {
+      ctx = await createDaemonTestContext({
+        paseoHomeRoot: root,
+        staticDir: cwd,
+        cleanup: false,
+        mcpEnabled: false,
+      });
+      const parent = await ctx.client.createAgent({ provider: "claude", cwd, background: true });
+      await ctx.client.sendMessage(parent.id, "Reply DONE.");
+      expect((await ctx.client.waitForFinish(parent.id, 5_000)).status).toBe("idle");
+      await ctx.cleanup();
+      ctx = undefined;
+      ctx = await createDaemonTestContext({
+        paseoHomeRoot: root,
+        staticDir: cwd,
+        cleanup: false,
+        mcpEnabled: false,
+      });
+      expect(ctx.daemon.daemon.agentManager.getAgent(parent.id)).toBeNull();
+      expect(
+        (await ctx.client.fetchAgents({ filter: { includeBackground: true } })).entries,
+      ).toContainEqual(
+        expect.objectContaining({ agent: expect.objectContaining({ id: parent.id }) }),
+      );
+
+      if (kind === "agent") {
+        const child = await ctx.client.createAgent({
+          provider: "claude",
+          cwd,
+          callerAgentId: parent.id,
+        });
+        expect(child.workspaceId).toBe(parent.workspaceId);
+        expect(child.labels[PARENT_AGENT_ID_LABEL]).toBe(parent.id);
+      } else {
+        const result = await ctx.client.createWorkspace({
+          source: { kind: "directory", path: cwd },
+          callerAgentId: parent.id,
+        });
+        expect(result.error).toBeNull();
+        expect(result.workspace?.background).toBe(true);
+      }
+      expect(ctx.daemon.daemon.agentManager.getAgent(parent.id)).toBeNull();
+    } finally {
+      await ctx?.cleanup();
+      await rm(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+  },
+  60_000,
+);
+
+test("creation still rejects a caller removed by workspace archive", async () => {
+  const artifacts = path.resolve(".artifacts");
+  await mkdir(artifacts, { recursive: true });
+  const root = await mkdtemp(path.join(artifacts, "archived-caller-"));
+  const cwd = path.join(root, "project");
+  await mkdir(cwd);
+  execFileSync("git", ["init", cwd], { stdio: "pipe" });
+  const ctx = await createDaemonTestContext({
+    paseoHomeRoot: root,
+    staticDir: cwd,
+    cleanup: false,
+    mcpEnabled: false,
+  });
+  try {
+    const parent = await ctx.client.createAgent({ provider: "claude", cwd });
+    const archived = await ctx.client.archiveWorkspace(parent.workspaceId);
+    expect(archived.error).toBeNull();
+    expect(ctx.daemon.daemon.agentManager.getAgent(parent.id)).toBeNull();
+    await expect(
+      ctx.client.createAgent({ provider: "claude", cwd, callerAgentId: parent.id }),
+    ).rejects.toThrow(`Caller agent ${parent.id} not found`);
+  } finally {
+    await ctx.cleanup();
+    await rm(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}, 60_000);
diff --git a/packages/server/src/server/daemon-e2e/pi-rewind.real.e2e.test.ts b/packages/server/src/server/daemon-e2e/pi-rewind.real.e2e.test.ts
index d198be9e09..704243d503 100644
--- a/packages/server/src/server/daemon-e2e/pi-rewind.real.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/pi-rewind.real.e2e.test.ts
@@ -1,5 +1,7 @@
 import { mkdtempSync, rmSync } from "node:fs";
-import { readdir } from "node:fs/promises";
+import { readdir, mkdir, mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { PiRpcAgentClient } from "../agent/providers/pi/agent.js";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import pino from "pino";
@@ -366,3 +368,213 @@ describe("daemon E2E (real pi) - rewind", () => {
     }
   }, 900_000);
 });
+
+test("seeded compacted Pi history survives daemon reload, native rewind and Fork chat", async (context) => {
+  if (!(await canRunRealProvider("pi"))) {
+    context.skip();
+    return;
+  }
+  const artifacts = path.resolve(".artifacts/pi-timeline");
+  await mkdir(artifacts, { recursive: true });
+  const root = await mkdtemp(path.join(artifacts, "daemon-history-"));
+  const cwd = path.join(root, "cwd");
+  await mkdir(cwd);
+  const file = path.join(root, "session.jsonl");
+  const nativeId = randomUUID();
+  const timestamp = new Date().toISOString();
+  const assistant = (text: string) => ({
+    role: "assistant",
+    content: [{ type: "text", text }],
+    api: "openai-completions",
+    provider: "openrouter",
+    model: "google/gemini-2.5-flash-lite",
+    stopReason: "stop",
+    timestamp: Date.now(),
+    usage: {
+      input: 1,
+      output: 1,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 2,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+  });
+  const records = [
+    { type: "session", version: 3, id: nativeId, cwd, timestamp },
+    {
+      type: "message",
+      id: "system",
+      parentId: null,
+      timestamp,
+      message: {
+        role: "system",
+        content: [{ type: "text", text: "private system context" }],
+        timestamp: Date.now(),
+      },
+    },
+    {
+      type: "message",
+      id: "u1",
+      parentId: "system",
+      timestamp,
+      message: { role: "user", content: "old question", timestamp: Date.now() },
+    },
+    {
+      type: "message",
+      id: "tool-request",
+      parentId: "u1",
+      timestamp,
+      message: {
+        ...assistant(""),
+        content: [
+          { type: "toolCall", id: "read-call", name: "read", arguments: { path: "readme.txt" } },
+        ],
+      },
+    },
+    {
+      type: "message",
+      id: "tool-result",
+      parentId: "tool-request",
+      timestamp,
+      message: {
+        role: "toolResult",
+        toolCallId: "read-call",
+        toolName: "read",
+        content: [{ type: "text", text: "saved tool output" }],
+        isError: false,
+        timestamp: Date.now(),
+      },
+    },
+    {
+      type: "message",
+      id: "a1",
+      parentId: "tool-result",
+      timestamp,
+      message: assistant("old answer"),
+    },
+    {
+      type: "message",
+      id: "abandoned",
+      parentId: "a1",
+      timestamp,
+      message: { role: "user", content: "abandoned question", timestamp: Date.now() },
+    },
+    {
+      type: "compaction",
+      id: "compact",
+      parentId: "a1",
+      timestamp,
+      summary: "old summary",
+      firstKeptEntryId: null,
+      tokensBefore: 50000,
+    },
+    {
+      type: "message",
+      id: "u2",
+      parentId: "compact",
+      timestamp,
+      message: { role: "user", content: "follow up", timestamp: Date.now() },
+    },
+    { type: "message", id: "a2", parentId: "u2", timestamp, message: assistant("new answer") },
+  ];
+  await writeFile(file, records.map((record) => JSON.stringify(record)).join("\n") + "\n");
+  const logger = pino({ level: "silent" });
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { pi: new PiRpcAgentClient({ logger }) },
+    logger,
+    paseoHomeRoot: path.join(root, "home"),
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const imported = await client.importAgent({ provider: "pi", sessionId: file, cwd });
+    const session = { agentId: imported.id, cwd };
+    const expected = { userTexts: ["old question", "follow up"], assistantCount: 2 };
+    expectTimeline(await fetchTimelineItems(client, imported.id), expected);
+    expect(
+      userMessageIdForToken(await fetchTimelineItems(client, imported.id), "old question"),
+    ).toBe("u1");
+    expect(userMessageIdForToken(await fetchTimelineItems(client, imported.id), "follow up")).toBe(
+      "u2",
+    );
+    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
+    await client.refreshAgent(imported.id);
+    const restored = await fetchTimelineItems(client, imported.id);
+    expectTimeline(restored, expected);
+    const tools = restored.filter((item) => item.type === "tool_call");
+    expect(tools).toHaveLength(1);
+    expect(tools[0].detail).toEqual({
+      type: "read",
+      filePath: "readme.txt",
+      content: "saved tool output",
+    });
+    expect(
+      restored.filter((item) => item.type === "user_message").map((item) => item.messageId),
+    ).toEqual(["u1", "u2"]);
+    const oldAnswer = restored.find(
+      (item) => item.type === "assistant_message" && item.text === "old answer",
+    );
+    if (oldAnswer?.type !== "assistant_message" || !oldAnswer.messageId)
+      throw new Error("Restored reply missing identity");
+    const beforeFork = await readFile(file, "utf8");
+    const fork = await client.buildAgentForkContext(imported.id, {
+      boundaryMessageId: oldAnswer.messageId,
+    });
+    expect(fork.attachment?.text).toContain("old question");
+    expect(fork.attachment?.text).toContain("old answer");
+    expect(fork.attachment?.text).not.toContain("follow up");
+    expect(fork.attachment?.text).not.toContain("abandoned question");
+    expect(await readFile(file, "utf8")).toBe(beforeFork);
+    const forkFile = path.join(root, "native-fork.jsonl");
+    const forkId = randomUUID();
+    await writeFile(
+      forkFile,
+      [
+        { ...records[0], id: forkId },
+        ...records.slice(1),
+        {
+          type: "custom",
+          id: "fork-leaf",
+          parentId: "a1",
+          timestamp,
+          customType: "paseo_rewind",
+          data: { targetId: "a1" },
+        },
+      ]
+        .map((record) => JSON.stringify(record))
+        .join("\n") + "\n",
+    );
+    const importedFork = await client.importAgent({ provider: "pi", sessionId: forkFile, cwd });
+    expectTimeline(await fetchTimelineItems(client, importedFork.id), {
+      userTexts: ["old question"],
+      assistantCount: 1,
+    });
+    expect(await runtimeSessionId({ client, daemon }, { agentId: importedFork.id, cwd })).toBe(
+      forkId,
+    );
+    expect(await readFile(file, "utf8")).toBe(beforeFork);
+    await client.rewindAgent(imported.id, "u2", "conversation");
+    expectTimeline(await fetchTimelineItems(client, imported.id), {
+      userTexts: ["old question"],
+      assistantCount: 1,
+    });
+    await client.refreshAgent(imported.id);
+    expectTimeline(await fetchTimelineItems(client, imported.id), {
+      userTexts: ["old question"],
+      assistantCount: 1,
+    });
+    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
+    await client.rewindAgent(imported.id, "u1", "conversation");
+    await client.refreshAgent(imported.id);
+    expectTimeline(await fetchTimelineItems(client, imported.id), {
+      userTexts: [],
+      assistantCount: 0,
+    });
+    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(root, { recursive: true, force: true });
+  }
+}, 120_000);
diff --git a/packages/server/src/server/daemon-e2e/real-provider-test-config.ts b/packages/server/src/server/daemon-e2e/real-provider-test-config.ts
index e54b781e65..e15c618fbf 100644
--- a/packages/server/src/server/daemon-e2e/real-provider-test-config.ts
+++ b/packages/server/src/server/daemon-e2e/real-provider-test-config.ts
@@ -26,7 +26,7 @@ const PI_AUTH_CONFIG_PATH = join(homedir(), ".pi", "agent", "auth.json");
 const CODEX_AUTH_CONFIG_PATH = join(homedir(), ".codex", "auth.json");
 const CLAUDE_REAL_TEST_MODEL = "haiku";
 const CODEX_REAL_TEST_MODEL = "~openai/gpt-latest";
-const OPENCODE_REAL_TEST_MODEL = "openrouter/google/gemini-2.5-flash-lite";
+const OPENCODE_REAL_TEST_MODEL = "openrouter/google/gemini-3.5-flash-lite";
 const PI_OPENROUTER_REAL_TEST_MODEL = "openrouter/google/gemini-2.5-flash-lite";
 const PI_CODEX_REAL_TEST_MODEL = "openai-codex/gpt-5.4";
 const OMP_OPENROUTER_REAL_TEST_MODEL = "openrouter/google/gemini-2.5-flash-lite";
diff --git a/packages/server/src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts b/packages/server/src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts
index d606b4d4d9..a9789c906e 100644
--- a/packages/server/src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts
@@ -18,6 +18,7 @@ import { DaemonClient } from "../test-utils/daemon-client.js";
 import { resolveDaemonVersion } from "../daemon-version.js";
 import { readDaemonInstance, stopDaemonInstance } from "../daemon-instance.js";
 import { currentBootId } from "../pid-lock.js";
+import { resolveTerminalWorkerSocketPath } from "../../terminal/terminal-worker-socket-path.js";
 import { connectTerminalWorker } from "../../terminal/terminal-worker-client.js";
 import { createTerminalWorkerProcessInspector } from "../../terminal/terminal-worker-processes.js";
 import { reapTerminalWorkers } from "../../terminal/terminal-worker-reaper.js";
@@ -316,14 +317,6 @@ function spawnUnrelated(): ChildProcess {
   return child;
 }
 
-async function birthOf(pid: number): Promise<string> {
-  const inspection = await inspector.inspect(pid);
-  if (inspection.status !== "alive" || !inspection.snapshot.startedAt) {
-    throw new Error(`no birth time for ${pid}`);
-  }
-  return inspection.snapshot.startedAt;
-}
-
 afterEach(async () => {
   for (const harness of harnesses.splice(0)) {
     const pid = harness.supervisor.pid;
@@ -582,28 +575,26 @@ describe("terminals when the daemon stops", { timeout: 240_000 }, () => {
     const reused = spawnUnrelated();
     const earlierBoot = spawnUnrelated();
     const base = await currentWorkerRecord(harness.home);
-    // Same pid, another birth time: what a reused pid looks like, whatever its command line.
+    // A reused pid with its old record-specific socket gone must never be signaled.
     writeTerminalWorkerRecord(harness.home, {
       ...base,
       recordId: "stale-record",
       pid: reused.pid!,
-      identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "node -e setInterval" },
+      socketPath: resolveTerminalWorkerSocketPath({
+        paseoHome: harness.home,
+        workerPid: reused.pid!,
+        recordId: "stale-record",
+      }),
       terminals: [{ id: "t-stale", pid: reused.pid!, startedAt: "Thu Jan  1 00:00:00 1970" }],
     });
-    // The right birth time, but written before this boot.
+    // Records from an earlier boot are retired before checking any process.
     writeTerminalWorkerRecord(harness.home, {
       ...base,
       recordId: "earlier-boot-record",
       pid: earlierBoot.pid!,
       bootId: currentBootId() ? "another-boot" : null,
       createdAt: "2000-01-01T00:00:00.000Z",
-      identity: {
-        startedAt: await birthOf(earlierBoot.pid!),
-        commandLine: `node --paseo-terminal-worker earlier-boot-record`,
-      },
-      terminals: [
-        { id: "t-boot", pid: earlierBoot.pid!, startedAt: await birthOf(earlierBoot.pid!) },
-      ],
+      terminals: [{ id: "t-boot", pid: earlierBoot.pid!, startedAt: null }],
     });
 
     await stopDaemon(harness);
@@ -616,7 +607,11 @@ describe("terminals when the daemon stops", { timeout: 240_000 }, () => {
       ...base,
       recordId: "stale-record",
       pid: reused.pid!,
-      identity: { startedAt: "Thu Jan  1 00:00:00 1970", commandLine: "node -e setInterval" },
+      socketPath: resolveTerminalWorkerSocketPath({
+        paseoHome: harness.home,
+        workerPid: reused.pid!,
+        recordId: "stale-record",
+      }),
       terminals: [{ id: "t-stale", pid: reused.pid!, startedAt: "Thu Jan  1 00:00:00 1970" }],
     });
     await stopDaemonInstance(harness.home, { force: true });
diff --git a/packages/server/src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts b/packages/server/src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts
index 80c9409cef..b0c38bc985 100644
--- a/packages/server/src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts
+++ b/packages/server/src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts
@@ -1,5 +1,5 @@
 import { resolveDaemonVersion } from "../daemon-version.js";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, expect, test } from "vitest";
@@ -269,3 +269,132 @@ test.runIf(process.platform !== "win32")(
     expect((await sdk.terminals.list({ workspaceId })).entries).toEqual([]);
   },
 );
+
+test("host-wide terminal observation tracks every workspace, metadata and release", async () => {
+  const first = await createWorkspace("Observe first");
+  const second = await createWorkspace("Observe second");
+  expect(client.getLastServerInfoMessage()?.features?.terminalCollection).toBe(true);
+  const observation = client.observeTerminals({});
+  let terminals = (await observation.ready).terminals;
+  const update = observation.subscribe({
+    snapshot: (value) => {
+      terminals = value.terminals;
+    },
+    update: (message) => {
+      if (message.type === "terminals_changed") terminals = message.payload.terminals;
+    },
+  });
+  try {
+    expect(terminals).toEqual([]);
+    const scoped = client.observeTerminals({ workspaceId: first });
+    const scopedSnapshot = await scoped.ready;
+    let owned = scopedSnapshot.terminals;
+    const releaseScoped = scoped.subscribe({
+      snapshot: (value) => {
+        owned = value.terminals;
+      },
+      update: (message) => {
+        if (message.type === "terminals_changed") owned = message.payload.terminals;
+      },
+    });
+    // Use a controlled process: interactive shells publish their own OSC title on startup.
+    const command = {
+      command: process.execPath,
+      args: ["-e", "console.log('READY'); process.stdin.resume()"],
+    };
+    const a = await sdk.terminals.create({
+      workspaceId: first,
+      name: "First terminal",
+      ...command,
+    });
+    const b = await sdk.terminals.create({
+      workspaceId: second,
+      name: "Second terminal",
+      ...command,
+    });
+    await expect
+      .poll(async () => (await a.capture({ stripAnsi: true })).lines.join("\n"))
+      .toContain("READY");
+    await expect
+      .poll(async () => (await b.capture({ stripAnsi: true })).lines.join("\n"))
+      .toContain("READY");
+    await expect.poll(() => terminals.map((item) => item.id).sort()).toEqual([a.id, b.id].sort());
+    expect(terminals.every((item) => item.cwd === cwd && item.createdAt && !item.isScript)).toBe(
+      true,
+    );
+    expect(terminals.map((item) => item.workspaceId).sort()).toEqual([first, second].sort());
+    await expect.poll(() => owned.map((item) => item.id)).toEqual([a.id]);
+    releaseScoped();
+    await scoped.release();
+    await client.renameTerminal({ terminalId: a.id, title: "Renamed terminal" });
+    await expect
+      .poll(() => terminals.find((item) => item.id === a.id)?.title)
+      .toBe("Renamed terminal");
+    await b.kill();
+    await expect.poll(() => terminals.map((item) => item.id)).toEqual([a.id]);
+    await a.kill();
+    await expect.poll(() => terminals).toEqual([]);
+  } finally {
+    update();
+    await observation.release();
+  }
+}, 60_000);
+
+test("terminal collection reports workspace script ownership after runtime registration", async () => {
+  await writeFile(
+    path.join(cwd, "paseo.json"),
+    JSON.stringify({
+      scripts: {
+        sleeper: {
+          type: "script",
+          command: `node -e "const fs = require('node:fs'); fs.writeFileSync('sleeper.pid', String(process.pid)); setInterval(() => { if (fs.existsSync('finish-sleeper')) process.exit(0); }, 50)"`,
+        },
+      },
+    }),
+  );
+  const workspaceId = await createWorkspace("Script observation");
+  const observation = client.observeTerminals({});
+  let terminals = (await observation.ready).terminals;
+  const release = observation.subscribe({
+    snapshot: (value) => {
+      terminals = value.terminals;
+    },
+    update: (message) => {
+      if (message.type === "terminals_changed") terminals = message.payload.terminals;
+    },
+  });
+  try {
+    expect((await client.startWorkspaceScript(workspaceId, "sleeper")).error).toBeNull();
+    await expect
+      .poll(() =>
+        terminals.some((terminal) => terminal.workspaceId === workspaceId && terminal.isScript),
+      )
+      .toBe(true);
+    const terminalId = terminals.find((terminal) => terminal.workspaceId === workspaceId)!.id;
+    const pidFile = path.join(cwd, "sleeper.pid");
+    await expect
+      .poll(async () => Number(await readFile(pidFile, "utf8")), { timeout: 10_000 })
+      .toBeGreaterThan(0);
+    const pid = Number(await readFile(pidFile, "utf8"));
+    await writeFile(path.join(cwd, "finish-sleeper"), "done");
+    await expect.poll(() => isFixtureProcessRunning(pid), { timeout: 10_000 }).toBe(false);
+    // The program has exited; now close its interactive shell as well.
+    await sdk.terminals.ref(terminalId).kill();
+    await expect
+      .poll(() => terminals.filter((terminal) => terminal.workspaceId === workspaceId))
+      .toEqual([]);
+  } finally {
+    release();
+    await observation.release();
+  }
+}, 60_000);
+
+function isFixtureProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
+    throw error;
+  }
+}
diff --git a/packages/server/src/server/diff/batches.ts b/packages/server/src/server/diff/batches.ts
new file mode 100644
index 0000000000..25628eed57
--- /dev/null
+++ b/packages/server/src/server/diff/batches.ts
@@ -0,0 +1,30 @@
+import { encodeDiffFrame, DiffOpcode, type DiffBody } from "@getpaseo/protocol/binary-frames/index";
+
+export async function* packBodies(
+  files: AsyncIterable<DiffBody> | Iterable<DiffBody>,
+  revision: number,
+): AsyncGenerator<DiffBody[]> {
+  let batch: DiffBody[] = [];
+  let size = 0;
+  for await (const file of files) {
+    const bytes = encodeDiffFrame({
+      opcode: DiffOpcode.Bodies,
+      slot: 0,
+      revision,
+      files: [file],
+    }).length;
+    if (batch.length && size + bytes > 256 * 1024) {
+      yield batch;
+      batch = [];
+      size = 0;
+    }
+    batch.push(file);
+    size += bytes;
+    if (size >= 256 * 1024) {
+      yield batch;
+      batch = [];
+      size = 0;
+    }
+  }
+  if (batch.length) yield batch;
+}
diff --git a/packages/server/src/server/diff/dependencies.ts b/packages/server/src/server/diff/dependencies.ts
new file mode 100644
index 0000000000..81b9cd194b
--- /dev/null
+++ b/packages/server/src/server/diff/dependencies.ts
@@ -0,0 +1,92 @@
+import {
+  affectsGitDiffInterpretation,
+  classifyGitMetadataPath,
+  type GitMetadataScope,
+} from "../git-metadata-event-rules.js";
+import { resolve } from "node:path";
+import { runGitCommand } from "../../utils/run-git-command.js";
+import type { WorkspaceGitService } from "../workspace-git-service.js";
+import { createFileObserver, type FileObserverSubscription } from "../file-observer/index.js";
+
+export interface DiffDependencies {
+  cwd: string;
+  refs: string[];
+  index: boolean;
+  worktree: boolean;
+}
+// Own metadata observations here; comparison managers declare inputs rather than watching paths.
+export class DiffDependencyObserver {
+  private observer = createFileObserver();
+  constructor(private workspaceGit: Pick<WorkspaceGitService, "requestWorkingTreeWatch">) {}
+  async declareDependencies(
+    input: DiffDependencies,
+    changed: (kind: "endpoints" | "interpretation") => void,
+  ): Promise<() => Promise<void>> {
+    const hasMutableEndpoints = input.refs.length > 0 || input.index || input.worktree;
+    let polling: ReturnType<typeof setInterval> | null = null;
+    const subscriptions: FileObserverSubscription[] = [];
+    let workingTree: Awaited<ReturnType<WorkspaceGitService["requestWorkingTreeWatch"]>> | null =
+      null;
+    try {
+      const paths = await runGitCommand(["rev-parse", "--absolute-git-dir", "--git-common-dir"], {
+        cwd: input.cwd,
+      });
+      const [gitDir, commonDir] = paths.stdout.split(/\r?\n/);
+      if (!gitDir || !commonDir) throw new Error("Git returned incomplete metadata roots");
+      const roots = new Map<string, GitMetadataScope[]>();
+      for (const [directory, scope] of [
+        [gitDir, "worktree"],
+        [commonDir, "common"],
+      ] as const) {
+        const root = resolve(input.cwd, directory);
+        const scopes = roots.get(root) ?? [];
+        scopes.push(scope);
+        roots.set(root, scopes);
+      }
+      for (const [root, scopes] of roots) {
+        const subscription = await this.observer.subscribe(
+          root,
+          (error, events) => {
+            if (error) {
+              changed("endpoints");
+              polling ??= setInterval(() => changed("endpoints"), 5000);
+              return;
+            }
+            let interpretation = false;
+            const endpoints = events.some((event) => {
+              const path = event.path.slice(root.length + 1).replaceAll("\\", "/");
+              if (scopes.some((scope) => affectsGitDiffInterpretation(scope, path)))
+                interpretation = true;
+              if (!hasMutableEndpoints) return false;
+              if (path === "index") return input.index;
+              return scopes.some((scope) => classifyGitMetadataPath(scope, path).kind !== "ignore");
+            });
+            if (endpoints) changed("endpoints");
+            else if (interpretation) changed("interpretation");
+          },
+          { ignore: [resolve(root, "objects"), resolve(root, "logs"), resolve(root, "hooks")] },
+        );
+        subscriptions.push(subscription);
+      }
+      workingTree = await this.workspaceGit.requestWorkingTreeWatch(input.cwd, () =>
+        changed(input.worktree ? "endpoints" : "interpretation"),
+      );
+      return async () => {
+        if (polling) clearInterval(polling);
+        await workingTree?.unsubscribe();
+        await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe()));
+      };
+    } catch (error) {
+      if (polling) clearInterval(polling);
+      await workingTree?.unsubscribe();
+      await Promise.all(subscriptions.map((subscription) => subscription.unsubscribe()));
+      throw error;
+    }
+  }
+  getObservationCount(): number {
+    return this.observer.getDiagnostics().activeObservationCount;
+  }
+  async close(): Promise<void> {
+    await this.observer.close();
+  }
+}
diff --git a/packages/server/src/server/diff/git.test.ts b/packages/server/src/server/diff/git.test.ts
new file mode 100644
index 0000000000..5c77f80e45
--- /dev/null
+++ b/packages/server/src/server/diff/git.test.ts
@@ -0,0 +1,719 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, readFile, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { expect, test } from "vitest";
+import { listComparison, type Comparison } from "./git.js";
+
+test("working tree comparisons preserve staged deletions whose file remains on disk", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-comparison-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git("rm", "--cached", "x.ts");
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+      highlight: false,
+    });
+    expect(comparison.files.map((file) => file.entry)).toEqual([
+      {
+        path: "x.ts",
+        oldPath: null,
+        change: "modified",
+        content: "text",
+        additions: 1,
+        deletions: 1,
+        body: true,
+      },
+    ]);
+    const body = await readBody(comparison);
+    expect(body.body.hunks[0].lines).toEqual([
+      { type: "header", content: "@@ -1 +1 @@" },
+      { type: "remove", content: "const value = 1;" },
+      { type: "add", content: "const value = 2;" },
+    ]);
+    expect(comparison.metrics.highlightCalls).toBe(0);
+    await comparison.close();
+    expect(git("diff", "--cached", "--name-status")).toBe("D\tx.ts");
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("supports empty trees, unborn HEAD, staged and unstaged comparisons", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-endpoints-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    const unborn = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+    });
+    expect(unborn.files.map((file) => file.entry.path)).toEqual(["x.ts"]);
+    await unborn.close();
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const empty = await listComparison({
+      cwd,
+      base: { kind: "empty" },
+      head: { kind: "rev", rev: "HEAD" },
+    });
+    expect(empty.files[0].entry.change).toBe("added");
+    await empty.close();
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    git("add", ".");
+    const indexPath = join(cwd, ".git", "index");
+    const originalIndex = await readFile(indexPath);
+    const originalMtime = (await lstat(indexPath, { bigint: true })).mtimeNs;
+    const staged = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "index" },
+      highlight: false,
+    });
+    expect(await readFile(indexPath)).toEqual(originalIndex);
+    expect((await lstat(indexPath, { bigint: true })).mtimeNs).toBe(originalMtime);
+    const stagedSha = staged.headSha;
+    expect(staged.files[0].entry).toMatchObject({ additions: 1, deletions: 1 });
+    await staged.close();
+    await writeFile(join(cwd, "x.ts"), "const value = 3;\n");
+    const unstaged = await listComparison({
+      cwd,
+      base: { kind: "index" },
+      head: { kind: "worktree" },
+      highlight: false,
+    });
+    expect(unstaged.baseSha).toBe(stagedSha);
+    const record = await readBody(unstaged);
+    expect(record.body.hunks[0].lines).toContainEqual({
+      type: "remove",
+      content: "const value = 2;",
+    });
+    await unstaged.close();
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("lists oversized untracked files without treating their truncated contents as additions", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-large-file-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "huge.ts"), Buffer.alloc(2 * 1024 * 1024, 120));
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+    });
+    expect(comparison.files[0].entry).toMatchObject({
+      path: "huge.ts",
+      additions: 0,
+      deletions: 0,
+      content: "text",
+    });
+    expect(await comparison.read(comparison.files[0])).toEqual({ kind: "too_large" });
+    await comparison.close();
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("preserves highlighting context outside the emitted hunks", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-highlight-context-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    const lines = [
+      "/*",
+      ...Array.from({ length: 30 }, (_, index) => `comment ${index}`),
+      "*/",
+      "export const value = 1;",
+    ];
+    await writeFile(join(cwd, "x.ts"), lines.join("\n") + "\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    lines[15] = "new comment";
+    await writeFile(join(cwd, "x.ts"), lines.join("\n") + "\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+    });
+    const record = await readBody(comparison);
+    expect(record.body.hunks[0].lines.find((line) => line.type === "add")).toMatchObject({
+      content: "new comment",
+      runs: [{ style: "comment", length: 11 }],
+    });
+    await comparison.close();
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("reads patches independently of repository color and prefix presentation settings", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-presentation-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "x.ts"), "before\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git("config", "color.ui", "always");
+    git("config", "diff.noprefix", "true");
+    await writeFile(join(cwd, "x.ts"), "after\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+      highlight: false,
+    });
+    const record = await readBody(comparison);
+    expect(record.body.hunks).toHaveLength(1);
+    expect(record.body.hunks[0].lines).toContainEqual({ type: "add", content: "after" });
+    await comparison.close();
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("merge-base index comparisons resolve against HEAD while reporting both endpoint SHAs", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-index-merge-base-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const common = git("rev-parse", "HEAD");
+    git("checkout", "-b", "side");
+    await writeFile(join(cwd, "side.txt"), "side\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "side");
+    const side = git("rev-parse", "HEAD");
+    git("checkout", "main");
+    await writeFile(join(cwd, "main.txt"), "main\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "main");
+    await writeFile(join(cwd, "staged.txt"), "staged\n");
+    git("add", "staged.txt");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "side" },
+      head: { kind: "index" },
+      mergeBase: true,
+    });
+    expect(comparison.baseSha).toBe(side);
+    expect(comparison.mergeBaseSha).toBe(common);
+    expect(comparison.files.map((file) => file.entry.path)).toEqual(["main.txt", "staged.txt"]);
+    await comparison.close();
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+async function readBody(comparison: Comparison) {
+  const record = await comparison.read(comparison.files[0]);
+  if (record.kind !== "ready") throw new Error("Expected a readable file body");
+  return record;
+}
+
+test.each(["worktree", "index", "rev"] as const)(
+  "%s whitespace filtering omits spacing-only edits and retains meaningful edits",
+  async (headKind) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-whitespace-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+    try {
+      git("init", "-b", "main");
+      git("config", "user.email", "test@example.com");
+      git("config", "user.name", "Test");
+      await writeFile(join(cwd, "a.ts"), "const x = 1;\n");
+      await writeFile(join(cwd, "b.txt"), "before\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD").trim();
+      await writeFile(join(cwd, "a.ts"), "const  x = 1;\n");
+      await writeFile(join(cwd, "b.txt"), "after\n");
+      if (headKind !== "worktree") git("add", ".");
+      if (headKind === "rev") git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      const head = headKind === "rev" ? { kind: "rev" as const, rev: "HEAD" } : { kind: headKind };
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: base },
+        head,
+        ignoreWhitespace: true,
+        highlight: false,
+      });
+      expect(comparison.files.map((file) => file.entry.path)).toEqual(["b.txt"]);
+      await comparison.close();
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test.skipIf(process.platform === "win32")(
+  "comparison roots preserve trailing folder spaces",
+  async () => {
+    const root = await mkdtemp(join(tmpdir(), "diff-space-"));
+    const cwd = join(root, "repo ");
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(cwd);
+    try {
+      execFileSync("git", ["init", "-b", "main"], { cwd });
+      const { worktreeRoot } = await import("./git.js");
+      expect(await worktreeRoot(cwd)).toBe(cwd);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+);
+
+test.each(["worktree", "index", "rev"] as const)(
+  "%s rename reads select the destination when the old path becomes a directory",
+  async (headKind) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-rename-directory-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const { mkdir } = await import("node:fs/promises");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await writeFile(join(cwd, "a.txt"), "original line\n".repeat(16));
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD");
+      git("mv", "a.txt", "z.txt");
+      await writeFile(join(cwd, "z.txt"), "original line\n".repeat(16) + "renamed line\n");
+      await mkdir(join(cwd, "a.txt"));
+      await writeFile(join(cwd, "a.txt", "child.txt"), "replacement line\n");
+      git("add", ".");
+      if (headKind === "rev") git("-c", "commit.gpgsign=false", "commit", "-m", "rename");
+      const head = headKind === "rev" ? { kind: "rev" as const, rev: "HEAD" } : { kind: headKind };
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: base },
+        head,
+        highlight: false,
+      });
+      try {
+        const file = comparison.files.find((candidate) => candidate.entry.path === "z.txt");
+        if (!file) throw new Error("Missing rename");
+        expect(file.entry.oldPath).toBe("a.txt");
+        const record = await comparison.read(file);
+        if (record.kind !== "ready") throw new Error("Expected readable rename");
+        const lines = record.body.hunks.flatMap((hunk) => hunk.lines.map((line) => line.content));
+        expect(lines).toContain("renamed line");
+        expect(lines).not.toContain("replacement line");
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test.skipIf(process.platform === "win32")(
+  "a dangling untracked symlink exposes its target text alongside tracked changes",
+  async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-dangling-link-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+    const { symlink } = await import("node:fs/promises");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await writeFile(join(cwd, "a.txt"), "before\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      await writeFile(join(cwd, "a.txt"), "after\n");
+      await symlink("not-created-yet", join(cwd, "link"));
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: "HEAD" },
+        head: { kind: "worktree" },
+        highlight: false,
+      });
+      try {
+        expect(comparison.files.map((file) => file.entry.path)).toEqual(["a.txt", "link"]);
+        const record = await comparison.read(comparison.files[1]);
+        if (record.kind !== "ready") throw new Error("Expected link body");
+        expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual({
+          type: "add",
+          content: "not-created-yet",
+        });
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test("untracked nested repositories do not hide tracked edits", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-nested-repository-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  const { mkdir } = await import("node:fs/promises");
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "a.txt"), "before\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "a.txt"), "after\n");
+    await mkdir(join(cwd, "nested"));
+    git("-C", "nested", "init");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+      highlight: false,
+    });
+    try {
+      expect(comparison.files.map((file) => file.entry.path)).toEqual(["a.txt"]);
+      const record = await readBody(comparison);
+      expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual({
+        type: "add",
+        content: "after",
+      });
+    } finally {
+      await comparison.close();
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test.each(["worktree", "index", "rev"] as const)(
+  "%s preserves hunks for paths containing a patch prefix delimiter",
+  async (headKind) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-path-delimiter-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const { mkdir } = await import("node:fs/promises");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await mkdir(join(cwd, "dir b"));
+      await writeFile(join(cwd, "dir b", "file.txt"), "before\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD");
+      await writeFile(join(cwd, "dir b", "file.txt"), "after\n");
+      if (headKind !== "worktree") git("add", ".");
+      if (headKind === "rev") git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      const head = headKind === "rev" ? { kind: "rev" as const, rev: "HEAD" } : { kind: headKind };
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: base },
+        head,
+        highlight: false,
+      });
+      try {
+        expect(comparison.files[0].entry.path).toBe("dir b/file.txt");
+        const record = await readBody(comparison);
+        expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual({
+          type: "add",
+          content: "after",
+        });
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test("highlighted BOM source content survives the production frame codec", async () => {
+  const { encodeDiffFrame, decodeDiffFrame } =
+    await import("@getpaseo/protocol/binary-frames/index");
+  const cwd = await mkdtemp(join(tmpdir(), "diff-bom-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  try {
+    git("init", "-b", "main");
+    await writeFile(join(cwd, "bom.ts"), "\uFEFFexport const value = 1;\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "empty" },
+      head: { kind: "worktree" },
+    });
+    try {
+      const record = await readBody(comparison);
+      const frame = { opcode: 0x41 as const, slot: 0, revision: 1, files: [record.body] };
+      expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+      expect(
+        record.body.hunks
+          .flatMap((hunk) => hunk.lines)
+          .some((line) => line.content.startsWith("\uFEFF")),
+      ).toBe(true);
+    } finally {
+      await comparison.close();
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test.skipIf(process.platform === "win32")(
+  "symlink replacement retains both patch sections",
+  async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-type-change-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+    const { symlink, unlink } = await import("node:fs/promises");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await symlink("old-target", join(cwd, "file.txt"));
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      await unlink(join(cwd, "file.txt"));
+      await writeFile(join(cwd, "file.txt"), "replacement contents\n");
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: "HEAD" },
+        head: { kind: "worktree" },
+        highlight: false,
+      });
+      try {
+        expect(comparison.files[0].entry).toMatchObject({ additions: 1, deletions: 1 });
+        const record = await readBody(comparison);
+        expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toEqual(
+          expect.arrayContaining([
+            { type: "remove", content: "old-target" },
+            { type: "add", content: "replacement contents" },
+          ]),
+        );
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test.skipIf(process.platform === "win32")(
+  "highlighted symlink replacements use stored link text instead of target contents",
+  async () => {
+    const { encodeDiffFrame, decodeDiffFrame } =
+      await import("@getpaseo/protocol/binary-frames/index");
+    const cwd = await mkdtemp(join(tmpdir(), "diff-highlighted-link-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+    const { symlink, unlink } = await import("node:fs/promises");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await writeFile(join(cwd, "file.ts"), "export const old = 1;\n");
+      await writeFile(join(cwd, "target.ts"), "export const entirelyDifferentLength = 2;\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      await unlink(join(cwd, "file.ts"));
+      await symlink("target.ts", join(cwd, "file.ts"));
+      const comparison = await listComparison({
+        cwd,
+        base: { kind: "rev", rev: "HEAD" },
+        head: { kind: "worktree" },
+      });
+      try {
+        const record = await readBody(comparison);
+        expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual(
+          expect.objectContaining({ type: "add", content: "target.ts" }),
+        );
+        const frame = { opcode: 0x41 as const, slot: 0, revision: 1, files: [record.body] };
+        expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test("files removed between listing and highlighting retain their deletion patch", async () => {
+  const { encodeDiffFrame, decodeDiffFrame } =
+    await import("@getpaseo/protocol/binary-frames/index");
+  const cwd = await mkdtemp(join(tmpdir(), "diff-source-disappeared-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "a.ts"), "export const old = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "a.ts"), "export const old = 2;\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+    });
+    try {
+      expect(comparison.files[0].entry.change).toBe("modified");
+      await rm(join(cwd, "a.ts"));
+      const record = await readBody(comparison);
+      expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual(
+        expect.objectContaining({ type: "remove", content: "export const old = 1;" }),
+      );
+      const frame = { opcode: 0x41 as const, slot: 0, revision: 1, files: [record.body] };
+      expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+    } finally {
+      await comparison.close();
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("a batched oversized tracked patch does not hide its small sibling", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-batch-budget-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "a.txt"), "before\n");
+    await writeFile(join(cwd, "b.txt"), "before\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "a.txt"), "oversized\n".repeat(1024 * 1024));
+    await writeFile(join(cwd, "b.txt"), "after\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+      highlight: false,
+    });
+    try {
+      expect(await comparison.read(comparison.files[0])).toEqual({ kind: "too_large" });
+      const sibling = await comparison.read(comparison.files[1]);
+      if (sibling.kind !== "ready") throw new Error("Expected readable sibling");
+      expect(sibling.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual({
+        type: "add",
+        content: "after",
+      });
+    } finally {
+      await comparison.close();
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("replacing a submodule with a regular file preserves its replacement body", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-gitlink-replacement-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  const { mkdir } = await import("node:fs/promises");
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await mkdir(join(cwd, "sub"));
+    git("-C", "sub", "init", "-b", "main");
+    git("-C", "sub", "config", "user.name", "Test");
+    git("-C", "sub", "config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "sub", "a.txt"), "base\n");
+    git("-C", "sub", "add", ".");
+    git("-C", "sub", "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "record submodule");
+    await rm(join(cwd, "sub"), { recursive: true, force: true });
+    await writeFile(join(cwd, "sub"), "replacement contents\n");
+    const comparison = await listComparison({
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+    });
+    try {
+      const record = await readBody(comparison);
+      expect(record.body.hunks.flatMap((hunk) => hunk.lines)).toContainEqual(
+        expect.objectContaining({ type: "add", content: "replacement contents" }),
+      );
+    } finally {
+      await comparison.close();
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test.each([
+  { ignoreWhitespace: false, after: "export const value = 2;\n", files: ["a.ts"] },
+  { ignoreWhitespace: true, after: "export  const value = 1;\n", files: [] },
+])(
+  "interpretation checks ignore content edits but detect new binary attributes, whitespace=$ignoreWhitespace",
+  async ({ ignoreWhitespace, after, files }) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-interpretation-check-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      git("config", "core.autocrlf", "false");
+      await writeFile(join(cwd, "a.ts"), "export const value = 1;\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD");
+      await writeFile(join(cwd, "a.ts"), after);
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      const compare = {
+        cwd,
+        base: { kind: "rev" as const, rev: base },
+        head: { kind: "rev" as const, rev: git("rev-parse", "HEAD") },
+        ignoreWhitespace,
+        highlight: false,
+      };
+      const comparison = await listComparison(compare);
+      try {
+        expect(comparison.files.map((file) => file.entry.path)).toEqual(files);
+        expect(await comparison.hasInterpretationChanged()).toBe(false);
+        await writeFile(join(cwd, "a.ts"), "uncommitted content\n");
+        expect(await comparison.hasInterpretationChanged()).toBe(false);
+        await writeFile(join(cwd, ".gitattributes"), "a.ts -diff\n");
+        expect(await comparison.hasInterpretationChanged()).toBe(true);
+        const fresh = await listComparison(compare);
+        try {
+          expect(fresh.files.map((file) => file.entry)).toEqual([
+            expect.objectContaining({ path: "a.ts", content: "binary" }),
+          ]);
+        } finally {
+          await fresh.close();
+        }
+      } finally {
+        await comparison.close();
+      }
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/packages/server/src/server/diff/git.ts b/packages/server/src/server/diff/git.ts
new file mode 100644
index 0000000000..c58c1de181
--- /dev/null
+++ b/packages/server/src/server/diff/git.ts
@@ -0,0 +1,431 @@
+import { parseGitRevParsePath } from "../../utils/git-rev-parse-path.js";
+import { readGitInputs } from "./inputs.js";
+import { Patches } from "./patches.js";
+import { HighlightSources } from "./sources.js";
+import {
+  prepareAllChangesIndex,
+  PER_FILE_DIFF_MAX_BYTES,
+  GIT_PATCH_FORMAT_ARGS,
+  inspectUntrackedFile,
+  snapshotComparisonIndex,
+  resolveCheckoutDiffBase,
+  type CheckoutDiffCompare,
+} from "../../utils/checkout-git.js";
+import { lstat, readFile, readlink } from "node:fs/promises";
+import type { BigIntStats } from "node:fs";
+import { resolve } from "node:path";
+import type { DiffEndpoint, DiffSubscribeRequest } from "@getpaseo/protocol/messages";
+import type { DiffEntry, DiffBody } from "@getpaseo/protocol/binary-frames/index";
+import { runGitCommand, type GitCommandOptions } from "../../utils/run-git-command.js";
+import { parseDiff, highlightDiffWithFileContent } from "../utils/diff-highlighter.js";
+
+export type Compare = Omit<DiffSubscribeRequest, "type" | "requestId"> & {
+  checkoutBase?: { compare: CheckoutDiffCompare; paseoHome: string };
+};
+export interface ListedFile {
+  entry: DiffEntry;
+  identity: string;
+  source: { kind: "tracked" } | { kind: "untracked"; size: number };
+}
+interface ResolvedComparison {
+  baseSha: string;
+  headSha: string;
+  mergeBaseSha: string;
+  comparisonBaseSha: string;
+}
+export type DiffFileRead = { kind: "ready"; body: DiffBody; bytes: number } | { kind: "too_large" };
+export interface Comparison extends Pick<
+  ResolvedComparison,
+  "baseSha" | "headSha" | "mergeBaseSha"
+> {
+  files: ListedFile[];
+  metrics: { highlightCalls: number };
+  close(): Promise<void>;
+  selectBodies(paths: ReadonlySet<string>): void;
+  hasInterpretationChanged(): Promise<boolean>;
+  read(
+    file: ListedFile,
+    budget?: { remainingBytes?: number; maxPatchBytes?: number },
+  ): Promise<DiffFileRead>;
+}
+export class DiffReadError extends Error {
+  constructor(
+    readonly code: "INVALID_COMPARE" | "NOT_GIT_REPO" | "REF_NOT_FOUND",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+const EMPTY = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export function validateCompare(compare: Compare): void {
+  if (compare.head.kind === "empty")
+    throw new DiffReadError("INVALID_COMPARE", "The head cannot be empty");
+  if (compare.base.kind === "worktree")
+    throw new DiffReadError("INVALID_COMPARE", "The working tree cannot be the base");
+  if (compare.base.kind === "index" && compare.head.kind !== "worktree")
+    throw new DiffReadError("INVALID_COMPARE", "An index base requires a working tree head");
+  if (compare.mergeBase && compare.base.kind !== "rev")
+    throw new DiffReadError("INVALID_COMPARE", "Merge base requires a revision base");
+}
+export async function worktreeRoot(cwd: string): Promise<string> {
+  const result = await runGitCommand(["rev-parse", "--show-toplevel"], {
+    cwd,
+    acceptExitCodes: [0, 128],
+  });
+  if (result.exitCode !== 0) throw new DiffReadError("NOT_GIT_REPO", "Not a git repository");
+  const root = parseGitRevParsePath(result.stdout);
+  if (root === null) throw new DiffReadError("NOT_GIT_REPO", "Git returned no working tree root");
+  return resolve(root);
+}
+async function resolveEndpoint(
+  cwd: string,
+  endpoint: DiffEndpoint,
+  indexFile: string | null,
+): Promise<string> {
+  if (endpoint.kind === "empty") return EMPTY;
+  if (endpoint.kind === "index") {
+    if (indexFile === null) throw new Error("Index comparisons require an index snapshot");
+    const result = await runGitCommand(["write-tree"], {
+      cwd,
+      envOverlay: { GIT_INDEX_FILE: indexFile },
+    });
+    return result.stdout.trim();
+  }
+  const ref = endpoint.kind === "rev" ? endpoint.rev : "HEAD";
+  const result = await runGitCommand(
+    ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`],
+    {
+      cwd,
+      acceptExitCodes: [0, 128],
+    },
+  );
+  if (result.exitCode === 0) return result.stdout.trim();
+  if (ref === "HEAD") {
+    const unborn = await runGitCommand(["rev-parse", "--verify", "HEAD"], {
+      cwd,
+      acceptExitCodes: [0, 128],
+    });
+    if (unborn.exitCode !== 0) return EMPTY;
+  }
+  throw new DiffReadError("REF_NOT_FOUND", `Revision not found: ${ref}`);
+}
+function parseStats(
+  text: string,
+): Map<string, { additions: number; deletions: number; binary: boolean }> {
+  const fields = text.split("\0");
+  const stats = new Map<string, { additions: number; deletions: number; binary: boolean }>();
+  for (let index = 0; index < fields.length - 1; index++) {
+    const line = fields[index];
+    const tab = line.indexOf("\t");
+    const second = line.indexOf("\t", tab + 1);
+    const add = line.slice(0, tab);
+    const del = line.slice(tab + 1, second);
+    let path = line.slice(second + 1);
+    if (!path) {
+      index++;
+      path = fields[++index];
+    }
+    stats.set(path, {
+      additions: Number(add) || 0,
+      deletions: Number(del) || 0,
+      binary: add === "-",
+    });
+  }
+  return stats;
+}
+export async function listComparison(compare: Compare): Promise<Comparison> {
+  if (compare.checkoutBase) {
+    const selected = await resolveCheckoutDiffBase(compare.cwd, compare.checkoutBase.compare, {
+      paseoHome: compare.checkoutBase.paseoHome,
+    });
+    if (!selected) throw new DiffReadError("REF_NOT_FOUND", "Comparison base is unavailable");
+    compare = { ...compare, base: { kind: "rev", rev: selected } };
+  }
+  validateCompare(compare);
+  const cwd = compare.cwd;
+  let privateIndex: Awaited<ReturnType<typeof prepareAllChangesIndex>> = null;
+  try {
+    if (compare.base.kind === "index" || compare.head.kind === "index")
+      privateIndex = await snapshotComparisonIndex(cwd);
+    const indexFile = privateIndex ? privateIndex.indexFile : null;
+    const baseSha = await resolveEndpoint(cwd, compare.base, indexFile);
+    const headSha = await resolveEndpoint(cwd, compare.head, indexFile);
+    let mergeBaseSha = "";
+    let comparisonBaseSha = baseSha;
+    if (compare.mergeBase) {
+      const headCommit =
+        compare.head.kind === "index"
+          ? await resolveEndpoint(cwd, { kind: "rev", rev: "HEAD" }, indexFile)
+          : headSha;
+      if (headCommit === EMPTY) comparisonBaseSha = EMPTY;
+      else if (baseSha !== EMPTY) {
+        const result = await runGitCommand(["merge-base", baseSha, headCommit], {
+          cwd,
+          acceptExitCodes: [0, 1],
+        });
+        mergeBaseSha = result.stdout.trim();
+        if (mergeBaseSha) comparisonBaseSha = mergeBaseSha;
+      }
+    }
+    if (compare.head.kind === "worktree" && compare.base.kind !== "index")
+      privateIndex = await prepareAllChangesIndex(cwd, comparisonBaseSha);
+    return await readComparisonList(
+      compare,
+      { baseSha, headSha, mergeBaseSha, comparisonBaseSha },
+      privateIndex,
+    );
+  } catch (error) {
+    await privateIndex?.cleanup();
+    throw error;
+  }
+}
+
+async function readComparisonList(
+  compare: Compare,
+  resolved: ResolvedComparison,
+  privateIndex: Awaited<ReturnType<typeof prepareAllChangesIndex>>,
+): Promise<Comparison> {
+  const { baseSha, headSha, mergeBaseSha, comparisonBaseSha } = resolved;
+  const cwd = compare.cwd;
+  const args = diffArguments(compare, comparisonBaseSha, headSha);
+  const options: GitCommandOptions = {
+    cwd,
+    envOverlay: {
+      GIT_OPTIONAL_LOCKS: "0",
+      ...(privateIndex ? { GIT_INDEX_FILE: privateIndex.indexFile } : {}),
+    },
+  };
+  const { files, worktreeFiles, interpretationPaths } = await readTrackedFiles(
+    compare,
+    args,
+    options,
+  );
+  if (compare.head.kind === "worktree") files.push(...(await listUntrackedFiles(options)));
+  files.sort((a, b) => a.entry.path.localeCompare(b.entry.path));
+  for (const file of files) interpretationPaths.add(file.entry.path);
+  const gitInputs = await readGitInputs([...interpretationPaths].sort(), worktreeFiles, options);
+  for (const file of files)
+    file.identity += JSON.stringify([
+      gitInputs.identities.get(file.entry.path),
+      gitInputs.identities.get(file.entry.oldPath ?? file.entry.path),
+    ]);
+  const metrics = { highlightCalls: 0 };
+  const patches = new Patches(args, options, files);
+  const sources = new HighlightSources({
+    cwd,
+    baseSha: comparisonBaseSha,
+    headSha: compare.head.kind === "worktree" ? null : headSha,
+    files,
+  });
+  return {
+    baseSha,
+    headSha,
+    mergeBaseSha,
+    files,
+    metrics,
+    selectBodies: (paths) => patches.select(paths),
+    hasInterpretationChanged: gitInputs.hasInterpretationChanged,
+    close: async () => {
+      await privateIndex?.cleanup();
+    },
+    async read(file, budget = {}) {
+      const maxPatchBytes = budget.maxPatchBytes ?? PER_FILE_DIFF_MAX_BYTES;
+      const remainingBytes = budget.remainingBytes ?? maxPatchBytes;
+      if (file.source.kind === "untracked" && file.source.size > maxPatchBytes) {
+        return { kind: "too_large" };
+      }
+      const result =
+        file.source.kind === "untracked"
+          ? await runGitCommand(
+              ["diff", "--no-index", ...GIT_PATCH_FORMAT_ARGS, "--", "/dev/null", file.entry.path],
+              {
+                ...options,
+                acceptExitCodes: [0, 1],
+                maxOutputBytes: maxPatchBytes + 1,
+              },
+            )
+          : await patches.read(file, maxPatchBytes);
+      const bytes = Buffer.byteLength(result.stdout);
+      if (result.truncated || bytes > remainingBytes || bytes > maxPatchBytes)
+        return { kind: "too_large" };
+      // File-type changes have a deletion and addition section for the same path.
+      const sections = parseDiff(result.stdout).filter(
+        (candidate) => candidate.path === file.entry.path,
+      );
+      if (!sections.length)
+        return { kind: "ready", body: { path: file.entry.path, hunks: [] }, bytes };
+      const parsed = {
+        path: file.entry.path,
+        isNew: file.entry.change === "added",
+        isDeleted: file.entry.change === "deleted",
+        additions: file.entry.additions,
+        deletions: file.entry.deletions,
+        hunks: sections.flatMap((section) => section.hunks),
+      };
+      let highlighted = parsed;
+      if (compare.highlight !== false) {
+        metrics.highlightCalls++;
+        const context = await sources.read(file);
+        highlighted = await highlightDiffWithFileContent(parsed, cwd, context);
+      }
+      const hunks = highlighted.hunks.map((hunk) => ({
+        oldStart: hunk.oldStart,
+        oldCount: hunk.oldCount,
+        newStart: hunk.newStart,
+        newCount: hunk.newCount,
+        lines: hunk.lines.map((line) => {
+          if (!line.tokens) return { type: line.type, content: line.content };
+          return {
+            type: line.type,
+            content: line.content,
+            runs: line.tokens
+              .filter((token) => token.text.length > 0)
+              .map((token) => ({ style: token.style, length: token.text.length })),
+          };
+        }),
+      }));
+      return { kind: "ready", body: { path: file.entry.path, hunks }, bytes };
+    },
+  };
+}
+
+async function readTrackedFiles(
+  compare: Compare,
+  args: string[],
+  options: GitCommandOptions,
+): Promise<{ files: ListedFile[]; worktreeFiles: Set<string>; interpretationPaths: Set<string> }> {
+  const [raw, stat] = await Promise.all([
+    runGitCommand([...args.filter((arg) => arg !== "-w"), "--raw", "--no-abbrev", "-z"], options),
+    runGitCommand([...args, "--numstat", "-z"], options),
+  ]);
+  if (raw.truncated || stat.truncated)
+    throw new Error("Diff entry list exceeded the git output budget");
+  const stats = parseStats(stat.stdout);
+  const fields = raw.stdout.split("\0");
+  const files: ListedFile[] = [];
+  const worktreeFiles = new Set<string>();
+  const interpretationPaths = new Set<string>();
+  for (let index = 0; index < fields.length - 1; index++) {
+    const header = fields[index].split(" ");
+    const code = header[4]?.[0];
+    let path = fields[++index];
+    let oldPath: string | null = null;
+    if (code === "R" || code === "C") {
+      oldPath = path;
+      path = fields[++index];
+    }
+    interpretationPaths.add(path);
+    if (oldPath !== null) interpretationPaths.add(oldPath);
+    const counts = stats.get(path);
+    // With -w, a raw metadata entry need not have a numstat record.
+    if (!counts && compare.ignoreWhitespace) continue;
+    if (!counts) throw new Error(`Missing diff statistics for ${path}`);
+    let change: DiffEntry["change"] = "modified";
+    if (code === "A") change = "added";
+    else if (code === "D") change = "deleted";
+    else if (oldPath !== null) change = "renamed";
+    let identity = header.join(" ");
+    if (compare.head.kind === "worktree" && code !== "D") {
+      const worktree = await readWorktreeIdentity(path, header, options);
+      identity += `:${worktree.identity}`;
+      if (worktree.regular && !counts.binary) worktreeFiles.add(path);
+    }
+
+    files.push({
+      entry: {
+        path,
+        oldPath,
+        change,
+        content: counts.binary ? "binary" : "text",
+        additions: counts.additions,
+        deletions: counts.deletions,
+        body: !counts.binary,
+      },
+      identity,
+      source: { kind: "tracked" },
+    });
+  }
+  return { files, worktreeFiles, interpretationPaths };
+}
+
+async function readWorktreeIdentity(
+  path: string,
+  header: string[],
+  options: GitCommandOptions,
+): Promise<{ identity: string; regular: boolean }> {
+  const value = await lstat(resolve(options.cwd, path), { bigint: true });
+  let identity = fileStatIdentity(value);
+  if (value.isDirectory() && (header[0] === ":160000" || header[1] === "160000")) {
+    const submodule = await runGitCommand(
+      ["status", "--porcelain=v2", "--branch", "--untracked-files=normal"],
+      { cwd: resolve(options.cwd, path), envOverlay: { GIT_OPTIONAL_LOCKS: "0" } },
+    );
+    identity += `:${submodule.stdout}`;
+  }
+  return { identity, regular: value.isFile() };
+}
+
+function diffArguments(compare: Compare, baseSha: string, headSha: string): string[] {
+  const revisions: string[] = [];
+  if (compare.base.kind !== "index") revisions.push(baseSha);
+  if (compare.head.kind === "rev") revisions.push(headSha);
+  if (compare.head.kind === "index") revisions.unshift("--cached");
+  const args = ["diff", ...GIT_PATCH_FORMAT_ARGS, "--no-textconv", "-M", ...revisions];
+  if (compare.ignoreWhitespace) args.push("-w");
+  return args;
+}
+
+async function readUntrackedText(
+  path: string,
+  symlink: boolean,
+  omitted: boolean,
+): Promise<Buffer> {
+  if (symlink) return Buffer.from(await readlink(path));
+  if (omitted) return Buffer.alloc(0);
+  return readFile(path);
+}
+
+async function listUntrackedFiles(options: GitCommandOptions): Promise<ListedFile[]> {
+  const cwd = options.cwd;
+  const files: ListedFile[] = [];
+  const untracked = await runGitCommand(
+    ["ls-files", "--others", "--exclude-standard", "-z"],
+    options,
+  );
+  for (const path of untracked.stdout.split("\0").filter(Boolean)) {
+    const value = await lstat(resolve(cwd, path), { bigint: true });
+    if (!value.isFile() && !value.isSymbolicLink()) continue;
+    const symlink = value.isSymbolicLink();
+    let binary = false;
+    let omitted = false;
+    if (!symlink) {
+      const inspected = await inspectUntrackedFile(cwd, path);
+      binary = inspected.stat?.isBinary === true;
+      omitted = inspected.truncated;
+    }
+    const content = await readUntrackedText(resolve(cwd, path), symlink, binary || omitted);
+    const additions =
+      binary || content.length === 0
+        ? 0
+        : content.toString("utf8").split("\n").length - Number(content.at(-1) === 10);
+    files.push({
+      entry: {
+        path,
+        oldPath: null,
+        change: "added",
+        content: binary ? "binary" : "text",
+        additions,
+        deletions: 0,
+        body: !binary,
+      },
+      identity: fileStatIdentity(value),
+      source: { kind: "untracked", size: Number(value.size) },
+    });
+  }
+  return files;
+}
+
+function fileStatIdentity(value: BigIntStats): string {
+  // Timestamp-preserving copies still change file status or replace the inode.
+  return `${value.dev}:${value.ino}:${value.size}:${value.mtimeNs}:${value.ctimeNs}`;
+}
diff --git a/packages/server/src/server/diff/index.ts b/packages/server/src/server/diff/index.ts
new file mode 100644
index 0000000000..6c9a537f86
--- /dev/null
+++ b/packages/server/src/server/diff/index.ts
@@ -0,0 +1,487 @@
+import { TOTAL_DIFF_MAX_BYTES } from "../../utils/checkout-git.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, runGitCommand } from "../../utils/run-git-command.js";
+import { expandTilde, createRealpathAwarePathMatcher } from "../../utils/path.js";
+import { packBodies } from "./batches.js";
+import { setImmediate } from "node:timers/promises";
+import {
+  DiffOpcode,
+  materializeDiffFile,
+  type DiffFrame,
+  type DiffEntry,
+  type DiffBody,
+} from "@getpaseo/protocol/binary-frames/index";
+import type {
+  DiffError,
+  DiffEndpoint,
+  ParsedDiffFile,
+  CheckoutCommitFileDiffRequest,
+} from "@getpaseo/protocol/messages";
+import type { WorkspaceGitService } from "../workspace-git-service.js";
+import {
+  listComparison,
+  validateCompare,
+  worktreeRoot,
+  DiffReadError,
+  type Compare,
+  type Comparison,
+} from "./git.js";
+import { DiffDependencyObserver } from "./dependencies.js";
+
+interface RecordCache {
+  identity: string;
+  body: DiffBody;
+  bytes: number;
+}
+interface Listener {
+  emit(frame: DiffFrame): Promise<void>;
+  active: boolean;
+  delivery: Promise<void>;
+}
+interface Target {
+  key: string;
+  compare: Compare;
+  listeners: Set<Listener>;
+  revision: number;
+  committed: number;
+  cache: Map<string, RecordCache>;
+  entries: DiffEntry[];
+  resolved: Pick<Comparison, "baseSha" | "headSha" | "mergeBaseSha">;
+  error: DiffError | null;
+  omitted: string[];
+  refresh: Promise<void> | null;
+  dirty: boolean;
+  checkInterpretation: (() => Promise<boolean>) | null;
+  interpretationCheck: Promise<void> | null;
+  interpretationDirty: boolean;
+  release: (() => Promise<void>) | null;
+  opening: Promise<void> | null;
+  closed: boolean;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+export interface CommitFileRead extends Pick<
+  CheckoutCommitFileDiffRequest,
+  "cwd" | "sha" | "path"
+> {
+  signal?: AbortSignal;
+}
+export interface DiffSubscription {
+  start(): Promise<void>;
+  release(): Promise<void>;
+}
+export class DiffSubscriptions {
+  private targets = new Map<string, Target>();
+  private dependencies: DiffDependencyObserver;
+  private computations = 0;
+  private highlightCalls = 0;
+  constructor(workspaceGit: Pick<WorkspaceGitService, "requestWorkingTreeWatch">) {
+    this.dependencies = new DiffDependencyObserver(workspaceGit);
+  }
+  getMetrics() {
+    return {
+      targets: this.targets.size,
+      subscriptions: [...this.targets.values()].reduce(
+        (sum, target) => sum + target.listeners.size,
+        0,
+      ),
+      computations: this.computations,
+      highlightCalls: this.highlightCalls,
+      metadataObservers: this.dependencies.getObservationCount(),
+    };
+  }
+  async readCommitFile(input: CommitFileRead): Promise<ParsedDiffFile | null> {
+    input.signal?.throwIfAborted();
+    const cwd = await worktreeRoot(expandTilde(input.cwd));
+    const result = await runGitCommand(
+      ["rev-list", "--parents", "--max-count=1", "--end-of-options", input.sha],
+      { cwd },
+    );
+    const [head, parent] = result.stdout.trim().split(" ");
+    if (!head) throw new DiffReadError("REF_NOT_FOUND", `Revision not found: ${input.sha}`);
+    const base: DiffEndpoint = parent ? { kind: "rev", rev: parent } : { kind: "empty" };
+    const comparison = await listComparison({ cwd, base, head: { kind: "rev", rev: head } });
+    try {
+      input.signal?.throwIfAborted();
+      const file = comparison.files.find((candidate) => candidate.entry.path === input.path);
+      if (!file || file.entry.content === "binary") return null;
+      comparison.selectBodies(new Set([file.entry.path]));
+      const record = await comparison.read(file, { maxPatchBytes: DEFAULT_MAX_OUTPUT_BYTES });
+      input.signal?.throwIfAborted();
+      return materializeDiffFile(
+        file.entry,
+        record.kind === "ready" ? record.body : null,
+        record.kind === "too_large",
+      );
+    } finally {
+      await comparison.close();
+    }
+  }
+  async subscribe(compare: Compare, emit: Listener["emit"]): Promise<DiffSubscription> {
+    validateCompare(compare);
+    compare = {
+      ...compare,
+      cwd: await worktreeRoot(expandTilde(compare.cwd)),
+      mergeBase: compare.mergeBase === true,
+      ignoreWhitespace: compare.ignoreWhitespace === true,
+      highlight: compare.highlight !== false,
+    };
+    const key = JSON.stringify([
+      compare.cwd,
+      compare.checkoutBase
+        ? ["checkout", JSON.stringify(compare.checkoutBase)]
+        : endpointKey(compare.base),
+      endpointKey(compare.head),
+      compare.mergeBase,
+      compare.ignoreWhitespace,
+      compare.highlight,
+    ]);
+    let target = this.targets.get(key);
+    if (!target) {
+      target = {
+        key,
+        compare,
+        listeners: new Set(),
+        revision: 0,
+        committed: 0,
+        cache: new Map(),
+        entries: [],
+        resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+        error: null,
+        omitted: [],
+        refresh: null,
+        dirty: false,
+        checkInterpretation: null,
+        interpretationCheck: null,
+        interpretationDirty: false,
+        release: null,
+        opening: null,
+        closed: false,
+        timer: null,
+      };
+      this.targets.set(key, target);
+      const captured = target;
+      try {
+        target.opening = this.dependencies
+          .declareDependencies(
+            {
+              cwd: compare.cwd,
+              refs: [compare.base, compare.head].flatMap((endpoint) =>
+                endpoint.kind === "rev" && !/^[a-f0-9]{40,64}$/.test(endpoint.rev)
+                  ? [endpoint.rev]
+                  : [],
+              ),
+              index: compare.base.kind === "index" || compare.head.kind !== "rev",
+              worktree: compare.head.kind === "worktree",
+            },
+            (kind) => {
+              if (kind === "interpretation") this.invalidateInterpretation(captured);
+              else this.invalidate(captured);
+            },
+          )
+          .then((release) => {
+            captured.release = release;
+            return undefined;
+          });
+      } catch (error) {
+        this.targets.delete(key);
+        throw error;
+      }
+    }
+    try {
+      await target.opening;
+    } catch (error) {
+      target.closed = true;
+      this.targets.delete(key);
+      throw error;
+    }
+    if (target.closed) throw new Error("Diff subscription cancelled");
+    const current = target;
+    const listener: Listener = { emit, active: false, delivery: Promise.resolve() };
+    current.listeners.add(listener);
+    let released = false;
+    return {
+      start: async () => {
+        while (current.refresh) await current.refresh;
+        if (current.closed || released) return;
+        listener.active = true;
+        if (!current.committed) await this.refresh(current);
+        else {
+          const replay = this.replay(current, listener);
+          listener.delivery = replay.catch(() => {});
+          await replay;
+        }
+      },
+      release: async () => {
+        if (released) return;
+        released = true;
+        listener.active = false;
+        current.listeners.delete(listener);
+        if (current.listeners.size) return;
+        current.closed = true;
+        if (current.timer) clearTimeout(current.timer);
+        this.targets.delete(key);
+        await current.release?.();
+        await current.refresh;
+        await current.interpretationCheck;
+      },
+    };
+  }
+  async invalidateForCwd(cwd: string): Promise<void> {
+    let root: string;
+    try {
+      root = await worktreeRoot(expandTilde(cwd));
+    } catch (error) {
+      if (error instanceof DiffReadError && error.code === "NOT_GIT_REPO") return;
+      throw error;
+    }
+    const matches = createRealpathAwarePathMatcher(root);
+    for (const target of this.targets.values())
+      if (matches(target.compare.cwd)) this.invalidate(target);
+  }
+  private invalidateInterpretation(target: Target): void {
+    if (target.closed) return;
+    target.interpretationDirty = true;
+    target.interpretationCheck ??= this.checkInterpretation(target).finally(() => {
+      target.interpretationCheck = null;
+    });
+  }
+  private async checkInterpretation(target: Target): Promise<void> {
+    do {
+      target.interpretationDirty = false;
+      try {
+        if (!target.checkInterpretation || (await target.checkInterpretation())) {
+          this.invalidate(target);
+          return;
+        }
+      } catch {
+        // A normal revision owns error delivery and recovery.
+        this.invalidate(target);
+        return;
+      }
+    } while (target.interpretationDirty && !target.closed);
+  }
+  private invalidate(target: Target): void {
+    if (target.closed) return;
+    target.dirty = true;
+    if (target.listeners.size === 0) return;
+    if (target.timer) clearTimeout(target.timer);
+    target.timer = setTimeout(() => {
+      target.timer = null;
+      void this.refresh(target);
+    }, 150);
+  }
+  private async emit(target: Target, frame: DiffFrame): Promise<void> {
+    await Promise.all(
+      [...target.listeners]
+        .filter((listener) => listener.active)
+        .map((listener) => {
+          const sent = listener.delivery.then(() => listener.emit(frame));
+          listener.delivery = sent.catch(() => {});
+          return sent;
+        }),
+    );
+    await setImmediate();
+  }
+  private async replay(target: Target, listener: Listener): Promise<void> {
+    const entries = target.entries.map((entry) => ({ ...entry, body: entry.content !== "binary" }));
+    await listener.emit({
+      opcode: DiffOpcode.Begin,
+      slot: 0,
+      revision: target.committed,
+      baseRevision: 0,
+      ...target.resolved,
+      entries,
+    });
+    const bodies: DiffBody[] = [];
+    for (const entry of entries) {
+      const cached = target.cache.get(entry.path);
+      if (entry.body && cached) bodies.push(cached.body);
+    }
+    for await (const files of packBodies(bodies, target.committed)) {
+      await listener.emit({
+        opcode: DiffOpcode.Bodies,
+        slot: 0,
+        revision: target.committed,
+        files,
+      });
+      await setImmediate();
+    }
+    await listener.emit({
+      opcode: DiffOpcode.End,
+      slot: 0,
+      revision: target.committed,
+      diffTooLarge: target.omitted.length > 0,
+      omitted: target.omitted,
+      error: target.error,
+    });
+  }
+  private async refresh(target: Target): Promise<void> {
+    if (target.refresh || target.closed) return target.refresh ?? undefined;
+    target.refresh = this.run(target).finally(() => {
+      target.refresh = null;
+    });
+    return target.refresh;
+  }
+  private async run(target: Target): Promise<void> {
+    do {
+      target.dirty = false;
+      const revision = ++target.revision;
+      let comparison: Comparison | null = null;
+      let began = false;
+      try {
+        this.computations++;
+        comparison = await listComparison(target.compare);
+        target.checkInterpretation = comparison.hasInterpretationChanged;
+        const resolved = {
+          baseSha: comparison.baseSha,
+          headSha: comparison.headSha,
+          mergeBaseSha: comparison.mergeBaseSha,
+        };
+        const tooManyFiles = comparison.files.length > 10000;
+        const entries = comparison.files.map((file) => ({
+          ...file.entry,
+          body: tooManyFiles
+            ? file.entry.content === "text"
+            : needsBody(target, file.entry, file.identity),
+        }));
+        await this.emit(target, {
+          opcode: DiffOpcode.Begin,
+          slot: 0,
+          revision,
+          baseRevision: target.error ? 0 : target.committed,
+          ...resolved,
+          entries,
+        });
+        began = true;
+        const cache = new Map<string, RecordCache>();
+        const omitted: string[] = [];
+        const state = { cache, omitted, total: 0 };
+        const records = this.readBodies(target, comparison, entries, state);
+        for await (const files of packBodies(records, revision)) {
+          if (isInterrupted(target)) break;
+          await this.emit(target, { opcode: DiffOpcode.Bodies, slot: 0, revision, files });
+        }
+        if (isInterrupted(target)) continue;
+        await this.emit(target, {
+          opcode: DiffOpcode.End,
+          slot: 0,
+          revision,
+          omitted,
+          diffTooLarge: omitted.length > 0,
+          error: null,
+        });
+        target.committed = revision;
+        target.resolved = resolved;
+        target.entries = entries;
+        target.cache = cache;
+        target.omitted = omitted;
+        target.error = null;
+      } catch (error) {
+        const failure = diffError(error);
+        if (!began)
+          await this.emit(target, {
+            opcode: DiffOpcode.Begin,
+            slot: 0,
+            revision,
+            baseRevision: 0,
+            baseSha: "",
+            headSha: "",
+            mergeBaseSha: "",
+            entries: [],
+          });
+        await this.emit(target, {
+          opcode: DiffOpcode.End,
+          slot: 0,
+          revision,
+          diffTooLarge: false,
+          omitted: [],
+          error: failure,
+        });
+        target.error = failure;
+        target.committed = revision;
+        target.entries = [];
+        target.cache.clear();
+        target.omitted = [];
+      } finally {
+        if (comparison) this.highlightCalls += comparison.metrics.highlightCalls;
+        await comparison?.close();
+      }
+    } while (target.dirty && !target.closed);
+  }
+  private async *readBodies(
+    target: Target,
+    comparison: Comparison,
+    entries: DiffEntry[],
+    state: { cache: Map<string, RecordCache>; omitted: string[]; total: number },
+  ): AsyncGenerator<DiffBody> {
+    if (entries.length > 10000) {
+      for (const entry of entries) if (entry.content === "text") state.omitted.push(entry.path);
+      return;
+    }
+    comparison.selectBodies(
+      new Set(entries.filter((entry) => entry.body).map((entry) => entry.path)),
+    );
+    for (let index = 0; index < comparison.files.length; index++) {
+      if (isInterrupted(target)) return;
+      const file = comparison.files[index];
+      const entry = entries[index];
+      if (entry.content === "binary") continue;
+      let record = target.cache.get(entry.path);
+      if (entry.body || !record) {
+        const read = await comparison.read(file, {
+          remainingBytes: TOTAL_DIFF_MAX_BYTES - state.total,
+        });
+        if (read.kind === "too_large") {
+          state.omitted.push(entry.path);
+          continue;
+        }
+        record = { identity: file.identity, body: read.body, bytes: read.bytes };
+      }
+      if (exceedsBudget(state.total, record.bytes)) {
+        state.omitted.push(entry.path);
+        continue;
+      }
+      state.total += record.bytes;
+      state.cache.set(entry.path, record);
+      if (entry.body) yield record.body;
+    }
+  }
+  async close(): Promise<void> {
+    for (const target of this.targets.values()) {
+      target.closed = true;
+      if (target.timer) clearTimeout(target.timer);
+      await target.opening;
+      await target.release?.();
+      await target.refresh;
+      await target.interpretationCheck;
+    }
+    this.targets.clear();
+    await this.dependencies.close();
+  }
+}
+
+function isInterrupted(target: Target): boolean {
+  return target.closed || target.dirty;
+}
+function exceedsBudget(total: number, bytes: number): boolean {
+  return total + bytes > TOTAL_DIFF_MAX_BYTES;
+}
+function needsBody(target: Target, entry: DiffEntry, identity: string): boolean {
+  return (
+    entry.content === "text" &&
+    (target.error !== null || target.cache.get(entry.path)?.identity !== identity)
+  );
+}
+
+function diffError(error: unknown): DiffError {
+  return {
+    code: error instanceof DiffReadError ? error.code : "UNKNOWN",
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+export { DiffSession } from "./session.js";
+
+function endpointKey(endpoint: DiffEndpoint): string[] {
+  if (endpoint.kind === "rev") return [endpoint.kind, endpoint.rev];
+  return [endpoint.kind];
+}
diff --git a/packages/server/src/server/diff/inputs.ts b/packages/server/src/server/diff/inputs.ts
new file mode 100644
index 0000000000..84a5a7f446
--- /dev/null
+++ b/packages/server/src/server/diff/inputs.ts
@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { runGitCommand, type GitCommandOptions } from "../../utils/run-git-command.js";
+
+interface Interpretation {
+  config: string;
+  attributes: Map<string, string[]>;
+  fingerprint: string;
+}
+
+// Reuse depends on Git's interpretation, not just filesystem metadata. Ask Git
+// for effective attributes/config and filtered blob identities without writing objects.
+export async function readGitInputs(
+  paths: string[],
+  worktreeFiles: Set<string>,
+  options: GitCommandOptions,
+) {
+  const regular = paths.filter((path) => worktreeFiles.has(path));
+  const [interpretation, blobs] = await Promise.all([
+    readInterpretation(paths, options),
+    regular.length
+      ? runGitCommand(["hash-object", "--stdin-paths"], {
+          ...options,
+          input: regular.map(quotePath).join("\n") + "\n",
+        })
+      : null,
+  ]);
+  if (blobs?.truncated) throw new Error("Git input identity exceeded the output budget");
+  const hashes = blobs?.stdout.trim().split(/\r?\n/) ?? [];
+  if (hashes.length !== regular.length) throw new Error("Git returned incomplete blob identities");
+  const blobByPath = new Map(regular.map((path, index) => [path, hashes[index]]));
+  const identities = new Map(
+    paths.map((path) => [
+      path,
+      fingerprint([
+        interpretation.config,
+        interpretation.attributes.get(path) ?? [],
+        blobByPath.get(path) ?? null,
+      ]),
+    ]),
+  );
+  return {
+    identities,
+    hasInterpretationChanged: interpretationCheck(paths, options.cwd, interpretation.fingerprint),
+  };
+}
+
+function interpretationCheck(
+  paths: string[],
+  cwd: string,
+  baseline: string,
+): () => Promise<boolean> {
+  // Retain only the input description, never a comparison's patch/source pages.
+  return async () => {
+    const current = await readInterpretation(paths, {
+      cwd,
+      envOverlay: { GIT_OPTIONAL_LOCKS: "0" },
+    });
+    return current.fingerprint !== baseline;
+  };
+}
+
+async function readInterpretation(
+  paths: string[],
+  options: GitCommandOptions,
+): Promise<Interpretation> {
+  if (!paths.length) return { config: "", attributes: new Map(), fingerprint: "" };
+  const [config, result] = await Promise.all([
+    runGitCommand(["config", "--null", "--list"], options),
+    runGitCommand(["check-attr", "--all", "-z", "--stdin"], {
+      ...options,
+      input: paths.join("\0") + "\0",
+    }),
+  ]);
+  if (config.truncated || result.truncated)
+    throw new Error("Git input identity exceeded the output budget");
+  const attributes = new Map<string, string[]>();
+  const fields = result.stdout.split("\0");
+  if (fields.at(-1) === "") fields.pop();
+  if (fields.length % 3) throw new Error("Git returned invalid attributes");
+  for (let index = 0; index < fields.length; index += 3) {
+    const values = attributes.get(fields[index]) ?? [];
+    values.push(JSON.stringify([fields[index + 1], fields[index + 2]]));
+    attributes.set(fields[index], values);
+  }
+  for (const values of attributes.values()) values.sort();
+  const configIdentity = createHash("sha256").update(config.stdout).digest("hex");
+  return {
+    config: configIdentity,
+    attributes,
+    fingerprint: fingerprint([
+      configIdentity,
+      paths.map((path) => [path, attributes.get(path) ?? []]),
+    ]),
+  };
+}
+
+function fingerprint(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function quotePath(path: string): string {
+  let quoted = '"';
+  for (const byte of Buffer.from(path)) {
+    quoted +=
+      byte >= 32 && byte <= 126 && byte !== 34 && byte !== 92
+        ? String.fromCharCode(byte)
+        : `\\${byte.toString(8).padStart(3, "0")}`;
+  }
+  return quoted + '"';
+}
diff --git a/packages/server/src/server/diff/patches.ts b/packages/server/src/server/diff/patches.ts
new file mode 100644
index 0000000000..ef5dbc08c1
--- /dev/null
+++ b/packages/server/src/server/diff/patches.ts
@@ -0,0 +1,80 @@
+import { runGitCommand, type GitCommandOptions } from "../../utils/run-git-command.js";
+import { parseDiff } from "../utils/diff-highlighter.js";
+import type { ListedFile } from "./git.js";
+
+interface Patch {
+  stdout: string;
+  truncated: boolean;
+}
+
+// Acquire one bounded page lazily. Highlighting and delivery remain per file.
+export class Patches {
+  private files: ListedFile[];
+  private pending = new Map<string, Promise<Map<string, Patch>>>();
+  constructor(
+    private args: string[],
+    private options: GitCommandOptions,
+    files: ListedFile[],
+  ) {
+    this.files = files.filter((file) => file.source.kind === "tracked" && file.entry.body);
+  }
+  select(paths: ReadonlySet<string>): void {
+    this.files = this.files.filter((file) => paths.has(file.entry.path));
+  }
+  async read(file: ListedFile, maxBytes: number): Promise<Patch> {
+    const existing = this.pending.get(file.entry.path);
+    if (existing) return (await existing).get(file.entry.path) ?? { stdout: "", truncated: false };
+    const renamed = file.entry.oldPath !== null;
+    const candidates = this.files.filter(
+      (candidate) => (candidate.entry.oldPath !== null) === renamed,
+    );
+    const index = candidates.indexOf(file);
+    const page = renamed || index < 0 ? [file] : candidates.slice(index, index + 64);
+    this.pending.clear();
+    const reading = this.load(page, maxBytes);
+    for (const candidate of page) this.pending.set(candidate.entry.path, reading);
+    return (await reading).get(file.entry.path) ?? { stdout: "", truncated: false };
+  }
+
+  private async load(files: ListedFile[], maxBytes: number): Promise<Map<string, Patch>> {
+    const paths = [
+      ...new Set(
+        files.flatMap((file) =>
+          file.entry.oldPath === null ? [file.entry.path] : [file.entry.oldPath, file.entry.path],
+        ),
+      ),
+    ];
+    const result = await runGitCommand(
+      [
+        ...this.args,
+        ...(files[0].entry.oldPath !== null ? ["--diff-filter=RC"] : []),
+        "--patch",
+        "--",
+        ...paths.map((path) => `:(literal)${path}`),
+      ],
+      {
+        ...this.options,
+        acceptExitCodes: [0, 1],
+        maxOutputBytes: (files.length === 1 ? maxBytes : 8 * maxBytes) + 1,
+      },
+    );
+    if (files.length === 1) return new Map([[files[0].entry.path, result]]);
+    if (result.truncated) {
+      const middle = Math.ceil(files.length / 2);
+      return new Map([
+        ...(await this.load(files.slice(0, middle), maxBytes)),
+        ...(await this.load(files.slice(middle), maxBytes)),
+      ]);
+    }
+    const patches = new Map<string, Patch>();
+    for (const section of result.stdout.split(/(?=^diff --git )/m).filter(Boolean)) {
+      const hunkStart = section.indexOf("\n@@ ");
+      const parsed = parseDiff(hunkStart < 0 ? section : section.slice(0, hunkStart))[0];
+      if (!parsed) throw new Error("Git returned an invalid patch header");
+      const previous = patches.get(parsed.path)?.stdout ?? "";
+      const stdout = previous + section;
+      patches.set(parsed.path, { stdout, truncated: Buffer.byteLength(stdout) > maxBytes });
+    }
+    return patches;
+  }
+}
diff --git a/packages/server/src/server/diff/session.test.ts b/packages/server/src/server/diff/session.test.ts
new file mode 100644
index 0000000000..3ffc0a40e5
--- /dev/null
+++ b/packages/server/src/server/diff/session.test.ts
@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import pino from "pino";
+import { expect, test } from "vitest";
+import {
+  decodeDiffFrame,
+  DiffOpcode,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import { DiffSession, DiffSubscriptions } from "./index.js";
+import { createFileObserver } from "../file-observer/index.js";
+import { SessionDelivery } from "../session/owned-subscriptions/index.js";
+
+test("a failed physical send releases that subscriber while its sibling completes the revision", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-send-failure-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const observer = createFileObserver();
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root, changed) {
+      const watch = await observer.subscribe(root, () => changed(), {
+        ignore: [join(root, ".git")],
+      });
+      return {
+        repoRoot: root,
+        unsubscribe: async () => {
+          await watch.unsubscribe();
+        },
+      };
+    },
+  });
+  const first = {};
+  const second = {};
+  let failFirst = false;
+  const firstFrames: DiffFrame[] = [];
+  const secondFrames: DiffFrame[] = [];
+  const delivery = new SessionDelivery(
+    () => {},
+    async (source, bytes) => {
+      if (source === first && failFirst) throw new Error("Physical send failed");
+      const frame = decodeDiffFrame(bytes);
+      const received = source === first ? firstFrames : secondFrames;
+      received.push(frame);
+    },
+  );
+  delivery.attach(first, true);
+  delivery.attach(second, true);
+  const session = new DiffSession(subscriptions, pino({ level: "silent" }));
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "x.ts"), "export const value = 1;\n");
+    for (const [source, requestId] of [
+      [first, "first"],
+      [second, "second"],
+    ] as const) {
+      const message = {
+        type: "diff.subscribe.request" as const,
+        requestId,
+        cwd,
+        base: { kind: "rev" as const, rev: "HEAD" },
+        head: { kind: "worktree" as const },
+      };
+      await delivery.request(source, message, () => session.subscribe(message, delivery, () => {}));
+      const received = source === first ? firstFrames : secondFrames;
+      await waitForEnd(received);
+    }
+    secondFrames.length = 0;
+    failFirst = true;
+    await writeFile(join(cwd, "x.ts"), "export const value = 2;\n");
+    await waitForEnd(secondFrames);
+    const begins = secondFrames
+      .filter((frame) => frame.opcode === DiffOpcode.Begin)
+      .map((frame) => frame.revision);
+    expect(new Set(begins).size).toBe(begins.length);
+    expect(secondFrames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+    expect(delivery.subscriptionIds(first, "diffs")).toEqual([]);
+    expect(delivery.subscriptionIds(second, "diffs")).toHaveLength(1);
+  } finally {
+    await delivery.close();
+    await subscriptions.close();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+async function waitForEnd(frames: DiffFrame[]): Promise<void> {
+  await expect
+    .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+    .toBe(true);
+}
diff --git a/packages/server/src/server/diff/session.ts b/packages/server/src/server/diff/session.ts
new file mode 100644
index 0000000000..a965b2fa91
--- /dev/null
+++ b/packages/server/src/server/diff/session.ts
@@ -0,0 +1,86 @@
+import type { Logger } from "pino";
+import { encodeDiffFrame } from "@getpaseo/protocol/binary-frames/index";
+import type {
+  DiffSubscribeRequest,
+  SessionOutboundMessage,
+  DiffError,
+} from "@getpaseo/protocol/messages";
+import type { SessionDelivery, OwnedSubscription } from "../session/owned-subscriptions/index.js";
+import { DiffReadError } from "./git.js";
+import type { DiffSubscriptions, DiffSubscription } from "./index.js";
+
+export class DiffSession {
+  private slots = new Set<number>();
+  constructor(
+    private subscriptions: DiffSubscriptions,
+    private logger: Pick<Logger, "debug" | "error">,
+  ) {}
+  async subscribe(
+    msg: DiffSubscribeRequest,
+    ownership: SessionDelivery,
+    emit: (message: SessionOutboundMessage) => void,
+  ): Promise<void> {
+    const slot = Array.from({ length: 256 }, (_, value) => value).find(
+      (value) => !this.slots.has(value),
+    );
+    if (slot === undefined) {
+      this.reject(msg, emit, {
+        code: "TOO_MANY_SUBSCRIPTIONS",
+        message: "Too many diff subscriptions",
+      });
+      return;
+    }
+    this.slots.add(slot);
+    let subscription: DiffSubscription | null = null;
+    const owner = ownership.begin("diffs", undefined, async () => {
+      this.slots.delete(slot);
+      await subscription?.release();
+    });
+    try {
+      subscription = await this.subscriptions.subscribe(msg, async (frame) => {
+        if (owner.signal.aborted) return;
+        const bytes = encodeDiffFrame({ ...frame, slot });
+        try {
+          await owner.emitBinaryAndWait(bytes);
+        } catch (error) {
+          void this.stopFailedSource(owner, error);
+        }
+      });
+      if (owner.signal.aborted) {
+        await subscription.release();
+        return;
+      }
+      emit({
+        type: "diff.subscribe.response",
+        payload: { requestId: msg.requestId, subscriptionId: owner.responseId, slot, error: null },
+      });
+      // Start outside the request context: the owned subscription carries delivery authority.
+      void subscription.start().catch((error) => this.stopFailedSource(owner, error));
+    } catch (error) {
+      await owner.release();
+      const code = error instanceof DiffReadError ? error.code : "UNKNOWN";
+      this.reject(msg, emit, {
+        code,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  private async stopFailedSource(owner: OwnedSubscription, error: unknown): Promise<void> {
+    if (!owner.signal.aborted) this.logger.debug({ err: error }, "Diff frame delivery failed");
+    try {
+      await owner.release();
+    } catch (failure) {
+      this.logger.error({ err: failure }, "Failed to release diff subscription");
+    }
+  }
+  private reject(
+    msg: DiffSubscribeRequest,
+    emit: (message: SessionOutboundMessage) => void,
+    error: DiffError,
+  ): void {
+    emit({
+      type: "diff.subscribe.response",
+      payload: { requestId: msg.requestId, subscriptionId: "", slot: 0, error },
+    });
+  }
+}
diff --git a/packages/server/src/server/diff/sources.ts b/packages/server/src/server/diff/sources.ts
new file mode 100644
index 0000000000..776303a9eb
--- /dev/null
+++ b/packages/server/src/server/diff/sources.ts
@@ -0,0 +1,76 @@
+import { lstat, readlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readGitFileContents, readGitFileContentAtRef } from "../../utils/git-file-contents.js";
+import type { ListedFile } from "./git.js";
+
+interface SourceOptions {
+  cwd: string;
+  baseSha: string;
+  headSha: string | null;
+  files: ListedFile[];
+}
+interface HighlightContext {
+  oldFileContent: string | null;
+  newFileContent: string | null | undefined;
+}
+
+// Keep one bounded page of source text; bodies are still highlighted only when requested.
+export class HighlightSources {
+  private indices: Map<string, number>;
+  private page = -1;
+  private pending: Promise<Map<string, string | null> | null> | null = null;
+  constructor(private options: SourceOptions) {
+    this.indices = new Map(options.files.map((file, index) => [file.entry.path, index]));
+  }
+  async read(file: ListedFile): Promise<HighlightContext> {
+    const index = this.indices.get(file.entry.path);
+    if (index === undefined) throw new Error("Unknown comparison file");
+    const page = Math.floor(index / 64) * 64;
+    if (this.pending === null || this.page !== page) {
+      this.page = page;
+      this.pending = this.load(page);
+    }
+    const contents = await this.pending;
+    const oldFileContent =
+      file.entry.change === "added"
+        ? null
+        : await this.content(contents, this.options.baseSha, file.entry.oldPath ?? file.entry.path);
+    let newFileContent: string | null | undefined;
+    if (this.options.headSha !== null) {
+      newFileContent = await this.content(contents, this.options.headSha, file.entry.path);
+    } else if (file.entry.change !== "deleted") {
+      const path = resolve(this.options.cwd, file.entry.path);
+      newFileContent = await readWorktreeLink(path);
+    }
+    return { oldFileContent, newFileContent };
+  }
+  private async load(start: number): Promise<Map<string, string | null> | null> {
+    const specs: string[] = [];
+    for (const file of this.options.files.slice(start, start + 64)) {
+      if (file.entry.content === "binary") continue;
+      if (file.entry.change !== "added")
+        specs.push(`${this.options.baseSha}:${file.entry.oldPath ?? file.entry.path}`);
+      if (this.options.headSha !== null) specs.push(`${this.options.headSha}:${file.entry.path}`);
+    }
+    return readGitFileContents(this.options.cwd, specs);
+  }
+  private async content(
+    contents: Map<string, string | null> | null,
+    ref: string,
+    path: string,
+  ): Promise<string | null> {
+    if (contents === null) return readGitFileContentAtRef(this.options.cwd, ref, path);
+    const content = contents.get(`${ref}:${path}`);
+    if (content === undefined) throw new Error("Missing comparison source");
+    return content;
+  }
+}
+
+async function readWorktreeLink(path: string): Promise<string | undefined> {
+  try {
+    if ((await lstat(path)).isSymbolicLink()) return await readlink(path);
+  } catch {
+    // Source context is optional; files can disappear after Git reads the patch.
+  }
+  return undefined;
+}
diff --git a/packages/server/src/server/diff/subscriptions.test.ts b/packages/server/src/server/diff/subscriptions.test.ts
new file mode 100644
index 0000000000..6f792a3311
--- /dev/null
+++ b/packages/server/src/server/diff/subscriptions.test.ts
@@ -0,0 +1,1045 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { expect, test } from "vitest";
+import { DiffOpcode, type DiffFrame } from "@getpaseo/protocol/binary-frames/index";
+import { DiffSubscriptions } from "./index.js";
+import { createFileObserver } from "../file-observer/index.js";
+import {
+  configureGitProcessPolicy,
+  runGitCommand,
+  runWithGitCommandPriority,
+} from "../../utils/run-git-command.js";
+import {
+  DEFAULT_GIT_PROCESS_POLICY,
+  resolveGitProcessPolicy,
+} from "../../utils/git-process-scheduler.js";
+
+async function createObservedWorktreeDiff(prefix: string) {
+  const cwd = await mkdtemp(join(tmpdir(), prefix));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const observer = createFileObserver();
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root, onChange) {
+      const watch = await observer.subscribe(root, () => onChange(), {
+        ignore: [join(root, ".git")],
+      });
+      return {
+        repoRoot: root,
+        unsubscribe: async () => {
+          await watch.unsubscribe();
+        },
+      };
+    },
+  });
+  git("init", "-b", "main");
+  git("config", "user.email", "test@example.com");
+  git("config", "user.name", "Test");
+  for (const directory of ["src", "src/nested", "docs"]) {
+    await mkdir(join(cwd, directory), { recursive: true });
+    for (let index = 0; index < 40; index++)
+      await writeFile(join(cwd, directory, `${index}.ts`), `export const value = ${index};\n`);
+  }
+  git("add", ".");
+  git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+  for (let index = 0; index < 10; index++)
+    await writeFile(join(cwd, "src", `${index}.ts`), `export const value = ${index + 100};\n`);
+  return {
+    cwd,
+    subscriptions,
+    compare: {
+      cwd,
+      base: { kind: "rev" as const, rev: "HEAD" },
+      head: { kind: "worktree" as const },
+      highlight: true,
+    },
+    async close() {
+      await subscriptions.close();
+      await observer.close();
+      await rm(cwd, { recursive: true, force: true });
+    },
+  };
+}
+
+test("a cold worktree diff over existing files is complete at its first revision", async () => {
+  const fixture = await createObservedWorktreeDiff("diff-cold-revision-");
+  const frames: DiffFrame[] = [];
+  try {
+    const subscription = await fixture.subscriptions.subscribe(fixture.compare, async (frame) => {
+      frames.push(frame);
+    });
+    await subscription.start();
+    await writeFile(join(fixture.cwd, "docs", "0.ts"), "export const value = 999;\n");
+    await expect
+      .poll(() => frames.filter((frame) => frame.opcode === DiffOpcode.End).length, {
+        timeout: 10_000,
+      })
+      .toBe(2);
+    expect(
+      frames.filter((frame) => frame.opcode === DiffOpcode.Begin).map((frame) => frame.revision),
+    ).toEqual([1, 2]);
+    await subscription.release();
+  } finally {
+    await fixture.close();
+  }
+}, 30_000);
+
+test("a cold diff finishes ahead of a queued background Git burst", async () => {
+  const fixture = await createObservedWorktreeDiff("diff-cold-burst-");
+  // The suite lifts the start-rate cap; the burst needs the daemon's real one.
+  configureGitProcessPolicy(DEFAULT_GIT_PROCESS_POLICY);
+  try {
+    let burstSettledAt = Number.POSITIVE_INFINITY;
+    // ~3 s of queued work at 64 starts/s, the shape of a reconciliation rescan.
+    const burst = runWithGitCommandPriority("background", () =>
+      Promise.all(
+        Array.from({ length: 200 }, () =>
+          runGitCommand(["rev-parse", "HEAD"], { cwd: fixture.cwd }),
+        ),
+      ),
+    ).then(() => {
+      burstSettledAt = performance.now();
+      return undefined;
+    });
+    let readyAt = Number.POSITIVE_INFINITY;
+    const subscription = await fixture.subscriptions.subscribe(fixture.compare, async (frame) => {
+      if (frame.opcode === DiffOpcode.End && frame.error === null) readyAt = performance.now();
+    });
+    await subscription.start();
+    await burst;
+    expect(readyAt).toBeLessThan(burstSettledAt);
+    await subscription.release();
+  } finally {
+    configureGitProcessPolicy(resolveGitProcessPolicy({ env: process.env }));
+    await fixture.close();
+  }
+}, 30_000);
+
+test("shares computation, highlights only the changed file, recovers refs and releases observations", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-subscriptions-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const observer = createFileObserver();
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root, onChange) {
+      const subscription = await observer.subscribe(root, () => onChange(), {
+        ignore: [join(root, ".git")],
+      });
+      return {
+        repoRoot: root,
+        unsubscribe: () => {
+          void subscription.unsubscribe();
+        },
+      };
+    },
+  });
+  const first: DiffFrame[] = [];
+  const second: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    for (let index = 0; index < 252; index++)
+      await writeFile(join(cwd, `${index}.ts`), `const value = ${index};\n`);
+    const compare = {
+      cwd,
+      base: { kind: "rev" as const, rev: "HEAD" },
+      head: { kind: "worktree" as const },
+      highlight: true,
+    };
+    const coldStarted = performance.now();
+    let lastEndAt = coldStarted;
+    const a = await subscriptions.subscribe(compare, async (frame) => {
+      first.push(frame);
+      if (frame.opcode === DiffOpcode.End) lastEndAt = performance.now();
+    });
+    await a.start();
+    const coldMs = lastEndAt - coldStarted;
+    const before = subscriptions.getMetrics().computations;
+    const previousHighlightCalls = subscriptions.getMetrics().highlightCalls;
+    const b = await subscriptions.subscribe(compare, async (frame) => {
+      second.push(frame);
+    });
+    await b.start();
+    expect(subscriptions.getMetrics()).toEqual({
+      targets: 1,
+      subscriptions: 2,
+      computations: before,
+      highlightCalls: previousHighlightCalls,
+      metadataObservers: 1,
+    });
+    first.length = 0;
+    second.length = 0;
+    const refreshStarted = performance.now();
+    await writeFile(join(cwd, "9.ts"), "const value = 999;\n");
+    await expect
+      .poll(() => first.filter((frame) => frame.opcode === DiffOpcode.End).length, {
+        timeout: 10000,
+      })
+      .toBeGreaterThan(0);
+    const begin = first.find((frame) => frame.opcode === DiffOpcode.Begin);
+    if (!begin || begin.opcode !== DiffOpcode.Begin) throw new Error("Missing begin");
+    expect(begin.entries.filter((entry) => entry.body).map((entry) => entry.path)).toEqual([
+      "9.ts",
+    ]);
+    const bodies = first.filter((frame) => frame.opcode === DiffOpcode.Bodies);
+    expect(bodies).toHaveLength(1);
+    expect(second).toEqual(first);
+    await expect
+      .poll(() => subscriptions.getMetrics().highlightCalls, { timeout: 10000 })
+      .toBe(previousHighlightCalls + 1);
+    const artifactDirectory = join(
+      import.meta.dirname,
+      "../../../../../.artifacts/diff-subscription",
+    );
+    await mkdir(artifactDirectory, { recursive: true });
+    await writeFile(
+      join(artifactDirectory, "refresh-metrics.json"),
+      JSON.stringify(
+        {
+          files: 252,
+          coldMs,
+          oneFileRefreshMs: lastEndAt - refreshStarted,
+          changedBodies: bodies.length,
+          highlightCalls: subscriptions.getMetrics().highlightCalls - previousHighlightCalls,
+        },
+        null,
+        2,
+      ),
+    );
+    await a.release();
+    await b.release();
+    expect(subscriptions.getMetrics().targets).toBe(0);
+    expect(subscriptions.getMetrics().metadataObservers).toBe(0);
+    const missing: DiffFrame[] = [];
+    const recovery = await subscriptions.subscribe(
+      {
+        ...compare,
+        base: { kind: "rev", rev: "refs/tags/later" },
+        head: { kind: "rev", rev: "HEAD" },
+      },
+      async (frame) => {
+        missing.push(frame);
+      },
+    );
+    await recovery.start();
+    expect(missing.at(-1)).toMatchObject({
+      opcode: DiffOpcode.End,
+      error: { code: "REF_NOT_FOUND" },
+    });
+    missing.length = 0;
+    git("update-ref", "refs/tags/later", "HEAD");
+    await expect
+      .poll(
+        () => missing.some((frame) => frame.opcode === DiffOpcode.End && frame.error === null),
+        { timeout: 10_000 },
+      )
+      .toBe(true);
+    await recovery.release();
+  } finally {
+    await subscriptions.close();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 60_000);
+
+test("supersedes an in-flight revision at a batch boundary and ends the replacement", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-supersede-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const observer = createFileObserver();
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root, onChange) {
+      const watch = await observer.subscribe(root, () => onChange(), {
+        ignore: [join(root, ".git")],
+      });
+      return {
+        repoRoot: root,
+        unsubscribe: async () => {
+          await watch.unsubscribe();
+        },
+      };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  let interrupted = false;
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const content =
+      Array.from(
+        { length: 100 },
+        (_, index) => `export const fn${index} = (value: string) => ({ value, count: ${index} });`,
+      ).join("\n") + "\n";
+    for (let index = 0; index < 80; index++) await writeFile(join(cwd, `${index}.ts`), content);
+    const subscription = await subscriptions.subscribe(
+      { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "worktree" } },
+      async (frame) => {
+        frames.push(frame);
+        if (frame.opcode === DiffOpcode.Bodies && !interrupted) {
+          interrupted = true;
+          await writeFile(join(cwd, "0.ts"), content + "export const added = true;\n");
+          await subscriptions.invalidateForCwd(cwd);
+        }
+      },
+    );
+    await subscription.start();
+    const begins = frames.filter((frame) => frame.opcode === DiffOpcode.Begin);
+    expect(interrupted).toBe(true);
+    expect(begins.length).toBeGreaterThan(1);
+    for (let index = 0; index < begins.length - 1; index++) {
+      const revision = begins[index].revision;
+      const ended = frames.some(
+        (frame) => frame.opcode === DiffOpcode.End && frame.revision === revision,
+      );
+      const superseded = begins[index + 1].revision > revision;
+      expect(ended || superseded).toBe(true);
+    }
+    expect(frames.at(-1)).toMatchObject({
+      opcode: DiffOpcode.End,
+      revision: begins.at(-1)?.revision,
+      error: null,
+    });
+    await subscription.release();
+  } finally {
+    await subscriptions.close();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30_000);
+
+test("moving, deleting and recreating a branch recovers, and staging changes the resolved index SHA", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-ref-index-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const observer = createFileObserver();
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root, changed) {
+      const watch = await observer.subscribe(root, () => changed(), {
+        ignore: [join(root, ".git")],
+      });
+      return {
+        repoRoot: root,
+        unsubscribe: async () => {
+          await watch.unsubscribe();
+        },
+      };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git("branch", "compare");
+    await writeFile(join(cwd, "x.ts"), "export const value = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "feature");
+    const head = git("rev-parse", "HEAD");
+    const branch = await subscriptions.subscribe(
+      { cwd, base: { kind: "rev", rev: "refs/heads/compare" }, head: { kind: "rev", rev: "HEAD" } },
+      async (frame) => {
+        frames.push(frame);
+      },
+    );
+    await branch.start();
+    frames.length = 0;
+    git("update-ref", "refs/heads/compare", head);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    expect(frames.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+      baseSha: head,
+      entries: [],
+    });
+    frames.length = 0;
+    git("update-ref", "-d", "refs/heads/compare");
+    await expect
+      .poll(
+        () =>
+          frames.some(
+            (frame) => frame.opcode === DiffOpcode.End && frame.error?.code === "REF_NOT_FOUND",
+          ),
+        { timeout: 10000 },
+      )
+      .toBe(true);
+    frames.length = 0;
+    git("update-ref", "refs/heads/compare", head);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End && frame.error === null), {
+        timeout: 10000,
+      })
+      .toBe(true);
+    await branch.release();
+    frames.length = 0;
+    const staged = await subscriptions.subscribe(
+      { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "index" } },
+      async (frame) => {
+        frames.push(frame);
+      },
+    );
+    await staged.start();
+    const old = frames.find((frame) => frame.opcode === DiffOpcode.Begin);
+    if (!old || old.opcode !== DiffOpcode.Begin) throw new Error("Missing initial index revision");
+    frames.length = 0;
+    await writeFile(join(cwd, "staged.ts"), "export const staged = true;\n");
+    git("add", "staged.ts");
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    const changed = frames.find((frame) => frame.opcode === DiffOpcode.Begin);
+    if (!changed || changed.opcode !== DiffOpcode.Begin) throw new Error("Missing staged revision");
+    expect(changed.headSha).not.toBe(old.headSha);
+    expect(changed.entries.map((entry) => entry.path)).toEqual(["staged.ts"]);
+    await staged.release();
+  } finally {
+    await subscriptions.close();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test("a cached replay completes before a live refresh can depend on it", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-replay-order-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+  const subscriptions = new DiffSubscriptions({
+    async requestWorkingTreeWatch() {
+      return { repoRoot: cwd, unsubscribe: async () => {} };
+    },
+  });
+  let resume!: () => void;
+  let began!: () => void;
+  const paused = new Promise<void>((resolve) => {
+    resume = resolve;
+  });
+  const replayBegan = new Promise<void>((resolve) => {
+    began = resolve;
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "a.txt"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "a.txt"), "first\n");
+    const compare = {
+      cwd,
+      base: { kind: "rev", rev: "HEAD" },
+      head: { kind: "worktree" },
+      highlight: false,
+    } as const;
+    const first = await subscriptions.subscribe(compare, async () => {});
+    await first.start();
+    const second = await subscriptions.subscribe(compare, async (frame) => {
+      frames.push(frame);
+      if (frames.length === 1) {
+        began();
+        await paused;
+      }
+    });
+    const replay = second.start();
+    await replayBegan;
+    await writeFile(join(cwd, "a.txt"), "second\n");
+    await subscriptions.invalidateForCwd(cwd);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    resume();
+    await replay;
+    await expect
+      .poll(() => frames.filter((frame) => frame.opcode === DiffOpcode.End).length, {
+        timeout: 10000,
+      })
+      .toBe(2);
+    let committed = 0;
+    for (const frame of frames) {
+      if (frame.opcode === DiffOpcode.Begin) expect([0, committed]).toContain(frame.baseRevision);
+      if (frame.opcode === DiffOpcode.End) committed = frame.revision;
+    }
+    await second.release();
+    await first.release();
+  } finally {
+    resume();
+    await subscriptions.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("submodule commits invalidate cached worktree gitlink bodies", async () => {
+  const { lstat } = await import("node:fs/promises");
+  const cwd = await mkdtemp(join(tmpdir(), "diff-gitlink-cache-"));
+  const sub = join(cwd, "sub");
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const streams = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root) {
+      return { repoRoot: root, unsubscribe: async () => {} };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await mkdir(sub);
+    git("-C", "sub", "init", "-b", "main");
+    git("-C", "sub", "config", "user.name", "Test");
+    git("-C", "sub", "config", "user.email", "test@example.com");
+    await writeFile(join(sub, "a.txt"), "A\n");
+    git("-C", "sub", "add", ".");
+    git("-C", "sub", "-c", "commit.gpgsign=false", "commit", "-m", "A");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "record A");
+    await writeFile(join(sub, "a.txt"), "B\n");
+    git("-C", "sub", "-c", "commit.gpgsign=false", "commit", "-am", "B");
+    const before = await lstat(sub, { bigint: true });
+    const subscription = await streams.subscribe(
+      { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "worktree" } },
+      async (frame) => {
+        frames.push(frame);
+      },
+    );
+    await subscription.start();
+    expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+    frames.length = 0;
+    await writeFile(join(sub, "a.txt"), "C\n");
+    git("-C", "sub", "-c", "commit.gpgsign=false", "commit", "-am", "C");
+    const sha = git("-C", "sub", "rev-parse", "HEAD");
+    expect((await lstat(sub, { bigint: true })).mtimeNs).toBe(before.mtimeNs);
+    await streams.invalidateForCwd(cwd);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 5000 })
+      .toBe(true);
+    const bodies = frames.flatMap((frame) =>
+      frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+    );
+    expect(bodies.flatMap((file) => file.hunks.flatMap((hunk) => hunk.lines))).toContainEqual(
+      expect.objectContaining({ type: "add", content: `Subproject commit ${sha}` }),
+    );
+    await subscription.release();
+  } finally {
+    await streams.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test.each([true, false])(
+  "tracked=%s timestamp-preserving replacements refresh cached bodies",
+  async (tracked) => {
+    const { lstat, utimes } = await import("node:fs/promises");
+    const cwd = await mkdtemp(join(tmpdir(), "diff-preserved-time-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const streams = new DiffSubscriptions({
+      async requestWorkingTreeWatch(root) {
+        return { repoRoot: root, unsubscribe: async () => {} };
+      },
+    });
+    const frames: DiffFrame[] = [];
+    const path = join(cwd, "file.txt");
+    const timestamp = new Date("2000-01-01T00:00:00Z");
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await writeFile(join(cwd, "README"), "base\n");
+      if (tracked) await writeFile(path, "base\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      await writeFile(path, "first\n");
+      await utimes(path, timestamp, timestamp);
+      const compare = {
+        cwd,
+        base: { kind: "rev" as const, rev: "HEAD" },
+        head: { kind: "worktree" as const },
+      };
+      const subscription = await streams.subscribe(compare, async (frame) => {
+        frames.push(frame);
+      });
+      await subscription.start();
+      expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      const before = await lstat(path, { bigint: true });
+      frames.length = 0;
+      await writeFile(path, "later\n");
+      await utimes(path, timestamp, timestamp);
+      const after = await lstat(path, { bigint: true });
+      expect(after.mtimeNs).toBe(before.mtimeNs);
+      expect(after.size).toBe(before.size);
+      expect(after.ctimeNs).not.toBe(before.ctimeNs);
+      await streams.invalidateForCwd(cwd);
+      await expect
+        .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 5000 })
+        .toBe(true);
+      const files = frames.flatMap((frame) =>
+        frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+      );
+      expect(files.flatMap((file) => file.hunks.flatMap((hunk) => hunk.lines))).toContainEqual(
+        expect.objectContaining({ type: "add", content: "later" }),
+      );
+      const { listComparison } = await import("./git.js");
+      const fresh = await listComparison(compare);
+      try {
+        const record = await fresh.read(fresh.files[0]);
+        if (record.kind !== "ready") throw new Error("Expected readable replacement");
+        expect(files).toEqual([record.body]);
+      } finally {
+        await fresh.close();
+      }
+      await subscription.release();
+    } finally {
+      await streams.close();
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test.each([true, false])(
+  "autocrlf=%s highlighted CRLF worktrees keep the revision readable",
+  async (autocrlf) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-crlf-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const streams = new DiffSubscriptions({
+      async requestWorkingTreeWatch(root) {
+        return { repoRoot: root, unsubscribe: async () => {} };
+      },
+    });
+    const frames: DiffFrame[] = [];
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      git("config", "core.autocrlf", String(autocrlf));
+      await writeFile(join(cwd, "a.ts"), "export const value = 1;\r\n");
+      await writeFile(join(cwd, "b.txt"), "before\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      await writeFile(join(cwd, "a.ts"), "export const value = 2;\r\n");
+      await writeFile(join(cwd, "b.txt"), "after\n");
+      const subscription = await streams.subscribe(
+        { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "worktree" } },
+        async (frame) => {
+          frames.push(frame);
+        },
+      );
+      await subscription.start();
+      expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      const files = frames.flatMap((frame) =>
+        frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+      );
+      expect(files.map((file) => file.path)).toEqual(["a.ts", "b.txt"]);
+      const line = files[0].hunks
+        .flatMap((hunk) => hunk.lines)
+        .find((candidate) => candidate.type === "add");
+      expect(line?.content).toBe(`export const value = 2;${autocrlf ? "" : "\r"}`);
+      expect(line?.runs?.reduce((length, run) => length + run.length, 0)).toBe(
+        line?.content.length,
+      );
+      await subscription.release();
+    } finally {
+      await streams.close();
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+);
+
+test("explicit refresh accepts an equivalent worktree path alias", async () => {
+  const { symlink } = await import("node:fs/promises");
+  const root = await mkdtemp(join(tmpdir(), "diff-refresh-alias-"));
+  const cwd = join(root, "repo");
+  const alias = join(root, "alias");
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const streams = new DiffSubscriptions({
+    async requestWorkingTreeWatch(directory) {
+      return { repoRoot: directory, unsubscribe: async () => {} };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    await mkdir(cwd);
+    await symlink(cwd, alias, "junction");
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "a.txt"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const base = git("rev-parse", "HEAD");
+    await writeFile(join(cwd, "a.txt"), "first\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+    const head = git("rev-parse", "HEAD");
+    const subscription = await streams.subscribe(
+      { cwd, base: { kind: "rev", rev: base }, head: { kind: "rev", rev: head } },
+      async (frame) => {
+        frames.push(frame);
+      },
+    );
+    await subscription.start();
+    frames.length = 0;
+    await streams.invalidateForCwd(alias);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, revision: 2, error: null });
+    await subscription.release();
+  } finally {
+    await streams.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("attribute changes refresh interpreted content without rewriting the tracked file", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-attribute-input-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const streams = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root) {
+      return { repoRoot: root, unsubscribe: async () => {} };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    git("config", "core.autocrlf", "false");
+    await writeFile(join(cwd, "file.txt"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await writeFile(join(cwd, "file.txt"), "first\r\n");
+    const compare = {
+      cwd,
+      base: { kind: "rev" as const, rev: "HEAD" },
+      head: { kind: "worktree" as const },
+    };
+    const subscription = await streams.subscribe(compare, async (frame) => {
+      frames.push(frame);
+    });
+    await subscription.start();
+    frames.length = 0;
+    await writeFile(join(cwd, ".git", "info", "attributes"), "file.txt text eol=lf\n");
+    await streams.invalidateForCwd(cwd);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    const files = frames.flatMap((frame) =>
+      frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+    );
+    expect(files.flatMap((file) => file.hunks.flatMap((hunk) => hunk.lines))).toContainEqual(
+      expect.objectContaining({ type: "add", content: "first" }),
+    );
+    const { listComparison } = await import("./git.js");
+    const fresh = await listComparison(compare);
+    try {
+      const record = await fresh.read(fresh.files[0]);
+      if (record.kind !== "ready") throw new Error("Expected interpreted body");
+      expect(files).toEqual([record.body]);
+    } finally {
+      await fresh.close();
+    }
+    await subscription.release();
+  } finally {
+    await streams.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("explicit refresh resolves subdirectories without refreshing a nested repository's parent", async () => {
+  const root = await mkdtemp(join(tmpdir(), "diff-refresh-directory-"));
+  const cwd = join(root, "repo");
+  const directory = join(cwd, "workspace");
+  const nested = join(directory, "nested");
+  const git = (at: string, ...args: string[]) =>
+    execFileSync("git", args, { cwd: at, encoding: "utf8" }).trim();
+  const streams = new DiffSubscriptions({
+    async requestWorkingTreeWatch(at) {
+      return { repoRoot: at, unsubscribe: async () => {} };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  try {
+    await mkdir(nested, { recursive: true });
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "file.txt"), "before\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const base = git(cwd, "rev-parse", "HEAD");
+    await writeFile(join(cwd, "file.txt"), "after\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "edit");
+    const head = git(cwd, "rev-parse", "HEAD");
+    git(nested, "init", "-b", "main");
+    git(nested, "config", "user.name", "Test");
+    git(nested, "config", "user.email", "test@example.com");
+    await writeFile(join(nested, "nested.txt"), "nested content\n");
+    git(nested, "add", ".");
+    git(nested, "-c", "commit.gpgsign=false", "commit", "-m", "nested base");
+    const nestedHead = git(nested, "rev-parse", "HEAD");
+    const subscription = await streams.subscribe(
+      { cwd: directory, base: { kind: "rev", rev: base }, head: { kind: "rev", rev: head } },
+      async (frame) => {
+        frames.push(frame);
+      },
+    );
+    await subscription.start();
+    frames.length = 0;
+    await streams.invalidateForCwd(directory);
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null, revision: 2 });
+    const nestedFrames: DiffFrame[] = [];
+    const sibling = await streams.subscribe(
+      { cwd: nested, base: { kind: "empty" }, head: { kind: "rev", rev: nestedHead } },
+      async (frame) => {
+        nestedFrames.push(frame);
+      },
+    );
+    await sibling.start();
+    nestedFrames.length = 0;
+    const before = streams.getMetrics().computations;
+    await streams.invalidateForCwd(nested);
+    await expect
+      .poll(() => nestedFrames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    expect(streams.getMetrics().computations).toBe(before + 1);
+    await sibling.release();
+    await subscription.release();
+  } finally {
+    await streams.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test.each(["main", "linked"] as const)(
+  "%s checkout observes worktree configuration and shared attributes",
+  async (checkout) => {
+    const { resolve } = await import("node:path");
+    const { readFile } = await import("node:fs/promises");
+    const root = await mkdtemp(join(tmpdir(), "diff-interpretation-watch-"));
+    let cwd = join(root, "repo");
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const streams = new DiffSubscriptions({
+      async requestWorkingTreeWatch(at) {
+        return { repoRoot: at, unsubscribe: async () => {} };
+      },
+    });
+    const frames: DiffFrame[] = [];
+    try {
+      await mkdir(cwd);
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      const lines = Array.from(
+        { length: 20 },
+        (_, index) => `export const value${index} = ${index};`,
+      );
+      await writeFile(join(cwd, "a.ts"), lines.join("\n") + "\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD");
+      lines[10] = "export const value10 = 999;";
+      await writeFile(join(cwd, "a.ts"), lines.join("\n") + "\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      git("config", "extensions.worktreeConfig", "true");
+      if (checkout === "linked") {
+        const linked = join(root, "linked");
+        git("worktree", "add", "-b", "side", linked);
+        cwd = linked;
+      }
+      git("config", "--worktree", "diff.context", "3");
+      const configPath = resolve(cwd, git("rev-parse", "--git-path", "config.worktree"));
+      const configText = await readFile(configPath, "utf8");
+      const subscription = await streams.subscribe(
+        { cwd, base: { kind: "rev", rev: base }, head: { kind: "rev", rev: "HEAD" } },
+        async (frame) => {
+          frames.push(frame);
+        },
+      );
+      await subscription.start();
+      const initialFiles = frames.flatMap((frame) =>
+        frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+      );
+      expect(initialFiles[0].hunks[0].lines.filter((line) => line.type === "context")).toHaveLength(
+        6,
+      );
+      const attributesPath = resolve(cwd, git("rev-parse", "--git-path", "info/attributes"));
+      frames.length = 0;
+      await writeFile(attributesPath, "a.ts -diff\n");
+      await expect
+        .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+        .toBe(true);
+      expect(frames.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+        entries: [{ path: "a.ts", content: "binary" }],
+      });
+      expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      frames.length = 0;
+      await writeFile(attributesPath, "");
+      await expect
+        .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+        .toBe(true);
+      const restoredFiles = frames.flatMap((frame) =>
+        frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+      );
+      expect(
+        restoredFiles[0].hunks[0].lines.filter((line) => line.type === "context"),
+      ).toHaveLength(6);
+      frames.length = 0;
+      const changedConfig = configText.replace("context = 3", "context = 0");
+      expect(changedConfig).not.toBe(configText);
+      await writeFile(configPath, changedConfig);
+      await expect
+        .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+        .toBe(true);
+      expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      const updatedFiles = frames.flatMap((frame) =>
+        frame.opcode === DiffOpcode.Bodies ? frame.files : [],
+      );
+      expect(updatedFiles[0].hunks[0].lines.filter((line) => line.type === "context")).toHaveLength(
+        0,
+      );
+      await subscription.release();
+    } finally {
+      await streams.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+  30000,
+);
+
+test("pinned comparisons refresh Git interpretation before replaying to a joining subscriber", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "diff-pinned-interpretation-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const streams = new DiffSubscriptions({
+    async requestWorkingTreeWatch(root) {
+      return { repoRoot: root, unsubscribe: async () => {} };
+    },
+  });
+  const frames: DiffFrame[] = [];
+  const joined: DiffFrame[] = [];
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    await writeFile(join(cwd, "a.ts"), "export const value = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const base = git("rev-parse", "HEAD");
+    await writeFile(join(cwd, "a.ts"), "export const value = 2;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+    const compare = {
+      cwd,
+      base: { kind: "rev" as const, rev: base },
+      head: { kind: "rev" as const, rev: git("rev-parse", "HEAD") },
+    };
+    const first = await streams.subscribe(compare, async (frame) => {
+      frames.push(frame);
+    });
+    await first.start();
+    expect(frames.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+      entries: [{ path: "a.ts", content: "text" }],
+    });
+    frames.length = 0;
+    await writeFile(join(cwd, ".git", "info", "attributes"), "a.ts -diff\n");
+    await expect
+      .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+      .toBe(true);
+    expect(frames.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+      entries: [{ path: "a.ts", content: "binary" }],
+    });
+    expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+    const computations = streams.getMetrics().computations;
+    const second = await streams.subscribe(compare, async (frame) => {
+      joined.push(frame);
+    });
+    await second.start();
+    expect(joined.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+      entries: [{ path: "a.ts", content: "binary" }],
+    });
+    expect(joined.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+    expect(streams.getMetrics().computations).toBe(computations);
+    await second.release();
+    await first.release();
+  } finally {
+    await streams.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test.each(["pinned", "HEAD"] as const)(
+  "%s revision comparisons observe worktree attributes and replay their current result",
+  async (endpoint) => {
+    const cwd = await mkdtemp(join(tmpdir(), "diff-worktree-attributes-"));
+    const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+    const observer = createFileObserver();
+    const streams = new DiffSubscriptions({
+      async requestWorkingTreeWatch(root, changed) {
+        const watch = await observer.subscribe(root, () => changed(), {
+          ignore: [join(root, ".git")],
+        });
+        return { repoRoot: root, unsubscribe: () => watch.unsubscribe() };
+      },
+    });
+    const frames: DiffFrame[] = [];
+    const joined: DiffFrame[] = [];
+    try {
+      git("init", "-b", "main");
+      git("config", "user.name", "Test");
+      git("config", "user.email", "test@example.com");
+      await writeFile(join(cwd, "a.ts"), "export const value = 1;\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+      const base = git("rev-parse", "HEAD");
+      await writeFile(join(cwd, "a.ts"), "export const value = 2;\n");
+      git("add", ".");
+      git("-c", "commit.gpgsign=false", "commit", "-m", "edit");
+      const compare = {
+        cwd,
+        base: { kind: "rev" as const, rev: base },
+        head: {
+          kind: "rev" as const,
+          rev: endpoint === "HEAD" ? "HEAD" : git("rev-parse", "HEAD"),
+        },
+      };
+      const first = await streams.subscribe(compare, async (frame) => {
+        frames.push(frame);
+      });
+      await first.start();
+      frames.length = 0;
+      await writeFile(join(cwd, ".gitattributes"), "a.ts -diff\n");
+      await expect
+        .poll(() => frames.some((frame) => frame.opcode === DiffOpcode.End), { timeout: 10000 })
+        .toBe(true);
+      expect(frames.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+        entries: [{ path: "a.ts", content: "binary" }],
+      });
+      expect(frames.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      const computations = streams.getMetrics().computations;
+      const second = await streams.subscribe(compare, async (frame) => {
+        joined.push(frame);
+      });
+      await second.start();
+      expect(joined.find((frame) => frame.opcode === DiffOpcode.Begin)).toMatchObject({
+        entries: [{ path: "a.ts", content: "binary" }],
+      });
+      expect(joined.at(-1)).toMatchObject({ opcode: DiffOpcode.End, error: null });
+      expect(streams.getMetrics().computations).toBe(computations);
+      await second.release();
+      await first.release();
+    } finally {
+      await streams.close();
+      await observer.close();
+      await rm(cwd, { recursive: true, force: true });
+    }
+  },
+  30000,
+);
diff --git a/packages/server/src/server/directory-sync/index.ts b/packages/server/src/server/directory-sync/index.ts
index e16e20302f..d115da3dec 100644
--- a/packages/server/src/server/directory-sync/index.ts
+++ b/packages/server/src/server/directory-sync/index.ts
@@ -6,6 +6,7 @@ import type {
   WorkspaceDescriptorPayload,
   WorkspaceProjectDescriptorPayload,
 } from "@getpaseo/protocol/messages";
+import type { BackgroundVisibility } from "../agent/directory.js";
 import { type CollectionRead, VersionedCollection } from "./internal/versioned-collection.js";
 
 interface AgentDirectoryEntry {
@@ -69,7 +70,7 @@ export class DirectorySyncService {
   synchronizeWorkspaces(
     snapshot: Iterable<WorkspaceDescriptorPayload>,
     cursor: DirectorySyncCursor,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): Pick<FetchWorkspacesResponse, "entries" | "emptyProjects" | "pageInfo" | "sync"> {
     this.workspaces.replaceAll(snapshot);
     const read = this.read(this.workspaces, cursor, includeBackground);
@@ -84,7 +85,7 @@ export class DirectorySyncService {
   synchronizeAgents(
     snapshot: Iterable<AgentDirectoryEntry>,
     cursor: DirectorySyncCursor,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): Pick<FetchAgentsResponse, "entries" | "pageInfo" | "sync"> {
     this.agents.replaceAll(snapshot);
     const read = this.read(this.agents, cursor, includeBackground);
@@ -113,7 +114,7 @@ export class DirectorySyncService {
     value: WorkspaceDescriptorPayload | null,
     id: string,
     includeSequence: boolean,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): T & Partial<DirectoryVersion> {
     if (value) {
       this.workspaces.replace(value);
@@ -133,7 +134,7 @@ export class DirectorySyncService {
     value: AgentDirectoryEntry | null,
     id: string,
     includeSequence: boolean,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): T & Partial<DirectoryVersion> {
     if (value) {
       this.agents.replace(value);
@@ -148,7 +149,7 @@ export class DirectorySyncService {
     );
   }
 
-  private metadata(read: CollectionRead<unknown>, includeBackground = false) {
+  private metadata(read: CollectionRead<unknown>, includeBackground: BackgroundVisibility = false) {
     return {
       generation: this.generationFor(includeBackground),
       headSeq: read.headSeq,
@@ -162,7 +163,7 @@ export class DirectorySyncService {
     payload: T,
     includeSequence: boolean,
     version: DirectoryVersion | null,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): T & Partial<DirectoryVersion> {
     return version && includeSequence
       ? { ...payload, ...version, generation: this.generationFor(includeBackground) }
@@ -172,7 +173,7 @@ export class DirectorySyncService {
   private read<T>(
     collection: VersionedCollection<T>,
     cursor: DirectorySyncCursor,
-    includeBackground = false,
+    includeBackground: BackgroundVisibility = false,
   ): CollectionRead<T> {
     if (cursor.generation !== this.generationFor(includeBackground)) {
       return collection.readSnapshot(
@@ -185,7 +186,9 @@ export class DirectorySyncService {
     return collection.readAfter(cursor.afterSeq);
   }
 
-  private generationFor(includeBackground: boolean): string {
+  // Each visibility scope admits a different subset, so cursors never cross scopes.
+  private generationFor(includeBackground: BackgroundVisibility): string {
+    if (includeBackground === "workspaces") return `${this.generation}:background-workspaces`;
     return includeBackground ? `${this.generation}:background` : this.generation;
   }
 
diff --git a/packages/server/src/server/file-observer/index.test.ts b/packages/server/src/server/file-observer/index.test.ts
index 95fe416c54..c30e294817 100644
--- a/packages/server/src/server/file-observer/index.test.ts
+++ b/packages/server/src/server/file-observer/index.test.ts
@@ -47,6 +47,34 @@ test("observes nested files while pruning excluded directories", async () => {
   await subscription.unsubscribe();
 });
 
+// macOS FSEvents can replay writes made just before the stream starts, so the
+// startup contract is only exact on the Linux backend.
+test.skipIf(process.platform !== "linux")(
+  "subscribing to a populated tree reports only later changes",
+  async () => {
+    const root = await createRoot();
+    for (const directory of ["src", join("src", "nested"), "docs"]) {
+      await mkdir(join(root, directory), { recursive: true });
+      await Promise.all(
+        Array.from({ length: 20 }, (_, index) =>
+          writeFile(join(root, directory, `existing-${index}.txt`), `${index}`),
+        ),
+      );
+    }
+    const events: FileChange[] = [];
+    const subscription = await subscribeToFileChanges(root, (error, batch) => {
+      expect(error).toBeNull();
+      events.push(...batch);
+    });
+
+    const laterPath = join(root, "src", "nested", "later.txt");
+    await writeFile(laterPath, "later");
+    await expect.poll(() => events.map((event) => event.path)).toContain(laterPath);
+    expect(new Set(events.map((event) => event.path))).toEqual(new Set([laterPath]));
+    await subscription.unsubscribe();
+  },
+);
+
 test("covers files populated immediately inside a newly created directory", async () => {
   const root = await createRoot();
   const events: FileChange[] = [];
@@ -165,7 +193,11 @@ test("classifies a removed file as deleted", async () => {
   });
 
   await rm(target);
-  await expect.poll(() => events.find((event) => event.path === target)?.type).toBe("delete");
+  // Native recursive delivery can be coalesced before the backend's deletion audit.
+  // Assert eventual classification without imposing Vitest's one-second default.
+  await expect
+    .poll(() => events.find((event) => event.path === target)?.type, { timeout: 10_000 })
+    .toBe("delete");
   await subscription.unsubscribe();
 });
 
diff --git a/packages/server/src/server/file-observer/internal/linux.ts b/packages/server/src/server/file-observer/internal/linux.ts
index d67517a006..dc5138430f 100644
--- a/packages/server/src/server/file-observer/internal/linux.ts
+++ b/packages/server/src/server/file-observer/internal/linux.ts
@@ -23,6 +23,11 @@ const RECONCILIATION_DELAY_MS = 50;
 const MAX_CONCURRENT_CLASSIFICATIONS = 32;
 const MAX_QUEUED_CLASSIFICATIONS = 16_384;
 
+// "baseline" establishes coverage of what already exists when the subscription
+// starts, so it reports nothing. "changes" scans topology that appeared while
+// observed, so files found before their directory was covered are creates.
+type ReconcileMode = "baseline" | "changes";
+
 interface DirectorySnapshot {
   directories: Set<string>;
   filesDiscoveredBeforeCoverage: Set<string>;
@@ -62,7 +67,7 @@ class LinuxBackend implements ObservationBackend {
 
   async start(): Promise<void> {
     this.watchDirectory(this.host.root);
-    await this.enqueue([this.host.root]);
+    await this.enqueue([this.host.root], "baseline");
   }
 
   async updateIgnore(): Promise<void> {
@@ -75,7 +80,7 @@ class LinuxBackend implements ObservationBackend {
       }
     }
     this.cancelQueued();
-    await this.enqueue([this.host.root]);
+    await this.enqueue([this.host.root], "changes");
     await Promise.allSettled(inFlight);
   }
 
@@ -159,15 +164,17 @@ class LinuxBackend implements ObservationBackend {
       this.timer = null;
       const scopes = [...this.pendingScopes];
       this.pendingScopes.clear();
-      void this.enqueue(scopes).catch((error: unknown) => this.host.fail(toError(error)));
+      void this.enqueue(scopes, "changes").catch((error: unknown) =>
+        this.host.fail(toError(error)),
+      );
     }, RECONCILIATION_DELAY_MS);
     this.timer.unref();
   }
 
-  private enqueue(scopes: string[]): Promise<void> {
+  private enqueue(scopes: string[], mode: ReconcileMode): Promise<void> {
     this.queueDepth += 1;
     const result = this.reconcileTail
-      .then(() => this.run(scopes))
+      .then(() => this.run(scopes, mode))
       .finally(() => {
         this.queueDepth -= 1;
       });
@@ -175,12 +182,12 @@ class LinuxBackend implements ObservationBackend {
     return result;
   }
 
-  private async run(scopes: string[]): Promise<void> {
+  private async run(scopes: string[], mode: ReconcileMode): Promise<void> {
     if (!this.host.isActive()) return;
     this.inFlight = true;
     const startedAt = performance.now();
     try {
-      await this.reconcile(this.paths.collapse(scopes));
+      await this.reconcile(this.paths.collapse(scopes), mode);
     } catch (error) {
       this.host.metrics.reconciliationFailureCount += 1;
       throw error;
@@ -197,15 +204,17 @@ class LinuxBackend implements ObservationBackend {
     }
   }
 
-  private async reconcile(scopes: string[]): Promise<void> {
+  private async reconcile(scopes: string[], mode: ReconcileMode): Promise<void> {
     for (const scope of scopes) {
       const snapshot = await this.scan(scope);
       if (!this.host.isActive()) return;
       for (const directory of snapshot.directories) {
         if (!this.watchSnapshotDirectory(directory)) snapshot.directories.delete(directory);
       }
-      for (const path of snapshot.filesDiscoveredBeforeCoverage) {
-        this.host.queueEvent("create", path);
+      if (mode === "changes") {
+        for (const path of snapshot.filesDiscoveredBeforeCoverage) {
+          this.host.queueEvent("create", path);
+        }
       }
       for (const [directory, watcher] of this.watchers) {
         const disappeared =
diff --git a/packages/server/src/server/file-observer/internal/native-recursive.test.ts b/packages/server/src/server/file-observer/internal/native-recursive.test.ts
index 12ab1b18f3..8511e26bbf 100644
--- a/packages/server/src/server/file-observer/internal/native-recursive.test.ts
+++ b/packages/server/src/server/file-observer/internal/native-recursive.test.ts
@@ -60,6 +60,7 @@ test.each(["existing", "new"])(
       await Promise.all(removed.map((path) => rm(path)));
       vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance"] });
       for (const path of removed) notifications.emit("change", "change", path);
+      // The file-only event uses the eight-second optional audit debounce.
       await vi.advanceTimersByTimeAsync(8_000);
       vi.useRealTimers();
       await expect
@@ -309,79 +310,98 @@ test("a classification shed onto the scoped audit still recovers the file", asyn
 // re-link `directory` itself back into its parent -- walkSubtree only
 // descends through that link, so without the re-link a later ancestor
 // removal can no longer reach anything below the reconciled directory.
-test("a recursive-scope reconcile re-links its directory so an ancestor removal still finds nested files", async () => {
-  const root = await mkdtemp(join(tmpdir(), "native-relink-"));
-  const paths = createObserverPaths(process.platform);
-  const deepDirectory = join(root, "a", "b", "c");
-  const deepFile = join(deepDirectory, "deep.txt");
-  await mkdir(deepDirectory, { recursive: true });
-  await writeFile(deepFile, "content");
-  const events: FileChange[] = [];
-  const notifications = new EventEmitter();
-  const observer = createFileObserver();
-  let active = true;
-  const backend = createNativeRecursiveBackend(
-    {
-      root,
-      metrics: observer.getDiagnostics(),
-      isActive: () => active,
-      isIgnored: () => false,
-      isPathInside: paths.isInside,
-      queueEvent: (type, path) => events.push({ type, path }),
-      fail: (error) => {
-        throw error;
-      },
-    },
-    paths,
-    (_root, listener) => {
-      notifications.on("change", listener);
-      return {
-        close: () => notifications.removeAllListeners(),
-        on: (event, onError) => notifications.on(event, onError),
-      };
-    },
-  );
-  const settled = () =>
-    expect
-      .poll(
-        () => {
-          const diagnostics = backend.getDiagnostics();
-          return (
-            diagnostics.pendingReconciliationWorkCount === 0 && !diagnostics.reconciliationInFlight
-          );
+test.each([
+  { notification: "ancestor", deletedPath: ["a"] },
+  { notification: "file", deletedPath: ["a", "b", "c", "deep.txt"] },
+])(
+  "a recursive-scope reconcile preserves nested deletions announced by $notification",
+  async ({ deletedPath }) => {
+    const root = await mkdtemp(join(tmpdir(), "native-relink-"));
+    const paths = createObserverPaths(process.platform);
+    const deepDirectory = join(root, "a", "b", "c");
+    const deepFile = join(deepDirectory, "deep.txt");
+    await mkdir(deepDirectory, { recursive: true });
+    await writeFile(deepFile, "content");
+    const events: FileChange[] = [];
+    const notifications = new EventEmitter();
+    const observer = createFileObserver();
+    let active = true;
+    const backend = createNativeRecursiveBackend(
+      {
+        root,
+        metrics: observer.getDiagnostics(),
+        isActive: () => active,
+        isIgnored: () => false,
+        isPathInside: paths.isInside,
+        queueEvent: (type, path) => events.push({ type, path }),
+        fail: (error) => {
+          throw error;
         },
-        { timeout: 10_000 },
-      )
-      .toBe(true);
-  try {
-    await backend.start(); // Tracks a, a/b, a/b/c, and deep.txt.
-
-    // A rename event landing on the already-known directory a/b produces a
-    // local scope on its parent "a" (rebuilding a's DirectoryEntry from a
-    // fresh shallow scan) and, once classify()'s real stat() confirms a/b is
-    // still a directory, a recursive scope on a/b itself -- the same "known
-    // directory changes in place" shape the directory-churn benchmark
-    // exercises via atomic replace.
-    notifications.emit("change", "rename", join(root, "a", "b"));
-    await settled();
-
-    // Remove the ancestor while the native event names only a deleted file.
-    // The scoped scan must report its missing directory as well as that file.
-    await rm(join(root, "a"), { recursive: true, force: true });
-    notifications.emit("change", "rename", deepFile);
-    await settled();
-
-    expect(events.filter((event) => event.type === "delete").map((event) => event.path)).toContain(
-      deepFile,
+      },
+      paths,
+      (_root, listener) => {
+        notifications.on("change", listener);
+        return {
+          close: () => notifications.removeAllListeners(),
+          on: (event, onError) => notifications.on(event, onError),
+        };
+      },
     );
-    expect(events).toContainEqual({ type: "delete", path: deepDirectory });
-  } finally {
-    active = false;
-    await backend.close();
-    await observer.close();
-    await rm(root, { recursive: true, force: true });
-  }
-}, 15_000);
+    const settled = async () => {
+      // Classification uses real filesystem I/O and can request another audit.
+      // Drain it before advancing the debounce clock so no later classification
+      // leaves a fresh timer behind.
+      await expect
+        .poll(() => backend.getDiagnostics().pendingClassificationCount, { timeout: 10_000 })
+        .toBe(0);
+      // The file-only event uses the eight-second optional audit debounce.
+      await vi.advanceTimersByTimeAsync(8_000);
+      await expect
+        .poll(
+          () => {
+            const diagnostics = backend.getDiagnostics();
+            return (
+              diagnostics.pendingReconciliationWorkCount === 0 &&
+              !diagnostics.reconciliationInFlight
+            );
+          },
+          { timeout: 10_000 },
+        )
+        .toBe(true);
+    };
+    try {
+      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance"] });
+      await backend.start(); // Tracks a, a/b, a/b/c, and deep.txt.
+
+      // A rename event landing on the already-known directory a/b produces a
+      // local scope on its parent "a" (rebuilding a's DirectoryEntry from a
+      // fresh shallow scan) and, once classify()'s real stat() confirms a/b is
+      // still a directory, a recursive scope on a/b itself -- the same "known
+      // directory changes in place" shape the directory-churn benchmark
+      // exercises via atomic replace.
+      notifications.emit("change", "rename", join(root, "a", "b"));
+      await settled();
+
+      // An ancestor notification must walk the re-linked subtree. A file-only
+      // notification must also recover the missing directory from its scoped scan.
+      await rm(join(root, "a"), { recursive: true, force: true });
+      notifications.emit("change", "rename", join(root, ...deletedPath));
+      await settled();
+
+      expect(
+        events.filter((event) => event.type === "delete").map((event) => event.path),
+      ).toContain(deepFile);
+      expect(events).toContainEqual({ type: "delete", path: deepDirectory });
+    } finally {
+      vi.useRealTimers();
+      active = false;
+      await backend.close();
+      await observer.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+  15_000,
+);
 
 test("a full native inventory audit reports a removed directory", async () => {
   const root = await mkdtemp(join(tmpdir(), "native-full-audit-"));
diff --git a/packages/server/src/server/git-filename-diffs.e2e.test.ts b/packages/server/src/server/git-filename-diffs.e2e.test.ts
index c32ee040b8..4b8bcb1566 100644
--- a/packages/server/src/server/git-filename-diffs.e2e.test.ts
+++ b/packages/server/src/server/git-filename-diffs.e2e.test.ts
@@ -29,6 +29,8 @@ test("a rename-only commit returns zero added or deleted lines through the clien
     expect(await client.getCommitFileDiff(cwd, sha, "new.txt")).toEqual({
       file: {
         path: "new.txt",
+        oldPath: "old.txt",
+        status: "ok",
         isNew: false,
         isDeleted: false,
         additions: 0,
@@ -98,3 +100,144 @@ test.skipIf(process.platform === "win32")(
     }
   },
 );
+
+test("streamed Changes preserves BOM-prefixed paths and highlighted content", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "stream-bom-diff-"));
+  const daemon = await createTestPaseoDaemon({ agentClients: {} });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd });
+    writeFileSync(join(cwd, "\uFEFFbom.ts"), "\uFEFFexport const value = 1;\n");
+    writeFileSync(join(cwd, "other.txt"), "other edit\n");
+    await client.connect();
+    const states: import("@getpaseo/client").DiffState[] = [];
+    const observation = client.observeDiff({
+      cwd,
+      base: { kind: "empty" },
+      head: { kind: "worktree" },
+    });
+    const unsubscribe = observation.subscribe({
+      snapshot: (state) => states.push(state),
+      update: () => {},
+    });
+    try {
+      await expect.poll(() => states.at(-1)?.phase, { timeout: 15000 }).toBe("ready");
+      const readyState = states.at(-1);
+      if (readyState?.phase !== "ready") throw new Error("Expected ready diff");
+      expect(readyState.files.map((file) => file.path)).toContain("other.txt");
+      const bomFile = readyState.files.find((file) => file.path === "\uFEFFbom.ts");
+      const addedLine = bomFile?.hunks
+        .flatMap((hunk) => hunk.lines)
+        .find((line) => line.type === "add");
+      expect(addedLine?.content).toBe("\uFEFFexport const value = 1;");
+      expect(addedLine?.tokens?.map((token) => token.text).join("")).toBe(addedLine?.content);
+      expect(states.some((state) => state.phase === "error")).toBe(false);
+    } finally {
+      unsubscribe();
+      await observation.release();
+    }
+  } finally {
+    await client.close();
+    await daemon.close();
+    rmSync(cwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+});
+
+test("checkout refresh from a subdirectory updates a pinned streamed comparison", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "stream-subdirectory-refresh-"));
+  const { mkdirSync } = await import("node:fs");
+  const workspace = join(cwd, "workspace");
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const daemon = await createTestPaseoDaemon({ agentClients: {} });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    mkdirSync(workspace);
+    writeFileSync(join(cwd, "file.txt"), "committed content\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    const head = git("rev-parse", "HEAD");
+    await client.connect();
+    const states: import("@getpaseo/client").DiffState[] = [];
+    const observation = client.observeDiff({
+      cwd: workspace,
+      base: { kind: "empty" },
+      head: { kind: "rev", rev: head },
+    });
+    const unsubscribe = observation.subscribe({
+      snapshot: (state) => states.push(state),
+      update: () => {},
+    });
+    try {
+      await expect.poll(() => states.at(-1)?.phase, { timeout: 15000 }).toBe("ready");
+      const initial = states.at(-1);
+      if (initial?.phase !== "ready") throw new Error("Expected initial diff");
+      expect(initial.files[0]).toMatchObject({ path: "file.txt", status: "ok" });
+      expect(await client.checkoutRefresh(workspace)).toMatchObject({ success: true, error: null });
+      await expect
+        .poll(() => states.at(-1)?.revision, { timeout: 15000 })
+        .toBeGreaterThan(initial.revision);
+      expect(states.at(-1)).toMatchObject({
+        phase: "ready",
+        files: [{ path: "file.txt", status: "ok" }],
+      });
+      writeFileSync(join(cwd, ".git", "info", "attributes"), "file.txt -diff\n");
+      await expect
+        .poll(() => states.at(-1), { timeout: 15000 })
+        .toMatchObject({
+          phase: "ready",
+          files: [{ path: "file.txt", status: "binary", hunks: [] }],
+        });
+    } finally {
+      unsubscribe();
+      await observation.release();
+    }
+  } finally {
+    await client.close();
+    await daemon.close();
+    rmSync(cwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+});
+
+test("refreshing a non-Git workspace succeeds while a Git comparison is open", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "stream-refresh-git-"));
+  const plain = mkdtempSync(join(tmpdir(), "stream-refresh-plain-"));
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  const daemon = await createTestPaseoDaemon({ agentClients: {} });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    git("init", "-b", "main");
+    git("config", "user.name", "Test");
+    git("config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "file.txt"), "committed content\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await client.connect();
+    const states: import("@getpaseo/client").DiffState[] = [];
+    const observation = client.observeDiff({
+      cwd,
+      base: { kind: "empty" },
+      head: { kind: "rev", rev: git("rev-parse", "HEAD") },
+    });
+    const unsubscribe = observation.subscribe({
+      snapshot: (state) => states.push(state),
+      update: () => {},
+    });
+    try {
+      await expect.poll(() => states.at(-1)?.phase, { timeout: 15000 }).toBe("ready");
+      const revision = states.at(-1)?.revision;
+      expect(await client.checkoutRefresh(plain)).toMatchObject({ success: true, error: null });
+      expect(states.at(-1)).toMatchObject({ phase: "ready", revision });
+    } finally {
+      unsubscribe();
+      await observation.release();
+    }
+  } finally {
+    await client.close();
+    await daemon.close();
+    rmSync(cwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    rmSync(plain, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+});
diff --git a/packages/server/src/server/git-metadata-event-rules.test.ts b/packages/server/src/server/git-metadata-event-rules.test.ts
index 8c7e491970..43edc861d5 100644
--- a/packages/server/src/server/git-metadata-event-rules.test.ts
+++ b/packages/server/src/server/git-metadata-event-rules.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 import {
   classifyGitMetadataPath,
+  affectsGitDiffInterpretation,
   GIT_METADATA_EVENT_RULES,
   getPrunedGitMetadataPaths,
 } from "./git-metadata-event-rules.js";
@@ -21,6 +22,7 @@ describe("Git metadata event rules", () => {
     ["worktree", "HEAD", { kind: "owner", refreshBase: true }],
     ["worktree", "config.worktree", { kind: "owner", refreshBase: true }],
     ["worktree", "paseo/worktree.json", { kind: "owner", refreshBase: true }],
+    ["common", "paseo/worktree.json", { kind: "owner", refreshBase: true }],
     ["worktree", "COMMIT_EDITMSG", { kind: "ignore" }],
     ["worktree", "ORIG_HEAD", { kind: "ignore" }],
     ["common", "index", { kind: "owner", refreshBase: false }],
@@ -34,14 +36,28 @@ describe("Git metadata event rules", () => {
     ["common", "packed-refs", { kind: "all", refreshBase: true }],
     ["common", "reftable/tables.list", { kind: "all", refreshBase: true }],
     ["common", "config", { kind: "all", refreshBase: true }],
+    ["common", "info/attributes", { kind: "all", refreshBase: false }],
     ["common", "worktrees/new/index", { kind: "ignore" }],
     ["common", "hooks/pre-commit", { kind: "ignore" }],
     ["common", "logs/refs/heads/main", { kind: "ignore" }],
     ["common", "objects/ab/cdef", { kind: "ignore" }],
-    ["common", "refs/tags/v1", { kind: "ignore" }],
+    ["common", "refs/tags/v1", { kind: "all", refreshBase: true }],
     ["common", "FETCH_HEAD", { kind: "ignore" }],
     ["common", "packed-refs.lock", { kind: "ignore" }],
   ] as const)("classifies %s metadata path %s", (scope, path, expected) => {
     expect(classifyGitMetadataPath(scope, path)).toEqual(expected);
   });
 });
+
+test.each([
+  ["worktree", "config.worktree", true],
+  ["common", "config.worktree", false],
+  ["common", "config", true],
+  ["common", "info/attributes", true],
+  ["worktree", "info/attributes", false],
+  ["common", "refs/heads/main", false],
+  ["worktree", "index", false],
+  ["common", "config.lock", false],
+] as const)("diff interpretation dependency %s/%s is %s", (scope, path, expected) => {
+  expect(affectsGitDiffInterpretation(scope, path)).toBe(expected);
+});
diff --git a/packages/server/src/server/git-metadata-event-rules.ts b/packages/server/src/server/git-metadata-event-rules.ts
index dab6bc4887..2557639f16 100644
--- a/packages/server/src/server/git-metadata-event-rules.ts
+++ b/packages/server/src/server/git-metadata-event-rules.ts
@@ -5,6 +5,7 @@ type GitMetadataEventRule = {
   scope: GitMetadataScope | "both";
   path: string;
   prune?: true;
+  diffInput?: true;
 } & (
   | { match: "exact" | "prefix" | "suffix"; route: "ignore" }
   | { match: "exact" | "prefix" | "suffix"; route: "owner" | "all"; refreshBase: boolean }
@@ -36,6 +37,7 @@ export const GIT_METADATA_EVENT_RULES = [
   },
   {
     id: "worktree-config",
+    diffInput: true,
     scope: "worktree",
     match: "exact",
     path: "config.worktree",
@@ -44,7 +46,7 @@ export const GIT_METADATA_EVENT_RULES = [
   },
   {
     id: "paseo-worktree-metadata",
-    scope: "worktree",
+    scope: "both",
     match: "exact",
     path: "paseo/worktree.json",
     route: "owner",
@@ -73,6 +75,14 @@ export const GIT_METADATA_EVENT_RULES = [
     path: "refs/heads/",
     route: "local-ref",
   },
+  {
+    id: "tag",
+    scope: "common",
+    match: "prefix",
+    path: "refs/tags/",
+    route: "all",
+    refreshBase: true,
+  },
   {
     id: "remote-branch",
     scope: "common",
@@ -98,12 +108,22 @@ export const GIT_METADATA_EVENT_RULES = [
   },
   {
     id: "shared-config",
+    diffInput: true,
     scope: "common",
     match: "exact",
     path: "config",
     route: "all",
     refreshBase: true,
   },
+  {
+    id: "shared-attributes",
+    diffInput: true,
+    scope: "common",
+    match: "exact",
+    path: "info/attributes",
+    route: "all",
+    refreshBase: false,
+  },
   {
     id: "worktree-administration",
     scope: "common",
@@ -150,11 +170,7 @@ export function classifyGitMetadataPath(
   inputPath: string,
 ): GitMetadataEffect {
   const path = inputPath.replaceAll("\\", "/");
-  const rule = GIT_METADATA_EVENT_RULES.find(
-    (candidate) =>
-      (candidate.scope === "both" || candidate.scope === scope) &&
-      matchesGitMetadataPath(candidate.match, candidate.path, path),
-  );
+  const rule = findGitMetadataRule(scope, path);
   if (!rule || rule.route === "ignore") return { kind: "ignore" };
   if (rule.route === "owner" || rule.route === "all") {
     return { kind: rule.route, refreshBase: rule.refreshBase };
@@ -166,6 +182,19 @@ export function classifyGitMetadataPath(
   };
 }
 
+export function affectsGitDiffInterpretation(scope: GitMetadataScope, inputPath: string): boolean {
+  const rule = findGitMetadataRule(scope, inputPath.replaceAll("\\", "/"));
+  return rule !== undefined && "diffInput" in rule && rule.diffInput;
+}
+
+function findGitMetadataRule(scope: GitMetadataScope, path: string) {
+  return GIT_METADATA_EVENT_RULES.find(
+    (candidate) =>
+      (candidate.scope === "both" || candidate.scope === scope) &&
+      matchesGitMetadataPath(candidate.match, candidate.path, path),
+  );
+}
+
 function matchesGitMetadataPath(
   match: GitMetadataEventRule["match"],
   pattern: string,
diff --git a/packages/server/src/server/hub/daemon-executions.test.ts b/packages/server/src/server/hub/daemon-executions.test.ts
index d78b29d732..65c2a9617b 100644
--- a/packages/server/src/server/hub/daemon-executions.test.ts
+++ b/packages/server/src/server/hub/daemon-executions.test.ts
@@ -86,7 +86,10 @@ test("Hub MCP configuration reaches the provider alongside Paseo MCP without ent
     cwd: response.payload.agent.cwd,
   });
   expect(JSON.stringify(response.payload.agent)).not.toContain(bearer);
-  expect(JSON.stringify(response.payload.agent)).not.toContain("private-build");
+  // Provider options are not secret and appear in the snapshot's `options`.
+  expect(response.payload.agent.options).toMatchObject({
+    sandbox_workspace_write: { writable_roots: ["/var/cache/private-build"] },
+  });
   expect(JSON.stringify(response.payload.agent)).not.toContain("finish_execution");
 
   const update = hub.hubMessages().find((message) => message.type === "hub.execution.agent.update");
@@ -104,7 +107,6 @@ test("Hub MCP configuration reaches the provider alongside Paseo MCP without ent
     cwd: update.payload.agent.cwd,
   });
   expect(JSON.stringify(update.payload.agent)).not.toContain(bearer);
-  expect(JSON.stringify(update.payload.agent)).not.toContain("private-build");
   expect(JSON.stringify(update.payload.agent)).not.toContain("finish_execution");
 });
 
diff --git a/packages/server/src/server/hub/daemon-executions.ts b/packages/server/src/server/hub/daemon-executions.ts
index ec629c3fc9..029e2090c7 100644
--- a/packages/server/src/server/hub/daemon-executions.ts
+++ b/packages/server/src/server/hub/daemon-executions.ts
@@ -23,7 +23,6 @@ export interface HubExecutionAgentCreateInput {
   model?: string;
   modeId?: string;
   thinkingOptionId?: string;
-  featureValues?: Record<string, unknown>;
   providerOptions?: ProviderOptions;
   toolPolicy?: ToolPolicy;
   env?: Record<string, string>;
@@ -193,7 +192,6 @@ export class DaemonExecutions implements HubExecutionAgents {
         cwd: input.cwd,
         mode: input.modeId,
         thinking: input.thinkingOptionId,
-        features: input.featureValues,
         env: input.env,
         ...(input.mcpServers || input.providerOptions || input.toolPolicy
           ? {
@@ -290,7 +288,11 @@ export class DaemonExecutions implements HubExecutionAgents {
       agent: live
         ? serializeAgentSnapshot(live)
         : {
-            ...buildStoredAgentPayload(record, this.agentManager.getRegisteredProviderIds()),
+            ...buildStoredAgentPayload(
+              record,
+              this.agentManager.getRegisteredProviderIds(),
+              (provider, own) => this.agentManager.effectiveOptionsFor(provider, own),
+            ),
             status: "closed",
           },
     };
diff --git a/packages/server/src/server/hub/execution-controller.ts b/packages/server/src/server/hub/execution-controller.ts
index 4199433d3d..23343b4e61 100644
--- a/packages/server/src/server/hub/execution-controller.ts
+++ b/packages/server/src/server/hub/execution-controller.ts
@@ -13,6 +13,7 @@ import {
 } from "../agent/provider-options.js";
 
 import type { HubExecutionAgents, OwnedAgentEvent } from "./daemon-executions.js";
+import { foldFeatureValues } from "../agent/option-controls.js";
 
 interface HubExecutionControllerOptions {
   agents: HubExecutionAgents;
@@ -167,8 +168,8 @@ export class HubExecutionController {
         model: message.model,
         modeId: message.modeId,
         thinkingOptionId: message.thinkingOptionId,
-        featureValues: message.featureValues,
-        providerOptions: message.providerOptions,
+        // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+        providerOptions: foldFeatureValues(message).providerOptions,
         toolPolicy: message.toolPolicy,
         env: message.env,
         mcpServers: message.mcpServers,
diff --git a/packages/server/src/server/hub/test-utils/relationship-harness.ts b/packages/server/src/server/hub/test-utils/relationship-harness.ts
index 115745492c..37ad149174 100644
--- a/packages/server/src/server/hub/test-utils/relationship-harness.ts
+++ b/packages/server/src/server/hub/test-utils/relationship-harness.ts
@@ -440,7 +440,7 @@ type AcceptedCreate = Omit<
 
 const providerCatalog = {
   async resolveCreateConfig(input) {
-    return { modeId: input.requestedMode, featureValues: input.featureValues };
+    return { modeId: input.requestedMode, providerOptions: input.providerOptions };
   },
 } satisfies CreateAgentCommandDependencies["providerSnapshotManager"];
 
@@ -840,7 +840,7 @@ export class HubRelationshipHarness {
   }
 
   async durableOwnedAgentIds(): Promise<string[]> {
-    return (await this.daemon!.agentStorage.list())
+    return (await this.daemon!.agentStorage.listAll())
       .filter((record) => record.owner?.kind === "daemon")
       .map((record) => record.id);
   }
@@ -850,7 +850,7 @@ export class HubRelationshipHarness {
       path.join(this.paseoHome, "agents"),
       pino({ level: "silent" }),
     );
-    return (await storage.list())
+    return (await storage.listAll())
       .filter((record) => record.owner?.kind === "daemon")
       .map((record) => record.id);
   }
@@ -1272,7 +1272,7 @@ export class HubRelationshipHarness {
     });
     const executions = this.executionsForReconstruction(manager, storage);
     const replay = await executions.create(this.ownedCreateInput(executionId));
-    const durableAgentCount = (await storage.list()).filter(
+    const durableAgentCount = (await storage.listAll()).filter(
       (record) => record.owner?.kind === "daemon",
     ).length;
     return { replay, durableAgentCount };
@@ -1285,8 +1285,9 @@ export class HubRelationshipHarness {
       pino({ level: "silent" }),
     );
     return {
-      durableAgentCount: (await storage.list()).filter((record) => record.owner?.kind === "daemon")
-        .length,
+      durableAgentCount: (await storage.listAll()).filter(
+        (record) => record.owner?.kind === "daemon",
+      ).length,
     };
   }
 
diff --git a/packages/server/src/server/migrations/backfill-workspace-id.migration.ts b/packages/server/src/server/migrations/backfill-workspace-id.migration.ts
index 5451be2826..2ccd808cfd 100644
--- a/packages/server/src/server/migrations/backfill-workspace-id.migration.ts
+++ b/packages/server/src/server/migrations/backfill-workspace-id.migration.ts
@@ -68,8 +68,10 @@ export async function backfillWorkspaceIdForLegacyAgents(options: {
   workspaceRegistry: WorkspaceRegistry;
   logger: Logger;
 }): Promise<number> {
-  const workspaceRecords = await options.workspaceRegistry.list();
-  const records = await options.agentStorage.list();
+  // One-time migration resolves ownership against archived workspace history.
+  const workspaceRecords = await options.workspaceRegistry.listAll();
+  // One-time migration updates archived agents as well as active agents.
+  const records = await options.agentStorage.listAll();
   let migrated = 0;
 
   for (const record of records) {
diff --git a/packages/server/src/server/owned-subscriptions.e2e.test.ts b/packages/server/src/server/owned-subscriptions.e2e.test.ts
index fc73e44db4..c210118f1f 100644
--- a/packages/server/src/server/owned-subscriptions.e2e.test.ts
+++ b/packages/server/src/server/owned-subscriptions.e2e.test.ts
@@ -985,6 +985,45 @@ test("config changes require their own event demand and cannot escape to an idle
   }
 });
 
+test("a config change push carries profiles with the legacy featureValues the unchanged app reads", async () => {
+  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+  const admin = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.8.0" });
+  let observer: SubscriptionPeer | undefined;
+  try {
+    await admin.connect();
+    await admin.patchDaemonConfig({
+      agentProfiles: [
+        { id: "p", name: "P", provider: "codex", options: {}, featureValues: { plan_mode: true } },
+      ],
+    });
+    observer = await SubscriptionPeer.connect(daemon.port, "config-push-session");
+    await observer.request({
+      type: "session.events.set_subscription.request",
+      requestId: "config-feed",
+      events: ["status.daemon_config_changed"],
+    });
+
+    await admin.patchDaemonConfig({ autoArchiveAfterMerge: true });
+
+    const peer = observer;
+    await expect
+      .poll(() =>
+        peer.frames.flatMap((frame) =>
+          frame.type === "session" &&
+          frame.message.type === "status" &&
+          frame.message.payload.status === "daemon_config_changed"
+            ? [frame.message.payload.config?.agentProfiles?.[0]?.featureValues]
+            : [],
+        ),
+      )
+      .toEqual([{ plan_mode: true }]);
+  } finally {
+    observer?.close();
+    await admin.close();
+    await daemon.close();
+  }
+});
+
 test("status-shaped operation replies use actual source request provenance", async () => {
   const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
   const peers: SubscriptionPeer[] = [];
@@ -1873,3 +1912,115 @@ test("public project subscriptions request updates and release their producer de
     await daemon.close();
   }
 });
+
+test.each([
+  { closed: false, batch: false },
+  { closed: true, batch: false },
+  { closed: false, batch: true },
+  { closed: true, batch: true },
+])(
+  "clearing workspace attention reaches independent subscribers (closed=$closed, batch=$batch)",
+  async ({ closed, batch }) => {
+    const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+    const clients = Array.from(
+      { length: 4 },
+      () => new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }),
+    );
+    const [actor, observer, unreadObserver, quiet] = clients;
+    const updates: SessionOutboundMessage[] = [];
+    const unreadUpdates: SessionOutboundMessage[] = [];
+    const quietUpdates: SessionOutboundMessage[] = [];
+    const responses: SessionOutboundMessage[] = [];
+    try {
+      await Promise.all(clients.map((client) => client.connect()));
+      const agentIds: string[] = [];
+      for (let index = 0; index < (batch ? 2 : 1); index += 1) {
+        const cwd = path.join(daemon.staticDir, `workspace-${index}`);
+        await mkdir(cwd);
+        const agent = await actor.createAgent({ provider: "codex", cwd });
+        await actor.sendMessage(agent.id, "Reply with OK.");
+        await actor.waitForFinish(agent.id, 5000);
+        await daemon.daemon.agentManager.clearAgentAttention(agent.id);
+        if (closed) await daemon.daemon.agentManager.closeAgent(agent.id);
+        agentIds.push(agent.id);
+      }
+      const snapshot = await observer.fetchAgents({
+        filter: { includeArchived: true },
+        subscribe: {},
+      });
+      const workspaceIds = agentIds.map(
+        (id) => snapshot.entries.find((entry) => entry.agent.id === id)!.agent.workspaceId!,
+      );
+      expect(new Set(workspaceIds).size).toBe(agentIds.length);
+      await unreadObserver.fetchAgents({ filter: { requiresAttention: true }, subscribe: {} });
+      actor.subscribeRawMessages((message) => responses.push(message));
+      observer.subscribeRawMessages((message) => updates.push(message));
+      unreadObserver.subscribeRawMessages((message) => unreadUpdates.push(message));
+      quiet.subscribeRawMessages((message) => quietUpdates.push(message));
+      const attention = (id: string) =>
+        updates
+          .flatMap((message) =>
+            message.type === "agent_update" &&
+            message.payload.kind === "upsert" &&
+            message.payload.agent.id === id
+              ? [message.payload.agent.requiresAttention]
+              : [],
+          )
+          .at(-1);
+      for (const [index, id] of agentIds.entries()) {
+        await actor.markWorkspaceUnread(workspaceIds[index]);
+        await expect.poll(() => attention(id)).toBe(true);
+        await expect
+          .poll(() =>
+            unreadUpdates.some(
+              (message) =>
+                message.type === "agent_update" &&
+                message.payload.kind === "upsert" &&
+                message.payload.agent.id === id,
+            ),
+          )
+          .toBe(true);
+      }
+      updates.length = unreadUpdates.length = quietUpdates.length = 0;
+      await actor.clearWorkspaceAttention(batch ? workspaceIds : workspaceIds[0]);
+      const response = responses.findLast(
+        (message) => message.type === "workspace.clear_attention.response",
+      );
+      expect(response?.payload).toEqual({
+        requestId: expect.any(String),
+        workspaceId: batch ? workspaceIds : workspaceIds[0],
+        clearedAgentIds: agentIds,
+        results: workspaceIds.map((workspaceId, index) => ({
+          workspaceId,
+          clearedAgentIds: [agentIds[index]],
+          success: true,
+          error: null,
+        })),
+        success: true,
+        error: null,
+      });
+      const fresh = await actor.fetchAgents();
+      for (const id of agentIds) {
+        expect(fresh.entries.find((entry) => entry.agent.id === id)?.agent.requiresAttention).toBe(
+          false,
+        );
+        expect(Boolean(daemon.daemon.agentManager.getAgent(id))).toBe(!closed);
+        await expect.poll(() => attention(id)).toBe(false);
+        await expect
+          .poll(() =>
+            unreadUpdates.some(
+              (message) =>
+                message.type === "agent_update" &&
+                message.payload.kind === "remove" &&
+                message.payload.agentId === id,
+            ),
+          )
+          .toBe(true);
+      }
+      expect(quietUpdates.filter((message) => message.type === "agent_update")).toEqual([]);
+    } finally {
+      await Promise.all(clients.map((client) => client.close()));
+      await daemon.close();
+    }
+  },
+);
diff --git a/packages/server/src/server/paseo-worktree-service.test.ts b/packages/server/src/server/paseo-worktree-service.test.ts
index 1579f92d5f..2243d936e9 100644
--- a/packages/server/src/server/paseo-worktree-service.test.ts
+++ b/packages/server/src/server/paseo-worktree-service.test.ts
@@ -675,6 +675,40 @@ test("renames the branch even when the app supplies a random placeholder slug",
   expect(branchAfter).toBe("renamed-from-prompt");
 });
 
+test("keeps a branch the caller named instead of renaming it from the first agent context", async () => {
+  const { repoDir, tempDir } = createGitRepo();
+  cleanupPaths.push(tempDir);
+
+  const created = await createPaseoWorktree(
+    {
+      cwd: repoDir,
+      worktreeSlug: "dazzling-yak",
+      branchName: "pas-101-slow-sidebar",
+      firstAgentContext: { prompt: "Investigate the failing login flow" },
+
+      paseoHome: path.join(tempDir, ".paseo"),
+    },
+    createDeps(),
+  );
+
+  expect(created.worktree.branchName).toBe("pas-101-slow-sidebar");
+  await expect(
+    attemptFirstAgentBranchAutoName({
+      cwd: created.worktree.worktreePath,
+      firstAgentContext: { prompt: "Investigate the failing login flow" },
+      generateBranchNameFromContext: async () => "must-not-rename",
+    }),
+  ).resolves.toEqual({ attempted: false, renamed: false, branchName: null });
+  expect(
+    execFileSync("git", ["branch", "--show-current"], {
+      cwd: created.worktree.worktreePath,
+      stdio: "pipe",
+    })
+      .toString()
+      .trim(),
+  ).toBe("pas-101-slow-sidebar");
+});
+
 test("renames the branch from a github_pr attachment when no prompt is supplied", async () => {
   const { repoDir, tempDir } = createGitRepo();
   cleanupPaths.push(tempDir);
@@ -1092,7 +1126,8 @@ function createDeps(options?: {
   const workspaceRegistry: WorkspaceRegistry = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => Array.from(workspaces.values()),
+    listAll: async () => Array.from(workspaces.values()),
+    listActive: async () => Array.from(workspaces.values()).filter((record) => !record.archivedAt),
     get: async (workspaceId) => workspaces.get(workspaceId) ?? null,
     update: async (workspaceId, updater) => {
       const workspace = workspaces.get(workspaceId);
diff --git a/packages/server/src/server/paseo-worktree-service.ts b/packages/server/src/server/paseo-worktree-service.ts
index 1205554d4a..ff02d3fa8c 100644
--- a/packages/server/src/server/paseo-worktree-service.ts
+++ b/packages/server/src/server/paseo-worktree-service.ts
@@ -1,3 +1,4 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { PluginLifecycle } from "./plugins/lifecycle/index.js";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
@@ -34,6 +35,7 @@ export interface CreatePaseoWorktreeInput extends CreateWorktreeCoreInput {
   workspaceId?: string;
   projectId?: string;
   title?: string;
+  metadata?: Record<string, JsonValue>;
   background?: boolean;
   callerWorkspaceId?: string;
 }
@@ -88,7 +90,7 @@ async function createPaseoWorktreeWithPriority(
         },
       });
     }
-    await maybeMarkFirstAgentBranchAutoNameEligible({ createdWorktree });
+    await maybeMarkFirstAgentBranchAutoNameEligible({ createdWorktree, input });
     const workspaceCwd = mapWorkspaceRelativeCwdToWorktree({
       relativeWorkspaceCwd: workspaceCwdPlan.relativeWorkspaceCwd,
       targetWorktreePath: createdWorktree.worktree.worktreePath,
@@ -113,6 +115,7 @@ async function createPaseoWorktreeWithPriority(
       branch: createdWorktree.worktree.branchName || null,
       baseBranch: createdWorktree.worktree.comparisonBaseRef,
       title: input.title?.trim() || resolveFirstAgentPromptTitle(input.firstAgentContext),
+      metadata: input.metadata,
       expectsInitialAgent: Boolean(input.firstAgentContext),
       background: input.background,
       callerWorkspaceId: input.callerWorkspaceId,
@@ -277,11 +280,16 @@ async function findAvailableBranchName(options: {
 
 async function maybeMarkFirstAgentBranchAutoNameEligible(options: {
   createdWorktree: Awaited<ReturnType<typeof createWorktreeCore>>;
+  input: Pick<CreatePaseoWorktreeInput, "branchName">;
 }): Promise<void> {
-  const { createdWorktree } = options;
+  const { createdWorktree, input } = options;
   if (!createdWorktree.created || createdWorktree.intent.kind !== "branch-off") {
     return;
   }
+  // A branch the caller named is their choice; only a placeholder slug is replaced.
+  if (input.branchName !== undefined) {
+    return;
+  }
 
   await writePaseoWorktreeFirstAgentBranchAutoNameMetadata(createdWorktree.worktree.worktreePath, {
     placeholderBranchName: createdWorktree.worktree.branchName,
diff --git a/packages/server/src/server/persistence-hooks.ts b/packages/server/src/server/persistence-hooks.ts
index e95743d6be..9d60d9e249 100644
--- a/packages/server/src/server/persistence-hooks.ts
+++ b/packages/server/src/server/persistence-hooks.ts
@@ -18,7 +18,7 @@ function getLogger(logger: LoggerLike): LoggerLike {
   return logger.child({ module: "persistence" });
 }
 
-type AgentStoragePersistence = Pick<AgentStorage, "applySnapshot" | "list">;
+type AgentStoragePersistence = Pick<AgentStorage, "applySnapshot">;
 type AgentManagerStateSource = Pick<AgentManager, "subscribe">;
 
 interface BuildSessionConfigOptions {
@@ -73,7 +73,6 @@ export function buildConfigOverrides(record: StoredAgentRecord): Partial<AgentSe
     modeId: record.lastModeId ?? record.config?.modeId ?? undefined,
     model: record.config?.model ?? undefined,
     thinkingOptionId: record.config?.thinkingOptionId ?? undefined,
-    featureValues: record.config?.featureValues ?? undefined,
     providerOptions: record.config?.providerOptions ?? undefined,
     toolPolicy: record.config?.toolPolicy ?? undefined,
     systemPrompt: record.config?.systemPrompt ?? undefined,
@@ -95,7 +94,6 @@ export function buildSessionConfig(
     modeId: overrides.modeId,
     model: overrides.model,
     thinkingOptionId: overrides.thinkingOptionId,
-    featureValues: overrides.featureValues,
     providerOptions: overrides.providerOptions,
     toolPolicy: overrides.toolPolicy,
     systemPrompt: overrides.systemPrompt,
@@ -139,16 +137,20 @@ export function extractTimestamps(record: StoredAgentRecord): {
   updatedAt: Date;
   lastUserMessageAt: Date | null;
   labels?: Record<string, string>;
+  metadata?: StoredAgentRecord["metadata"];
   workspaceId?: string;
   owner?: StoredAgentRecord["owner"];
+  background?: boolean;
 } {
   return {
     createdAt: new Date(record.createdAt),
     updatedAt: new Date(resolveStoredAgentUpdatedAt(record)),
     lastUserMessageAt: record.lastUserMessageAt ? new Date(record.lastUserMessageAt) : null,
     labels: record.labels,
+    metadata: record.metadata,
     workspaceId: record.workspaceId,
     owner: record.owner,
+    background: record.background,
   };
 }
 
diff --git a/packages/server/src/server/plugins/builtin/index.ts b/packages/server/src/server/plugins/builtin/index.ts
index 463ee8407d..d51f6ee4d8 100644
--- a/packages/server/src/server/plugins/builtin/index.ts
+++ b/packages/server/src/server/plugins/builtin/index.ts
@@ -8,6 +8,7 @@ export const builtinPlugins = [
   "codex-usage-source",
   "copilot-usage-source",
   "cursor-usage-source",
+  "fx-provider",
   "grok-usage-source",
   "hoplite-provider",
   "kimi-usage-source",
diff --git a/packages/server/src/server/plugins/index.posix.test.ts b/packages/server/src/server/plugins/index.posix.test.ts
index c529bd37d3..2c3c36c1bd 100644
--- a/packages/server/src/server/plugins/index.posix.test.ts
+++ b/packages/server/src/server/plugins/index.posix.test.ts
@@ -15,11 +15,12 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import pino from "pino";
-import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { DaemonConfigStore } from "../daemon-config-store.js";
 import { PluginService } from "./index.js";
 import { BuiltinPluginLoader } from "./builtin/index.js";
 import { ManagedPluginSources } from "./managed-source.js";
+import type { PluginProviderMetadata } from "./plugin-process-protocol.js";
 import {
   startNpmRegistry,
   npmPluginPackages,
@@ -33,7 +34,13 @@ const emptyUsageRuntime = {
   getUsageSourceRegistrations: () => [],
   fetchUsage: async () => undefined,
   discoverUsage: async () => [],
-} satisfies Pick<TestPluginRuntime, "getUsageSourceRegistrations" | "fetchUsage" | "discoverUsage">;
+  startSubscription: () => {
+    throw new Error("No subscriptions in this test");
+  },
+} satisfies Pick<
+  TestPluginRuntime,
+  "getUsageSourceRegistrations" | "fetchUsage" | "discoverUsage" | "startSubscription"
+>;
 
 async function createPlugin(id: string, source: string): Promise<string> {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-service-"));
@@ -179,6 +186,55 @@ function createPluginSelectivePausedRuntime(pausedPluginId: string) {
   return { runtime, started, releaseStart, starts };
 }
 
+function createGatedRuntime(providers: Record<string, readonly PluginProviderMetadata[]> = {}) {
+  const gates = new Map<string, PromiseWithResolvers<void>>();
+  const gate = (pluginId: string) => {
+    const existing = gates.get(pluginId);
+    if (existing) return existing;
+    const created = Promise.withResolvers<void>();
+    gates.set(pluginId, created);
+    return created;
+  };
+  const begun: string[] = [];
+  const running = new Set<string>();
+  const runtime: TestPluginRuntime = {
+    ...emptyUsageRuntime,
+    catalog: () => [...running].map((id) => ({ id, clientBundle: "bundle" })),
+    invoke: async () => undefined,
+    getLogs: () => [],
+    clearLogs: () => undefined,
+    getProviderRegistrations: (pluginId) =>
+      running.has(pluginId) ? (providers[pluginId] ?? []) : [],
+    startPlugin: async (pluginId) => {
+      begun.push(pluginId);
+      await gate(pluginId).promise;
+      running.add(pluginId);
+    },
+    stopPluginById: async (pluginId) => running.delete(pluginId),
+    stopAll: async () => {
+      running.clear();
+    },
+    subscribe: () => () => undefined,
+    bindPaseoSessionHost: () => undefined,
+  };
+  return {
+    runtime,
+    begun,
+    finish: (pluginId: string) => gate(pluginId).resolve(),
+    fail: (pluginId: string, error: Error) => gate(pluginId).reject(error),
+  };
+}
+
+function nextNotification(service: PluginService, pluginId: string): Promise<void> {
+  return new Promise((resolve) => {
+    const unsubscribe = service.subscribe((notified) => {
+      if (notified !== pluginId) return;
+      unsubscribe();
+      resolve();
+    });
+  });
+}
+
 describe("PluginService", () => {
   it.each([
     { shadow: false, runtime: "subprocess" },
@@ -372,15 +428,127 @@ describe("PluginService", () => {
       "startup-first": { source: "directory", path: first },
       "startup-second": { source: "directory", path: second },
     });
-    const snapshots: string[][] = [];
-    service.subscribe(() => snapshots.push(catalogIds(service)));
+    const notifications: { pluginId: string; running: boolean }[] = [];
+    service.subscribe((pluginId) =>
+      notifications.push({ pluginId, running: catalogIds(service).includes(pluginId) }),
+    );
 
     await service.start();
 
-    expect(snapshots).toEqual([["startup-first"], ["startup-first", "startup-second"]]);
+    expect(notifications).toEqual([
+      { pluginId: "startup-first", running: true },
+      { pluginId: "startup-second", running: true },
+    ]);
+    expect(catalogIds(service)).toEqual(["startup-first", "startup-second"]);
     await service.stopAllPlugins();
   }, 20_000);
 
+  it("starts configured plugins concurrently and publishes them in config order", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    roots.push(home);
+    const gated = createGatedRuntime();
+    const service = createService(
+      home,
+      {
+        alpha: { source: "directory", path: "/plugins/alpha" },
+        beta: { source: "directory", path: "/plugins/beta" },
+        gamma: { source: "directory", path: "/plugins/gamma" },
+      },
+      { runtime: gated.runtime },
+    );
+    const notified: string[] = [];
+    service.subscribe((pluginId) => notified.push(pluginId));
+    let started = false;
+    const starting = (async () => {
+      await service.start();
+      started = true;
+    })();
+
+    await expect.poll(() => gated.begun).toEqual(["alpha", "beta", "gamma"]);
+
+    gated.finish("gamma");
+    const alphaPublished = nextNotification(service, "alpha");
+    gated.finish("alpha");
+    await alphaPublished;
+    expect(notified).toEqual(["alpha"]);
+    expect(started).toBe(false);
+
+    gated.finish("beta");
+    await starting;
+    expect(notified).toEqual(["alpha", "beta", "gamma"]);
+    expect(catalogIds(service)).toEqual(["alpha", "beta", "gamma"]);
+    await service.stopAllPlugins();
+  });
+
+  it("starts the other configured plugins when one fails while they are still starting", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    roots.push(home);
+    const gated = createGatedRuntime();
+    const service = createService(
+      home,
+      {
+        broken: { source: "directory", path: "/plugins/broken" },
+        healthy: { source: "directory", path: "/plugins/healthy" },
+      },
+      { runtime: gated.runtime },
+    );
+    const notified: string[] = [];
+    service.subscribe((pluginId) => notified.push(pluginId));
+    const starting = service.start();
+
+    await expect.poll(() => gated.begun).toEqual(["broken", "healthy"]);
+    const brokenPublished = nextNotification(service, "broken");
+    gated.fail("broken", new Error("startup exploded"));
+    await brokenPublished;
+    gated.finish("healthy");
+    await starting;
+
+    expect(notified).toEqual(["broken", "healthy"]);
+    expect(catalogIds(service)).toEqual(["healthy"]);
+    expect(await service.listPlugins()).toMatchObject([
+      { id: "broken", status: "failed", error: "startup exploded" },
+      { id: "healthy", status: "running" },
+    ]);
+    await service.stopAllPlugins();
+  });
+
+  it("keeps a provider ID with the plugin listed first when both start at once", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    roots.push(home);
+    const gated = createGatedRuntime({
+      first: [{ id: "shared-agent", label: "First agent" }],
+      second: [{ id: "shared-agent", label: "Second agent" }],
+    });
+    const service = createService(
+      home,
+      {
+        first: { source: "directory", path: "/plugins/first" },
+        second: { source: "directory", path: "/plugins/second" },
+      },
+      { runtime: gated.runtime },
+    );
+    const starting = service.start();
+
+    await expect.poll(() => gated.begun).toEqual(["first", "second"]);
+    gated.finish("second");
+    gated.finish("first");
+    await starting;
+
+    expect(service.getProviderRegistrations()).toMatchObject([
+      { id: "shared-agent", label: "First agent" },
+    ]);
+    expect(catalogIds(service)).toEqual(["first"]);
+    expect(await service.listPlugins()).toMatchObject([
+      { id: "first", status: "running" },
+      {
+        id: "second",
+        status: "failed",
+        error: 'Plugin second cannot register provider ID "shared-agent" twice',
+      },
+    ]);
+    await service.stopAllPlugins();
+  });
+
   it("uses an explicit config key, exposes reload failure, and retries from disk", async () => {
     const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
     roots.push(home);
@@ -470,91 +638,6 @@ describe("PluginService", () => {
     await service.stopAllPlugins();
   });
 
-  it("resolves a bare registry id even when a matching directory exists in the daemon cwd", async () => {
-    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
-    const owner = path.join(process.cwd(), `registry-shadow-${randomUUID()}`);
-    await mkdir(owner);
-    roots.push(home, owner);
-    const source = `${path.basename(owner)}/example`;
-    const repository = await createPlugin("registry-example", "export default () => () => {};\n");
-    await mkdir(path.join(owner, "example"));
-    await cp(repository, path.join(owner, "example"), { recursive: true });
-    await runGitCommand(["init", "-b", "main"], { cwd: repository });
-    await runGitCommand(["add", "-A"], { cwd: repository });
-    await runGitCommand(
-      [
-        "-c",
-        "user.name=Paseo Tests",
-        "-c",
-        "user.email=paseo@example.test",
-        "commit",
-        "-m",
-        "fixture",
-      ],
-      { cwd: repository },
-    );
-    const { stdout } = await runGitCommand(["rev-parse", "HEAD"], { cwd: repository });
-    const requests: Array<string | undefined> = [];
-    const server = createServer((request, response) => {
-      requests.push(request.url);
-      response.setHeader("Content-Type", "application/json");
-      response.end(
-        JSON.stringify({
-          id: source,
-          name: "Example",
-          description: "Test",
-          categories: [],
-          author: { github: path.basename(owner) },
-          repository: { url: "https://github.com/fixture/example" },
-          artifact: {
-            kind: "git",
-            remote: pathToFileURL(repository).href,
-            commit: stdout.trim(),
-            pluginPath: ".",
-          },
-          media: [],
-          submittedAt: "2026-10-03",
-          reviewedAt: "2026-10-03",
-          updatedAt: "2026-10-03",
-          publishedAt: "2026-10-03",
-          readme: "# Test",
-        }),
-      );
-    });
-    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
-    const address = server.address();
-    if (!address || typeof address === "string") throw new Error("Missing registry address");
-    const url = `http://127.0.0.1:${address.port}`;
-    const store = createStore(home);
-    await store.patch({ pluginsEnabled: false });
-    const service = bindTestSessionHost(
-      new PluginService(pino({ level: "silent" }), store, "0.4.0", {
-        managedSources: new ManagedPluginSources(home, { defaultUrl: url }),
-      }),
-    );
-    try {
-      await service.start();
-      await expect(service.installSource({ source })).resolves.toMatchObject({
-        id: "registry-example",
-        status: "disabled",
-        installation: {
-          identity: { kind: "git", registry: { url, id: source } },
-          currentRevision: stdout.trim(),
-        },
-      });
-      expect(requests).toEqual([`/plugins/${source}.json`]);
-      await expect(
-        service.installSource({ source: `./${source}`, id: "local-example" }),
-      ).resolves.toMatchObject({
-        installation: { identity: { kind: "directory", path: path.join(owner, "example") } },
-      });
-      expect(requests).toEqual([`/plugins/${source}.json`]);
-    } finally {
-      await service.stopAllPlugins();
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    }
-  }, 30_000);
-
   it("names a missing explicit directory instead of trying a managed source", async () => {
     const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
     roots.push(home);
@@ -589,15 +672,26 @@ describe("PluginService", () => {
     await service.stopAllPlugins();
   }, 20_000);
 
-  it.each([true, false])(
-    "updates the shipped legacy Git layout with enabled=%s",
-    async (enabled) => {
-      const home = await mkdtemp(path.join(tmpdir(), "paseo-legacy-layout-"));
+  describe("legacy Git migration", () => {
+    const id = "legacy-review";
+    const pluginPath = "plugins/review";
+    let home: string;
+    let repository: string;
+    let initial: string;
+    let remote: string;
+    let legacyRoot: string;
+    let directory: string;
+    let settingsDirectory: string;
+    let settingsFile: string;
+    let savedSettings: string;
+
+    // Build the legacy installation before the migration workflow deadline starts.
+    // These seven real Git launches have their own fixture setup budget.
+    beforeEach(async () => {
+      home = await mkdtemp(path.join(tmpdir(), "paseo-legacy-layout-"));
       roots.push(home);
-      const repository = await mkdtemp(path.join(tmpdir(), "paseo-legacy-remote-"));
+      repository = await mkdtemp(path.join(tmpdir(), "paseo-legacy-remote-"));
       roots.push(repository);
-      const id = "legacy-review";
-      const pluginPath = "plugins/review";
       await mkdir(path.join(repository, pluginPath), { recursive: true });
       await writeFile(
         path.join(repository, pluginPath, "paseo-plugin.json"),
@@ -620,13 +714,11 @@ export default function contribute(server: PluginServerContext) {
         ["tag", "v1"],
       ])
         await runGitCommand(args, { cwd: repository });
-      const initial = (
-        await runGitCommand(["rev-parse", "HEAD"], { cwd: repository })
-      ).stdout.trim();
-      const remote = pathToFileURL(repository).href;
-      const legacyRoot = path.join(home, "plugins", id, `${initial.slice(0, 12)}-${randomUUID()}`);
+      initial = (await runGitCommand(["rev-parse", "HEAD"], { cwd: repository })).stdout.trim();
+      remote = pathToFileURL(repository).href;
+      legacyRoot = path.join(home, "plugins", id, `${initial.slice(0, 12)}-${randomUUID()}`);
       const checkoutRoot = path.join(legacyRoot, "checkout");
-      const directory = path.join(checkoutRoot, pluginPath);
+      directory = path.join(checkoutRoot, pluginPath);
       await mkdir(legacyRoot, { recursive: true });
       await runGitCommand(["clone", remote, checkoutRoot], { cwd: home });
       await runGitCommand(["checkout", "--detach", "v1"], { cwd: checkoutRoot });
@@ -643,159 +735,188 @@ export default function contribute(server: PluginServerContext) {
           },
         }),
       );
-      const settingsDirectory = path.join(home, "plugin-settings");
+      settingsDirectory = path.join(home, "plugin-settings");
       await mkdir(path.join(settingsDirectory, id), { recursive: true });
-      const settingsFile = path.join(settingsDirectory, id, "preferences.json");
-      const savedSettings = JSON.stringify({ version: 1, values: { message: "keep my settings" } });
+      settingsFile = path.join(settingsDirectory, id, "preferences.json");
+      savedSettings = JSON.stringify({ version: 1, values: { message: "keep my settings" } });
       await writeFile(settingsFile, savedSettings);
-      const store = createStore(home, { [id]: { source: "directory", path: directory, enabled } });
-      const open = () =>
-        bindTestSessionHost(
-          new PluginService(pino({ level: "silent" }), store, "0.8.0", {
-            managedSources: new ManagedPluginSources(home),
-            settingsDirectory,
-          }),
-        );
-      let service = open();
-      try {
-        await service.start();
-        const expected = {
-          identity: { kind: "git", remote, pluginPath },
-          currentRevision: initial,
-        };
-        await rename(repository, `${repository}-offline`);
-        try {
-          expect(await new ManagedPluginSources(home).describe(id, directory)).toEqual(expected);
-          expect(await service.listPlugins()).toMatchObject([
-            { id, enabled, status: enabled ? "running" : "disabled", installation: expected },
-          ]);
-        } finally {
-          await rename(`${repository}-offline`, repository);
-        }
-        await service.stopAllPlugins();
-        service = open();
-        await service.start();
-        await runGitCommand(["checkout", "-b", "new-default"], { cwd: repository });
-        await writeFile(path.join(repository, pluginPath, "revision.txt"), "new default");
-        for (const args of [
-          ["add", "."],
-          ["-c", "user.name=Test", "-c", "user.email=test@example.test", "commit", "-m", "update"],
-        ])
-          await runGitCommand(args, { cwd: repository });
-        const latest = (
-          await runGitCommand(["rev-parse", "HEAD"], { cwd: repository })
-        ).stdout.trim();
-        const [preview] = await service.previewUpdates({ pluginId: id });
-        expect(preview).toMatchObject({
-          outcome: "update",
-          current: expected,
-          target: { kind: "git", commit: latest },
+    });
+
+    it.each([true, false])(
+      "updates the shipped legacy Git layout with enabled=%s",
+      async (enabled) => {
+        const store = createStore(home, {
+          [id]: { source: "directory", path: directory, enabled },
         });
-        const [updated] = await service.applyUpdates([preview!.proposal!]);
-        expect(updated).toMatchObject({
-          outcome: "updated",
-          plugin: {
-            id,
-            enabled,
-            status: enabled ? "running" : "disabled",
-            installation: { identity: expected.identity, currentRevision: latest },
-          },
-        });
-        await expect(stat(legacyRoot)).rejects.toMatchObject({ code: "ENOENT" });
-        expect(await readFile(settingsFile, "utf8")).toBe(savedSettings);
-        await service.disablePlugin(id);
-        await service.enablePlugin(id);
-        expect(await service.reloadPlugin(id)).toMatchObject({ status: "running" });
-        expect(await service.invokePluginRpc(id, "settings.preferences.read", {})).toMatchObject({
-          status: "ready",
-          values: { message: "keep my settings" },
-        });
-        await service.removePlugin(id);
-        await expect(stat(path.join(home, "plugins", id))).rejects.toMatchObject({
-          code: "ENOENT",
-        });
-        expect(await stat(repository)).toBeDefined();
-        const sources = new ManagedPluginSources(home);
-        // A record cannot confer ownership on another plugin's tree or a malformed version name.
-        sources.commit(id, { kind: "git", remote });
-        for (const outside of [
-          path.join(home, "plugins", "other", path.basename(legacyRoot), "checkout"),
-          path.join(home, "plugins", id, "f".repeat(36), "checkout"),
-          path.join(home, "plugins", id, `${initial.slice(0, 12)}-invalid`, "checkout"),
-        ])
-          await expect(sources.describe(id, outside)).rejects.toThrow(
-            "outside its managed installation",
+        const open = () =>
+          bindTestSessionHost(
+            new PluginService(pino({ level: "silent" }), store, "0.8.0", {
+              managedSources: new ManagedPluginSources(home),
+              settingsDirectory,
+            }),
           );
-      } finally {
-        await service.stopAllPlugins();
-      }
-    },
-    60_000,
-  );
+        let service = open();
+        try {
+          await service.start();
+          const expected = {
+            identity: { kind: "git", remote, pluginPath },
+            currentRevision: initial,
+          };
+          await rename(repository, `${repository}-offline`);
+          try {
+            expect(await new ManagedPluginSources(home).describe(id, directory)).toEqual(expected);
+            expect(await service.listPlugins()).toMatchObject([
+              { id, enabled, status: enabled ? "running" : "disabled", installation: expected },
+            ]);
+          } finally {
+            await rename(`${repository}-offline`, repository);
+          }
+          await service.stopAllPlugins();
+          service = open();
+          await service.start();
+          await runGitCommand(["checkout", "-b", "new-default"], { cwd: repository });
+          await writeFile(path.join(repository, pluginPath, "revision.txt"), "new default");
+          for (const args of [
+            ["add", "."],
+            [
+              "-c",
+              "user.name=Test",
+              "-c",
+              "user.email=test@example.test",
+              "commit",
+              "-m",
+              "update",
+            ],
+          ])
+            await runGitCommand(args, { cwd: repository });
+          const latest = (
+            await runGitCommand(["rev-parse", "HEAD"], { cwd: repository })
+          ).stdout.trim();
+          const [preview] = await service.previewUpdates({ pluginId: id });
+          expect(preview).toMatchObject({
+            outcome: "update",
+            current: expected,
+            target: { kind: "git", commit: latest },
+          });
+          const [updated] = await service.applyUpdates([preview!.proposal!]);
+          expect(updated).toMatchObject({
+            outcome: "updated",
+            plugin: {
+              id,
+              enabled,
+              status: enabled ? "running" : "disabled",
+              installation: { identity: expected.identity, currentRevision: latest },
+            },
+          });
+          await expect(stat(legacyRoot)).rejects.toMatchObject({ code: "ENOENT" });
+          expect(await readFile(settingsFile, "utf8")).toBe(savedSettings);
+          await service.disablePlugin(id);
+          await service.enablePlugin(id);
+          expect(await service.reloadPlugin(id)).toMatchObject({ status: "running" });
+          expect(await service.invokePluginRpc(id, "settings.preferences.read", {})).toMatchObject({
+            status: "ready",
+            values: { message: "keep my settings" },
+          });
+          await service.removePlugin(id);
+          await expect(stat(path.join(home, "plugins", id))).rejects.toMatchObject({
+            code: "ENOENT",
+          });
+          expect(await stat(repository)).toBeDefined();
+          const sources = new ManagedPluginSources(home);
+          // A record cannot confer ownership on another plugin's tree or a malformed version name.
+          sources.commit(id, { kind: "git", remote });
+          for (const outside of [
+            path.join(home, "plugins", "other", path.basename(legacyRoot), "checkout"),
+            path.join(home, "plugins", id, "f".repeat(36), "checkout"),
+            path.join(home, "plugins", id, `${initial.slice(0, 12)}-invalid`, "checkout"),
+          ])
+            await expect(sources.describe(id, outside)).rejects.toThrow(
+              "outside its managed installation",
+            );
+        } finally {
+          await service.stopAllPlugins();
+        }
+      },
+      60_000,
+    );
+  });
 
-  it("keeps the running commit when a Git update build command fails", async () => {
-    const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
-    roots.push(home);
-    const repository = await mkdtemp(path.join(tmpdir(), "paseo-plugin-repository-"));
-    roots.push(repository);
-    await runGitCommand(["init", "-b", "main"], { cwd: repository });
-    await runGitCommand(["config", "user.name", "Paseo Tests"], { cwd: repository });
-    await runGitCommand(["config", "user.email", "paseo@example.test"], { cwd: repository });
-    await writeFile(
-      path.join(repository, "paseo-plugin.json"),
-      JSON.stringify({ id: "git-update" }),
-    );
-    await writeFile(
-      path.join(repository, "index.server.ts"),
-      "export default function contribute(plugin: unknown) { void plugin; return () => undefined; }",
-    );
-    await runGitCommand(["add", "-A"], { cwd: repository });
-    await runGitCommand(["commit", "-m", "initial"], { cwd: repository });
+  describe("a Git update whose build command fails", () => {
+    let home: string;
+    let service: PluginService;
+    let installedPath: string;
+    let installedCommit: string | undefined;
 
-    const store = createStore(home);
-    const service = bindTestSessionHost(
-      new PluginService(pino({ level: "silent" }), store, "0.4.0", {
-        managedSources: new ManagedPluginSources(home),
-      }),
-    );
-    await service.start();
-    const installed = await service.installSource({ source: pathToFileURL(repository).href });
-    const installedPath = installed.path;
-    const installedCommit = installed.commit;
+    // Prepare the installed revision and its broken update before the update deadline.
+    beforeEach(async () => {
+      home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+      roots.push(home);
+      const repository = await mkdtemp(path.join(tmpdir(), "paseo-plugin-repository-"));
+      roots.push(repository);
+      await runGitCommand(["init", "-b", "main"], { cwd: repository });
+      await runGitCommand(["config", "user.name", "Paseo Tests"], { cwd: repository });
+      await runGitCommand(["config", "user.email", "paseo@example.test"], { cwd: repository });
+      await writeFile(
+        path.join(repository, "paseo-plugin.json"),
+        JSON.stringify({ id: "git-update" }),
+      );
+      await writeFile(
+        path.join(repository, "index.server.ts"),
+        "export default function contribute(plugin: unknown) { void plugin; return () => undefined; }",
+      );
+      await runGitCommand(["add", "-A"], { cwd: repository });
+      await runGitCommand(["commit", "-m", "initial"], { cwd: repository });
 
-    await writeFile(
-      path.join(repository, "paseo-plugin.json"),
-      JSON.stringify({
-        id: "git-update",
-        build: [
-          [process.execPath, "-e", 'process.stderr.write("build exploded") ; process.exit(1)'],
-        ],
-      }),
-    );
-    await writeFile(
-      path.join(repository, "index.server.ts"),
-      'export default function contribute(plugin: unknown) { void plugin; throw new Error("broken update"); }',
-    );
-    await runGitCommand(["add", "-A"], { cwd: repository });
-    await runGitCommand(["commit", "-m", "broken update"], { cwd: repository });
+      const store = createStore(home);
+      service = bindTestSessionHost(
+        new PluginService(pino({ level: "silent" }), store, "0.4.0", {
+          managedSources: new ManagedPluginSources(home),
+        }),
+      );
+      await service.start();
+      const installed = await service.installSource({ source: pathToFileURL(repository).href });
+      installedPath = installed.path;
+      installedCommit = installed.commit;
 
-    expect(await applyReviewedUpdate(service, "git-update")).toMatchObject([
-      { outcome: "error", error: expect.stringContaining("build exploded") },
-    ]);
-    expect(await readdir(path.join(home, "plugins", ".staging"))).toEqual([]);
-    expect(service.catalog()).toEqual([
-      expect.objectContaining({ id: "git-update", clientBundle: expect.any(String) }),
-    ]);
-    expect(await service.listPlugins()).toMatchObject([
-      expect.objectContaining({
-        id: "git-update",
-        path: installedPath,
-        commit: installedCommit,
-        status: "running",
-      }),
-    ]);
-    await service.stopAllPlugins();
-  }, 30_000);
+      await writeFile(
+        path.join(repository, "paseo-plugin.json"),
+        JSON.stringify({
+          id: "git-update",
+          build: [
+            [process.execPath, "-e", 'process.stderr.write("build exploded") ; process.exit(1)'],
+          ],
+        }),
+      );
+      await writeFile(
+        path.join(repository, "index.server.ts"),
+        'export default function contribute(plugin: unknown) { void plugin; throw new Error("broken update"); }',
+      );
+      await runGitCommand(["add", "-A"], { cwd: repository });
+      await runGitCommand(["commit", "-m", "broken update"], { cwd: repository });
+    });
+
+    afterEach(async () => {
+      await service?.stopAllPlugins();
+    });
+
+    it("keeps the running commit when a Git update build command fails", async () => {
+      expect(await applyReviewedUpdate(service, "git-update")).toMatchObject([
+        { outcome: "error", error: expect.stringContaining("build exploded") },
+      ]);
+      expect(await readdir(path.join(home, "plugins", ".staging"))).toEqual([]);
+      expect(service.catalog()).toEqual([
+        expect.objectContaining({ id: "git-update", clientBundle: expect.any(String) }),
+      ]);
+      expect(await service.listPlugins()).toMatchObject([
+        expect.objectContaining({
+          id: "git-update",
+          path: installedPath,
+          commit: installedCommit,
+          status: "running",
+        }),
+      ]);
+    }, 30_000);
+  });
 
   it("runs Git build commands in staging before validation and activation on install and update", async () => {
     const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
@@ -1071,9 +1192,38 @@ export default function contribute(plugin: unknown) {
       "second",
       `export default function contribute(plugin: unknown) { void plugin; return () => undefined; }`,
     );
+    // Hold cleanup open so synchronous detach and queued recovery are tested
+    // independently of compiler/process startup speed on the runner.
+    let finishCleanup = () => undefined;
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve;
+    });
+    const running = new Set<string>();
+    const runtime: TestPluginRuntime = {
+      ...emptyUsageRuntime,
+      catalog: () => [...running].map((id) => ({ id, clientBundle: "bundle" })),
+      invoke: async (pluginId) => {
+        if (!running.has(pluginId)) throw new Error(`Plugin is not available: ${pluginId}`);
+        return pluginId;
+      },
+      getLogs: () => [],
+      clearLogs: () => undefined,
+      startPlugin: async (pluginId, _path, canPublish) => {
+        if (!canPublish()) throw new Error(`Plugin start cancelled: ${pluginId}`);
+        running.add(pluginId);
+      },
+      stopPluginById: async (pluginId) => {
+        const existed = running.delete(pluginId);
+        await cleanup;
+        return existed;
+      },
+      stopAll: async () => running.clear(),
+      subscribe: () => () => undefined,
+      bindPaseoSessionHost: () => undefined,
+    };
     const store = createStore(home);
     const service = bindTestSessionHost(
-      new PluginService(pino({ level: "silent" }), store, "0.4.0"),
+      new PluginService(pino({ level: "silent" }), store, "0.4.0", { runtime }),
     );
     try {
       await service.start();
@@ -1087,6 +1237,8 @@ export default function contribute(plugin: unknown) {
         "Plugin is not available",
       );
       await store.patch({ pluginsEnabled: true });
+      expect(service.catalog()).toEqual([]);
+      finishCleanup();
       // Observe recovery itself. Reloading here restarts a healthy plugin and
       // would also conceal a failure to restart it after the global enable.
       await expect
@@ -1096,6 +1248,7 @@ export default function contribute(plugin: unknown) {
           { id: "second", status: "running" },
         ]);
     } finally {
+      finishCleanup();
       await service.stopAllPlugins();
     }
   }, 20_000);
@@ -1326,6 +1479,105 @@ export default function contribute(plugin: unknown) {
   });
 });
 
+describe("PluginService registry source resolution", () => {
+  let home: string;
+  let owner: string;
+  let source: string;
+  let repository: string;
+  let revision: string;
+
+  // Prepare the real Git fixture before the install deadline starts. On Windows,
+  // these four Git launches can consume much of the test’s 30-second budget.
+  beforeEach(async () => {
+    home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
+    owner = path.join(process.cwd(), `registry-shadow-${randomUUID()}`);
+    await mkdir(owner);
+    roots.push(home, owner);
+    source = `${path.basename(owner)}/example`;
+    repository = await createPlugin("registry-example", "export default () => () => {};\n");
+    await mkdir(path.join(owner, "example"));
+    await cp(repository, path.join(owner, "example"), { recursive: true });
+    await runGitCommand(["init", "-b", "main"], { cwd: repository });
+    await runGitCommand(["add", "-A"], { cwd: repository });
+    await runGitCommand(
+      [
+        "-c",
+        "user.name=Paseo Tests",
+        "-c",
+        "user.email=paseo@example.test",
+        "commit",
+        "-m",
+        "fixture",
+      ],
+      { cwd: repository },
+    );
+    const { stdout } = await runGitCommand(["rev-parse", "HEAD"], { cwd: repository });
+    revision = stdout.trim();
+  });
+
+  it("resolves a bare registry id even when a matching directory exists in the daemon cwd", async () => {
+    const requests: Array<string | undefined> = [];
+    const server = createServer((request, response) => {
+      requests.push(request.url);
+      response.setHeader("Content-Type", "application/json");
+      response.end(
+        JSON.stringify({
+          id: source,
+          name: "Example",
+          description: "Test",
+          categories: [],
+          author: { github: path.basename(owner) },
+          repository: { url: "https://github.com/fixture/example" },
+          artifact: {
+            kind: "git",
+            remote: pathToFileURL(repository).href,
+            commit: revision,
+            pluginPath: ".",
+          },
+          media: [],
+          submittedAt: "2026-10-03",
+          reviewedAt: "2026-10-03",
+          updatedAt: "2026-10-03",
+          publishedAt: "2026-10-03",
+          readme: "# Test",
+        }),
+      );
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Missing registry address");
+    const url = `http://127.0.0.1:${address.port}`;
+    const store = createStore(home);
+    await store.patch({ pluginsEnabled: false });
+    const service = bindTestSessionHost(
+      new PluginService(pino({ level: "silent" }), store, "0.4.0", {
+        managedSources: new ManagedPluginSources(home, { defaultUrl: url }),
+      }),
+    );
+    try {
+      await service.start();
+      await expect(service.installSource({ source })).resolves.toMatchObject({
+        id: "registry-example",
+        status: "disabled",
+        installation: {
+          identity: { kind: "git", registry: { url, id: source } },
+          currentRevision: revision,
+        },
+      });
+      expect(requests).toEqual([`/plugins/${source}.json`]);
+      await expect(
+        service.installSource({ source: `./${source}`, id: "local-example" }),
+      ).resolves.toMatchObject({
+        installation: { identity: { kind: "directory", path: path.join(owner, "example") } },
+      });
+      expect(requests).toEqual([`/plugins/${source}.json`]);
+    } finally {
+      await service.stopAllPlugins();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  }, 30_000);
+});
+
 describe("npm plugin installation", () => {
   let registry: Awaited<ReturnType<typeof startNpmRegistry>>;
 
diff --git a/packages/server/src/server/plugins/index.ts b/packages/server/src/server/plugins/index.ts
index 5dad547d5c..c3ffb6bef2 100644
--- a/packages/server/src/server/plugins/index.ts
+++ b/packages/server/src/server/plugins/index.ts
@@ -25,6 +25,7 @@ import { readPluginManifest } from "./manifest.js";
 import { expandTilde } from "../../utils/path.js";
 import { runPluginBuild } from "./preparation.js";
 import { PluginRuntime } from "./runtime.js";
+import type { PluginRuntimeSubscription } from "./runtime-subscription.js";
 import { BuiltinPluginLoader, type BuiltinPlugin } from "./builtin/index.js";
 import type { PluginProviderMetadata } from "./plugin-process-protocol.js";
 import { readPluginProviderIcon } from "./provider-icon.js";
@@ -48,6 +49,7 @@ interface PluginRuntimePort {
   wait?: PluginLifecycle["wait"];
   catalog: PluginRuntime["catalog"];
   invoke(pluginId: string, method: string, input: unknown): Promise<unknown>;
+  startSubscription: PluginRuntime["startSubscription"];
   getLogs(pluginId: string): PluginLogEntry[];
   clearLogs(pluginId: string): void;
   getProviderRegistrations?(pluginId: string): readonly PluginProviderMetadata[];
@@ -230,11 +232,18 @@ export class PluginService {
       }
     });
     if (config.pluginsEnabled === true) {
-      for (const [pluginId, source] of Object.entries(config.plugins ?? {})) {
-        if (source.enabled === false) continue;
-        await this.startConfigured(pluginId);
-        this.notify(pluginId);
-      }
+      let earlierPublished: Promise<unknown> = Promise.resolve();
+      await Promise.all(
+        Object.entries(config.plugins ?? {})
+          .filter(([, source]) => source.enabled !== false)
+          .map(async ([pluginId]) => {
+            const publishTurn = earlierPublished;
+            const starting = this.startConfigured(pluginId, publishTurn);
+            earlierPublished = Promise.all([publishTurn, starting]);
+            await starting;
+            this.notify(pluginId);
+          }),
+      );
     }
     this.configStore.onFieldChange("pluginsEnabled", (value) => {
       this.handleGlobalSwitch(value === true);
@@ -532,6 +541,10 @@ export class PluginService {
     return this.runtime.invoke(pluginId, method, input);
   }
 
+  subscribePluginRpc(pluginId: string, method: string, input: unknown): PluginRuntimeSubscription {
+    return this.runtime.startSubscription(pluginId, method, input);
+  }
+
   async stopAllPlugins(): Promise<void> {
     this.globalStartsBlocked = true;
     const stopping = this.stopAll();
@@ -560,12 +573,12 @@ export class PluginService {
     }).catch((error) => this.logger.error({ err: error }, "Failed to enable plugins"));
   }
 
-  private async startConfigured(pluginId: string): Promise<void> {
+  private async startConfigured(pluginId: string, publishTurn?: Promise<unknown>): Promise<void> {
     const source = this.configStore.get().plugins?.[pluginId];
     if (!source || source.enabled === false || !this.canPublish(pluginId)) return;
     this.errors.delete(pluginId);
     try {
-      await this.startPlugin(pluginId, source.path);
+      await this.startPlugin(pluginId, source.path, publishTurn);
     } catch (error) {
       if (this.canPublish(pluginId)) this.recordFailure(pluginId, error);
     }
@@ -594,8 +607,13 @@ export class PluginService {
     );
   }
 
-  private async startPlugin(pluginId: string, sourcePath: string): Promise<void> {
+  private async startPlugin(
+    pluginId: string,
+    sourcePath: string,
+    publishTurn?: Promise<unknown>,
+  ): Promise<void> {
     await this.runtime.startPlugin(pluginId, sourcePath, () => this.canPublish(pluginId));
+    await publishTurn;
     try {
       await this.publishProviderRegistrations(pluginId, sourcePath);
       this.publishUsageSources(pluginId);
diff --git a/packages/server/src/server/plugins/lifecycle.e2e.test.ts b/packages/server/src/server/plugins/lifecycle.e2e.test.ts
index bd1dfa8859..7d5ffe3082 100644
--- a/packages/server/src/server/plugins/lifecycle.e2e.test.ts
+++ b/packages/server/src/server/plugins/lifecycle.e2e.test.ts
@@ -8,6 +8,7 @@ import { DaemonClient } from "../test-utils/daemon-client.js";
 import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
 import { resolveDaemonVersion } from "../daemon-version.js";
 import { BuiltinPluginLoader } from "./builtin/index.js";
+import { createPaseoApi } from "@getpaseo/client";
 
 test("a plugin transforms workspace creation once across receipt replays and observes its committed lifecycle", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-lifecycle-"));
@@ -240,6 +241,193 @@ export default function contribute(server) {
   }
 }, 60_000);
 
+test("metadata set at creation reaches the hooks, a before hook can add to it, and snapshots carry it", async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-metadata-hooks-"));
+  const daemon = await createTestPaseoDaemon();
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await writeFile(
+      path.join(directory, "paseo-plugin.json"),
+      JSON.stringify({
+        id: "metadata-hooks",
+        requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` },
+      }),
+    );
+    await writeFile(
+      path.join(directory, "index.server.ts"),
+      `
+export default function contribute(server) {
+  const log = (hook, metadata) => console.log(JSON.stringify({ hook, metadata }));
+  server.addHook("workspace.create.before", async ({ request }) => {
+    log("workspace.create.before", request.metadata);
+    return request;
+  });
+  server.addHook("workspace.create.after", async ({ workspace }) => {
+    log("workspace.create.after", workspace.metadata);
+  });
+  server.addHook("agent.create.before", async ({ request }) => {
+    log("agent.create.before", request.metadata);
+    return { ...request, metadata: { ...request.metadata, "hook.added": true } };
+  });
+  server.addHook("agent.open.before", async ({ request }) => {
+    log("agent.open.before", request.metadata);
+    return request;
+  });
+  server.addHook("agent.create.after", async ({ agent }) => {
+    log("agent.create.after", agent.metadata);
+  });
+  return () => {};
+}
+`,
+    );
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(directory);
+    const workspace = await client.createWorkspace({
+      source: { kind: "directory", path: directory },
+      metadata: { "linear.issue": { id: "ENG-123" } },
+    });
+    expect(workspace.workspace?.metadata).toEqual({ "linear.issue": { id: "ENG-123" } });
+    const agent = await client.createAgent({
+      provider: "claude",
+      cwd: directory,
+      workspaceId: workspace.workspace!.id,
+      metadata: { "linear.issue": { id: "ENG-123" } },
+    });
+    expect(agent.metadata).toEqual({ "linear.issue": { id: "ENG-123" }, "hook.added": true });
+    await expect
+      .poll(async () => {
+        const logs = await client.getPluginLogs("metadata-hooks");
+        return logs
+          .filter((entry) => entry.message.startsWith('{"hook":'))
+          .map((entry) => JSON.parse(entry.message));
+      })
+      .toMatchObject([
+        { hook: "workspace.create.before", metadata: { "linear.issue": { id: "ENG-123" } } },
+        { hook: "workspace.create.after", metadata: { "linear.issue": { id: "ENG-123" } } },
+        { hook: "agent.create.before", metadata: { "linear.issue": { id: "ENG-123" } } },
+        {
+          hook: "agent.open.before",
+          metadata: { "linear.issue": { id: "ENG-123" }, "hook.added": true },
+        },
+        {
+          hook: "agent.create.after",
+          metadata: { "linear.issue": { id: "ENG-123" }, "hook.added": true },
+        },
+      ]);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(directory, { recursive: true, force: true });
+  }
+}, 60_000);
+
+test("metadata set at creation and through setMetadata survives a daemon restart", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-metadata-restart-"));
+  const directory = await mkdtemp(path.join(tmpdir(), "paseo-metadata-cwd-"));
+  const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-metadata-plugin-"));
+  try {
+    await writeFile(
+      path.join(pluginDirectory, "paseo-plugin.json"),
+      JSON.stringify({
+        id: "metadata-restart",
+        requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` },
+      }),
+    );
+    // Returns an explicit object without `metadata`, as a plugin written before metadata existed.
+    await writeFile(
+      path.join(pluginDirectory, "index.server.ts"),
+      `
+export default function contribute(server) {
+  server.addHook("agent.open.before", async ({ request }) => {
+    console.log(JSON.stringify({ hook: "agent.open.before", metadata: request.metadata }));
+    const { metadata, ...old } = request;
+    return { ...old, env: { ...old.env, HOOK_OPEN: "opened" } };
+  });
+  return () => {};
+}
+`,
+    );
+    const first = await createTestPaseoDaemon({ paseoHomeRoot: root, cleanup: false });
+    const firstClient = new DaemonClient({ url: `ws://127.0.0.1:${first.port}/ws` });
+    const firstApi = createPaseoApi(firstClient);
+    let agentId: string;
+    let workspaceId: string;
+    try {
+      await firstClient.connect();
+      await firstClient.fetchAgents({ subscribe: {} });
+      await firstClient.patchDaemonConfig({ pluginsEnabled: true });
+      await firstClient.installDirectoryPlugin(pluginDirectory);
+      const workspace = await firstClient.createWorkspace({
+        source: { kind: "directory", path: directory },
+        metadata: { "a.workspace": 1, "b.workspace": "to remove" },
+      });
+      workspaceId = workspace.workspace!.id;
+      const agent = await firstClient.createAgent({
+        provider: "claude",
+        cwd: directory,
+        workspaceId,
+        metadata: { "a.agent": { nested: [1, 2] }, "b.agent": "to remove" },
+      });
+      agentId = agent.id;
+      const agentHandle = firstApi.agents.ref(agentId);
+      await agentHandle.setMetadata({ "b.agent": null, "c.agent": true });
+      await firstApi.workspaces.ref(workspaceId).setMetadata({
+        "b.workspace": null,
+        "c.workspace": [],
+      });
+      expect((await firstClient.fetchAgent({ agentId }))?.agent.metadata).toEqual({
+        "a.agent": { nested: [1, 2] },
+        "c.agent": true,
+      });
+    } finally {
+      await firstApi.dispose();
+      await firstClient.close();
+      await first.close();
+    }
+
+    const second = await createTestPaseoDaemon({ paseoHomeRoot: root, cleanup: false });
+    const secondClient = new DaemonClient({ url: `ws://127.0.0.1:${second.port}/ws` });
+    try {
+      await secondClient.connect();
+      const agent = await secondClient.fetchAgent({ agentId });
+      expect(agent?.agent.metadata).toEqual({ "a.agent": { nested: [1, 2] }, "c.agent": true });
+      const workspaces = await secondClient.fetchWorkspaces({});
+      expect(workspaces.entries.find((entry) => entry.id === workspaceId)?.metadata).toEqual({
+        "a.workspace": 1,
+        "c.workspace": [],
+      });
+      await secondClient.fetchAgents({ subscribe: {} });
+      await secondClient.patchDaemonConfig({ pluginsEnabled: true });
+      await secondClient.installDirectoryPlugin(pluginDirectory);
+      await secondClient.refreshAgent(agentId);
+      await expect
+        .poll(async () => {
+          const logs = await secondClient.getPluginLogs("metadata-restart");
+          return logs
+            .filter((entry) => entry.message.startsWith('{"hook":'))
+            .map((entry) => JSON.parse(entry.message));
+        })
+        .toContainEqual({
+          hook: "agent.open.before",
+          metadata: { "a.agent": { nested: [1, 2] }, "c.agent": true },
+        });
+      expect((await secondClient.fetchAgent({ agentId }))?.agent.metadata).toEqual({
+        "a.agent": { nested: [1, 2] },
+        "c.agent": true,
+      });
+    } finally {
+      await secondClient.close();
+      await second.close();
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(directory, { recursive: true, force: true });
+    await rm(pluginDirectory, { recursive: true, force: true });
+  }
+}, 60_000);
+
 test("agent creation hooks change the provider and environment before the session opens", async () => {
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-agent-hooks-"));
   const pluginDirectory = await createProviderPlugin(directory, {
diff --git a/packages/server/src/server/plugins/lifecycle/handlers.test.ts b/packages/server/src/server/plugins/lifecycle/handlers.test.ts
index e17cca1ed5..49cf75fceb 100644
--- a/packages/server/src/server/plugins/lifecycle/handlers.test.ts
+++ b/packages/server/src/server/plugins/lifecycle/handlers.test.ts
@@ -92,6 +92,7 @@ test("session-open hooks reject changes to session identity instead of silently
         env: {},
         title: null,
         labels: {},
+        metadata: {},
         tools: [],
         mcpServers: {},
       },
@@ -100,6 +101,105 @@ test("session-open hooks reject changes to session identity instead of silently
   ).rejects.toThrow("agent.open.before hooks can only change env");
 });
 
+test("a create hook that omits metadata passes on what an earlier hook added", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  hooks.addHook("agent.create.before", async ({ request }) => ({
+    ...request,
+    metadata: { ...request.metadata, "new.plugin": { ticket: 42 } },
+  }));
+  hooks.addHook("agent.create.before", async ({ request }) => ({
+    config: request.config,
+    env: request.env,
+  }));
+  const seen: unknown[] = [];
+  hooks.addHook("agent.create.before", async ({ request }) => {
+    seen.push(request.metadata);
+  });
+  const result = await hooks.invoke(
+    "operation",
+    "agent.create.before",
+    { config: { provider: "codex", cwd: "/project" }, env: {}, metadata: { original: true } },
+    paseo,
+  );
+  expect(result).toMatchObject({ metadata: { original: true, "new.plugin": { ticket: 42 } } });
+  expect(seen).toEqual([{ original: true, "new.plugin": { ticket: 42 } }]);
+});
+
+test("a workspace create hook that omits metadata passes on what an earlier hook added", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  hooks.addHook("workspace.create.before", async ({ request }) => ({
+    ...request,
+    metadata: { ...request.metadata, "new.plugin": { ticket: 42 } },
+  }));
+  hooks.addHook("workspace.create.before", async ({ request }) => ({ source: request.source }));
+  const seen: unknown[] = [];
+  hooks.addHook("workspace.create.before", async ({ request }) => {
+    seen.push(request.metadata);
+  });
+  const result = await hooks.invoke(
+    "operation",
+    "workspace.create.before",
+    { source: { kind: "directory", path: "/project" }, metadata: { original: true } },
+    paseo,
+  );
+  expect(result).toMatchObject({ metadata: { original: true, "new.plugin": { ticket: 42 } } });
+  expect(seen).toEqual([{ original: true, "new.plugin": { ticket: 42 } }]);
+
+  const replacing = new PluginHookHandlers(() => {});
+  replacing.addHook("workspace.create.before", async ({ request }) => ({
+    ...request,
+    metadata: {},
+  }));
+  await expect(
+    replacing.invoke(
+      "operation",
+      "workspace.create.before",
+      { source: { kind: "directory", path: "/project" }, metadata: { original: true } },
+      paseo,
+    ),
+  ).resolves.toMatchObject({ metadata: {} });
+});
+
+test("a session-open hook that returns its own object without metadata leaves metadata unchanged", async () => {
+  const hooks = new PluginHookHandlers(() => {});
+  hooks.addHook("agent.open.before", async ({ request }) => ({
+    agentId: request.agentId,
+    workspaceId: request.workspaceId,
+    provider: request.provider,
+    cwd: request.cwd,
+    reason: request.reason,
+    purpose: request.purpose,
+    title: request.title,
+    labels: request.labels,
+    tools: request.tools,
+    env: { HOOK: "1" },
+    mcpServers: request.mcpServers,
+  }));
+  const result = await hooks.invoke(
+    "operation",
+    "agent.open.before",
+    {
+      agentId: "agent",
+      workspaceId: null,
+      provider: "codex",
+      cwd: "/project",
+      title: null,
+      labels: {},
+      metadata: { "linear.issue": { id: "ENG-1" } },
+      tools: [],
+      mcpServers: {},
+      env: {},
+      reason: "resume",
+      purpose: "interactive",
+    },
+    paseo,
+  );
+  expect(result).toMatchObject({
+    env: { HOOK: "1" },
+    metadata: { "linear.issue": { id: "ENG-1" } },
+  });
+});
+
 test.each([{ title: "Changed" }, { labels: { changed: "true" } }])(
   "session-open targeting metadata is read-only: %j",
   async (patch) => {
@@ -116,6 +216,7 @@ test.each([{ title: "Changed" }, { labels: { changed: "true" } }])(
           cwd: "/project",
           title: "Original",
           labels: {},
+          metadata: {},
           tools: [],
           mcpServers: {},
           env: {},
diff --git a/packages/server/src/server/plugins/lifecycle/index.ts b/packages/server/src/server/plugins/lifecycle/index.ts
index d4f58cc78c..f7ddd84b74 100644
--- a/packages/server/src/server/plugins/lifecycle/index.ts
+++ b/packages/server/src/server/plugins/lifecycle/index.ts
@@ -13,6 +13,7 @@ import {
 import type { AgentToolDefinition } from "@getpaseo/plugin/server";
 import type { AgentStreamEvent } from "../../agent/agent-sdk-types.js";
 import { z } from "zod";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import { CreateAgentRequestMessageSchema } from "@getpaseo/protocol/messages";
 import type {
   PluginHookAgent,
@@ -91,6 +92,7 @@ const beforeSchemas = {
   "agent.create.before": CreateAgentRequestMessageSchema.pick({
     config: true,
     env: true,
+    metadata: true,
   }).strict(),
   "agent.open.before": z
     .object({
@@ -102,6 +104,8 @@ const beforeSchemas = {
       purpose: z.enum(["interactive", "history"]),
       title: z.string().nullable(),
       labels: z.record(z.string(), z.string()),
+      // Optional so a plugin that returns its own object keeps working; omitted means unchanged.
+      metadata: z.record(z.string(), z.custom<JsonValue>()).optional(),
       tools: z.array(agentToolMetadataSchema),
       env: z.record(z.string(), z.string()),
       mcpServers: CreateAgentRequestMessageSchema.shape.config.shape.mcpServers.unwrap(),
@@ -152,6 +156,7 @@ export function describeHookWorkspace(workspace: PersistedWorkspaceRecord): Plug
     cwd: workspace.cwd,
     name: workspace.title,
     archivedAt: workspace.archivedAt,
+    metadata: workspace.metadata,
   };
 }
 
@@ -162,6 +167,7 @@ export function describeHookAgent(agent: {
   cwd: string;
   title?: string | null;
   labels: Record<string, string>;
+  metadata: Record<string, JsonValue>;
 }): PluginHookAgent {
   return {
     id: agent.id,
@@ -170,6 +176,7 @@ export function describeHookAgent(agent: {
     provider: agent.provider,
     cwd: agent.cwd,
     title: agent.title ?? null,
+    metadata: agent.metadata,
   };
 }
 
@@ -229,10 +236,12 @@ export async function validateBeforeResult<Name extends keyof PluginWireBeforeRe
       previous.reason !== next.reason ||
       previous.purpose !== next.purpose ||
       previous.title !== next.title ||
-      !isDeepStrictEqual(previous.labels, next.labels)
+      !isDeepStrictEqual(previous.labels, next.labels) ||
+      (next.metadata !== undefined && !isDeepStrictEqual(previous.metadata, next.metadata))
     ) {
       throw new Error("agent.open.before hooks can only change env, tools, and mcpServers");
     }
+    return { ...result, metadata: previous.metadata };
   }
   if (name === "agent.create.before") {
     const previous = beforeSchemas["agent.create.before"].parse(input);
@@ -240,6 +249,14 @@ export async function validateBeforeResult<Name extends keyof PluginWireBeforeRe
     if (previous.config.cwd !== next.config.cwd) {
       throw new Error("agent.create.before hooks cannot change the workspace directory");
     }
+    // Omitted means unchanged: the next hook sees what this one was handed.
+    return { ...result, metadata: next.metadata ?? previous.metadata };
+  }
+  if (name === "workspace.create.before") {
+    const previous = beforeSchemas["workspace.create.before"].parse(input);
+    const next = beforeSchemas["workspace.create.before"].parse(result);
+    // Omitted means unchanged; an explicit {} still replaces.
+    return { ...result, metadata: next.metadata ?? previous.metadata };
   }
   if (name === "worktree.create.before") {
     const previous = beforeSchemas["worktree.create.before"].parse(input);
diff --git a/packages/server/src/server/plugins/managed-source.posix.test.ts b/packages/server/src/server/plugins/managed-source.posix.test.ts
index 466780b79a..440ef52074 100644
--- a/packages/server/src/server/plugins/managed-source.posix.test.ts
+++ b/packages/server/src/server/plugins/managed-source.posix.test.ts
@@ -61,10 +61,24 @@ describe("managed Git plugin sources", () => {
     roots.push(home);
     const sources = new ManagedPluginSources(home);
 
-    const failure = sources.prepareInstall({
-      source: "git:https://oauth2:super-secret@127.0.0.1:1/missing.git",
+    // Own the failure response instead of relying on a closed port and OS connect timing.
+    const server = createServer((_request, response) => {
+      response.writeHead(500, { "Content-Type": "text/plain" });
+      response.end("clone rejected for oauth2:super-secret\n");
     });
-    await expect(failure).rejects.not.toThrow(/oauth2|super-secret/);
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address() as { port: number };
+    try {
+      const failure = sources.prepareInstall({
+        source: `git:http://oauth2:super-secret@127.0.0.1:${address.port}/missing.git`,
+      });
+      await expect(failure).rejects.toThrow("500");
+      await expect(failure).rejects.toThrow("clone rejected for [redacted]:[redacted]");
+      await expect(failure).rejects.not.toThrow(/oauth2|super-secret/);
+    } finally {
+      server.closeAllConnections();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
   });
 
   it("normalizes explicit GitHub and Git identifiers to the same Git source", async () => {
@@ -561,3 +575,53 @@ it("installs and updates only the npm artifacts pinned by the plugin registry",
     else process.env.npm_config_userconfig = previous;
   }
 }, 30_000);
+
+it("installs a registry npm pin through the configured npm mirror", async () => {
+  const { startNpmRegistry, npmPluginPackages } =
+    await import("../../../../../scripts/test-support/npm-registry.mjs");
+  const { readNpmArtifact, resolveNpm } = await import("./managed-source/npm.js");
+  const mirror = await startNpmRegistry(npmPluginPackages());
+  const previous = process.env.npm_config_userconfig;
+  process.env.npm_config_userconfig = mirror.userconfig;
+  // The public registry pins npmjs.org tarball URLs, which a mirror does not serve at the same path.
+  const pin = {
+    version: "1.0.0",
+    resolved: "https://registry.npmjs.org/paseo-fixture-plugin/-/paseo-fixture-plugin-1.0.0.tgz",
+    integrity: "",
+  };
+  const server = createServer((_request, response) => {
+    response.end(
+      JSON.stringify({
+        id: "acme/example",
+        artifact: { kind: "npm", package: "paseo-fixture-plugin", ...pin },
+      }),
+    );
+  });
+  try {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-registry-npm-mirror-"));
+    roots.push(home);
+    pin.integrity = (await resolveNpm("paseo-fixture-plugin", "1.0.0", home)).integrity;
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Missing registry address");
+    const sources = new ManagedPluginSources(home, {
+      defaultUrl: `http://127.0.0.1:${address.port}`,
+    });
+    const candidate = await sources.place(
+      "example",
+      await sources.prepareInstall({ source: "acme/example" }),
+    );
+    await sources.verifyCandidate("example", candidate);
+    sources.commit("example", candidate.record);
+    expect((await sources.describe("example", candidate.directory)).currentRevision).toBe("1.0.0");
+    expect(
+      await readNpmArtifact(path.resolve(candidate.directory, "../.."), "paseo-fixture-plugin"),
+    ).toEqual({ ...pin, resolved: `${mirror.url}/artifacts/1.tgz` });
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await mirror.close();
+    if (previous === undefined) delete process.env.npm_config_userconfig;
+    else process.env.npm_config_userconfig = previous;
+  }
+}, 30_000);
diff --git a/packages/server/src/server/plugins/managed-source.ts b/packages/server/src/server/plugins/managed-source.ts
index 5373b7453a..a20be890b3 100644
--- a/packages/server/src/server/plugins/managed-source.ts
+++ b/packages/server/src/server/plugins/managed-source.ts
@@ -22,7 +22,13 @@ import {
 import { runGitCommand } from "../../utils/run-git-command.js";
 import { ensurePrivateDirectory, writePrivateFileAtomicSync } from "../private-files.js";
 import { readPluginManifest, type PluginManifest } from "./manifest.js";
-import { acquireNpm, isNpmSource, readNpmArtifact, resolveNpm } from "./managed-source/npm.js";
+import {
+  acquireNpm,
+  isNpmSource,
+  isSameNpmArtifact,
+  readNpmArtifact,
+  resolveNpm,
+} from "./managed-source/npm.js";
 
 const GIT_TIMEOUT_MS = 120_000;
 const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" } as const;
@@ -346,11 +352,7 @@ export class ManagedPluginSources {
       throw new Error("Preparation changed the reviewed Git commit");
     if (target?.kind === "npm" && location.identity.kind === "npm") {
       const artifact = await readNpmArtifact(location.versionRoot, location.identity.packageName);
-      if (
-        artifact.version !== target.version ||
-        artifact.integrity !== target.integrity ||
-        artifact.resolved !== target.resolved
-      )
+      if (!isSameNpmArtifact({ installed: artifact, target }))
         throw new Error("Preparation changed the reviewed npm artifact");
     }
   }
diff --git a/packages/server/src/server/plugins/managed-source/npm.ts b/packages/server/src/server/plugins/managed-source/npm.ts
index 315bbc981e..419a807201 100644
--- a/packages/server/src/server/plugins/managed-source/npm.ts
+++ b/packages/server/src/server/plugins/managed-source/npm.ts
@@ -48,7 +48,7 @@ export async function acquireNpm(source: string, installRoot: string, target?: N
       name: "paseo-plugin-installation",
       version: "1.0.0",
       private: true,
-      dependencies: { [packageName]: target?.resolved ?? requestedSpec },
+      dependencies: { [packageName]: requestedSpec },
     }),
   );
   const npm = await requireNpm();
@@ -70,23 +70,28 @@ export async function acquireNpm(source: string, installRoot: string, target?: N
     { cwd: installRoot, timeout: 120_000, maxBuffer: 1024 * 1024 },
   );
   const installed = await readNpmArtifact(installRoot, packageName);
-  if (
-    target &&
-    (installed.version !== target.version ||
-      installed.integrity !== target.integrity ||
-      installed.resolved !== target.resolved)
-  ) {
+  if (target && !isSameNpmArtifact({ installed, target })) {
     throw new Error(`npm artifact changed since review for ${packageName}`);
   }
   return { packageName, ...installed };
 }
 
+// Mirrors serve the reviewed tarball from their own URL, so the content hash identifies it.
+export function isSameNpmArtifact({ installed, target }: NpmArtifactComparison): boolean {
+  return installed.version === target.version && installed.integrity === target.integrity;
+}
+
 export interface NpmArtifact {
   version: string;
   resolved: string;
   integrity: string;
 }
 
+export interface NpmArtifactComparison {
+  installed: NpmArtifact;
+  target: NpmArtifact;
+}
+
 export async function readNpmArtifact(
   installRoot: string,
   packageName: string,
diff --git a/packages/server/src/server/plugins/plugin-process-protocol.ts b/packages/server/src/server/plugins/plugin-process-protocol.ts
index e582387d48..2f4e7b43f7 100644
--- a/packages/server/src/server/plugins/plugin-process-protocol.ts
+++ b/packages/server/src/server/plugins/plugin-process-protocol.ts
@@ -1,3 +1,4 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { PluginHookAgent } from "@getpaseo/plugin/server";
 import { UsageScopeSchema, type UsageScope } from "@getpaseo/plugin/server/usage";
 import type {
@@ -60,6 +61,14 @@ export type PluginProcessRequest =
   | { type: "usage.fetch"; requestId: string; sourceId: string; input: unknown }
   | { type: "usage.discover"; requestId: string; sourceId: string; scope: UsageScope }
   | { type: "invoke"; requestId: string; method: string; input: unknown }
+  | {
+      type: "subscribe";
+      requestId: string;
+      subscriptionId: string;
+      method: string;
+      input: unknown;
+    }
+  | { type: "unsubscribe"; subscriptionId: string }
   | {
       type: "provider.connect";
       providerId: string;
@@ -83,6 +92,7 @@ export type PluginProcessMessage =
   | {
       type: "ready";
       methods: string[];
+      subscriptions?: string[];
       providers: PluginProviderMetadata[];
       usageSources?: PluginUsageSourceMetadata[];
       hooks?: string[];
@@ -90,6 +100,8 @@ export type PluginProcessMessage =
   | { type: "result"; requestId: string; output: unknown }
   | { type: "error"; requestId: string; error: string }
   | { type: "fatal"; error: string }
+  | { type: "subscription.event"; subscriptionId: string; event: unknown }
+  | { type: "subscription.closed"; subscriptionId: string; error?: string }
   | {
       type: "provider.connected";
       connectionId: string;
@@ -157,6 +169,7 @@ export const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest> = z.dis
             provider: z.string(),
             cwd: z.string(),
             title: z.string().nullable(),
+            metadata: z.record(z.string(), z.custom<JsonValue>()),
           })
           .strict(),
         name: z.string(),
@@ -240,6 +253,16 @@ export const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest> = z.dis
         input: z.unknown(),
       })
       .strict(),
+    z
+      .object({
+        type: z.literal("subscribe"),
+        requestId: z.string().min(1),
+        subscriptionId: z.string().min(1),
+        method: z.string().min(1),
+        input: z.unknown(),
+      })
+      .strict(),
+    z.object({ type: z.literal("unsubscribe"), subscriptionId: z.string().min(1) }).strict(),
     z
       .object({
         type: z.literal("provider.connect"),
@@ -272,6 +295,7 @@ export const PluginProcessMessageSchema: z.ZodType<PluginProcessMessage> = z.dis
       .object({
         type: z.literal("ready"),
         methods: z.array(z.string()),
+        subscriptions: z.array(z.string()).optional(),
         providers: z.array(providerMetadataSchema),
         usageSources: z.array(usageSourceMetadataSchema).optional(),
         hooks: hooksSchema.optional(),
@@ -284,6 +308,20 @@ export const PluginProcessMessageSchema: z.ZodType<PluginProcessMessage> = z.dis
       .object({ type: z.literal("error"), requestId: z.string().min(1), error: z.string() })
       .strict(),
     z.object({ type: z.literal("fatal"), error: z.string() }).strict(),
+    z
+      .object({
+        type: z.literal("subscription.event"),
+        subscriptionId: z.string().min(1),
+        event: z.unknown(),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal("subscription.closed"),
+        subscriptionId: z.string().min(1),
+        error: z.string().optional(),
+      })
+      .strict(),
     z
       .object({
         type: z.literal("provider.connected"),
diff --git a/packages/server/src/server/plugins/plugin-process.ts b/packages/server/src/server/plugins/plugin-process.ts
index 62514cd0b2..1c0d6bc476 100644
--- a/packages/server/src/server/plugins/plugin-process.ts
+++ b/packages/server/src/server/plugins/plugin-process.ts
@@ -7,8 +7,21 @@ import {
   type PluginProcessRequest,
 } from "./plugin-process-protocol.js";
 import type { UsageSourceRegistration } from "@getpaseo/plugin/server/usage";
-import type { SettingsDefinition, PluginRpcContract } from "@getpaseo/plugin";
-import type { PluginHandlerContext, PluginServerContribution } from "@getpaseo/plugin/server";
+import type {
+  SettingsDefinition,
+  PluginRpcContract,
+  PluginSubscriptionContract,
+} from "@getpaseo/plugin";
+import type {
+  PluginHandlerContext,
+  PluginServerContext,
+  PluginServerContribution,
+} from "@getpaseo/plugin/server";
+import { assertPluginWireValue } from "@getpaseo/protocol/binary-frames/index";
+import {
+  PluginSubscriptionHandlers,
+  type PluginSubscriptionHandler,
+} from "./subscription-handlers.js";
 import { fileURLToPath } from "node:url";
 import type { ZodType } from "zod";
 import {
@@ -66,6 +79,7 @@ export function createPluginWorker(options: {
     send({ type: "hooks.changed", hooks: hooks.catalog() });
   }, agentTools);
   const handlers = new Map<string, RegisteredRpc>();
+  const subscriptions = new PluginSubscriptionHandlers({ send, sendAndWait });
   const providers = new Map<string, ProviderRegistration>();
   const usageSources = new Map<string, UsageSourceRegistration>();
   const providerConnections = new Map<
@@ -98,12 +112,36 @@ export function createPluginWorker(options: {
     if (!/^[a-z][a-z0-9._-]*$/.test(normalized)) {
       throw new Error(`Invalid plugin RPC method: ${method}`);
     }
-    if (handlers.has(normalized)) {
+    if (handlers.has(normalized) || subscriptions.has(normalized)) {
       throw new Error(`Duplicate plugin RPC method: ${normalized}`);
     }
     return normalized;
   }
 
+  function registerSubscription(
+    contract: PluginSubscriptionContract,
+    handler: PluginSubscriptionHandler,
+  ): void {
+    if (typeof handler !== "function") {
+      throw new Error(`Plugin subscription ${contract.name} must provide a handler`);
+    }
+    const method = validateMethod(contract.name);
+    subscriptions.register({ ...contract, name: method }, handler);
+  }
+
+  // One name serves either an RPC or a subscription; the contract says which.
+  const handle = ((
+    contract: PluginRpcContract | PluginSubscriptionContract,
+    handler: (input: unknown, context: never) => unknown,
+  ) => {
+    if ("event" in contract) {
+      // The subscription handlers parse the input once and pass the result here.
+      registerSubscription(contract, handler as PluginSubscriptionHandler);
+      return;
+    }
+    register(contract, (input, context) => handler(input, context as never));
+  }) as PluginServerContext["handle"];
+
   function register(contract: PluginRpcContract, handler: RpcHandler): void {
     if (typeof handler !== "function") {
       throw new Error(`Plugin RPC ${contract.name} must provide a handler`);
@@ -284,8 +322,7 @@ export function createPluginWorker(options: {
         )
       : null;
     const contributedCleanup = contribute({
-      handle: (contract, handler) =>
-        register(contract, (input, context) => handler(contract.input.parse(input), context)),
+      handle,
       registerProvider,
       registerUsageSource,
       registerSettings,
@@ -311,6 +348,7 @@ export function createPluginWorker(options: {
     send({
       type: "ready",
       methods: [...handlers.keys()].sort(),
+      subscriptions: subscriptions.catalog(),
       hooks: hooks.catalog(),
       providers: [...providers.values()]
         .sort((left, right) => left.id.localeCompare(right.id))
@@ -327,6 +365,7 @@ export function createPluginWorker(options: {
       .catch((error) => console.error("Plugin API cleanup failed", error));
     hooks.close();
     agentTools.close();
+    subscriptions.releaseAll();
     for (const pending of pendingProviderConnections.values()) pending.tombstoned = true;
     const currentCleanup = cleanup;
     cleanup = null;
@@ -365,7 +404,8 @@ export function createPluginWorker(options: {
       message.type === "provider.status" ||
       message.type === "provider.catalog_key" ||
       message.type === "usage.fetch" ||
-      message.type === "usage.discover"
+      message.type === "usage.discover" ||
+      message.type === "subscribe"
     ) {
       send({ type: "error", requestId: message.requestId, error: "Plugin is stopping" });
     } else if (message.type === "provider.connect") {
@@ -422,6 +462,14 @@ export function createPluginWorker(options: {
     return false;
   }
 
+  function handleSubscriptionMessage(
+    message: Extract<PluginProcessRequest, { type: "subscribe" | "unsubscribe" }>,
+  ): void {
+    if (message.type === "unsubscribe") subscriptions.release(message.subscriptionId);
+    else if (paseo) subscriptions.start(message, paseo);
+    else send({ type: "error", requestId: message.requestId, error: "Plugin API unavailable" });
+  }
+
   function handleMessage(rawMessage: unknown): void {
     const parsed = PluginProcessRequestSchema.safeParse(rawMessage);
     if (!parsed.success) {
@@ -525,6 +573,11 @@ export function createPluginWorker(options: {
       handleHookMessage(message);
       return;
     }
+    if (message.type === "invoke") invoke(message);
+    else handleSubscriptionMessage(message);
+  }
+
+  function invoke(message: Extract<PluginProcessRequest, { type: "invoke" }>): void {
     const registered = handlers.get(message.method);
     if (!registered) {
       send({
@@ -540,7 +593,10 @@ export function createPluginWorker(options: {
         if (!paseo) throw new Error("Plugin Paseo API is unavailable");
         return registered.handler(input, { paseo });
       })
-      .then((output) => registered.contract.output.parseAsync(output))
+      .then((output: unknown) => {
+        assertPluginWireValue(output, "output");
+        return output;
+      })
       .then(
         (output) => send({ type: "result", requestId: message.requestId, output }),
         (error) =>
diff --git a/packages/server/src/server/plugins/plugin-subscriptions.e2e.test.ts b/packages/server/src/server/plugins/plugin-subscriptions.e2e.test.ts
new file mode 100644
index 0000000000..97af53c364
--- /dev/null
+++ b/packages/server/src/server/plugins/plugin-subscriptions.e2e.test.ts
@@ -0,0 +1,428 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { WebSocket } from "ws";
+import {
+  DaemonClient,
+  type OwnedSubscription,
+  type WebSocketLike,
+} from "@getpaseo/client/internal/daemon-client";
+import { afterEach, expect, test } from "vitest";
+import { defineRpc } from "@getpaseo/plugin";
+import { callPluginRpc } from "@getpaseo/plugin/client/host";
+import { z } from "zod";
+import { resolveDaemonVersion } from "../daemon-version.js";
+import { createTestPaseoDaemon, type TestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+
+const PLUGIN_ID = "subscriptions";
+
+// Written as an author writes a plugin: one contract per name, handlers that read like English.
+const SERVER_ENTRY = `
+import { defineRpc, defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+const ticks = defineSubscription({
+  name: "ticks",
+  input: z.object({ count: z.number().int(), bytes: z.boolean() }),
+  event: z.union([z.instanceof(Uint8Array), z.object({ n: z.number() })]),
+});
+const failing = defineSubscription({
+  name: "failing",
+  input: z.object({ when: z.enum(["before-ack", "after-ack"]) }),
+  event: z.object({}),
+});
+const nestedPush = defineSubscription({
+  name: "nested-push",
+  input: z.object({}),
+  event: z.object({ data: z.instanceof(Uint8Array) }),
+});
+const repeated = defineSubscription({
+  name: "repeated",
+  input: z.object({ times: z.string().transform(Number) }),
+  event: z.string().transform((text) => text.length),
+});
+const transformed = defineRpc({
+  name: "transformed",
+  input: z.object({ when: z.string().transform(async (text) => new Date(text)) }),
+  output: z.object({ n: z.string().transform(async (text) => Number(text)) }),
+});
+const defaulted = defineRpc({ name: "defaulted", input: z.string().default("x"), output: z.string() });
+const defaultedOutput = defineRpc({ name: "defaulted-output", input: z.object({}), output: z.string().default("x") });
+const watchers = defineRpc({
+  name: "watchers",
+  input: z.object({}),
+  output: z.object({ starts: z.number(), active: z.number() }),
+});
+const thumbnail = defineRpc({
+  name: "thumbnail",
+  input: z.object({ size: z.number().int() }),
+  output: z.instanceof(Uint8Array),
+});
+const nestedOutput = defineRpc({
+  name: "nested-output",
+  input: z.object({}),
+  output: z.object({ data: z.instanceof(Uint8Array) }),
+});
+const reverse = defineRpc({
+  name: "reverse",
+  input: z.instanceof(Uint8Array),
+  output: z.instanceof(Uint8Array),
+});
+
+export default function contribute(server: PluginServerContext) {
+  let starts = 0;
+  let active = 0;
+  server.handle(ticks, ({ count, bytes }, { push, signal }) => {
+    starts += 1;
+    active += 1;
+    signal.addEventListener("abort", () => { active -= 1; }, { once: true });
+    for (let n = 0; n < count; n += 1) void push(bytes ? new Uint8Array([n, n + 1]) : { n });
+  });
+  server.handle(failing, ({ when }) => {
+    if (when === "before-ack") throw new Error("refused before acknowledging");
+    return Promise.reject(new Error("failed after acknowledging"));
+  });
+  server.handle(nestedPush, (_input, { push }) => {
+    void push({ data: new Uint8Array(1) }).catch((error) => {
+      console.error("nested push", error.message);
+    });
+  });
+  server.handle(repeated, async ({ times }, { push }) => {
+    await push(typeof times === "number" ? "x".repeat(times) : "input arrived untransformed");
+  });
+  server.handle(transformed, ({ when }) => ({ n: String(when.getUTCFullYear()) }));
+  server.handle(defaulted, (input) => input);
+  server.handle(defaultedOutput, () => undefined);
+  server.handle(watchers, () => ({ starts, active }));
+  server.handle(thumbnail, ({ size }) => Buffer.alloc(size, 7));
+  server.handle(nestedOutput, () => ({ data: new Uint8Array(1) }));
+  server.handle(reverse, (bytes) => Uint8Array.from(bytes).reverse());
+  return () => undefined;
+}
+`;
+
+type Received =
+  | { type: "event"; event: unknown }
+  | { type: "bytes"; bytes: number[] }
+  | { type: "closed"; error?: string };
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+interface Harness {
+  daemon: TestPaseoDaemon;
+  client: DaemonClient;
+  sockets: WebSocket[];
+  close(): Promise<void>;
+}
+
+async function writePlugin(id: string, serverEntry: string): Promise<string> {
+  const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-subscriptions-"));
+  roots.push(pluginDirectory);
+  await writeFile(
+    path.join(pluginDirectory, "paseo-plugin.json"),
+    JSON.stringify({ id, requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` } }),
+  );
+  await writeFile(path.join(pluginDirectory, "index.server.ts"), serverEntry);
+  return pluginDirectory;
+}
+
+async function startHarness(): Promise<Harness> {
+  const pluginDirectory = await writePlugin(PLUGIN_ID, SERVER_ENTRY);
+  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+  const sockets: WebSocket[] = [];
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    clientId: `clid_plugin_subscriptions_${Date.now()}`,
+    appVersion: resolveDaemonVersion(import.meta.url),
+    reconnect: { enabled: true, baseDelayMs: 10, maxDelayMs: 50 },
+    webSocketFactory: (url) => {
+      const socket = new WebSocket(url);
+      sockets.push(socket);
+      return socket as unknown as WebSocketLike;
+    },
+  });
+  await client.connect();
+  await client.patchDaemonConfig({ pluginsEnabled: true });
+  await expect(client.installDirectoryPlugin(pluginDirectory)).resolves.toMatchObject({
+    id: PLUGIN_ID,
+    status: "running",
+  });
+  return {
+    daemon,
+    client,
+    sockets,
+    async close() {
+      await client.close().catch(() => undefined);
+      await daemon.close();
+    },
+  };
+}
+
+function collect(subscription: OwnedSubscription<unknown>): Received[] {
+  const received: Received[] = [];
+  subscription.subscribe({
+    snapshot: () => undefined,
+    update: (message) => {
+      if (message.type === "plugin.rpc.event")
+        received.push({ type: "event", event: message.payload.event });
+      if (message.type === "plugin.rpc.closed")
+        received.push({
+          type: "closed",
+          ...(message.payload.error ? { error: message.payload.error } : {}),
+        });
+    },
+    binary: (payload) => received.push({ type: "bytes", bytes: [...payload] }),
+  });
+  return received;
+}
+
+function watcherCount(client: DaemonClient) {
+  return client.invokePluginRpc(PLUGIN_ID, "watchers", {});
+}
+
+test("a subscription delivers JSON and binary events in order and release aborts its handler", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const json = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 3, bytes: false });
+    const jsonEvents = collect(json);
+    await json.ready;
+    const binary = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 2, bytes: true });
+    const binaryEvents = collect(binary);
+    await binary.ready;
+
+    await expect
+      .poll(() => jsonEvents)
+      .toEqual([
+        { type: "event", event: { n: 0 } },
+        { type: "event", event: { n: 1 } },
+        { type: "event", event: { n: 2 } },
+      ]);
+    await expect
+      .poll(() => binaryEvents)
+      .toEqual([
+        { type: "bytes", bytes: [0, 1] },
+        { type: "bytes", bytes: [1, 2] },
+      ]);
+    expect(json.subscriptionId).not.toBe(binary.subscriptionId);
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 2 });
+
+    await json.release();
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 1 });
+    await binary.release();
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 0 });
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("a schema transform runs once: the handler gets the parsed input and the wire carries the pushed event", async () => {
+  const harness = await startHarness();
+  try {
+    const subscription = harness.client.observePluginRpc(PLUGIN_ID, "repeated", { times: "2" });
+    const received = collect(subscription);
+    await subscription.ready;
+    // The client parses "xx" into 2; parsing it on the plugin side too would reject it.
+    await expect.poll(() => received).toEqual([{ type: "event", event: "xx" }, { type: "closed" }]);
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("dropping the connection releases subscriptions and reconnecting runs the handler again", async () => {
+  const harness = await startHarness();
+  const { client, sockets } = harness;
+  try {
+    const subscription = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 1, bytes: false });
+    const events = collect(subscription);
+    await subscription.ready;
+    await expect.poll(() => events).toEqual([{ type: "event", event: { n: 0 } }]);
+    const firstId = subscription.subscriptionId;
+
+    sockets.at(-1)!.terminate();
+    await expect
+      .poll(() => subscription.subscriptionId, { timeout: 10_000 })
+      .toSatisfy((id: unknown) => typeof id === "string" && id !== firstId);
+    await expect
+      .poll(() => events)
+      .toEqual([
+        { type: "event", event: { n: 0 } },
+        { type: "event", event: { n: 0 } },
+      ]);
+    // The first handler's signal aborted when its connection dropped; one handler runs now.
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 1 });
+    await subscription.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("a handler that throws before acknowledging rejects; one that fails later closes", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const refused = client.observePluginRpc(PLUGIN_ID, "failing", { when: "before-ack" });
+    await expect(refused.ready).rejects.toThrow("refused before acknowledging");
+
+    const later = client.observePluginRpc(PLUGIN_ID, "failing", { when: "after-ack" });
+    const events = collect(later);
+    await later.ready;
+    await expect
+      .poll(() => events)
+      .toEqual([{ type: "closed", error: "failed after acknowledging" }]);
+    await later.release();
+
+    const invalid = client.observePluginRpc(PLUGIN_ID, "ticks", { count: "many" });
+    await expect(invalid.ready).rejects.toThrow();
+    const unknown = client.observePluginRpc(PLUGIN_ID, "watchers", {});
+    await expect(unknown.ready).rejects.toThrow("does not contribute subscription watchers");
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("reloading the plugin closes its subscriptions with an error", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const subscription = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 0, bytes: false });
+    const events = collect(subscription);
+    await subscription.ready;
+    await client.reloadPlugin(PLUGIN_ID);
+    await expect
+      .poll(() => events)
+      .toEqual([{ type: "closed", error: `Plugin stopped: ${PLUGIN_ID}` }]);
+    await subscription.release();
+    // The reloaded plugin starts fresh and serves new subscriptions.
+    const again = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 1, bytes: false });
+    const againEvents = collect(again);
+    await again.ready;
+    await expect.poll(() => againEvents).toEqual([{ type: "event", event: { n: 0 } }]);
+    await again.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("RPC bytes ride as binary frames in both directions and nested bytes fail validation", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const output = await client.invokePluginRpc(PLUGIN_ID, "thumbnail", { size: 4 });
+    expect(output).toBeInstanceOf(Uint8Array);
+    expect([...(output as Uint8Array)]).toEqual([7, 7, 7, 7]);
+
+    const reversed = await client.invokePluginRpc(PLUGIN_ID, "reverse", new Uint8Array([1, 2, 3]));
+    expect([...(reversed as Uint8Array)]).toEqual([3, 2, 1]);
+
+    await expect(client.invokePluginRpc(PLUGIN_ID, "nested-output", {})).rejects.toThrow(
+      "output.data is a Uint8Array. Bytes cross the wire only as the whole value",
+    );
+    await expect(
+      client.invokePluginRpc(PLUGIN_ID, "reverse", { data: new Uint8Array(1) }),
+    ).rejects.toThrow("input.data is a Uint8Array");
+
+    const nested = client.observePluginRpc(PLUGIN_ID, "nested-push", {});
+    await nested.ready;
+    await expect
+      .poll(async () => JSON.stringify(await client.getPluginLogs(PLUGIN_ID)))
+      .toContain("event.data is a Uint8Array");
+    await nested.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("one name cannot serve both an RPC and a subscription", async () => {
+  const harness = await startHarness();
+  try {
+    const directory = await writePlugin(
+      "collision",
+      `
+import { defineRpc, defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(defineRpc({ name: "watch", input: z.object({}), output: z.null() }), () => null);
+  server.handle(
+    defineSubscription({ name: "watch", input: z.object({}), event: z.object({}) }),
+    () => undefined,
+  );
+  return () => undefined;
+}
+`,
+    );
+    await expect(harness.client.installDirectoryPlugin(directory)).rejects.toThrow(
+      "Duplicate plugin RPC method: watch",
+    );
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("plain RPC parses async input and output transforms once at the receiver", async () => {
+  const transformed = defineRpc({
+    name: "transformed",
+    input: z.object({ when: z.string().transform(async (text) => new Date(text)) }),
+    output: z.object({ n: z.string().transform(async (text) => Number(text)) }),
+  });
+
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        transformed,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        { when: "2026-01-01T00:00:00.000Z" },
+      ),
+    ).resolves.toEqual({ n: 2026 });
+  } finally {
+    await harness.close();
+  }
+});
+
+test("plain RPC applies a top-level input default in the plugin process", async () => {
+  const contract = defineRpc({
+    name: "defaulted",
+    input: z.string().default("x"),
+    output: z.string(),
+  });
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        contract,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        undefined,
+      ),
+    ).resolves.toBe("x");
+  } finally {
+    await harness.close();
+  }
+});
+
+test("plain RPC applies a top-level output default on the client", async () => {
+  const contract = defineRpc({
+    name: "defaulted-output",
+    input: z.object({}),
+    output: z.string().default("x"),
+  });
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        contract,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        {},
+      ),
+    ).resolves.toBe("x");
+  } finally {
+    await harness.close();
+  }
+}, 30_000);
diff --git a/packages/server/src/server/plugins/plugin-subscriptions.perf.e2e.test.ts b/packages/server/src/server/plugins/plugin-subscriptions.perf.e2e.test.ts
new file mode 100644
index 0000000000..7b58fbb629
--- /dev/null
+++ b/packages/server/src/server/plugins/plugin-subscriptions.perf.e2e.test.ts
@@ -0,0 +1,108 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { afterEach, expect, test } from "vitest";
+import { resolveDaemonVersion } from "../daemon-version.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+
+const PUSH_BYTES = 256 * 1024;
+const TOTAL_BYTES = 100 * 1024 * 1024;
+const PUSHES = TOTAL_BYTES / PUSH_BYTES;
+const MIN_MEGABYTES_PER_SECOND = 200;
+
+// One buffer, pushed until the total is out: what a capture loop looks like.
+const SERVER_ENTRY = `
+import { defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+const stream = defineSubscription({
+  name: "stream",
+  input: z.object({ pushes: z.number().int(), bytes: z.number().int() }),
+  event: z.instanceof(Uint8Array),
+});
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(stream, async ({ pushes, bytes }, { push, signal }) => {
+    const chunk = new Uint8Array(bytes).fill(7);
+    for (let sent = 0; sent < pushes && !signal.aborted; sent += 1) await push(chunk);
+    await new Promise((resolve) => signal.addEventListener("abort", resolve, { once: true }));
+  });
+  return () => undefined;
+}
+`;
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+test(`a plugin streams ${TOTAL_BYTES / 1024 / 1024} MiB in ${PUSH_BYTES / 1024} KiB pushes at ${MIN_MEGABYTES_PER_SECOND} MB/s without copying per frame`, async () => {
+  const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-stream-"));
+  roots.push(pluginDirectory);
+  await writeFile(
+    path.join(pluginDirectory, "paseo-plugin.json"),
+    JSON.stringify({
+      id: "stream",
+      requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` },
+    }),
+  );
+  await writeFile(path.join(pluginDirectory, "index.server.ts"), SERVER_ENTRY);
+  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    clientId: `clid_plugin_stream_${Date.now()}`,
+    appVersion: resolveDaemonVersion(import.meta.url),
+  });
+  try {
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(pluginDirectory);
+
+    let received = 0;
+    let frames = 0;
+    let copied = 0;
+    let finished!: () => void;
+    const done = new Promise<void>((resolve) => {
+      finished = resolve;
+    });
+    const baseline = process.memoryUsage().arrayBuffers;
+    let peak = baseline;
+    const started = performance.now();
+    const subscription = client.observePluginRpc("stream", "stream", {
+      pushes: PUSHES,
+      bytes: PUSH_BYTES,
+    });
+    subscription.subscribe({
+      snapshot: () => undefined,
+      update: () => undefined,
+      binary: (payload) => {
+        received += payload.byteLength;
+        frames += 1;
+        // The payload is a view into the frame the socket received, not a copy of it.
+        if (payload.buffer.byteLength - payload.byteLength > 1024) copied += 1;
+        if (frames % 40 === 0) peak = Math.max(peak, process.memoryUsage().arrayBuffers);
+        if (received >= TOTAL_BYTES) finished();
+      },
+    });
+    await done;
+    const seconds = (performance.now() - started) / 1000;
+    const megabytesPerSecond = TOTAL_BYTES / 1e6 / seconds;
+    process.stderr.write(
+      `[plugin stream] ${frames} frames, ${(TOTAL_BYTES / 1e6).toFixed(1)} MB in ${(seconds * 1000).toFixed(0)} ms: ${megabytesPerSecond.toFixed(0)} MB/s, peak external buffers +${((peak - baseline) / 1024 / 1024).toFixed(1)} MiB\n`,
+    );
+
+    expect(frames).toBe(PUSHES);
+    expect(received).toBe(TOTAL_BYTES);
+    expect(copied).toBe(0);
+    expect(megabytesPerSecond).toBeGreaterThanOrEqual(MIN_MEGABYTES_PER_SECOND);
+    // Memory held while streaming stays bounded by in-flight frames, not by the payload total.
+    expect(peak - baseline).toBeLessThan(TOTAL_BYTES / 2);
+    await subscription.release();
+  } finally {
+    await client.close().catch(() => undefined);
+    await daemon.close();
+  }
+}, 120_000);
diff --git a/packages/server/src/server/plugins/runtime-subscription.ts b/packages/server/src/server/plugins/runtime-subscription.ts
new file mode 100644
index 0000000000..25194f4348
--- /dev/null
+++ b/packages/server/src/server/plugins/runtime-subscription.ts
@@ -0,0 +1,56 @@
+/** Receives a plugin subscription's events once its owner attached. */
+export interface PluginSubscriptionSink {
+  event(event: unknown): void;
+  /** The plugin ended the subscription, or stopped. Not called after `release()`. */
+  closed(error?: string): void;
+}
+
+/** A started plugin subscription, from the daemon's side of the subprocess. */
+export interface PluginRuntimeSubscription {
+  /** Resolves when the plugin acknowledged; rejects when it refused. */
+  readonly ready: Promise<void>;
+  /** Delivers what arrived so far, then everything that follows. */
+  attach(sink: PluginSubscriptionSink): void;
+  release(): void;
+}
+
+type Pending = { type: "event"; event: unknown } | { type: "closed"; error?: string };
+
+/**
+ * Holds events until the owner attaches, so the owner can answer the subscribe request before
+ * the first event goes out.
+ */
+export class BufferedPluginSubscription {
+  private sink: PluginSubscriptionSink | null = null;
+  private pending: Pending[] = [];
+  private ended = false;
+
+  attach(sink: PluginSubscriptionSink): void {
+    if (this.sink) throw new Error("Plugin subscription is already attached");
+    this.sink = sink;
+    const pending = this.pending;
+    this.pending = [];
+    for (const entry of pending) {
+      if (entry.type === "event") sink.event(entry.event);
+      else sink.closed(entry.error);
+    }
+  }
+
+  event(event: unknown): void {
+    if (this.ended) return;
+    if (this.sink) this.sink.event(event);
+    else this.pending.push({ type: "event", event });
+  }
+
+  closed(error?: string): void {
+    if (this.ended) return;
+    this.ended = true;
+    if (this.sink) this.sink.closed(error);
+    else this.pending.push({ type: "closed", ...(error === undefined ? {} : { error }) });
+  }
+
+  released(): void {
+    this.ended = true;
+    this.pending = [];
+  }
+}
diff --git a/packages/server/src/server/plugins/runtime.posix.test.ts b/packages/server/src/server/plugins/runtime.posix.test.ts
index cfa3292567..1792a9d7ff 100644
--- a/packages/server/src/server/plugins/runtime.posix.test.ts
+++ b/packages/server/src/server/plugins/runtime.posix.test.ts
@@ -1399,6 +1399,44 @@ export default function contribute(server: { registerProvider(provider: Provider
     }
   });
 
+  it("releases a subscription in the plugin when its subscribe times out", async () => {
+    vi.useFakeTimers();
+    try {
+      const directory = await createPlugin(
+        "slow-subscribe",
+        `export default function contribute(plugin: unknown) { void plugin; return () => undefined; }`,
+      );
+      const child = createReloadChild("slow-subscribe", []);
+      const sent: Array<{ type: string; subscriptionId?: string }> = [];
+      const originalSend = child.send.bind(child);
+      child.send = (message, callback) => {
+        sent.push(message);
+        if (message.type !== "initialize") return originalSend(message, callback);
+        callback?.(null);
+        queueMicrotask(() =>
+          child.emitMessage({ type: "ready", methods: [], subscriptions: ["feed"], providers: [] }),
+        );
+        return true;
+      };
+      const runtime = createTestRuntime({ spawnChild: () => child });
+      await runtime.startPlugin("slow-subscribe", directory);
+
+      const subscription = runtime.startSubscription("slow-subscribe", "feed", {});
+      const rejection = subscription.ready.catch((error: Error) => error);
+      await vi.advanceTimersByTimeAsync(30_000);
+      await expect(rejection).resolves.toMatchObject({
+        message: expect.stringContaining("timed out"),
+      });
+      const subscribe = sent.find((message) => message.type === "subscribe");
+      expect(sent).toContainEqual({
+        type: "unsubscribe",
+        subscriptionId: subscribe?.subscriptionId,
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("escalates a plugin that ignores graceful shutdown from TERM to KILL", async () => {
     vi.useFakeTimers();
     try {
@@ -1815,7 +1853,7 @@ export function inspect() { void Surface; return {}; }`,
     await runtime.stopAll();
   });
 
-  it("rejects a handler result that does not match its RPC output schema", async () => {
+  it("forwards a handler result for the client to validate against its RPC output schema", async () => {
     const directory = await createPlugin(
       "invalid-output",
       `import { z } from "zod";
@@ -1834,7 +1872,9 @@ export default function contribute(plugin: any) {
 
     await runtime.startPlugin("invalid-output", directory);
 
-    await expect(runtime.invoke("invalid-output", "broken", {})).rejects.toThrow();
+    await expect(runtime.invoke("invalid-output", "broken", {})).resolves.toEqual({
+      value: "wrong",
+    });
     await runtime.stopAll();
   });
 
@@ -2082,7 +2122,7 @@ it.each(examples)("builds and loads the %s plugin example", async (example) => {
   const runtime = createTestRuntime(
     { settingsDirectory },
     undefined,
-    resolveDaemonVersion(import.meta.url),
+    example === "sidebar-views" ? "0.16.0" : resolveDaemonVersion(import.meta.url),
   );
   try {
     await runtime.startPlugin(example, path.join(examplesDirectory, example));
diff --git a/packages/server/src/server/plugins/runtime.ts b/packages/server/src/server/plugins/runtime.ts
index 31f313cb7f..98cbf8fcf0 100644
--- a/packages/server/src/server/plugins/runtime.ts
+++ b/packages/server/src/server/plugins/runtime.ts
@@ -34,6 +34,10 @@ import type {
   PluginUsageSourceMetadata,
 } from "./plugin-process-protocol.js";
 import { PluginProcessMessageSchema } from "./plugin-process-protocol.js";
+import {
+  BufferedPluginSubscription,
+  type PluginRuntimeSubscription,
+} from "./runtime-subscription.js";
 import { PluginSessionSocket } from "./session-socket.js";
 import { InternalPluginChild } from "./internal-child.js";
 import { evaluateBundle } from "./bundle-evaluator.js";
@@ -75,6 +79,8 @@ interface LoadedPlugin {
   /** Lets a client that already holds this bundle skip downloading it again. */
   clientBundleHash: string;
   methods: ReadonlySet<string>;
+  subscriptionMethods: ReadonlySet<string>;
+  subscriptions: Map<string, BufferedPluginSubscription>;
   hooks: string[];
   providers: readonly PluginProviderMetadata[];
   usageSources: readonly PluginUsageSourceMetadata[];
@@ -514,6 +520,40 @@ export class PluginRuntime {
     return this.request(loaded, { type: "invoke", requestId: randomUUID(), method, input });
   }
 
+  /** Starts one subscriber's handler in the plugin process. */
+  startSubscription(pluginId: string, method: string, input: unknown): PluginRuntimeSubscription {
+    const loaded = this.plugins.get(pluginId);
+    if (!loaded) throw new Error(`Plugin is not available: ${pluginId}`);
+    if (!loaded.subscriptionMethods.has(method))
+      throw new Error(`Plugin ${pluginId} does not contribute subscription ${method}`);
+    const subscriptionId = randomUUID();
+    const subscription = new BufferedPluginSubscription();
+    loaded.subscriptions.set(subscriptionId, subscription);
+    const ready = this.request(loaded, {
+      type: "subscribe",
+      requestId: randomUUID(),
+      subscriptionId,
+      method,
+      input,
+    }).then(
+      () => undefined,
+      (error: unknown) => {
+        loaded.subscriptions.delete(subscriptionId);
+        throw error;
+      },
+    );
+    return {
+      ready,
+      attach: (sink) => subscription.attach(sink),
+      release: () => {
+        subscription.released();
+        if (!loaded.subscriptions.delete(subscriptionId)) return;
+        if (loaded.child?.connected)
+          void send(loaded.child, { type: "unsubscribe", subscriptionId }).catch(() => undefined);
+      },
+    };
+  }
+
   emit<Name extends keyof PluginHookEvents>(name: Name, event: PluginHookEvents[Name]): void {
     for (const loaded of this.plugins.values()) {
       if (!loaded.hooks.includes(name)) {
@@ -727,6 +767,11 @@ export class PluginRuntime {
           if (message.type === "hook") {
             void send(child, { type: "hook.cancel", requestId }).catch(() => {});
           }
+          // The handler may still start after the daemon gave up on it.
+          if (message.type === "subscribe") {
+            const { subscriptionId } = message;
+            void send(child, { type: "unsubscribe", subscriptionId }).catch(() => {});
+          }
           reject(new Error(`Plugin RPC timed out: ${pluginId}.${message.type}`));
         },
         message.type === "tool.call" ? TOOL_CALL_TIMEOUT_MS : REQUEST_TIMEOUT_MS,
@@ -781,6 +826,8 @@ export class PluginRuntime {
         clientBundleHash: hashClientBundle(clientBundle),
         requirements: manifest.requirements,
         methods: new Set(),
+        subscriptionMethods: new Set(),
+        subscriptions: new Map(),
         hooks: [],
         providers: [],
         usageSources: [],
@@ -911,6 +958,8 @@ export class PluginRuntime {
       clientBundleHash: hashClientBundle(clientBundle),
       requirements,
       methods: new Set(ready.methods),
+      subscriptionMethods: new Set(ready.subscriptions ?? []),
+      subscriptions: new Map(),
       hooks: ready.hooks ?? [],
       providers: ready.providers ?? [],
       usageSources: ready.usageSources ?? [],
@@ -1009,6 +1058,16 @@ export class PluginRuntime {
       this.handleProviderMessage(loaded, message);
       return;
     }
+    if (message.type === "subscription.event") {
+      loaded.subscriptions.get(message.subscriptionId)?.event(message.event);
+      return;
+    }
+    if (message.type === "subscription.closed") {
+      const subscription = loaded.subscriptions.get(message.subscriptionId);
+      loaded.subscriptions.delete(message.subscriptionId);
+      subscription?.closed(message.error);
+      return;
+    }
     if (message.type !== "result" && message.type !== "error") return;
     const pending = loaded.pending.get(message.requestId);
     if (!pending) return;
@@ -1367,12 +1426,16 @@ export class PluginRuntime {
     this.appendLog(loaded.id, "stdout", "[paseo] Plugin stopped");
   }
 
+  /** Rejects in-flight requests and closes open subscriptions with the reason. */
   private rejectPending(loaded: LoadedPlugin, message: string): void {
     for (const invocation of loaded.pending.values()) {
       clearTimeout(invocation.timeout);
       invocation.reject(new Error(message));
     }
     loaded.pending.clear();
+    const subscriptions = [...loaded.subscriptions.values()];
+    loaded.subscriptions.clear();
+    for (const subscription of subscriptions) subscription.closed(message);
   }
 
   private appendLog(pluginId: string, stream: PluginLogEntry["stream"], message: string): void {
diff --git a/packages/server/src/server/plugins/settings/index.test.ts b/packages/server/src/server/plugins/settings/index.test.ts
index de81919eae..f47a8fb6ba 100644
--- a/packages/server/src/server/plugins/settings/index.test.ts
+++ b/packages/server/src/server/plugins/settings/index.test.ts
@@ -175,3 +175,11 @@ test("installation namespaces and definition IDs remain separate", async () => {
   expect(() => store.register(definition)).toThrow("Duplicate settings");
   expect(() => store.register({ ...definition, id: "../escape" })).toThrow("Invalid settings ID");
 });
+
+test("device-scoped settings are owned by the client", async () => {
+  const { directory } = await setup();
+  const store = new PluginSettingsStore(directory, () => {});
+  expect(() => store.register(defineSettings({ ...definition, scope: "device" }))).toThrow(
+    "Device settings belong to the client",
+  );
+});
diff --git a/packages/server/src/server/plugins/settings/index.ts b/packages/server/src/server/plugins/settings/index.ts
index 775a47f6a4..683eb3ab82 100644
--- a/packages/server/src/server/plugins/settings/index.ts
+++ b/packages/server/src/server/plugins/settings/index.ts
@@ -45,6 +45,7 @@ export class PluginSettingsStore {
 
   register<Schema extends ZodType>(definition: SettingsDefinition<Schema>) {
     defineSettings(definition);
+    if (definition.scope !== "host") throw new Error("Device settings belong to the client");
     if (this.definitions.has(definition.id))
       throw new Error(`Duplicate settings: ${definition.id}`);
     this.definitions.set(definition.id, definition);
diff --git a/packages/server/src/server/plugins/subscription-handlers.test.ts b/packages/server/src/server/plugins/subscription-handlers.test.ts
new file mode 100644
index 0000000000..ed8b881a8f
--- /dev/null
+++ b/packages/server/src/server/plugins/subscription-handlers.test.ts
@@ -0,0 +1,55 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
+import type { PluginSubscriptionContext } from "@getpaseo/plugin/server";
+import type { PaseoApi } from "@getpaseo/client";
+import { expect, test } from "vitest";
+import { z } from "zod";
+import type { PluginProcessMessage } from "./plugin-process-protocol.js";
+import { PluginSubscriptionHandlers } from "./subscription-handlers.js";
+
+const lengths = defineSubscription({
+  name: "lengths",
+  input: z.object({ times: z.string().transform(Number) }),
+  event: z.string().transform((text) => text.length),
+});
+
+/** The plugin process's handlers wired to the client helper through the channel between them. */
+function connect(handler: (input: unknown, context: PluginSubscriptionContext) => unknown) {
+  const handlers = new PluginSubscriptionHandlers({
+    send: (message) => deliver(message),
+    sendAndWait: async (message) => deliver(message),
+  });
+  handlers.register(lengths, handler);
+  let observer: Parameters<Parameters<typeof subscribePluginRpc>[1]>[2] | null = null;
+  function deliver(message: PluginProcessMessage) {
+    if (message.type === "subscription.event") observer?.event(message.event);
+    if (message.type === "subscription.closed") observer?.closed();
+  }
+  return (method: string, input: unknown, next: NonNullable<typeof observer>) => {
+    observer = next;
+    handlers.start(
+      { type: "subscribe", requestId: "r", subscriptionId: "s", method, input },
+      {} as PaseoApi,
+    );
+    return Object.assign(() => handlers.release("s"), {
+      ready: Promise.resolve(),
+      release: async () => handlers.release("s"),
+    });
+  };
+}
+
+test("an event schema that transforms is applied once, on the receiving side", async () => {
+  const handled: unknown[] = [];
+  const received: number[] = [];
+  const closed: unknown[] = [];
+  const subscribe = connect(async (input, { push }) => {
+    handled.push(input);
+    await push("abc");
+  });
+  subscribePluginRpc(lengths, subscribe, { times: "2" }, (length) => received.push(length), {
+    onClosed: (result) => closed.push(result),
+  });
+  await expect.poll(() => received).toEqual([3]);
+  expect(handled).toEqual([{ times: 2 }]);
+  expect(closed).toEqual([{}]);
+});
diff --git a/packages/server/src/server/plugins/subscription-handlers.ts b/packages/server/src/server/plugins/subscription-handlers.ts
new file mode 100644
index 0000000000..1d2c4fefdb
--- /dev/null
+++ b/packages/server/src/server/plugins/subscription-handlers.ts
@@ -0,0 +1,132 @@
+import type { PluginSubscriptionContract } from "@getpaseo/plugin";
+import type { PluginSubscriptionContext } from "@getpaseo/plugin/server";
+import type { PaseoApi } from "@getpaseo/client";
+import { assertPluginWireValue } from "@getpaseo/protocol/binary-frames/index";
+import type { PluginProcessMessage, PluginProcessRequest } from "./plugin-process-protocol.js";
+
+export type PluginSubscriptionHandler = (
+  input: unknown,
+  context: PluginSubscriptionContext,
+) => unknown;
+
+interface ActiveSubscription {
+  controller: AbortController;
+}
+
+interface SubscriptionChannel {
+  send(message: PluginProcessMessage): void;
+  sendAndWait(message: PluginProcessMessage): Promise<void>;
+}
+
+type SubscribeRequest = Extract<PluginProcessRequest, { type: "subscribe" }>;
+
+/**
+ * The plugin subprocess side of subscriptions: one handler call per subscriber, an abort signal
+ * that fires on release, and `push` that validates each event and resolves when it left the
+ * process.
+ */
+export class PluginSubscriptionHandlers {
+  private readonly registered = new Map<
+    string,
+    { contract: PluginSubscriptionContract; handler: PluginSubscriptionHandler }
+  >();
+  private readonly active = new Map<string, ActiveSubscription>();
+  private readonly channel: SubscriptionChannel;
+
+  constructor(channel: SubscriptionChannel) {
+    this.channel = channel;
+  }
+
+  has(name: string): boolean {
+    return this.registered.has(name);
+  }
+
+  register(contract: PluginSubscriptionContract, handler: PluginSubscriptionHandler): void {
+    this.registered.set(contract.name, { contract, handler });
+  }
+
+  catalog(): string[] {
+    return [...this.registered.keys()].sort();
+  }
+
+  start(message: SubscribeRequest, paseo: PaseoApi): void {
+    const { requestId, subscriptionId } = message;
+    const registered = this.registered.get(message.method);
+    if (!registered) {
+      this.channel.send({
+        type: "error",
+        requestId,
+        error: `Unknown subscription: ${message.method}`,
+      });
+      return;
+    }
+    const parsed = registered.contract.input.safeParse(message.input);
+    if (!parsed.success) {
+      this.channel.send({
+        type: "error",
+        requestId,
+        error: `Invalid input for ${message.method}: ${parsed.error.message}`,
+      });
+      return;
+    }
+    const controller = new AbortController();
+    const { signal } = controller;
+    let acknowledge = () => {};
+    const acknowledged = new Promise<void>((resolve) => {
+      acknowledge = resolve;
+    });
+    const push = async (event: unknown): Promise<void> => {
+      if (signal.aborted) return;
+      // The receiver parses into the schema's output; sending that output would parse it twice.
+      registered.contract.event.parse(event);
+      assertPluginWireValue(event, "event");
+      // Events pushed while the handler runs follow the acknowledgement.
+      await acknowledged;
+      if (signal.aborted) return;
+      await this.channel.sendAndWait({ type: "subscription.event", subscriptionId, event });
+    };
+    this.active.set(subscriptionId, { controller });
+    let result: unknown;
+    try {
+      result = registered.handler(parsed.data, { paseo, push, signal });
+    } catch (error) {
+      this.active.delete(subscriptionId);
+      controller.abort();
+      this.channel.send({ type: "error", requestId, error: describeError(error) });
+      return;
+    }
+    this.channel.send({ type: "result", requestId, output: null });
+    acknowledge();
+    if (result instanceof Promise)
+      result.then(
+        () => this.close(subscriptionId),
+        (error: unknown) => this.close(subscriptionId, describeError(error)),
+      );
+  }
+
+  /** The daemon released the subscription; it needs no closed message back. */
+  release(subscriptionId: string): void {
+    const active = this.active.get(subscriptionId);
+    if (!active) return;
+    this.active.delete(subscriptionId);
+    active.controller.abort();
+  }
+
+  releaseAll(): void {
+    for (const subscriptionId of this.active.keys()) this.release(subscriptionId);
+  }
+
+  private close(subscriptionId: string, error?: string): void {
+    if (!this.active.has(subscriptionId)) return;
+    this.release(subscriptionId);
+    this.channel.send({
+      type: "subscription.closed",
+      subscriptionId,
+      ...(error === undefined ? {} : { error }),
+    });
+  }
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
diff --git a/packages/server/src/server/project-suggestions.test.ts b/packages/server/src/server/project-suggestions.test.ts
new file mode 100644
index 0000000000..d637ee2ea1
--- /dev/null
+++ b/packages/server/src/server/project-suggestions.test.ts
@@ -0,0 +1,188 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createTestLogger } from "../test-utils/test-logger.js";
+import type {
+  AgentManager,
+  ImportableSessionProviderError,
+  ManagedImportableProviderSession,
+} from "./agent/agent-manager.js";
+import { listProjectSuggestions } from "./project-suggestions.js";
+import { WorkspaceGitServiceImpl } from "./workspace-git-service.js";
+import type { PersistedProjectRecord } from "./workspace-registry.js";
+
+const NOW = new Date("2026-10-31T12:00:00.000Z");
+
+function daysAgo(days: number): Date {
+  return new Date(NOW.getTime() - days * 24 * 60 * 60 * 1000);
+}
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function createRepo(root: string, name: string): string {
+  const repo = path.join(root, name);
+  mkdirSync(repo, { recursive: true });
+  git(repo, "init", "-b", "main");
+  git(repo, "config", "user.email", "test@example.com");
+  git(repo, "config", "user.name", "Test");
+  writeFileSync(path.join(repo, "README.md"), "hello\n");
+  git(repo, "add", ".");
+  git(repo, "commit", "-m", "init");
+  return repo;
+}
+
+function session(
+  provider: string,
+  cwd: string,
+  lastActivityAt: Date,
+): ManagedImportableProviderSession {
+  return {
+    provider,
+    providerHandleId: `${provider}-${cwd}-${lastActivityAt.toISOString()}`,
+    cwd,
+    title: null,
+    firstPromptPreview: "Fix the build",
+    lastPromptPreview: null,
+    lastActivityAt,
+  };
+}
+
+/** Agent history as the providers report it. */
+function agentHistory(
+  sessions: ManagedImportableProviderSession[],
+  providerErrors: ImportableSessionProviderError[] = [],
+): Pick<AgentManager, "listImportableSessions"> {
+  return {
+    listImportableSessions: async (options) => ({
+      sessions: sessions.filter(
+        (entry) => !options?.providerFilter || options.providerFilter.has(entry.provider),
+      ),
+      providerErrors,
+    }),
+  };
+}
+
+function projects(...rootPaths: Array<{ rootPath: string; archived?: boolean }>) {
+  const records = rootPaths.map(
+    ({ rootPath, archived }, index): PersistedProjectRecord => ({
+      projectId: `project-${index}`,
+      rootPath,
+      kind: "git",
+      displayName: path.basename(rootPath),
+      projectKey: null,
+      customName: null,
+      createdAt: NOW.toISOString(),
+      updatedAt: NOW.toISOString(),
+      archivedAt: archived ? NOW.toISOString() : null,
+    }),
+  );
+  return { list: async () => records };
+}
+
+describe("listProjectSuggestions", () => {
+  let root: string;
+  let gitService: WorkspaceGitServiceImpl;
+
+  beforeEach(() => {
+    // The native realpath expands Windows short names (RUNNER~1), which git reports in full.
+    root = realpathSync.native(mkdtempSync(path.join(tmpdir(), "project-suggestions-")));
+    gitService = new WorkspaceGitServiceImpl({
+      logger: createTestLogger(),
+      paseoHome: path.join(root, ".paseo"),
+    });
+  });
+
+  afterEach(async () => {
+    await gitService.dispose();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("groups sessions in a repo, its subdirectories and its worktrees under the main checkout", async () => {
+    const app = createRepo(root, "app");
+    mkdirSync(path.join(app, "packages", "web"), { recursive: true });
+    const worktree = path.join(root, "codex-worktrees", "app-feature");
+    git(app, "worktree", "add", "-b", "feature", worktree);
+
+    const result = await listProjectSuggestions({
+      request: {},
+      agentManager: agentHistory([
+        session("claude", app, daysAgo(1)),
+        session("claude", path.join(app, "packages", "web"), daysAgo(2)),
+        session("codex", worktree, daysAgo(3)),
+      ]),
+      projectRegistry: projects(),
+      workspaceGitService: gitService,
+      now: NOW,
+    });
+
+    expect(result).toEqual({
+      suggestions: [
+        {
+          rootPath: app,
+          displayName: "app",
+          sessionCount: 3,
+          providerIds: ["claude", "codex"],
+          lastActivityAt: daysAgo(1).toISOString(),
+        },
+      ],
+      providerErrors: [],
+    });
+  });
+
+  test("leaves out active projects, deleted folders, old sessions and the home directory", async () => {
+    const added = createRepo(root, "already-added");
+    const removed = createRepo(root, "removed-project");
+    const notes = path.join(root, "notes");
+    mkdirSync(notes);
+
+    const result = await listProjectSuggestions({
+      request: {},
+      agentManager: agentHistory([
+        session("claude", added, daysAgo(1)),
+        session("claude", removed, daysAgo(2)),
+        session("claude", notes, daysAgo(4)),
+        session("claude", path.join(root, "deleted"), daysAgo(1)),
+        session("claude", createRepo(root, "stale"), daysAgo(45)),
+        session("claude", homedir(), daysAgo(1)),
+      ]),
+      projectRegistry: projects({ rootPath: added }, { rootPath: removed, archived: true }),
+      workspaceGitService: gitService,
+      now: NOW,
+    });
+
+    expect(result.suggestions.map((suggestion) => suggestion.rootPath)).toEqual([removed, notes]);
+  });
+
+  test("reads only the requested providers and reports the ones that failed", async () => {
+    const app = createRepo(root, "app");
+    const api = createRepo(root, "api");
+
+    const result = await listProjectSuggestions({
+      request: { providers: ["codex"] },
+      agentManager: agentHistory(
+        [session("claude", app, daysAgo(1)), session("codex", api, daysAgo(1))],
+        [{ provider: "codex", message: "Timed out listing sessions" }],
+      ),
+      projectRegistry: projects(),
+      workspaceGitService: gitService,
+      now: NOW,
+    });
+
+    expect(result).toEqual({
+      suggestions: [
+        {
+          rootPath: api,
+          displayName: "api",
+          sessionCount: 1,
+          providerIds: ["codex"],
+          lastActivityAt: daysAgo(1).toISOString(),
+        },
+      ],
+      providerErrors: [{ provider: "codex", message: "Timed out listing sessions" }],
+    });
+  });
+});
diff --git a/packages/server/src/server/project-suggestions.ts b/packages/server/src/server/project-suggestions.ts
new file mode 100644
index 0000000000..4ad73585de
--- /dev/null
+++ b/packages/server/src/server/project-suggestions.ts
@@ -0,0 +1,177 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, parse, resolve } from "node:path";
+import pLimit from "p-limit";
+import type { ProjectSuggestion, ProjectSuggestionsRequest } from "@getpaseo/protocol/messages";
+import type { AgentManager, ManagedImportableProviderSession } from "./agent/agent-manager.js";
+import { isMetadataGenerationSession } from "./agent/import-sessions.js";
+import type { WorkspaceGitService } from "./workspace-git-service.js";
+import type { ProjectRegistry } from "./workspace-registry.js";
+import { normalizePathForIdentity } from "../utils/path.js";
+
+const DEFAULT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_LIMIT = 20;
+// Sessions read per provider. Enough history to find every repo used in the window.
+const SESSION_SCAN_LIMIT = 500;
+const CHECKOUT_READ_CONCURRENCY = 8;
+
+export class ProjectSuggestionsRequestError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ProjectSuggestionsRequestError";
+  }
+}
+
+export interface ListProjectSuggestionsInput {
+  request: Pick<ProjectSuggestionsRequest, "providers" | "since" | "limit">;
+  agentManager: Pick<AgentManager, "listImportableSessions">;
+  projectRegistry: Pick<ProjectRegistry, "list">;
+  workspaceGitService: Pick<WorkspaceGitService, "getCheckout">;
+  now?: Date;
+}
+
+export interface ListProjectSuggestionsResult {
+  suggestions: ProjectSuggestion[];
+  providerErrors: Array<{ provider: string; message: string }>;
+}
+
+/**
+ * Turns the agent sessions a user already ran into projects they could add. Sessions are grouped
+ * by repository: a session in a subdirectory or in any worktree counts toward the main checkout,
+ * because that is the path a project is keyed by.
+ */
+export async function listProjectSuggestions(
+  input: ListProjectSuggestionsInput,
+): Promise<ListProjectSuggestionsResult> {
+  const now = input.now ?? new Date();
+  const since = parseSince(input.request.since, now);
+  const listing = await input.agentManager.listImportableSessions({
+    limit: SESSION_SCAN_LIMIT,
+    scanLimit: SESSION_SCAN_LIMIT,
+    providerFilter: input.request.providers ? new Set(input.request.providers) : undefined,
+  });
+  const sessions = listing.sessions.filter(
+    (session) => session.lastActivityAt.getTime() >= since && !isMetadataGenerationSession(session),
+  );
+
+  const rootByCwd = await resolveProjectRoots(
+    new Set(sessions.map((session) => resolve(session.cwd))),
+    input.workspaceGitService,
+  );
+  const excludedRoots = await collectExcludedRoots(input.projectRegistry);
+  const groups = new Map<string, SuggestionGroup>();
+  for (const session of sessions) {
+    const rootPath = rootByCwd.get(resolve(session.cwd));
+    if (!rootPath || excludedRoots.has(normalizePathForIdentity(rootPath))) {
+      continue;
+    }
+    addSession(groups, rootPath, session);
+  }
+
+  const suggestions = Array.from(groups.values())
+    .sort((a, b) => b.lastActivityAt - a.lastActivityAt)
+    .slice(0, input.request.limit ?? DEFAULT_LIMIT)
+    .map(toSuggestion);
+  return { suggestions, providerErrors: listing.providerErrors };
+}
+
+interface SuggestionGroup {
+  rootPath: string;
+  sessionCount: number;
+  providerIds: Set<string>;
+  lastActivityAt: number;
+}
+
+function parseSince(since: string | undefined, now: Date): number {
+  if (!since) {
+    return now.getTime() - DEFAULT_WINDOW_MS;
+  }
+  const timestamp = Date.parse(since);
+  if (Number.isNaN(timestamp)) {
+    throw new ProjectSuggestionsRequestError("invalid_since", `Invalid since timestamp: ${since}`);
+  }
+  return timestamp;
+}
+
+/** Maps each session cwd to the folder a project would be added at, or null when it is gone. */
+async function resolveProjectRoots(
+  cwds: Set<string>,
+  workspaceGitService: Pick<WorkspaceGitService, "getCheckout">,
+): Promise<Map<string, string | null>> {
+  const limit = pLimit(CHECKOUT_READ_CONCURRENCY);
+  const entries = await Promise.all(
+    Array.from(cwds, (cwd) =>
+      limit(async () => [cwd, await resolveProjectRoot(cwd, workspaceGitService)] as const),
+    ),
+  );
+  return new Map(entries);
+}
+
+async function resolveProjectRoot(
+  cwd: string,
+  workspaceGitService: Pick<WorkspaceGitService, "getCheckout">,
+): Promise<string | null> {
+  if (!(await isDirectory(cwd))) {
+    return null;
+  }
+  const checkout = await workspaceGitService.getCheckout(cwd);
+  // Git reports Windows roots with forward slashes; resolve to the form project.add keys by.
+  const rootPath = resolve(checkout.mainRepoRoot ?? checkout.worktreeRoot ?? cwd);
+  if (rootPath !== cwd && !(await isDirectory(rootPath))) {
+    return null;
+  }
+  return rootPath;
+}
+
+/** Active projects are already added; the home directory and filesystem root are not projects. */
+async function collectExcludedRoots(
+  projectRegistry: Pick<ProjectRegistry, "list">,
+): Promise<Set<string>> {
+  const home = homedir();
+  const excluded = new Set([home, parse(home).root].map(normalizePathForIdentity));
+  for (const project of await projectRegistry.list()) {
+    if (!project.archivedAt) {
+      excluded.add(normalizePathForIdentity(project.rootPath));
+    }
+  }
+  return excluded;
+}
+
+function addSession(
+  groups: Map<string, SuggestionGroup>,
+  rootPath: string,
+  session: ManagedImportableProviderSession,
+): void {
+  const key = normalizePathForIdentity(rootPath);
+  const group = groups.get(key) ?? {
+    rootPath,
+    sessionCount: 0,
+    providerIds: new Set<string>(),
+    lastActivityAt: 0,
+  };
+  group.sessionCount += 1;
+  group.providerIds.add(session.provider);
+  group.lastActivityAt = Math.max(group.lastActivityAt, session.lastActivityAt.getTime());
+  groups.set(key, group);
+}
+
+function toSuggestion(group: SuggestionGroup): ProjectSuggestion {
+  return {
+    rootPath: group.rootPath,
+    displayName: basename(group.rootPath) || group.rootPath,
+    sessionCount: group.sessionCount,
+    providerIds: Array.from(group.providerIds).sort(),
+    lastActivityAt: new Date(group.lastActivityAt).toISOString(),
+  };
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
diff --git a/packages/server/src/server/record-patch.ts b/packages/server/src/server/record-patch.ts
new file mode 100644
index 0000000000..490ad0b6b0
--- /dev/null
+++ b/packages/server/src/server/record-patch.ts
@@ -0,0 +1,15 @@
+/** Top-level keys replace; a null value removes the key. */
+export function applyRecordPatch<Value>(
+  record: Record<string, Value>,
+  patch: Record<string, Value | null>,
+): Record<string, Value> {
+  const next = { ...record };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete next[key];
+    } else {
+      next[key] = value;
+    }
+  }
+  return next;
+}
diff --git a/packages/server/src/server/resolve-workspace-id-for-path.test.ts b/packages/server/src/server/resolve-workspace-id-for-path.test.ts
index 162fdf1c5a..763e7d5352 100644
--- a/packages/server/src/server/resolve-workspace-id-for-path.test.ts
+++ b/packages/server/src/server/resolve-workspace-id-for-path.test.ts
@@ -46,6 +46,30 @@ describe("resolveWorkspaceIdForPath", () => {
     ).toEqual("ws-archived");
   });
 
+  test("prefers the reopened active workspace to archived history at the same path", () => {
+    const archived = createWorkspaceRecord("/workspace/project", "old", {
+      archivedAt: "2026-03-05T00:00:00.000Z",
+    });
+    const active = createWorkspaceRecord("/workspace/project", "current");
+    for (const records of [
+      [archived, active],
+      [active, archived],
+    ]) {
+      expect(resolveWorkspaceIdForPath("/workspace/project", records)).toBe("current");
+    }
+  });
+
+  test("prefers an archived exact match to an active enclosing directory", () => {
+    expect(
+      resolveWorkspaceIdForPath("/workspace/project/sub", [
+        createWorkspaceRecord("/workspace/project", "parent"),
+        createWorkspaceRecord("/workspace/project/sub", "archived-child", {
+          archivedAt: "2026-03-05T00:00:00.000Z",
+        }),
+      ]),
+    ).toBe("archived-child");
+  });
+
   test("resolves the deepest enclosing workspace for a subdirectory path", () => {
     expect(
       resolveWorkspaceIdForPath("/workspace/project/packages/app", [
diff --git a/packages/server/src/server/resolve-workspace-id-for-path.ts b/packages/server/src/server/resolve-workspace-id-for-path.ts
index 58b7572cff..027f0b15b6 100644
--- a/packages/server/src/server/resolve-workspace-id-for-path.ts
+++ b/packages/server/src/server/resolve-workspace-id-for-path.ts
@@ -12,7 +12,7 @@ import type { PersistedWorkspaceRecord } from "./workspace-registry.js";
 // agents under a workspace — those are keyed by `workspaceId`, and git facts
 // derive from a workspace's OWN cwd (id → cwd).
 //
-// Resolution: an exact directory match wins; otherwise the deepest enclosing
+// Resolution: active exact match, archived exact match, then the deepest enclosing
 // workspace directory, never the home directory; null when nothing encloses it.
 export function resolveWorkspaceIdForPath(
   cwd: string,
@@ -20,7 +20,10 @@ export function resolveWorkspaceIdForPath(
 ): string | null {
   const workspaceRecords = Array.from(workspaces);
   const resolvedCwd = resolve(cwd);
-  const exactMatch = workspaceRecords.find((workspace) => resolve(workspace.cwd) === resolvedCwd);
+  const exactMatches = workspaceRecords.filter(
+    (workspace) => resolve(workspace.cwd) === resolvedCwd,
+  );
+  const exactMatch = exactMatches.find((workspace) => !workspace.archivedAt) ?? exactMatches[0];
   if (exactMatch) {
     return exactMatch.workspaceId;
   }
diff --git a/packages/server/src/server/schedule/cron.test.ts b/packages/server/src/server/schedule/cron.test.ts
index 9d4172ff27..da8d9760ed 100644
--- a/packages/server/src/server/schedule/cron.test.ts
+++ b/packages/server/src/server/schedule/cron.test.ts
@@ -20,6 +20,37 @@ describe("schedule cron cadence", () => {
     expect(next.toISOString()).toBe("2026-01-05T09:15:00.000Z");
   });
 
+  test("matches either restricted day field", () => {
+    const next = computeNextRunAt(
+      { type: "cron", expression: "0 9 1 * 1" },
+      new Date("2026-10-17T00:00:00.000Z"),
+    );
+
+    expect(next.toISOString()).toBe("2026-10-19T09:00:00.000Z");
+  });
+
+  test.each([
+    ["0 9 1 * 1", "2026-10-30T10:00:00.000Z", "2026-11-01T09:00:00.000Z"],
+    ["0 9 1 * *", "2026-10-17T00:00:00.000Z", "2026-11-01T09:00:00.000Z"],
+    ["0 9 * * 1", "2026-10-17T00:00:00.000Z", "2026-10-19T09:00:00.000Z"],
+    ["0 9 */2 * 1", "2026-10-19T09:00:00.000Z", "2026-11-09T09:00:00.000Z"],
+    ["0 9 1-31 * 1", "2026-10-17T00:00:00.000Z", "2026-10-17T09:00:00.000Z"],
+    ["0 9 1,15 * 5", "2026-10-17T00:00:00.000Z", "2026-10-23T09:00:00.000Z"],
+  ])("honors day-field semantics for %s", (expression, after, expected) => {
+    const next = computeNextRunAt({ type: "cron", expression }, new Date(after));
+
+    expect(next.toISOString()).toBe(expected);
+  });
+
+  test("matches either restricted day field in the schedule's time zone", () => {
+    const next = computeNextRunAt(
+      { type: "cron", expression: "0 9 1 * 1", timezone: "America/New_York" },
+      new Date("2026-10-17T00:00:00.000Z"),
+    );
+
+    expect(next.toISOString()).toBe("2026-10-19T13:00:00.000Z");
+  });
+
   test("computes timezone cron matches at the requested wall-clock time", () => {
     const winter = computeNextRunAt(
       { type: "cron", expression: "0 9 * * 1-5", timezone: "America/New_York" },
diff --git a/packages/server/src/server/schedule/cron.ts b/packages/server/src/server/schedule/cron.ts
index 2ac2e78972..972289322d 100644
--- a/packages/server/src/server/schedule/cron.ts
+++ b/packages/server/src/server/schedule/cron.ts
@@ -1,4 +1,7 @@
-import { parseCronExpression } from "@getpaseo/protocol/schedule/cron-expression";
+import {
+  parseCronExpression,
+  validateCronExpression,
+} from "@getpaseo/protocol/schedule/cron-expression";
 import type { ScheduleCadence } from "@getpaseo/protocol/schedule/types";
 
 interface CronDateParts {
@@ -78,7 +81,10 @@ function createCronDatePartsReader(timeZone: string | undefined): (date: Date) =
 
 export function validateScheduleCadence(cadence: ScheduleCadence): void {
   if (cadence.type === "cron") {
-    parseCronExpression(cadence.expression);
+    const error = validateCronExpression(cadence.expression);
+    if (error) {
+      throw new Error(error);
+    }
     if (cadence.timezone !== undefined) {
       assertValidTimeZone(cadence.timezone);
     }
@@ -93,19 +99,24 @@ export function computeNextRunAt(cadence: ScheduleCadence, after: Date): Date {
   }
 
   const cron = parseCronExpression(cadence.expression);
+  const hasWildcardDay = cron.dayOfMonth.isWildcard || cron.dayOfWeek.isWildcard;
   const readDateParts = createCronDatePartsReader(cadence.timezone);
   const limit = 366 * 24 * 60;
   let cursor = startOfNextMinute(after);
 
   for (let index = 0; index < limit; index += 1) {
     const { minute, hour, dayOfMonth, month, dayOfWeek } = readDateParts(cursor);
+    const dayOfMonthMatches = cron.dayOfMonth.matches(dayOfMonth);
+    const dayOfWeekMatches = cron.dayOfWeek.matches(dayOfWeek);
+    const bothDaysMatch = dayOfMonthMatches && dayOfWeekMatches;
+    const eitherDayMatches = dayOfMonthMatches || dayOfWeekMatches;
+    const dayMatches = hasWildcardDay ? bothDaysMatch : eitherDayMatches;
 
     if (
       cron.minute.matches(minute) &&
       cron.hour.matches(hour) &&
-      cron.dayOfMonth.matches(dayOfMonth) &&
       cron.month.matches(month) &&
-      cron.dayOfWeek.matches(dayOfWeek)
+      dayMatches
     ) {
       return cursor;
     }
diff --git a/packages/server/src/server/schedule/service.test.ts b/packages/server/src/server/schedule/service.test.ts
index 1a9f0f5fd4..5f185676a8 100644
--- a/packages/server/src/server/schedule/service.test.ts
+++ b/packages/server/src/server/schedule/service.test.ts
@@ -88,7 +88,7 @@ const NO_UNATTENDED_SCHEDULE_POLICY: Pick<ProviderSnapshotManager, "resolveCreat
   async resolveCreateConfig(input) {
     return {
       modeId: input.unattended ? input.requestedMode : "interactive",
-      featureValues: input.featureValues,
+      providerOptions: input.providerOptions,
     };
   },
 };
@@ -257,9 +257,9 @@ async function createRegistryBackedScheduleWorkspaceDeps(rootDir: string): Promi
               agentManager,
               agentStorage,
               findWorkspaceIdForCwd: async (cwd) =>
-                resolveWorkspaceIdForPath(cwd, await workspaceRegistry.list()),
+                resolveWorkspaceIdForPath(cwd, await workspaceRegistry.listAll()),
               listActiveWorkspaces: async () =>
-                (await workspaceRegistry.list())
+                (await workspaceRegistry.listAll())
                   .filter((workspace) => !workspace.archivedAt)
                   .map((workspace) => ({
                     workspaceId: workspace.workspaceId,
@@ -828,7 +828,7 @@ describe("ScheduleService", () => {
       model: "test-model",
       cwd: tempDir,
     });
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
   });
 
   test("archiveOnFinish=false local runs create one active workspace per run", async () => {
@@ -885,7 +885,7 @@ describe("ScheduleService", () => {
     expect(firstAgent?.workspaceId).not.toBe(secondAgent?.workspaceId);
     expect(firstAgent?.archivedAt ?? null).toBeNull();
     expect(secondAgent?.archivedAt ?? null).toBeNull();
-    expect(await workspaceRegistry.list()).toEqual([
+    expect(await workspaceRegistry.listAll()).toEqual([
       expect.objectContaining({
         workspaceId: firstAgent?.workspaceId,
         cwd: tempDir,
@@ -1012,7 +1012,7 @@ describe("ScheduleService", () => {
       (service as unknown as ScheduleServiceInternals).executeSchedule(created, "run-create-fails"),
     ).rejects.toThrow("provider misconfigured");
 
-    expect(await workspaceRegistry.list()).toEqual([
+    expect(await workspaceRegistry.listAll()).toEqual([
       expect.objectContaining({
         cwd: tempDir,
         archivedAt: expect.any(String),
@@ -1883,7 +1883,7 @@ describe("ScheduleService", () => {
       agentId: expect.any(String),
       error: expect.stringContaining("start turn exploded"),
     });
-    const storedAgents = await agentStorage.list();
+    const storedAgents = await agentStorage.listAll();
     expect(storedAgents).toHaveLength(1);
     expect(inspected.runs[0]?.agentId).toBe(storedAgents[0]?.id);
     expect(storedAgents[0]).toMatchObject({
@@ -1911,7 +1911,7 @@ describe("ScheduleService", () => {
           });
           return {
             modeId: input.unattended ? "bypassPermissions" : "interactive",
-            featureValues: input.featureValues,
+            providerOptions: input.providerOptions,
           };
         },
       },
@@ -1980,9 +1980,9 @@ describe("ScheduleService", () => {
           });
           return {
             modeId: input.unattended ? "build" : "interactive",
-            featureValues: input.unattended
-              ? { ...input.featureValues, auto_accept: true }
-              : input.featureValues,
+            providerOptions: input.unattended
+              ? { ...input.providerOptions, auto_accept: true }
+              : input.providerOptions,
           };
         },
       },
@@ -2010,7 +2010,7 @@ describe("ScheduleService", () => {
     expect(inspected.runs[0]?.error).toBeNull();
     expect(createdConfigs[0]).toMatchObject({
       modeId: "build",
-      featureValues: { auto_accept: true },
+      providerOptions: { auto_accept: true },
     });
   });
 
@@ -2052,7 +2052,7 @@ describe("ScheduleService", () => {
           });
           return {
             modeId: input.requestedMode,
-            featureValues: { ...input.featureValues, resolved: true },
+            providerOptions: { ...input.providerOptions, resolved: true },
           };
         },
       },
@@ -2099,11 +2099,13 @@ describe("ScheduleService", () => {
       model: "test-model",
       modeId: "stored-mode",
       thinkingOptionId: "think-hard",
+      // Stored schedules written before options carry `featureValues`; launch folds them.
       providerOptions: {
         allowedTools: ["Read"],
         sandbox: { enabled: true, network: { allowLocalBinding: true } },
+        auto_accept: true,
+        resolved: true,
       },
-      featureValues: { auto_accept: true, resolved: true },
       systemPrompt: "Stay concise.",
       mcpServers: {
         docs: {
@@ -2114,6 +2116,81 @@ describe("ScheduleService", () => {
     });
   });
 
+  test("rejects numeric cron steps when creating or updating a schedule", async () => {
+    const service = createScheduleService({
+      paseoHome: tempDir,
+      logger: createTestLogger(),
+      agentManager: new AgentManager({ logger: createTestLogger() }),
+      agentStorage,
+      providerSnapshotManager: NO_UNATTENDED_SCHEDULE_POLICY,
+      now: () => now,
+    });
+    const input = {
+      prompt: "Periodic check",
+      cadence: { type: "cron" as const, expression: "*/15 * * * *" },
+      target: {
+        type: "new-agent" as const,
+        config: { provider: "claude" as const, cwd: tempDir },
+      },
+      runOnCreate: false,
+    };
+
+    await expect(
+      service.create({ ...input, cadence: { type: "cron", expression: "0/15 * * * *" } }),
+    ).rejects.toThrow("Invalid cron minute step: use * or a range before /");
+    expect(await service.list()).toEqual([]);
+
+    const created = await service.create(input);
+    await expect(
+      service.update({ id: created.id, cadence: { type: "cron", expression: "0/15 * * * *" } }),
+    ).rejects.toThrow("Invalid cron minute step: use * or a range before /");
+    expect((await service.inspect(created.id)).cadence).toEqual(input.cadence);
+  });
+
+  test("recovers and runs numeric cron steps persisted by an older daemon", async () => {
+    const service = createScheduleService({
+      paseoHome: tempDir,
+      logger: createTestLogger(),
+      agentManager: new AgentManager({ logger: createTestLogger() }),
+      agentStorage,
+      providerSnapshotManager: NO_UNATTENDED_SCHEDULE_POLICY,
+      now: () => now,
+      runner: async () => ({ agentId: null, output: "ok" }),
+    });
+    const created = await service.create({
+      prompt: "Periodic check",
+      cadence: { type: "cron", expression: "0 * * * *" },
+      target: {
+        type: "new-agent",
+        config: { provider: "claude", cwd: tempDir },
+      },
+      runOnCreate: false,
+    });
+    const store = new ScheduleStore(join(tempDir, "schedules"), createTestLogger());
+    await store.update(created.id, (schedule) => ({
+      ...schedule,
+      cadence: { type: "cron", expression: "0/15 * * * *" },
+    }));
+
+    now = new Date("2026-01-01T03:10:00.000Z");
+    try {
+      await service.start();
+      await service.stop();
+      expect((await service.inspect(created.id)).nextRunAt).toBe("2026-01-01T04:00:00.000Z");
+
+      now = new Date("2026-01-01T04:00:00.000Z");
+      await service.tick();
+      const inspected = await service.inspect(created.id);
+      expect(inspected.cadence).toEqual({ type: "cron", expression: "0/15 * * * *" });
+      expect(inspected.status).toBe("active");
+      expect(inspected.nextRunAt).toBe("2026-01-01T05:00:00.000Z");
+      expect(inspected.runs).toHaveLength(1);
+      expect(inspected.runs[0]).toMatchObject({ status: "succeeded", output: "ok" });
+    } finally {
+      await service.stop();
+    }
+  });
+
   test("advances stale nextRunAt on daemon restart", async () => {
     const service1 = createScheduleService({
       paseoHome: tempDir,
diff --git a/packages/server/src/server/schedule/service.ts b/packages/server/src/server/schedule/service.ts
index 411bb3084e..fb804d914e 100644
--- a/packages/server/src/server/schedule/service.ts
+++ b/packages/server/src/server/schedule/service.ts
@@ -15,6 +15,7 @@ import type { PersistedWorkspaceRecord } from "../workspace-registry.js";
 import type { CreatePaseoWorktreeWorkflowResult } from "../worktree-session.js";
 import { ScheduleStore } from "./store.js";
 import { computeNextRunAt, validateScheduleCadence } from "./cron.js";
+import { foldFeatureValues } from "../agent/option-controls.js";
 import type {
   CreateScheduleInput,
   ScheduleExecutionResult,
@@ -235,7 +236,7 @@ type ScheduleAgentManager = Pick<
 > &
   Pick<
     AgentManager,
-    | "createAgent"
+    | "createAgentFromRecord"
     | "getRegisteredProviderIds"
     | "resumeAgentFromPersistence"
     | "runAgent"
@@ -997,7 +998,6 @@ export class ScheduleService {
         },
         mode: config.modeId,
         thinking: config.thinkingOptionId,
-        features: config.featureValues,
         unattended: true,
         promptFailure: "return-error",
         notifyOnFinish: false,
@@ -1097,8 +1097,8 @@ function buildScheduleAgentConfig(
     model: config.model,
     thinkingOptionId: config.thinkingOptionId,
     title: config.title,
-    providerOptions: config.providerOptions,
-    featureValues: config.featureValues,
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    providerOptions: foldFeatureValues(config).providerOptions,
     systemPrompt: config.systemPrompt,
     mcpServers: config.mcpServers as AgentSessionConfig["mcpServers"],
   };
diff --git a/packages/server/src/server/selective-timeline-delivery.e2e.test.ts b/packages/server/src/server/selective-timeline-delivery.e2e.test.ts
index 97929987fb..3add5181d1 100644
--- a/packages/server/src/server/selective-timeline-delivery.e2e.test.ts
+++ b/packages/server/src/server/selective-timeline-delivery.e2e.test.ts
@@ -185,6 +185,7 @@ async function connect(input: {
   timelineNotifications?: boolean;
   pluginTimelineItems?: boolean;
   workspaceSetupBlocked?: boolean;
+  ownedSubscriptions?: boolean;
 }): Promise<ConnectedClient> {
   let socket!: WebSocket;
   const client = new DaemonClient({
@@ -195,7 +196,7 @@ async function connect(input: {
       return socket as unknown as WebSocketLike;
     },
     capabilities: {
-      [CLIENT_CAPS.ownedSubscriptions]: false,
+      [CLIENT_CAPS.ownedSubscriptions]: input.ownedSubscriptions ?? false,
       [CLIENT_CAPS.selectiveAgentTimeline]: input.selective,
       [CLIENT_CAPS.pluginTimelineItems]: input.pluginTimelineItems ?? false,
       [CLIENT_CAPS.workspaceSetupBlocked]: input.workspaceSetupBlocked ?? false,
@@ -213,6 +214,97 @@ async function connect(input: {
   return connected;
 }
 
+async function startDaemonWithMockAgents(
+  home: { paseoHomeRoot: string; cleanup: boolean } | Record<string, never> = {},
+): Promise<void> {
+  await daemon.close();
+  daemon = await createTestPaseoDaemon({
+    isDev: true,
+    agentClients: { mock: new MockLoadTestAgentClient() },
+    ...home,
+  });
+}
+
+async function connectForFreshness(clientId: string): Promise<ConnectedClient> {
+  return connect({ clientId, selective: true, ownedSubscriptions: true });
+}
+
+async function createChatAtHead(connected: ConnectedClient, title: string) {
+  const agent = await connected.client.createAgent({
+    provider: "mock",
+    cwd: "/tmp",
+    title,
+    model: "ten-second-stream",
+  });
+  await daemon.daemon.agentManager.appendTimelineItem(agent.id, {
+    type: "assistant_message",
+    text: "Already on screen",
+  });
+  const page = await connected.client.fetchAgentTimeline(agent.id, { direction: "tail" });
+  if (!page.endCursor) throw new Error("Expected a timeline cursor");
+  return { agentId: agent.id, head: { epoch: page.endCursor.epoch, seq: page.endCursor.seq } };
+}
+
+test("subscribing with a cursor answers whether each chat is at its head", async () => {
+  await startDaemonWithMockAgents();
+  const connected = await connectForFreshness("freshness-loaded");
+  const atHead = await createChatAtHead(connected, "At head");
+  const staleSeq = await createChatAtHead(connected, "Stale seq");
+  const otherEpoch = await createChatAtHead(connected, "Other epoch");
+  const noCursor = await createChatAtHead(connected, "No cursor");
+
+  const observation = connected.client.observeTimeline(
+    [atHead.agentId, staleSeq.agentId, otherEpoch.agentId, noCursor.agentId],
+    {
+      cursors: {
+        [atHead.agentId]: atHead.head,
+        [staleSeq.agentId]: { ...staleSeq.head, seq: staleSeq.head.seq - 1 },
+        [otherEpoch.agentId]: { ...otherEpoch.head, epoch: "another-epoch" },
+      },
+    },
+  );
+
+  const answer = await observation.ready;
+  expect(answer.timelines).toEqual({
+    [atHead.agentId]: "current",
+    [staleSeq.agentId]: "behind",
+    [otherEpoch.agentId]: "behind",
+  });
+  // Only a current chat skips the fetch that would have delivered its agent row.
+  expect(Object.keys(answer.agents ?? {})).toEqual([atHead.agentId]);
+  expect(answer.agents?.[atHead.agentId]).toMatchObject({ id: atHead.agentId, title: "At head" });
+
+  connected.clear();
+  await daemon.daemon.agentManager.appendTimelineItem(atHead.agentId, {
+    type: "assistant_message",
+    text: "Arrives after the answer",
+  });
+  await connected.next(isAgentStream(atHead.agentId), "live row after a current answer");
+  await observation.release();
+});
+
+test("subscribing with a cursor answers behind for a stored agent and leaves it unloaded", async () => {
+  const paseoHomeRoot = await mkdtemp(path.join(os.tmpdir(), "paseo-freshness-"));
+  await startDaemonWithMockAgents({ paseoHomeRoot, cleanup: false });
+  const before = await connectForFreshness("freshness-before-restart");
+  const stored = await createChatAtHead(before, "Stored");
+  before.close();
+  await before.client.close();
+  await startDaemonWithMockAgents({ paseoHomeRoot, cleanup: true });
+  expect(daemon.daemon.agentManager.getAgent(stored.agentId)).toBeNull();
+
+  const connected = await connectForFreshness("freshness-after-restart");
+  const observation = connected.client.observeTimeline([stored.agentId], {
+    cursors: { [stored.agentId]: stored.head },
+  });
+
+  const answer = await observation.ready;
+  expect(answer.timelines).toEqual({ [stored.agentId]: "behind" });
+  expect(answer.agents).toEqual({});
+  expect(daemon.daemon.agentManager.getAgent(stored.agentId)).toBeNull();
+  await observation.release();
+});
+
 test("notification timeline items are sent only to clients that advertise support", async () => {
   await daemon.close();
   daemon = await createTestPaseoDaemon({
diff --git a/packages/server/src/server/service-proxy.test.ts b/packages/server/src/server/service-proxy.test.ts
index 5764b19539..eb679d5629 100644
--- a/packages/server/src/server/service-proxy.test.ts
+++ b/packages/server/src/server/service-proxy.test.ts
@@ -1,7 +1,9 @@
+import { type EventEmitter, once } from "node:events";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import http from "node:http";
 import net from "node:net";
+import type { Duplex } from "node:stream";
 import express from "express";
 import { describe, expect, it } from "vitest";
 import pino from "pino";
@@ -332,48 +334,39 @@ describe("service proxy subsystem shape", () => {
   });
 });
 
-interface ForwardedFixture {
+interface ProxiedServiceFixture {
   upstreamPort: number;
   daemonPort: number;
+  daemon: http.Server;
   hostname: string;
   close(): Promise<void>;
 }
 
 /**
- * Runs a real workspace service behind a real daemon listener. The upstream
- * echoes the headers it received so tests can assert what actually crossed the
- * proxy, not what a helper returned.
+ * Runs a real workspace service behind a real daemon listener that serves the
+ * service proxy for both HTTP and upgrades.
  */
-async function startForwardedHeadersFixture(upstreamHost = "127.0.0.1"): Promise<ForwardedFixture> {
-  const upstream = http.createServer((req, res) => {
-    let body = "";
-    req.on("data", (chunk: Buffer) => {
-      body += chunk.toString();
+async function startProxiedService(
+  upstream: http.Server,
+  options: { upstreamHost?: string; logger?: pino.Logger } = {},
+): Promise<ProxiedServiceFixture> {
+  const { upstreamHost = "127.0.0.1", logger: proxyLogger = logger } = options;
+  // Upgraded sockets keep the server alive; close() alone would hang.
+  const sockets = new Set<net.Socket>();
+  function trackConnections(server: http.Server) {
+    server.on("connection", (socket: net.Socket) => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
     });
-    req.on("end", () => {
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ ...req.headers, method: req.method, url: req.url, body }));
-    });
-  });
-  const upgradeSockets: net.Socket[] = [];
-  upstream.on("upgrade", (req, socket) => {
-    upgradeSockets.push(socket);
-    // The client resets this connection once it has the echo, so the reset
-    // reaches us as an 'error'. A raw upgrade socket has no default handler —
-    // without this the event goes unhandled and takes down the test process.
-    socket.on("error", () => socket.destroy());
-    const payload = JSON.stringify(req.headers);
-    socket.write(
-      `HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nX-Echo-Length: ${payload.length}\r\n\r\n${payload}`,
-    );
-  });
+  }
+  trackConnections(upstream);
   await new Promise<void>((resolve, reject) => {
     upstream.once("error", reject);
     upstream.listen(0, upstreamHost, resolve);
   });
   const upstreamPort = (upstream.address() as net.AddressInfo).port;
 
-  const serviceProxy = createServiceProxySubsystem({ logger });
+  const serviceProxy = createServiceProxySubsystem({ logger: proxyLogger });
   const route = serviceProxy.registerWorkspaceService({
     workspaceId: "workspace-a",
     projectSlug: "repo",
@@ -390,24 +383,51 @@ async function startForwardedHeadersFixture(upstreamHost = "127.0.0.1"): Promise
     res.status(404).send("404 Not Found");
   });
   const daemon = http.createServer(app);
+  trackConnections(daemon);
   daemon.on("upgrade", serviceProxy.upgradeHandler({ passthroughUnknown: false }));
   await new Promise<void>((resolve) => daemon.listen(daemonPort, "127.0.0.1", resolve));
 
   return {
     upstreamPort,
     daemonPort,
+    daemon,
     hostname: route.hostname,
     async close() {
-      // Upgraded sockets keep the server alive; close() alone would hang.
-      for (const socket of upgradeSockets) socket.destroy();
-      daemon.closeAllConnections();
+      for (const socket of sockets) socket.destroy();
       await new Promise<void>((resolve) => daemon.close(() => resolve()));
-      upstream.closeAllConnections();
       await new Promise<void>((resolve) => upstream.close(() => resolve()));
     },
   };
 }
 
+/**
+ * The upstream echoes the headers it received so tests can assert what
+ * actually crossed the proxy, not what a helper returned.
+ */
+function startForwardedHeadersFixture(upstreamHost = "127.0.0.1"): Promise<ProxiedServiceFixture> {
+  const upstream = http.createServer((req, res) => {
+    let body = "";
+    req.on("data", (chunk: Buffer) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ...req.headers, method: req.method, url: req.url, body }));
+    });
+  });
+  upstream.on("upgrade", (req, socket) => {
+    // The client resets this connection once it has the echo, so the reset
+    // reaches us as an 'error'. A raw upgrade socket has no default handler —
+    // without this the event goes unhandled and takes down the test process.
+    socket.on("error", () => socket.destroy());
+    const payload = JSON.stringify(req.headers);
+    socket.write(
+      `HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nX-Echo-Length: ${payload.length}\r\n\r\n${payload}`,
+    );
+  });
+  return startProxiedService(upstream, { upstreamHost });
+}
+
 function upgradeThroughProxy(
   port: number,
   host: string,
@@ -651,3 +671,198 @@ describe("service proxy forwarded headers", () => {
     }
   });
 });
+
+function closed(emitter: EventEmitter): Promise<void> {
+  return new Promise((resolve) => {
+    emitter.once("close", () => resolve());
+  });
+}
+
+async function within<T>(promise: Promise<T>, ms: number, failure: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${failure} after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function requestThroughProxy(
+  fixture: ProxiedServiceFixture,
+  requestPath: string,
+): http.ClientRequest {
+  return http.get({
+    hostname: "127.0.0.1",
+    port: fixture.daemonPort,
+    path: requestPath,
+    headers: { host: fixture.hostname },
+  });
+}
+
+const STRAY_WARNING_GRACE_MS = 100;
+
+function createUpgradeUpstream(onUpgrade: (socket: Duplex) => void): http.Server {
+  const upstream = http.createServer();
+  upstream.on("upgrade", (_req, socket) => {
+    socket.on("error", () => socket.destroy());
+    socket.on("end", () => socket.end());
+    socket.write(
+      "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n",
+    );
+    onUpgrade(socket);
+  });
+  return upstream;
+}
+
+function openUpgradeThroughProxy(fixture: ProxiedServiceFixture): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host: "127.0.0.1", port: fixture.daemonPort }, () => {
+      const lines = [
+        "GET /ws HTTP/1.1",
+        `Host: ${fixture.hostname}`,
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        "",
+        "",
+      ];
+      socket.write(lines.join("\r\n"));
+    });
+    let raw = "";
+    socket.on("data", (chunk: Buffer) => {
+      raw += chunk.toString();
+      if (raw.includes("\r\n\r\n")) resolve(socket);
+    });
+    socket.on("close", () => reject(new Error("upgrade closed before the 101 arrived")));
+    socket.on("error", reject);
+  });
+}
+
+describe("service proxy connection teardown", () => {
+  it("closes the upstream connection when a client leaves an event stream", async () => {
+    const upstreamResponse = Promise.withResolvers<http.ServerResponse>();
+    const upstream = http.createServer((_req, res) => {
+      res.writeHead(200, { "content-type": "text/event-stream" });
+      res.write("data: open\n\n");
+      upstreamResponse.resolve(res);
+    });
+    const fixture = await startProxiedService(upstream);
+    try {
+      const request = requestThroughProxy(fixture, "/events");
+      const [response] = (await once(request, "response")) as [http.IncomingMessage];
+      await once(response, "data");
+      const upstreamClosed = closed(await upstreamResponse.promise);
+
+      request.destroy();
+
+      await within(upstreamClosed, 1000, "the service still holds the event stream");
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+
+  it("aborts the upstream request when a client leaves before the response starts", async () => {
+    const warnings: unknown[] = [];
+    const proxyLogger = pino(
+      { level: "warn" },
+      { write: (line: string) => warnings.push(JSON.parse(line)) },
+    );
+    const upstreamResponse = Promise.withResolvers<http.ServerResponse>();
+    const upstream = http.createServer((_req, res) => {
+      upstreamResponse.resolve(res);
+    });
+    const fixture = await startProxiedService(upstream, { logger: proxyLogger });
+    try {
+      const request = requestThroughProxy(fixture, "/slow");
+      request.on("error", () => undefined);
+      const upstreamClosed = closed(await upstreamResponse.promise);
+
+      request.destroy();
+
+      await within(upstreamClosed, 1000, "the service still holds the abandoned request");
+      await new Promise((resolve) => setTimeout(resolve, STRAY_WARNING_GRACE_MS));
+      expect(warnings).toEqual([]);
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+
+  it("lets a complete response finish without resetting the service", async () => {
+    const upstreamResponse = Promise.withResolvers<http.ServerResponse>();
+    const upstream = http.createServer((_req, res) => {
+      res.writeHead(200, { "content-type": "text/plain" });
+      res.write("first;");
+      upstreamResponse.resolve(res);
+    });
+    const fixture = await startProxiedService(upstream);
+    try {
+      const response = httpGet(fixture.daemonPort, fixture.hostname, { path: "/" });
+      const res = await upstreamResponse.promise;
+      const upstreamClosed = closed(res);
+
+      res.end("second");
+
+      await expect(response).resolves.toEqual({ status: 200, body: "first;second" });
+      await within(upstreamClosed, 1000, "the service response never closed");
+      expect(res.writableFinished).toBe(true);
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+
+  it("closes the upstream WebSocket when the daemon drops the client socket", async () => {
+    const upstreamSocket = Promise.withResolvers<Duplex>();
+    const fixture = await startProxiedService(
+      createUpgradeUpstream((socket) => upstreamSocket.resolve(socket)),
+    );
+    const daemonSide = Promise.withResolvers<Duplex>();
+    fixture.daemon.on("upgrade", (_req, socket) => daemonSide.resolve(socket));
+    try {
+      const client = await openUpgradeThroughProxy(fixture);
+      const upstreamClosed = closed(await upstreamSocket.promise);
+
+      (await daemonSide.promise).destroy();
+
+      await within(upstreamClosed, 1000, "the service still holds the WebSocket");
+      client.destroy();
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+
+  it("closes the upstream WebSocket when the client disconnects", async () => {
+    const upstreamSocket = Promise.withResolvers<Duplex>();
+    const fixture = await startProxiedService(
+      createUpgradeUpstream((socket) => upstreamSocket.resolve(socket)),
+    );
+    try {
+      const client = await openUpgradeThroughProxy(fixture);
+      const upstreamClosed = closed(await upstreamSocket.promise);
+
+      client.destroy();
+
+      await within(upstreamClosed, 1000, "the service still holds the WebSocket");
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+
+  it("closes the client WebSocket when the service closes it", async () => {
+    const upstreamSocket = Promise.withResolvers<Duplex>();
+    const fixture = await startProxiedService(
+      createUpgradeUpstream((socket) => upstreamSocket.resolve(socket)),
+    );
+    try {
+      const client = await openUpgradeThroughProxy(fixture);
+      const clientClosed = closed(client);
+
+      (await upstreamSocket.promise).destroy();
+
+      await within(clientClosed, 1000, "the client WebSocket is still open");
+    } finally {
+      await fixture.close();
+    }
+  }, 5000);
+});
diff --git a/packages/server/src/server/service-proxy.ts b/packages/server/src/server/service-proxy.ts
index ef93a27f9a..24bfd80c93 100644
--- a/packages/server/src/server/service-proxy.ts
+++ b/packages/server/src/server/service-proxy.ts
@@ -342,7 +342,14 @@ function proxyHttpRequest({
       proxyRes.pipe(res, { end: true });
     },
   );
+  let clientClosed = false;
+  res.on("close", () => {
+    if (res.writableFinished) return;
+    clientClosed = true;
+    proxyReq.destroy();
+  });
   proxyReq.on("error", (err) => {
+    if (clientClosed) return;
     logger.warn(
       { err, hostname: route.hostname, port: route.port },
       "Service proxy: upstream unreachable",
@@ -399,6 +406,9 @@ function proxyUpgradeRequest({
   socket.on("error", () => {
     targetSocket.destroy();
   });
+  socket.on("close", () => {
+    targetSocket.destroy();
+  });
 }
 
 function sameRouteOwner(left: ServiceProxyRouteEntry, right: ServiceProxyRouteEntry): boolean {
diff --git a/packages/server/src/server/session.create-agent-worktree-autoarchive.e2e.test.ts b/packages/server/src/server/session.create-agent-worktree-autoarchive.e2e.test.ts
index 34d1483023..313300d82a 100644
--- a/packages/server/src/server/session.create-agent-worktree-autoarchive.e2e.test.ts
+++ b/packages/server/src/server/session.create-agent-worktree-autoarchive.e2e.test.ts
@@ -14,6 +14,7 @@ import {
 import type { CreateAgentOptions } from "./test-utils/index.js";
 import type { CreateAgentWorktreeTarget } from "./messages.js";
 import { createRealpathAwarePathMatcher } from "../utils/path.js";
+import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
 
 let ctx: DaemonTestContext;
 const tempRoots: string[] = [];
@@ -477,7 +478,7 @@ test("background workspaces keep durable agents addressable through restart and
     ),
   ).toContain(hidden.id);
   const child = await ctx.client.createAgent({ config, callerAgentId: hidden.id });
-  expect(child.workspaceId).toBe(hidden.workspaceId);
+  expect(child).toMatchObject({ workspaceId: hidden.workspaceId, background: true });
   const inherited = await ctx.client.createWorkspace({
     source: { kind: "directory", path: cwd },
     callerAgentId: hidden.id,
@@ -509,9 +510,16 @@ test("background workspaces keep durable agents addressable through restart and
     false,
   );
 
-  await expect(
-    ctx.client.createAgent({ config, workspaceId: hidden.workspaceId, background: false }),
-  ).rejects.toThrow("workspace creation intent");
+  expect(hidden.background).toBe(true);
+  const visibleInHidden = await ctx.client.createAgent({
+    config,
+    workspaceId: hidden.workspaceId,
+    background: false,
+  });
+  expect(visibleInHidden.background).toBeUndefined();
+  expect((await ctx.client.fetchAgents()).entries.map((entry) => entry.agent.id)).not.toContain(
+    visibleInHidden.id,
+  );
   await ctx.client.sendAgentMessage(hidden.id, "Say done.");
   await ctx.client.waitForFinish(hidden.id, 10_000);
   expect(
@@ -616,3 +624,111 @@ test("default and inclusive observers retain independent snapshots, live updates
     await otherClient.close();
   }
 }, 30_000);
+
+test("a background agent in a visible workspace is hidden from default discovery through restart", async () => {
+  const cwd = createGitRepo();
+  const config = { ...getFullAccessConfig("codex"), cwd };
+  const visible = await ctx.client.createAgent({ config });
+  const hidden = await ctx.client.createAgent({
+    config,
+    workspaceId: visible.workspaceId,
+    background: true,
+  });
+  expect(hidden).toMatchObject({ workspaceId: visible.workspaceId, background: true });
+  expect(visible.background).toBeUndefined();
+  const defaultIds = async () =>
+    (await ctx.client.fetchAgents()).entries.map((entry) => entry.agent.id);
+  const inclusiveIds = async () =>
+    (await ctx.client.fetchAgents({ filter: { includeBackground: true } })).entries.map(
+      (entry) => entry.agent.id,
+    );
+  expect(await defaultIds()).toEqual([visible.id]);
+  expect(await inclusiveIds()).toEqual(expect.arrayContaining([visible.id, hidden.id]));
+  expect((await ctx.client.fetchWorkspaces()).entries).toContainEqual(
+    expect.objectContaining({ id: visible.workspaceId, background: false }),
+  );
+
+  await ctx.client.sendAgentMessage(hidden.id, "Say done.");
+  await ctx.client.waitForFinish(hidden.id, 10_000);
+  expect((await ctx.client.fetchAgent(hidden.id))?.agent).toMatchObject({
+    background: true,
+    requiresAttention: false,
+  });
+
+  const homeRoot = path.dirname(ctx.daemon.paseoHome);
+  tempRoots.push(ctx.daemon.staticDir);
+  await ctx.client.close();
+  await ctx.daemon.daemon.stop();
+  await ctx.daemon.daemon.agentManager.flush();
+  ctx = await createDaemonTestContext({ paseoHomeRoot: homeRoot });
+
+  expect(await defaultIds()).toEqual([visible.id]);
+  expect(await inclusiveIds()).toContain(hidden.id);
+  await ctx.client.sendAgentMessage(hidden.id, "Say done again.");
+  await ctx.client.waitForFinish(hidden.id, 10_000);
+  expect((await ctx.client.fetchAgent(hidden.id))?.agent.background).toBe(true);
+  expect(await defaultIds()).toEqual([visible.id]);
+  await ctx.client.archiveAgent(hidden.id);
+  expect(
+    (await ctx.client.fetchAgentHistory()).entries.map((entry) => entry.agent.id),
+  ).not.toContain(hidden.id);
+  expect(
+    (await ctx.client.fetchAgentHistory({ filter: { includeBackground: true } })).entries.map(
+      (entry) => entry.agent.id,
+    ),
+  ).toContain(hidden.id);
+}, 30_000);
+
+test("a client without background_agents never receives background agents, even in inclusive reads", async () => {
+  const oldApp = new DaemonClient({
+    url: `ws://127.0.0.1:${ctx.daemon.port}/ws`,
+    capabilities: { [CLIENT_CAPS.backgroundAgents]: false },
+  });
+  await oldApp.connect();
+  try {
+    const cwd = createGitRepo();
+    const config = { ...getFullAccessConfig("codex"), cwd };
+    const visible = await ctx.client.createAgent({ config });
+    const hidden = await ctx.client.createAgent({
+      config,
+      workspaceId: visible.workspaceId,
+      background: true,
+    });
+    const backgroundWorkspace = await ctx.client.createWorkspace({
+      source: { kind: "directory", path: cwd },
+      background: true,
+    });
+    const workspaceAgent = await ctx.client.createAgent({
+      config,
+      workspaceId: backgroundWorkspace.workspace?.id,
+    });
+    const observed = oldApp.observeAgents({ scope: "active", sync: {}, includeBackground: true });
+    const snapshot = await observed.ready;
+    expect(snapshot.entries.map((entry) => entry.agent.id).toSorted()).toEqual(
+      [visible.id, workspaceAgent.id].toSorted(),
+    );
+    const upserts: string[] = [];
+    observed.subscribe({
+      snapshot: () => {},
+      update: (message) => {
+        if (message.type === "agent_update" && message.payload.kind === "upsert")
+          upserts.push(message.payload.agent.id);
+      },
+    });
+    await ctx.client.sendAgentMessage(hidden.id, "Say done.");
+    await ctx.client.waitForFinish(hidden.id, 10_000);
+    await ctx.client.sendAgentMessage(visible.id, "Say done.");
+    await ctx.client.waitForFinish(visible.id, 10_000);
+    await expect.poll(() => upserts).toContain(visible.id);
+    expect(upserts).not.toContain(hidden.id);
+    expect(
+      (await oldApp.fetchAgents({ filter: { includeBackground: true } })).entries.map(
+        (entry) => entry.agent.id,
+      ),
+    ).not.toContain(hidden.id);
+    expect((await oldApp.fetchAgent(hidden.id))?.agent.id).toBe(hidden.id);
+    await observed.release();
+  } finally {
+    await oldApp.close();
+  }
+}, 30_000);
diff --git a/packages/server/src/server/session.test.ts b/packages/server/src/server/session.test.ts
index 45ab17b703..88b0f414f7 100644
--- a/packages/server/src/server/session.test.ts
+++ b/packages/server/src/server/session.test.ts
@@ -348,6 +348,7 @@ interface SessionForTestOptions {
   messages?: unknown[];
   targetedMessages?: Array<{ source: object; message: SessionOutboundMessage }>;
   binaryMessages?: Uint8Array[];
+  clientCapabilities?: SessionOptions["clientCapabilities"];
   pluginRuntime?: SessionOptions["pluginRuntime"];
   orchestrationSkills?: SessionOptions["orchestrationSkills"];
   workspaceLabelService?: WorkspaceLabelService;
@@ -402,6 +403,7 @@ function createSessionForTest(options: SessionForTestOptions = {}): Session {
             messages.push(message),
         }),
     onBinaryMessage: createBinaryMessageHandler(options.binaryMessages),
+    clientCapabilities: options.clientCapabilities,
     logger,
     downloadTokenStore: options.downloadTokenStore ?? asDownloadTokenStore(),
     pushNotifications: options.pushNotifications ?? asPushNotifications(),
@@ -409,6 +411,7 @@ function createSessionForTest(options: SessionForTestOptions = {}): Session {
     agentManager: asAgentManager({
       listAgents: vi.fn(() => []),
       listProviderSubagentActivity: vi.fn(() => []),
+      getAgentBackgroundWorkSummary: () => undefined,
       subscribe: vi.fn(() => () => {}),
       ...options.agentManager,
     }),
@@ -601,6 +604,64 @@ test("routes plugin requests and releases its owned catalog subscription on clea
   expect(releasePluginSubscription).toHaveBeenCalledOnce();
 });
 
+test("losing daemon.manage releases the session's plugin subscriptions", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const release = vi.fn();
+  const pluginRuntime = {
+    subscribe: () => () => {},
+    subscribePluginRpc: () => ({ ready: Promise.resolve(), attach: () => {}, release }),
+  } as unknown as NonNullable<SessionOptions["pluginRuntime"]>;
+  const session = createSessionForTest({ messages, pluginRuntime });
+
+  await session.handleMessage({
+    type: "plugin.rpc.subscribe.request",
+    requestId: "watch",
+    pluginId: "example",
+    method: "screen.capture",
+    input: {},
+  });
+  expect(messages.map((message) => message.type)).toContain("plugin.rpc.subscribe.response");
+  session.setPermissions(["daemon.read"]);
+
+  // Bytes have no outbound permission check, so the stream itself has to end.
+  await vi.waitFor(() => expect(release).toHaveBeenCalledOnce());
+});
+
+test("losing daemon.manage during a plugin RPC withholds its JSON and binary results", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const binaryMessages: Uint8Array[] = [];
+  const outputs = new Map<string, (output: unknown) => void>();
+  const pluginRuntime = {
+    subscribe: () => () => {},
+    invokePluginRpc: (_pluginId: string, method: string) =>
+      new Promise((resolve) => outputs.set(method, resolve)),
+  } as unknown as NonNullable<SessionOptions["pluginRuntime"]>;
+  const session = createSessionForTest({
+    messages,
+    binaryMessages,
+    pluginRuntime,
+    clientCapabilities: { [CLIENT_CAPS.pluginBinaryPayloads]: true },
+  });
+  const invoke = (method: string) =>
+    session.handleMessage({
+      type: "plugin.rpc.invoke.request",
+      requestId: method,
+      pluginId: "example",
+      method,
+      input: {},
+    });
+
+  const pending = [invoke("capture.json"), invoke("capture.bytes")];
+  await vi.waitFor(() => expect(outputs.size).toBe(2));
+  session.setPermissions(["daemon.read"]);
+  outputs.get("capture.json")?.({ width: 1 });
+  outputs.get("capture.bytes")?.(new Uint8Array([1, 2, 3]));
+  await Promise.all(pending);
+
+  expect(messages.filter((message) => message.type === "plugin.rpc.invoke.response")).toEqual([]);
+  expect(binaryMessages).toEqual([]);
+});
+
 test("leaves out the client bundles a catalog request already holds", async () => {
   const messages: SessionOutboundMessage[] = [];
   const pluginRuntime: NonNullable<SessionOptions["pluginRuntime"]> = {
@@ -4181,7 +4242,7 @@ describe("session workspace descriptors", () => {
         ),
       },
       messages,
-      workspaceRegistry: { get: vi.fn(), list: vi.fn().mockResolvedValue([workspace]) },
+      workspaceRegistry: { get: vi.fn(), listActive: vi.fn().mockResolvedValue([workspace]) },
       projectRegistry: {
         list: vi.fn().mockResolvedValue([project]),
         get: vi.fn().mockResolvedValue(project),
@@ -4261,7 +4322,7 @@ describe("session workspace descriptors", () => {
         ),
       },
       messages,
-      workspaceRegistry: { get: vi.fn(), list: vi.fn().mockResolvedValue([workspace]) },
+      workspaceRegistry: { get: vi.fn(), listActive: vi.fn().mockResolvedValue([workspace]) },
       projectRegistry: { list: vi.fn().mockResolvedValue([project]), get: vi.fn() },
       workspaceGitService: {
         getSnapshot: vi.fn(),
@@ -5818,7 +5879,7 @@ describe("agent config setters", () => {
     const messages: SessionOutboundMessage[] = [];
     const session = createSessionForTest({
       messages,
-      agentManager: liveAgentManager({ setAgentFeature: vi.fn().mockResolvedValue(undefined) }),
+      agentManager: liveAgentManager({ setAgentOptions: vi.fn().mockResolvedValue(undefined) }),
     });
 
     await session.handleMessage({
@@ -5842,7 +5903,7 @@ describe("agent config setters", () => {
     const session = createSessionForTest({
       messages,
       agentManager: liveAgentManager({
-        setAgentFeature: vi.fn().mockRejectedValue(new Error("feature boom")),
+        setAgentOptions: vi.fn().mockRejectedValue(new Error("feature boom")),
       }),
     });
 
@@ -6047,3 +6108,251 @@ test("a failing direct source observes fire-and-forget file replies without unha
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test("answers an agent background work list request", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const session = createSessionForTest({
+    messages,
+    agentManager: {
+      waitForAgentClose: vi.fn().mockResolvedValue(undefined),
+      getAgent: vi.fn(() => ({ id: "agent-a" })),
+      getAgentBackgroundWorkSummary: () => ({ count: 1 }),
+      listAgentBackgroundWork: vi.fn(() => [
+        {
+          id: "bash-1",
+          kind: "shell",
+          description: "sleep 20",
+          startedAt: "2026-10-06T10:00:00.000Z",
+        },
+      ]),
+    },
+  });
+
+  await session.handleMessage({
+    type: "agent.background_work.list.request",
+    agentId: "agent-a",
+    requestId: "list-1",
+  });
+
+  expect(messages).toContainEqual({
+    type: "agent.background_work.list.response",
+    payload: {
+      requestId: "list-1",
+      agentId: "agent-a",
+      items: [
+        {
+          id: "bash-1",
+          kind: "shell",
+          description: "sleep 20",
+          startedAt: "2026-10-06T10:00:00.000Z",
+        },
+      ],
+      error: null,
+    },
+  });
+});
+
+test("reports an unavailable inventory for a stored agent without loading it", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const resumeAgentFromPersistence = vi.fn();
+  const createAgent = vi.fn();
+  const listAgentBackgroundWork = vi.fn(() => []);
+  const session = createSessionForTest({
+    messages,
+    agentManager: {
+      waitForAgentClose: vi.fn().mockResolvedValue(undefined),
+      getAgent: () => undefined,
+      getRegisteredProviderIds: vi.fn(() => ["claude"]),
+      resumeAgentFromPersistence,
+      createAgent,
+      listAgentBackgroundWork,
+    },
+    agentStorage: {
+      get: vi.fn().mockResolvedValue(
+        createStoredAgentRecord({
+          id: "agent-a",
+          cwd: "/tmp/repo",
+          provider: "claude",
+          persistence: { provider: "claude", sessionId: "session-a" },
+        }),
+      ),
+    },
+  });
+
+  await session.handleMessage({
+    type: "agent.background_work.list.request",
+    agentId: "agent-a",
+    requestId: "list-stored",
+  });
+
+  expect(messages).toContainEqual({
+    type: "agent.background_work.list.response",
+    payload: {
+      requestId: "list-stored",
+      agentId: "agent-a",
+      items: [],
+      error: "Background work inventory is unavailable",
+    },
+  });
+  expect(resumeAgentFromPersistence).not.toHaveBeenCalled();
+  expect(createAgent).not.toHaveBeenCalled();
+  expect(listAgentBackgroundWork).not.toHaveBeenCalled();
+});
+
+test.each([
+  {
+    name: "an archived agent",
+    record: createStoredAgentRecord({
+      id: "agent-a",
+      cwd: "/tmp/repo",
+      archivedAt: "2026-10-06T10:00:00.000Z",
+    }),
+    error: "Agent is archived: agent-a",
+  },
+  { name: "an unknown agent", record: undefined, error: "Unknown agent 'agent-a'" },
+  {
+    name: "an internal agent",
+    record: createStoredAgentRecord({ id: "agent-a", cwd: "/tmp/repo", internal: true }),
+    error: "Unknown agent 'agent-a'",
+  },
+])("rejects a background work list request for $name that is not loaded", async (scenario) => {
+  const messages: SessionOutboundMessage[] = [];
+  const session = createSessionForTest({
+    messages,
+    agentManager: {
+      waitForAgentClose: vi.fn().mockResolvedValue(undefined),
+      getAgent: () => undefined,
+      getRegisteredProviderIds: vi.fn(() => ["codex"]),
+      resumeAgentFromPersistence: vi.fn(),
+      createAgent: vi.fn(),
+    },
+    agentStorage: { get: vi.fn().mockResolvedValue(scenario.record) },
+  });
+
+  await session.handleMessage({
+    type: "agent.background_work.list.request",
+    agentId: "agent-a",
+    requestId: "list-rejected",
+  });
+
+  expect(messages).toContainEqual({
+    type: "agent.background_work.list.response",
+    payload: { requestId: "list-rejected", agentId: "agent-a", items: [], error: scenario.error },
+  });
+});
+
+test("never pushes background work to an old app", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const targetedMessages: Array<{ source: object; message: SessionOutboundMessage }> = [];
+  const agentEventListeners: Array<(event: AgentManagerEvent) => void> = [];
+  const session = createSessionForTest({
+    messages,
+    targetedMessages,
+    agentManager: {
+      getAgent: vi.fn(() => undefined),
+      subscribe: vi.fn((listener: (event: AgentManagerEvent) => void) => {
+        agentEventListeners.push(listener);
+        return () => {};
+      }),
+    },
+  });
+  // provider_subagents makes subagent updates flow to this legacy socket, so the
+  // manager listener is installed for it.
+  const legacySocket = {};
+  session.updateClientCapabilities({ provider_subagents: true }, legacySocket);
+  const listener = agentEventListeners[0];
+  if (!listener) throw new Error("Agent event listener was not installed");
+
+  listener({
+    type: "background_work",
+    agentId: "agent-a",
+    items: [
+      { id: "bash-1", kind: "shell", description: null, startedAt: "2026-10-06T10:00:00.000Z" },
+    ],
+  });
+
+  const pushed = [...messages, ...targetedMessages.map((entry) => entry.message)];
+  expect(pushed.some((message) => message.type === "agent.background_work.update")).toBe(false);
+});
+
+test("pushes background work only to clients that subscribed to it", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const agentEventListeners: Array<(event: AgentManagerEvent) => void> = [];
+  const session = createSessionForTest({
+    messages,
+    agentManager: {
+      getAgent: vi.fn(() => undefined),
+      subscribe: vi.fn((listener: (event: AgentManagerEvent) => void) => {
+        agentEventListeners.push(listener);
+        return () => {};
+      }),
+    },
+  });
+  const forward = (event: AgentManagerEvent) => {
+    for (const listener of agentEventListeners) listener(event);
+  };
+  const event: AgentManagerEvent = {
+    type: "background_work",
+    agentId: "agent-a",
+    items: [
+      { id: "bash-1", kind: "shell", description: null, startedAt: "2026-10-06T10:00:00.000Z" },
+    ],
+  };
+
+  // Subscribe to an unrelated event so the manager listener is installed, then prove
+  // a client that did not ask for background work never receives it.
+  await session.handleMessage({
+    type: "session.events.set_subscription.request",
+    requestId: "events-1",
+    events: ["agent.provider_subagents.update"],
+  });
+  if (agentEventListeners.length === 0) throw new Error("Agent event listener was not installed");
+  forward(event);
+  expect(messages.some((message) => message.type === "agent.background_work.update")).toBe(false);
+
+  await session.handleMessage({
+    type: "session.events.set_subscription.request",
+    requestId: "events-2",
+    events: ["agent.background_work.update"],
+  });
+  messages.length = 0;
+
+  forward(event);
+
+  expect(messages).toContainEqual(
+    expect.objectContaining({
+      type: "agent.background_work.update",
+      payload: expect.objectContaining({ agentId: "agent-a", items: event.items }),
+    }),
+  );
+});
+
+test("does not publish internal agents' background work to subscribed clients", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  let listener: ((event: AgentManagerEvent) => void) | undefined;
+  const session = createSessionForTest({
+    messages,
+    agentManager: {
+      getAgent: () => ({ id: "internal-agent", internal: true }) as never,
+      subscribe: (callback) => {
+        listener = callback;
+        return () => {};
+      },
+    },
+  });
+  await session.handleMessage({
+    type: "session.events.set_subscription.request",
+    requestId: "subscribe-internal-background",
+    events: ["agent.background_work.update"],
+  });
+  messages.length = 0;
+  if (!listener) throw new Error("Agent event listener was not installed");
+  listener({
+    type: "background_work",
+    agentId: "internal-agent",
+    items: [
+      { id: "work", kind: "shell", description: "private", startedAt: "2026-10-06T10:00:00.000Z" },
+    ],
+  });
+  expect(messages.some((message) => message.type === "agent.background_work.update")).toBe(false);
+});
diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts
index 167bc96605..a9ae285e54 100644
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -1,8 +1,15 @@
+import { DiffSession } from "./diff/index.js";
 import { type WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import type { AgentMessageDelivery } from "./agent/agent-messages/index.js";
-import { AgentDirectory } from "./agent/directory.js";
+import { AgentDirectory, type BackgroundVisibility } from "./agent/directory.js";
 import { ConnectedHostSession } from "./connected-hosts/index.js";
 import type { ConnectedHosts } from "./connected-hosts/index.js";
+import {
+  createWorkspaceBaseBranchService,
+  type WorkspaceBaseBranchService,
+} from "./session/workspace-base-branch/service.js";
+import type { WorkspaceBaseBranchSetRequest } from "@getpaseo/protocol/messages";
+
 import { searchTimeline } from "./agent/chat-search/index.js";
 import type { BrowserToolsBroker } from "./browser-tools/broker.js";
 import { BrowserAutomationHostCapabilitySchema } from "@getpaseo/protocol/browser-automation/capabilities";
@@ -16,6 +23,7 @@ import { isAbsolute } from "node:path";
 import { CreationService, type CreatedAgent } from "./creation/index.js";
 import type { CreationSnapshot, AgentCreateRequest } from "@getpaseo/protocol/messages";
 import type { MessageReceipts } from "./message-receipts/index.js";
+import type { AgentBackgroundWorkItem } from "./agent/background-work/index.js";
 import equal from "fast-deep-equal";
 import { WorkspaceSetupObservation } from "./workspace-setup-observation.js";
 import { SessionDelivery, type OwnedSubscription } from "./session/owned-subscriptions/index.js";
@@ -51,6 +59,11 @@ import type {
 import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
 import type { TerminalActivity } from "@getpaseo/protocol/terminal-activity";
 import type { BinaryFrame } from "@getpaseo/protocol/binary-frames/index";
+import {
+  encodePluginEventFrame,
+  encodePluginOutputFrame,
+  PluginFrameOpcode,
+} from "@getpaseo/protocol/binary-frames/index";
 import { CursorError } from "./pagination/cursor.js";
 import { SortablePager, type SortSpec } from "./pagination/sortable-pager.js";
 import { matchesAgentHistoryQuery } from "./agent-history-search.js";
@@ -85,11 +98,12 @@ import {
   createWorkspaceScriptsService,
   type WorkspaceScriptsService,
 } from "./session/workspace-scripts/workspace-scripts-service.js";
-import type { DaemonConfigStore } from "./daemon-config-store.js";
+import { toWireDaemonConfig, type DaemonConfigStore } from "./daemon-config-store.js";
 import { releaseWorkspaceServicePortPlan } from "./workspace-service-port-registry.js";
 import { getErrorMessage, getErrorMessageOr } from "@getpaseo/protocol/error-utils";
 import { getAgentStatusPriority } from "@getpaseo/protocol/agent-state-bucket";
 import { getParentAgentIdFromLabels } from "@getpaseo/protocol/agent-labels";
+import { applyRecordPatch } from "./record-patch.js";
 import type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.js";
 import type { ProjectUpdate } from "./workspace-reconciliation-service.js";
 import {
@@ -119,7 +133,13 @@ import type {
   ManagedAgent,
 } from "./agent/agent-manager.js";
 import { createAgentCommand } from "./agent/create-agent/create.js";
-import { resolveCreateAgentIntent, type CreateAgentIntent } from "./agent/create-agent/intent.js";
+import {
+  inheritAgentBackground,
+  inheritWorkspaceBackground,
+  resolveCreateAgentIntent,
+  type CreateAgentIntent,
+  type CreateAgentCaller,
+} from "./agent/create-agent/intent.js";
 import {
   archiveAgentCommand,
   cancelAgentRunCommand,
@@ -149,6 +169,7 @@ import {
   listImportableProviderSessions,
   normalizeImportAgentRequest,
 } from "./agent/import-sessions.js";
+import { listProjectSuggestions, ProjectSuggestionsRequestError } from "./project-suggestions.js";
 import {
   checkoutLiteFromGitSnapshot,
   checkoutFromPersistedWorkspacePlacement,
@@ -265,6 +286,10 @@ import {
   handleWorkspaceSetupRunRequest as handleWorkspaceSetupRunRequestMessage,
 } from "./worktree-session.js";
 import { archiveByScope, type ActiveWorkspaceRef } from "./workspace-archive-service.js";
+import {
+  WorkspaceArchiveOperations,
+  type WorkspaceArchiveUndoInput,
+} from "./workspace-archive-operations.js";
 import { WorkspaceSetupRuntime } from "./workspace-setup-runtime.js";
 import { SessionAuthorization, type DaemonPermission } from "./authorization/index.js";
 
@@ -273,6 +298,12 @@ function resolveWorkspaceSetupRuntime(
 ): WorkspaceSetupRuntime {
   return runtime ?? new WorkspaceSetupRuntime();
 }
+
+function resolveWorkspaceArchiveOperations(
+  operations: WorkspaceArchiveOperations | undefined,
+): WorkspaceArchiveOperations {
+  return operations ?? new WorkspaceArchiveOperations();
+}
 import { WorktreeRequestError, toWorktreeWireError } from "./worktree-errors.js";
 import { parseGitRemoteLocation } from "@getpaseo/protocol/git-remote";
 import {
@@ -387,6 +418,7 @@ type CreateAgentRequestMessage = Extract<SessionInboundMessage, { type: "create_
 interface ResolvedSessionCreateAgentIntent {
   config: AgentSessionConfig;
   intent: CreateAgentIntent;
+  background: boolean;
   createdDirectoryWorkspace: boolean;
 }
 
@@ -475,6 +507,7 @@ export interface SessionOptions {
   creationService: Pick<CreationService, "create" | "subscribe">;
   projectRegistry: ProjectRegistry;
   workspaceRegistry: WorkspaceRegistry;
+  workspaceBaseBranch?: WorkspaceBaseBranchService;
   directorySync?: DirectorySyncService;
   workspaceLabelService?: WorkspaceLabelService;
   filesystem?: SessionFileSystem;
@@ -526,6 +559,11 @@ export interface SessionOptions {
     subscribeSettings?(listener: (pluginId: string, settingsId: string) => void): () => void;
     catalog(): Array<{ id: string; clientBundle: string; clientBundleHash?: string }>;
     invokePluginRpc(pluginId: string, method: string, input: unknown): Promise<unknown>;
+    subscribePluginRpc(
+      pluginId: string,
+      method: string,
+      input: unknown,
+    ): import("./plugins/runtime-subscription.js").PluginRuntimeSubscription;
     listUsageReports(options?: {
       forceRefresh?: boolean;
       reportIds?: string[];
@@ -546,6 +584,8 @@ export interface SessionOptions {
   scriptRuntimeStore?: WorkspaceScriptRuntimeStore;
   workspaceSetupObservation?: WorkspaceSetupObservation;
   workspaceSetupRuntime?: WorkspaceSetupRuntime;
+  /** Shared by every session so an undo from any connection reaches the archive it cancels. */
+  workspaceArchiveOperations?: WorkspaceArchiveOperations;
   onBranchChanged?: (
     workspaceId: string,
     oldBranch: string | null,
@@ -766,6 +806,7 @@ export class Session {
   private readonly gitMutation: GitMutationService;
   private readonly workspaceProvisioning: WorkspaceProvisioningService;
   private readonly workspaceRecovery: WorkspaceRecoveryService;
+  private workspaceBaseBranch: WorkspaceBaseBranchService | undefined;
   private readonly daemonConfigStore: DaemonConfigStore;
   private readonly pushNotifications: PushNotifications;
   private readonly pluginRuntime: SessionOptions["pluginRuntime"];
@@ -816,10 +857,12 @@ export class Session {
   private readonly workspaceSetupObservation: WorkspaceSetupObservation;
   private readonly unsubscribeSetupObservation: () => void;
   private readonly workspaceSetupRuntime: WorkspaceSetupRuntime;
+  private readonly workspaceArchiveOperations: WorkspaceArchiveOperations;
   private readonly workspaceGitObserver: WorkspaceGitObserverService;
   private readonly workspaceDirectory: WorkspaceDirectory;
   private readonly voiceSessions: VoiceSessions;
   private readonly checkoutSession: CheckoutSession;
+  private readonly diffSession: DiffSession;
   private readonly scheduleSession: ScheduleSession;
   private readonly providerCatalogSession: ProviderCatalogSession;
   private readonly usageSession: UsageSession;
@@ -881,6 +924,7 @@ export class Session {
       scriptRuntimeStore,
       workspaceSetupObservation,
       workspaceSetupRuntime,
+      workspaceArchiveOperations,
       onBranchChanged,
       getDaemonTcpPort,
       getDaemonTcpHost,
@@ -931,7 +975,7 @@ export class Session {
     this.workspaceFilesSession = new WorkspaceFilesSession({
       host: {
         emit: (msg, source) => this.emitForSource(msg, source),
-        emitBinary: (frame, source) => this.emitBinaryForFileTransfer(frame, source),
+        emitBinary: (frame, source) => this.emitBinaryReply(frame, source),
         hasBinaryChannel: () => this.onBinaryMessage !== null,
       },
       downloadTokenStore,
@@ -949,12 +993,22 @@ export class Session {
     this.renameCurrentBranch = renameCurrentBranch ?? renameCurrentBranchDefault;
     this.workspaceGitService = workspaceGitService;
     this.workspaceRuntimeStore = workspaceRuntimeStore;
+    this.workspaceBaseBranch =
+      options.workspaceBaseBranch ??
+      createWorkspaceBaseBranchService({
+        paseoHome: this.paseoHome,
+        worktreesRoot: this.worktreesRoot,
+        workspaceRegistry: this.workspaceRegistry,
+        workspaceGitService: this.workspaceGitService,
+      });
+
     this.gitMutation = createGitMutationService({
       workspaceGitService: this.workspaceGitService,
       logger: this.sessionLogger,
     });
     this.workspaceAutoName = workspaceAutoName;
     this.workspaceProvisioning = createWorkspaceProvisioningService({
+      withCheckoutLock: this.workspaceBaseBranch.withCheckoutLock,
       lifecycle: this.pluginRuntime,
       serverId,
       workspaceRegistry: this.workspaceRegistry,
@@ -973,6 +1027,7 @@ export class Session {
         await this.workspaceProvisioning.ensureWorkspaceRecordUnarchived(workspace);
       },
     });
+    this.diffSession = new DiffSession(checkoutDiffManager.streams, this.sessionLogger);
     this.checkoutSession = new CheckoutSession({
       host: {
         emit: (msg) => this.emit(msg),
@@ -1041,7 +1096,7 @@ export class Session {
         supportsProviderSnapshotReferences: () =>
           this.supports(CLIENT_CAPS.providerSnapshotReferences),
         listProviderAvailability: () => this.agentManager.listProviderAvailability(),
-        listDraftFeatures: (config) => this.agentManager.listDraftFeatures(config),
+        listDraftControls: (config) => this.agentManager.listDraftControls(config),
       },
       providerSnapshotManager,
       logger: this.sessionLogger,
@@ -1071,8 +1126,7 @@ export class Session {
         setMode: async (agentId, modeId) =>
           (await setAgentModeCommand({ agentManager }, { agentId, modeId })).notice,
         setModel: (agentId, modelId) => agentManager.setAgentModel(agentId, modelId),
-        setFeature: (agentId, featureId, value) =>
-          agentManager.setAgentFeature(agentId, featureId, value),
+        setOptions: (agentId, patch) => agentManager.setAgentOptions(agentId, patch),
         setThinking: (agentId, thinkingOptionId) =>
           agentManager.setAgentThinkingOption(agentId, thinkingOptionId),
       },
@@ -1116,7 +1170,8 @@ export class Session {
       getTerminalsUnavailable: () => terminalManager?.getUnavailableError?.()?.message ?? null,
       listAgents: () => this.agentManager.listAgents(),
       listProjects: () => this.projectRegistry.list(),
-      listWorkspaces: () => this.workspaceRegistry.list(),
+      // Diagnostics report both the active count and total archived history.
+      listWorkspaces: () => this.workspaceRegistry.listAll(),
       logger: this.sessionLogger,
       hubRelationships: options.hubRelationships,
       reloadConfig: () => daemonConfigStore.reload(),
@@ -1140,6 +1195,12 @@ export class Session {
       isPathWithinRoot: (rootPath, candidatePath) => this.isPathWithinRoot(rootPath, candidatePath),
       sessionLogger: this.sessionLogger,
       listTerminalWorkspaceRefs: () => this.listActiveWorkspaceRefs(),
+      isScriptTerminal: (terminal) =>
+        this.scriptRuntimeStore
+          ?.listForWorkspace(terminal.workspaceId)
+          .some((script) => script.terminalId === terminal.id) ?? false,
+      subscribeTerminalMetadata: (listener) =>
+        this.scriptRuntimeStore?.subscribe(listener) ?? (() => {}),
       getClientBufferedAmount: (source) => this.getTransportBufferedAmount(source),
     });
     this.agentDirectory = new AgentDirectory({
@@ -1156,8 +1217,8 @@ export class Session {
         ),
     });
     this.agentUpdates = createAgentUpdatesService({
-      includesWorkspace: (agent, includeBackground) =>
-        this.agentDirectory.includes(agent, includeBackground),
+      includesWorkspace: (agent, backgroundVisibility) =>
+        this.agentDirectory.includes(agent, backgroundVisibility),
       emit: (message) => this.emit(message),
       enrichAgentPayload: (payload) => this.enrichAgentPayload(payload),
       buildStoredAgentPayload: (record) => this.buildStoredAgentPayload(record),
@@ -1217,6 +1278,7 @@ export class Session {
       },
     );
     this.workspaceSetupRuntime = resolveWorkspaceSetupRuntime(workspaceSetupRuntime);
+    this.workspaceArchiveOperations = resolveWorkspaceArchiveOperations(workspaceArchiveOperations);
     this.getDaemonTcpPort = getDaemonTcpPort ?? null;
     this.getDaemonTcpHost = getDaemonTcpHost ?? null;
     this.serviceProxyPublicBaseUrl = serviceProxyPublicBaseUrl ?? null;
@@ -1247,8 +1309,10 @@ export class Session {
       logger: this.sessionLogger,
       projectRegistry: this.projectRegistry,
       workspaceRegistry: this.workspaceRegistry,
-      listAgentPayloads: () => this.listAgentPayloads({ includeBackground: true }),
-      workspaceLastUserMessageTimes: () => this.agentDirectory.workspaceLastUserMessageTimes(),
+      listAgentPayloads: (workspaceIds) =>
+        this.listAgentPayloads({ workspaceIds, includeBackground: true, includeAncestors: true }),
+      workspaceLastUserMessageTimes: (workspaceIds) =>
+        this.agentDirectory.workspaceLastUserMessageTimes(workspaceIds),
       listProviderSubagentActivity: async () => this.agentManager.listProviderSubagentActivity(),
       listTerminalActivityContributions: () => this.listTerminalActivityContributions(),
       isProviderVisibleToClient: (provider) => this.isProviderVisibleToClient(provider),
@@ -1349,6 +1413,72 @@ export class Session {
     this.refreshObservationProducers();
   }
 
+  private async compareTimelineCursors(
+    agentIds: string[],
+    cursors: Record<string, AgentTimelineCursor>,
+    source?: object,
+  ): Promise<Record<string, "current" | "behind">> {
+    const timelines: Record<string, "current" | "behind"> = {};
+    for (const agentId of agentIds) {
+      const cursor = cursors[agentId];
+      if (!cursor) continue;
+      const head = await this.agentManager.getLoadedTimelineHead(agentId);
+      // The client holds the epoch it was sent, which for a client that cannot apply rewinds
+      // changes with every retirement.
+      const epoch = head ? this.wireEpoch(head.epoch, head.retirementCount, source) : null;
+      timelines[agentId] =
+        head && epoch === cursor.epoch && head.seq === cursor.seq ? "current" : "behind";
+    }
+    return timelines;
+  }
+
+  private async answerTimelineFreshness(
+    agentIds: string[],
+    cursors: Record<string, AgentTimelineCursor>,
+    source?: object,
+  ): Promise<{
+    timelines: Record<string, "current" | "behind">;
+    agents: Record<string, AgentSnapshotPayload>;
+  }> {
+    const snapshots = await Promise.all(
+      agentIds.flatMap((agentId) => {
+        const agent = cursors[agentId] ? this.agentManager.getAgent(agentId) : null;
+        return agent ? [this.buildAgentPayload(agent)] : [];
+      }),
+    );
+    // Compared after the await, so a row appended while reading the snapshots answers behind.
+    const timelines = await this.compareTimelineCursors(agentIds, cursors, source);
+    const agents: Record<string, AgentSnapshotPayload> = {};
+    for (const snapshot of snapshots) {
+      if (timelines[snapshot.id] === "current") agents[snapshot.id] = snapshot;
+    }
+    return { timelines, agents };
+  }
+
+  private async handleAgentTimelineSubscription(
+    msg: Extract<SessionInboundMessage, { type: "agent.timeline.set_subscription.request" }>,
+    source?: object,
+  ): Promise<void> {
+    const agentIds = [...new Set(msg.agentIds)].sort();
+    // Attach before comparing: a row appended after the comparison reaches this owner live.
+    const owner = this.subscribeAgentTimelines(agentIds);
+    const freshness = msg.cursors
+      ? await this.answerTimelineFreshness(agentIds, msg.cursors, source)
+      : {};
+    this.emitForSource(
+      {
+        type: "agent.timeline.set_subscription.response",
+        payload: {
+          agentIds,
+          requestId: msg.requestId,
+          subscriptionId: owner.responseId,
+          ...freshness,
+        },
+      },
+      source,
+    );
+  }
+
   private subscribeAgentTimelines(agentIds: string[]): OwnedSubscription {
     const owner = this.delivery.begin("timelines", undefined, (id) => {
       this.timelineSubscriptions.delete(id);
@@ -1748,7 +1878,8 @@ export class Session {
       this.wantsEvent("agent_attention_required") ||
       this.wantsEvent("agent_permission_request") ||
       this.wantsEvent("agent_permission_resolved") ||
-      this.wantsEvent("agent.provider_subagents.update");
+      this.wantsEvent("agent.provider_subagents.update") ||
+      this.wantsEvent("agent.background_work.update");
     if (agents && !this.unsubscribeAgentEvents) this.subscribeToAgentEvents();
     if (!agents) {
       this.unsubscribeAgentEvents?.();
@@ -1888,11 +2019,19 @@ export class Session {
       if (this.isCleanedUp) {
         return;
       }
-      const projectWorkspaceIds = (await this.workspaceRegistry.list())
+      const projectWorkspaceIds = (await this.workspaceRegistry.listActive())
         .filter((workspace) => workspace.projectId === mutation.projectId)
         .map((workspace) => workspace.workspaceId);
 
       if (mutation.kind === "remove") {
+        // Archived workspaces can still represent an empty project in this subscription.
+        for (const [workspaceId, update] of subscription.lastEmittedByWorkspaceId) {
+          const projectId =
+            update.kind === "upsert" ? update.workspace.projectId : update.emptyProject?.projectId;
+          if (projectId === mutation.projectId && !projectWorkspaceIds.includes(workspaceId)) {
+            projectWorkspaceIds.push(workspaceId);
+          }
+        }
         const visibleWorkspaceIds = projectWorkspaceIds.filter((workspaceId) => {
           const lastEmitted = subscription.lastEmittedByWorkspaceId.get(workspaceId);
           return (
@@ -2065,14 +2204,12 @@ export class Session {
         }
 
         if (event.type === "provider_subagent") {
-          // The subagents track of an internal parent stays hidden.
-          const parentAgentId =
-            event.event.type === "upsert"
-              ? event.event.subagent.parentAgentId
-              : event.event.parentAgentId;
-          if (this.agentManager.getAgent(parentAgentId)?.internal) return;
-          this.emitProviderSubagentWorkspaceUpdate(event.event);
-          this.forwardProviderSubagentUpdate(event.event);
+          this.forwardProviderSubagent(event.event);
+          return;
+        }
+
+        if (event.type === "background_work") {
+          this.forwardBackgroundWork(event);
           return;
         }
 
@@ -2147,6 +2284,26 @@ export class Session {
     );
   }
 
+  private forwardProviderSubagent(event: ProviderSubagentManagerEvent): void {
+    const parentAgentId =
+      event.type === "upsert" ? event.subagent.parentAgentId : event.parentAgentId;
+    if (this.agentManager.getAgent(parentAgentId)?.internal) return;
+    this.emitProviderSubagentWorkspaceUpdate(event);
+    this.forwardProviderSubagentUpdate(event);
+  }
+
+  private forwardBackgroundWork(
+    event: Extract<AgentManagerEvent, { type: "background_work" }>,
+  ): void {
+    const agent = this.agentManager.getAgent(event.agentId);
+    if (agent?.internal) return;
+    this.emit({
+      type: "agent.background_work.update",
+      payload: { agentId: event.agentId, items: event.items },
+    });
+    if (agent) void this.agentUpdates.forwardLiveAgent(agent);
+  }
+
   private emitProviderSubagentWorkspaceUpdate(event: ProviderSubagentManagerEvent): void {
     if (event.type === "timeline") {
       return;
@@ -2179,6 +2336,7 @@ export class Session {
   }
 
   private async enrichAgentPayload(payload: AgentSnapshotPayload): Promise<AgentSnapshotPayload> {
+    payload.backgroundWork = this.agentManager.getAgentBackgroundWorkSummary(payload.id);
     const storedRecord = await this.agentStorage.get(payload.id);
     payload.title = storedRecord?.title ?? null;
     payload.archivedAt = storedRecord?.archivedAt ?? null;
@@ -2195,6 +2353,7 @@ export class Session {
       agentManager: this.agentManager,
       agentStorage: this.agentStorage,
       logger: this.sessionLogger,
+      purpose: "history",
     });
     return source.kind === "live"
       ? await this.buildAgentPayload(source.agent)
@@ -2205,7 +2364,9 @@ export class Session {
     record: StoredAgentRecord,
     registeredProviderIds = new Set(this.providerSnapshotManager.listRegisteredProviderIds()),
   ): AgentSnapshotPayload {
-    return buildStoredAgentPayload(record, registeredProviderIds);
+    return buildStoredAgentPayload(record, registeredProviderIds, (provider, own) =>
+      this.agentManager.effectiveOptionsFor(provider, own),
+    );
   }
 
   private isProviderVisibleToClient(provider: string): boolean {
@@ -2271,13 +2432,15 @@ export class Session {
       this.peakInflightRequests = this.inflightRequests;
     }
     try {
-      this.sessionLogger.trace(
-        {
-          messageType: msg.type,
-          payloadBytes: JSON.stringify(msg).length,
-        },
-        "agent.session.inbound",
-      );
+      // Stringifying a binary plugin input costs its size; test logger stubs lack isLevelEnabled.
+      if (this.sessionLogger.isLevelEnabled?.("trace"))
+        this.sessionLogger.trace(
+          {
+            messageType: msg.type,
+            payloadBytes: JSON.stringify(msg).length,
+          },
+          "agent.session.inbound",
+        );
       if (!this.authorization.allowsInbound(msg)) {
         const requestId = sessionRequestId(msg);
         if (requestId) {
@@ -2342,6 +2505,17 @@ export class Session {
           this.sessionLogger.error({ err: error }, "Failed to release revoked browser hosting"),
         );
     }
+    // Binary plugin events skip the outbound permission check, so revocation ends the streams.
+    if (!this.authorization.allowsPermission("daemon.manage")) {
+      void this.delivery
+        .releaseFamily("plugin-rpc")
+        .catch((error) =>
+          this.sessionLogger.error(
+            { err: error },
+            "Failed to release revoked plugin subscriptions",
+          ),
+        );
+    }
   }
 
   public getPermissions(): DaemonPermission[] {
@@ -2504,6 +2678,7 @@ export class Session {
       this.dispatchOrchestrationSkillsMessage(msg) ??
       this.dispatchPluginDirectoryMessage(msg) ??
       this.dispatchPluginMessage(msg) ??
+      this.dispatchPluginRpcMessage(msg) ??
       this.dispatchHostServiceMessage(msg) ??
       this.dispatchMiscMessage(msg);
     if (promise) await promise;
@@ -2533,10 +2708,22 @@ export class Session {
       this.dispatchWorkspaceStateMessage(msg) ??
       this.dispatchWorkspaceLabelMessage(msg) ??
       this.dispatchWorkspaceSetupMessage(msg) ??
+      this.dispatchMetadataMessage(msg) ??
       this.dispatchWorkspaceAndProjectMessage(msg)
     );
   }
 
+  private dispatchMetadataMessage(msg: SessionInboundMessage): Promise<void> | undefined {
+    switch (msg.type) {
+      case "agent.metadata.update.request":
+        return this.handleAgentMetadataUpdateRequest(msg);
+      case "workspace.metadata.update.request":
+        return this.handleWorkspaceMetadataUpdateRequest(msg);
+      default:
+        return undefined;
+    }
+  }
+
   private dispatchOrchestrationSkillsMessage(
     msg: SessionInboundMessage,
   ): Promise<void> | undefined {
@@ -2671,21 +2858,98 @@ export class Session {
       });
       return undefined;
     }
+    return undefined;
+  }
+
+  private dispatchPluginRpcMessage(msg: SessionInboundMessage): Promise<void> | undefined {
     if (msg.type === "plugin.rpc.invoke.request") {
       if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
       return this.pluginRuntime
         .invokePluginRpc(msg.pluginId, msg.method, msg.input)
-        .then((output) => {
-          this.emit({
-            type: "plugin.rpc.invoke.response",
-            payload: { requestId: msg.requestId, output },
-          });
-          return undefined;
-        });
+        .then((output) => this.replyPluginRpc(msg, output));
     }
+    if (msg.type === "plugin.rpc.subscribe.request") return this.subscribePluginRpc(msg);
     return undefined;
   }
 
+  /** A `Uint8Array` output is the binary form of `plugin.rpc.invoke.response`. */
+  private async replyPluginRpc(
+    request: Extract<SessionInboundMessage, { type: "plugin.rpc.invoke.request" }>,
+    output: unknown,
+  ): Promise<void> {
+    const response: SessionOutboundMessage = {
+      type: "plugin.rpc.invoke.response",
+      payload: { requestId: request.requestId, output },
+    };
+    if (!(output instanceof Uint8Array)) {
+      this.emit(response);
+      return;
+    }
+    // The frame is the binary form of the response, so it needs the response's permission.
+    if (!this.authorization.allowsOutbound(response)) return;
+    if (!this.supports(CLIENT_CAPS.pluginBinaryPayloads) || this.onBinaryMessage === null)
+      throw new Error(
+        `Update Paseo to receive the binary output of plugin RPC ${request.pluginId}.${request.method}`,
+      );
+    await this.emitBinaryReply(
+      encodePluginOutputFrame(request.requestId, output),
+      this.delivery.currentSource,
+    );
+  }
+
+  private async subscribePluginRpc(
+    request: Extract<SessionInboundMessage, { type: "plugin.rpc.subscribe.request" }>,
+  ): Promise<void> {
+    if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
+    const subscription = this.pluginRuntime.subscribePluginRpc(
+      request.pluginId,
+      request.method,
+      request.input,
+    );
+    const owner = this.delivery.begin("plugin-rpc", undefined, () => subscription.release());
+    try {
+      await subscription.ready;
+    } catch (error) {
+      await owner.release();
+      throw error;
+    }
+    if (owner.signal.aborted) return;
+    this.emit({
+      type: "plugin.rpc.subscribe.response",
+      payload: { requestId: request.requestId, subscriptionId: owner.responseId },
+    });
+    const close = (reason?: string) => {
+      owner.emit({
+        type: "plugin.rpc.closed",
+        payload: {
+          subscriptionId: owner.responseId,
+          ...(reason === undefined ? {} : { error: reason }),
+        },
+      });
+      void owner.release().catch(() => undefined);
+    };
+    subscription.attach({
+      event: (event) => {
+        const message: SessionOutboundMessage = {
+          type: "plugin.rpc.event",
+          payload: { subscriptionId: owner.responseId, event },
+        };
+        if (!(event instanceof Uint8Array)) {
+          owner.emit(message);
+          return;
+        }
+        if (!this.authorization.allowsOutbound(message)) return;
+        if (this.onBinaryMessage === null) {
+          subscription.release();
+          close("This connection cannot carry binary plugin events");
+          return;
+        }
+        owner.emitBinary(encodePluginEventFrame(owner.responseId, event));
+      },
+      closed: close,
+    });
+  }
+
   private dispatchPluginDirectoryMessage(msg: SessionInboundMessage): Promise<void> | undefined {
     if (msg.type === "plugin.source.install.request") {
       if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
@@ -2864,6 +3128,10 @@ export class Session {
         return this.handleAgentTimelineListPromptsRequest(msg, source);
       case "agent.provider_subagents.list.request":
         return this.handleProviderSubagentListRequest(msg);
+      case "agent.background_work.list.request":
+        return this.handleAgentBackgroundWorkListRequest(msg);
+      case "agent.background_work.stop.request":
+        return this.handleAgentBackgroundWorkStopRequest(msg);
       case "agent.provider_subagents.timeline.get.request":
         return this.handleProviderSubagentTimelineRequest(msg, source);
       case "session.events.set_subscription.request": {
@@ -2892,18 +3160,8 @@ export class Session {
           throw error;
         });
       }
-      case "agent.timeline.set_subscription.request": {
-        const agentIds = [...new Set(msg.agentIds)].sort();
-        const owner = this.subscribeAgentTimelines(agentIds);
-        this.emitForSource(
-          {
-            type: "agent.timeline.set_subscription.response",
-            payload: { agentIds, requestId: msg.requestId, subscriptionId: owner.responseId },
-          },
-          source,
-        );
-        return undefined;
-      }
+      case "agent.timeline.set_subscription.request":
+        return this.handleAgentTimelineSubscription(msg, source);
       case "agent.fork_context.request":
         return this.handleAgentForkContextRequest(msg);
       default:
@@ -3000,7 +3258,10 @@ export class Session {
       case "get_daemon_config_request":
         this.emit({
           type: "get_daemon_config_response",
-          payload: { requestId: msg.requestId, config: this.daemonConfigStore.get() },
+          payload: {
+            requestId: msg.requestId,
+            config: toWireDaemonConfig(this.daemonConfigStore.get()),
+          },
         });
         return undefined;
       case "daemon.get_status.request":
@@ -3024,7 +3285,7 @@ export class Session {
             type: "set_daemon_config_response",
             payload: {
               requestId: msg.requestId,
-              config,
+              config: toWireDaemonConfig(config),
             },
           });
         });
@@ -3040,6 +3301,10 @@ export class Session {
   // eslint-disable-next-line complexity
   private dispatchCheckoutMessage(msg: SessionInboundMessage): Promise<void> | undefined {
     switch (msg.type) {
+      case "diff.subscribe.request":
+        return this.diffSession.subscribe(msg, this.delivery, (reply) => this.emit(reply));
+      case "diff.unsubscribe.request":
+        return this.delivery.release(msg.subscriptionId);
       case "checkout_status_request":
         return this.checkoutSession.handleStatusRequest(msg);
       case "checkout.commits.list.request":
@@ -3112,6 +3377,8 @@ export class Session {
         return this.handleFetchWorkspacesRequest(msg);
       case "project.list.request":
         return this.handleProjectListRequest(msg);
+      case "project.suggestions.request":
+        return this.handleProjectSuggestionsRequest(msg);
       case "paseo_worktree_list_request":
         return this.handlePaseoWorktreeListRequest(msg);
       case "paseo_worktree_archive_request":
@@ -3141,6 +3408,8 @@ export class Session {
         return this.handleWorkspaceTitleSetRequest(msg.workspaceId, msg.title, msg.requestId);
       case "workspace.pin.set.request":
         return this.handleWorkspacePinSetRequest(msg.workspaceId, msg.pinned, msg.requestId);
+      case "workspace.base_branch.set.request":
+        return this.handleWorkspaceBaseBranchSetRequest(msg);
       default:
         return undefined;
     }
@@ -3214,6 +3483,8 @@ export class Session {
         return this.handleWorkspaceRecoveryInspectRequest(msg);
       case "workspace.recovery.restore.request":
         return this.handleWorkspaceRecoveryRestoreRequest(msg);
+      case "workspace.archive.undo.request":
+        return this.handleWorkspaceArchiveUndoRequest(msg);
       case "workspace.clear_attention.request":
         return this.handleWorkspaceClearAttentionRequest(msg);
       case "workspace.mark_unread.request":
@@ -3231,6 +3502,8 @@ export class Session {
         return this.providerCatalogSession.handleListProviderModesRequest(msg);
       case "list_provider_features_request":
         return this.providerCatalogSession.handleListProviderFeaturesRequest(msg);
+      case "provider.controls.list.request":
+        return this.providerCatalogSession.handleProviderControlsListRequest(msg);
       case "list_available_providers_request":
         return this.providerCatalogSession.handleListAvailableProvidersRequest(msg);
       case "get_providers_snapshot_request":
@@ -3322,6 +3595,22 @@ export class Session {
       this.connectedHostSession?.binary(binaryFrame.frame, source);
       return;
     }
+    if (binaryFrame.kind === "plugin") {
+      const frame = binaryFrame.frame;
+      // The binary form of plugin.rpc.invoke.request; it authorizes and replies like the JSON form.
+      if (frame.opcode !== PluginFrameOpcode.Input) return;
+      await this.handleMessage(
+        {
+          type: "plugin.rpc.invoke.request",
+          requestId: frame.requestId,
+          pluginId: frame.pluginId,
+          method: frame.method,
+          input: frame.payload,
+        },
+        source,
+      );
+      return;
+    }
     if (!this.authorization.allowsPermission("workspace.write")) {
       return;
     }
@@ -3329,7 +3618,9 @@ export class Session {
       await this.workspaceFilesSession.handleFileTransferFrame(binaryFrame.frame, source);
       return;
     }
-    this.terminalController.handleBinaryFrame(binaryFrame.frame, source);
+    if (binaryFrame.kind === "terminal") {
+      this.terminalController.handleBinaryFrame(binaryFrame.frame, source);
+    }
   }
 
   private async handleRestartServerRequest(
@@ -3728,7 +4019,7 @@ export class Session {
 
       // Re-emit descriptors for every workspace under this project so the new
       // resolved name lands in the UI immediately.
-      const workspaces = await this.workspaceRegistry.list();
+      const workspaces = await this.workspaceRegistry.listActive();
       const affectedWorkspaceIds = workspaces
         .filter((workspace) => workspace.projectId === existing.projectId)
         .map((workspace) => workspace.workspaceId);
@@ -3780,7 +4071,7 @@ export class Session {
       });
       await this.emitProjectUpdate({ kind: "upsert", project: updated });
 
-      const affectedWorkspaceIds = (await this.workspaceRegistry.list())
+      const affectedWorkspaceIds = (await this.workspaceRegistry.listActive())
         .filter((workspace) => workspace.projectId === projectId)
         .map((workspace) => workspace.workspaceId);
       if (affectedWorkspaceIds.length > 0) {
@@ -3826,7 +4117,7 @@ export class Session {
     try {
       const project = await this.projectRegistry.get(projectId);
       const resolvedProjectId = project?.projectId ?? projectId;
-      const projectWorkspaces = (await this.workspaceRegistry.list()).filter(
+      const projectWorkspaces = (await this.workspaceRegistry.listActive()).filter(
         (workspace) => workspace.projectId === resolvedProjectId,
       );
       const activeWorkspaceIds = projectWorkspaces
@@ -3988,6 +4279,114 @@ export class Session {
     }
   }
 
+  private async handleAgentMetadataUpdateRequest(
+    request: Extract<SessionInboundMessage, { type: "agent.metadata.update.request" }>,
+  ): Promise<void> {
+    const { agentId, patch, requestId } = request;
+    this.sessionLogger.info({ agentId, requestId }, "session: agent.metadata.update.request");
+    try {
+      const metadata = await this.agentManager.setMetadata(agentId, patch);
+      this.emit({
+        type: "agent.metadata.update.response",
+        payload: { requestId, agentId, accepted: true, metadata, error: null },
+      });
+    } catch (error) {
+      this.sessionLogger.error(
+        { err: error, agentId, requestId },
+        "session: agent.metadata.update.request error",
+      );
+      this.emit({
+        type: "agent.metadata.update.response",
+        payload: {
+          requestId,
+          agentId,
+          accepted: false,
+          metadata: null,
+          error: getErrorMessageOr(error, "Failed to update agent metadata"),
+        },
+      });
+    }
+  }
+
+  private async handleWorkspaceMetadataUpdateRequest(
+    request: Extract<SessionInboundMessage, { type: "workspace.metadata.update.request" }>,
+  ): Promise<void> {
+    const { workspaceId, patch, requestId } = request;
+    this.sessionLogger.info(
+      { workspaceId, requestId },
+      "session: workspace.metadata.update.request",
+    );
+    const reject = (error: string) =>
+      this.emit({
+        type: "workspace.metadata.update.response",
+        payload: { requestId, workspaceId, accepted: false, metadata: null, error },
+      });
+    try {
+      const updatedAt = new Date().toISOString();
+      const updated = await this.workspaceRegistry.update(workspaceId, (existing) => ({
+        ...existing,
+        metadata: applyRecordPatch(existing.metadata, patch),
+        updatedAt,
+      }));
+      if (!updated) {
+        reject("Workspace not found");
+        return;
+      }
+      this.emit({
+        type: "workspace.metadata.update.response",
+        payload: {
+          requestId,
+          workspaceId,
+          accepted: true,
+          metadata: updated.metadata,
+          error: null,
+        },
+      });
+      await this.emitWorkspaceUpdatesForWorkspaceIds([workspaceId]);
+    } catch (error) {
+      this.sessionLogger.error(
+        { err: error, workspaceId, requestId },
+        "session: workspace.metadata.update.request error",
+      );
+      reject(getErrorMessageOr(error, "Failed to update workspace metadata"));
+    }
+  }
+
+  private async handleWorkspaceBaseBranchSetRequest(
+    msg: WorkspaceBaseBranchSetRequest,
+  ): Promise<void> {
+    try {
+      this.workspaceBaseBranch ??= createWorkspaceBaseBranchService({
+        paseoHome: this.paseoHome,
+        worktreesRoot: this.worktreesRoot,
+        workspaceRegistry: this.workspaceRegistry,
+        workspaceGitService: this.workspaceGitService,
+      });
+      const baseRef = await this.workspaceBaseBranch.setBaseBranch(msg);
+      this.emit({
+        type: "workspace.base_branch.set.response",
+        payload: {
+          requestId: msg.requestId,
+          workspaceId: msg.workspaceId,
+          accepted: true,
+          baseRef,
+          error: null,
+        },
+      });
+    } catch (error) {
+      this.emit({
+        type: "workspace.base_branch.set.response",
+        payload: {
+          requestId: msg.requestId,
+          workspaceId: msg.workspaceId,
+          accepted: false,
+          baseRef: null,
+          error: getErrorMessage(error),
+        },
+      });
+    }
+  }
+
   private async handleWorkspacePinSetRequest(
     workspaceId: string,
     pinned: boolean,
@@ -4457,14 +4856,6 @@ export class Session {
       throw new Error(
         "Public internal agents were removed; create a background workspace instead.",
       );
-    if (
-      request.background !== undefined &&
-      (request.workspaceId || (request.callerAgentId && !request.worktree))
-    ) {
-      throw new Error(
-        "background is workspace creation intent; configure the selected workspace at creation.",
-      );
-    }
   }
 
   private async createSessionAgent(
@@ -4515,8 +4906,7 @@ export class Session {
         cwd: config.cwd,
         target: worktree,
         firstAgentContext,
-        background: msg.background,
-        callerWorkspaceId: this.getCallerWorkspaceId(msg.callerAgentId),
+        ...(await this.workspaceBackgroundIntent(msg.background, msg.callerAgentId)),
       });
       createdWorktreeForCleanup = createdWorktree;
       const resolvedIntent = await this.resolveSessionCreateAgentIntent({
@@ -4547,6 +4937,7 @@ export class Session {
           agentId,
           config: resolvedIntent.config,
           workspaceId: resolvedIntent.intent.workspaceId,
+          background: resolvedIntent.background,
           initialPrompt,
           source: msg.callerAgentId
             ? { kind: "agent-message", agentId: msg.callerAgentId }
@@ -4556,13 +4947,17 @@ export class Session {
           images,
           attachments,
           labels: resolvedIntent.intent.labels,
+          metadata: msg.metadata,
           env,
           provisionalTitle,
           firstAgentContext,
         },
       );
       createdAgentId = snapshot.id;
-      await this.agentUpdates.forwardLiveAgent(snapshot);
+      // `snapshot` predates the initial prompt; subscribers keep the last state they receive.
+      await this.agentUpdates.forwardLiveAgent(
+        this.agentManager.getAgent(snapshot.id) ?? liveSnapshot,
+      );
       if (resolvedIntent.createdDirectoryWorkspace && trimmedPrompt) {
         this.workspaceAutoName.scheduleForDirectory(
           {
@@ -4598,20 +4993,13 @@ export class Session {
     workspacePromptTitle: string | null;
   }): Promise<ResolvedSessionCreateAgentIntent> {
     const { request, createdWorktree } = input;
-    const callerAgent = request.callerAgentId
-      ? this.agentManager.getAgent(request.callerAgentId)
-      : null;
-    if (request.callerAgentId && !callerAgent) {
-      throw new Error(`Caller agent ${request.callerAgentId} not found`);
-    }
+    const callerAgent = await this.resolveCreationCaller(request.callerAgentId);
 
     let config = request.config;
 
     const intent = await resolveCreateAgentIntent({
       explicitWorkspaceId: createdWorktree?.workspace.workspaceId ?? request.workspaceId,
-      caller: callerAgent
-        ? { id: callerAgent.id, cwd: callerAgent.cwd, workspaceId: callerAgent.workspaceId }
-        : null,
+      caller: callerAgent,
       labels: request.labels,
       resolveWorkspace: async (workspaceId) => {
         if (createdWorktree?.workspace.workspaceId === workspaceId) {
@@ -4628,7 +5016,7 @@ export class Session {
           createdWorktree: null,
           cwd: config.cwd,
           initialTitle: input.workspacePromptTitle,
-          background: request.background,
+          background: inheritWorkspaceBackground(request.background, callerAgent),
           callerWorkspaceId: callerAgent?.workspaceId,
         }),
         cwd: config.cwd,
@@ -4639,6 +5027,7 @@ export class Session {
     return {
       config,
       intent,
+      background: inheritAgentBackground(request.background, callerAgent),
       createdDirectoryWorkspace: !createdWorktree && !request.workspaceId && !callerAgent,
     };
   }
@@ -4682,7 +5071,12 @@ export class Session {
         : overrides;
       let snapshot: ManagedAgent;
       try {
-        snapshot = await this.agentManager.resumeAgentFromPersistence(handle, effectiveOverrides);
+        snapshot = await this.agentManager.resumeAgentFromPersistence(
+          handle,
+          effectiveOverrides,
+          undefined,
+          { workspaceId: matched?.record.workspaceId },
+        );
       } catch (error) {
         if (matched?.didUnarchive && matched.originalArchivedAt) {
           await this.agentManager.archiveSnapshot(matched.record.id, matched.originalArchivedAt);
@@ -5433,7 +5827,8 @@ export class Session {
       return { ok: true, agentId: trimmed };
     }
 
-    const stored = await this.agentStorage.list();
+    // Explicit identifier resolution admits archived agents by ID prefix.
+    const stored = await this.agentStorage.listAll();
     const storedRecords = stored.filter((record) => !record.internal);
     const knownIds = new Set<string>();
     for (const record of storedRecords) {
@@ -5545,7 +5940,7 @@ export class Session {
     Map<string, ProjectPlacementPayload>
   > {
     const [persistedWorkspaces, persistedProjects] = await Promise.all([
-      this.workspaceRegistry.list(),
+      this.workspaceRegistry.listActive(),
       this.projectRegistry.list(),
     ]);
     const activeProjects = new Map(
@@ -5618,7 +6013,22 @@ export class Session {
     return matchedEntries;
   }
 
-  private async listFetchAgentsEntries(request: AgentDirectoryRequestMessage): Promise<{
+  /**
+   * Inclusive discovery for the requesting source. Exact-ID reads never pass through this.
+   * COMPAT(backgroundAgents): added in v0.15.0, remove after 2027-05-03 once client floor
+   * >= v0.15.0. Sources without the capability see background workspaces' agents only.
+   */
+  private resolveBackgroundVisibility(
+    includeBackground: boolean | undefined,
+  ): BackgroundVisibility {
+    if (!includeBackground) return false;
+    return this.supports(CLIENT_CAPS.backgroundAgents) ? true : "workspaces";
+  }
+
+  private async listFetchAgentsEntries(
+    request: AgentDirectoryRequestMessage,
+    backgroundVisibility: BackgroundVisibility,
+  ): Promise<{
     entries: FetchAgentsResponseEntry[];
     pageInfo: FetchAgentsResponsePageInfo;
     searchTruncated?: boolean;
@@ -5634,9 +6044,7 @@ export class Session {
     let agents = await this.listAgentPayloads({
       labels: filter?.labels,
       includeArchived: filter?.includeArchived,
-      includeBackground:
-        filter?.includeBackground ||
-        (request.type === "fetch_agents_request" && request.includeBackground),
+      includeBackground: backgroundVisibility,
       includeUnavailablePersisted: request.type === "fetch_agent_history_request",
     });
     const activePlacementsByWorkspaceId =
@@ -5723,6 +6131,7 @@ export class Session {
             pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
             requiresAttention: agent.requiresAttention,
             attentionReason: agent.attentionReason ?? null,
+            backgroundWork: agent.backgroundWork,
           });
         case "created_at":
           return Date.parse(agent.createdAt);
@@ -5781,7 +6190,9 @@ export class Session {
       title: workspace.title,
       pinnedAt: workspace.pinnedAt,
       ...(workspace.labels && workspace.labels.length > 0 ? { labels: workspace.labels } : {}),
+      metadata: workspace.metadata,
       background: workspace.background,
+      parentWorkspaceId: workspace.parentWorkspaceId,
       archivingAt: null,
       status: "done",
       statusEnteredAt: null,
@@ -5870,6 +6281,7 @@ export class Session {
       projectKind: projectRecord?.kind ?? "git",
       workspaceKind: result.workspace.kind,
       background: result.workspace.background,
+      parentWorkspaceId: result.workspace.parentWorkspaceId,
       name: resolveWorkspaceName({
         title: result.workspace.title,
         derivedDisplayName: result.worktree.branchName || result.workspace.displayName,
@@ -5879,6 +6291,7 @@ export class Session {
       ...(result.workspace.labels && result.workspace.labels.length > 0
         ? { labels: result.workspace.labels }
         : {}),
+      metadata: result.workspace.metadata,
       archivingAt: null,
       status: "done",
       statusEnteredAt: result.workspace.createdAt,
@@ -5931,7 +6344,8 @@ export class Session {
   // than a workspaceId. This is a directory lookup for an archive target, not a
   // status/ownership attribution.
   private async findWorkspaceIdForCwd(cwd: string): Promise<string | null> {
-    const workspaces = await this.workspaceRegistry.list();
+    // Explicit archive administration must prefer an archived exact match to an active ancestor.
+    const workspaces = await this.workspaceRegistry.listAll();
     return resolveWorkspaceIdForPath(cwd, workspaces);
   }
 
@@ -6059,6 +6473,10 @@ export class Session {
 
   private async restoreWorkspaceAndEmit(workspaceId: string): Promise<void> {
     await this.workspaceRecovery.restore(workspaceId);
+    await this.publishRecoveredWorkspace(workspaceId);
+  }
+
+  private async publishRecoveredWorkspace(workspaceId: string): Promise<void> {
     const workspace = await this.workspaceRegistry.get(workspaceId);
     if (!workspace) {
       throw new Error(`Recovered workspace record not found: ${workspaceId}`);
@@ -6122,7 +6540,7 @@ export class Session {
   }
 
   private async listActiveWorkspaceRefs(): Promise<ActiveWorkspaceRef[]> {
-    const workspaces = await this.workspaceRegistry.list();
+    const workspaces = await this.workspaceRegistry.listActive();
     return workspaces
       .filter((workspace) => !workspace.archivedAt)
       .map((workspace) => ({
@@ -6148,7 +6566,7 @@ export class Session {
     }
 
     if (!existingWorkspace.archivedAt) {
-      const activeSiblings = (await this.workspaceRegistry.list()).filter(
+      const activeSiblings = (await this.workspaceRegistry.listActive()).filter(
         (workspace) => workspace.projectId === existingWorkspace.projectId && !workspace.archivedAt,
       );
       this.sessionLogger.info(
@@ -6353,7 +6771,7 @@ export class Session {
   // path. See `workspaceIdsOnCheckout`.
   private async emitWorkspaceUpdateForCwd(cwd: string, options?: {}): Promise<void> {
     if (this.workspaceUpdatesSubscriptions.size === 0) return;
-    const workspaceIds = workspaceIdsOnCheckout(await this.workspaceRegistry.list(), cwd);
+    const workspaceIds = workspaceIdsOnCheckout(await this.workspaceRegistry.listActive(), cwd);
     if (workspaceIds.length === 0) {
       return;
     }
@@ -6370,16 +6788,17 @@ export class Session {
         })
       : null;
     const subscriptionId = owner?.responseId;
+    const backgroundVisibility = this.resolveBackgroundVisibility(
+      request.includeBackground || request.filter?.includeBackground,
+    );
     try {
       if (owner) {
         this.agentUpdates.beginSubscription({
           subscriptionId: owner.id,
           isProviderVisible: (provider) =>
             this.delivery.forSource(owner.source, () => this.isProviderVisibleToClient(provider)),
-          filter: {
-            ...request.filter,
-            ...(request.includeBackground ? { includeBackground: true } : {}),
-          },
+          filter: request.filter,
+          backgroundVisibility,
           syncEnabled: Boolean(request.sync),
           emit: (message) => {
             if (message.type === "agent_update") owner.emit(message);
@@ -6389,8 +6808,8 @@ export class Session {
       }
 
       const payload = request.sync
-        ? await this.readAgentDirectorySync(request)
-        : await this.listFetchAgentsEntries(request);
+        ? await this.readAgentDirectorySync(request, backgroundVisibility)
+        : await this.listFetchAgentsEntries(request, backgroundVisibility);
       const snapshotUpdatedAtByAgentId = new Map<string, number>();
       for (const entry of payload.entries) {
         const parsedUpdatedAt = Date.parse(entry.agent.updatedAt);
@@ -6434,7 +6853,10 @@ export class Session {
     request: Extract<SessionInboundMessage, { type: "fetch_agent_history_request" }>,
   ): Promise<void> {
     try {
-      const payload = await this.listFetchAgentsEntries(request);
+      const payload = await this.listFetchAgentsEntries(
+        request,
+        this.resolveBackgroundVisibility(request.filter?.includeBackground),
+      );
       this.emit({
         type: "fetch_agent_history_response",
         payload: {
@@ -6628,6 +7050,37 @@ export class Session {
     }
   }
 
+  private async handleProjectSuggestionsRequest(
+    request: Extract<SessionInboundMessage, { type: "project.suggestions.request" }>,
+  ): Promise<void> {
+    try {
+      const result = await listProjectSuggestions({
+        request,
+        agentManager: this.agentManager,
+        projectRegistry: this.projectRegistry,
+        workspaceGitService: this.workspaceGitService,
+      });
+      this.emit({
+        type: "project.suggestions.response",
+        payload: { requestId: request.requestId, ...result },
+      });
+    } catch (error) {
+      this.sessionLogger.error({ err: error }, "Failed to handle project.suggestions.request");
+      this.emit({
+        type: "rpc_error",
+        payload: {
+          requestId: request.requestId,
+          requestType: request.type,
+          error: error instanceof Error ? error.message : "Failed to list project suggestions",
+          code:
+            error instanceof ProjectSuggestionsRequestError
+              ? error.code
+              : "project_suggestions_failed",
+        },
+      });
+    }
+  }
+
   private requireWorkspaceLabels(): WorkspaceLabelService {
     if (!this.workspaceLabelService) {
       throw new SessionRequestError("workspace_labels_unavailable", "Workspace labels unavailable");
@@ -6768,6 +7221,7 @@ export class Session {
 
   private async readAgentDirectorySync(
     request: Extract<SessionInboundMessage, { type: "fetch_agents_request" }>,
+    backgroundVisibility: BackgroundVisibility,
   ) {
     if (request.scope !== "active" || request.filter) {
       throw new SessionRequestError(
@@ -6775,19 +7229,19 @@ export class Session {
         "Sequenced agent directory reads require scope=active and no filter.",
       );
     }
-    const snapshot = await this.listFetchAgentsEntries({
-      ...request,
-      includeBackground: true,
-      page: { limit: Number.MAX_SAFE_INTEGER },
-    });
+    // The canonical collection is complete; only the read below is scoped.
+    const snapshot = await this.listFetchAgentsEntries(
+      { ...request, page: { limit: Number.MAX_SAFE_INTEGER } },
+      true,
+    );
     const result = this.directorySync.synchronizeAgents(
       snapshot.entries,
       request.sync ?? {},
-      request.includeBackground,
+      backgroundVisibility,
     );
     const entries = await Promise.all(
       result.entries.map(async (entry) =>
-        (await this.agentDirectory.includes(entry.agent, request.includeBackground)) ? entry : null,
+        (await this.agentDirectory.includes(entry.agent, backgroundVisibility)) ? entry : null,
       ),
     );
     return { ...result, entries: entries.filter((entry) => entry !== null) };
@@ -6888,11 +7342,34 @@ export class Session {
     }
   }
 
-  private getCallerWorkspaceId(callerAgentId?: string): string | undefined {
-    if (!callerAgentId) return undefined;
-    const caller = this.agentManager.getAgent(callerAgentId);
+  private async resolveCreationCaller(
+    callerAgentId?: string,
+  ): Promise<(CreateAgentCaller & { background?: boolean }) | null> {
+    if (!callerAgentId) return null;
+    let caller: (CreateAgentCaller & { background?: boolean }) | null =
+      this.agentManager.getAgent(callerAgentId);
+    if (!caller) {
+      const stored = await this.agentStorage.get(callerAgentId);
+      if (stored && !stored.archivedAt) caller = stored;
+    }
     if (!caller) throw new Error(`Caller agent ${callerAgentId} not found`);
-    return caller.workspaceId;
+    return {
+      id: caller.id,
+      cwd: caller.cwd,
+      workspaceId: caller.workspaceId,
+      background: caller.background,
+    };
+  }
+
+  private async workspaceBackgroundIntent(
+    background: boolean | undefined,
+    callerAgentId: string | undefined,
+  ): Promise<{ background?: boolean; callerWorkspaceId?: string }> {
+    const caller = await this.resolveCreationCaller(callerAgentId);
+    return {
+      background: inheritWorkspaceBackground(background, caller),
+      callerWorkspaceId: caller?.workspaceId,
+    };
   }
 
   private async createRequestedWorkspace(
@@ -6941,8 +7418,8 @@ export class Session {
       {
         expectsInitialAgent: Boolean(request.firstAgentContext),
         workspaceId,
-        background: request.background,
-        callerWorkspaceId: this.getCallerWorkspaceId(request.callerAgentId),
+        metadata: request.metadata,
+        ...(await this.workspaceBackgroundIntent(request.background, request.callerAgentId)),
       },
     );
     await this.syncWorkspaceGitObserverForWorkspace(workspace);
@@ -7005,8 +7482,8 @@ export class Session {
         githubPrNumber: source.githubPrNumber,
         firstAgentContext: request.firstAgentContext,
         title: request.title,
-        background: request.background,
-        callerWorkspaceId: this.getCallerWorkspaceId(request.callerAgentId),
+        metadata: request.metadata,
+        ...(await this.workspaceBackgroundIntent(request.background, request.callerAgentId)),
       },
       source.baseBranch
         ? { resolveDefaultBranch: async () => source.baseBranch as string }
@@ -7050,7 +7527,7 @@ export class Session {
         projectsBefore.set(project.projectId, project);
       }
       const workspacesBefore = new Map<string, PersistedWorkspaceRecord>();
-      for (const workspaceRecord of await this.workspaceRegistry.list()) {
+      for (const workspaceRecord of await this.workspaceRegistry.listActive()) {
         workspacesBefore.set(workspaceRecord.workspaceId, workspaceRecord);
       }
       const workspace = await this.workspaceProvisioning.findOrCreateWorkspaceForDirectory(cwd);
@@ -7608,41 +8085,62 @@ export class Session {
     request: Extract<SessionInboundMessage, { type: "archive_workspace_request" }>,
   ): Promise<void> {
     try {
-      const existing = await this.workspaceRegistry.get(request.workspaceId);
-      if (!existing) {
-        throw new Error(`Workspace not found: ${request.workspaceId}`);
-      }
-
-      await archiveByScope(
-        {
-          paseoHome: this.paseoHome,
-          paseoWorktreesBaseRoot: this.worktreesRoot,
-          github: this.github,
-          workspaceGitService: this.workspaceGitService,
-          agentManager: this.agentManager,
-          agentStorage: this.agentStorage,
-          findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
-          getWorkspace: (workspaceId) => this.workspaceRegistry.get(workspaceId),
-          listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
-          archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
-          emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) =>
-            this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
-          markWorkspaceArchiving: (workspaceIds, archivingAt) =>
-            this.markWorkspaceArchiving(workspaceIds, archivingAt),
-          clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
-          assertWorkspaceAutomationAllowed: (workspaceId) =>
-            assertWorkspaceAutomationAllowedForWorkspace(this.workspaceRegistry, workspaceId),
-          killTerminalsForWorkspace: (workspaceId) =>
-            this.terminalController.killTerminalsForWorkspace(workspaceId),
-          stopWorkspaceSetup: (workspaceId) => this.workspaceSetupRuntime.stop(workspaceId),
-          sessionLogger: this.sessionLogger,
-        },
-        {
-          scope: { kind: "workspace", workspaceId: existing.workspaceId },
-          requestId: request.requestId,
+      // Claim the archive queue before any await, so an undo sent right behind this request
+      // queues after it and cancels it instead of running first.
+      const outcome = await this.workspaceArchiveOperations.archive(
+        request.workspaceId,
+        async (signal) => {
+          const existing = await this.workspaceRegistry.get(request.workspaceId);
+          if (!existing) {
+            throw new Error(`Workspace not found: ${request.workspaceId}`);
+          }
+          return archiveByScope(
+            {
+              paseoHome: this.paseoHome,
+              paseoWorktreesBaseRoot: this.worktreesRoot,
+              github: this.github,
+              workspaceGitService: this.workspaceGitService,
+              agentManager: this.agentManager,
+              agentStorage: this.agentStorage,
+              findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd),
+              getWorkspace: (workspaceId) => this.workspaceRegistry.get(workspaceId),
+              listActiveWorkspaces: () => this.listActiveWorkspaceRefs(),
+              archiveWorkspaceRecord: (workspaceId) => this.archiveWorkspaceRecord(workspaceId),
+              emitWorkspaceUpdatesForWorkspaceIds: (workspaceIds) =>
+                this.emitWorkspaceUpdatesForWorkspaceIds(workspaceIds),
+              markWorkspaceArchiving: (workspaceIds, archivingAt) =>
+                this.markWorkspaceArchiving(workspaceIds, archivingAt),
+              clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds),
+              assertWorkspaceAutomationAllowed: (workspaceId) =>
+                assertWorkspaceAutomationAllowedForWorkspace(this.workspaceRegistry, workspaceId),
+              killTerminalsForWorkspace: (workspaceId) =>
+                this.terminalController.killTerminalsForWorkspace(workspaceId),
+              stopWorkspaceSetup: (workspaceId) => this.workspaceSetupRuntime.stop(workspaceId),
+              sessionLogger: this.sessionLogger,
+            },
+            {
+              scope: { kind: "workspace", workspaceId: existing.workspaceId },
+              requestId: request.requestId,
+              signal,
+            },
+          );
         },
       );
 
+      if (outcome.kind === "canceled") {
+        this.emit({
+          type: "archive_workspace_response",
+          payload: {
+            requestId: request.requestId,
+            workspaceId: request.workspaceId,
+            archivedAt: null,
+            error: "Workspace archive was undone",
+            canceled: true,
+          },
+        });
+        return;
+      }
+
       const archivedWorkspace = await this.workspaceRegistry.get(request.workspaceId);
       const archivedAt = archivedWorkspace?.archivedAt ?? new Date().toISOString();
       this.emit({
@@ -7672,6 +8170,69 @@ export class Session {
     }
   }
 
+  private async handleWorkspaceArchiveUndoRequest(
+    request: Extract<SessionInboundMessage, { type: "workspace.archive.undo.request" }>,
+  ): Promise<void> {
+    try {
+      await this.workspaceArchiveOperations.undo(request.workspaceId, (input) =>
+        this.restoreArchivedWorkspaceAndAgents(request.workspaceId, input),
+      );
+      this.emit({
+        type: "workspace.archive.undo.response",
+        payload: {
+          requestId: request.requestId,
+          workspaceId: request.workspaceId,
+          accepted: true,
+          error: null,
+        },
+      });
+    } catch (error) {
+      this.sessionLogger.warn(
+        { err: error, workspaceId: request.workspaceId, requestId: request.requestId },
+        "session: workspace.archive.undo.request rejected",
+      );
+      this.emit({
+        type: "workspace.archive.undo.response",
+        payload: {
+          requestId: request.requestId,
+          workspaceId: request.workspaceId,
+          accepted: false,
+          error: getErrorMessageOr(error, "Failed to undo the workspace archive"),
+        },
+      });
+    }
+  }
+
+  // Runs on the archive lane after any in-flight archive has stopped, so the record reflects how
+  // far it got: still active when it was canceled early, archived (directory kept or removed)
+  // otherwise.
+  private async restoreArchivedWorkspaceAndAgents(
+    workspaceId: string,
+    input: WorkspaceArchiveUndoInput,
+  ): Promise<void> {
+    const workspace = await this.workspaceRegistry.get(workspaceId);
+    if (!workspace) {
+      throw new Error(`Workspace not found: ${workspaceId}`);
+    }
+    if (workspace.archivedAt) {
+      await this.workspaceRecovery.restore(workspaceId);
+    }
+    const results = await Promise.allSettled(
+      input.agentIds.map((agentId) =>
+        unarchiveAgentState(this.agentStorage, this.agentManager, agentId),
+      ),
+    );
+    for (const [index, result] of results.entries()) {
+      if (result.status === "rejected") {
+        this.sessionLogger.warn(
+          { err: result.reason, workspaceId, agentId: input.agentIds[index] },
+          "Failed to unarchive agent while undoing workspace archive",
+        );
+      }
+    }
+    await this.publishRecoveredWorkspace(workspaceId);
+  }
+
   private async handleWorkspaceClearAttentionRequest(
     request: Extract<SessionInboundMessage, { type: "workspace.clear_attention.request" }>,
   ): Promise<void> {
@@ -7679,7 +8240,10 @@ export class Session {
     const requestedWorkspaceIds = Array.isArray(workspaceId) ? workspaceId : [workspaceId];
     let agents: AgentSnapshotPayload[];
     try {
-      agents = await this.listAgentPayloads({ includeBackground: true });
+      agents = await this.listAgentPayloads({
+        workspaceIds: requestedWorkspaceIds,
+        includeBackground: true,
+      });
     } catch (error) {
       const message = getErrorMessage(error);
       const results = requestedWorkspaceIds.map((requestedWorkspaceId) => ({
@@ -7744,24 +8308,7 @@ export class Session {
           ) {
             continue;
           }
-          const nextRecord: StoredAgentRecord = {
-            ...record,
-            updatedAt: new Date().toISOString(),
-            requiresAttention: false,
-            attentionReason: null,
-            attentionTimestamp: null,
-          };
-          await this.agentStorage.upsert(nextRecord);
-          const agent = this.buildStoredAgentPayload(nextRecord);
-          const project = await this.buildProjectPlacementForWorkspace(workspace);
-          this.emit({
-            type: "agent_update",
-            payload: {
-              kind: "upsert",
-              agent,
-              project,
-            },
-          });
+          await this.agentManager.clearAgentAttention(agentId);
           clearedAgentIds.push(agentId);
         }
 
@@ -7819,14 +8366,22 @@ export class Session {
         throw new Error(`Workspace not found: ${workspaceId}`);
       }
 
-      const agents = (await this.listAgentPayloads({ includeBackground: true })).filter((agent) =>
-        this.isProviderVisibleToClient(agent.provider),
-      );
+      const agents = (
+        await this.listAgentPayloads({
+          workspaceIds: [workspaceId],
+          includeBackground: true,
+          includeAncestors: true,
+        })
+      ).filter((agent) => this.isProviderVisibleToClient(agent.provider));
       const agentsById = new Map(agents.map((agent) => [agent.id, agent] as const));
       const candidates = agents
-        .filter((agent) => !agent.archivedAt && agent.workspaceId === workspace.workspaceId)
+        .filter((agent) => !agent.archivedAt && !agent.background)
+        .filter((agent) => agent.workspaceId === workspace.workspaceId)
         .filter((agent) => resolveWorkspaceRootAgent(agent, agentsById)?.id === agent.id)
-        .filter((agent) => agent.status === "idle" || agent.status === "closed")
+        .filter(
+          (agent) =>
+            agent.status === "idle" || agent.status === "closed" || agent.status === "error",
+        )
         .filter((agent) => agent.requiresAttention !== true)
         .filter((agent) => (agent.pendingPermissions?.length ?? 0) === 0)
         .sort(
@@ -7835,7 +8390,7 @@ export class Session {
         );
       const candidate = candidates[0];
       if (!candidate) {
-        throw new Error(`Workspace has no finished agent to mark unread: ${workspaceId}`);
+        throw new Error(`Workspace has no read agent to mark unread: ${workspaceId}`);
       }
 
       await this.agentManager.markAgentUnread(candidate.id);
@@ -8142,6 +8697,7 @@ export class Session {
       agentManager: this.agentManager,
       agentStorage: this.agentStorage,
       logger: this.sessionLogger,
+      purpose: "history",
     });
     if (source.kind === "stored" && source.record.internal) {
       throw new Error(`Unknown agent '${parentAgentId}'`);
@@ -8175,6 +8731,75 @@ export class Session {
     }
   }
 
+  private async handleAgentBackgroundWorkStopRequest(
+    msg: Extract<SessionInboundMessage, { type: "agent.background_work.stop.request" }>,
+  ): Promise<void> {
+    let error: string | null = null;
+    try {
+      await this.agentManager.stopAgentBackgroundWork({
+        agentId: msg.agentId,
+        itemId: msg.itemId,
+        stopToken: msg.stopToken,
+      });
+    } catch (cause) {
+      error = cause instanceof Error ? cause.message : String(cause);
+    }
+    this.emit({
+      type: "agent.background_work.stop.response",
+      payload: {
+        requestId: msg.requestId,
+        agentId: msg.agentId,
+        itemId: msg.itemId,
+        error,
+      },
+    });
+  }
+
+  private async handleAgentBackgroundWorkListRequest(
+    msg: Extract<SessionInboundMessage, { type: "agent.background_work.list.request" }>,
+  ): Promise<void> {
+    try {
+      this.emit({
+        type: "agent.background_work.list.response",
+        payload: {
+          requestId: msg.requestId,
+          agentId: msg.agentId,
+          items: await this.readAgentBackgroundWork(msg.agentId),
+          error: null,
+        },
+      });
+    } catch (error) {
+      this.emit({
+        type: "agent.background_work.list.response",
+        payload: {
+          requestId: msg.requestId,
+          agentId: msg.agentId,
+          items: [],
+          error: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  }
+
+  // Background work lives only in memory, so an agent that is not loaded has none.
+  // Answering from storage keeps a read from resuming a dormant agent.
+  private async readAgentBackgroundWork(agentId: string): Promise<AgentBackgroundWorkItem[]> {
+    if (this.agentManager.getAgent(agentId)) {
+      if (!this.agentManager.getAgentBackgroundWorkSummary(agentId)) {
+        throw new Error("Background work inventory is unavailable");
+      }
+      return this.agentManager.listAgentBackgroundWork(agentId);
+    }
+    const record = await this.agentStorage.get(agentId);
+    if (!record || record.internal) {
+      throw new Error(`Unknown agent '${agentId}'`);
+    }
+    if (record.archivedAt) {
+      throw new Error(`Agent is archived: ${agentId}`);
+    }
+    throw new Error("Background work inventory is unavailable");
+  }
+
   private async handleProviderSubagentTimelineRequest(
     msg: Extract<SessionInboundMessage, { type: "agent.provider_subagents.timeline.get.request" }>,
     source?: object,
@@ -8392,7 +9017,7 @@ export class Session {
             },
             activeTurnBehavior: msg.activeTurnBehavior ?? "steer",
             sessionMode: msg.sessionMode,
-            clearPendingPermissions: true,
+            clearPendingPermissions: false,
           });
           deliveryStatus = "queued";
           queued();
@@ -8764,9 +9389,9 @@ export class Session {
     }
   }
 
-  private async emitBinaryForFileTransfer(frame: Uint8Array, source?: object): Promise<void> {
+  private async emitBinaryReply(frame: Uint8Array, source?: object): Promise<void> {
     if (source && this.onBinaryMessageToSource) {
-      this.delivery.authorizeFileReply(frame, source);
+      this.delivery.authorizeBinaryReply(frame, source);
       await this.onBinaryMessageToSource(source, frame);
       return;
     }
@@ -8893,6 +9518,7 @@ function sessionEventCategory(message: SessionOutboundMessage): SessionEventSubs
     case "script_status_update":
     case "workspace_setup_progress":
     case "agent.provider_subagents.update":
+    case "agent.background_work.update":
     case "terminal_attention_required":
     case "activity_log":
     case "hub.execution.agent.update":
@@ -8931,6 +9557,9 @@ function legacyWantsEvent(
       return !capabilities.has(CLIENT_CAPS.explicitEventSubscriptions);
     case "agent.provider_subagents.update":
       return capabilities.has(CLIENT_CAPS.providerSubagents);
+    // Old apps parse outbound messages strictly and do not know this type.
+    case "agent.background_work.update":
+      return false;
     default:
       return true;
   }
diff --git a/packages/server/src/server/session.workspace-git-watch.test.ts b/packages/server/src/server/session.workspace-git-watch.test.ts
index f13b90d2c8..3912a2dc8b 100644
--- a/packages/server/src/server/session.workspace-git-watch.test.ts
+++ b/packages/server/src/server/session.workspace-git-watch.test.ts
@@ -208,7 +208,10 @@ function createSessionForWorkspaceGitWatchTests(options?: {
       getAgent: () => null,
     }),
     agentStorage: createStub<SessionOptions["agentStorage"]>({
-      list: async () => [],
+      listAll: async () => [],
+      listActive: async () => [],
+      listByWorkspaces: async () => [],
+      lastUserMessageAtByWorkspace: async () => new Map<string, string>(),
       get: async () => null,
     }),
     projectRegistry: createStub<SessionOptions["projectRegistry"]>({
@@ -233,7 +236,9 @@ function createSessionForWorkspaceGitWatchTests(options?: {
       subscribeToMutations: () => () => {},
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => Array.from(workspaces.values()),
+      listAll: async () => Array.from(workspaces.values()),
+      listActive: async () =>
+        Array.from(workspaces.values()).filter((record) => !record.archivedAt),
       get: async (workspaceId: string) => workspaces.get(workspaceId) ?? null,
       upsert: async (record: ReturnType<typeof createPersistedWorkspaceRecord>) => {
         workspaces.set(record.workspaceId, record);
diff --git a/packages/server/src/server/session.workspace-resolution-invariants.test.ts b/packages/server/src/server/session.workspace-resolution-invariants.test.ts
index 2a5402a0c3..d0a53de9b2 100644
--- a/packages/server/src/server/session.workspace-resolution-invariants.test.ts
+++ b/packages/server/src/server/session.workspace-resolution-invariants.test.ts
@@ -115,7 +115,10 @@ function createHarness(input: {
       notifyAgentState: () => {},
     }),
     agentStorage: createStub<SessionOptions["agentStorage"]>({
-      list: async () => [],
+      listAll: async () => [],
+      listActive: async () => [],
+      listByWorkspaces: async () => [],
+      lastUserMessageAtByWorkspace: async () => new Map<string, string>(),
       get: async () => null,
     }),
     projectRegistry: createStub<SessionOptions["projectRegistry"]>({
@@ -155,7 +158,9 @@ function createHarness(input: {
       subscribeToMutations: () => () => {},
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => Array.from(workspaces.values()),
+      listAll: async () => Array.from(workspaces.values()),
+      listActive: async () =>
+        Array.from(workspaces.values()).filter((record) => !record.archivedAt),
       get: async (id: string) => workspaces.get(id) ?? null,
       upsert: async (record: PersistedWorkspaceRecord) => {
         workspaces.set(record.workspaceId, record);
diff --git a/packages/server/src/server/session.workspaces.test.ts b/packages/server/src/server/session.workspaces.test.ts
index 7e0208f45e..1172481782 100644
--- a/packages/server/src/server/session.workspaces.test.ts
+++ b/packages/server/src/server/session.workspaces.test.ts
@@ -1,3 +1,5 @@
+import { AgentDirectory } from "./agent/directory.js";
+import { buildStoredAgentPayload } from "./agent/agent-projections.js";
 import {
   createWorkspaceRuntimeStore,
   type WorkspaceRuntimeStore,
@@ -57,7 +59,7 @@ import {
   type WorkspaceGitRuntimeSnapshot,
 } from "./workspace-git-service.js";
 import type { CheckoutSnapshotFacts, CheckoutStatusGit } from "../utils/checkout-git.js";
-import type pino from "pino";
+import pino from "pino";
 import type { GeneratedWorkspaceName } from "./worktree-branch-name-generator.js";
 import { WorkspaceAutoName } from "./workspace-auto-name.js";
 import type { ForgeService } from "../services/forge-service.js";
@@ -125,7 +127,7 @@ interface SessionTestAccess {
     remove(projectId: string): Promise<void>;
   };
   agentStorage: {
-    list(...args: unknown[]): Promise<unknown[]>;
+    listAll(...args: unknown[]): Promise<unknown[]>;
     get(agentId: string): Promise<unknown>;
     upsert(record: unknown): Promise<void>;
   };
@@ -150,7 +152,8 @@ interface SessionTestAccess {
     setTitle(agentId: string, title: string): Promise<unknown>;
   };
   workspaceRegistry: {
-    list(...args: unknown[]): Promise<unknown[]>;
+    listActive(...args: unknown[]): Promise<unknown[]>;
+    listAll(...args: unknown[]): Promise<unknown[]>;
     archive(workspaceId: string, archivedAt: string): Promise<void>;
     get(workspaceId: string): Promise<unknown>;
     update(
@@ -610,7 +613,10 @@ function createSessionForWorkspaceTests(
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = options.workspaceRegistry ?? {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => [
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => [
       createPersistedWorkspaceRecord({
         workspaceId: "ws-repo-running",
         projectId: "proj-repo-running",
@@ -621,18 +627,9 @@ function createSessionForWorkspaceTests(
         updatedAt: "2026-03-01T12:00:00.000Z",
       }),
     ],
-    get: async (workspaceId: string) =>
-      workspaceId === "ws-repo-running"
-        ? createPersistedWorkspaceRecord({
-            workspaceId: "ws-repo-running",
-            projectId: "proj-repo-running",
-            cwd: REPO_CWD,
-            kind: "directory",
-            displayName: "repo",
-            createdAt: "2026-03-01T12:00:00.000Z",
-            updatedAt: "2026-03-01T12:00:00.000Z",
-          })
-        : null,
+    get: async function (workspaceId: string) {
+      return (await this.listAll()).find((record) => record.workspaceId === workspaceId) ?? null;
+    },
     update: async (workspaceId, updater) => {
       if (workspaceId !== "ws-repo-running") {
         return null;
@@ -674,7 +671,7 @@ function createSessionForWorkspaceTests(
       worktreesRoot: options.worktreesRoot,
       agentManager,
       agentStorage: asAgentStorage({
-        list: async () => [
+        listAll: async () => [
           createPersistedWorkspaceRecord({
             workspaceId: "ws-repo-running",
             projectId: "proj-repo-running",
@@ -1266,25 +1263,19 @@ test("create_agent_request launches from an exact subdirectory in a created work
 test("create_agent_request does not title an existing workspace from the agent prompt", async () => {
   vi.useFakeTimers();
   const workdir = mkdtempSync(path.join(tmpdir(), "paseo-create-agent-existing-title-"));
+  const errors: string[] = [];
+  const logger = pino({ level: "error" }, { write: (entry) => errors.push(entry) });
+  const agentStorage = new AgentStorage(path.join(workdir, "agents"), asSessionLogger(logger));
+  const agentManager = new AgentManager({
+    clients: { codex: new CreateAgentTestClient() },
+    registry: agentStorage,
+    logger: asSessionLogger(logger),
+    idFactory: () => "00000000-0000-4000-8000-000000000552",
+  });
   try {
     const cwd = path.join(workdir, "repo");
     mkdirSync(cwd, { recursive: true });
 
-    const logger = {
-      child: () => logger,
-      trace: vi.fn(),
-      debug: vi.fn(),
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-    };
-    const agentStorage = new AgentStorage(path.join(workdir, "agents"), asSessionLogger(logger));
-    const agentManager = new AgentManager({
-      clients: { codex: new CreateAgentTestClient() },
-      registry: agentStorage,
-      logger: asSessionLogger(logger),
-      idFactory: () => "00000000-0000-4000-8000-000000000552",
-    });
     const projectRegistry = new FileBackedProjectRegistry(
       path.join(workdir, "projects.json"),
       asSessionLogger(logger),
@@ -1388,6 +1379,141 @@ test("create_agent_request does not title an existing workspace from the agent p
       updatedAt: "2026-05-07T00:00:00.000Z",
     });
   } finally {
+    // Fake timers do not drain filesystem writes started by the initial prompt.
+    await agentManager.flush();
+    vi.useRealTimers();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+  // Also catch writes that teardown would otherwise abandon after deleting their directory.
+  await agentManager.flush();
+  expect(errors).toEqual([]);
+});
+
+test("create_agent_request does not publish the pre-prompt snapshot after the prompt starts", async () => {
+  vi.useFakeTimers();
+  const workdir = mkdtempSync(path.join(tmpdir(), "paseo-create-agent-live-state-"));
+  const logger = createTestLogger();
+  const agentStorage = new AgentStorage(path.join(workdir, "agents"), asSessionLogger(logger));
+  // The test session's turn starts and then reports nothing, like a provider
+  // that stays quiet until its turn ends.
+  const agentManager = new AgentManager({
+    clients: { codex: new CreateAgentTestClient() },
+    registry: agentStorage,
+    logger: asSessionLogger(logger),
+    idFactory: () => "00000000-0000-4000-8000-000000000553",
+  });
+  try {
+    const cwd = path.join(workdir, "repo");
+    mkdirSync(cwd, { recursive: true });
+
+    const projectRegistry = new FileBackedProjectRegistry(
+      path.join(workdir, "projects.json"),
+      asSessionLogger(logger),
+    );
+    const workspaceRegistry = new FileBackedWorkspaceRegistry(
+      path.join(workdir, "workspaces.json"),
+      asSessionLogger(logger),
+    );
+
+    await projectRegistry.upsert(
+      createPersistedProjectRecord({
+        projectId: "proj-live-state",
+        rootPath: cwd,
+        kind: "git",
+        displayName: "repo",
+        createdAt: "2026-05-07T00:00:00.000Z",
+        updatedAt: "2026-05-07T00:00:00.000Z",
+      }),
+    );
+    await workspaceRegistry.upsert(
+      createPersistedWorkspaceRecord({
+        workspaceId: "ws-live-state",
+        projectId: "proj-live-state",
+        cwd,
+        kind: "local_checkout",
+        displayName: "repo",
+        title: null,
+        createdAt: "2026-05-07T00:00:00.000Z",
+        updatedAt: "2026-05-07T00:00:00.000Z",
+      }),
+    );
+
+    const agentUpdates: Extract<SessionOutboundMessage, { type: "agent_update" }>["payload"][] = [];
+    const session = asTestSession(
+      new Session({
+        workspaceRuntimeStore: createWorkspaceRuntimeStore(),
+        messageReceipts: createMessageReceiptsStub(),
+        agentMessages: createAgentMessageDeliveryStub(),
+        creationService: createTestCreationService(),
+        clientId: "test-client",
+        permissions: OWNER_PERMISSIONS,
+        appVersion: null,
+        onMessage: (message) => {
+          if (message.type === "agent_update") agentUpdates.push(message.payload);
+        },
+        logger: asSessionLogger(logger),
+        downloadTokenStore: asDownloadTokenStore(),
+        pushNotifications: asPushNotifications(),
+        paseoHome: path.join(workdir, "paseo-home"),
+        agentManager,
+        agentStorage,
+        projectRegistry,
+        workspaceRegistry,
+        scheduleService: asScheduleService(),
+        checkoutDiffManager: asCheckoutDiffManager({
+          subscribe: async () => ({
+            initial: { cwd, files: [], error: null },
+            unsubscribe: () => {},
+          }),
+          scheduleRefreshForCwd: () => {},
+          onWorkspaceStateMayHaveChanged: () => {},
+          invalidateForge: () => {},
+          getMetrics: () => ({
+            checkoutDiffTargetCount: 0,
+            checkoutDiffSubscriptionCount: 0,
+            checkoutDiffWatcherCount: 0,
+            checkoutDiffFallbackRefreshTargetCount: 0,
+          }),
+          dispose: () => {},
+        }),
+        workspaceGitService: createNoopWorkspaceGitService(),
+        daemonConfigStore: asDaemonConfigStore({
+          get: () => ({ mcp: { injectIntoAgents: false }, providers: {} }),
+          onChange: () => () => {},
+        }),
+        mcpBaseUrl: null,
+        stt: null,
+        tts: null,
+        generateWorkspaceName: async () => null,
+        providerSnapshotManager: createProviderSnapshotManagerStub().manager,
+        terminalManager: null,
+      }),
+    );
+    await activateAgentUpdatesSubscription(session, "sub-live-state");
+
+    await session.handleMessage({
+      type: "create_agent_request",
+      requestId: "req-create-live-state",
+      workspaceId: "ws-live-state",
+      config: { provider: "codex", cwd },
+      initialPrompt: "Print the report",
+      attachments: [],
+    });
+    await vi.runAllTimersAsync();
+
+    const [createdAgent] = agentManager.listAgents();
+    expect(createdAgent?.lifecycle).toBe("running");
+    const upserts = agentUpdates.flatMap((update) =>
+      update.kind === "upsert" && update.agent.id === createdAgent?.id ? [update.agent] : [],
+    );
+    expect(upserts.length).toBeGreaterThan(0);
+    // A client keeps the last update it hears, so the latest one must be the running agent.
+    expect(upserts.at(-1)).toMatchObject({ status: "running" });
+    const updatedAt = upserts.map((agent) => Date.parse(agent.updatedAt));
+    expect(updatedAt).toEqual([...updatedAt].sort((left, right) => left - right));
+  } finally {
+    // Drain snapshot writes before removing their storage directory.
+    await agentManager.flush();
     vi.useRealTimers();
     rmSync(workdir, { recursive: true, force: true });
   }
@@ -1425,7 +1551,7 @@ test("unsupported persisted agents are excluded from active lists but preserved
     archivedAt: "2026-04-13T10:16:06.514Z",
   };
 
-  session.agentStorage.list = async () => [storedRecord];
+  session.agentStorage.listAll = async () => [storedRecord];
   session.agentStorage.get = async (agentId: string) =>
     agentId === storedRecord.id ? storedRecord : null;
 
@@ -1490,7 +1616,9 @@ test("agent_update placement does not refresh git snapshots", async () => {
   });
 
   session.projectRegistry.get = async (id: string) => (id === project.projectId ? project : null);
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async (id: string) =>
     id === workspace.workspaceId ? workspace : null;
   await activateAgentUpdatesSubscription(session, "sub-agents", {});
@@ -1622,7 +1750,7 @@ test("archive emits an authoritative agent_update upsert for subscribed clients"
         notifyAgentState: () => {},
       }),
       agentStorage: asAgentStorage({
-        list: async () => [archivedRecord],
+        listAll: async () => [archivedRecord],
         get: async (agentId: string) => (agentId === archivedRecord.id ? archivedRecord : null),
         upsert: async (record: typeof archivedRecord) => {
           Object.assign(archivedRecord, record);
@@ -1660,7 +1788,10 @@ test("archive emits an authoritative agent_update upsert for subscribed clients"
         return {
           initialize: async () => {},
           existsOnDisk: async () => true,
-          list: async () => [ws],
+          listActive: async function () {
+            return (await this.listAll()).filter((record) => !record.archivedAt);
+          },
+          listAll: async () => [ws],
           get: async (id: string) => (id === "ws-1" ? ws : null),
           upsert: async () => {},
           archive: async () => {},
@@ -1716,79 +1847,6 @@ test("archive emits an authoritative agent_update upsert for subscribed clients"
   });
 });
 
-test("workspace clear attention clears stored-only agents and responds", async () => {
-  const emitted: SessionOutboundMessage[] = [];
-  const workspace = createPersistedWorkspaceRecord({
-    workspaceId: REPO_CWD,
-    projectId: REPO_CWD,
-    cwd: REPO_CWD,
-    kind: "directory",
-    displayName: "repo",
-    createdAt: "2026-03-30T15:00:00.000Z",
-    updatedAt: "2026-03-30T15:00:00.000Z",
-  });
-  const project = createPersistedProjectRecord({
-    projectId: REPO_CWD,
-    rootPath: REPO_CWD,
-    kind: "non_git",
-    displayName: "repo",
-    createdAt: "2026-03-30T15:00:00.000Z",
-    updatedAt: "2026-03-30T15:00:00.000Z",
-  });
-  let storedRecord = makeStoredAgent({
-    id: "stored-agent-1",
-    cwd: REPO_CWD,
-    updatedAt: "2026-03-30T15:00:00.000Z",
-    requiresAttention: true,
-    attentionReason: "finished",
-  });
-  const session = createSessionForWorkspaceTests({ onMessage: (message) => emitted.push(message) });
-
-  session.workspaceRegistry.list = async () => [workspace];
-  session.workspaceRegistry.get = async (id: string) =>
-    id === workspace.workspaceId ? workspace : null;
-  session.projectRegistry.list = async () => [project];
-  session.projectRegistry.get = async (id: string) => (id === project.projectId ? project : null);
-  session.agentStorage.get = async (agentId: string) =>
-    agentId === storedRecord.id ? storedRecord : null;
-  session.agentStorage.upsert = async (record: unknown) => {
-    storedRecord = record as StoredAgentRecord;
-  };
-  session.listAgentPayloads = async () => [
-    makeAgent({
-      id: storedRecord.id,
-      cwd: storedRecord.cwd,
-      workspaceId: workspace.workspaceId,
-      status: "closed",
-      updatedAt: storedRecord.updatedAt,
-      requiresAttention: true,
-      attentionReason: "finished",
-    }),
-  ];
-
-  await session.handleMessage({
-    type: "workspace.clear_attention.request",
-    workspaceId: workspace.workspaceId,
-    requestId: "req-1",
-  });
-
-  expect(storedRecord.requiresAttention).toBe(false);
-  expect(storedRecord.attentionReason).toBeNull();
-  expect(storedRecord.attentionTimestamp).toBeNull();
-  expect(findByType(emitted, "workspace.clear_attention.response").payload).toMatchObject({
-    requestId: "req-1",
-    workspaceId: workspace.workspaceId,
-    clearedAgentIds: [storedRecord.id],
-    success: true,
-    error: null,
-  });
-  const agentUpdate = findByType(emitted, "agent_update");
-  expect(agentUpdate.payload.kind).toBe("upsert");
-  if (agentUpdate.payload.kind === "upsert") {
-    expect(agentUpdate.payload.agent.requiresAttention).toBe(false);
-  }
-});
-
 test("workspace clear attention responds with an error instead of timing out", async () => {
   const emitted: SessionOutboundMessage[] = [];
   const session = createSessionForWorkspaceTests({ onMessage: (message) => emitted.push(message) });
@@ -1859,7 +1917,9 @@ test("workspace mark unread selects the newest finished workspace root", async (
     },
   });
 
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async (id: string) =>
     id === workspace.workspaceId ? workspace : null;
   session.projectRegistry.list = async () => [project];
@@ -1895,7 +1955,147 @@ test("workspace mark unread selects the newest finished workspace root", async (
   });
 });
 
-test("workspace mark unread rejects workspaces without a finished root agent", async () => {
+test("workspace mark unread selects a finished cross-workspace child with scoped parent context", async () => {
+  const emitted: SessionOutboundMessage[] = [];
+  const workspace = createPersistedWorkspaceRecord({
+    workspaceId: REPO_CWD,
+    projectId: REPO_CWD,
+    cwd: REPO_CWD,
+    kind: "directory",
+    displayName: "repo",
+    createdAt: "2026-03-30T15:00:00.000Z",
+    updatedAt: "2026-03-30T15:00:00.000Z",
+  });
+  const project = createPersistedProjectRecord({
+    projectId: REPO_CWD,
+    rootPath: REPO_CWD,
+    kind: "non_git",
+    displayName: "repo",
+    createdAt: "2026-03-30T15:00:00.000Z",
+    updatedAt: "2026-03-30T15:00:00.000Z",
+  });
+  const storedRecords = new Map<string, StoredAgentRecord>([
+    [
+      "root-agent",
+      makeStoredAgent({
+        id: "root-agent",
+        cwd: REPO_CWD,
+        workspaceId: "parent-workspace",
+        updatedAt: "2026-03-30T16:00:00.000Z",
+      }),
+    ],
+    [
+      "newer-child",
+      makeStoredAgent({
+        id: "newer-child",
+        cwd: REPO_CWD,
+        workspaceId: workspace.workspaceId,
+        updatedAt: "2026-03-30T17:00:00.000Z",
+        labels: { "paseo.parent-agent-id": "root-agent" },
+      }),
+    ],
+  ]);
+  const markedAgentIds: string[] = [];
+  const session = createSessionForWorkspaceTests({
+    onMessage: (message) => emitted.push(message),
+    agentManager: {
+      markAgentUnread: async (agentId: string) => {
+        markedAgentIds.push(agentId);
+      },
+    },
+  });
+
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
+  session.workspaceRegistry.get = async (id: string) =>
+    id === workspace.workspaceId ? workspace : null;
+  session.projectRegistry.list = async () => [project];
+  session.projectRegistry.get = async (id: string) => (id === project.projectId ? project : null);
+  const home = mkdtempSync(path.join(tmpdir(), "mark-unread-parent-"));
+  const storage = new AgentStorage(path.join(home, "agents"), pino({ level: "silent" }));
+  for (const record of storedRecords.values()) await storage.upsert(record);
+  const directory = new AgentDirectory({
+    storage,
+    manager: { listAgents: () => [] },
+    workspaces: { get: async () => null },
+    projectLive: async () => {
+      throw new Error("No live agents");
+    },
+    projectStored: (record) =>
+      buildStoredAgentPayload(record, ["codex"], (_provider, own) => own ?? {}),
+    isProviderVisible: () => true,
+    isStoredProviderAvailable: () => true,
+  });
+  session.listAgentPayloads = (filter) =>
+    directory.list(filter as Parameters<AgentDirectory["list"]>[0]);
+  try {
+    await session.handleMessage({
+      type: "workspace.mark_unread.request",
+      workspaceId: workspace.workspaceId,
+      requestId: "req-mark-unread",
+    });
+
+    expect(markedAgentIds).toEqual(["newer-child"]);
+    expect(findByType(emitted, "workspace.mark_unread.response").payload).toEqual({
+      requestId: "req-mark-unread",
+      workspaceId: workspace.workspaceId,
+      markedAgentId: "newer-child",
+      success: true,
+      error: null,
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("workspace mark unread marks a read errored root agent", async () => {
+  const emitted: SessionOutboundMessage[] = [];
+  const workspace = createPersistedWorkspaceRecord({
+    workspaceId: REPO_CWD,
+    projectId: REPO_CWD,
+    cwd: REPO_CWD,
+    kind: "directory",
+    displayName: "repo",
+    createdAt: "2026-03-30T15:00:00.000Z",
+    updatedAt: "2026-03-30T15:00:00.000Z",
+  });
+  const markedAgentIds: string[] = [];
+  const session = createSessionForWorkspaceTests({
+    onMessage: (message) => emitted.push(message),
+    agentManager: {
+      markAgentUnread: async (agentId: string) => {
+        markedAgentIds.push(agentId);
+      },
+    },
+  });
+  session.workspaceRegistry.get = async (id: string) =>
+    id === workspace.workspaceId ? workspace : null;
+  session.listAgentPayloads = async () => [
+    makeAgent({
+      id: "errored-agent",
+      cwd: REPO_CWD,
+      workspaceId: workspace.workspaceId,
+      status: "error",
+      updatedAt: "2026-03-30T16:00:00.000Z",
+      requiresAttention: false,
+    }),
+  ];
+
+  await session.handleMessage({
+    type: "workspace.mark_unread.request",
+    workspaceId: workspace.workspaceId,
+    requestId: "req-mark-unread",
+  });
+
+  expect(markedAgentIds).toEqual(["errored-agent"]);
+  expect(findByType(emitted, "workspace.mark_unread.response").payload).toMatchObject({
+    markedAgentId: "errored-agent",
+    success: true,
+  });
+});
+
+test("workspace mark unread rejects workspaces without a read root agent", async () => {
   const emitted: SessionOutboundMessage[] = [];
   const workspace = createPersistedWorkspaceRecord({
     workspaceId: REPO_CWD,
@@ -1922,111 +2122,7 @@ test("workspace mark unread rejects workspaces without a finished root agent", a
     workspaceId: workspace.workspaceId,
     markedAgentId: null,
     success: false,
-    error: `Workspace has no finished agent to mark unread: ${workspace.workspaceId}`,
-  });
-});
-
-test("workspace clear attention can clear multiple workspaces in one request", async () => {
-  const emitted: SessionOutboundMessage[] = [];
-  const workspaces = [
-    createPersistedWorkspaceRecord({
-      workspaceId: "ws-repo-a",
-      projectId: "/tmp/repo-a",
-      cwd: "/tmp/repo-a",
-      kind: "directory",
-      displayName: "repo-a",
-      createdAt: "2026-03-30T15:00:00.000Z",
-      updatedAt: "2026-03-30T15:00:00.000Z",
-    }),
-    createPersistedWorkspaceRecord({
-      workspaceId: "ws-repo-b",
-      projectId: "/tmp/repo-b",
-      cwd: "/tmp/repo-b",
-      kind: "directory",
-      displayName: "repo-b",
-      createdAt: "2026-03-30T15:00:00.000Z",
-      updatedAt: "2026-03-30T15:00:00.000Z",
-    }),
-  ];
-  const projects = workspaces.map((workspace) =>
-    createPersistedProjectRecord({
-      projectId: workspace.projectId,
-      rootPath: workspace.cwd,
-      kind: "non_git",
-      displayName: workspace.displayName,
-      createdAt: "2026-03-30T15:00:00.000Z",
-      updatedAt: "2026-03-30T15:00:00.000Z",
-    }),
-  );
-  const storedRecords = new Map(
-    workspaces.map((workspace, index) => [
-      `stored-agent-${index + 1}`,
-      makeStoredAgent({
-        id: `stored-agent-${index + 1}`,
-        cwd: workspace.cwd,
-        updatedAt: "2026-03-30T15:00:00.000Z",
-        requiresAttention: true,
-        attentionReason: "finished",
-      }),
-    ]),
-  );
-  const session = createSessionForWorkspaceTests({ onMessage: (message) => emitted.push(message) });
-
-  session.workspaceRegistry.list = async () => workspaces;
-  session.workspaceRegistry.get = async (id: string) =>
-    workspaces.find((workspace) => workspace.workspaceId === id) ?? null;
-  session.projectRegistry.list = async () => projects;
-  session.projectRegistry.get = async (id: string) =>
-    projects.find((project) => project.projectId === id) ?? null;
-  session.agentStorage.get = async (agentId: string) => storedRecords.get(agentId) ?? null;
-  session.agentStorage.upsert = async (record: unknown) => {
-    const storedRecord = record as StoredAgentRecord;
-    storedRecords.set(storedRecord.id, storedRecord);
-  };
-  session.listAgentPayloads = async () =>
-    Array.from(storedRecords.values()).map((record) => {
-      const owner = workspaces.find((workspace) => workspace.cwd === record.cwd);
-      return makeAgent({
-        id: record.id,
-        cwd: record.cwd,
-        ...(owner ? { workspaceId: owner.workspaceId } : {}),
-        status: "closed",
-        updatedAt: record.updatedAt,
-        requiresAttention: record.requiresAttention,
-        attentionReason: record.attentionReason,
-      });
-    });
-
-  await session.handleMessage({
-    type: "workspace.clear_attention.request",
-    workspaceId: workspaces.map((workspace) => workspace.workspaceId),
-    requestId: "req-1",
-  });
-
-  expect(Array.from(storedRecords.values()).map((record) => record.requiresAttention)).toEqual([
-    false,
-    false,
-  ]);
-  expect(findByType(emitted, "workspace.clear_attention.response").payload).toMatchObject({
-    requestId: "req-1",
-    workspaceId: workspaces.map((workspace) => workspace.workspaceId),
-    clearedAgentIds: ["stored-agent-1", "stored-agent-2"],
-    results: [
-      {
-        workspaceId: workspaces[0].workspaceId,
-        clearedAgentIds: ["stored-agent-1"],
-        success: true,
-        error: null,
-      },
-      {
-        workspaceId: workspaces[1].workspaceId,
-        clearedAgentIds: ["stored-agent-2"],
-        success: true,
-        error: null,
-      },
-    ],
-    success: true,
-    error: null,
+    error: `Workspace has no read agent to mark unread: ${workspace.workspaceId}`,
   });
 });
 
@@ -2099,7 +2195,7 @@ test("close_items_request archives agents and kills terminals in one batch", asy
         notifyAgentState: () => {},
       }),
       agentStorage: asAgentStorage({
-        list: async () => [],
+        listAll: async () => [],
         get: async (agentId: string) => {
           if (agentId !== "agent-1") {
             return null;
@@ -2141,7 +2237,10 @@ test("close_items_request archives agents and kills terminals in one batch", asy
         return {
           initialize: async () => {},
           existsOnDisk: async () => true,
-          list: async () => [ws],
+          listActive: async function () {
+            return (await this.listAll()).filter((record) => !record.archivedAt);
+          },
+          listAll: async () => [ws],
           get: async (id: string) => (id === "ws-close" ? ws : null),
           upsert: async () => {},
           archive: async () => {},
@@ -2286,7 +2385,7 @@ test("close_items_request archives stored agents that are not currently loaded",
         notifyAgentState: () => {},
       }),
       agentStorage: asAgentStorage({
-        list: async () => [],
+        listAll: async () => [],
         get: async (agentId: string) => {
           if (agentId === "agent-live") {
             return liveRecord;
@@ -2330,7 +2429,10 @@ test("close_items_request archives stored agents that are not currently loaded",
         return {
           initialize: async () => {},
           existsOnDisk: async () => true,
-          list: async () => [ws],
+          listActive: async function () {
+            return (await this.listAll()).filter((record) => !record.archivedAt);
+          },
+          listAll: async () => [ws],
           get: async (id: string) => (id === "ws-stored" ? ws : null),
           upsert: async () => {},
           archive: async () => {},
@@ -2439,7 +2541,7 @@ test("close_items_request continues after an archive failure", async () => {
         notifyAgentState: () => {},
       }),
       agentStorage: asAgentStorage({
-        list: async () => [],
+        listAll: async () => [],
         get: async (agentId: string) => {
           if (agentId !== "agent-good") {
             return null;
@@ -2481,7 +2583,10 @@ test("close_items_request continues after an archive failure", async () => {
         return {
           initialize: async () => {},
           existsOnDisk: async () => true,
-          list: async () => [ws],
+          listActive: async function () {
+            return (await this.listAll()).filter((record) => !record.archivedAt);
+          },
+          listAll: async () => [ws],
           get: async (id: string) => (id === "ws-err" ? ws : null),
           upsert: async () => {},
           archive: async () => {},
@@ -2548,7 +2653,7 @@ test("close_items_request continues after an archive failure", async () => {
 
 test("non-git workspace uses deterministic directory name and no unknown branch fallback", async () => {
   const session = createSessionForWorkspaceTests();
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     createPersistedWorkspaceRecord({
       workspaceId: "ws-non-git",
       projectId: "proj-non-git",
@@ -2716,7 +2821,7 @@ test("active-scoped fetch_agents includes only unarchived agents in active works
   session.projectRegistry.list = async () => [activeProject, archivedProject];
   session.projectRegistry.get = async (projectId: string) =>
     [activeProject, archivedProject].find((project) => project.projectId === projectId) ?? null;
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     activeWorkspace,
     archivedWorkspace,
     workspaceInArchivedProject,
@@ -2814,7 +2919,11 @@ test("active-scoped fetch_agents pages within active scope instead of global his
 
   session.projectRegistry.list = async () => [project];
   session.projectRegistry.get = async () => project;
-  session.workspaceRegistry.list = async () => [activeOne, activeTwo, archivedWorkspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    activeOne,
+    activeTwo,
+    archivedWorkspace,
+  ];
   session.listAgentPayloads = async () => [
     makeAgent({
       id: "active-one",
@@ -2892,7 +3001,10 @@ test("legacy unscoped fetch_agents keeps global workspace behavior", async () =>
   });
 
   session.projectRegistry.get = async () => project;
-  session.workspaceRegistry.list = async () => [activeWorkspace, archivedWorkspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    activeWorkspace,
+    archivedWorkspace,
+  ];
   session.workspaceRegistry.get = async (workspaceId: string) =>
     [activeWorkspace, archivedWorkspace].find(
       (workspace) => workspace.workspaceId === workspaceId,
@@ -2952,7 +3064,9 @@ test("fetch_agent_history_request pages archived historical rows separately", as
     if (isSessionOutboundMessage(message)) emitted.push(message);
   };
   session.projectRegistry.get = async () => project;
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async () => workspace;
   session.listAgentPayloads = async () => [
     {
@@ -3020,7 +3134,9 @@ test("fetch_agent_history_request filters across history and paginates chronolog
     if (isSessionOutboundMessage(message)) emitted.push(message);
   };
   session.projectRegistry.get = async () => project;
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async () => workspace;
   session.listAgentPayloads = async () => [
     // Search keeps chronological order, skipping unrelated rows between pages.
@@ -3106,7 +3222,9 @@ test("fetch_agent_history_request rejects a malformed search cursor", async () =
     if (isSessionOutboundMessage(message)) emitted.push(message);
   };
   session.projectRegistry.get = async () => project;
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async () => workspace;
   session.listAgentPayloads = async () => [
     {
@@ -3326,7 +3444,7 @@ test("fetch_recent_provider_sessions_request lists importable provider sessions
       providerErrors: [],
     };
   };
-  session.agentStorage.list = async () => [
+  session.agentStorage.listAll = async () => [
     {
       id: "stored-agent",
       provider: "codex",
@@ -3393,7 +3511,7 @@ test("fetch_recent_provider_sessions_request forwards providerFilter to agent ma
 
   session.emit = (message) => emitted.push(message as { type: string; payload: unknown });
   session.agentManager.listAgents = () => [];
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentManager.listImportableSessions = async (options?: unknown) => {
     capturedOptions = options as { providerFilter?: Set<string>; limit?: number };
     return {
@@ -3438,7 +3556,7 @@ test("fetch_recent_provider_sessions_request reports filteredAlreadyImportedCoun
       },
     },
   ];
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentManager.listImportableSessions = async () => ({
     sessions: [
       {
@@ -3532,7 +3650,7 @@ test("fetch_agent_request still resolves archived historical agents", async () =
 
 test("git branch workspace uses branch as canonical name", async () => {
   const session = createSessionForWorkspaceTests();
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     createPersistedWorkspaceRecord({
       workspaceId: "ws-repo-branch",
       projectId: "proj-repo-branch",
@@ -3575,7 +3693,7 @@ test("git branch workspace uses branch as canonical name", async () => {
 
 test("branch/detached policies and dominant status bucket are deterministic", async () => {
   const session = createSessionForWorkspaceTests();
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     createPersistedWorkspaceRecord({
       workspaceId: "ws-repo-status",
       projectId: "proj-repo-status",
@@ -3622,7 +3740,7 @@ test("branch/detached policies and dominant status bucket are deterministic", as
 
 test("subdirectory agents contribute to their owning workspace descriptor", async () => {
   const session = createSessionForWorkspaceTests();
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     createPersistedWorkspaceRecord({
       workspaceId: "ws-repo-subdir",
       projectId: "proj-repo-subdir",
@@ -3688,7 +3806,7 @@ test("workspace update stream keeps persisted workspace visible after agents sto
         getAgent: () => null,
       }),
       agentStorage: asAgentStorage({
-        list: async () => [],
+        listAll: async () => [],
         get: async () => null,
       }),
       projectRegistry: {
@@ -3703,7 +3821,10 @@ test("workspace update stream keeps persisted workspace visible after agents sto
       workspaceRegistry: {
         initialize: async () => {},
         existsOnDisk: async () => true,
-        list: async () => [
+        listActive: async function () {
+          return (await this.listAll()).filter((record) => !record.archivedAt);
+        },
+        listAll: async () => [
           createPersistedWorkspaceRecord({
             workspaceId: "ws-repo-running",
             projectId: "proj-repo-running",
@@ -3850,7 +3971,9 @@ test("archiving the last workspace emits a remove carrying the now-empty project
   });
 
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [archivedWorkspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    archivedWorkspace,
+  ];
   session.workspaceRegistry.get = async (workspaceId: string) =>
     workspaceId === archivedWorkspace.workspaceId ? archivedWorkspace : null;
 
@@ -3918,7 +4041,8 @@ test("project.remove.request archives active workspaces and removes the project
   };
   session.workspaceRegistry.get = async (workspaceId: string) =>
     workspaces.get(workspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.archive = async (workspaceId: string, archivedAt: string) => {
     const existing = workspaces.get(workspaceId);
     if (!existing) return;
@@ -4014,7 +4138,8 @@ test("project.remove.request removes an already-empty project", async () => {
   };
   session.workspaceRegistry.get = async (workspaceId: string) =>
     workspaces.get(workspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.archive = async (workspaceId: string, archivedAt: string) => {
     const existing = workspaces.get(workspaceId);
     if (!existing) return;
@@ -4130,7 +4255,8 @@ test("create paseo worktree response preserves an explicit non-Git project", asy
   session.paseoHome = paseoHome;
   session.workspaceRegistry.get = async (lookupWorkspaceId: string) =>
     workspaces.get(lookupWorkspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.upsert = async (
     record: ReturnType<typeof createPersistedWorkspaceRecord>,
   ) => {
@@ -4210,7 +4336,7 @@ test("workspace updates stay scoped to the matching cwd", async () => {
   const mainCwd = path.join(missingRoot, "main");
   const featureCwd = path.join(missingRoot, "feature");
   const session = createSessionForWorkspaceTests();
-  session.workspaceRegistry.list = async () => [
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
     createPersistedWorkspaceRecord({
       workspaceId: "ws-repo-main",
       projectId: "proj-repo-main",
@@ -4311,7 +4437,8 @@ test("open_project_request registers a workspace before any agent exists", async
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.buildProjectPlacement = async (cwd: string) => ({
     projectKey: cwd,
     projectName: "repo",
@@ -4366,7 +4493,8 @@ test("import_agent_request registers a workspace for a never-seen cwd", async ()
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.buildProjectPlacement = async (cwd: string) => ({
     projectKey: cwd,
     projectName: "imported",
@@ -4391,7 +4519,7 @@ test("import_agent_request registers a workspace for a never-seen cwd", async ()
   session.agentManager.importProviderSession = async () => managed;
   session.agentManager.getTimeline = () => [];
   session.agentManager.setTitle = async () => undefined;
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentStorage.get = async () => null;
   session.agentUpdates.forwardLiveAgent = async () => undefined;
 
@@ -4480,7 +4608,7 @@ test("import_agent_request imports into the workspace that opened the import she
     });
   };
   session.agentManager.getTimeline = () => [];
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentStorage.get = async () => null;
   session.agentUpdates.forwardLiveAgent = async () => undefined;
 
@@ -4511,7 +4639,7 @@ test("import_agent_request maps an import failure to agent_create_failed", async
       createdAt: "2026-03-01T12:00:00.000Z",
       updatedAt: "2026-03-01T12:00:00.000Z",
     });
-  session.agentStorage.list = async () => [];
+  session.agentStorage.listAll = async () => [];
   session.agentManager.importProviderSession = async () => {
     throw new Error("provider session is unavailable");
   };
@@ -4556,7 +4684,8 @@ test("open_project_response returns immediately even when the GitHub fetch is sl
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceGitService.getCheckout = async (requestedCwd: string) => ({
     cwd: requestedCwd,
     isGit: true,
@@ -4632,7 +4761,8 @@ test("open_project_request emits a workspace_update with githubRuntime once the
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceGitService.getCheckout = async (requestedCwd: string) => ({
     cwd: requestedCwd,
     isGit: true,
@@ -4743,7 +4873,8 @@ test("open_project_request does not match a new child directory to an existing p
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   await session.handleMessage({
     type: "open_project_request",
@@ -4812,7 +4943,8 @@ test("open_project_request does not unarchive an archived parent workspace for a
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   await session.handleMessage({
     type: "open_project_request",
@@ -4887,7 +5019,8 @@ test("open_project_request reclassifies an archived directory workspace when git
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceGitService.getCheckout = async () => ({
     cwd,
     isGit: true,
@@ -5003,7 +5136,8 @@ test("open_project_request reclassifies an active directory workspace when git m
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceGitService.getCheckout = async (requestedCwd: string) => ({
     cwd: requestedCwd,
     isGit: true,
@@ -5093,7 +5227,8 @@ test("open_project_request gives a plain git worktree its own exact-root project
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceGitService.getCheckout = async (requestedCwd: string) => ({
     cwd: requestedCwd,
     isGit: true,
@@ -5182,7 +5317,8 @@ test("open_project_request keeps archived records and allocates a fresh workspac
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   await session.handleMessage({
     type: "open_project_request",
@@ -5237,7 +5373,8 @@ test("open_project_request does not repurpose an orphaned archived workspace", a
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   await session.handleMessage({
     type: "open_project_request",
@@ -5297,7 +5434,9 @@ test("workspace recovery stays accepted when git observer warming fails", async
   };
   session.workspaceRegistry.get = async (workspaceId: string) =>
     workspaceId === workspace.workspaceId ? workspace : null;
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.upsert = async (record: PersistedWorkspaceRecord) => {
     workspace = record;
   };
@@ -5388,7 +5527,8 @@ test("refresh_agent_request leaves workspace archival independent when its direc
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   session.agentStorage.get = async (id: string) => (id === agentId ? storedAgent : null);
   session.agentStorage.upsert = async () => {};
@@ -5487,7 +5627,8 @@ test("refresh_agent_request leaves workspace archival independent when its direc
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   session.agentStorage.get = async (id: string) => (id === agentId ? storedAgent : null);
   session.agentStorage.upsert = async () => {};
@@ -5579,7 +5720,8 @@ test("refresh_agent_request does not recreate or unarchive a deleted worktree",
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   session.agentStorage.get = async (id: string) => (id === agentId ? storedAgent : null);
   session.agentStorage.upsert = async () => {};
@@ -5679,7 +5821,8 @@ test("refresh_agent_request does not inspect an archived worktree branch", async
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   session.agentStorage.get = async (id: string) => (id === agentId ? storedAgent : null);
   session.agentStorage.upsert = async () => {};
@@ -5810,7 +5953,8 @@ test("legacy refresh_agent_request restores a real deleted worktree", async () =
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.agentStorage.get = async (id: string) => (id === agentId ? storedAgent : null);
   session.agentStorage.upsert = async () => {};
 
@@ -5869,7 +6013,8 @@ test.skip("open_project_request collapses a git subdirectory onto the repo root
     workspaces.set(record.workspaceId, record);
   };
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.buildProjectPlacement = async (cwd: string) => ({
     projectKey: repoRoot,
     projectName: "repo",
@@ -5945,7 +6090,9 @@ test("archive_workspace_request hides non-destructive workspace records", async
   session.workspaceRegistry.archive = async (_workspaceId: string, archivedAt: string) => {
     workspace.archivedAt = archivedAt;
   };
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.projectRegistry.archive = async () => {};
 
   await session.handleMessage({
@@ -6045,7 +6192,9 @@ test("archive_workspace_request archives a worktree-kind workspace and removes t
     if (isSessionOutboundMessage(message)) emitted.push(message);
   };
   session.workspaceRegistry.get = async () => workspace;
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.archive = async (_id: string, archivedAt: string) => {
     workspace.archivedAt = archivedAt;
   };
@@ -6131,7 +6280,8 @@ test.skip("opening a new worktree reconciles older local workspaces into the rem
   };
   session.workspaceRegistry.get = async (lookupWorkspaceId: string) =>
     workspaces.get(lookupWorkspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.upsert = async (
     record: ReturnType<typeof createPersistedWorkspaceRecord>,
   ) => {
@@ -6237,7 +6387,8 @@ test.skip("fetch_workspaces_request reconciles remote URL changes for existing w
   };
   session.workspaceRegistry.get = async (lookupWorkspaceId: string) =>
     workspaces.get(lookupWorkspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.upsert = async (
     record: ReturnType<typeof createPersistedWorkspaceRecord>,
   ) => {
@@ -6333,7 +6484,8 @@ test.skip("reconcile archives stale subdirectory workspace records when collapsi
   };
   session.workspaceRegistry.get = async (lookupWorkspaceId: string) =>
     workspaces.get(lookupWorkspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.upsert = async (
     record: ReturnType<typeof createPersistedWorkspaceRecord>,
   ) => {
@@ -6393,7 +6545,9 @@ test("listWorkspaceDescriptorsSnapshot keeps git workspaces on the baseline desc
 
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
 
   const baselineDescriptor = {
     id: workspace.workspaceId,
@@ -6455,7 +6609,9 @@ test("lists Git runtime for a checkout explicitly owned by a non-Git project", a
   });
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRuntimeStore.get = () => createWorkspaceRuntimeSnapshot(REPO_CWD);
 
   const descriptors = Array.from(
@@ -6489,7 +6645,9 @@ test("buildWorkspaceDescriptorMap computes statusEnteredAt from runtime agent fi
       updatedAt: "2026-03-01T12:00:00.000Z",
     });
     session.projectRegistry.list = async () => [project];
-    session.workspaceRegistry.list = async () => [workspace];
+    session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+      workspace,
+    ];
     return { session, workspace };
   };
 
@@ -6716,7 +6874,10 @@ test("same-cwd workspace descriptors compute agent status per workspaceId", asyn
     updatedAt: "2026-03-01T12:00:01.000Z",
   });
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspaceA, workspaceB];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspaceA,
+    workspaceB,
+  ];
 
   // A running agent owned by A leaves the sibling B done — status is per id.
   session.listAgentPayloads = async () => [
@@ -6773,7 +6934,9 @@ test("buildWorkspaceDescriptorMap keeps a done workspace recent after its agents
   const archivedAt = "2026-05-12T09:45:00.000Z";
 
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.listAgentPayloads = async () => [
     makeAgent({
       id: "agent-done",
@@ -6831,7 +6994,9 @@ test("buildWorkspaceDescriptorMap stamps workspace archiving state", async () =>
 
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
 
   const readArchivingAt = async () =>
     (
@@ -6879,7 +7044,9 @@ test("emitWorkspaceUpdatesForWorkspaceIds includes archiving state and dedupes u
   });
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
 
   emitted.length = 0;
   session.markWorkspaceArchiving([workspace.workspaceId], archivingAt);
@@ -6935,7 +7102,7 @@ test("external workspace updates emit one deduplicated batch", async () => {
     snapshotReads.projects += 1;
     return [project];
   };
-  session.workspaceRegistry.list = async () => {
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => {
     snapshotReads.workspaces += 1;
     return [main, feature];
   };
@@ -6986,7 +7153,8 @@ test("external workspace updates emit one deduplicated batch", async () => {
       },
     },
   ]);
-  expect(snapshotReads).toEqual({ projects: 1, workspaces: 1 });
+  // Scoped projection reads each of the two requested workspace IDs once.
+  expect(snapshotReads).toEqual({ projects: 1, workspaces: 2 });
 });
 
 test("fetch_workspaces_response reads runtime fields from passive workspace git service snapshots", async () => {
@@ -7047,7 +7215,9 @@ test("fetch_workspaces_response reads runtime fields from passive workspace git
   };
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.buildProjectPlacement = async (cwd: string) => ({
     projectKey: cwd,
     projectName: "repo",
@@ -7146,7 +7316,9 @@ test("fetch_workspaces_response emits before cold registration-triggered git wor
 
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
 
   await session.handleMessage({
     type: "fetch_workspaces_request",
@@ -7214,7 +7386,9 @@ test("workspace_update includes updated runtime fields", async () => {
   });
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.buildProjectPlacement = async (cwd: string) => ({
     projectKey: cwd,
     projectName: "repo",
@@ -7327,7 +7501,10 @@ test("subscribed fetch_workspaces includes git enrichment in the initial snapsho
   };
   session.listAgentPayloads = async () => [];
   session.projectRegistry.list = async () => [gitProject, directoryProject];
-  session.workspaceRegistry.list = async () => [gitWorkspace, directoryWorkspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    gitWorkspace,
+    directoryWorkspace,
+  ];
   const describeWorkspaceRecordSubscribed = vi.fn(
     async (workspace: typeof gitWorkspace, project: unknown) => {
       if (workspace.workspaceId === gitWorkspace.workspaceId) {
@@ -7388,7 +7565,10 @@ test("workspace mutation handling does not let a delayed upsert recreate an arch
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => listedWorkspaces,
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => listedWorkspaces,
     get: async (workspaceId: string) => (workspaceId === workspace.workspaceId ? workspace : null),
     update: async () => null,
     upsert: async () => {},
@@ -7433,14 +7613,16 @@ test("workspace mutation handling does not let a delayed upsert recreate an arch
   });
   listedWorkspaces = [workspace];
 
+  const getWorkspace = workspaceRegistry.get.bind(workspaceRegistry);
   let resumeDescribe!: () => void;
   const describeStarted = new Promise<void>((resolveStarted) => {
-    workspaceRegistry.list = async () => {
+    workspaceRegistry.get = async (workspaceId) => {
+      workspaceRegistry.get = getWorkspace;
       resolveStarted();
       await new Promise<void>((resolveResume) => {
         resumeDescribe = resolveResume;
       });
-      return listedWorkspaces;
+      return listedWorkspaces.find((record) => record.workspaceId === workspaceId) ?? null;
     };
   });
 
@@ -7510,7 +7692,10 @@ test("workspace mutations outside a filtered subscription neither watch nor emit
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => [workspace],
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => [workspace],
     get: async (workspaceId: string) => (workspaceId === workspace.workspaceId ? workspace : null),
     update: async () => null,
     upsert: async () => {},
@@ -7626,7 +7811,10 @@ test("project removal mutation broadcasts the final delta to another subscribed
     workspaceRegistry: {
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => [workspace],
+      listActive: async function () {
+        return (await this.listAll()).filter((record) => !record.archivedAt);
+      },
+      listAll: async () => [workspace],
       get: async (workspaceId) => (workspaceId === workspace.workspaceId ? workspace : null),
       update: async () => null,
       upsert: async () => {},
@@ -7700,7 +7888,10 @@ test("workspace mutation handling drops queued observer sync after session clean
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => listedWorkspaces,
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => listedWorkspaces,
     get: async (workspaceId: string) => workspaces.get(workspaceId) ?? null,
     update: async () => null,
     upsert: async () => {},
@@ -7965,7 +8156,7 @@ test("project.icon.set.request publishes a custom icon that project.icon.get ser
     projects.set(id, updated);
     return updated;
   };
-  session.workspaceRegistry.list = async () => [];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [];
 
   await session.handleMessage({
     type: "project.icon.set.request",
@@ -8055,7 +8246,9 @@ test("project.rename.request stores customName and emits an updated workspace de
     const parsed = record as typeof project;
     projects.set(parsed.projectId, parsed);
   };
-  session.workspaceRegistry.list = async () => [workspace];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [
+    workspace,
+  ];
   session.workspaceRegistry.get = async (id: string) =>
     id === workspace.workspaceId ? workspace : null;
 
@@ -8111,7 +8304,7 @@ test("project.rename.request updates a project with no workspaces", async () =>
   });
   session.projectRegistry.get = async () => project;
   session.projectRegistry.upsert = async () => project;
-  session.workspaceRegistry.list = async () => [];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [];
 
   await session.handleMessage({
     type: "project.rename.request",
@@ -8153,7 +8346,7 @@ test("project.rename.request with whitespace-only customName clears the override
     const parsed = record as typeof project;
     projects.set(parsed.projectId, parsed);
   };
-  session.workspaceRegistry.list = async () => [];
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () => [];
 
   await session.handleMessage({
     type: "project.rename.request",
@@ -8224,7 +8417,8 @@ test("workspace.title.set.request stores the title and emits an updated descript
   const workspaces = new Map([[workspace.workspaceId, workspace]]);
   session.projectRegistry.get = async (id: string) => projects.get(id) ?? null;
   session.projectRegistry.list = async () => Array.from(projects.values());
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.get = async (id: string) => workspaces.get(id) ?? null;
   session.workspaceRegistry.update = async (id, updater) => {
     const existing = workspaces.get(id);
@@ -8294,7 +8488,8 @@ test("workspace.pin.set.request stores the pin timestamp and emits an updated de
   const workspaces = new Map([[workspace.workspaceId, workspace]]);
   session.projectRegistry.get = async (id: string) => (id === project.projectId ? project : null);
   session.projectRegistry.list = async () => [project];
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.update = async (id, updater) => {
     const existing = workspaces.get(id);
     if (!existing) return null;
@@ -8351,7 +8546,8 @@ test("workspace.title.set.request with whitespace-only title clears the title",
   });
 
   const workspaces = new Map([[workspace.workspaceId, workspace]]);
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.get = async (id: string) => workspaces.get(id) ?? null;
   session.workspaceRegistry.update = async (id, updater) => {
     const existing = workspaces.get(id);
@@ -8425,7 +8621,10 @@ async function createSessionWithTerminalManager(options: {
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => options.workspaces,
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => options.workspaces,
     get: async (workspaceId: string) =>
       options.workspaces.find((workspace) => workspace.workspaceId === workspaceId) ?? null,
     upsert: async () => {},
@@ -8482,7 +8681,7 @@ test("overlapping workspace rebuilds publish the newest provider subagent status
   let listener: ((event: AgentManagerEvent) => void) | null = null;
   const session = createSessionForWorkspaceTests({
     onMessage: (message) => emitted.push(message),
-    agentStorage: { list: async () => [] },
+    agentStorage: { listAll: async () => [] },
     agentManager: {
       subscribe: (nextListener: (event: AgentManagerEvent) => void) => {
         listener = nextListener;
@@ -9029,7 +9228,10 @@ test("workspace.create worktree source checks out a GitHub PR from githubPrNumbe
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => Array.from(workspaces.values()),
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => Array.from(workspaces.values()),
     get: async (workspaceId: string) => workspaces.get(workspaceId) ?? null,
     upsert: async (record) => {
       workspaces.set(record.workspaceId, record);
@@ -9353,7 +9555,8 @@ test("checkout.rename_branch.request renames the branch without a denormalized b
 
   const workspaces = new Map([[workspace.workspaceId, workspace]]);
   const upsertedRecords: Array<typeof workspace> = [];
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
   session.workspaceRegistry.get = async (id: string) => workspaces.get(id) ?? null;
   session.workspaceRegistry.upsert = async (record: unknown) => {
     const parsed = record as typeof workspace;
@@ -9393,7 +9596,10 @@ test("workspace.create.response persists the first prompt as the initial title",
     workspaceRegistry: {
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => Array.from(workspaces.values()),
+      listActive: async function () {
+        return (await this.listAll()).filter((record) => !record.archivedAt);
+      },
+      listAll: async () => Array.from(workspaces.values()),
       get: async (workspaceId: string) => workspaces.get(workspaceId) ?? null,
       upsert: async (workspace) => {
         workspaces.set(workspace.workspaceId, workspace);
@@ -9434,7 +9640,10 @@ test("workspace create emits through a matching workspace subscription", async (
     workspaceRegistry: {
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => Array.from(workspaces.values()),
+      listActive: async function () {
+        return (await this.listAll()).filter((record) => !record.archivedAt);
+      },
+      listAll: async () => Array.from(workspaces.values()),
       get: async (workspaceId) => workspaces.get(workspaceId) ?? null,
       upsert: async (workspace, context) => {
         workspaces.set(workspace.workspaceId, workspace);
@@ -9486,7 +9695,10 @@ test("workspace create stays out of a non-matching workspace subscription", asyn
     workspaceRegistry: {
       initialize: async () => {},
       existsOnDisk: async () => true,
-      list: async () => Array.from(workspaces.values()),
+      listActive: async function () {
+        return (await this.listAll()).filter((record) => !record.archivedAt);
+      },
+      listAll: async () => Array.from(workspaces.values()),
       get: async (workspaceId) => workspaces.get(workspaceId) ?? null,
       upsert: async (workspace) => {
         workspaces.set(workspace.workspaceId, workspace);
@@ -9568,7 +9780,8 @@ test("workspace.create.request with background persists a hidden workspace that
   };
   session.workspaceRegistry.get = async (workspaceId: string) =>
     workspaces.get(workspaceId) ?? null;
-  session.workspaceRegistry.list = async () => Array.from(workspaces.values());
+  session.workspaceRegistry.listAll = session.workspaceRegistry.listActive = async () =>
+    Array.from(workspaces.values());
 
   await session.handleMessage({
     type: "workspace.create.request",
@@ -9763,7 +9976,10 @@ test("workspace PR status survives session cleanup and reconnect", async () => {
   const workspaceRegistry: SessionOptions["workspaceRegistry"] = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => [workspace],
+    listActive: async function () {
+      return (await this.listAll()).filter((record) => !record.archivedAt);
+    },
+    listAll: async () => [workspace],
     get: async (id) => (id === workspace.workspaceId ? workspace : null),
     update: async (id, updater) => (id === workspace.workspaceId ? updater(workspace) : null),
     upsert: async () => {},
@@ -9934,3 +10150,77 @@ test("workspace PR status survives session cleanup and reconnect", async () => {
     await gitService.dispose();
   }
 });
+
+test("path archive of an archived exact child leaves its active parent untouched", async () => {
+  const now = "2026-03-30T15:00:00.000Z";
+  const root = mkdtempSync(path.join(tmpdir(), "archive-exact-child-"));
+  const childPath = path.join(root, "sub");
+  mkdirSync(childPath);
+  const parent = createPersistedWorkspaceRecord({
+    workspaceId: "parent",
+    projectId: "project",
+    cwd: root,
+    kind: "directory",
+    displayName: "parent",
+    createdAt: now,
+    updatedAt: now,
+  });
+  const child = createPersistedWorkspaceRecord({
+    workspaceId: "child",
+    projectId: "project",
+    cwd: childPath,
+    kind: "directory",
+    displayName: "child",
+    createdAt: now,
+    updatedAt: now,
+    archivedAt: now,
+  });
+  const records = [parent, child];
+  const archivedAgents: string[] = [];
+  const archivedWorkspaces: string[] = [];
+  const emitted: SessionOutboundMessage[] = [];
+  const session = createSessionForWorkspaceTests({
+    onMessage: (message) => emitted.push(message),
+    agentManager: {
+      listAgents: () => [
+        makeManagedAgent({
+          id: "parent-agent",
+          cwd: root,
+          workspaceId: parent.workspaceId,
+          lifecycle: "idle",
+          updatedAt: now,
+        }),
+      ],
+      archiveAgent: async (id: string) => {
+        archivedAgents.push(id);
+        return { archivedAt: now };
+      },
+    },
+    workspaceRegistry: {
+      initialize: async () => {},
+      existsOnDisk: async () => true,
+      listAll: async () => records,
+      listActive: async () => records.filter((record) => !record.archivedAt),
+      get: async (id) => records.find((record) => record.workspaceId === id) ?? null,
+      upsert: async () => {},
+      update: async () => null,
+      remove: async () => {},
+      archive: async (id) => {
+        archivedWorkspaces.push(id);
+      },
+    },
+  });
+  try {
+    await session.handleMessage({
+      type: "paseo_worktree_archive_request",
+      requestId: "archive-exact",
+      worktreePath: childPath,
+    });
+    expect(archivedAgents).toEqual([]);
+    expect(archivedWorkspaces).toEqual([]);
+    expect(parent.archivedAt).toBeNull();
+    expect(existsSync(root)).toBe(true);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/packages/server/src/server/session/agent-config/agent-config-session.test.ts b/packages/server/src/server/session/agent-config/agent-config-session.test.ts
index 1592c5bb3d..d6589683a7 100644
--- a/packages/server/src/server/session/agent-config/agent-config-session.test.ts
+++ b/packages/server/src/server/session/agent-config/agent-config-session.test.ts
@@ -12,7 +12,7 @@ class FakeAgentConfigOperations implements AgentConfigOperations {
   readonly loadedAgentIds: string[] = [];
   readonly modeCalls: Array<{ agentId: string; modeId: string }> = [];
   readonly modelCalls: Array<{ agentId: string; modelId: string | null }> = [];
-  readonly featureCalls: Array<{ agentId: string; featureId: string; value: unknown }> = [];
+  readonly optionsCalls: Array<{ agentId: string; patch: Record<string, unknown> }> = [];
   readonly thinkingCalls: Array<{ agentId: string; thinkingOptionId: string | null }> = [];
   /** Cross-operation ordering, which the per-operation arrays above cannot show. */
   readonly callLog: string[] = [];
@@ -39,9 +39,9 @@ class FakeAgentConfigOperations implements AgentConfigOperations {
     if (this.failWith) throw this.failWith;
   }
 
-  async setFeature(agentId: string, featureId: string, value: unknown): Promise<void> {
-    this.featureCalls.push({ agentId, featureId, value });
-    this.callLog.push(`feature:${featureId}`);
+  async setOptions(agentId: string, patch: Record<string, unknown>): Promise<void> {
+    this.optionsCalls.push({ agentId, patch });
+    this.callLog.push("options");
     if (this.failWith) throw this.failWith;
   }
 
@@ -206,7 +206,7 @@ describe("AgentConfigSession", () => {
     });
   });
 
-  test("set feature: forwards the feature value and emits an accepted response with no notice", async () => {
+  test("set feature: maps the feature value to a one-key options patch and emits an accepted response with no notice", async () => {
     const { subsystem, emitted, operations } = makeSubsystem();
 
     await subsystem.handleSetAgentFeatureRequest({
@@ -217,9 +217,7 @@ describe("AgentConfigSession", () => {
       requestId: "req-1",
     });
 
-    expect(operations.featureCalls).toEqual([
-      { agentId: "agent-1", featureId: "web_search", value: true },
-    ]);
+    expect(operations.optionsCalls).toEqual([{ agentId: "agent-1", patch: { web_search: true } }]);
     expect(emitted).toEqual([
       {
         type: "set_agent_feature_response",
@@ -309,7 +307,7 @@ describe("AgentConfigSession", () => {
     });
   });
 
-  test("apply: sets model before thinking and features last, in one accepted response", async () => {
+  test("apply: sets model before thinking and options last, in one accepted response", async () => {
     const { subsystem, emitted, operations } = makeSubsystem();
 
     await subsystem.handleAgentConfigApplyRequest({
@@ -319,18 +317,16 @@ describe("AgentConfigSession", () => {
         modelId: "opus-5",
         modeId: "plan",
         thinkingOptionId: "high",
-        featureValues: { webSearch: true },
+        options: { webSearch: true },
       },
       requestId: "req-1",
     });
 
-    expect(operations.callLog).toEqual(["model", "mode", "thinking", "feature:webSearch"]);
+    expect(operations.callLog).toEqual(["model", "mode", "thinking", "options"]);
     expect(operations.modelCalls).toEqual([{ agentId: "agent-1", modelId: "opus-5" }]);
     expect(operations.modeCalls).toEqual([{ agentId: "agent-1", modeId: "plan" }]);
     expect(operations.thinkingCalls).toEqual([{ agentId: "agent-1", thinkingOptionId: "high" }]);
-    expect(operations.featureCalls).toEqual([
-      { agentId: "agent-1", featureId: "webSearch", value: true },
-    ]);
+    expect(operations.optionsCalls).toEqual([{ agentId: "agent-1", patch: { webSearch: true } }]);
     expect(operations.loadedAgentIds).toEqual(["agent-1"]);
     expect(emitted).toEqual([
       {
@@ -346,6 +342,39 @@ describe("AgentConfigSession", () => {
     ]);
   });
 
+  test("apply: passes an options patch through, null included, in one call", async () => {
+    const { subsystem, operations } = makeSubsystem();
+
+    await subsystem.handleAgentConfigApplyRequest({
+      type: "agent.config.apply.request",
+      agentId: "agent-1",
+      config: { options: { fast_mode: true, service_tier: null } },
+      requestId: "req-1",
+    });
+
+    expect(operations.optionsCalls).toEqual([
+      { agentId: "agent-1", patch: { fast_mode: true, service_tier: null } },
+    ]);
+  });
+
+  test("apply: folds legacy featureValues into the options patch, options winning", async () => {
+    const { subsystem, operations } = makeSubsystem();
+
+    await subsystem.handleAgentConfigApplyRequest({
+      type: "agent.config.apply.request",
+      agentId: "agent-1",
+      config: {
+        featureValues: { fast_mode: true, service_tier: "fast" },
+        options: { fast_mode: false },
+      },
+      requestId: "req-1",
+    });
+
+    expect(operations.optionsCalls).toEqual([
+      { agentId: "agent-1", patch: { fast_mode: false, service_tier: "fast" } },
+    ]);
+  });
+
   test("apply: leaves omitted fields alone", async () => {
     const { subsystem, operations } = makeSubsystem();
 
@@ -381,11 +410,11 @@ describe("AgentConfigSession", () => {
     await subsystem.handleAgentConfigApplyRequest({
       type: "agent.config.apply.request",
       agentId: "agent-1",
-      config: { modeId: "plan", thinkingOptionId: "high", featureValues: { webSearch: true } },
+      config: { modeId: "plan", thinkingOptionId: "high", options: { webSearch: true } },
       requestId: "req-1",
     });
 
-    expect(operations.callLog).toEqual(["mode", "thinking", "feature:webSearch"]);
+    expect(operations.callLog).toEqual(["mode", "thinking", "options"]);
     expect(emitted).toEqual([
       {
         type: "agent.config.apply.response",
diff --git a/packages/server/src/server/session/agent-config/agent-config-session.ts b/packages/server/src/server/session/agent-config/agent-config-session.ts
index 8cf2394192..b7ba697670 100644
--- a/packages/server/src/server/session/agent-config/agent-config-session.ts
+++ b/packages/server/src/server/session/agent-config/agent-config-session.ts
@@ -3,6 +3,7 @@ import { v4 as uuidv4 } from "uuid";
 import { getErrorMessage, getErrorMessageOr } from "@getpaseo/protocol/error-utils";
 import type { AgentConfigApply } from "@getpaseo/protocol/messages";
 import type { AgentProviderNotice } from "../../agent/agent-sdk-types.js";
+import type { ProviderOptionsPatch } from "../../agent/option-controls.js";
 import type { SessionInboundMessage, SessionOutboundMessage } from "../../messages.js";
 
 /**
@@ -22,13 +23,13 @@ export interface AgentConfigSessionHost {
  * The per-agent config mutations this subsystem drives. The shell adapts these
  * onto the AgentManager and loads a closed agent before mutation (mode still
  * routes through setAgentModeCommand); tests wire an in-memory fake. Mode and
- * thinking yield a provider notice; model and feature do not.
+ * thinking yield a provider notice; model and options do not.
  */
 export interface AgentConfigOperations {
   ensureLoaded(agentId: string): Promise<void>;
   setMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null>;
   setModel(agentId: string, modelId: string | null): Promise<void>;
-  setFeature(agentId: string, featureId: string, value: unknown): Promise<void>;
+  setOptions(agentId: string, patch: ProviderOptionsPatch): Promise<void>;
   setThinking(
     agentId: string,
     thinkingOptionId: string | null,
@@ -112,8 +113,9 @@ export class AgentConfigSession {
       logLabel: "set_agent_feature_request",
       logFields: { agentId, featureId, value, requestId },
       failureText: "Failed to set agent feature",
+      // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. A feature is a one-key options patch.
       run: async () => {
-        await this.operations.setFeature(agentId, featureId, value);
+        await this.operations.setOptions(agentId, { [featureId]: value });
         return undefined;
       },
       emitResponse: (payload) => this.host.emit({ type: "set_agent_feature_response", payload }),
@@ -152,7 +154,7 @@ export class AgentConfigSession {
 
   /**
    * Model first, because a thinking option only means anything against the model
-   * that offers it; features last so they settle on top of the rest. An omitted
+   * that offers it; options last so they settle on top of the rest. An omitted
    * field is left alone. The first notice produced is the one the client sees —
    * later steps still run, so a notice never truncates the bundle.
    *
@@ -189,8 +191,10 @@ export class AgentConfigSession {
       const thinkingNotice = await this.operations.setThinking(agentId, config.thinkingOptionId);
       notice ??= thinkingNotice;
     }
-    for (const [featureId, value] of Object.entries(config.featureValues ?? {})) {
-      await this.operations.setFeature(agentId, featureId, value);
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. `featureValues` is an options patch.
+    const optionsPatch = { ...config.featureValues, ...config.options };
+    if (Object.keys(optionsPatch).length > 0) {
+      await this.operations.setOptions(agentId, optionsPatch);
     }
 
     return notice;
diff --git a/packages/server/src/server/session/agent-updates/agent-updates-service.ts b/packages/server/src/server/session/agent-updates/agent-updates-service.ts
index f17e2a2067..789dcbe5c3 100644
--- a/packages/server/src/server/session/agent-updates/agent-updates-service.ts
+++ b/packages/server/src/server/session/agent-updates/agent-updates-service.ts
@@ -7,6 +7,7 @@ import type {
 } from "../../messages.js";
 import type { ManagedAgent } from "../../agent/agent-manager.js";
 import type { StoredAgentRecord } from "../../agent/agent-storage.js";
+import type { BackgroundVisibility } from "../../agent/directory.js";
 import { resolveEffectiveThinkingOptionId, toAgentPayload } from "../../agent/agent-projections.js";
 
 type AgentUpdatePayload = Extract<SessionOutboundMessage, { type: "agent_update" }>["payload"];
@@ -19,6 +20,7 @@ interface AgentUpdatesSubscriptionState {
   emit: (message: SessionOutboundMessage) => void;
   syncEnabled: boolean;
   filter?: AgentUpdatesFilter;
+  backgroundVisibility: BackgroundVisibility;
   isProviderVisible: (provider: string) => boolean;
   isBootstrapping: boolean;
   pendingUpdatesByAgentId: Map<string, AgentUpdatePayload>;
@@ -31,6 +33,7 @@ export interface AgentUpdatesService {
     isProviderVisible?: (provider: string) => boolean;
     emit?: (message: SessionOutboundMessage) => void;
     filter?: AgentUpdatesFilter;
+    backgroundVisibility?: BackgroundVisibility;
     syncEnabled?: boolean;
   }): void;
   flushBootstrapped(
@@ -47,7 +50,10 @@ export interface AgentUpdatesService {
 }
 
 export interface AgentUpdatesServiceDeps {
-  includesWorkspace?(agent: AgentSnapshotPayload, includeBackground?: boolean): Promise<boolean>;
+  includesWorkspace?(
+    agent: AgentSnapshotPayload,
+    backgroundVisibility: BackgroundVisibility,
+  ): Promise<boolean>;
   emit(message: SessionOutboundMessage): void;
   enrichAgentPayload(payload: AgentSnapshotPayload): Promise<AgentSnapshotPayload>;
   buildStoredAgentPayload(record: StoredAgentRecord): AgentSnapshotPayload;
@@ -60,7 +66,7 @@ export interface AgentUpdatesServiceDeps {
     project: ProjectPlacementPayload | null,
     agentId: string,
     includeSequence: boolean,
-    includeBackground?: boolean,
+    backgroundVisibility: BackgroundVisibility,
   ): T;
   logger: pino.Logger;
 }
@@ -173,7 +179,7 @@ export function createAgentUpdatesService(deps: AgentUpdatesServiceDeps): AgentU
       project,
       agentId,
       sub.syncEnabled === true,
-      sub.filter?.includeBackground,
+      sub.backgroundVisibility,
     );
 
   function bufferOrEmit(sub: AgentUpdatesSubscriptionState, payload: AgentUpdatePayload): void {
@@ -194,10 +200,12 @@ export function createAgentUpdatesService(deps: AgentUpdatesServiceDeps): AgentU
     isProviderVisible?: (provider: string) => boolean;
     emit?: (message: SessionOutboundMessage) => void;
     filter?: AgentUpdatesFilter;
+    backgroundVisibility?: BackgroundVisibility;
     syncEnabled?: boolean;
   }): void {
     subscriptions.set(input.subscriptionId, {
       ...input,
+      backgroundVisibility: input.backgroundVisibility ?? false,
       emit: input.emit ?? deps.emit,
       syncEnabled: input.syncEnabled ?? false,
       isProviderVisible: input.isProviderVisible ?? deps.isProviderVisibleToClient,
@@ -249,9 +257,7 @@ export function createAgentUpdatesService(deps: AgentUpdatesServiceDeps): AgentU
       ? await deps.buildProjectPlacementForWorkspaceId(payload.workspaceId)
       : null;
     const backgroundVisible = await Promise.all(
-      observers.map(
-        (sub) => deps.includesWorkspace?.(payload, sub.filter?.includeBackground) ?? true,
-      ),
+      observers.map((sub) => deps.includesWorkspace?.(payload, sub.backgroundVisibility) ?? true),
     );
     return (
       project !== null &&
@@ -273,7 +279,7 @@ export function createAgentUpdatesService(deps: AgentUpdatesServiceDeps): AgentU
     for (const sub of observers) {
       const matches =
         project &&
-        ((await deps.includesWorkspace?.(payload, sub.filter?.includeBackground)) ?? true) &&
+        ((await deps.includesWorkspace?.(payload, sub.backgroundVisibility)) ?? true) &&
         matchesAgentUpdatesFilter({ agent: payload, project, filter: sub.filter });
       bufferOrEmit(
         sub,
diff --git a/packages/server/src/server/session/checkout/checkout-session.test.ts b/packages/server/src/server/session/checkout/checkout-session.test.ts
index aaa79e3da1..61c9328e48 100644
--- a/packages/server/src/server/session/checkout/checkout-session.test.ts
+++ b/packages/server/src/server/session/checkout/checkout-session.test.ts
@@ -50,6 +50,7 @@ function createFakeDiffSubscriber(initial: CheckoutDiffSnapshotPayload) {
   const subscriptions: FakeDiffSubscription[] = [];
   const refreshedCwds: string[] = [];
   const subscriber: CheckoutDiffSubscriber = {
+    readCommitFile: async () => null,
     read: async (params) => ({ ...initial, cwd: params.cwd }),
     subscribe: async (params, listener) => {
       let isSubscribed = true;
@@ -77,7 +78,7 @@ function createFakeDiffSubscriber(initial: CheckoutDiffSnapshotPayload) {
         unsubscribe,
       };
     },
-    scheduleRefreshForCwd: (cwd) => {
+    scheduleRefreshForCwd: async (cwd) => {
       refreshedCwds.push(cwd);
     },
   };
diff --git a/packages/server/src/server/session/checkout/checkout-session.ts b/packages/server/src/server/session/checkout/checkout-session.ts
index ceb69e9623..1611356bc8 100644
--- a/packages/server/src/server/session/checkout/checkout-session.ts
+++ b/packages/server/src/server/session/checkout/checkout-session.ts
@@ -51,7 +51,6 @@ import {
   pullCurrentBranch,
   pushCurrentBranch,
   listCheckoutCommits,
-  getCommitFileDiff,
 } from "../../../utils/checkout-git.js";
 import { runGitCommand } from "../../../utils/run-git-command.js";
 import { expandTilde } from "../../../utils/path.js";
@@ -109,6 +108,7 @@ function toLegacyGithubSearchItems(items: ForgeSearchResultItem[]): LegacyGithub
  * real CheckoutDiffManager satisfies this structurally; tests supply a fake.
  */
 export interface CheckoutDiffSubscriber {
+  readCommitFile: import("../../diff/index.js").DiffSubscriptions["readCommitFile"];
   read(
     params: Omit<CheckoutDiffSubscriptionRequest, "signal">,
   ): Promise<CheckoutDiffSnapshotPayload>;
@@ -116,7 +116,7 @@ export interface CheckoutDiffSubscriber {
     params: CheckoutDiffSubscriptionRequest,
     listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
   ): Promise<CheckoutDiffSubscription>;
-  scheduleRefreshForCwd(cwd: string): void;
+  scheduleRefreshForCwd(cwd: string): Promise<void>;
 }
 
 export interface CheckoutSessionOptions {
@@ -301,7 +301,12 @@ export class CheckoutSession {
       if (path.length === 0 || isAbsolute(path) || path.split(/[\\/]/).includes("..")) {
         throw new Error(`Invalid path: ${path}`);
       }
-      const file = await getCommitFileDiff({ cwd: expandTilde(cwd), sha, path, signal });
+      const file = await this.checkoutDiffManager.readCommitFile({
+        cwd: expandTilde(cwd),
+        sha,
+        path,
+        signal,
+      });
       this.host.emit({
         type: "checkout.commits.file_diff.response",
         payload: { cwd, sha, path, file, error: null, requestId },
@@ -379,13 +384,14 @@ export class CheckoutSession {
   }
 
   async handleBranchSuggestionsRequest(msg: BranchSuggestionsRequest): Promise<void> {
-    const { cwd, query, limit, requestId } = msg;
+    const { cwd, query, limit, refMode, requestId } = msg;
 
     try {
       const resolvedCwd = expandTilde(cwd);
       const branchDetails = await this.workspaceGitService.suggestBranchesForCwd(resolvedCwd, {
         query,
         limit,
+        refMode,
       });
       this.host.emit({
         type: "branch_suggestions_response",
@@ -493,7 +499,7 @@ export class CheckoutSession {
         includeForge: true,
         reason: "manual-refresh",
       });
-      this.checkoutDiffManager.scheduleRefreshForCwd(resolvedCwd);
+      await this.checkoutDiffManager.scheduleRefreshForCwd(resolvedCwd);
       this.host.emit({
         type: "checkout.refresh.response",
         payload: {
@@ -547,8 +553,8 @@ export class CheckoutSession {
    * Notify the live diff subscriptions that the working tree at `cwd` changed.
    * Called by the command handlers below after they mutate the repository.
    */
-  private scheduleDiffRefresh(cwd: string): void {
-    this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
+  private scheduleDiffRefresh(cwd: string): Promise<void> {
+    return this.checkoutDiffManager.scheduleRefreshForCwd(cwd);
   }
 
   // ---------------------------------------------------------------------------
@@ -562,7 +568,7 @@ export class CheckoutSession {
 
     try {
       const checkoutResult = await this.gitMutation.checkoutExistingBranch(cwd, branch);
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
 
       // Push a workspace_update immediately so the sidebar/header reflect
       // the new branch name without waiting for the background git watcher.
@@ -614,7 +620,7 @@ export class CheckoutSession {
     try {
       const result = await this.host.renameCurrentBranch(cwd, branch);
       await this.gitMutation.notifyGitMutation(cwd, "rename-branch", { invalidateForge: true });
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
       this.host.handleWorkspaceGitBranchSnapshot(cwd, result.currentBranch);
 
       // Branch is a git fact derived per-descriptor from each workspace's own
@@ -656,7 +662,7 @@ export class CheckoutSession {
     try {
       await discardChanges(cwd, paths);
       await this.gitMutation.notifyGitMutation(cwd, "discard-changes");
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
       this.host.emit({
         type: "checkout.discard_changes.response",
         payload: { cwd, success: true, error: null, requestId },
@@ -683,7 +689,7 @@ export class CheckoutSession {
         timeout: 120_000,
       });
       await this.gitMutation.notifyGitMutation(cwd, "stash-push");
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
       this.host.emit({
         type: "stash_save_response",
         payload: { cwd, success: true, error: null, requestId },
@@ -706,7 +712,7 @@ export class CheckoutSession {
         timeout: 120_000,
       });
       await this.gitMutation.notifyGitMutation(cwd, "stash-pop");
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
       this.host.emit({
         type: "stash_pop_response",
         payload: { cwd, success: true, error: null, requestId },
@@ -758,7 +764,7 @@ export class CheckoutSession {
         addAll: msg.addAll ?? true,
       });
       await this.gitMutation.notifyGitMutation(cwd, "commit-changes");
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
 
       this.host.emit({
         type: "checkout_commit_response",
@@ -819,7 +825,7 @@ export class CheckoutSession {
         this.gitMutation.notifyGitMutation(mutatedCwd, "merge-to-base", { invalidateForge: true }),
         ...(mutatedCwd !== cwd ? [this.gitMutation.notifyGitMutation(cwd, "merge-to-base")] : []),
       ]);
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
 
       this.host.emit({
         type: "checkout_merge_response",
@@ -865,7 +871,7 @@ export class CheckoutSession {
         { paseoHome: this.paseoHome, worktreesRoot: this.worktreesRoot },
       );
       await this.gitMutation.notifyGitMutation(cwd, "merge-from-base", { invalidateForge: true });
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
 
       this.host.emit({
         type: "checkout_merge_from_base_response",
@@ -897,7 +903,7 @@ export class CheckoutSession {
     try {
       await pullCurrentBranch(cwd);
       await this.gitMutation.notifyGitMutation(cwd, "pull", { invalidateForge: true });
-      this.scheduleDiffRefresh(cwd);
+      await this.scheduleDiffRefresh(cwd);
 
       this.host.emit({
         type: "checkout_pull_response",
diff --git a/packages/server/src/server/session/owned-subscriptions/index.ts b/packages/server/src/server/session/owned-subscriptions/index.ts
index c17e5829be..4bb9b1eee4 100644
--- a/packages/server/src/server/session/owned-subscriptions/index.ts
+++ b/packages/server/src/server/session/owned-subscriptions/index.ts
@@ -56,6 +56,11 @@ export interface OwnedSubscription {
   release(): Promise<void>;
 }
 
+const BINARY_REPLY_REQUESTS: ReadonlySet<string> = new Set([
+  "file_explorer_request",
+  "plugin.rpc.invoke.request",
+]);
+
 // One registration per context kind; per-session registrations outlive closed sessions in Node.
 const requests = new AsyncLocalStorage<RequestOwner>();
 const projectionSource = new AsyncLocalStorage<ProjectionOwner>();
@@ -394,12 +399,13 @@ export class SessionDelivery {
     if (owner) await this.releaseOwner(owner);
   }
 
-  authorizeFileReply(frame: Uint8Array, socket: object): void {
+  /** Lets a binary frame answer the current request, for requests whose reply can be bytes. */
+  authorizeBinaryReply(frame: Uint8Array, socket: object): void {
     const owner = this.currentRequest;
     if (
       owner?.active &&
       owner.source.socket === socket &&
-      owner.request.type === "file_explorer_request"
+      BINARY_REPLY_REQUESTS.has(owner.request.type)
     )
       this.proofs.set(frame, owner);
   }
diff --git a/packages/server/src/server/session/provider/provider-catalog-session.test.ts b/packages/server/src/server/session/provider/provider-catalog-session.test.ts
index c1cec0b42a..704b6fd21b 100644
--- a/packages/server/src/server/session/provider/provider-catalog-session.test.ts
+++ b/packages/server/src/server/session/provider/provider-catalog-session.test.ts
@@ -13,7 +13,7 @@ import {
   type ProviderSnapshot,
   type ProviderSnapshotTransition,
 } from "../../agent/provider-snapshot-manager.js";
-import type { ProviderSnapshotEntry } from "../../agent/agent-sdk-types.js";
+import type { AgentSessionConfig, ProviderSnapshotEntry } from "../../agent/agent-sdk-types.js";
 import { expandProviderSnapshot } from "@getpaseo/protocol/provider-snapshot-codec";
 
 type SnapshotChangeHandler = (transition: ProviderSnapshotTransition) => void;
@@ -58,7 +58,7 @@ function makeSubsystem(options: MakeOptions = {}) {
     },
     supportsCompactProviderSnapshots: () => options.supportsCompactProviderSnapshots ?? false,
     listProviderAvailability: async () => [],
-    listDraftFeatures: async () => [],
+    listDraftControls: async () => ({ controls: [], options: {} }),
     ...options.host,
   };
   const providerSnapshotManager = createStub<ProviderSnapshotManager>({
@@ -296,10 +296,100 @@ describe("ProviderCatalogSession", () => {
     });
   });
 
+  it("lists controls and effective options for a draft config", async () => {
+    const drafts: AgentSessionConfig[] = [];
+    const { subsystem, emitted } = makeSubsystem({
+      host: {
+        listDraftControls: async (config) => {
+          drafts.push(config);
+          return {
+            controls: [{ type: "toggle", key: "fast_mode", label: "Fast" }],
+            options: { fast_mode: true },
+          };
+        },
+      },
+    });
+
+    await subsystem.handleProviderControlsListRequest({
+      type: "provider.controls.list.request",
+      requestId: "c1",
+      draftConfig: {
+        provider: "claude",
+        cwd: "/tmp/project",
+        model: "claude-opus-4-8",
+        providerOptions: { fast_mode: true },
+      },
+    });
+
+    expect(drafts).toEqual([
+      {
+        provider: "claude",
+        cwd: "/tmp/project",
+        model: "claude-opus-4-8",
+        providerOptions: { fast_mode: true },
+      },
+    ]);
+    expect(findByType(emitted, "provider.controls.list.response")?.payload).toEqual({
+      provider: "claude",
+      controls: [{ type: "toggle", key: "fast_mode", label: "Fast" }],
+      options: { fast_mode: true },
+      error: null,
+      fetchedAt: expect.any(String),
+      requestId: "c1",
+    });
+  });
+
+  it("surfaces a controls failure inline, not as an rpc_error", async () => {
+    const { subsystem, emitted } = makeSubsystem({
+      host: {
+        listDraftControls: async () => {
+          throw new Error("controls probe failed");
+        },
+      },
+    });
+
+    await subsystem.handleProviderControlsListRequest({
+      type: "provider.controls.list.request",
+      requestId: "c2",
+      draftConfig: { provider: "codex", cwd: "/tmp/project" },
+    });
+
+    expect(findByType(emitted, "rpc_error")).toBeUndefined();
+    expect(findByType(emitted, "provider.controls.list.response")?.payload.error).toBe(
+      "controls probe failed",
+    );
+  });
+
+  it("answers list_provider_features_request from controls, folding legacy featureValues", async () => {
+    const drafts: AgentSessionConfig[] = [];
+    const { subsystem, emitted } = makeSubsystem({
+      host: {
+        listDraftControls: async (config) => {
+          drafts.push(config);
+          return {
+            controls: [{ type: "toggle", key: "fast_mode", label: "Fast" }],
+            options: { fast_mode: true },
+          };
+        },
+      },
+    });
+
+    await subsystem.handleListProviderFeaturesRequest({
+      type: "list_provider_features_request",
+      requestId: "f0",
+      draftConfig: { provider: "claude", cwd: "/tmp/project", featureValues: { fast_mode: true } },
+    });
+
+    expect(drafts[0]?.providerOptions).toEqual({ fast_mode: true });
+    expect(findByType(emitted, "list_provider_features_response")?.payload.features).toEqual([
+      { type: "toggle", id: "fast_mode", label: "Fast", value: true },
+    ]);
+  });
+
   it("surfaces a feature-list failure inline, not as an rpc_error", async () => {
     const { subsystem, emitted } = makeSubsystem({
       host: {
-        listDraftFeatures: async () => {
+        listDraftControls: async () => {
           throw new Error("feature probe failed");
         },
       },
@@ -379,7 +469,7 @@ it("announces shared content without retransmitting models or hashing discovery
         },
         supportsProviderSnapshotReferences: () => references,
         listProviderAvailability: async () => [],
-        listDraftFeatures: async () => [],
+        listDraftControls: async () => ({ controls: [], options: {} }),
       },
     });
   const emitted: SessionOutboundMessage[] = [];
diff --git a/packages/server/src/server/session/provider/provider-catalog-session.ts b/packages/server/src/server/session/provider/provider-catalog-session.ts
index af04199bca..ee9560f812 100644
--- a/packages/server/src/server/session/provider/provider-catalog-session.ts
+++ b/packages/server/src/server/session/provider/provider-catalog-session.ts
@@ -13,12 +13,15 @@ import {
 } from "../../agent/provider-snapshot-manager.js";
 import {
   filterSelectableAgentModels,
-  type AgentFeature,
+  type AgentOptionControl,
   type AgentProvider,
   type AgentSessionConfig,
   type ProviderSnapshotEntry,
 } from "../../agent/agent-sdk-types.js";
 import type { ProviderAvailability } from "../../agent/agent-manager.js";
+import { featuresFromControls } from "@getpaseo/protocol/option-controls";
+import { foldFeatureValues } from "../../agent/option-controls.js";
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { expandTilde } from "../../../utils/path.js";
 
 // COMPAT(customModeIcons): the only mode icons known to clients before v0.1.84. Any
@@ -49,7 +52,9 @@ export interface ProviderCatalogSessionHost {
   supportsProviderSnapshotReferences(): boolean;
   publishSnapshot(project: () => SessionOutboundMessage | null): void;
   listProviderAvailability(): Promise<ProviderAvailability[]>;
-  listDraftFeatures(config: AgentSessionConfig): Promise<AgentFeature[]>;
+  listDraftControls(
+    config: AgentSessionConfig,
+  ): Promise<{ controls: AgentOptionControl[]; options: ProviderOptions }>;
 }
 
 export interface ProviderCatalogSessionOptions {
@@ -340,29 +345,59 @@ export class ProviderCatalogSession {
     model?: string;
     thinkingOptionId?: string;
     featureValues?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
   }): AgentSessionConfig {
+    // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01.
+    const { providerOptions } = foldFeatureValues(draftConfig);
     return {
       provider: draftConfig.provider,
       cwd: expandTilde(draftConfig.cwd),
       ...(draftConfig.modeId ? { modeId: draftConfig.modeId } : {}),
       ...(draftConfig.model ? { model: draftConfig.model } : {}),
       ...(draftConfig.thinkingOptionId ? { thinkingOptionId: draftConfig.thinkingOptionId } : {}),
-      ...(draftConfig.featureValues ? { featureValues: draftConfig.featureValues } : {}),
+      ...(providerOptions ? { providerOptions } : {}),
     };
   }
 
+  async handleProviderControlsListRequest(
+    msg: Extract<SessionInboundMessage, { type: "provider.controls.list.request" }>,
+  ): Promise<void> {
+    const fetchedAt = new Date().toISOString();
+    const provider = msg.draftConfig.provider;
+    try {
+      const { controls, options } = await this.host.listDraftControls(
+        this.buildDraftAgentSessionConfig(msg.draftConfig),
+      );
+      this.host.emit({
+        type: "provider.controls.list.response",
+        payload: { provider, controls, options, error: null, fetchedAt, requestId: msg.requestId },
+      });
+    } catch (error) {
+      this.logger.error(
+        { err: error, provider, draftConfig: msg.draftConfig },
+        `Failed to list controls for ${provider}`,
+      );
+      this.host.emit({
+        type: "provider.controls.list.response",
+        payload: { provider, error: getErrorMessage(error), fetchedAt, requestId: msg.requestId },
+      });
+    }
+  }
+
+  // COMPAT(featureValues): added in v0.15.0, remove after 2027-05-01. Answered from controls.
   async handleListProviderFeaturesRequest(
     msg: Extract<SessionInboundMessage, { type: "list_provider_features_request" }>,
   ): Promise<void> {
     const fetchedAt = new Date().toISOString();
     try {
-      const sessionConfig = this.buildDraftAgentSessionConfig(msg.draftConfig);
-      const features = await this.host.listDraftFeatures(sessionConfig);
+      const { controls, options } = await this.host.listDraftControls(
+        this.buildDraftAgentSessionConfig(msg.draftConfig),
+      );
       this.host.emit({
         type: "list_provider_features_response",
         payload: {
           provider: msg.draftConfig.provider,
-          features,
+          features: featuresFromControls({ controls, options }),
           error: null,
           fetchedAt,
           requestId: msg.requestId,
diff --git a/packages/server/src/server/session/workspace-base-branch/service.ts b/packages/server/src/server/session/workspace-base-branch/service.ts
new file mode 100644
index 0000000000..ffc8feffb0
--- /dev/null
+++ b/packages/server/src/server/session/workspace-base-branch/service.ts
@@ -0,0 +1,104 @@
+import { resolve } from "node:path";
+import { getCheckoutSnapshotFacts, setCheckoutBaseBranch } from "../../../utils/checkout-git.js";
+import {
+  readPaseoWorktreeMetadata,
+  setPaseoWorktreeBaseRef,
+} from "../../../utils/worktree-metadata.js";
+import type { WorkspaceRegistry } from "../../workspace-registry.js";
+import type { WorkspaceGitService } from "../../workspace-git-service.js";
+
+interface Dependencies {
+  paseoHome: string;
+  worktreesRoot?: string;
+  workspaceRegistry: WorkspaceRegistry;
+  workspaceGitService: WorkspaceGitService;
+}
+
+export function createWorkspaceBaseBranchService(deps: Dependencies) {
+  const queues = new Map<string, Promise<void>>();
+
+  async function withCheckoutLock<T>(root: string, operation: () => Promise<T>): Promise<T> {
+    root = resolve(root);
+    const previous = queues.get(root);
+    let release!: () => void;
+    const queued = new Promise<void>((done) => {
+      release = done;
+    });
+    queues.set(root, queued);
+    await previous;
+
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (queues.get(root) === queued) queues.delete(root);
+    }
+  }
+
+  async function setBaseBranch(input: { workspaceId: string; baseRef: string }): Promise<string> {
+    const workspace = await deps.workspaceRegistry.get(input.workspaceId);
+    if (!workspace || workspace.archivedAt) throw new Error("Workspace is unavailable");
+    const facts = await getCheckoutSnapshotFacts(workspace.cwd, {
+      paseoHome: deps.paseoHome,
+      worktreesRoot: deps.worktreesRoot,
+    });
+    if (!facts.isGit) throw new Error("Workspace is not a Git checkout");
+    if (!facts.paseoWorktree.isPaseoOwnedWorktree)
+      throw new Error("Workspace is not a Paseo worktree");
+    const root = resolve(facts.worktreeRoot);
+    return withCheckoutLock(root, async () => {
+      const current = await deps.workspaceRegistry.get(input.workspaceId);
+      if (!current || current.archivedAt) throw new Error("Workspace is unavailable");
+      const records = await deps.workspaceRegistry.listActive();
+      const matching = records.filter(
+        (record) =>
+          record.workspaceId === input.workspaceId ||
+          resolve(record.worktreeRoot ?? record.cwd) === root,
+      );
+      await deps.workspaceGitService.getSnapshot(root);
+      const metadata = await readPaseoWorktreeMetadata(root);
+      const baseRef = await setCheckoutBaseBranch({
+        cwd: root,
+        baseRef: input.baseRef,
+        context: { paseoHome: deps.paseoHome, worktreesRoot: deps.worktreesRoot },
+      });
+      const updatedAt = new Date().toISOString();
+      try {
+        for (const record of matching) {
+          await deps.workspaceRegistry.update(record.workspaceId, (latest) => ({
+            ...latest,
+            baseBranch: baseRef,
+            updatedAt,
+          }));
+        }
+      } catch (error) {
+        if (metadata)
+          await setPaseoWorktreeBaseRef({
+            worktreeRoot: root,
+            baseRef: metadata.baseRef ?? metadata.baseRefName,
+          });
+        for (const record of matching) {
+          await deps.workspaceRegistry.update(record.workspaceId, (latest) => ({
+            ...latest,
+            baseBranch: record.baseBranch,
+            updatedAt: record.updatedAt,
+          }));
+        }
+        throw error;
+      }
+      for (const cwd of new Set(matching.map((record) => record.cwd))) {
+        await deps.workspaceGitService.getSnapshot(cwd, {
+          force: true,
+          afterInFlight: true,
+          includeForge: false,
+          reason: "base-branch-change",
+        });
+      }
+      return baseRef;
+    });
+  }
+
+  return { setBaseBranch, withCheckoutLock };
+}
+
+export type WorkspaceBaseBranchService = ReturnType<typeof createWorkspaceBaseBranchService>;
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
index c93e535709..706f199114 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
@@ -5,6 +5,11 @@ import { mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { afterEach, beforeEach, expect, test } from "vitest";
 
 import { getCheckoutStatus } from "../../../utils/checkout-git.js";
+import {
+  setPaseoWorktreeBaseRef,
+  writePaseoWorktreeMetadata,
+} from "../../../utils/worktree-metadata.js";
+import { createWorkspaceBaseBranchService } from "../workspace-base-branch/service.js";
 import { createTestLogger } from "../../../test-utils/test-logger.js";
 import {
   createNoGitWorkspaceRuntimeSnapshot,
@@ -125,6 +130,62 @@ afterEach(() => {
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
+test("a workspace created during a base change records the new base", async () => {
+  const cwd = path.join(tmpDir, "worktree");
+  mkdirSync(path.join(cwd, ".git"), { recursive: true });
+  await writePaseoWorktreeMetadata(cwd, { baseRefName: "main", baseRef: "refs/heads/main" });
+  const git = createNoopWorkspaceGitService({
+    getCheckout: async () => ({
+      cwd,
+      isGit: true,
+      currentBranch: "feature",
+      remoteUrl: null,
+      worktreeRoot: cwd,
+      isPaseoOwnedWorktree: true,
+      mainRepoRoot: cwd,
+    }),
+  });
+  const bases = createWorkspaceBaseBranchService({
+    paseoHome: tmpDir,
+    workspaceRegistry,
+    workspaceGitService: git,
+  });
+  let release!: () => void;
+  let entered!: () => void;
+  let attempted!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const locked = new Promise<void>((resolve) => {
+    entered = resolve;
+  });
+  const waiting = new Promise<void>((resolve) => {
+    attempted = resolve;
+  });
+  const change = bases.withCheckoutLock(cwd, async () => {
+    entered();
+    await gate;
+    await setPaseoWorktreeBaseRef({ worktreeRoot: cwd, baseRef: "refs/heads/release" });
+  });
+  await locked;
+  const creator = createWorkspaceProvisioningService({
+    workspaceRegistry,
+    projectRegistry,
+    workspaceGitService: git,
+    isDirectory,
+    logger,
+    withCheckoutLock: (root, operation) => {
+      attempted();
+      return bases.withCheckoutLock(root, operation);
+    },
+  });
+  const created = creator.createWorkspaceForDirectory(cwd);
+  await waiting;
+  release();
+  await change;
+  expect((await created).baseBranch).toBe("refs/heads/release");
+});
+
 test("fresh git repo creates a workspace at the canonical worktree root", async () => {
   const repo = path.join(tmpDir, "repo");
   gitRoots.add(repo);
@@ -132,7 +193,7 @@ test("fresh git repo creates a workspace at the canonical worktree root", async
   const workspace = await provisioning.findOrCreateWorkspaceForDirectory(repo);
 
   expect(workspace.cwd).toBe(repo);
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
   expect(await projectRegistry.list()).toHaveLength(1);
 });
 
@@ -144,6 +205,82 @@ test("fresh non-git directory creates a directory workspace at the exact path",
   expect(workspace.cwd).toBe(dir);
 });
 
+test("workspace parentage survives reload and parent archive without changing placement", async () => {
+  const cwd = path.join(tmpDir, "plain");
+  const parent = await provisioning.createWorkspaceForDirectory(cwd);
+  const child = await provisioning.createWorkspaceForDirectory(cwd, null, undefined, {
+    callerWorkspaceId: parent.workspaceId,
+    background: false,
+  });
+  const grandchild = await provisioning.createWorkspaceForDirectory(
+    path.join(tmpDir, "other"),
+    null,
+    undefined,
+    {
+      callerWorkspaceId: child.workspaceId,
+    },
+  );
+  expect(parent.parentWorkspaceId).toBeUndefined();
+  expect(child).toMatchObject({ parentWorkspaceId: parent.workspaceId, cwd });
+  expect(grandchild).toMatchObject({ parentWorkspaceId: child.workspaceId });
+  await workspaceRegistry.archive(parent.workspaceId, ARCHIVED_AT);
+  const reloaded = new FileBackedWorkspaceRegistry(
+    path.join(tmpDir, "projects", "workspaces.json"),
+    logger,
+  );
+  await reloaded.initialize();
+  expect(await reloaded.get(child.workspaceId)).toMatchObject({
+    parentWorkspaceId: parent.workspaceId,
+    archivedAt: null,
+  });
+  expect(await reloaded.get(grandchild.workspaceId)).toMatchObject({
+    parentWorkspaceId: child.workspaceId,
+    archivedAt: null,
+  });
+});
+
+test("worktree workspace creation records its caller independently of its source project", async () => {
+  const sourceCwd = path.join(tmpDir, "repo");
+  gitRoots.add(sourceCwd);
+  const parent = await provisioning.createWorkspaceForDirectory(path.join(tmpDir, "other"));
+  const child = await provisioning.createWorkspaceForWorktree({
+    sourceCwd,
+    repoRoot: sourceCwd,
+    cwd: path.join(tmpDir, "worktree"),
+    worktreeRoot: path.join(tmpDir, "worktree"),
+    branch: "child",
+    baseBranch: "main",
+    title: null,
+    callerWorkspaceId: parent.workspaceId,
+  });
+  expect(child.parentWorkspaceId).toBe(parent.workspaceId);
+  expect(child.projectId).not.toBe(parent.projectId);
+  expect(await workspaceRegistry.get(child.workspaceId)).toMatchObject({
+    parentWorkspaceId: parent.workspaceId,
+  });
+});
+
+test("workspace creation rejects an unknown caller even with explicit visibility", async () => {
+  await expect(
+    provisioning.createWorkspaceForDirectory(path.join(tmpDir, "plain"), null, undefined, {
+      callerWorkspaceId: "missing",
+      background: false,
+    }),
+  ).rejects.toThrow("Caller workspace missing not found");
+});
+
+test("workspace creation cannot overwrite its caller with a self relationship", async () => {
+  const cwd = path.join(tmpDir, "plain");
+  const parent = await provisioning.createWorkspaceForDirectory(cwd);
+  await expect(
+    provisioning.createWorkspaceForDirectory(cwd, null, undefined, {
+      callerWorkspaceId: parent.workspaceId,
+      workspaceId: parent.workspaceId,
+    }),
+  ).rejects.toThrow("A workspace cannot be its own parent");
+  expect(await workspaceRegistry.get(parent.workspaceId)).toEqual(parent);
+});
+
 test("background workspace creation preserves hooks, inheritance and durable visibility", async () => {
   const dir = path.join(tmpDir, "plain");
   const events: string[] = [];
@@ -192,7 +329,7 @@ test("re-opening an active workspace by exact path returns the same record witho
   const second = await provisioning.findOrCreateWorkspaceForDirectory(repo);
 
   expect(second.workspaceId).toBe(first.workspaceId);
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
 });
 
 test("re-opening Windows-equivalent workspace cwd spellings reuses the active and archived record", async () => {
@@ -202,12 +339,12 @@ test("re-opening Windows-equivalent workspace cwd spellings reuses the active an
 
   const active = await provisioning.findOrCreateWorkspaceForDirectory(cwd);
   expect(active.workspaceId).toBe(created.workspaceId);
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
 
   await workspaceRegistry.archive(created.workspaceId, ARCHIVED_AT);
   const reopened = await provisioning.findOrCreateWorkspaceForDirectory(cwd);
   expect(reopened).toMatchObject({ workspaceId: created.workspaceId, archivedAt: null });
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
 });
 
 test("re-opening refreshes mutable checkout metadata without renaming the workspace", async () => {
@@ -361,14 +498,15 @@ test("uses one workspace snapshot when reopening an archived workspace", async (
   const created = await provisioning.findOrCreateWorkspaceForDirectory(repo);
   await workspaceRegistry.archive(created.workspaceId, ARCHIVED_AT);
 
-  const archived = (await workspaceRegistry.list()).filter(
+  const archived = (await workspaceRegistry.listAll()).filter(
     (workspace) => workspace.workspaceId === created.workspaceId,
   );
   let reads = 0;
   const snapshotRegistry: WorkspaceRegistry = {
     initialize: () => workspaceRegistry.initialize(),
     existsOnDisk: () => workspaceRegistry.existsOnDisk(),
-    list: async () => (reads++ === 0 ? archived : []),
+    listAll: async () => (reads++ === 0 ? archived : []),
+    listActive: () => workspaceRegistry.listActive(),
     get: (workspaceId) => workspaceRegistry.get(workspaceId),
     upsert: (workspace) => workspaceRegistry.upsert(workspace),
     archive: (workspaceId, archivedAt) => workspaceRegistry.archive(workspaceId, archivedAt),
@@ -384,7 +522,7 @@ test("uses one workspace snapshot when reopening an archived workspace", async (
   const reopened = await snapshotProvisioning.findOrCreateWorkspaceForDirectory(repo);
 
   expect(reopened).toMatchObject({ workspaceId: created.workspaceId, archivedAt: null });
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
 });
 
 test("reopening an archived workspace refreshes placement without renaming it", async () => {
@@ -540,7 +678,7 @@ test("resolveOrCreateWorkspaceIdForCreateAgent returns a created worktree's id w
   });
 
   expect(id).toBe("ws-from-worktree");
-  expect(await workspaceRegistry.list()).toHaveLength(0);
+  expect(await workspaceRegistry.listAll()).toHaveLength(0);
 });
 
 test("resolveOrCreateWorkspaceIdForCreateAgent honors an explicitly requested workspace id", async () => {
@@ -552,7 +690,7 @@ test("resolveOrCreateWorkspaceIdForCreateAgent honors an explicitly requested wo
   });
 
   expect(id).toBe("ws-requested");
-  expect(await workspaceRegistry.list()).toHaveLength(0);
+  expect(await workspaceRegistry.listAll()).toHaveLength(0);
 });
 
 test("resolveOrCreateWorkspaceIdForCreateAgent creates a titled workspace when nothing is provided", async () => {
@@ -577,7 +715,7 @@ test("createWorkspaceForDirectory always mints a fresh workspace even when one a
   const second = await provisioning.createWorkspaceForDirectory(repo);
 
   expect(second.workspaceId).not.toBe(first.workspaceId);
-  expect(await workspaceRegistry.list()).toHaveLength(2);
+  expect(await workspaceRegistry.listAll()).toHaveLength(2);
 });
 
 test("directory creation persists the live branch and a trimmed title", async () => {
@@ -677,7 +815,7 @@ test("runInImportWorkspace uses an active requested workspace without creating a
   );
 
   expect(result).toEqual({ value: workspace.workspaceId, createdWorkspace: null });
-  expect(await workspaceRegistry.list()).toEqual([workspace]);
+  expect(await workspaceRegistry.listAll()).toEqual([workspace]);
 });
 
 test("runInImportWorkspace reuses an active workspace for an untargeted import", async () => {
@@ -691,7 +829,7 @@ test("runInImportWorkspace reuses an active workspace for an untargeted import",
   );
 
   expect(result).toEqual({ value: workspace.workspaceId, createdWorkspace: null });
-  expect(await workspaceRegistry.list()).toEqual([workspace]);
+  expect(await workspaceRegistry.listAll()).toEqual([workspace]);
 });
 
 test("runInImportWorkspace unarchives a workspace for an untargeted import", async () => {
@@ -710,7 +848,7 @@ test("runInImportWorkspace unarchives a workspace for an untargeted import", asy
     workspaceId: workspace.workspaceId,
     archivedAt: null,
   });
-  expect(await workspaceRegistry.list()).toHaveLength(1);
+  expect(await workspaceRegistry.listAll()).toHaveLength(1);
 });
 
 test("runInImportWorkspace leaves a reused workspace intact when import fails", async () => {
@@ -725,7 +863,7 @@ test("runInImportWorkspace leaves a reused workspace intact when import fails",
     }),
   ).rejects.toThrow("provider session is unavailable");
 
-  expect(await workspaceRegistry.list()).toEqual([workspace]);
+  expect(await workspaceRegistry.listAll()).toEqual([workspace]);
   expect(await projectRegistry.get(workspace.projectId)).toEqual(project);
 });
 
@@ -823,7 +961,7 @@ test("runInImportWorkspace creates one fresh workspace for an untargeted import"
   );
 
   expect(result.value).toBe(result.createdWorkspace?.workspaceId);
-  expect(await workspaceRegistry.list()).toEqual([result.createdWorkspace]);
+  expect(await workspaceRegistry.listAll()).toEqual([result.createdWorkspace]);
 });
 
 test.each(["missing", "archived"] as const)(
@@ -844,7 +982,7 @@ test.each(["missing", "archived"] as const)(
       }),
     ).rejects.toThrow("provider session is unavailable");
 
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
     expect(await projectRegistry.list()).toEqual(previousProject ? [previousProject] : []);
   },
 );
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
index 08d7b93bf4..28a412e7e5 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
@@ -1,3 +1,4 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import type { PluginLifecycle } from "../../plugins/lifecycle/index.js";
 import { describeHookWorkspace } from "../../plugins/lifecycle/index.js";
 import { basename, resolve } from "node:path";
@@ -20,6 +21,7 @@ import type { CreatePaseoWorktreeWorkflowResult } from "../../worktree-session.j
 import { deriveProjectKey } from "../../project-key.js";
 import { areEquivalentPaths, createRealpathAwarePathMatcher } from "../../../utils/path.js";
 import type { UntrustedWorkspaceSource } from "../../workspace-automation-gate.js";
+import { readPaseoWorktreeMetadata } from "../../../utils/worktree-metadata.js";
 
 export interface ResolveOrCreateWorkspaceIdInput {
   createdWorktree: CreatePaseoWorktreeWorkflowResult | null;
@@ -50,6 +52,7 @@ export interface CreateWorktreeWorkspaceInput {
   branch: string | null;
   baseBranch: string | null;
   title: string | null;
+  metadata?: Record<string, JsonValue>;
   expectsInitialAgent?: boolean;
   untrustedSource?: UntrustedWorkspaceSource;
   background?: boolean;
@@ -70,6 +73,7 @@ export interface WorkspaceProvisioningService {
     context?: {
       expectsInitialAgent?: boolean;
       workspaceId?: string;
+      metadata?: Record<string, JsonValue>;
       background?: boolean;
       callerWorkspaceId?: string;
     },
@@ -107,6 +111,7 @@ export function createWorkspaceProvisioningService(deps: {
   isDirectory: (path: string) => Promise<boolean>;
   logger: Logger;
   lifecycle?: PluginLifecycle;
+  withCheckoutLock?: <T>(root: string, operation: () => Promise<T>) => Promise<T>;
 }): WorkspaceProvisioningService {
   const { serverId, workspaceRegistry, projectRegistry, workspaceGitService, logger } = deps;
 
@@ -149,7 +154,8 @@ export function createWorkspaceProvisioningService(deps: {
 
     const [projectsBeforeImport, workspacesBeforeImport] = await Promise.all([
       projectRegistry.list(),
-      workspaceRegistry.list(),
+      // Import rollback must distinguish restored records from newly allocated workspaces.
+      workspaceRegistry.listAll(),
     ]);
     const workspace = await findOrCreateWorkspaceForDirectory(input.cwd);
     const createdWorkspace = workspacesBeforeImport.some(
@@ -179,7 +185,7 @@ export function createWorkspaceProvisioningService(deps: {
   ): Promise<void> {
     try {
       await workspaceRegistry.remove(workspace.workspaceId);
-      const projectHasActiveWorkspace = (await workspaceRegistry.list()).some(
+      const projectHasActiveWorkspace = (await workspaceRegistry.listActive()).some(
         (candidate) => candidate.projectId === workspace.projectId && !candidate.archivedAt,
       );
       if (projectHasActiveWorkspace) {
@@ -224,15 +230,21 @@ export function createWorkspaceProvisioningService(deps: {
     return project;
   }
 
-  async function resolveBackground(input?: {
+  async function resolveCreationMetadata(input?: {
+    workspaceId?: string;
     background?: boolean;
     callerWorkspaceId?: string;
-  }): Promise<boolean> {
-    if (input?.background !== undefined) return input.background;
-    if (!input?.callerWorkspaceId) return false;
+  }): Promise<{ background: boolean; parentWorkspaceId?: string }> {
+    if (!input?.callerWorkspaceId) return { background: input?.background ?? false };
+    if (input.workspaceId === input.callerWorkspaceId) {
+      throw new Error("A workspace cannot be its own parent");
+    }
     const callerWorkspace = await workspaceRegistry.get(input.callerWorkspaceId);
     if (!callerWorkspace) throw new Error(`Caller workspace ${input.callerWorkspaceId} not found`);
-    return callerWorkspace.background;
+    return {
+      background: input.background ?? callerWorkspace.background,
+      parentWorkspaceId: callerWorkspace.workspaceId,
+    };
   }
 
   async function createWorkspaceForDirectory(
@@ -242,6 +254,7 @@ export function createWorkspaceProvisioningService(deps: {
     context?: {
       expectsInitialAgent?: boolean;
       workspaceId?: string;
+      metadata?: Record<string, JsonValue>;
       background?: boolean;
       callerWorkspaceId?: string;
     },
@@ -252,21 +265,32 @@ export function createWorkspaceProvisioningService(deps: {
       ? await refreshProjectKind(await requireActiveProject(projectId), normalizedCwd, checkout)
       : // COMPAT(workspaceCreateMissingProjectId): added in v0.1.107, remove after 2027-01-15.
         await findOrCreateProjectForDirectory(normalizedCwd);
-    const timestamp = new Date().toISOString();
-    const workspace = createPersistedWorkspaceRecord({
-      workspaceId: context?.workspaceId ?? generateWorkspaceId(),
-      projectId: project.projectId,
-      ...initialWorkspacePlacement({ source: "checkout", cwd: normalizedCwd, checkout }),
-      title: title?.trim() || null,
-      createdAt: timestamp,
-      updatedAt: timestamp,
-      background: await resolveBackground(context),
-    });
-    await workspaceRegistry.upsert(workspace, {
-      expectsInitialAgent: context?.expectsInitialAgent,
-    });
-    emitWorkspaceCreated(workspace);
-    return workspace;
+    const create = async () => {
+      const baseMetadata =
+        checkout.isGit && checkout.isPaseoOwnedWorktree
+          ? await readPaseoWorktreeMetadata(checkout.worktreeRoot ?? normalizedCwd)
+          : null;
+      const timestamp = new Date().toISOString();
+      const workspace = createPersistedWorkspaceRecord({
+        workspaceId: context?.workspaceId ?? generateWorkspaceId(),
+        projectId: project.projectId,
+        ...initialWorkspacePlacement({ source: "checkout", cwd: normalizedCwd, checkout }),
+        baseBranch: baseMetadata?.baseRef ?? baseMetadata?.baseRefName ?? null,
+        title: title?.trim() || null,
+        metadata: context?.metadata,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        ...(await resolveCreationMetadata(context)),
+      });
+      await workspaceRegistry.upsert(workspace, {
+        expectsInitialAgent: context?.expectsInitialAgent,
+      });
+      emitWorkspaceCreated(workspace);
+      return workspace;
+    };
+    return deps.withCheckoutLock && checkout.isGit && checkout.isPaseoOwnedWorktree
+      ? deps.withCheckoutLock(checkout.worktreeRoot ?? normalizedCwd, create)
+      : create();
   }
 
   async function createWorkspaceForWorktree(
@@ -294,10 +318,11 @@ export function createWorkspaceProvisioningService(deps: {
         mainRepoRoot: repoRoot,
       }),
       title: input.title,
+      metadata: input.metadata,
       createdAt: timestamp,
       updatedAt: timestamp,
       ...(input.untrustedSource ? { untrustedSource: input.untrustedSource } : {}),
-      background: await resolveBackground(input),
+      ...(await resolveCreationMetadata(input)),
     });
     await workspaceRegistry.upsert(workspace, {
       expectsInitialAgent: input.expectsInitialAgent,
@@ -321,7 +346,7 @@ export function createWorkspaceProvisioningService(deps: {
       return refreshProjectKind(await requireActiveProject(input.projectId));
     }
 
-    const workspaces = await workspaceRegistry.list();
+    const workspaces = await workspaceRegistry.listActive();
     const sourceWorkspace =
       workspaces.find(
         (workspace) => !workspace.archivedAt && areEquivalentPaths(workspace.cwd, input.sourceCwd),
@@ -356,7 +381,8 @@ export function createWorkspaceProvisioningService(deps: {
   async function findOrCreateWorkspaceForDirectory(cwd: string): Promise<PersistedWorkspaceRecord> {
     const normalizedCwd = resolve(cwd);
     // Path-based discovery selects public work; explicit-ID recovery bypasses this selector.
-    const workspaces = (await workspaceRegistry.list())
+    // Opening a directory explicitly recovers an archived workspace at that path.
+    const workspaces = (await workspaceRegistry.listAll())
       .filter(
         (workspace) => !workspace.background && areEquivalentPaths(workspace.cwd, normalizedCwd),
       )
diff --git a/packages/server/src/server/snapshot-mutation-ownership.test.ts b/packages/server/src/server/snapshot-mutation-ownership.test.ts
index 2917d0fec9..3c942d0c9e 100644
--- a/packages/server/src/server/snapshot-mutation-ownership.test.ts
+++ b/packages/server/src/server/snapshot-mutation-ownership.test.ts
@@ -1,3 +1,4 @@
+import { DiffSubscriptions } from "./diff/index.js";
 import { createWorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import { createAgentMessageDeliveryStub } from "./test-utils/session-stubs.js";
 import {
@@ -49,13 +50,13 @@ describe("snapshot mutation ownership boundary", () => {
 
       const applySnapshotSpy = vi.spyOn(daemonHandle.daemon.agentStorage, "applySnapshot");
 
-      await daemonHandle.daemon.agentManager.setAgentModel(snapshot.id, "gpt-5.4");
+      await daemonHandle.daemon.agentManager.setAgentModel(snapshot.id, "gpt-5.4-mini");
       await daemonHandle.daemon.agentManager.flush();
 
       expect(applySnapshotSpy.mock.calls.length).toBeGreaterThanOrEqual(1);
 
       const persisted = await daemonHandle.daemon.agentStorage.get(snapshot.id);
-      expect(persisted?.config?.model).toBe("gpt-5.4");
+      expect(persisted?.config?.model).toBe("gpt-5.4-mini");
     } finally {
       rmSync(cwd, { recursive: true, force: true });
       await daemonHandle.close();
@@ -105,6 +106,13 @@ describe("snapshot mutation ownership boundary", () => {
 
     const session = asInternals<SessionInternals>(
       new Session({
+        checkoutDiffManager: createStub<SessionOptions["checkoutDiffManager"]>({
+          streams: new DiffSubscriptions({
+            async requestWorkingTreeWatch() {
+              throw new Error("Unexpected diff observation");
+            },
+          }),
+        }),
         workspaceRuntimeStore: createWorkspaceRuntimeStore(),
         messageReceipts: createMessageReceiptsStub(),
         agentMessages: createAgentMessageDeliveryStub(),
diff --git a/packages/server/src/server/terminal-activity-route.test.ts b/packages/server/src/server/terminal-activity-route.test.ts
index afc97d77e8..e047c56ab9 100644
--- a/packages/server/src/server/terminal-activity-route.test.ts
+++ b/packages/server/src/server/terminal-activity-route.test.ts
@@ -95,7 +95,13 @@ it("accepts terminalId and token reports through the route into the tracker", as
     command: process.execPath,
     args: [
       "-e",
-      `require("node:fs").writeFileSync(${JSON.stringify(envPath)}, JSON.stringify({ terminalId: process.env.PASEO_TERMINAL_ID, token: process.env.PASEO_ACTIVITY_TOKEN, url: process.env.PASEO_TERMINAL_ACTIVITY_URL })); setInterval(() => {}, 1000);`,
+      `
+        const fs = require("node:fs");
+        const envPath = ${JSON.stringify(envPath)};
+        fs.writeFileSync(envPath + ".tmp", JSON.stringify({ terminalId: process.env.PASEO_TERMINAL_ID, token: process.env.PASEO_ACTIVITY_TOKEN, url: process.env.PASEO_TERMINAL_ACTIVITY_URL }));
+        fs.renameSync(envPath + ".tmp", envPath);
+        setInterval(() => {}, 1000);
+      `,
     ],
   });
   await waitForCondition(() => existsSync(envPath), 10000);
diff --git a/packages/server/src/server/test-fixtures/reconciliation-registries.ts b/packages/server/src/server/test-fixtures/reconciliation-registries.ts
index 2d020ec23f..b6490e8f88 100644
--- a/packages/server/src/server/test-fixtures/reconciliation-registries.ts
+++ b/packages/server/src/server/test-fixtures/reconciliation-registries.ts
@@ -64,7 +64,8 @@ export function createTestRegistries() {
   const workspaceRegistry: WorkspaceRegistry = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => Array.from(workspaces.values()),
+    listAll: async () => Array.from(workspaces.values()),
+    listActive: async () => Array.from(workspaces.values()).filter((w) => !w.archivedAt),
     get: async (id: string) => workspaces.get(id) ?? null,
     update: async (id, updater) => {
       const existing = workspaces.get(id);
diff --git a/packages/server/src/server/test-utils/fake-agent-client.ts b/packages/server/src/server/test-utils/fake-agent-client.ts
index 4304a767e1..a7a237b9de 100644
--- a/packages/server/src/server/test-utils/fake-agent-client.ts
+++ b/packages/server/src/server/test-utils/fake-agent-client.ts
@@ -1,3 +1,4 @@
+import type { ProviderOptions } from "@getpaseo/protocol/agent-types";
 import { randomUUID } from "node:crypto";
 import { readFileSync, writeFileSync, rmSync, readdirSync } from "node:fs";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
@@ -6,7 +7,7 @@ import path from "node:path";
 import type {
   AgentCapabilityFlags,
   AgentClient,
-  AgentFeature,
+  AgentOptionControl,
   AgentLaunchContext,
   AgentMode,
   AgentModelDefinition,
@@ -15,6 +16,7 @@ import type {
   AgentRunOptions,
   AgentRunResult,
   AgentSession,
+  AgentSelectOption,
   AgentSessionConfig,
   AgentStreamEvent,
   AgentSlashCommand,
@@ -37,6 +39,26 @@ const TEST_CAPABILITIES: AgentCapabilityFlags = {
 };
 
 const TEST_FEATURE_ID = "test_feature";
+const TEST_THINKING_OPTIONS: AgentSelectOption[] = [
+  { id: "low", label: "Low", isDefault: true },
+  { id: "high", label: "High" },
+];
+
+const TEST_MODELS: Record<string, Array<{ id: string; label: string }>> = {
+  claude: [
+    { id: "haiku", label: "Haiku" },
+    { id: "sonnet", label: "Sonnet" },
+  ],
+  codex: [
+    { id: "gpt-5.4-mini", label: "gpt-5.4-mini" },
+    { id: "gpt-5.4", label: "gpt-5.4" },
+  ],
+  opencode: [
+    { id: "test-model", label: "Test Model" },
+    { id: "test-model-alt", label: "Test Model Alt" },
+  ],
+};
+
 const TEST_MODES: AgentMode[] = [
   { id: "bypassPermissions", label: "Bypass", description: "No permissions" },
   { id: "default", label: "Default", description: "Ask for permissions" },
@@ -379,14 +401,13 @@ class FakeAgentSession implements AgentSession {
     return this.providerName;
   }
 
-  get features(): AgentFeature[] {
+  get controls(): AgentOptionControl[] {
     return [
       {
         type: "toggle",
-        id: TEST_FEATURE_ID,
+        key: TEST_FEATURE_ID,
         label: "Test feature",
         description: "Deterministic provider feature used by MCP integration tests.",
-        value: this.config.featureValues?.[TEST_FEATURE_ID] === true,
       },
     ];
   }
@@ -873,11 +894,8 @@ class FakeAgentSession implements AgentSession {
     this.config.modeId = modeId;
   }
 
-  async setFeature(featureId: string, value: unknown): Promise<void> {
-    this.config.featureValues = {
-      ...this.config.featureValues,
-      [featureId]: value,
-    };
+  async applyOptions(options: ProviderOptions): Promise<void> {
+    this.config.providerOptions = { ...this.config.providerOptions, ...options };
   }
 
   getPendingPermissions(): AgentPermissionRequest[] {
@@ -1283,30 +1301,18 @@ class FakeAgentClient implements AgentClient {
   async fetchCatalog(
     _options: FetchCatalogOptions,
   ): Promise<{ models: AgentModelDefinition[]; modes: AgentMode[] }> {
-    if (this.provider === "claude") {
-      return {
-        models: [
-          { provider: this.provider, id: "haiku", label: "Haiku", isDefault: true },
-          { provider: this.provider, id: "sonnet", label: "Sonnet", isDefault: false },
-        ],
-        modes: TEST_MODES,
-      };
-    }
-    if (this.provider === "codex") {
-      return {
-        models: [
-          {
-            provider: this.provider,
-            id: "gpt-5.4-mini",
-            label: "gpt-5.4-mini",
-            isDefault: true,
-          },
-        ],
-        modes: TEST_MODES,
-      };
-    }
+    // Every provider lists two models that each list thinking options, so the live model and
+    // thinking switches have listed values to switch between.
+    const listed = TEST_MODELS[this.provider] ?? TEST_MODELS.opencode;
     return {
-      models: [{ provider: this.provider, id: "test-model", label: "Test Model", isDefault: true }],
+      models: listed.map((model, index) => ({
+        provider: this.provider,
+        id: model.id,
+        label: model.label,
+        isDefault: index === 0,
+        thinkingOptions: TEST_THINKING_OPTIONS,
+        defaultThinkingOptionId: "low",
+      })),
       modes: TEST_MODES,
     };
   }
diff --git a/packages/server/src/server/test-utils/session-stubs.ts b/packages/server/src/server/test-utils/session-stubs.ts
index 922f673935..0c156ae5d9 100644
--- a/packages/server/src/server/test-utils/session-stubs.ts
+++ b/packages/server/src/server/test-utils/session-stubs.ts
@@ -37,6 +37,8 @@ export function asAgentManager(stub: {
   return createStub<SessionOptions["agentManager"]>({
     listProviderSubagentActivity: () => [],
     getRetiredInternalAgent: () => null,
+    effectiveOptionsFor: (_provider: string, own?: Record<string, unknown>) => own ?? {},
+    getAgentBackgroundWorkSummary: () => undefined,
     ...stub,
   });
 }
@@ -45,6 +47,19 @@ export function asAgentStorage(stub: {
   [K in keyof SessionOptions["agentStorage"]]?: unknown;
 }): SessionOptions["agentStorage"] {
   return createStub<SessionOptions["agentStorage"]>({
+    listAll: async () => [],
+    listActive: async function (options) {
+      return (await this.listAll()).filter(
+        (record) => options?.includeArchived || !record.archivedAt,
+      );
+    },
+    listByWorkspaces: async function (ids, options) {
+      const selected = new Set(ids);
+      return (await this.listActive(options)).filter((record) =>
+        selected.has(record.workspaceId ?? ""),
+      );
+    },
+    lastUserMessageAtByWorkspace: async () => new Map<string, string>(),
     listByProviderSession: async () => [],
     listByWorkspace: async () => [],
     ...stub,
@@ -223,7 +238,7 @@ export function createProviderSnapshotManagerStub(): {
   const listModes = vi.fn<ProviderSnapshotManager["listModes"]>(async () => []);
   const resolveCreateConfig = vi.fn<ProviderSnapshotManager["resolveCreateConfig"]>(async () => ({
     modeId: undefined,
-    featureValues: undefined,
+    providerOptions: undefined,
   }));
   const resolveDefaultModel = vi.fn<ProviderSnapshotManager["resolveDefaultModel"]>(
     async () => undefined,
diff --git a/packages/server/src/server/utils/diff-highlighter.ts b/packages/server/src/server/utils/diff-highlighter.ts
index e3a0460322..6404ce2381 100644
--- a/packages/server/src/server/utils/diff-highlighter.ts
+++ b/packages/server/src/server/utils/diff-highlighter.ts
@@ -70,11 +70,6 @@ function extractPathFromMetadata(lines: string[], prefix: "--- " | "+++ "): stri
 
 function extractPathFromDiffHeader(lines: string[]): string {
   const firstLine = lines[0] ?? "";
-  const prefixedPathMatch = firstLine.match(/^a\/(.+) b\/(.+)$/);
-  if (prefixedPathMatch) {
-    return prefixedPathMatch[2];
-  }
-
   const quotedPathMatch =
     firstLine.match(/^("(?:\\.|[^"\\])*") (.+)$/) ?? firstLine.match(/^(.+) ("(?:\\.|[^"\\])*")$/);
   if (quotedPathMatch) {
@@ -86,10 +81,21 @@ function extractPathFromDiffHeader(lines: string[]): string {
     return newPath;
   }
 
-  const metadataPath =
-    extractPathFromMetadata(lines, "+++ ") ?? extractPathFromMetadata(lines, "--- ");
-  if (metadataPath) {
-    return metadataPath;
+  // The ---/+++ records are unambiguous even when a path contains " b/".
+  const oldMetadata = extractPathFromMetadata(lines, "--- ");
+  const newMetadata = extractPathFromMetadata(lines, "+++ ");
+  const metadata = newMetadata ?? oldMetadata;
+  if (metadata) {
+    const prefixed =
+      (oldMetadata !== null &&
+        newMetadata !== null &&
+        usesDiffPathPrefixes(oldMetadata, newMetadata)) ||
+      firstLine === `a/${metadata.slice(2)} b/${metadata.slice(2)}`;
+    return prefixed ? metadata.slice(2) : metadata;
+  }
+  const prefixedPathMatch = firstLine.match(/^a\/(.+) b\/(.+)$/);
+  if (prefixedPathMatch) {
+    return prefixedPathMatch[2];
   }
 
   const pathMatch = firstLine.match(/^(\S+)\s+(\S+)$/);
@@ -462,7 +468,8 @@ function applyTokensToHunks(
         newLineNum++;
       }
 
-      return tokens ? { ...line, tokens } : line;
+      const matchingTokens = tokensForPatchLine(tokens, line.content);
+      return matchingTokens ? { ...line, tokens: matchingTokens } : line;
     });
 
     return { ...hunk, lines: highlightedLines };
@@ -471,6 +478,25 @@ function applyTokensToHunks(
   return { ...file, hunks: highlightedHunks };
 }
 
+function tokensForPatchLine(
+  tokens: HighlightToken[] | undefined,
+  content: string,
+): HighlightToken[] | undefined {
+  if (!tokens) return undefined;
+  const source = tokens.map((token) => token.text).join("");
+  if (source === content) return tokens;
+  // Git can normalize a CRLF worktree while source highlighting retains its CR.
+  if (source !== `${content}\r`) return undefined;
+  const aligned: HighlightToken[] = [];
+  let remaining = content.length;
+  for (const token of tokens) {
+    const text = token.text.slice(0, remaining);
+    if (text) aligned.push({ text, style: token.style });
+    remaining -= text.length;
+  }
+  return aligned;
+}
+
 /**
  * Parse and highlight a complete diff, using actual file content when available.
  */
diff --git a/packages/server/src/server/web-ui.test.ts b/packages/server/src/server/web-ui.test.ts
index 2e1f6ba663..b1aa04a8d2 100644
--- a/packages/server/src/server/web-ui.test.ts
+++ b/packages/server/src/server/web-ui.test.ts
@@ -187,6 +187,33 @@ describe("daemon web UI route module", () => {
     expect(res.body).toContain("app");
   });
 
+  test.each([
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-protected-resource/mcp/agents",
+    "/.well-known/oauth-authorization-server",
+    "/.well-known/openid-configuration",
+  ])("returns a JSON 404 instead of the SPA for missing %s", async (requestPath) => {
+    const app = createApp({ enabled: true, distDir, publicDir });
+
+    const res = await request(app, "GET", requestPath);
+
+    expect(res.status).toBe(404);
+    expect(res.headers["content-type"]).toBe("application/json; charset=utf-8");
+    expect(JSON.parse(res.body)).toEqual({ error: "Not found" });
+  });
+
+  test("serves well-known files that exist in the dist directory", async () => {
+    await mkdir(path.join(distDir, ".well-known"), { recursive: true });
+    await writeFile(path.join(distDir, ".well-known", "security.json"), '{"ok":true}');
+    const app = createApp({ enabled: true, distDir, publicDir });
+
+    const res = await request(app, "GET", "/.well-known/security.json");
+
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toBe("application/json; charset=utf-8");
+    expect(res.body).toBe('{"ok":true}');
+  });
+
   test("serves static assets", async () => {
     const app = createApp({ enabled: true, distDir, publicDir });
 
diff --git a/packages/server/src/server/web-ui.ts b/packages/server/src/server/web-ui.ts
index b59896c159..c00611a4e9 100644
--- a/packages/server/src/server/web-ui.ts
+++ b/packages/server/src/server/web-ui.ts
@@ -15,6 +15,13 @@ function isExcludedPath(requestPath: string): boolean {
   return EXCLUDED_PATHS.has(requestPath);
 }
 
+// RFC 8615 well-known URIs are machine-read metadata. Clients such as MCP OAuth
+// discovery (RFC 9728, RFC 8414) need a 404 for documents the daemon does not
+// serve; the SPA's index.html with a 200 reads as malformed metadata.
+function isWellKnownPath(requestPath: string): boolean {
+  return requestPath === "/.well-known" || requestPath.startsWith("/.well-known/");
+}
+
 const CONTENT_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -71,7 +78,14 @@ interface ResolvedTarget {
   isIndexHtml: boolean;
 }
 
-function resolveTargetFile(distDir: string, requestPath: string): ResolvedTarget | null {
+interface ResolveTargetFileOptions {
+  distDir: string;
+  requestPath: string;
+  spaFallback: boolean;
+}
+
+function resolveTargetFile(options: ResolveTargetFileOptions): ResolvedTarget | null {
+  const { distDir, requestPath, spaFallback } = options;
   const safePath = path.normalize(requestPath).replace(/^(\.\.[/\\])+/, "");
   let filePath = path.join(distDir, safePath);
 
@@ -82,6 +96,9 @@ function resolveTargetFile(distDir: string, requestPath: string): ResolvedTarget
 
   const finalStat = safeStat(filePath);
   if (!finalStat?.isFile()) {
+    if (!spaFallback) {
+      return null;
+    }
     filePath = path.join(distDir, "index.html");
     const fallbackStat = safeStat(filePath);
     if (!fallbackStat?.isFile()) {
@@ -190,8 +207,13 @@ interface ServeWebUiFileOptions {
 function serveWebUiFile(options: ServeWebUiFileOptions): void {
   const { distDir, requestPath, label, req, res } = options;
 
-  const target = resolveTargetFile(distDir, requestPath);
+  const wellKnown = isWellKnownPath(requestPath);
+  const target = resolveTargetFile({ distDir, requestPath, spaFallback: !wellKnown });
   if (!target) {
+    if (wellKnown) {
+      res.status(404).json({ error: "Not found" });
+      return;
+    }
     res.status(404).end();
     return;
   }
diff --git a/packages/server/src/server/websocket-server.relay-reconnect.test.ts b/packages/server/src/server/websocket-server.relay-reconnect.test.ts
index 2d48a93c87..7dcb02669c 100644
--- a/packages/server/src/server/websocket-server.relay-reconnect.test.ts
+++ b/packages/server/src/server/websocket-server.relay-reconnect.test.ts
@@ -1153,10 +1153,12 @@ describe("relay external socket reconnect behavior", () => {
     expect(serverInfo.features?.canonicalSubmittedPrompts).toBe(true);
     expect(serverInfo.features?.providersSnapshotCwd).toBe(true);
     expect(serverInfo.features?.hopliteProvider).toBe(false);
+    expect(serverInfo.features?.fxProvider).toBe(false);
     expect(serverInfo.features?.pluginLogs).toBe(true);
     expect(serverInfo.features?.workspaceMarkUnread).toBe(true);
     expect(serverInfo.features?.["terminal-input-mode-replay"]).toBe(true);
     expect(serverInfo.features?.["terminal-size-ownership"]).toBe(true);
+    expect(serverInfo.features?.["terminal-grapheme-widths"]).toBe(true);
     expect(serverInfo.features?.agentTurnIdentity).toBeUndefined();
     expect(serverInfo.permissions).toEqual(DAEMON_PERMISSIONS);
     await server.close();
diff --git a/packages/server/src/server/websocket-server.ts b/packages/server/src/server/websocket-server.ts
index 78fcdd6804..555706343e 100644
--- a/packages/server/src/server/websocket-server.ts
+++ b/packages/server/src/server/websocket-server.ts
@@ -16,6 +16,10 @@ import { HOST_ROUTE_OPCODE } from "@getpaseo/protocol/binary-frames/index";
 import { DaemonLinkEndpoint, VirtualHostSocket } from "./connected-hosts/index.js";
 import { ConnectedHosts } from "./connected-hosts/index.js";
 import { stat } from "node:fs/promises";
+import {
+  createWorkspaceBaseBranchService,
+  type WorkspaceBaseBranchService,
+} from "./session/workspace-base-branch/service.js";
 import type { CreationSnapshot } from "@getpaseo/protocol/messages";
 import { CreationService } from "./creation/index.js";
 import { MessageReceipts } from "./message-receipts/index.js";
@@ -34,7 +38,11 @@ import type { ProjectRegistry, WorkspaceRegistry } from "./workspace-registry.js
 import type { ProjectUpdate } from "./workspace-reconciliation-service.js";
 import type { ScheduleService } from "./schedule/service.js";
 import type { CheckoutDiffManager, CheckoutDiffMetrics } from "./checkout-diff-manager.js";
-import type { DaemonConfigStore, MutableDaemonConfig } from "./daemon-config-store.js";
+import {
+  toWireDaemonConfig,
+  type DaemonConfigStore,
+  type MutableDaemonConfig,
+} from "./daemon-config-store.js";
 import {
   type ServerInfoStatusPayload,
   type ScriptStatusUpdateMessage,
@@ -61,6 +69,7 @@ import {
 import type { HubRelationshipManagement } from "./hub/relationship-controller.js";
 import { WorkspaceSetupObservation } from "./workspace-setup-observation.js";
 import { WorkspaceSetupRuntime } from "./workspace-setup-runtime.js";
+import { WorkspaceArchiveOperations } from "./workspace-archive-operations.js";
 import type { HubExecutionAgents } from "./hub/daemon-executions.js";
 import type { AgentProvider } from "./agent/agent-sdk-types.js";
 import { ProviderSnapshotManager } from "./agent/provider-snapshot-manager.js";
@@ -358,7 +367,8 @@ function createNoopWorkspaceRegistry(): WorkspaceRegistry {
   return {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => [],
+    listAll: async () => [],
+    listActive: async () => [],
     get: async () => null,
     update: async () => null,
     upsert: async () => {},
@@ -445,6 +455,7 @@ function bufferFromWsData(data: Buffer | ArrayBuffer | Buffer[] | string): Buffe
 
 export interface WebSocketLike {
   maxFrameBytes?: number;
+  supportsConcurrentWrites?: boolean;
   readyState: number;
   bufferedAmount?: number;
   send: (
@@ -568,6 +579,7 @@ export class VoiceAssistantWebSocketServer {
   private readonly creationService: CreationService;
   private readonly projectRegistry: ProjectRegistry;
   private readonly workspaceRegistry: WorkspaceRegistry;
+  private readonly workspaceBaseBranch: WorkspaceBaseBranchService;
   private readonly workspaceLabelService: WorkspaceLabelService | null;
   private readonly scheduleService: ScheduleService;
   private readonly checkoutDiffManager: CheckoutDiffManager;
@@ -603,6 +615,9 @@ export class VoiceAssistantWebSocketServer {
   private readonly voiceCallerContexts = new Map<string, VoiceCallerContext>();
   private readonly workspaceSetupObservation = new WorkspaceSetupObservation();
   private readonly workspaceSetupRuntime: WorkspaceSetupRuntime;
+  // One lane per workspace across every connection, so an undo from any client can cancel an
+  // archive another connection started.
+  private readonly workspaceArchiveOperations = new WorkspaceArchiveOperations();
   private readonly providerSnapshotManager: ProviderSnapshotManager;
   private onLifecycleIntent!: ((intent: SessionLifecycleIntent) => void) | null;
   private onBranchChanged!:
@@ -755,12 +770,18 @@ export class VoiceAssistantWebSocketServer {
     this.checkoutDiffManager = requiredServices.checkoutDiffManager;
     this.github = github ?? createGitHubService();
     this.workspaceGitService = workspaceGitService ?? createFallbackWorkspaceGitService();
+    this.worktreesRoot = daemonRuntimeConfig?.worktreesRoot;
+    this.workspaceBaseBranch = createWorkspaceBaseBranchService({
+      paseoHome,
+      worktreesRoot: this.worktreesRoot,
+      workspaceRegistry: this.workspaceRegistry,
+      workspaceGitService: this.workspaceGitService,
+    });
     this.workspaceAutoName = workspaceAutoName;
     this.downloadTokenStore = downloadTokenStore;
     this.paseoHome = paseoHome;
     this.connectedHosts = new ConnectedHosts(paseoHome, { serverId, label: getHostName() });
     this.passwordHash = auth?.password;
-    this.worktreesRoot = daemonRuntimeConfig?.worktreesRoot;
     this.daemonConfigStore = daemonConfigStore;
     this.mcpBaseUrl = mcpBaseUrl;
     this.assignOptionalServices({
@@ -1211,7 +1232,7 @@ export class VoiceAssistantWebSocketServer {
 
     await Promise.all(cleanupPromises);
     this.providerSnapshotManager.destroy();
-    this.checkoutDiffManager.dispose();
+    await this.checkoutDiffManager.dispose();
     await this.workspaceGitService.dispose();
     this.pendingConnections.clear();
     this.sessions.clear();
@@ -1291,6 +1312,7 @@ export class VoiceAssistantWebSocketServer {
     if (!transport) {
       transport = new ChunkedTransport({
         frameBytes: ws.maxFrameBytes ?? 32 * 1024 * 1024,
+        supportsConcurrentWrites: ws.supportsConcurrentWrites,
         onFailure: (err) =>
           this.closePhysicalSocket({
             ws,
@@ -1660,6 +1682,7 @@ export class VoiceAssistantWebSocketServer {
       creationService: this.creationService,
       projectRegistry: this.projectRegistry,
       workspaceRegistry: this.workspaceRegistry,
+      workspaceBaseBranch: this.workspaceBaseBranch,
       workspaceLabelService: this.workspaceLabelService ?? undefined,
       directorySync: this.directorySync,
       scheduleService: this.scheduleService,
@@ -1684,6 +1707,7 @@ export class VoiceAssistantWebSocketServer {
       scriptRuntimeStore: this.scriptRuntimeStore ?? undefined,
       workspaceSetupObservation: this.workspaceSetupObservation,
       workspaceSetupRuntime: this.workspaceSetupRuntime,
+      workspaceArchiveOperations: this.workspaceArchiveOperations,
       onBranchChanged: this.onBranchChanged ?? undefined,
       getDaemonTcpPort: this.getDaemonTcpPort ?? undefined,
       getDaemonTcpHost: this.getDaemonTcpHost ?? undefined,
@@ -2007,16 +2031,23 @@ export class VoiceAssistantWebSocketServer {
         usageSetting: true,
         usageSources: true,
         ownedSubscriptions: true,
+        providerOptionControls: true,
+        entityMetadata: true,
+        diffSubscription: true,
         binaryChunkingV1: true,
         agentRequestReceipts: true,
         workspaceRequestReceipts: true,
         creationLifecycle: true,
         hubAgentRpc: true,
         backgroundWorkspaces: true,
+        // COMPAT(backgroundAgents): added in v0.15.0; remove gate after 2027-05-03.
+        backgroundAgents: true,
+        workspaceBaseBranch: true,
         // COMPAT(directorySync): added in v0.3.x, remove gate after 2027-02-12.
         directorySync: true,
         // COMPAT(workspaceLabels): added in v0.5.0, remove after 2027-08-14.
         ...(this.workspaceLabelService ? { workspaceLabels: true } : {}),
+        terminalCollection: true,
         // COMPAT(workspaceSetupRun): added in v0.7.3, remove gate after 2027-09-02.
         workspaceSetupRun: true,
         workspaceSetupObservation: true,
@@ -2066,6 +2097,8 @@ export class VoiceAssistantWebSocketServer {
         pluginThemes: true,
         pluginSettings: true,
         pluginTimelineItems: true,
+        // COMPAT(pluginSubscriptions): added in v0.15.0, remove gate after 2027-05-02.
+        pluginSubscriptions: true,
         // COMPAT(skillManagement): added in v0.4.0, remove gate after 2027-08-16.
         skillManagement: true,
         // COMPAT(idleRuntimeCleanupSetting): added in v0.13.0, remove gate after 2027-04-26.
@@ -2077,6 +2110,8 @@ export class VoiceAssistantWebSocketServer {
         "terminal-input-mode-replay": true,
         // COMPAT(terminalSizeOwnership): added in v0.2.6, remove gate after 2027-02-02.
         "terminal-size-ownership": true,
+        // COMPAT(terminalGraphemeWidths): added in v0.15.0, remove gate after 2027-05-01.
+        "terminal-grapheme-widths": true,
         workspaceTerminals: true,
         // COMPAT(rewind): added in v0.1.X, drop the gate when floor >= v0.1.X.
         rewind: true,
@@ -2096,10 +2131,14 @@ export class VoiceAssistantWebSocketServer {
         projectAdd: true,
         // COMPAT(projectList): added in v0.2.4, drop the gate when floor >= v0.2.4.
         projectList: true,
+        // COMPAT(projectSuggestions): added in v0.14.1, remove gate after 2027-05-01.
+        projectSuggestions: true,
         // COMPAT(worktreeRestore): keep through 2027-01-11 for clients older than v0.1.105.
         worktreeRestore: true,
         // COMPAT(workspaceRecovery): added in v0.1.105, remove after 2027-01-11 once daemon floor >= v0.1.105.
         workspaceRecovery: true,
+        // COMPAT(workspaceArchiveUndo): added in v0.15.3, remove gate after 2027-05-06.
+        workspaceArchiveUndo: true,
         // COMPAT(workspaceFileEditing): added in v0.2.0, remove after 2027-01-18 once daemon floor >= v0.2.0.
         workspaceFileEditing: true,
         // COMPAT(fileByteWrites): added in v0.13.0, remove gate after 2027-04-20.
@@ -2122,6 +2161,10 @@ export class VoiceAssistantWebSocketServer {
         agentForkContextCursor: true,
         // COMPAT(providerSubagents): added in v0.1.107, remove gate after 2027-01-12.
         providerSubagents: true,
+        // COMPAT(agentBackgroundWork): added after v0.11.0-beta.5, remove gate after 2027-04-06.
+        agentBackgroundWork: true,
+        // COMPAT(agentBackgroundWorkStop): added after v0.15.0, remove after 2027-05-03.
+        agentBackgroundWorkStop: true,
         // COMPAT(projectedSubagentTimeline): added after v0.8.0, remove gates after 2027-03-14; retain advertisement.
         projectedSubagentTimeline: true,
         wholeTurnTimeline: true,
@@ -2146,6 +2189,8 @@ export class VoiceAssistantWebSocketServer {
         // COMPAT(providerRemoval): added in v0.1.105, drop the gate when floor >= v0.1.105.
         providerRemoval: true,
         hopliteProvider: this.providerSnapshotManager.supportsConfigRequiredProvider("hoplite"),
+        // COMPAT(fxProvider): added after v0.15.3, remove after 2027-05-09 once host floor includes the bundled adapter.
+        fxProvider: this.providerSnapshotManager.supportsConfigRequiredProvider("fx"),
         // COMPAT(importSessionWorkspaceTarget): added in v0.1.110, remove gate after 2027-01-16.
         importSessionWorkspaceTarget: true,
         // COMPAT(importSessionSearch): added in v0.7.3, remove gate after 2027-03-02.
@@ -2155,6 +2200,8 @@ export class VoiceAssistantWebSocketServer {
         forgeProviders: true,
         // COMPAT(selectiveAgentTimeline): added in v0.1.106, remove after 2027-01-12.
         selectiveAgentTimeline: true,
+        // COMPAT(timelineFreshnessCheck): added after v0.15.3, remove after 2027-05-09.
+        timelineFreshnessCheck: true,
         explicitEventSubscriptions: true,
         // COMPAT(canonicalSubmittedPrompts): added in v0.2.6, remove gate after 2027-01-30.
         canonicalSubmittedPrompts: true,
@@ -2196,7 +2243,7 @@ export class VoiceAssistantWebSocketServer {
       type: "status",
       payload: {
         status: "daemon_config_changed",
-        config,
+        config: toWireDaemonConfig(config),
       },
     });
   }
diff --git a/packages/server/src/server/wire-compat.test.ts b/packages/server/src/server/wire-compat.test.ts
index de89963169..9045c43b1c 100644
--- a/packages/server/src/server/wire-compat.test.ts
+++ b/packages/server/src/server/wire-compat.test.ts
@@ -117,6 +117,10 @@ class InMemoryAgentManager {
     };
   }
 
+  getAgentBackgroundWorkSummary() {
+    return undefined;
+  }
+
   fetchTimeline(_agentId: string, options?: AgentTimelineFetchOptions) {
     return this.timeline.fetch({ agentId: "agent-1" }, options);
   }
@@ -131,13 +135,22 @@ class InMemoryAgentManager {
 }
 
 class EmptyAgentStorage {
-  async list() {
+  async listActive() {
     return [];
   }
 
   async get() {
     return null;
   }
+  async listByWorkspaces() {
+    return [];
+  }
+  async lastUserMessageAtByWorkspace() {
+    return new Map<string, string>();
+  }
+  async listAll() {
+    return [];
+  }
 }
 
 class EmptyProjectRegistry {
@@ -159,6 +172,12 @@ class EmptyProjectRegistry {
 }
 
 class EmptyWorkspaceRegistry {
+  listActive() {
+    return [];
+  }
+  listAll() {
+    return [];
+  }
   get() {
     return null;
   }
@@ -242,7 +261,7 @@ function createSessionForWireCompatTest(options?: {
     directorySync: options?.directorySync,
     scheduleService: {} as SessionOptions["scheduleService"],
     checkoutDiffManager: {
-      scheduleRefreshForCwd() {},
+      async scheduleRefreshForCwd() {},
       onWorkspaceStateMayHaveChanged() {},
     } as unknown as SessionOptions["checkoutDiffManager"],
     github: {
@@ -756,7 +775,7 @@ test("setup observation includes a transition that happens during its initial re
         readStarted();
         return pendingRead;
       },
-      list: () => [],
+      listActive: () => [],
     } as unknown as SessionOptions["workspaceRegistry"],
   });
   session.updateClientCapabilities(
diff --git a/packages/server/src/server/workspace-archive-operations.test.ts b/packages/server/src/server/workspace-archive-operations.test.ts
new file mode 100644
index 0000000000..c262f58fa3
--- /dev/null
+++ b/packages/server/src/server/workspace-archive-operations.test.ts
@@ -0,0 +1,282 @@
+import { describe, expect, test } from "vitest";
+
+import { WorkspaceArchiveOperations } from "./workspace-archive-operations.js";
+import { type ArchiveResult, WorkspaceArchiveCanceledError } from "./workspace-archive-service.js";
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+}
+
+function deferred<T = void>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function archived(newlyArchivedAgentIds: string[]): ArchiveResult {
+  return {
+    archivedAgentIds: newlyArchivedAgentIds,
+    newlyArchivedAgentIds,
+    archivedWorkspaceIds: ["ws"],
+    removedDirectory: false,
+  };
+}
+
+/**
+ * An archive that parks until released, then honours its abort signal the way archiveByScope's
+ * checkpoints do: an aborted run reports the agents it already took down.
+ */
+function parkedArchive(agentIds: string[]) {
+  const release = deferred();
+  const started = deferred();
+  let signal: AbortSignal | null = null;
+  return {
+    release: () => release.resolve(),
+    started: started.promise,
+    get aborted() {
+      return signal?.aborted ?? false;
+    },
+    run: async (runSignal: AbortSignal) => {
+      signal = runSignal;
+      started.resolve();
+      await release.promise;
+      if (runSignal.aborted) throw new WorkspaceArchiveCanceledError(agentIds, false);
+      return archived(agentIds);
+    },
+  };
+}
+
+describe("WorkspaceArchiveOperations", () => {
+  test("an undo during a running archive aborts it and restores the agents it took down", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    const archive = parkedArchive(["agent-a", "agent-b"]);
+    const restored: string[][] = [];
+
+    const archiveDone = operations.archive("ws", archive.run);
+    await archive.started;
+    const undoDone = operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+
+    expect(archive.aborted).toBe(true);
+    expect(restored).toEqual([]);
+    archive.release();
+
+    await expect(archiveDone).resolves.toEqual({ kind: "canceled" });
+    await undoDone;
+    expect(restored).toEqual([["agent-a", "agent-b"]]);
+  });
+
+  test("an undo after the archive finished restores the agents that archive took down", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+
+    const restored: string[][] = [];
+    await operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+
+    expect(restored).toEqual([["agent-a"]]);
+  });
+
+  test("restore runs only after the aborted archive has stopped", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    const archive = parkedArchive([]);
+    const order: string[] = [];
+
+    const archiveDone = operations
+      .archive("ws", async (signal) => {
+        try {
+          return await archive.run(signal);
+        } finally {
+          order.push("archive stopped");
+        }
+      })
+      .catch(() => undefined);
+    await archive.started;
+    const undoDone = operations.undo("ws", async () => {
+      order.push("restore");
+    });
+    archive.release();
+    await Promise.all([archiveDone, undoDone]);
+
+    expect(order).toEqual(["archive stopped", "restore"]);
+  });
+
+  test("a second archive while one runs joins it instead of archiving twice", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    const archive = parkedArchive(["agent-a"]);
+    let runs = 0;
+    const run = (signal: AbortSignal) => {
+      runs += 1;
+      return archive.run(signal);
+    };
+
+    const first = operations.archive("ws", run);
+    const second = operations.archive("ws", run);
+    archive.release();
+
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      { kind: "archived", result: archived(["agent-a"]) },
+      { kind: "archived", result: archived(["agent-a"]) },
+    ]);
+    expect(runs).toBe(1);
+  });
+
+  test("an archive requested during an undo runs after the undo, and wins", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+
+    const restoreGate = deferred();
+    const order: string[] = [];
+    const undoDone = operations.undo("ws", async () => {
+      await restoreGate.promise;
+      order.push("restored");
+    });
+    const rearchive = operations.archive("ws", async () => {
+      order.push("archived again");
+      return archived(["agent-a"]);
+    });
+
+    restoreGate.resolve();
+    await undoDone;
+    await expect(rearchive).resolves.toMatchObject({ kind: "archived" });
+    expect(order).toEqual(["restored", "archived again"]);
+  });
+
+  test("archive, undo, archive in quick succession leaves the workspace archived", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    const first = parkedArchive(["agent-a"]);
+    const restored: string[][] = [];
+
+    const firstDone = operations.archive("ws", first.run);
+    await first.started;
+    const undoDone = operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+    // The re-archive must not join the archive the undo just aborted.
+    const secondDone = operations.archive("ws", async () => archived(["agent-a"]));
+    first.release();
+
+    await expect(firstDone).resolves.toEqual({ kind: "canceled" });
+    await undoDone;
+    await expect(secondDone).resolves.toMatchObject({ kind: "archived" });
+    expect(restored).toEqual([["agent-a"]]);
+  });
+
+  test("a second undo while one runs joins it", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+    const restoreGate = deferred();
+    let restores = 0;
+    const restore = async () => {
+      restores += 1;
+      await restoreGate.promise;
+    };
+
+    const first = operations.undo("ws", restore);
+    const second = operations.undo("ws", restore);
+    restoreGate.resolve();
+    await Promise.all([first, second]);
+
+    expect(restores).toBe(1);
+  });
+
+  test("a failed restore keeps the agents for a retry", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+
+    await expect(
+      operations.undo("ws", async () => {
+        throw new Error("worktree recreation failed");
+      }),
+    ).rejects.toThrow("worktree recreation failed");
+
+    const restored: string[][] = [];
+    await operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+    expect(restored).toEqual([["agent-a"]]);
+  });
+
+  test("an archive of an already archived workspace keeps the earlier archive's agents for undo", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+    await operations.archive("ws", async () => ({
+      archivedAgentIds: ["agent-a"],
+      newlyArchivedAgentIds: [],
+      archivedWorkspaceIds: [],
+      removedDirectory: false,
+    }));
+    const restored: string[][] = [];
+
+    await operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+
+    expect(restored).toEqual([["agent-a"]]);
+  });
+
+  test("an undo restores the archive's agents once; a repeat undo restores none", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await operations.archive("ws", async () => archived(["agent-a"]));
+    const restored: string[][] = [];
+    const restore = async ({ agentIds }: { agentIds: string[] }) => {
+      restored.push(agentIds);
+    };
+
+    await operations.undo("ws", restore);
+    await operations.undo("ws", restore);
+
+    expect(restored).toEqual([["agent-a"], []]);
+  });
+
+  test("an undo after the retention window restores the workspace without agents", async () => {
+    let now = 0;
+    const operations = new WorkspaceArchiveOperations({ undoRetentionMs: 1000, now: () => now });
+    await operations.archive("ws", async () => archived(["agent-a"]));
+    now = 1000;
+
+    const restored: string[][] = [];
+    await operations.undo("ws", async ({ agentIds }) => {
+      restored.push(agentIds);
+    });
+    expect(restored).toEqual([[]]);
+  });
+
+  test("workspaces have independent lanes", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    const archive = parkedArchive(["agent-a"]);
+
+    const parked = operations.archive("ws-a", archive.run);
+    await archive.started;
+    await expect(operations.archive("ws-b", async () => archived(["agent-b"]))).resolves.toEqual({
+      kind: "archived",
+      result: archived(["agent-b"]),
+    });
+    await operations.undo("ws-b", async () => {});
+
+    expect(archive.aborted).toBe(false);
+    archive.release();
+    await expect(parked).resolves.toMatchObject({ kind: "archived" });
+  });
+
+  test("a failed archive frees the lane for the next request", async () => {
+    const operations = new WorkspaceArchiveOperations();
+    await expect(
+      operations.archive("ws", async () => {
+        throw new Error("registry unavailable");
+      }),
+    ).rejects.toThrow("registry unavailable");
+
+    await expect(operations.archive("ws", async () => archived([]))).resolves.toMatchObject({
+      kind: "archived",
+    });
+  });
+});
diff --git a/packages/server/src/server/workspace-archive-operations.ts b/packages/server/src/server/workspace-archive-operations.ts
new file mode 100644
index 0000000000..c8bb15a9d2
--- /dev/null
+++ b/packages/server/src/server/workspace-archive-operations.ts
@@ -0,0 +1,133 @@
+import { type ArchiveResult, WorkspaceArchiveCanceledError } from "./workspace-archive-service.js";
+
+export type WorkspaceArchiveOutcome =
+  | { kind: "archived"; result: ArchiveResult }
+  | { kind: "canceled" };
+
+export interface WorkspaceArchiveUndoInput {
+  /** Agents the undone archive took down. Empty when the daemon no longer remembers it. */
+  agentIds: string[];
+}
+
+type LaneEntry =
+  | { kind: "archiving"; controller: AbortController; done: Promise<WorkspaceArchiveOutcome> }
+  | { kind: "undoing"; done: Promise<void> };
+
+interface UndoableArchive {
+  agentIds: string[];
+  expiresAt: number;
+}
+
+const DEFAULT_UNDO_RETENTION_MS = 10 * 60_000;
+
+/**
+ * One lane per workspace for archive and its undo, shared by every session on the daemon.
+ *
+ * - An archive while one runs joins it.
+ * - An undo while an archive runs aborts it, waits for it to stop, then restores.
+ * - An archive while an undo runs waits for the undo, then archives.
+ * - An undo while an undo runs joins it.
+ *
+ * Each call claims the lane synchronously, so whichever request arrives last decides the
+ * workspace's final state no matter how the earlier work interleaves.
+ *
+ * The agents an archive took down are kept in memory for the undo window. An archive that took
+ * nothing down, such as a repeat archive from a stale client, leaves them alone. After a daemon
+ * restart, undo still restores the workspace but its agents stay archived.
+ */
+export class WorkspaceArchiveOperations {
+  private readonly lanes = new Map<string, LaneEntry>();
+  private readonly undoable = new Map<string, UndoableArchive>();
+  private readonly undoRetentionMs: number;
+  private readonly now: () => number;
+
+  constructor(options: { undoRetentionMs?: number; now?: () => number } = {}) {
+    this.undoRetentionMs = options.undoRetentionMs ?? DEFAULT_UNDO_RETENTION_MS;
+    this.now = options.now ?? Date.now;
+  }
+
+  archive(
+    workspaceId: string,
+    run: (signal: AbortSignal) => Promise<ArchiveResult>,
+  ): Promise<WorkspaceArchiveOutcome> {
+    const current = this.lanes.get(workspaceId);
+    if (current?.kind === "archiving") {
+      return current.done;
+    }
+    const controller = new AbortController();
+    const done = (async (): Promise<WorkspaceArchiveOutcome> => {
+      await settled(current?.done);
+      try {
+        const result = await run(controller.signal);
+        if (result.archivedWorkspaceIds.length > 0 || result.newlyArchivedAgentIds.length > 0) {
+          this.retainUndoable(workspaceId, result.newlyArchivedAgentIds);
+        }
+        return { kind: "archived", result };
+      } catch (error) {
+        if (!(error instanceof WorkspaceArchiveCanceledError)) throw error;
+        if (error.recordArchived || error.newlyArchivedAgentIds.length > 0) {
+          this.retainUndoable(workspaceId, error.newlyArchivedAgentIds);
+        }
+        return { kind: "canceled" };
+      }
+    })();
+    this.claim(workspaceId, { kind: "archiving", controller, done });
+    return done;
+  }
+
+  undo(
+    workspaceId: string,
+    restore: (input: WorkspaceArchiveUndoInput) => Promise<void>,
+  ): Promise<void> {
+    const current = this.lanes.get(workspaceId);
+    if (current?.kind === "undoing") {
+      return current.done;
+    }
+    current?.controller.abort();
+    const done = (async () => {
+      await settled(current?.done);
+      const agentIds = this.takeUndoable(workspaceId);
+      try {
+        await restore({ agentIds });
+      } catch (error) {
+        // Keep the agents for a retry; the archive they came from is still the latest one.
+        this.retainUndoable(workspaceId, agentIds);
+        throw error;
+      }
+    })();
+    this.claim(workspaceId, { kind: "undoing", done });
+    return done;
+  }
+
+  private claim(workspaceId: string, entry: LaneEntry): void {
+    this.lanes.set(workspaceId, entry);
+    const release = () => {
+      if (this.lanes.get(workspaceId) === entry) this.lanes.delete(workspaceId);
+    };
+    void (entry.done as Promise<unknown>).then(release, release);
+  }
+
+  private retainUndoable(workspaceId: string, agentIds: string[]): void {
+    const now = this.now();
+    for (const [id, entry] of this.undoable) {
+      if (entry.expiresAt <= now) this.undoable.delete(id);
+    }
+    this.undoable.set(workspaceId, { agentIds, expiresAt: now + this.undoRetentionMs });
+  }
+
+  private takeUndoable(workspaceId: string): string[] {
+    const entry = this.undoable.get(workspaceId);
+    this.undoable.delete(workspaceId);
+    if (!entry || entry.expiresAt <= this.now()) return [];
+    return entry.agentIds;
+  }
+}
+
+async function settled(promise: Promise<unknown> | undefined): Promise<void> {
+  if (!promise) return;
+  try {
+    await promise;
+  } catch {
+    // The earlier request reports its own failure; this one only waits for the lane.
+  }
+}
diff --git a/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts b/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
index df229f9221..d10a098d79 100644
--- a/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
+++ b/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
@@ -8,6 +8,7 @@ import { afterEach, beforeEach, expect, test } from "vitest";
 
 import { getFullAccessConfig } from "./daemon-e2e/agent-configs.js";
 import { createWorktree } from "../utils/worktree.js";
+import { readPaseoWorktreeMetadata } from "../utils/worktree-metadata.js";
 import {
   createDaemonTestContext,
   DaemonClient,
@@ -277,6 +278,118 @@ test("renaming a workspace updates every subscribed client", async () => {
   }
 });
 
+test("a local checkout rejects a base change without creating worktree metadata", async () => {
+  const repo = createGitRepo();
+  const id = await createLocalWorkspace(repo, "Local");
+  await expect(
+    ctx.client.setWorkspaceBaseBranch({ workspaceId: id, baseRef: "refs/heads/main" }),
+  ).rejects.toThrow("not a Paseo worktree");
+  expect(await readPaseoWorktreeMetadata(repo)).toBeNull();
+});
+
+test("changing a worktree base refreshes its diff and persists across restart", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["checkout", "-b", "release"], { cwd: repo });
+  writeFileSync(path.join(repo, "release.txt"), "release\n");
+  execFileSync("git", ["add", "release.txt"], { cwd: repo });
+  execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-m", "release"], { cwd: repo });
+  const created = await ctx.client.createWorkspace({
+    source: { kind: "worktree", cwd: repo, worktreeSlug: "base-refresh", baseBranch: "main" },
+  });
+  const workspace = created.workspace;
+  if (!workspace) throw new Error(created.error ?? "Failed to create workspace");
+  const cwd = workspace.workspaceDirectory;
+  execFileSync("git", ["merge", "--ff-only", "release"], { cwd });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).toContain("release.txt");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).not.toContain("release.txt");
+  await expect(
+    ctx.client.setWorkspaceBaseBranch({ workspaceId: workspace.id, baseRef: "refs/heads/missing" }),
+  ).rejects.toThrow("Base branch not found");
+  execFileSync("git", ["update-ref", "refs/remotes/origin/vanished", "release"], { cwd });
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/remotes/origin/vanished",
+  });
+  execFileSync("git", ["update-ref", "-d", "refs/remotes/origin/vanished"], { cwd });
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/main",
+  });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).toContain("release.txt");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  const previous = ctx;
+  const paseoHomeRoot = path.dirname(previous.daemon.paseoHome);
+  await previous.client.close();
+  await previous.daemon.daemon.stop();
+  tempRoots.push(previous.daemon.staticDir);
+  ctx = await createDaemonTestContext({ paseoHomeRoot });
+  expect((await ctx.client.getCheckoutStatus(cwd)).baseRefExact).toBe("refs/heads/release");
+}, 30_000);
+
+test("a managed workspace restores its changed base after archival removes the checkout", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["branch", "release"], { cwd: repo });
+  const created = await ctx.client.createWorkspace({
+    source: { kind: "worktree", cwd: repo, worktreeSlug: "changed-base", baseBranch: "main" },
+  });
+  const workspace = created.workspace;
+  if (!workspace) throw new Error(created.error ?? "Failed to create workspace");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  const joinedId = await createLocalWorkspace(
+    workspace.workspaceDirectory,
+    "Joined after changing base",
+  );
+  expect((await ctx.client.archiveWorkspace(workspace.id)).error).toBe(null);
+  expect(existsSync(workspace.workspaceDirectory)).toBe(true);
+  expect((await ctx.client.archiveWorkspace(joinedId)).error).toBe(null);
+  expect(existsSync(workspace.workspaceDirectory)).toBe(false);
+  await ctx.client.restoreWorkspace(joinedId);
+  expect((await readPaseoWorktreeMetadata(workspace.workspaceDirectory))?.baseRef).toBe(
+    "refs/heads/release",
+  );
+  expect((await ctx.client.getCheckoutStatus(workspace.workspaceDirectory)).baseRefExact).toBe(
+    "refs/heads/release",
+  );
+});
+
+test("an archived workspace keeps its base when a later workspace reuses its path", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["branch", "release"], { cwd: repo });
+  const source = { kind: "worktree", cwd: repo, worktreeSlug: "reused-path", baseBranch: "main" };
+  const first = (await ctx.client.createWorkspace({ source })).workspace;
+  if (!first) throw new Error("Failed to create first workspace");
+  expect((await ctx.client.archiveWorkspace(first.id)).error).toBe(null);
+  expect(existsSync(first.workspaceDirectory)).toBe(false);
+  const second = (await ctx.client.createWorkspace({ source })).workspace;
+  if (!second) throw new Error("Failed to create second workspace");
+  expect(second.workspaceDirectory).toBe(first.workspaceDirectory);
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: second.id,
+    baseRef: "refs/heads/release",
+  });
+  expect((await ctx.client.archiveWorkspace(second.id)).error).toBe(null);
+  await ctx.client.restoreWorkspace(first.id);
+  expect((await readPaseoWorktreeMetadata(first.workspaceDirectory))?.baseRef).toBe(
+    "refs/heads/main",
+  );
+});
+
 test.each(["worktree", "workspace"] as const)(
   "%s archive immediately removes the deleted worktree from a warm CLI listing",
   async (command) => {
diff --git a/packages/server/src/server/workspace-archive-service.test.ts b/packages/server/src/server/workspace-archive-service.test.ts
index 567c80054f..ecf4210ece 100644
--- a/packages/server/src/server/workspace-archive-service.test.ts
+++ b/packages/server/src/server/workspace-archive-service.test.ts
@@ -19,6 +19,7 @@ import {
   type ArchiveDependencies,
   type ArchiveResult,
   resolveWorkspaceIdAtPath,
+  WorkspaceArchiveCanceledError,
 } from "./workspace-archive-service.js";
 import { WorkspaceAutomationBlockedError } from "./workspace-automation-gate.js";
 
@@ -973,8 +974,9 @@ describe("archiveByScope", () => {
       }),
     };
     deps.agentStorage = {
-      list: async () => [{ id: agentId, workspaceId, archivedAt: null }] as StoredAgentRecord[],
-    } as Pick<AgentStorage, "list">;
+      listByWorkspace: async () =>
+        [{ id: agentId, workspaceId, archivedAt: null }] as StoredAgentRecord[],
+    } as Pick<AgentStorage, "listByWorkspace">;
 
     const result = await archiveByScope(deps, {
       scope: { kind: "workspace", workspaceId },
@@ -1018,6 +1020,207 @@ describe("archiveByScope", () => {
   });
 });
 
+function gate(): {
+  wait: Promise<void>;
+  open: () => void;
+  reached: Promise<void>;
+  reach: () => void;
+} {
+  let open!: () => void;
+  let reach!: () => void;
+  const wait = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  const reached = new Promise<void>((resolve) => {
+    reach = resolve;
+  });
+  return { wait, open, reached, reach };
+}
+
+async function canceledArchive(promise: Promise<unknown>): Promise<WorkspaceArchiveCanceledError> {
+  const error = await promise.then(
+    () => null,
+    (reason: unknown) => reason,
+  );
+  if (!(error instanceof WorkspaceArchiveCanceledError)) {
+    throw new Error(`Expected the archive to be canceled, got ${String(error)}`);
+  }
+  return error;
+}
+
+describe("archiveByScope cancellation", () => {
+  function storedAgents(
+    workspaceId: string,
+    agents: Array<{ id: string; archivedAt: string | null }>,
+  ) {
+    return {
+      listByWorkspace: async () =>
+        agents.map((agent) => ({ ...agent, workspaceId })) as StoredAgentRecord[],
+    } as Pick<AgentStorage, "listByWorkspace">;
+  }
+
+  test("an abort while agents archive keeps the record and reports only the agents it took down", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createPaseoOwnedWorktree(repoDir, paseoHome, "cancel-agents");
+    const workspaceId = "ws-cancel-agents";
+    const deps = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    deps.agentStorage = storedAgents(workspaceId, [
+      { id: "agent-active", archivedAt: null },
+      { id: "agent-already-archived", archivedAt: "2026-01-01T00:00:00.000Z" },
+    ]);
+    const agentArchive = gate();
+    deps.agentManager.archiveSnapshot = vi.fn(async (agentId: string) => {
+      agentArchive.reach();
+      await agentArchive.wait;
+      deps.archivedSnapshotIds.push(agentId);
+      return {} as StoredAgentRecord;
+    });
+    const controller = new AbortController();
+
+    const archive = archiveByScope(deps, {
+      scope: { kind: "workspace", workspaceId },
+      requestId: "req-cancel-agents",
+      signal: controller.signal,
+    });
+    await agentArchive.reached;
+    controller.abort();
+    agentArchive.open();
+    const error = await canceledArchive(archive);
+
+    expect({
+      newlyArchivedAgentIds: error.newlyArchivedAgentIds,
+      recordArchived: error.recordArchived,
+      activeWorkspaceIds: (await deps.listActiveWorkspaces()).map((w) => w.workspaceId),
+      directoryExists: existsSync(worktree.worktreePath),
+    }).toEqual({
+      newlyArchivedAgentIds: ["agent-active"],
+      recordArchived: false,
+      activeWorkspaceIds: [workspaceId],
+      directoryExists: true,
+    });
+    // The archiving marker never outlives a canceled archive.
+    expect(deps.clearWorkspaceArchiving).toHaveBeenCalledWith([workspaceId]);
+  });
+
+  test("an abort after the record archived keeps the worktree directory", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createPaseoOwnedWorktree(repoDir, paseoHome, "cancel-record");
+    const workspaceId = "ws-cancel-record";
+    const deps = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    const recordArchive = gate();
+    const archiveRecord = deps.archiveWorkspaceRecord;
+    deps.archiveWorkspaceRecord = async (id: string) => {
+      recordArchive.reach();
+      await recordArchive.wait;
+      await archiveRecord(id);
+    };
+    const controller = new AbortController();
+
+    const archive = archiveByScope(deps, {
+      scope: { kind: "workspace", workspaceId },
+      requestId: "req-cancel-record",
+      signal: controller.signal,
+    });
+    await recordArchive.reached;
+    controller.abort();
+    recordArchive.open();
+    const error = await canceledArchive(archive);
+
+    expect({
+      recordArchived: error.recordArchived,
+      activeWorkspaceIds: (await deps.listActiveWorkspaces()).map((w) => w.workspaceId),
+      directoryExists: existsSync(worktree.worktreePath),
+    }).toEqual({ recordArchived: true, activeWorkspaceIds: [], directoryExists: true });
+  });
+
+  test("an archive aborted before it starts touches nothing", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createPaseoOwnedWorktree(repoDir, paseoHome, "cancel-before");
+    const workspaceId = "ws-cancel-before";
+    const deps = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    deps.agentStorage = storedAgents(workspaceId, [{ id: "agent-active", archivedAt: null }]);
+    const controller = new AbortController();
+    controller.abort();
+
+    const error = await canceledArchive(
+      archiveByScope(deps, {
+        scope: { kind: "workspace", workspaceId },
+        requestId: "req-cancel-before",
+        signal: controller.signal,
+      }),
+    );
+
+    expect(error.newlyArchivedAgentIds).toEqual([]);
+    expect(deps.archivedSnapshotIds).toEqual([]);
+    expect(deps.markWorkspaceArchiving).not.toHaveBeenCalled();
+    expect(existsSync(worktree.worktreePath)).toBe(true);
+  });
+
+  test("a completed archive reports the agents it newly archived", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createPaseoOwnedWorktree(repoDir, paseoHome, "newly-archived");
+    const workspaceId = "ws-newly-archived";
+    const deps = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    deps.agentStorage = storedAgents(workspaceId, [
+      { id: "agent-active", archivedAt: null },
+      { id: "agent-already-archived", archivedAt: "2026-01-01T00:00:00.000Z" },
+    ]);
+
+    const result = await archiveByScope(deps, {
+      scope: { kind: "workspace", workspaceId },
+      requestId: "req-newly-archived",
+      signal: new AbortController().signal,
+    });
+
+    expect(result.archivedAgentIds.sort()).toEqual(["agent-active", "agent-already-archived"]);
+    expect(result.newlyArchivedAgentIds).toEqual(["agent-active"]);
+  });
+
+  test("an archived agent loaded to read its history is not reported as newly archived", async () => {
+    const { tempDir, repoDir } = createGitRepo();
+    const paseoHome = path.join(tempDir, ".paseo");
+    const worktree = await createPaseoOwnedWorktree(repoDir, paseoHome, "loaded-archived");
+    const workspaceId = "ws-loaded-archived";
+    const deps = createArchiveDeps({
+      paseoHome,
+      activeWorkspaces: [{ workspaceId, cwd: worktree.worktreePath, kind: "worktree" }],
+    });
+    deps.agentStorage = storedAgents(workspaceId, [
+      { id: "agent-active", archivedAt: null },
+      { id: "agent-history", archivedAt: "2026-01-01T00:00:00.000Z" },
+    ]);
+    deps.agentManager.listAgents = () =>
+      [
+        { id: "agent-active", workspaceId },
+        { id: "agent-history", workspaceId },
+      ] as ManagedAgent[];
+
+    const result = await archiveByScope(deps, {
+      scope: { kind: "workspace", workspaceId },
+      requestId: "req-loaded-archived",
+      signal: new AbortController().signal,
+    });
+
+    expect(result.newlyArchivedAgentIds).toEqual(["agent-active"]);
+  });
+});
+
 describe("resolveWorkspaceIdAtPath", () => {
   test("prefers the worktree-kind record on an exact cwd tie", async () => {
     const targetPath = "/worktrees/repo/feature";
diff --git a/packages/server/src/server/workspace-archive-service.ts b/packages/server/src/server/workspace-archive-service.ts
index 78f8c0b97d..54d772add1 100644
--- a/packages/server/src/server/workspace-archive-service.ts
+++ b/packages/server/src/server/workspace-archive-service.ts
@@ -67,6 +67,9 @@ export type ArchiveScope =
 
 export interface ArchiveResult {
   archivedAgentIds: string[];
+  // Agents this request moved from active to archived. `archivedAgentIds` also lists agents that
+  // were already archived; undo must restore only the ones this archive took down.
+  newlyArchivedAgentIds: string[];
   archivedWorkspaceIds: string[];
   removedDirectory: boolean;
   // Set when the record archived but its worktree directory was left on
@@ -78,6 +81,24 @@ export interface ArchiveResult {
 export interface ArchiveByScopeRequest {
   scope: ArchiveScope;
   requestId: string;
+  // Aborting cancels the archive at its next checkpoint. Removing the worktree directory is the
+  // point of no return: once it starts the archive completes.
+  signal?: AbortSignal;
+}
+
+/**
+ * The archive stopped at a checkpoint because its signal aborted. Whatever ran before the
+ * checkpoint stays done; `newlyArchivedAgentIds` and `recordArchived` say how far it got so the
+ * canceller can put it back.
+ */
+export class WorkspaceArchiveCanceledError extends Error {
+  constructor(
+    public readonly newlyArchivedAgentIds: string[],
+    public readonly recordArchived: boolean,
+  ) {
+    super("Workspace archive was canceled");
+    this.name = "WorkspaceArchiveCanceledError";
+  }
 }
 
 export async function requireActiveWorkspaceForArchive(
@@ -144,10 +165,22 @@ async function archiveByScopeWithPriority(
   dependencies: ArchiveDependencies,
   request: ArchiveByScopeRequest,
 ): Promise<ArchiveResult> {
+  const progress: ArchiveProgress = { newlyArchivedAgentIds: new Set(), recordArchived: false };
+  const checkpoint = () => {
+    if (request.signal?.aborted) {
+      throw new WorkspaceArchiveCanceledError(
+        Array.from(progress.newlyArchivedAgentIds),
+        progress.recordArchived,
+      );
+    }
+  };
+
+  checkpoint();
   const target = await resolveArchiveTarget(dependencies, request.scope);
   const targetWorkspaceIds = target.workspaceIds;
 
   await stopWorkspaceSetups(dependencies, target.setupWorkspaceIds, request.requestId);
+  checkpoint();
 
   if (targetWorkspaceIds.length > 0) {
     dependencies.markWorkspaceArchiving(targetWorkspaceIds, new Date().toISOString());
@@ -160,12 +193,14 @@ async function archiveByScopeWithPriority(
     if (targetWorkspaceIds.length > 0) {
       await dependencies.emitWorkspaceUpdatesForWorkspaceIds(targetWorkspaceIds);
     }
+    checkpoint();
 
     const { archivedAgents, archivedWorkspaceIds } = await archiveTargetRecords(
       dependencies,
       targetWorkspaceIds,
-      request.requestId,
+      { requestId: request.requestId, checkpoint, progress },
     );
+    checkpoint();
 
     if (target.backing?.mainRepoRoot) {
       try {
@@ -184,7 +219,7 @@ async function archiveByScopeWithPriority(
     if (target.backing !== null) {
       const removal = await maybeRemoveDirectory(
         dependencies,
-        request,
+        { requestId: request.requestId, checkpoint },
         target,
         archivedWorkspaceIds,
       );
@@ -194,6 +229,7 @@ async function archiveByScopeWithPriority(
 
     return {
       archivedAgentIds: Array.from(archivedAgents),
+      newlyArchivedAgentIds: Array.from(progress.newlyArchivedAgentIds),
       archivedWorkspaceIds,
       removedDirectory,
       ...(directoryLeftBehind ? { directoryLeftBehind } : {}),
@@ -206,6 +242,11 @@ async function archiveByScopeWithPriority(
   }
 }
 
+interface ArchiveProgress {
+  newlyArchivedAgentIds: Set<string>;
+  recordArchived: boolean;
+}
+
 async function resolveArchiveTarget(
   dependencies: ArchiveDependencies,
   scope: ArchiveScope,
@@ -352,16 +393,23 @@ async function resolveBackingDirectory(
 async function archiveTargetRecords(
   dependencies: ArchiveDependencies,
   targetWorkspaceIds: string[],
-  requestId: string,
+  options: { requestId: string; checkpoint: () => void; progress: ArchiveProgress },
 ): Promise<{ archivedAgents: Set<string>; archivedWorkspaceIds: string[] }> {
   const archivedAgents = new Set<string>();
   const archivedWorkspaceIds: string[] = [];
 
   const results = await Promise.allSettled(
     targetWorkspaceIds.map(async (workspaceId) => {
-      const agents = await archiveWorkspaceContents(dependencies, workspaceId);
+      const contents = await archiveWorkspaceContentsWithProgress(dependencies, workspaceId);
+      for (const agentId of contents.newlyArchivedAgentIds) {
+        options.progress.newlyArchivedAgentIds.add(agentId);
+      }
+      // Agents and terminals are down, the record is not: an abort here leaves the workspace
+      // listed, and the canceller restores the agents it reports.
+      options.checkpoint();
       await dependencies.archiveWorkspaceRecord(workspaceId);
-      return { workspaceId, agents };
+      options.progress.recordArchived = true;
+      return { workspaceId, agents: contents.agentIds };
     }),
   );
 
@@ -371,9 +419,14 @@ async function archiveTargetRecords(
       for (const agentId of result.value.agents) {
         archivedAgents.add(agentId);
       }
+    } else if (result.reason instanceof WorkspaceArchiveCanceledError) {
+      throw new WorkspaceArchiveCanceledError(
+        Array.from(options.progress.newlyArchivedAgentIds),
+        options.progress.recordArchived,
+      );
     } else {
       dependencies.sessionLogger?.warn(
-        { err: result.reason, requestId },
+        { err: result.reason, requestId: options.requestId },
         "archiveByScope workspace teardown failed; continuing",
       );
     }
@@ -384,7 +437,7 @@ async function archiveTargetRecords(
 
 async function maybeRemoveDirectory(
   dependencies: ArchiveDependencies,
-  request: Pick<ArchiveByScopeRequest, "requestId">,
+  request: { requestId: string; checkpoint: () => void },
   target: ArchiveTarget,
   archivedWorkspaceIds: string[],
 ): Promise<{
@@ -423,6 +476,7 @@ async function maybeRemoveDirectory(
       teardownTargets,
     );
     for (const teardownTarget of uniqueTeardownTargets(allowedTeardownTargets)) {
+      request.checkpoint();
       await runWorktreeTeardownCommands({
         worktreePath: backing.path,
         teardownCwd: teardownTarget.cwd,
@@ -452,6 +506,9 @@ async function maybeRemoveDirectory(
     return { removedDirectory: false };
   }
 
+  // Last chance to keep the directory. Teardown commands already ran, so a cancel here restores
+  // a workspace whose teardown hooks fired; that beats deleting what the user asked to keep.
+  request.checkpoint();
   try {
     await deletePaseoWorktree({
       cwd: backing.mainRepoRoot,
@@ -518,6 +575,13 @@ export async function archiveWorkspaceContents(
   dependencies: ArchiveWorkspaceContentsDependencies,
   workspaceId: string,
 ): Promise<Set<string>> {
+  return (await archiveWorkspaceContentsWithProgress(dependencies, workspaceId)).agentIds;
+}
+
+async function archiveWorkspaceContentsWithProgress(
+  dependencies: ArchiveWorkspaceContentsDependencies,
+  workspaceId: string,
+): Promise<{ agentIds: Set<string>; newlyArchivedAgentIds: string[] }> {
   const archivedAgents = new Set<string>();
 
   const liveAgents = dependencies.agentManager
@@ -542,29 +606,52 @@ export async function archiveWorkspaceContents(
   }
 
   const archivedAt = new Date().toISOString();
-  const agentIdsToArchive = new Set([
-    ...liveAgents.map((agent) => agent.id),
-    ...matchingStoredRecords.filter((record) => !record.archivedAt).map((record) => record.id),
-  ]);
-  const archiveResults = await Promise.allSettled([
-    ...[...agentIdsToArchive].map((agentId) =>
-      dependencies.agentManager.getAgent(agentId)
-        ? dependencies.agentManager.archiveAgent(agentId)
-        : dependencies.agentManager.archiveSnapshot(agentId, archivedAt),
+  const agentIdsToArchive = [
+    ...new Set([
+      ...liveAgents.map((agent) => agent.id),
+      ...matchingStoredRecords.filter((record) => !record.archivedAt).map((record) => record.id),
+    ]),
+  ];
+  // Undo brings back only what this archive took down. Internal agents are retired rather than
+  // archived, and an agent loaded only to read its history was archived before this request.
+  const restorableAgentIds = new Set(agentIdsToArchive);
+  for (const agent of liveAgents) {
+    if (agent.internal) restorableAgentIds.delete(agent.id);
+  }
+  for (const record of matchingStoredRecords) {
+    if (record.archivedAt) restorableAgentIds.delete(record.id);
+  }
+  const [agentResults, [terminalResult]] = await Promise.all([
+    Promise.allSettled(
+      agentIdsToArchive.map((agentId) =>
+        dependencies.agentManager.getAgent(agentId)
+          ? dependencies.agentManager.archiveAgent(agentId)
+          : dependencies.agentManager.archiveSnapshot(agentId, archivedAt),
+      ),
     ),
-    dependencies.killTerminalsForWorkspace(workspaceId),
+    Promise.allSettled([dependencies.killTerminalsForWorkspace(workspaceId)]),
   ]);
 
-  for (const result of archiveResults) {
+  const newlyArchivedAgentIds: string[] = [];
+  for (const [index, result] of agentResults.entries()) {
+    const agentId = agentIdsToArchive[index]!;
     if (result.status === "rejected") {
       dependencies.sessionLogger?.warn(
-        { err: result.reason, workspaceId },
+        { err: result.reason, workspaceId, agentId },
         "Workspace archive teardown step failed; continuing",
       );
+    } else if (restorableAgentIds.has(agentId)) {
+      newlyArchivedAgentIds.push(agentId);
     }
   }
+  if (terminalResult?.status === "rejected") {
+    dependencies.sessionLogger?.warn(
+      { err: terminalResult.reason, workspaceId },
+      "Workspace archive teardown step failed; continuing",
+    );
+  }
 
-  return archivedAgents;
+  return { agentIds: archivedAgents, newlyArchivedAgentIds };
 }
 
 // True when, after archiving
diff --git a/packages/server/src/server/workspace-archive-undo.e2e.test.ts b/packages/server/src/server/workspace-archive-undo.e2e.test.ts
new file mode 100644
index 0000000000..674e99415b
--- /dev/null
+++ b/packages/server/src/server/workspace-archive-undo.e2e.test.ts
@@ -0,0 +1,275 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, expect, test } from "vitest";
+
+import { getFullAccessConfig } from "./daemon-e2e/agent-configs.js";
+import { createDaemonTestContext, type DaemonTestContext } from "./test-utils/index.js";
+
+// Undo of a workspace archive, end to end through a real daemon. The archive is parked inside a
+// worktree teardown command that waits on a file, so the undo lands at a known point.
+
+let ctx: DaemonTestContext;
+const tempRoots: string[] = [];
+
+beforeEach(async () => {
+  ctx = await createDaemonTestContext();
+});
+
+afterEach(async () => {
+  await ctx.cleanup();
+  for (const tempRoot of tempRoots.splice(0)) {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
+interface GatedRepo {
+  repoDir: string;
+  teardownStartedPath: string;
+  releaseTeardown: () => void;
+}
+
+function git(repoDir: string, args: string[]): void {
+  execFileSync("git", args, { cwd: repoDir, stdio: "pipe" });
+}
+
+/** A repo whose worktree teardown parks until released. */
+function createRepoWithGatedTeardown(): GatedRepo {
+  const tempRoot = mkdtempSync(path.join(tmpdir(), "workspace-archive-undo-"));
+  tempRoots.push(tempRoot);
+  const repoDir = path.join(tempRoot, "repo");
+  const teardownStartedPath = path.join(tempRoot, "teardown-started");
+  const releasePath = path.join(tempRoot, "release-teardown");
+  execFileSync("git", ["init", "-b", "main", repoDir], { stdio: "pipe" });
+  git(repoDir, ["config", "user.email", "test@getpaseo.local"]);
+  git(repoDir, ["config", "user.name", "Paseo Test"]);
+  const teardown = `node -e "const fs=require('fs');fs.writeFileSync('${teardownStartedPath}','started');const timer=setInterval(()=>{if(fs.existsSync('${releasePath}'))clearInterval(timer)},20)"`;
+  writeFileSync(
+    path.join(repoDir, "paseo.json"),
+    JSON.stringify({ worktree: { teardown: [teardown] } }),
+  );
+  git(repoDir, ["add", "paseo.json"]);
+  git(repoDir, ["-c", "commit.gpgsign=false", "commit", "-m", "gated teardown"]);
+  return {
+    repoDir,
+    teardownStartedPath,
+    releaseTeardown: () => writeFileSync(releasePath, "release\n"),
+  };
+}
+
+async function createWorktreeWorkspaceWithAgent(repoDir: string, slug: string) {
+  const result = await ctx.client.createWorkspace({
+    source: { kind: "worktree", cwd: repoDir, worktreeSlug: slug, baseBranch: "main" },
+  });
+  const workspace = result.workspace;
+  if (!workspace?.workspaceDirectory) {
+    throw new Error(result.error ?? "Failed to create worktree workspace");
+  }
+  const agent = await ctx.client.createAgent({
+    ...getFullAccessConfig("codex"),
+    cwd: workspace.workspaceDirectory,
+    workspaceId: workspace.id,
+    title: "Undo agent",
+  });
+  return { workspaceId: workspace.id, directory: workspace.workspaceDirectory, agentId: agent.id };
+}
+
+async function isWorkspaceActive(workspaceId: string): Promise<boolean> {
+  const workspaces = await ctx.client.fetchWorkspaces();
+  return workspaces.entries.some((entry) => entry.id === workspaceId);
+}
+
+async function isAgentArchived(agentId: string): Promise<boolean> {
+  const agents = await ctx.client.fetchAgents({ filter: { includeArchived: true } });
+  const entry = agents.entries.find((candidate) => candidate.agent.id === agentId);
+  if (!entry) throw new Error(`Agent ${agentId} is missing`);
+  return entry.agent.archivedAt !== null && entry.agent.archivedAt !== undefined;
+}
+
+test.skipIf(process.platform === "win32")(
+  "an undo while teardown runs cancels the archive before the worktree is deleted",
+  async () => {
+    const repo = createRepoWithGatedTeardown();
+    const { workspaceId, directory, agentId } = await createWorktreeWorkspaceWithAgent(
+      repo.repoDir,
+      "undo-during-teardown",
+    );
+
+    try {
+      const archive = ctx.client.archiveWorkspace(workspaceId);
+      await expect.poll(() => existsSync(repo.teardownStartedPath), { timeout: 15000 }).toBe(true);
+      const undo = ctx.client.undoWorkspaceArchive(workspaceId);
+      repo.releaseTeardown();
+
+      const [archiveResponse] = await Promise.all([archive, undo]);
+
+      expect({
+        canceled: archiveResponse.canceled,
+        archivedAt: archiveResponse.archivedAt,
+        workspaceActive: await isWorkspaceActive(workspaceId),
+        directoryExists: existsSync(directory),
+        agentArchived: await isAgentArchived(agentId),
+      }).toEqual({
+        canceled: true,
+        archivedAt: null,
+        workspaceActive: true,
+        directoryExists: true,
+        agentArchived: false,
+      });
+    } finally {
+      repo.releaseTeardown();
+    }
+  },
+  60000,
+);
+
+test.skipIf(process.platform === "win32")(
+  "an undo after the archive finished recreates the worktree and its agents",
+  async () => {
+    const repo = createRepoWithGatedTeardown();
+    repo.releaseTeardown();
+    const { workspaceId, directory, agentId } = await createWorktreeWorkspaceWithAgent(
+      repo.repoDir,
+      "undo-after-archive",
+    );
+
+    const archived = await ctx.client.archiveWorkspace(workspaceId);
+    expect(archived.error).toBeNull();
+    expect(existsSync(directory)).toBe(false);
+    expect(await isAgentArchived(agentId)).toBe(true);
+
+    await ctx.client.undoWorkspaceArchive(workspaceId);
+
+    expect({
+      workspaceActive: await isWorkspaceActive(workspaceId),
+      directoryExists: existsSync(directory),
+      agentArchived: await isAgentArchived(agentId),
+    }).toEqual({ workspaceActive: true, directoryExists: true, agentArchived: false });
+  },
+  60000,
+);
+
+test.skipIf(process.platform === "win32")(
+  "archive, undo, archive leaves the workspace archived",
+  async () => {
+    const repo = createRepoWithGatedTeardown();
+    const { workspaceId, directory, agentId } = await createWorktreeWorkspaceWithAgent(
+      repo.repoDir,
+      "archive-undo-archive",
+    );
+
+    try {
+      const first = ctx.client.archiveWorkspace(workspaceId);
+      await expect.poll(() => existsSync(repo.teardownStartedPath), { timeout: 15000 }).toBe(true);
+      const undo = ctx.client.undoWorkspaceArchive(workspaceId);
+      const second = ctx.client.archiveWorkspace(workspaceId);
+      repo.releaseTeardown();
+
+      const [firstResponse, , secondResponse] = await Promise.all([first, undo, second]);
+
+      expect({
+        firstCanceled: firstResponse.canceled,
+        secondError: secondResponse.error,
+        secondCanceled: secondResponse.canceled ?? false,
+        workspaceActive: await isWorkspaceActive(workspaceId),
+        directoryExists: existsSync(directory),
+        agentArchived: await isAgentArchived(agentId),
+      }).toEqual({
+        firstCanceled: true,
+        secondError: null,
+        secondCanceled: false,
+        workspaceActive: false,
+        directoryExists: false,
+        agentArchived: true,
+      });
+    } finally {
+      repo.releaseTeardown();
+    }
+  },
+  60000,
+);
+
+test.skipIf(process.platform === "win32")(
+  "an undo sent right behind its archive leaves the workspace active",
+  async () => {
+    const repo = createRepoWithGatedTeardown();
+    repo.releaseTeardown();
+    const { workspaceId, directory, agentId } = await createWorktreeWorkspaceWithAgent(
+      repo.repoDir,
+      "archive-then-undo-same-tick",
+    );
+
+    const [archiveResponse] = await Promise.all([
+      ctx.client.archiveWorkspace(workspaceId),
+      ctx.client.undoWorkspaceArchive(workspaceId),
+    ]);
+
+    expect({
+      archiveCanceled: archiveResponse.canceled ?? false,
+      workspaceActive: await isWorkspaceActive(workspaceId),
+      directoryExists: existsSync(directory),
+      agentArchived: await isAgentArchived(agentId),
+    }).toEqual({
+      archiveCanceled: true,
+      workspaceActive: true,
+      directoryExists: true,
+      agentArchived: false,
+    });
+  },
+  60000,
+);
+
+test.skipIf(process.platform === "win32")(
+  "the undo response arrives after the client has seen its agents restored",
+  async () => {
+    const repo = createRepoWithGatedTeardown();
+    repo.releaseTeardown();
+    const { workspaceId, agentId } = await createWorktreeWorkspaceWithAgent(
+      repo.repoDir,
+      "undo-update-order",
+    );
+    await ctx.client.fetchAgents({ subscribe: {} });
+    // An archived agent leaves a default subscription; a restored one comes back as active.
+    let seenState: "active" | "archived" | "removed" = "active";
+    const stop = ctx.client.on("agent_update", (message) => {
+      if (message.payload.kind === "remove" && message.payload.agentId === agentId) {
+        seenState = "removed";
+      }
+      if (message.payload.kind === "upsert" && message.payload.agent.id === agentId) {
+        seenState = message.payload.agent.archivedAt ? "archived" : "active";
+      }
+    });
+
+    try {
+      await ctx.client.archiveWorkspace(workspaceId);
+      await expect.poll(() => seenState, { timeout: 15000 }).not.toBe("active");
+
+      await ctx.client.undoWorkspaceArchive(workspaceId);
+
+      // An app holds its agent tabs open until this response; an agent it still sees as
+      // archived at that point gets its tab closed.
+      expect(seenState).toBe("active");
+    } finally {
+      stop();
+    }
+  },
+  60000,
+);
+
+test("an undo on a workspace that was never archived leaves it as it was", async () => {
+  const repo = createRepoWithGatedTeardown();
+  repo.releaseTeardown();
+  const { workspaceId, directory, agentId } = await createWorktreeWorkspaceWithAgent(
+    repo.repoDir,
+    "undo-without-archive",
+  );
+
+  await ctx.client.undoWorkspaceArchive(workspaceId);
+
+  expect({
+    workspaceActive: await isWorkspaceActive(workspaceId),
+    directoryExists: existsSync(directory),
+    agentArchived: await isAgentArchived(agentId),
+  }).toEqual({ workspaceActive: true, directoryExists: true, agentArchived: false });
+}, 60000);
diff --git a/packages/server/src/server/workspace-directory.test.ts b/packages/server/src/server/workspace-directory.test.ts
index be59c3a24a..2b9eb396a2 100644
--- a/packages/server/src/server/workspace-directory.test.ts
+++ b/packages/server/src/server/workspace-directory.test.ts
@@ -1,4 +1,12 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { buildStoredAgentPayload } from "./agent/agent-projections.js";
+import type { ManagedAgent } from "./agent/agent-manager.js";
+import { Session as InspectorSession } from "node:inspector/promises";
+import type { HeapProfiler } from "node:inspector";
+import {
+  FileBackedWorkspaceRegistry,
+  createPersistedWorkspaceRecord,
+} from "./workspace-registry.js";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentStorage } from "./agent/agent-storage.js";
@@ -73,7 +81,10 @@ class WorkspaceStatus {
   private readonly directory = new WorkspaceDirectory({
     logger: createTestLogger(),
     projectRegistry: { list: async () => [this.project] },
-    workspaceRegistry: { list: async () => this.workspaces },
+    workspaceRegistry: {
+      listActive: async () => this.workspaces.filter((w) => !w.archivedAt),
+      get: async (id) => this.workspaces.find((w) => w.workspaceId === id) ?? null,
+    },
     listAgentPayloads: async () => this.agents,
     workspaceLastUserMessageTimes: async () => {
       const times = new Map<string, string>();
@@ -262,6 +273,8 @@ interface AgentState {
   pendingPermissionCount?: number;
   requiresAttention?: boolean;
   attentionReason?: AgentSnapshotPayload["attentionReason"];
+  backgroundWork?: AgentSnapshotPayload["backgroundWork"];
+  background?: boolean;
 }
 
 function createAgent(
@@ -273,6 +286,7 @@ function createAgent(
     provider: "codex",
     cwd: input.cwd,
     ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+    ...(input.background ? { background: true } : {}),
     model: null,
     thinkingOptionId: null,
     effectiveThinkingOptionId: null,
@@ -280,6 +294,7 @@ function createAgent(
     updatedAt: NOW,
     lastUserMessageAt: input.lastUserMessageAt ?? null,
     status: input.status,
+    backgroundWork: input.backgroundWork,
     capabilities: {
       supportsStreaming: true,
       supportsSessionPersistence: true,
@@ -311,6 +326,17 @@ function createAgent(
 }
 
 describe("WorkspaceDirectory", () => {
+  test("treats background work as running without changing foreground status", async () => {
+    const workspace = new WorkspaceStatus();
+    workspace.hasRootAgent({
+      id: "root-agent",
+      status: "idle",
+      backgroundWork: { count: 1 },
+      requiresAttention: true,
+      attentionReason: "finished",
+    });
+    await expect(workspace.workspaceStatus()).resolves.toBe("running");
+  });
   test("uses root agent activity, not delegated child activity, for workspace status", async () => {
     const workspace = new WorkspaceStatus();
 
@@ -330,6 +356,30 @@ describe("WorkspaceDirectory", () => {
     await expect(workspace.workspaceStatus()).resolves.toBe("running");
   });
 
+  test("an errored root agent shows failed only until its error is read", async () => {
+    const unread = new WorkspaceStatus();
+    unread.hasRootAgent({
+      id: "root-agent",
+      status: "error",
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    await expect(unread.workspaceStatus()).resolves.toBe("failed");
+
+    const read = new WorkspaceStatus();
+    read.hasRootAgent({ id: "root-agent", status: "error", requiresAttention: false });
+    await expect(read.workspaceStatus()).resolves.toBe("done");
+  });
+
+  test("a running background agent does not make its workspace running", async () => {
+    const workspace = new WorkspaceStatus();
+
+    workspace.hasRootAgent({ id: "root-agent", status: "idle" });
+    workspace.hasRootAgent({ id: "classifier", status: "running", background: true });
+
+    await expect(workspace.workspaceStatus()).resolves.toBe("done");
+  });
+
   test("same-cwd workspaces attribute agent status only to the owner", async () => {
     const workspace = new WorkspaceStatus();
 
@@ -575,7 +625,10 @@ describe("WorkspaceDirectory empty projects", () => {
     return new WorkspaceDirectory({
       logger: createTestLogger(),
       projectRegistry: { list: async () => input.projects },
-      workspaceRegistry: { list: async () => input.workspaces },
+      workspaceRegistry: {
+        listActive: async () => input.workspaces.filter((w) => !w.archivedAt),
+        get: async (id) => input.workspaces.find((w) => w.workspaceId === id) ?? null,
+      },
       listAgentPayloads: async () => [],
       workspaceLastUserMessageTimes: async () => new Map(),
       listProviderSubagentActivity: async () => [],
@@ -734,9 +787,9 @@ test("Git observation targets exclude archived records without hydrating app des
     logger: createTestLogger(),
     projectRegistry: { list: async () => [project("active"), project("archived", NOW)] },
     workspaceRegistry: {
-      list: async () => [
+      get: async () => null,
+      listActive: async () => [
         workspace("observed", "active"),
-        workspace("hidden", "active", NOW),
         workspace("hidden-project", "archived"),
       ],
     },
@@ -799,13 +852,22 @@ test("prompt recency reads archived records without projecting agents or exposin
       lastUserMessageAt: "2026-03-05T00:00:00.000Z",
     });
     await storage.upsert({ ...base, id: "output", lastActivityAt: "2026-03-06T00:00:00.000Z" });
+    await storage.upsert({ ...base, id: "live", lastUserMessageAt: "2026-03-09T00:00:00.000Z" });
     const unexpectedProjection = (): never => {
       throw new Error("Prompt sorting projected an agent payload");
     };
     const directory = new AgentDirectory({
       storage,
-      manager: { listAgents: () => [] },
-      workspaces: { get: async () => null, list: async () => [] },
+      manager: {
+        listAgents: () => [
+          {
+            id: "live",
+            workspaceId: "w",
+            lastUserMessageAt: new Date("2026-03-02T00:00:00.000Z"),
+          } as ManagedAgent,
+        ],
+      },
+      workspaces: { get: async () => null },
       projectLive: unexpectedProjection,
       projectStored: unexpectedProjection,
       isProviderVisible: () => false,
@@ -818,3 +880,149 @@ test("prompt recency reads archived records without projecting agents or exposin
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test("scoped descriptor builds allocate independently of archived history", async () => {
+  const home = await mkdtemp(join(tmpdir(), "descriptor-history-"));
+  try {
+    const logger = createTestLogger();
+    const agentsPath = join(home, "agents");
+    await mkdir(agentsPath);
+    const records = Array.from({ length: 10001 }, (_, i) =>
+      createPersistedWorkspaceRecord({
+        workspaceId: `w${i}`,
+        projectId: "p",
+        cwd: home,
+        kind: "directory",
+        displayName: "workspace",
+        createdAt: NOW,
+        updatedAt: NOW,
+        archivedAt: i ? NOW : null,
+      }),
+    );
+    await writeFile(join(home, "workspaces.json"), JSON.stringify(records));
+    for (let offset = 0; offset < 10000; offset += 100)
+      await Promise.all(
+        Array.from({ length: 100 }, (_, i) => {
+          const id = `a${offset + i}`;
+          return writeFile(
+            join(agentsPath, `${id}.json`),
+            JSON.stringify({
+              id,
+              provider: "codex",
+              cwd: home,
+              workspaceId: "w1",
+              createdAt: NOW,
+              updatedAt: NOW,
+              labels: {},
+              archivedAt: NOW,
+              lastUserMessageAt: NOW,
+            }),
+          );
+        }),
+      );
+    const storage = new AgentStorage(agentsPath, logger);
+    const registry = new FileBackedWorkspaceRegistry(join(home, "workspaces.json"), logger);
+    await storage.initialize();
+    await storage.upsert({
+      id: "parent",
+      provider: "codex",
+      cwd: home,
+      workspaceId: "w2",
+      createdAt: NOW,
+      updatedAt: NOW,
+    });
+    await storage.upsert({
+      id: "child",
+      provider: "codex",
+      cwd: home,
+      workspaceId: "w0",
+      createdAt: NOW,
+      updatedAt: NOW,
+      lastStatus: "running",
+      labels: { "paseo.parent-agent-id": "parent" },
+    });
+    await registry.initialize();
+    const agents = new AgentDirectory({
+      storage,
+      workspaces: registry,
+      manager: { listAgents: () => [] },
+      projectLive: async () => {
+        throw new Error("Unexpected live projection");
+      },
+      projectStored: (record) =>
+        buildStoredAgentPayload(record, ["codex"], (_provider, own) => own ?? {}),
+      isProviderVisible: () => true,
+      isStoredProviderAvailable: () => true,
+    });
+    const directory = new WorkspaceDirectory({
+      logger,
+      workspaceRegistry: registry,
+      projectRegistry: {
+        list: async () => [
+          {
+            projectId: "p",
+            rootPath: home,
+            kind: "non_git",
+            displayName: "project",
+            createdAt: NOW,
+            updatedAt: NOW,
+            archivedAt: null,
+          },
+        ],
+      },
+      listAgentPayloads: (workspaceIds) =>
+        agents.list({ workspaceIds, includeBackground: true, includeAncestors: true }),
+      workspaceLastUserMessageTimes: (workspaceIds) =>
+        agents.workspaceLastUserMessageTimes(workspaceIds),
+      listProviderSubagentActivity: async () => [],
+      listTerminalActivityContributions: async () => [],
+      isProviderVisibleToClient: () => true,
+      buildWorkspaceDescriptor: async ({ workspace }) => ({
+        id: workspace.workspaceId,
+        projectId: "p",
+        projectDisplayName: "project",
+        projectRootPath: home,
+        projectKind: "non_git",
+        workspaceDirectory: home,
+        workspaceKind: "directory",
+        name: "workspace",
+        status: "done",
+        activityAt: null,
+        diffStat: null,
+        scripts: [],
+        gitRuntime: null,
+        githubRuntime: null,
+      }),
+    });
+    const scoped = await directory.buildDescriptorMap({
+      workspaceIds: new Set(["w0"]).values(),
+      includeGitData: false,
+    });
+    expect(scoped.get("w0")?.status).toBe("running");
+    const inspector = new InspectorSession();
+    inspector.connect();
+    let bytes = 0;
+    try {
+      await inspector.post("HeapProfiler.startSampling", {
+        samplingInterval: 16384,
+        includeObjectsCollectedByMajorGC: true,
+        includeObjectsCollectedByMinorGC: true,
+      });
+      for (let i = 0; i < 100; i++)
+        await directory.buildDescriptorMap({
+          workspaceIds: new Set(["w0"]).values(),
+          includeGitData: false,
+        });
+      const { profile } = await inspector.post("HeapProfiler.stopSampling");
+      function sum(node: HeapProfiler.SamplingHeapProfileNode): number {
+        return node.selfSize + node.children.reduce((total, child) => total + sum(child), 0);
+      }
+      bytes = sum(profile.head);
+    } finally {
+      inspector.disconnect();
+    }
+    expect(bytes).toBeLessThan(8 * 1024 * 1024);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+}, 30000);
diff --git a/packages/server/src/server/workspace-directory.ts b/packages/server/src/server/workspace-directory.ts
index 50bc58a06d..ebab30916f 100644
--- a/packages/server/src/server/workspace-directory.ts
+++ b/packages/server/src/server/workspace-directory.ts
@@ -74,10 +74,13 @@ export interface WorkspaceDirectoryDeps {
     list(): Promise<PersistedProjectRecord[]>;
   };
   workspaceRegistry: {
-    list(): Promise<PersistedWorkspaceRecord[]>;
+    listActive(): Promise<PersistedWorkspaceRecord[]>;
+    get(id: string): Promise<PersistedWorkspaceRecord | null>;
   };
-  listAgentPayloads(): Promise<AgentSnapshotPayload[]>;
-  workspaceLastUserMessageTimes(): Promise<ReadonlyMap<string, string>>;
+  listAgentPayloads(workspaceIds?: Iterable<string>): Promise<AgentSnapshotPayload[]>;
+  workspaceLastUserMessageTimes(
+    workspaceIds?: Iterable<string>,
+  ): Promise<ReadonlyMap<string, string>>;
   listProviderSubagentActivity(): Promise<ProviderSubagentWorkspaceActivity[]>;
   listTerminalActivityContributions(): Promise<
     Array<{ cwd: string; workspaceId?: string; activity: TerminalActivity | null }>
@@ -217,6 +220,7 @@ export class WorkspaceDirectory {
     includeGitData: boolean;
     workspaceIds?: Iterable<string>;
   }): Promise<Map<string, WorkspaceDescriptorPayload>> {
+    const requestedIds = options.workspaceIds ? new Set(options.workspaceIds) : undefined;
     const [
       agents,
       lastUserMessageTimes,
@@ -225,10 +229,15 @@ export class WorkspaceDirectory {
       persistedProjects,
       terminalContributions,
     ] = await Promise.all([
-      this.deps.listAgentPayloads(),
-      this.deps.workspaceLastUserMessageTimes(),
+      this.deps.listAgentPayloads(requestedIds),
+      this.deps.workspaceLastUserMessageTimes(requestedIds),
       this.deps.listProviderSubagentActivity(),
-      this.deps.workspaceRegistry.list(),
+      requestedIds
+        ? Promise.all(Array.from(requestedIds, (id) => this.deps.workspaceRegistry.get(id))).then(
+            (records) =>
+              records.filter((record): record is PersistedWorkspaceRecord => record !== null),
+          )
+        : this.deps.workspaceRegistry.listActive(),
       this.deps.projectRegistry.list(),
       this.deps.listTerminalActivityContributions(),
     ]);
@@ -240,7 +249,7 @@ export class WorkspaceDirectory {
     );
     const activeRecords = activeWorkspaceRecords(persistedWorkspaces, persistedProjects);
     const descriptorsByWorkspaceId = new Map<string, WorkspaceDescriptorPayload>();
-    const workspaceIds = options.workspaceIds ? new Set(options.workspaceIds) : null;
+    const workspaceIds = requestedIds ? new Set(requestedIds) : null;
     const activeWorkspaceIds = new Set(activeRecords.map((workspace) => workspace.workspaceId));
     const includedWorkspaces = activeRecords.filter(
       (workspace) => !workspaceIds || workspaceIds.has(workspace.workspaceId),
@@ -267,8 +276,12 @@ export class WorkspaceDirectory {
       });
     }
 
+    // Background agents report to their creator; they never move the workspace's status.
     const activeAgents = agents.filter(
-      (agent) => !agent.archivedAt && this.deps.isProviderVisibleToClient(agent.provider),
+      (agent) =>
+        !agent.archivedAt &&
+        !agent.background &&
+        this.deps.isProviderVisibleToClient(agent.provider),
     );
     this.applyAgentBucketContributions({
       activeAgents,
@@ -379,7 +392,7 @@ export class WorkspaceDirectory {
         continue;
       }
       const isWorkspaceRoot = workspaceAgent.id === agent.id;
-      if (!isWorkspaceRoot && agent.status !== "running") {
+      if (!isWorkspaceRoot && agent.status !== "running" && !agent.backgroundWork?.count) {
         continue;
       }
       const bucket = isWorkspaceRoot
@@ -388,6 +401,7 @@ export class WorkspaceDirectory {
             pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
             requiresAttention: agent.requiresAttention,
             attentionReason: agent.attentionReason ?? null,
+            backgroundWork: agent.backgroundWork,
           })
         : "running";
 
@@ -537,6 +551,7 @@ export class WorkspaceDirectory {
           pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
           requiresAttention: agent.requiresAttention,
           attentionReason: agent.attentionReason ?? null,
+          backgroundWork: agent.backgroundWork,
         });
         return derived === winningBucket;
       })
@@ -566,7 +581,7 @@ export class WorkspaceDirectory {
     includeBackground?: boolean;
   }): Promise<WorkspaceProjectDescriptor[]> {
     const [persistedWorkspaces, persistedProjects] = await Promise.all([
-      this.deps.workspaceRegistry.list(),
+      this.deps.workspaceRegistry.listActive(),
       this.deps.projectRegistry.list(),
     ]);
     // A project whose only workspaces are hidden reads as empty to that caller.
@@ -597,7 +612,7 @@ export class WorkspaceDirectory {
     Pick<WorkspaceDescriptorPayload, "id" | "workspaceDirectory" | "workspaceKind">[]
   > {
     const [workspaces, projects] = await Promise.all([
-      this.deps.workspaceRegistry.list(),
+      this.deps.workspaceRegistry.listActive(),
       this.deps.projectRegistry.list(),
     ]);
     return activeWorkspaceRecords(workspaces, projects).map((workspace) => ({
diff --git a/packages/server/src/server/workspace-git-service.observation.integration.test.ts b/packages/server/src/server/workspace-git-service.observation.integration.test.ts
index c8d97390ed..8480d0604d 100644
--- a/packages/server/src/server/workspace-git-service.observation.integration.test.ts
+++ b/packages/server/src/server/workspace-git-service.observation.integration.test.ts
@@ -1,3 +1,10 @@
+import { flushGitCommandTrace } from "../utils/git-command-trace.js";
+import {
+  runWithGitCommandPriority,
+  startGitCommandMetrics,
+  stopGitCommandMetrics,
+  waitForGitCommandMetricsIdle,
+} from "../utils/run-git-command.js";
 import { createWorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -5,8 +12,11 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import pino from "pino";
 import { afterEach, expect, test, vi } from "vitest";
-import type { CheckoutSnapshotFacts, CheckoutStatusGit } from "../utils/checkout-git.js";
-import { CheckoutDiffManager } from "./checkout-diff-manager.js";
+import {
+  getCheckoutStatus as readCheckoutStatus,
+  type CheckoutSnapshotFacts,
+  type CheckoutStatusGit,
+} from "../utils/checkout-git.js";
 import { createFileObserver } from "./file-observer/index.js";
 import { WorkspaceGitServiceImpl } from "./workspace-git-service.js";
 import type { FileChange, FileObserver, SubscribeToFileChanges } from "./file-observer/index.js";
@@ -59,6 +69,49 @@ afterEach(async () => {
   }
 });
 
+test.each([false, true])(
+  "disposal waits for an admitted Git refresh after observation ends (unsubscribed: %s)",
+  async (unsubscribeBeforeDisposal) => {
+    const artifacts = path.resolve(".artifacts");
+    mkdirSync(artifacts, { recursive: true });
+    const root = realpathSync(mkdtempSync(path.join(artifacts, "git-refresh-shutdown-")));
+    execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+    const entered = Promise.withResolvers<void>();
+    const release = Promise.withResolvers<void>();
+    const service = new WorkspaceGitServiceImpl({
+      logger: pino({ enabled: false }),
+      paseoHome: path.join(root, "home"),
+      deps: {
+        getCheckoutStatus: async (...args) => {
+          entered.resolve();
+          await release.promise;
+          return readCheckoutStatus(...args);
+        },
+      },
+    });
+    const subscription = service.registerWorkspace({ cwd: root }, () => {});
+    try {
+      await entered.promise;
+      if (unsubscribeBeforeDisposal) subscription.unsubscribe();
+      let disposed = false;
+      const closing = service.dispose().then(() => {
+        disposed = true;
+        return undefined;
+      });
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      expect(disposed).toBe(false);
+      release.resolve();
+      await closing;
+      expect(disposed).toBe(true);
+    } finally {
+      release.resolve();
+      subscription.unsubscribe();
+      await service.dispose();
+      rmSync(root, { recursive: true, force: true });
+    }
+  },
+);
+
 test("a fresh checkout read makes a newly initialized repository available to cached readers", async () => {
   const root = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-checkout-init-")));
   const repo = path.join(root, "repo");
@@ -202,24 +255,15 @@ test("recursive observation updates tracked state and prunes ignored storms", as
   });
   const workspaceRuntimeStore = createWorkspaceRuntimeStore();
   service.onSnapshotUpdated((snapshot) => workspaceRuntimeStore.set(snapshot));
-  const diffManager = new CheckoutDiffManager({
-    workspaceRuntimeStore: workspaceRuntimeStore,
-    logger: createLogger(),
-    paseoHome: path.join(tempDir, "paseo-home"),
-    workspaceGitService: service,
-  });
+
   const summaryListener = vi.fn();
   const diffListener = vi.fn();
   const summarySubscription = service.registerWorkspace({ cwd: repoDir }, summaryListener);
-  const diffSubscription = await diffManager.subscribe(
-    { cwd: repoDir, compare: { mode: "uncommitted" } },
-    diffListener,
-  );
+  const diffSubscription = await service.requestWorkingTreeWatch(repoDir, diffListener);
 
   cleanup.push(async () => {
     diffSubscription.unsubscribe();
     summarySubscription.unsubscribe();
-    diffManager.dispose();
     await service.dispose();
     expect(activeWatcherCount).toBe(0);
     rmSync(tempDir, { recursive: true, force: true });
@@ -236,6 +280,8 @@ test("recursive observation updates tracked state and prunes ignored storms", as
         }),
       ).toBe(2);
       expect(workspaceRuntimeStore.get(repoDir)).not.toBeNull();
+      // The initial read, then the checkout read that follows watcher coverage.
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
       expect(service.getMetrics()).toMatchObject({
         workspaceObservationSetupInFlightCount: 0,
         workspaceRefreshInFlightCount: 0,
@@ -264,6 +310,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
   getCheckoutShortstat.mockClear();
   getCheckoutWorktreeState.mockClear();
   getCheckoutDiff.mockClear();
+  diffListener.mockClear();
   runGitCommand.mockClear();
   deliveredEvents.length = 0;
 
@@ -296,18 +343,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: repoDir,
-        files: [
-          {
-            path: "src/tracked.txt",
-            additions: 2,
-            deletions: 0,
-            status: "modified",
-          },
-        ],
-        error: null,
-      });
+      expect(diffListener).toHaveBeenCalled();
       expect(service.getMetrics().workspaceRefreshQueuedCount).toBe(0);
     },
     { timeout: 5_000 },
@@ -323,11 +359,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith(
-        expect.objectContaining({
-          files: [expect.objectContaining({ additions: 3 })],
-        }),
-      );
+      expect(diffListener).toHaveBeenCalled();
       expect(service.getMetrics()).toMatchObject({
         workspaceRefreshInFlightCount: 0,
         workspaceRefreshQueuedCount: 0,
@@ -361,18 +393,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: repoDir,
-        files: [
-          {
-            path: "build/tracked.txt",
-            additions: 2,
-            deletions: 0,
-            status: "modified",
-          },
-        ],
-        error: null,
-      });
+      expect(diffListener).toHaveBeenCalled();
       expect(service.getMetrics()).toMatchObject({
         workspaceRefreshInFlightCount: 0,
         workspaceRefreshQueuedCount: 0,
@@ -386,6 +407,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
   getCheckoutShortstat.mockClear();
   getCheckoutWorktreeState.mockClear();
   getCheckoutDiff.mockClear();
+  diffListener.mockClear();
   runGitCommand.mockClear();
   summaryListener.mockClear();
   diffListener.mockClear();
@@ -401,18 +423,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: repoDir,
-        files: [
-          {
-            path: "build/tracked.txt",
-            additions: 4,
-            deletions: 0,
-            status: "modified",
-          },
-        ],
-        error: null,
-      });
+      expect(diffListener).toHaveBeenCalled();
       expect(service.getMetrics()).toMatchObject({
         workspaceRefreshInFlightCount: 0,
         workspaceRefreshQueuedCount: 0,
@@ -426,6 +437,7 @@ test("recursive observation updates tracked state and prunes ignored storms", as
   getCheckoutShortstat.mockClear();
   getCheckoutWorktreeState.mockClear();
   getCheckoutDiff.mockClear();
+  diffListener.mockClear();
   runGitCommand.mockClear();
 
   for (let index = 0; index < 100; index += 1) {
@@ -576,42 +588,54 @@ test("Git refresh, command tracing and 10,000 ignored alias events do no synchro
       await writeFile(join(worktree, 'ignored', 'noise'), 'noise');
       await symlink(worktree, alias, process.platform === 'win32' ? 'junction' : 'dir');
       const subscription = await service.requestWorkingTreeWatch(alias, () => { notifications++; });
-      const events = Array.from({ length: process.env.GIT_IO_TRACE ? 2 : 10000 }, (_, i) => ({ type: 'update', path: join(i % 2 ? alias : worktree, 'ignored', 'noise') }));
+      // The observer hashes and coalesces paths in a Map before delivery. Reuse
+      // two prepared strings instead of constructing 10,000 equal-valued strings.
+      const noisePaths = [join(worktree, 'ignored', 'noise'), join(alias, 'ignored', 'noise')];
+      const events = Array.from({ length: process.env.GIT_IO_TRACE ? 2 : 10000 }, (_, i) => ({ type: 'update', path: noisePaths[i % 2] }));
       let fsCalls = 0;
       const hook = createHook({ init(_id, type) { if (type.startsWith('FSREQ')) fsCalls++; } });
       // Collect repository setup and event-fixture garbage before measuring
       // the cold filter. Allocations made by the filter still count.
       global.gc();
       await tick();
-      // Unrelated callbacks must not consume the synchronous filter's budget.
+      await marker('FILTER_START');
+      // Schedule the control only after marker IO settles, so it cannot run
+      // and allocate garbage before the cold filter starts. No await may
+      // separate this scheduling from the synchronous measurement.
       const threadCpuUsage = Reflect.get(process, 'threadCpuUsage');
+      let unrelatedWorkStarted = false;
       const unrelatedWork = tick().then(() => {
+        unrelatedWorkStarted = true;
         const started = threadCpuUsage();
         while (true) {
           const cpu = threadCpuUsage(started);
           if (cpu.user + cpu.system >= 80000) break;
         }
       });
-      await marker('FILTER_START');
+      assert.equal(unrelatedWorkStarted, false, 'control work must not contaminate the cold filter');
       hook.enable();
       let blockingMs;
+      let elapsedMs;
+      let cpu;
       try {
         // This callback is synchronous: measure its own span, without waiting
         // for marker IO, loader messages or other event-loop callbacks.
         const startedAt = performance.now();
         const startedCpu = threadCpuUsage();
         callback(null, events);
-        const cpu = threadCpuUsage(startedCpu);
+        cpu = threadCpuUsage(startedCpu);
         // Cap coarse Windows CPU accounting by elapsed time; exclude descheduling.
-        blockingMs = Math.min(performance.now() - startedAt, (cpu.user + cpu.system) / 1000);
+        elapsedMs = performance.now() - startedAt;
+        blockingMs = Math.min(elapsedMs, (cpu.user + cpu.system) / 1000);
       } finally {
         hook.disable();
         await marker('FILTER_END');
       }
       await unrelatedWork;
+      assert.equal(unrelatedWorkStarted, true, 'control work must run outside the filter span');
       assert.equal(fsCalls, 0, "filesystem calls");
       assert.equal(notifications, 0, "ignored event notification");
-      assert.ok(blockingMs < 20, 'blocking filter work: ' + blockingMs);
+      assert.ok(blockingMs < 20, 'blocking filter work: ' + JSON.stringify({ blockingMs, elapsedMs, cpu }));
       console.log(JSON.stringify({ blockingMs, fsCalls }));
       // Alias identity remains useful after deletion: no per-event realpath can recover this file.
       callback(null, [{ type: 'delete', path: join(worktree, 'tracked.txt') }]);
@@ -724,3 +748,274 @@ test("Git event identity retains a symlink's literal target before canonicalizin
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test.skipIf(process.platform !== "linux")(
+  "missing folders stop degraded Git polling and explicit refreshes, then recover",
+  async () => {
+    const artifacts = path.resolve(".artifacts");
+    mkdirSync(artifacts, { recursive: true });
+    const root = mkdtempSync(path.join(artifacts, "workspace-git-missing-"));
+    const cwd = path.join(root, "repo");
+    const initializeRepo = (branch: string) => {
+      mkdirSync(cwd);
+      execFileSync("git", ["init", "-b", branch], { cwd, stdio: "pipe" });
+      writeFileSync(path.join(cwd, "README.md"), "fixture\n");
+      execFileSync("git", ["add", "."], { cwd, stdio: "pipe" });
+      execFileSync(
+        "git",
+        [
+          "-c",
+          "user.name=Test",
+          "-c",
+          "user.email=test@example.invalid",
+          "-c",
+          "commit.gpgsign=false",
+          "commit",
+          "-m",
+          "fixture",
+        ],
+        { cwd, stdio: "pipe" },
+      );
+    };
+    initializeRepo("main");
+    // Exceed the real Linux observer's directory limit to enter degraded polling.
+    // No watcher errors or Git responses are injected.
+    for (let index = 0; index < 5100; index++) {
+      mkdirSync(path.join(cwd, `generated-${index}`));
+    }
+    const trace = path.join(root, "git.jsonl");
+    writeFileSync(trace, "");
+    const previousTrace = process.env.PASEO_GIT_TRACE_FILE;
+    process.env.PASEO_GIT_TRACE_FILE = trace;
+    let degraded = false;
+    let suspended = false;
+    const logger = pino(
+      { level: "warn" },
+      {
+        write(line) {
+          const message = JSON.parse(line).msg;
+          if (message === "Failed to start working tree watcher; using degraded polling")
+            degraded = true;
+          if (
+            message ===
+            "Workspace folder no longer exists; suspended git observation until it is back"
+          )
+            suspended = true;
+        },
+      },
+    );
+    const service = new WorkspaceGitServiceImpl({ logger, paseoHome: path.join(root, "home") });
+    const subscription = service.registerWorkspace({ cwd }, () => {});
+    const commandCount = async () => {
+      await flushGitCommandTrace();
+      return readFileSync(trace, "utf8").trim().split("\n").filter(Boolean).length;
+    };
+    try {
+      await expect
+        .poll(
+          () => {
+            const metrics = service.getMetrics();
+            // Metadata observation writes a canary after the working tree degrades.
+            return (
+              degraded &&
+              metrics.workspaceRefreshInFlightCount === 0 &&
+              metrics.workspaceObservationSetupInFlightCount === 0
+            );
+          },
+          { timeout: 15_000 },
+        )
+        .toBe(true);
+      rmSync(cwd, { recursive: true, force: true });
+      await expect.poll(() => suspended, { timeout: 15_000 }).toBe(true);
+      await expect.poll(() => service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
+      const commandsWhileMissing = await commandCount();
+      await service.getSnapshot(cwd, {
+        force: true,
+        includeForge: false,
+        reason: "refresh-button",
+      });
+      await service.refresh(cwd);
+      expect(await commandCount()).toBe(commandsWhileMissing);
+      await new Promise((resolve) => setTimeout(resolve, 16_000));
+      expect(await commandCount()).toBe(commandsWhileMissing);
+
+      initializeRepo("restored");
+      const snapshot = await service.getSnapshot(cwd, {
+        force: true,
+        includeForge: false,
+        reason: "refresh-button",
+      });
+      expect(snapshot.git).toMatchObject({ isGit: true, currentBranch: "restored" });
+      await expect
+        .poll(() => service.getMetrics(), { timeout: 15_000 })
+        .toMatchObject({
+          repositoryWorkspaceLinkCount: 1,
+          workspaceObservationSetupInFlightCount: 0,
+        });
+    } finally {
+      subscription.unsubscribe();
+      await service.dispose();
+      // The diagnostic sink outlives Git commands and owns writes into this fixture.
+      await flushGitCommandTrace();
+      if (previousTrace === undefined) delete process.env.PASEO_GIT_TRACE_FILE;
+      else process.env.PASEO_GIT_TRACE_FILE = previousTrace;
+      rmSync(root, { recursive: true, force: true });
+    }
+  },
+  60_000,
+);
+
+test("observation-driven refreshes run their Git work in the background lane", async () => {
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-git-priority-")));
+  const repo = path.join(root, "repo");
+  mkdirSync(repo);
+  const git = (...args: string[]) =>
+    execFileSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "pipe" });
+  git("init", "-b", "main");
+  git("config", "user.email", "test@example.com");
+  git("config", "user.name", "Test");
+  writeFileSync(path.join(repo, "README.md"), "base\n");
+  git("add", ".");
+  git("commit", "-m", "base");
+  const service = new WorkspaceGitServiceImpl({
+    logger: pino({ enabled: false }),
+    paseoHome: path.join(root, "home"),
+  });
+  const heads: Array<string | null> = [];
+  const subscription = service.registerWorkspace({ cwd: repo }, (snapshot) => {
+    heads.push(snapshot.git.currentBranch);
+  });
+  cleanup.push(async () => {
+    subscription.unsubscribe();
+    await service.dispose();
+    rmSync(root, { recursive: true, force: true });
+  });
+  // Registration, observation setup and the first refresh settle before the
+  // measured change.
+  startGitCommandMetrics();
+  await service.getSnapshot(repo, { includeForge: false });
+  await waitForGitCommandMetricsIdle({ quietMs: 500, timeoutMs: 10_000 });
+  stopGitCommandMetrics();
+
+  startGitCommandMetrics();
+  const deliveredBefore = heads.length;
+  git("switch", "-c", "feature");
+  await expect.poll(() => heads.slice(deliveredBefore), { timeout: 10_000 }).toContain("feature");
+  await waitForGitCommandMetricsIdle({ quietMs: 300, timeoutMs: 10_000 });
+  const observed = stopGitCommandMetrics().submissions;
+  expect(observed.length).toBeGreaterThan(0);
+  expect(new Set(observed.map((command) => command.priority))).toEqual(new Set(["background"]));
+
+  startGitCommandMetrics();
+  await service.getSnapshot(repo, { force: true, reason: "test-demand", includeForge: false });
+  await service.getCheckout(repo, { priority: "background" });
+  await waitForGitCommandMetricsIdle({ quietMs: 0, timeoutMs: 10_000 });
+  const demand = stopGitCommandMetrics().submissions;
+  const checkoutStart = demand.findIndex((command) => command.priority === "background");
+  expect(checkoutStart).toBeGreaterThan(0);
+  expect(new Set(demand.slice(0, checkoutStart).map((command) => command.priority))).toEqual(
+    new Set(["normal"]),
+  );
+  expect(new Set(demand.slice(checkoutStart).map((command) => command.priority))).toEqual(
+    new Set(["background"]),
+  );
+
+  startGitCommandMetrics();
+  await runWithGitCommandPriority("high", () =>
+    service.getSnapshot(repo, { force: true, reason: "test-user-action", includeForge: false }),
+  );
+  await waitForGitCommandMetricsIdle({ quietMs: 0, timeoutMs: 10_000 });
+  const userAction = stopGitCommandMetrics().submissions;
+  expect(userAction.length).toBeGreaterThan(0);
+  expect(new Set(userAction.map((command) => command.priority))).toEqual(new Set(["high"]));
+}, 30_000);
+
+test("an edit made before the working-tree watcher starts still reaches the cached snapshot", async () => {
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-git-coverage-gap-")));
+  const repo = path.join(root, "repo");
+  const trackedPath = path.join(repo, "src", "tracked.txt");
+  mkdirSync(path.dirname(trackedPath), { recursive: true });
+  const git = (...args: string[]) =>
+    execFileSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "pipe" });
+  git("init", "-b", "main");
+  git("config", "user.email", "test@example.com");
+  git("config", "user.name", "Test");
+  writeFileSync(trackedPath, "base\n");
+  git("add", ".");
+  git("commit", "-m", "base");
+  const observer = createFileObserver();
+  const workingTreeWatchGate = Promise.withResolvers<void>();
+  const service = new WorkspaceGitServiceImpl({
+    logger: pino({ enabled: false }),
+    paseoHome: path.join(root, "home"),
+    deps: {
+      subscribe: async (directory, callback, options) => {
+        if (directory === repo) await workingTreeWatchGate.promise;
+        return observer.subscribe(directory, callback, options);
+      },
+    },
+  });
+  const subscription = service.registerWorkspace({ cwd: repo }, () => {});
+  cleanup.push(async () => {
+    workingTreeWatchGate.resolve();
+    subscription.unsubscribe();
+    await service.dispose();
+    await observer.close();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  expect((await service.getSnapshot(repo, { includeForge: false })).git.isDirty).toBe(false);
+  writeFileSync(trackedPath, "edited before the watcher started\n");
+  workingTreeWatchGate.resolve();
+
+  await expect
+    .poll(async () => (await service.getSnapshot(repo, { includeForge: false })).git.isDirty, {
+      timeout: 10_000,
+    })
+    .toBe(true);
+}, 30_000);
+
+test("a branch switch made before the Git metadata watcher starts still reaches the cached snapshot", async () => {
+  const root = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-git-metadata-gap-")));
+  const repo = path.join(root, "repo");
+  mkdirSync(repo);
+  const git = (...args: string[]) =>
+    execFileSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "pipe" });
+  git("init", "-b", "main");
+  git("config", "user.email", "test@example.com");
+  git("config", "user.name", "Test");
+  writeFileSync(path.join(repo, "README.md"), "base\n");
+  git("add", ".");
+  git("commit", "-m", "base");
+  const observer = createFileObserver();
+  const metadataWatchGate = Promise.withResolvers<void>();
+  const service = new WorkspaceGitServiceImpl({
+    logger: pino({ enabled: false }),
+    paseoHome: path.join(root, "home"),
+    deps: {
+      subscribe: async (directory, callback, options) => {
+        if (directory !== repo) await metadataWatchGate.promise;
+        return observer.subscribe(directory, callback, options);
+      },
+    },
+  });
+  const subscription = service.registerWorkspace({ cwd: repo }, () => {});
+  cleanup.push(async () => {
+    metadataWatchGate.resolve();
+    subscription.unsubscribe();
+    await service.dispose();
+    await observer.close();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  expect((await service.getSnapshot(repo, { includeForge: false })).git.currentBranch).toBe("main");
+  git("switch", "-c", "feature");
+  metadataWatchGate.resolve();
+
+  await expect
+    .poll(
+      async () => (await service.getSnapshot(repo, { includeForge: false })).git.currentBranch,
+      { timeout: 10_000 },
+    )
+    .toBe("feature");
+}, 30_000);
diff --git a/packages/server/src/server/workspace-git-service.observation.test.ts b/packages/server/src/server/workspace-git-service.observation.test.ts
index ab93558793..c73e2de271 100644
--- a/packages/server/src/server/workspace-git-service.observation.test.ts
+++ b/packages/server/src/server/workspace-git-service.observation.test.ts
@@ -4,7 +4,6 @@ import { pathToFileURL } from "node:url";
 import type pino from "pino";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import type { CheckoutSnapshotFacts, CheckoutStatusGit } from "../utils/checkout-git.js";
-import { CheckoutDiffManager } from "./checkout-diff-manager.js";
 import type { FileObserver } from "./file-observer/index.js";
 import { WorkspaceGitServiceImpl } from "./workspace-git-service.js";
 
@@ -193,6 +192,8 @@ async function driveWatchRecoveryLadder(
   }
 }
 
+// Registering a workspace reads the checkout twice: once at start and once
+// when observation setup establishes watcher coverage.
 function createService(
   watcher: ReturnType<typeof createWatcherHarness>,
   overrides?: Record<string, unknown>,
@@ -244,6 +245,7 @@ function createService(
         filterEvents: (events) => events,
         verify: vi.fn(async () => {}),
       })),
+      workspaceFolderExists: vi.fn(async () => true),
       ...overrides,
     } as never,
   });
@@ -391,8 +393,9 @@ describe("WorkspaceGitService checkout observation", () => {
       expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
 
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
-    expect(getCheckoutStatus).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+    // The initial read, then one checkout read once the watcher covers the tree.
+    expect(getCheckoutStatus).toHaveBeenCalledTimes(2);
     expect(runGitCommand).toHaveBeenCalledTimes(2);
     expect(watcher.records.filter((record) => record.directory === REPO_CWD)).toHaveLength(1);
     expect(watcher.records.filter((record) => record.directory === GIT_DIR)).toHaveLength(1);
@@ -427,41 +430,30 @@ describe("WorkspaceGitService checkout observation", () => {
     service.dispose();
   });
 
-  test("a tracked edit refreshes summary and active uncommitted diff without structural or forge work", async () => {
+  test("a tracked edit refreshes summary and notifies worktree consumers without structural or forge work", async () => {
     const watcher = createWatcherHarness();
     const getCheckoutSnapshotFacts = vi.fn(async (cwd: string) => createCheckoutFacts(cwd));
     let diffStat = { additions: 1, deletions: 0 };
-    let diffFile = { path: "tracked.txt", additions: 1, deletions: 0, status: "modified" };
     const getCheckoutStatus = vi.fn(async (cwd: string) =>
       createCheckoutStatus(cwd, { isDirty: true }),
     );
     const getCheckoutShortstat = vi.fn(async () => diffStat);
     const getPullRequestStatus = vi.fn();
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [diffFile] }));
     const service = createService(watcher, {
       getCheckoutSnapshotFacts,
       getCheckoutStatus,
       getCheckoutShortstat,
       getPullRequestStatus,
-      getCheckoutDiff,
     });
     const workspaceRuntimeStore = createWorkspaceRuntimeStore();
     service.onSnapshotUpdated((snapshot) => workspaceRuntimeStore.set(snapshot));
-    const diffManager = new CheckoutDiffManager({
-      workspaceRuntimeStore: workspaceRuntimeStore,
-      logger: createLogger(),
-      paseoHome: "/tmp/paseo-home",
-      workspaceGitService: service,
-    });
+
     const summaryListener = vi.fn();
     const diffListener = vi.fn();
 
     await service.getSnapshot(REPO_CWD);
     const summarySubscription = service.registerWorkspace({ cwd: REPO_CWD }, summaryListener);
-    const diffSubscription = await diffManager.subscribe(
-      { cwd: REPO_CWD, compare: { mode: "uncommitted" } },
-      diffListener,
-    );
+    const diffSubscription = await service.requestWorkingTreeWatch(REPO_CWD, diffListener);
     await vi.waitFor(() => {
       expect(watcher.subscribe).toHaveBeenCalledWith(
         REPO_CWD,
@@ -474,7 +466,6 @@ describe("WorkspaceGitService checkout observation", () => {
     });
 
     diffStat = { additions: 4, deletions: 2 };
-    diffFile = { path: "tracked.txt", additions: 4, deletions: 2, status: "modified" };
     watcher.records[0]?.callback(null, [
       { path: path.join(REPO_CWD, "tracked.txt"), type: "update" },
     ]);
@@ -488,20 +479,15 @@ describe("WorkspaceGitService checkout observation", () => {
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: REPO_CWD,
-        files: [{ path: "tracked.txt", additions: 4, deletions: 2, status: "modified" }],
-        error: null,
-      });
+      expect(diffListener).toHaveBeenCalledTimes(1);
     });
     await flushPromises();
 
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
     expect(getPullRequestStatus).not.toHaveBeenCalled();
 
     diffSubscription.unsubscribe();
     summarySubscription.unsubscribe();
-    diffManager.dispose();
     service.dispose();
   });
 
@@ -569,7 +555,7 @@ describe("WorkspaceGitService checkout observation", () => {
       ?.callback(null, [{ path: path.join(GIT_DIR, "packed-refs"), type: "update" }]);
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
     });
 
     expect(listener).toHaveBeenCalledTimes(1);
@@ -639,7 +625,7 @@ describe("WorkspaceGitService checkout observation", () => {
       expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(1);
     });
 
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
     expect(listener).toHaveBeenCalledTimes(1);
 
     subscription.unsubscribe();
@@ -695,7 +681,7 @@ describe("WorkspaceGitService checkout observation", () => {
     await flushPromises();
     await vi.advanceTimersByTimeAsync(1_000);
 
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
     expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
 
     subscription.unsubscribe();
@@ -751,7 +737,7 @@ describe("WorkspaceGitService checkout observation", () => {
       });
       await vi.advanceTimersByTimeAsync(1_000);
       await vi.waitFor(() => {
-        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
       });
 
       subscription.unsubscribe();
@@ -802,72 +788,86 @@ describe("WorkspaceGitService checkout observation", () => {
     });
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
+    });
+    expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
+
+    subscription.unsubscribe();
+    service.dispose();
+  });
+
+  test.each([0, 100])(
+    "known packed remote refs materialize narrowly while namespace directories are ignored (watch setup delay %i ms)",
+    async (setupDelayMs) => {
+      const watcher = createWatcherHarness();
+      let fetchStarted = false;
+      const getCheckoutSnapshotFacts = vi.fn(async (cwd: string) => ({
+        ...createCheckoutFacts(cwd),
+        currentBranch: "feature",
+        remoteUrl: REMOTE_URL,
+        resolvedBaseRef: "main",
+        comparisonBaseRef: "origin/main",
+      }));
+      const getCheckoutRefDerivedState = vi.fn(async (_cwd, facts, current) => ({
+        ...current,
+        upstreamStatus: facts.upstreamStatus,
+      }));
+      const service = createService(watcher, {
+        subscribe: async (...args: Parameters<typeof watcher.subscribe>) => {
+          if (args[0] === GIT_DIR && setupDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, setupDelayMs));
+          }
+          return watcher.subscribe(...args);
+        },
+        getCheckoutSnapshotFacts,
+        getCheckoutRefDerivedState,
+        hasOriginRemote: vi.fn(async () => true),
+        runGitFetch: vi.fn(async (_cwd, observer) => {
+          fetchStarted = true;
+          observer.onRefSnapshot("before");
+          observer.onRefSnapshot("after");
+          return {
+            changes: [],
+            nonRemoteRefsChanged: false,
+            remoteRefs: new Set(["origin/main", "origin/load/00001"]),
+            error: null,
+          };
+        }),
+      });
+      const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+      await vi.waitFor(() => {
+        // An idle fetch count also holds before observation setup starts.
+        expect(fetchStarted).toBe(true);
+        expect(service.getMetrics().fetchInFlightCount).toBe(0);
+        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      });
+
+      const repoWatcher = watcher.records.find((record) => record.directory === GIT_DIR)!;
+      expect(repoWatcher).toBeDefined();
+      repoWatcher.callback(null, [
+        { path: path.join(GIT_DIR, "refs", "remotes", "origin", "load"), type: "create" },
+        {
+          path: path.join(GIT_DIR, "refs", "remotes", "origin", "load", "00001"),
+          type: "create",
+        },
+      ]);
+      await vi.advanceTimersByTimeAsync(1_000);
       expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
-    });
-    expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
+      expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
 
-    subscription.unsubscribe();
-    service.dispose();
-  });
+      repoWatcher.callback(null, [
+        { path: path.join(GIT_DIR, "refs", "remotes", "origin", "main"), type: "create" },
+      ]);
+      await vi.advanceTimersByTimeAsync(1_000);
+      await vi.waitFor(() => {
+        expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(1);
+      });
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
 
-  test("known packed remote refs materialize narrowly while namespace directories are ignored", async () => {
-    const watcher = createWatcherHarness();
-    const getCheckoutSnapshotFacts = vi.fn(async (cwd: string) => ({
-      ...createCheckoutFacts(cwd),
-      currentBranch: "feature",
-      remoteUrl: REMOTE_URL,
-      resolvedBaseRef: "main",
-      comparisonBaseRef: "origin/main",
-    }));
-    const getCheckoutRefDerivedState = vi.fn(async (_cwd, facts, current) => ({
-      ...current,
-      upstreamStatus: facts.upstreamStatus,
-    }));
-    const service = createService(watcher, {
-      getCheckoutSnapshotFacts,
-      getCheckoutRefDerivedState,
-      hasOriginRemote: vi.fn(async () => true),
-      runGitFetch: vi.fn(async (_cwd, observer) => {
-        observer.onRefSnapshot("before");
-        observer.onRefSnapshot("after");
-        return {
-          changes: [],
-          nonRemoteRefsChanged: false,
-          remoteRefs: new Set(["origin/main", "origin/load/00001"]),
-          error: null,
-        };
-      }),
-    });
-    const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
-    await vi.waitFor(() => {
-      expect(service.getMetrics().fetchInFlightCount).toBe(0);
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
-    });
-
-    const repoWatcher = watcher.records.find((record) => record.directory === GIT_DIR);
-    repoWatcher?.callback(null, [
-      { path: path.join(GIT_DIR, "refs", "remotes", "origin", "load"), type: "create" },
-      {
-        path: path.join(GIT_DIR, "refs", "remotes", "origin", "load", "00001"),
-        type: "create",
-      },
-    ]);
-    await vi.advanceTimersByTimeAsync(1_000);
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
-    expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
-
-    repoWatcher?.callback(null, [
-      { path: path.join(GIT_DIR, "refs", "remotes", "origin", "main"), type: "create" },
-    ]);
-    await vi.advanceTimersByTimeAsync(1_000);
-    await vi.waitFor(() => {
-      expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(1);
-    });
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
-
-    subscription.unsubscribe();
-    service.dispose();
-  });
+      subscription.unsubscribe();
+      await service.dispose();
+    },
+  );
 
   test("a second remote-ref move during a narrow refresh queues a final calculation", async () => {
     const watcher = createWatcherHarness();
@@ -997,7 +997,7 @@ describe("WorkspaceGitService checkout observation", () => {
     });
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
     });
 
     subscription.unsubscribe();
@@ -1039,14 +1039,14 @@ describe("WorkspaceGitService checkout observation", () => {
       expect(service.getMetrics().fetchInFlightCount).toBe(0);
       expect(runGitFetch).toHaveBeenCalledTimes(1);
     });
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
     const repoWatcher = getWatcherRecordsForDirectory(watcher, GIT_DIR)[0]!;
     repoWatcher.callback(null, [
       { path: path.join(GIT_DIR, "refs", "remotes", "origin", "main"), type: "update" },
     ]);
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
     });
 
     subscription.unsubscribe();
@@ -1230,7 +1230,7 @@ describe("WorkspaceGitService checkout observation", () => {
     service.dispose();
   });
 
-  test("metadata-only changes refresh worktree summary and active uncommitted diff", async () => {
+  test("metadata-only changes refresh worktree summary and invalidate the uncommitted projection", async () => {
     const watcher = createWatcherHarness();
     let isDirty = true;
     let diffStat = { additions: 3, deletions: 1 };
@@ -1245,19 +1245,10 @@ describe("WorkspaceGitService checkout observation", () => {
     });
     const workspaceRuntimeStore = createWorkspaceRuntimeStore();
     service.onSnapshotUpdated((snapshot) => workspaceRuntimeStore.set(snapshot));
-    const diffManager = new CheckoutDiffManager({
-      workspaceRuntimeStore: workspaceRuntimeStore,
-      logger: createLogger(),
-      paseoHome: "/tmp/paseo-home",
-      workspaceGitService: service,
-    });
+
     const summaryListener = vi.fn();
-    const diffListener = vi.fn();
     const summarySubscription = service.registerWorkspace({ cwd: REPO_CWD }, summaryListener);
-    const diffSubscription = await diffManager.subscribe(
-      { cwd: REPO_CWD, compare: { mode: "uncommitted" } },
-      diffListener,
-    );
+    await service.getCheckoutDiff(REPO_CWD, { mode: "uncommitted" });
 
     await vi.waitFor(() => {
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
@@ -1280,16 +1271,13 @@ describe("WorkspaceGitService checkout observation", () => {
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: REPO_CWD,
-        files: [],
-        error: null,
-      });
     });
 
-    diffSubscription.unsubscribe();
+    expect(await service.getCheckoutDiff(REPO_CWD, { mode: "uncommitted" })).toMatchObject({
+      structured: [],
+    });
+    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
     summarySubscription.unsubscribe();
-    diffManager.dispose();
     service.dispose();
   });
 
@@ -1303,20 +1291,14 @@ describe("WorkspaceGitService checkout observation", () => {
     const service = createService(watcher, { getCheckoutDiff, getCheckoutWorktreeState });
     const workspaceRuntimeStore = createWorkspaceRuntimeStore();
     service.onSnapshotUpdated((snapshot) => workspaceRuntimeStore.set(snapshot));
-    const diffManager = new CheckoutDiffManager({
-      workspaceRuntimeStore: workspaceRuntimeStore,
-      logger: createLogger(),
-      paseoHome: "/tmp/paseo-home",
-      workspaceGitService: service,
-    });
-    const diffSubscription = await diffManager.subscribe(
-      { cwd: REPO_CWD, compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
+
+    const subscription = service.registerWorkspace({ cwd: REPO_CWD }, () => {});
+    await service.getCheckoutDiff(REPO_CWD, { mode: "base", baseRef: "main" });
 
     await vi.waitFor(() => {
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
     });
+    await service.getCheckoutDiff(REPO_CWD, { mode: "base", baseRef: "main" });
     expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
 
     watcher.records
@@ -1324,6 +1306,7 @@ describe("WorkspaceGitService checkout observation", () => {
       ?.callback(null, [{ path: path.join(REPO_CWD, "tracked.txt"), type: "update" }]);
     await vi.advanceTimersByTimeAsync(1_000);
     await flushPromises();
+    await service.getCheckoutDiff(REPO_CWD, { mode: "base", baseRef: "main" });
     expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
 
     watcher.records
@@ -1331,12 +1314,10 @@ describe("WorkspaceGitService checkout observation", () => {
       ?.callback(null, [{ path: path.join(GIT_DIR, "packed-refs"), type: "update" }]);
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.advanceTimersByTimeAsync(150);
-    await vi.waitFor(() => {
-      expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-    });
+    await service.getCheckoutDiff(REPO_CWD, { mode: "base", baseRef: "main" });
+    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
 
-    diffSubscription.unsubscribe();
-    diffManager.dispose();
+    subscription.unsubscribe();
     service.dispose();
   });
 
@@ -1629,7 +1610,8 @@ describe("WorkspaceGitService checkout observation", () => {
         expect.any(Function),
         expect.any(Object),
       );
-      expect(getCheckoutStatus).toHaveBeenCalledTimes(1);
+      // The initial read, then one checkout read once the watcher covers the tree.
+      expect(getCheckoutStatus).toHaveBeenCalledTimes(2);
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
       expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
@@ -1764,7 +1746,9 @@ describe("WorkspaceGitService checkout observation", () => {
     await vi.waitFor(() => {
       expect(workspaceRuntimeStore.get(REPO_CWD)).not.toBeNull();
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
+      expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
+    const statusCallsBeforeError = getCheckoutStatus.mock.calls.length;
     const checkoutWatcher = watcher.records.find((record) => record.directory === REPO_CWD);
     expect(checkoutWatcher).toBeDefined();
 
@@ -1773,10 +1757,10 @@ describe("WorkspaceGitService checkout observation", () => {
     expect(service.getMetrics().watcherErrorCallbackCount).toBe(1);
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutStatus).toHaveBeenCalledTimes(2);
+      expect(getCheckoutStatus).toHaveBeenCalledTimes(statusCallsBeforeError + 1);
     });
 
-    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+    expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
     expect(service.getMetrics().workspaceRefreshQueuedCount).toBe(0);
 
     ignoredDirectories = "node_modules/\nbuild/\n";
@@ -2758,47 +2742,32 @@ describe("WorkspaceGitService checkout observation", () => {
     service.dispose();
   });
 
-  test("a working-tree watcher event refreshes summary and diff subscribers", async () => {
+  test("a working-tree watcher event refreshes summary and notifies worktree consumers", async () => {
     const watcher = createWatcherHarness();
     let isDirty = false;
     let diffStat = { additions: 0, deletions: 0 };
-    let diffFiles: Array<{
-      path: string;
-      additions: number;
-      deletions: number;
-      status: string;
-    }> = [];
     const getCheckoutStatus = vi.fn(async (cwd: string) => createCheckoutStatus(cwd, { isDirty }));
     const getCheckoutShortstat = vi.fn(async () => diffStat);
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: diffFiles }));
     const service = createService(watcher, {
       getCheckoutStatus,
       getCheckoutShortstat,
-      getCheckoutDiff,
     });
     const workspaceRuntimeStore = createWorkspaceRuntimeStore();
     service.onSnapshotUpdated((snapshot) => workspaceRuntimeStore.set(snapshot));
-    const diffManager = new CheckoutDiffManager({
-      workspaceRuntimeStore: workspaceRuntimeStore,
-      logger: createLogger(),
-      paseoHome: "/tmp/paseo-home",
-      workspaceGitService: service,
-    });
+
     const listener = vi.fn();
     const diffListener = vi.fn();
     const subscription = service.registerWorkspace({ cwd: REPO_CWD }, listener);
-    const diffSubscription = await diffManager.subscribe(
-      { cwd: REPO_CWD, compare: { mode: "uncommitted" } },
-      diffListener,
-    );
+    const diffSubscription = await service.requestWorkingTreeWatch(REPO_CWD, diffListener);
 
     await vi.waitFor(() => {
       expect(workspaceRuntimeStore.get(REPO_CWD)).not.toBeNull();
       expect(service.getMetrics().workspaceObservationSetupInFlightCount).toBe(0);
+      expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
+    const statusCallsBeforeEvent = getCheckoutStatus.mock.calls.length;
     isDirty = true;
     diffStat = { additions: 7, deletions: 3 };
-    diffFiles = [{ path: "tracked.txt", additions: 7, deletions: 3, status: "modified" }];
 
     getWatcherRecordsForDirectory(watcher, REPO_CWD)[0]?.callback(null, [
       { path: path.join(REPO_CWD, "tracked.txt"), type: "update" },
@@ -2813,17 +2782,12 @@ describe("WorkspaceGitService checkout observation", () => {
           }),
         }),
       );
-      expect(diffListener).toHaveBeenLastCalledWith({
-        cwd: REPO_CWD,
-        files: [{ path: "tracked.txt", additions: 7, deletions: 3, status: "modified" }],
-        error: null,
-      });
+      expect(diffListener).toHaveBeenCalledTimes(1);
     });
-    expect(getCheckoutStatus).toHaveBeenCalledTimes(2);
+    expect(getCheckoutStatus).toHaveBeenCalledTimes(statusCallsBeforeEvent + 1);
 
     diffSubscription.unsubscribe();
     subscription.unsubscribe();
-    diffManager.dispose();
     service.dispose();
   });
 });
diff --git a/packages/server/src/server/workspace-git-service.primitive.test.ts b/packages/server/src/server/workspace-git-service.primitive.test.ts
index 1b43026c7d..f9d4af8a9d 100644
--- a/packages/server/src/server/workspace-git-service.primitive.test.ts
+++ b/packages/server/src/server/workspace-git-service.primitive.test.ts
@@ -992,7 +992,9 @@ describe("WorkspaceGitServiceImpl primitive refresh entrypoint", () => {
     await flushPromises();
 
     await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(2));
-    expect(getCheckoutStatus).toHaveBeenCalledTimes(1);
+    // Setup itself does no snapshot read; once the watcher covers the tree, one
+    // checkout read catches changes made since the forced read.
+    await vi.waitFor(() => expect(getCheckoutStatus).toHaveBeenCalledTimes(2));
 
     subscription.unsubscribe();
     service.dispose();
diff --git a/packages/server/src/server/workspace-git-service.test.ts b/packages/server/src/server/workspace-git-service.test.ts
index 4e6acff9cd..9d91610cd8 100644
--- a/packages/server/src/server/workspace-git-service.test.ts
+++ b/packages/server/src/server/workspace-git-service.test.ts
@@ -1,5 +1,9 @@
 import { createWorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { existsSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path, { join } from "node:path";
 import type pino from "pino";
@@ -10,11 +14,14 @@ import type {
   PullRequestStatusResult,
 } from "../utils/checkout-git.js";
 import {
+  BACKGROUND_GIT_FETCH_INTERVAL_MS,
+  WORKSPACE_GIT_OBSERVATION_REENSURE_INTERVAL_MS,
   WORKSPACE_GIT_OBSERVATION_SETUP_CONCURRENCY,
   WORKSPACE_GIT_REFRESH_CONCURRENCY,
   WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS,
   WorkspaceGitServiceImpl,
   type WorkspaceGitRuntimeSnapshot,
+  workspaceFolderExists,
 } from "./workspace-git-service.js";
 
 const REPO_CWD = path.resolve("/tmp/repo");
@@ -23,6 +30,7 @@ function createLogger() {
   const logger = {
     child: () => logger,
     debug: vi.fn(),
+    info: vi.fn(),
     warn: vi.fn(),
   };
   return logger;
@@ -251,7 +259,7 @@ function createGitHubServiceStub(): ForgeService {
 interface CreateServiceTestOptions {
   subscribe?: ReturnType<typeof vi.fn>;
   getCheckoutStatus?: ReturnType<typeof vi.fn>;
-  getCheckoutSnapshotFacts?: ReturnType<typeof vi.fn>;
+  getCheckoutSnapshotFacts?: (cwd: string) => Promise<CheckoutSnapshotFacts>;
   getCheckoutShortstat?: ReturnType<typeof vi.fn>;
   getCheckoutWorktreeState?: ReturnType<typeof vi.fn>;
   getPullRequestStatus?: ReturnType<typeof vi.fn>;
@@ -261,6 +269,7 @@ interface CreateServiceTestOptions {
   runGitFetch?: ReturnType<typeof vi.fn>;
   runGitCommand?: ReturnType<typeof vi.fn>;
   getWorkspaceGitSelfHealPhaseMs?: (cwd: string) => number;
+  workspaceFolderExists?: (cwd: string) => Promise<boolean>;
   now?: () => Date;
 }
 
@@ -294,6 +303,7 @@ function buildDefaultTestServiceDeps() {
       signal: null,
     })),
     getWorkspaceGitSelfHealPhaseMs: vi.fn(() => 30_000),
+    workspaceFolderExists: vi.fn(async () => true),
     createWatcherLivenessCanary: vi.fn(() => ({
       path: "",
       filterEvents: (events) => events,
@@ -303,6 +313,8 @@ function buildDefaultTestServiceDeps() {
   };
 }
 
+// Registering a workspace reads the checkout twice: once at start and once
+// when observation setup establishes watcher coverage.
 function createService(options?: CreateServiceTestOptions) {
   const deps = { ...buildDefaultTestServiceDeps(), ...options };
   deps.getCheckoutWorktreeState =
@@ -324,6 +336,145 @@ function createService(options?: CreateServiceTestOptions) {
   });
 }
 
+type WatchCallback = (error: Error | null, events: Array<{ path: string; type: "update" }>) => void;
+
+interface FolderBackedGitOptions {
+  facts?: (cwd: string) => CheckoutSnapshotFacts;
+  unwatchableDirectories?: string[];
+  heldWatch?: { directory: string; release: Promise<void> };
+}
+
+function createFolderBackedGit(options?: FolderBackedGitOptions) {
+  const watchCallbacks = new Map<string, WatchCallback>();
+  const subscribe = vi.fn(async (directory: string, callback: WatchCallback) => {
+    if (!existsSync(directory) || options?.unwatchableDirectories?.includes(directory)) {
+      throw new Error(`Cannot watch ${directory}`);
+    }
+    if (options?.heldWatch?.directory === directory) {
+      await options.heldWatch.release;
+    }
+    watchCallbacks.set(directory, callback);
+    return createAsyncSubscription();
+  });
+  const getCheckoutSnapshotFacts = vi.fn(
+    async (cwd: string): Promise<CheckoutSnapshotFacts> =>
+      existsSync(cwd) ? (options?.facts ?? createCheckoutSnapshotFacts)(cwd) : { isGit: false },
+  );
+  const getCheckoutStatus = vi.fn(async (cwd: string) =>
+    existsSync(cwd) ? createCheckoutStatus(cwd) : ({ isGit: false } as const),
+  );
+  const getCheckoutShortstat = vi.fn(async (_cwd: string) => ({ additions: 1, deletions: 0 }));
+  const getCheckoutWorktreeState = vi.fn(async (_cwd: string) => ({
+    isDirty: false,
+    diffStat: { additions: 1, deletions: 0 },
+  }));
+  const runGitCommand = vi.fn(async (args: string[], runOptions: { cwd: string }) => ({
+    stdout: args[0] === "rev-parse" ? `${runOptions.cwd}\n` : "",
+    stderr: "",
+    truncated: false,
+    exitCode: 0,
+    signal: null,
+  }));
+  const runGitFetch = vi.fn(async (_cwd: string) => ({ changes: [], error: null }));
+  const callsIn = (fake: ReturnType<typeof vi.fn>, cwd: string) =>
+    fake.mock.calls.filter(([calledCwd]) => calledCwd === cwd).length;
+
+  return {
+    deps: {
+      subscribe,
+      getCheckoutSnapshotFacts,
+      getCheckoutStatus,
+      getCheckoutShortstat,
+      getCheckoutWorktreeState,
+      runGitCommand,
+      runGitFetch,
+      workspaceFolderExists: async (cwd: string) => existsSync(cwd),
+      now: () => new Date(),
+    },
+    watchCallbackFor(directory: string): WatchCallback {
+      const callback = watchCallbacks.get(directory);
+      if (!callback) {
+        throw new Error(`No watcher was started for ${directory}`);
+      }
+      return callback;
+    },
+    watchAttemptsFor: (directory: string) => callsIn(subscribe, directory),
+    pollsOf: (cwd: string) => callsIn(getCheckoutShortstat, cwd),
+    fetchesIn: (cwd: string) => callsIn(runGitFetch, cwd),
+    gitCommandsIn(cwd: string): number {
+      const cwdCommands = [
+        getCheckoutSnapshotFacts,
+        getCheckoutStatus,
+        getCheckoutShortstat,
+        getCheckoutWorktreeState,
+        runGitFetch,
+      ].reduce((count, fake) => count + callsIn(fake, cwd), 0);
+      const commandsRunInCwd = runGitCommand.mock.calls.filter(
+        ([, runOptions]) => runOptions.cwd === cwd,
+      ).length;
+      return cwdCommands + commandsRunInCwd;
+    },
+  };
+}
+
+function linkedWorktreeFacts(gitCommonDir: string) {
+  return (cwd: string): CheckoutSnapshotFacts => ({
+    ...createCheckoutSnapshotFacts(cwd),
+    absoluteGitDir: join(gitCommonDir, "worktrees", path.basename(cwd)),
+    gitCommonDir,
+  });
+}
+
+async function settle(assertion: () => void): Promise<void> {
+  // Observation setup resolves real filesystem paths even while the polling clock is frozen.
+  // Give that I/O wall-clock time without advancing the service's polling deadlines.
+  const deadline = performance.now() + 5_000;
+  while (true) {
+    try {
+      assertion();
+      return;
+    } catch (failure) {
+      if (performance.now() >= deadline) throw failure;
+    }
+    await delay(1);
+    await vi.advanceTimersByTimeAsync(0);
+  }
+}
+
+async function waitForRefreshesToSettle(service: WorkspaceGitServiceImpl): Promise<void> {
+  await settle(() => {
+    expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
+  });
+}
+
+async function waitForObservationToSettle(
+  service: WorkspaceGitServiceImpl,
+  repositoryWorkspaceLinkCount: number,
+): Promise<void> {
+  await settle(() => {
+    const metrics = service.getMetrics();
+    expect(metrics.repositoryWorkspaceLinkCount).toBe(repositoryWorkspaceLinkCount);
+    expect(metrics.workspaceObservationSetupInFlightCount).toBe(0);
+    expect(metrics.workspaceRefreshInFlightCount).toBe(0);
+  });
+}
+
+async function advanceThroughDegradedPolls(service: WorkspaceGitServiceImpl): Promise<void> {
+  for (const delayMs of [5_000, 10_000, 20_000, 40_000, 60_000, 60_000]) {
+    await vi.advanceTimersByTimeAsync(delayMs);
+    await waitForRefreshesToSettle(service);
+  }
+}
+
+async function advanceThroughWorkingTreeRecoveryAttempts(
+  service: WorkspaceGitServiceImpl,
+): Promise<void> {
+  for (const delayMs of [30_000, 60_000, 120_000]) {
+    await vi.advanceTimersByTimeAsync(delayMs);
+    await waitForRefreshesToSettle(service);
+  }
+}
+
 describe("WorkspaceGitServiceImpl", () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -617,6 +768,35 @@ describe("WorkspaceGitServiceImpl", () => {
     service.dispose();
   });
 
+  test("a refresh requested after a mutation waits for a new snapshot", async () => {
+    const gate = createDeferred<CheckoutStatusGit>();
+    let reads = 0;
+    const service = createService({
+      getCheckoutStatus: (cwd: string) => {
+        reads += 1;
+        return reads === 1
+          ? gate.promise
+          : Promise.resolve(createCheckoutStatus(cwd, { currentBranch: "new-base" }));
+      },
+    });
+    const first = service.getSnapshot(REPO_CWD, {
+      force: true,
+      includeForge: false,
+      reason: "before-mutation",
+    });
+    await vi.waitFor(() => expect(reads).toBe(1));
+    const after = service.getSnapshot(REPO_CWD, {
+      force: true,
+      includeForge: false,
+      reason: "after-mutation",
+      afterInFlight: true,
+    });
+    gate.resolve(createCheckoutStatus(REPO_CWD, { currentBranch: "old-base" }));
+    await first;
+    expect((await after).git.currentBranch).toBe("new-base");
+    service.dispose();
+  });
+
   test("bounds refresh generations and re-enqueues hot workspace successors fairly", async () => {
     const hotCwds = Array.from({ length: WORKSPACE_GIT_REFRESH_CONCURRENCY }, (_, index) =>
       path.resolve(`/tmp/hot-repo-${index}`),
@@ -956,6 +1136,18 @@ describe("WorkspaceGitServiceImpl", () => {
   });
 
   test("repo-level fetch intervals are shared for workspaces in the same repo", async () => {
+    // Keep the second workspace's observation setup behind its initial snapshot.
+    const secondCwd = join(REPO_CWD, "packages", "server");
+    const runGitCommand = vi.fn(async (_args, options) => {
+      if (options.cwd === secondCwd) await delay(250);
+      return {
+        stdout: `${REPO_CWD}\n`,
+        stderr: "",
+        truncated: false,
+        exitCode: 0,
+        signal: null,
+      };
+    });
     const firstFetch = createDeferred<void>();
     const runGitFetch = vi.fn(async () => {
       await firstFetch.promise;
@@ -977,6 +1169,7 @@ describe("WorkspaceGitServiceImpl", () => {
     const resolveAbsoluteGitDir = vi.fn(async () => join(REPO_CWD, ".git"));
 
     const service = createService({
+      runGitCommand,
       getCheckoutSnapshotFacts,
       getCheckoutRefDerivedState,
       resolveAbsoluteGitDir,
@@ -985,12 +1178,9 @@ describe("WorkspaceGitServiceImpl", () => {
     });
 
     const first = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
-    const second = service.registerWorkspace(
-      { cwd: join(REPO_CWD, "packages", "server") },
-      vi.fn(),
-    );
+    const second = service.registerWorkspace({ cwd: secondCwd }, vi.fn());
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
       expect(runGitFetch).toHaveBeenCalledTimes(1);
       expect(service.getMetrics().workspaceRefreshInFlightCount).toBe(0);
     });
@@ -999,11 +1189,13 @@ describe("WorkspaceGitServiceImpl", () => {
     expect(hasOriginRemote).toHaveBeenCalledTimes(0);
     expect(runGitFetch).toHaveBeenCalledTimes(1);
 
+    await waitForObservationToSettle(service, 2);
+
     firstFetch.resolve();
     await flushPromises();
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
       expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(2);
     });
 
@@ -1051,7 +1243,7 @@ describe("WorkspaceGitServiceImpl", () => {
     await vi.waitFor(() => {
       expect(runGitFetch).toHaveBeenCalledTimes(1);
       expect(service.getMetrics().fetchInFlightCount).toBe(0);
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
     });
     getCheckoutSnapshotFacts.mockClear();
 
@@ -1113,7 +1305,7 @@ describe("WorkspaceGitServiceImpl", () => {
     );
     await vi.waitFor(
       () => {
-        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
+        expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
         expect(service.getMetrics()).toMatchObject({
           repositoryWorkspaceLinkCount: 2,
           workspaceObservationSetupInFlightCount: 0,
@@ -1130,7 +1322,7 @@ describe("WorkspaceGitServiceImpl", () => {
     });
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(4);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(6);
     });
     expect(getCheckoutRefDerivedState).not.toHaveBeenCalled();
 
@@ -1170,7 +1362,7 @@ describe("WorkspaceGitServiceImpl", () => {
     const listener = vi.fn();
     const subscription = service.registerWorkspace({ cwd: REPO_CWD }, listener);
     await vi.waitFor(() => {
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(1);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
       expect(service.getMetrics().fetchInFlightCount).toBe(1);
     });
 
@@ -1182,8 +1374,10 @@ describe("WorkspaceGitServiceImpl", () => {
     await vi.advanceTimersByTimeAsync(1_000);
     await vi.waitFor(() => {
       expect(getCheckoutRefDerivedState).toHaveBeenCalledTimes(1);
-      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(2);
-      expect(getCheckoutShortstat).toHaveBeenCalledTimes(2);
+      expect(getCheckoutSnapshotFacts).toHaveBeenCalledTimes(3);
+      // Initial read, the checkout read once the watcher covers the tree,
+      // then the fallback.
+      expect(getCheckoutShortstat).toHaveBeenCalledTimes(3);
     });
     expect(listener.mock.lastCall?.[0].git.diffStat).toEqual({ additions: 2, deletions: 0 });
 
@@ -1411,6 +1605,241 @@ describe("WorkspaceGitServiceImpl", () => {
     service.dispose();
   });
 
+  test.each(["repository metadata", "working tree"])(
+    "recovers after a %s watcher subscription times out during setup",
+    async (kind) => {
+      const watchPath = kind === "repository metadata" ? join(REPO_CWD, ".git") : REPO_CWD;
+      let attempts = 0;
+      const subscribe = vi.fn(async (directory: string) => {
+        if (directory === watchPath && ++attempts === 1) {
+          return new Promise<ReturnType<typeof createAsyncSubscription>>(() => {});
+        }
+        return createAsyncSubscription();
+      });
+      const getCheckoutStatus = vi.fn(async (cwd: string) => createCheckoutStatus(cwd));
+      const service = createService({ subscribe, getCheckoutStatus });
+      const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+      try {
+        await settle(() => expect(attempts).toBe(1));
+        await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+        await waitForObservationToSettle(service, 1);
+        const readsBeforePoll = getCheckoutStatus.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(5_000);
+        await waitForRefreshesToSettle(service);
+        expect(getCheckoutStatus.mock.calls.length).toBeGreaterThan(readsBeforePoll);
+        await vi.advanceTimersByTimeAsync(24_999);
+        expect(attempts).toBe(1);
+        await vi.advanceTimersByTimeAsync(1);
+        await settle(() => expect(attempts).toBe(2));
+        // Recovery emits a debounced working-tree refresh before observation takes over.
+        await vi.advanceTimersByTimeAsync(1_000);
+        await waitForRefreshesToSettle(service);
+        const readsAfterRecovery = getCheckoutStatus.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(20_000);
+        await waitForRefreshesToSettle(service);
+        expect(getCheckoutStatus.mock.calls.length).toBe(readsAfterRecovery);
+      } finally {
+        subscription.unsubscribe();
+        await service.dispose();
+      }
+    },
+    15_000,
+  );
+
+  test.each(["repository metadata", "working tree"])(
+    "ignores expired %s watcher callbacks after recovery",
+    async (kind) => {
+      const watchPath = kind === "repository metadata" ? join(REPO_CWD, ".git") : REPO_CWD;
+      let attempts = 0;
+      const callbacks: Array<
+        (error: Error | null, events: Array<{ path: string; type: "update" }>) => void
+      > = [];
+      const recovered = createAsyncSubscription();
+      const subscribe = vi.fn(async (directory: string, callback: (typeof callbacks)[number]) => {
+        if (directory === watchPath) callbacks.push(callback);
+        if (directory === watchPath && ++attempts === 1) {
+          return new Promise<ReturnType<typeof createAsyncSubscription>>(() => {});
+        }
+        return directory === watchPath ? recovered : createAsyncSubscription();
+      });
+      const getCheckoutStatus = vi.fn(async (cwd: string) => createCheckoutStatus(cwd));
+      const service = createService({ subscribe, getCheckoutStatus });
+      const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+      try {
+        await settle(() => expect(attempts).toBe(1));
+        await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+        await waitForObservationToSettle(service, 1);
+        const readsBeforePoll = getCheckoutStatus.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(5_000);
+        await waitForRefreshesToSettle(service);
+        expect(getCheckoutStatus.mock.calls.length).toBeGreaterThan(readsBeforePoll);
+        await vi.advanceTimersByTimeAsync(24_999);
+        expect(attempts).toBe(1);
+        await vi.advanceTimersByTimeAsync(1);
+        await settle(() => expect(attempts).toBe(2));
+        // Recovery emits a debounced working-tree refresh before observation takes over.
+        await vi.advanceTimersByTimeAsync(1_000);
+        await waitForRefreshesToSettle(service);
+        const readsAfterRecovery = getCheckoutStatus.mock.calls.length;
+        callbacks[0]!(new Error("expired watcher stopped"), []);
+        callbacks[0]!(null, [{ path: join(watchPath, "stale.ts"), type: "update" }]);
+        expect(recovered.unsubscribe).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(20_000);
+        await waitForRefreshesToSettle(service);
+        expect(getCheckoutStatus.mock.calls.length).toBe(readsAfterRecovery);
+        expect(recovered.unsubscribe).not.toHaveBeenCalled();
+      } finally {
+        subscription.unsubscribe();
+        await service.dispose();
+      }
+    },
+    15_000,
+  );
+
+  test.each(["repository metadata", "working tree"])(
+    "refreshes changes missed before %s watcher recovery",
+    async (kind) => {
+      const watchPath = kind === "repository metadata" ? join(REPO_CWD, ".git") : REPO_CWD;
+      let attempts = 0;
+      let changed = false;
+      const subscribe = vi.fn(async (directory: string) => {
+        if (directory === watchPath && ++attempts === 1) {
+          return new Promise<ReturnType<typeof createAsyncSubscription>>(() => {});
+        }
+        return createAsyncSubscription();
+      });
+      const getCheckoutStatus = vi.fn(async (cwd: string) =>
+        createCheckoutStatus(cwd, {
+          isDirty: changed,
+          currentBranch: changed ? "feature" : "main",
+        }),
+      );
+      const service = createService({
+        subscribe,
+        getCheckoutStatus,
+        getCheckoutSnapshotFacts: async (cwd) => ({
+          ...createCheckoutSnapshotFacts(cwd),
+          currentBranch: changed ? "feature" : "main",
+        }),
+      });
+      const snapshots: WorkspaceGitRuntimeSnapshot[] = [];
+      service.onSnapshotUpdated((snapshot) => snapshots.push(snapshot));
+      const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+      try {
+        await settle(() => expect(attempts).toBe(1));
+        await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+        await waitForObservationToSettle(service, 1);
+        await vi.advanceTimersByTimeAsync(29_999);
+        await waitForRefreshesToSettle(service);
+        expect(snapshots.at(-1)?.git).toMatchObject({ currentBranch: "main", isDirty: false });
+        changed = true;
+        await vi.advanceTimersByTimeAsync(1);
+        await settle(() => expect(attempts).toBe(2));
+        await vi.advanceTimersByTimeAsync(1_000);
+        await waitForRefreshesToSettle(service);
+        expect(snapshots.at(-1)?.git).toMatchObject(
+          kind === "repository metadata" ? { currentBranch: "feature" } : { isDirty: true },
+        );
+        const readsAfterRecovery = getCheckoutStatus.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(20_000);
+        await waitForRefreshesToSettle(service);
+        expect(getCheckoutStatus.mock.calls.length).toBe(readsAfterRecovery);
+      } finally {
+        subscription.unsubscribe();
+        await service.dispose();
+      }
+    },
+  );
+
+  test.each(["repository metadata", "working tree"])(
+    "settles a pending %s watcher retry after the final consumer leaves",
+    async (kind) => {
+      const watchPath = kind === "repository metadata" ? join(REPO_CWD, ".git") : REPO_CWD;
+      let attempts = 0;
+      const subscribe = vi.fn(async (directory: string) => {
+        if (directory === watchPath) {
+          attempts += 1;
+          return new Promise<ReturnType<typeof createAsyncSubscription>>(() => {});
+        }
+        return createAsyncSubscription();
+      });
+      const getCheckoutStatus = vi.fn(async (cwd: string) => createCheckoutStatus(cwd));
+      const service = createService({ subscribe, getCheckoutStatus });
+      const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+      try {
+        await settle(() => expect(attempts).toBe(1));
+        await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+        await waitForObservationToSettle(service, 1);
+        await vi.advanceTimersByTimeAsync(30_000);
+        await settle(() => expect(attempts).toBe(2));
+        subscription.unsubscribe();
+        await waitForRefreshesToSettle(service);
+        const readsAfterUnsubscribe = getCheckoutStatus.mock.calls.length;
+        // Vitest reports any unhandled rejection as a suite failure.
+        await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+        await vi.advanceTimersByTimeAsync(300_000);
+        expect(attempts).toBe(2);
+        expect(vi.getTimerCount()).toBe(0);
+        expect(getCheckoutStatus.mock.calls.length).toBe(readsAfterUnsubscribe);
+      } finally {
+        subscription.unsubscribe();
+        await service.dispose();
+      }
+    },
+  );
+
+  test("metadata recovery reconciles exclusions changed during the outage", async () => {
+    let ignoredDirectories = "generated/\n";
+    let attempts = 0;
+    let workingTreeCallback!: (
+      error: Error | null,
+      events: Array<{ path: string; type: "delete" }>,
+    ) => void;
+    const workingTreeSubscription = createAsyncSubscription();
+    const subscribe = vi.fn(async (directory: string, callback: typeof workingTreeCallback) => {
+      if (directory === join(REPO_CWD, ".git") && ++attempts === 1) {
+        return new Promise<ReturnType<typeof createAsyncSubscription>>(() => {});
+      }
+      if (directory === REPO_CWD) {
+        workingTreeCallback = callback;
+        return workingTreeSubscription;
+      }
+      return createAsyncSubscription();
+    });
+    const runGitCommand = vi.fn(async (args: string[]) => ({
+      stdout: args[0] === "rev-parse" ? `${REPO_CWD}\n` : ignoredDirectories,
+      stderr: "",
+      truncated: false,
+      exitCode: 0,
+      signal: null,
+    }));
+    const getCheckoutStatus = vi.fn(async (cwd: string) => createCheckoutStatus(cwd));
+    const service = createService({ subscribe, runGitCommand, getCheckoutStatus });
+    const subscription = service.registerWorkspace({ cwd: REPO_CWD }, vi.fn());
+    try {
+      await settle(() => expect(attempts).toBe(1));
+      await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_WATCHER_SUBSCRIBE_TIMEOUT_MS);
+      await waitForObservationToSettle(service, 1);
+      expect(subscribe.mock.calls.find(([directory]) => directory === REPO_CWD)).toBeDefined();
+      ignoredDirectories = ""; // info/exclude changed while metadata observation was unavailable.
+      await vi.advanceTimersByTimeAsync(30_000);
+      await settle(() => expect(attempts).toBe(2));
+      await vi.advanceTimersByTimeAsync(1_000);
+      await waitForRefreshesToSettle(service);
+      const readsAfterRecovery = getCheckoutStatus.mock.calls.length;
+      workingTreeCallback(null, [
+        { path: join(REPO_CWD, "generated", "output.ts"), type: "delete" },
+      ]);
+      await vi.advanceTimersByTimeAsync(1_000);
+      await waitForRefreshesToSettle(service);
+      expect(getCheckoutStatus.mock.calls.length).toBeGreaterThan(readsAfterRecovery);
+      expect(workingTreeSubscription.updateIgnore).toHaveBeenCalledWith([join(REPO_CWD, ".git")]);
+    } finally {
+      subscription.unsubscribe();
+      await service.dispose();
+    }
+  });
+
   test("sets a bounded polling fallback when recursive observation is unavailable", async () => {
     const subscribe = vi.fn(async () => {
       throw new Error("watcher unavailable");
@@ -1418,7 +1847,7 @@ describe("WorkspaceGitServiceImpl", () => {
     const service = createService({ subscribe });
     const subscription = await service.requestWorkingTreeWatch(REPO_CWD, vi.fn());
 
-    expect(vi.getTimerCount()).toBe(1);
+    expect(vi.getTimerCount()).toBe(2);
 
     subscription.unsubscribe();
     service.dispose();
@@ -1553,3 +1982,477 @@ describe("WorkspaceGitServiceImpl", () => {
     service.dispose();
   });
 });
+
+describe("WorkspaceGitServiceImpl with workspace folders that no longer exist", () => {
+  const temporaryFolders: string[] = [];
+
+  async function createTemporaryFolder(): Promise<string> {
+    const folder = await mkdtemp(join(os.tmpdir(), "paseo-workspace-git-"));
+    temporaryFolders.push(folder);
+    return folder;
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    await Promise.all(
+      temporaryFolders.splice(0).map((folder) => rm(folder, { recursive: true, force: true })),
+    );
+  });
+
+  test("polling stops for a workspace whose folder no longer exists", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const subscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+
+    await rm(workspace, { recursive: true, force: true });
+    const gitCommandsAtDeletion = git.gitCommandsIn(workspace);
+    await advanceThroughDegradedPolls(service);
+
+    expect(git.gitCommandsIn(workspace)).toBe(gitCommandsAtDeletion);
+    expect(service.getMetrics()).toMatchObject({
+      repositoryTargetCount: 0,
+      workingTreeWatchTargetCount: 0,
+    });
+    expect(vi.getTimerCount()).toBe(1);
+
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test.each([0, 250])(
+    "a deleted worktree leaves its shared repository polling and fetch to the surviving worktree (watch delay: %ims)",
+    async (watchDelayMs) => {
+      const gitCommonDir = join(await createTemporaryFolder(), ".git");
+      const deletedWorktree = await createTemporaryFolder();
+      const survivingWorktree = await createTemporaryFolder();
+      const watchReady = createDeferred<void>();
+      const git = createFolderBackedGit({
+        facts: linkedWorktreeFacts(gitCommonDir),
+        heldWatch: { directory: survivingWorktree, release: watchReady.promise },
+      });
+      let survivingWorktreeEdits = 0;
+      git.deps.getCheckoutShortstat.mockImplementation(async (cwd: string) => ({
+        additions: cwd === survivingWorktree ? ++survivingWorktreeEdits : 1,
+        deletions: 0,
+      }));
+      const service = createService(git.deps);
+      try {
+        const deletedSubscription = service.registerWorkspace({ cwd: deletedWorktree }, vi.fn());
+        await waitForObservationToSettle(service, 1);
+        const survivingSubscription = service.registerWorkspace(
+          { cwd: survivingWorktree },
+          vi.fn(),
+        );
+        const pollingTime = Date.now();
+        void delay(watchDelayMs).then(() => watchReady.resolve());
+        await waitForObservationToSettle(service, 2);
+        expect(Date.now()).toBe(pollingTime);
+
+        await rm(deletedWorktree, { recursive: true, force: true });
+        await vi.advanceTimersByTimeAsync(60_000);
+        await waitForRefreshesToSettle(service);
+        const deletedWorktreeCommands = git.gitCommandsIn(deletedWorktree);
+
+        for (let tick = 0; tick < 3; tick += 1) {
+          const survivingWorktreePolls = git.pollsOf(survivingWorktree);
+          await vi.advanceTimersByTimeAsync(5_000);
+          await settle(() => {
+            expect(git.pollsOf(survivingWorktree)).toBe(survivingWorktreePolls + 1);
+          });
+        }
+        expect(git.gitCommandsIn(deletedWorktree)).toBe(deletedWorktreeCommands);
+
+        const fetchesBefore = git.deps.runGitFetch.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(2 * BACKGROUND_GIT_FETCH_INTERVAL_MS);
+        expect(git.deps.runGitFetch.mock.calls.slice(fetchesBefore).map(([cwd]) => cwd)).toEqual([
+          survivingWorktree,
+          survivingWorktree,
+        ]);
+        expect(git.gitCommandsIn(deletedWorktree)).toBe(deletedWorktreeCommands);
+
+        deletedSubscription.unsubscribe();
+        survivingSubscription.unsubscribe();
+      } finally {
+        watchReady.resolve();
+        await service.dispose();
+      }
+    },
+  );
+
+  test("deleting every worktree of a repository stops its polling and background fetch", async () => {
+    const gitCommonDir = join(await createTemporaryFolder(), ".git");
+    const firstWorktree = await createTemporaryFolder();
+    const secondWorktree = await createTemporaryFolder();
+    const git = createFolderBackedGit({ facts: linkedWorktreeFacts(gitCommonDir) });
+    const service = createService(git.deps);
+    const firstSubscription = service.registerWorkspace({ cwd: firstWorktree }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    const secondSubscription = service.registerWorkspace({ cwd: secondWorktree }, vi.fn());
+    await waitForObservationToSettle(service, 2);
+
+    await rm(firstWorktree, { recursive: true, force: true });
+    await rm(secondWorktree, { recursive: true, force: true });
+    const commandsAtDeletion = [
+      git.gitCommandsIn(firstWorktree),
+      git.gitCommandsIn(secondWorktree),
+    ];
+    await advanceThroughDegradedPolls(service);
+
+    expect([git.gitCommandsIn(firstWorktree), git.gitCommandsIn(secondWorktree)]).toEqual(
+      commandsAtDeletion,
+    );
+    expect(service.getMetrics()).toMatchObject({
+      repositoryTargetCount: 0,
+      workingTreeWatchTargetCount: 0,
+    });
+    expect(vi.getTimerCount()).toBe(2);
+
+    firstSubscription.unsubscribe();
+    secondSubscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("working tree fallback polling and watcher recovery stop for a workspace whose folder no longer exists", async () => {
+    const workspace = await createTemporaryFolder();
+    await mkdir(join(workspace, ".git"));
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const subscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+
+    await rm(workspace, { recursive: true, force: true });
+    git.watchCallbackFor(workspace)(new Error("watched directory was deleted"), []);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await waitForRefreshesToSettle(service);
+    const commandsAfterWatcherError = git.gitCommandsIn(workspace);
+    const watchAttemptsAfterWatcherError = git.watchAttemptsFor(workspace);
+    await advanceThroughDegradedPolls(service);
+
+    expect(git.gitCommandsIn(workspace)).toBe(commandsAfterWatcherError);
+    expect(git.watchAttemptsFor(workspace)).toBe(watchAttemptsAfterWatcherError);
+    expect(vi.getTimerCount()).toBe(1);
+
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a workspace whose folder comes back resumes polling on its next subscription", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const firstSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    await rm(workspace, { recursive: true, force: true });
+    const commandsWhileMissing = git.gitCommandsIn(workspace);
+    await advanceThroughDegradedPolls(service);
+    expect(git.gitCommandsIn(workspace)).toBe(commandsWhileMissing);
+
+    await mkdir(workspace);
+    const secondSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    const pollsAfterResume = git.pollsOf(workspace);
+    await vi.advanceTimersByTimeAsync(5_000);
+    await waitForRefreshesToSettle(service);
+
+    expect(git.pollsOf(workspace)).toBe(pollsAfterResume + 1);
+
+    firstSubscription.unsubscribe();
+    secondSubscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a suspended workspace costs no git while its folder is missing, even when a refresh is requested", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const subscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    await rm(workspace, { recursive: true, force: true });
+    await advanceThroughDegradedPolls(service);
+    const commandsWhileMissing = git.gitCommandsIn(workspace);
+
+    for (let probe = 0; probe < 10; probe += 1) {
+      await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_OBSERVATION_REENSURE_INTERVAL_MS);
+      await waitForRefreshesToSettle(service);
+    }
+    service.scheduleRefreshForCwd(workspace);
+    service.onWorkspaceStateMayHaveChanged(workspace);
+    await vi.advanceTimersByTimeAsync(5_000);
+    await waitForRefreshesToSettle(service);
+
+    expect(git.gitCommandsIn(workspace)).toBe(commandsWhileMissing);
+    expect(vi.getTimerCount()).toBe(1);
+
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a suspended worktree resumes polling and its repository fetch once its folder is back, without a new subscription", async () => {
+    const gitCommonDir = join(await createTemporaryFolder(), ".git");
+    const worktree = await createTemporaryFolder();
+    const git = createFolderBackedGit({ facts: linkedWorktreeFacts(gitCommonDir) });
+    const service = createService(git.deps);
+    const subscription = service.registerWorkspace({ cwd: worktree }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    await rm(worktree, { recursive: true, force: true });
+    await advanceThroughDegradedPolls(service);
+    await waitForObservationToSettle(service, 0);
+
+    await mkdir(worktree);
+    const fetchesBeforeRestore = git.fetchesIn(worktree);
+    await vi.advanceTimersByTimeAsync(WORKSPACE_GIT_OBSERVATION_REENSURE_INTERVAL_MS);
+    await waitForObservationToSettle(service, 1);
+    expect(git.fetchesIn(worktree)).toBe(fetchesBeforeRestore + 1);
+
+    const pollsAfterRestore = git.pollsOf(worktree);
+    await vi.advanceTimersByTimeAsync(5_000);
+    await waitForRefreshesToSettle(service);
+    expect(git.pollsOf(worktree)).toBe(pollsAfterRestore + 1);
+
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a forced snapshot resumes a suspended workspace whose folder is back", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const subscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    await rm(workspace, { recursive: true, force: true });
+    await advanceThroughDegradedPolls(service);
+    await waitForObservationToSettle(service, 0);
+
+    await mkdir(workspace);
+    const snapshot = await service.getSnapshot(workspace, {
+      force: true,
+      reason: "refresh-button",
+    });
+    await waitForObservationToSettle(service, 1);
+
+    expect(snapshot.git.isGit).toBe(true);
+
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a resumed workspace rebuilds observation from fresh facts, not the non-git facts cached while its folder was gone", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const firstSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    await rm(workspace, { recursive: true, force: true });
+    service.onWorkspaceStateMayHaveChanged(workspace);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await waitForRefreshesToSettle(service);
+    expect((await service.getSnapshot(workspace)).git.isGit).toBe(false);
+    await advanceThroughDegradedPolls(service);
+    await waitForObservationToSettle(service, 0);
+
+    await mkdir(workspace);
+    const secondSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+
+    expect((await service.getSnapshot(workspace)).git.isGit).toBe(true);
+
+    firstSubscription.unsubscribe();
+    secondSubscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("resuming waits for an observation setup that was still running when the folder vanished", async () => {
+    const workspace = await createTemporaryFolder();
+    const gitDir = join(workspace, ".git");
+    await mkdir(gitDir);
+    const metadataWatchRelease = createDeferred<void>();
+    const git = createFolderBackedGit({
+      unwatchableDirectories: [workspace],
+      heldWatch: { directory: gitDir, release: metadataWatchRelease.promise },
+    });
+    const service = createService(git.deps);
+    const firstSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await settle(() => {
+      expect(git.watchAttemptsFor(gitDir)).toBe(1);
+    });
+
+    await rm(workspace, { recursive: true, force: true });
+    await vi.advanceTimersByTimeAsync(5_000);
+    await settle(() => {
+      expect(service.getMetrics()).toMatchObject({
+        repositoryTargetCount: 0,
+        workingTreeWatchTargetCount: 0,
+      });
+    });
+    await mkdir(workspace);
+    const secondSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    metadataWatchRelease.resolve();
+    await waitForObservationToSettle(service, 1);
+
+    expect(service.getMetrics().workingTreeWatchTargetCount).toBe(1);
+
+    firstSubscription.unsubscribe();
+    secondSubscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("an open working tree watch neither notifies nor recovers while its folder is missing, and picks up once it is back", async () => {
+    const workspace = await createTemporaryFolder();
+    await mkdir(join(workspace, ".git"));
+    const git = createFolderBackedGit();
+    const service = createService(git.deps);
+    const workspaceSubscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
+    await waitForObservationToSettle(service, 1);
+    const diffListener = vi.fn();
+    const diffWatch = await service.requestWorkingTreeWatch(workspace, diffListener);
+
+    await rm(workspace, { recursive: true, force: true });
+    git.watchCallbackFor(workspace)(new Error("watched directory was deleted"), []);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await waitForRefreshesToSettle(service);
+    const commandsAfterWatcherError = git.gitCommandsIn(workspace);
+    const notificationsAfterWatcherError = diffListener.mock.calls.length;
+    const watchAttemptsAfterWatcherError = git.watchAttemptsFor(workspace);
+    await advanceThroughWorkingTreeRecoveryAttempts(service);
+
+    expect(git.gitCommandsIn(workspace)).toBe(commandsAfterWatcherError);
+    expect(diffListener.mock.calls.length).toBe(notificationsAfterWatcherError);
+    expect(git.watchAttemptsFor(workspace)).toBe(watchAttemptsAfterWatcherError);
+    expect(service.getMetrics().workingTreeWatchTargetCount).toBe(1);
+
+    await mkdir(join(workspace, ".git"), { recursive: true });
+    await vi.advanceTimersByTimeAsync(60_000);
+    await waitForRefreshesToSettle(service);
+    expect(diffListener.mock.calls.length).toBe(notificationsAfterWatcherError + 1);
+
+    await vi.advanceTimersByTimeAsync(240_000);
+    await waitForRefreshesToSettle(service);
+    expect(git.watchAttemptsFor(workspace)).toBe(watchAttemptsAfterWatcherError + 1);
+    const notificationsAfterResubscribe = diffListener.mock.calls.length;
+    await vi.advanceTimersByTimeAsync(120_000);
+    await waitForRefreshesToSettle(service);
+    expect(diffListener.mock.calls.length).toBe(notificationsAfterResubscribe);
+
+    diffWatch.unsubscribe();
+    workspaceSubscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("a refresh crossing suspension preserves the cached snapshot and drops queued work", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const started = createDeferred<void>();
+    const release = createDeferred<void>();
+    let holdNextRead = false;
+    let factsReads = 0;
+    const service = createService({
+      ...git.deps,
+      getCheckoutSnapshotFacts: async (cwd: string) => {
+        factsReads++;
+        if (holdNextRead) {
+          holdNextRead = false;
+          started.resolve();
+          await release.promise;
+        }
+        return git.deps.getCheckoutSnapshotFacts(cwd);
+      },
+    });
+    const updates: WorkspaceGitRuntimeSnapshot[] = [];
+    const subscription = service.registerWorkspace({ cwd: workspace }, (snapshot) =>
+      updates.push(snapshot),
+    );
+    await waitForObservationToSettle(service, 1);
+    const cached = await service.getSnapshot(workspace);
+    holdNextRead = true;
+    const active = service.getSnapshot(workspace, {
+      force: true,
+      includeForge: false,
+      reason: "overlapping-refresh",
+    });
+    await started.promise;
+    const queued = service.getSnapshot(workspace, {
+      force: true,
+      includeForge: true,
+      reason: "queued-refresh",
+    });
+    await rm(workspace, { recursive: true, force: true });
+    await vi.advanceTimersByTimeAsync(5_000);
+    await settle(() => expect(service.getMetrics().repositoryWorkspaceLinkCount).toBe(0));
+    const readsAtSuspension = factsReads;
+    const updatesAtSuspension = updates.length;
+    release.resolve();
+    expect(await active).toEqual(cached);
+    expect(await queued).toEqual(cached);
+    expect(await service.getSnapshot(workspace)).toEqual(cached);
+    expect(updates).toHaveLength(updatesAtSuspension);
+    expect(factsReads).toBe(readsAtSuspension);
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("restoration settles a suspended refresh before reloading facts", async () => {
+    const workspace = await createTemporaryFolder();
+    const git = createFolderBackedGit();
+    const staleFacts = createDeferred<CheckoutSnapshotFacts>();
+    const started = createDeferred<void>();
+    let holdNextRead = false;
+    const service = createService({
+      ...git.deps,
+      getCheckoutSnapshotFacts: async (cwd: string) => {
+        if (holdNextRead) {
+          holdNextRead = false;
+          started.resolve();
+          return staleFacts.promise;
+        }
+        return git.deps.getCheckoutSnapshotFacts(cwd);
+      },
+    });
+    const updates: WorkspaceGitRuntimeSnapshot[] = [];
+    const subscription = service.registerWorkspace({ cwd: workspace }, (snapshot) =>
+      updates.push(snapshot),
+    );
+    await waitForObservationToSettle(service, 1);
+    const cached = await service.getSnapshot(workspace);
+    holdNextRead = true;
+    const active = service.getSnapshot(workspace, {
+      force: true,
+      includeForge: false,
+      reason: "overlapping-refresh",
+    });
+    await started.promise;
+    await rm(workspace, { recursive: true, force: true });
+    await vi.advanceTimersByTimeAsync(5_000);
+    await settle(() => expect(service.getMetrics().repositoryWorkspaceLinkCount).toBe(0));
+    const updatesAtSuspension = updates.length;
+    await mkdir(workspace);
+    const restored = service.getSnapshot(workspace, {
+      force: true,
+      includeForge: false,
+      reason: "folder-returned",
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    staleFacts.resolve({ isGit: false });
+    expect(await active).toEqual(cached);
+    expect((await restored).git.isGit).toBe(true);
+    expect(updates.slice(updatesAtSuspension).every((snapshot) => snapshot.git.isGit)).toBe(true);
+    await waitForObservationToSettle(service, 1);
+    subscription.unsubscribe();
+    await service.dispose();
+  });
+
+  test("workspaceFolderExists reports a missing folder and a path under a file as missing", async () => {
+    const folder = await createTemporaryFolder();
+    const file = join(folder, "file.txt");
+    await writeFile(file, "");
+
+    expect(await workspaceFolderExists(folder)).toBe(true);
+    expect(await workspaceFolderExists(join(folder, "missing"))).toBe(false);
+    expect(await workspaceFolderExists(join(file, "nested"))).toBe(false);
+  });
+});
diff --git a/packages/server/src/server/workspace-git-service.ts b/packages/server/src/server/workspace-git-service.ts
index b5672846bd..c086fa41be 100644
--- a/packages/server/src/server/workspace-git-service.ts
+++ b/packages/server/src/server/workspace-git-service.ts
@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { LRUCache } from "lru-cache";
 import { CheckoutDiffCache } from "./checkout-diff-cache.js";
@@ -48,6 +48,7 @@ import {
   runGitCommand,
   type RunGitCommand,
 } from "../utils/run-git-command.js";
+import type { GitProcessPriority } from "../utils/git-process-scheduler.js";
 import { GitObservationPaths } from "./git-observation-paths.js";
 import { branchNameFromRef } from "../utils/worktree-metadata.js";
 import { listPaseoWorktrees, type PaseoWorktreeInfo } from "../utils/worktree.js";
@@ -74,7 +75,7 @@ import { checkoutLiteFromGitSnapshot } from "./workspace-registry-model.js";
 import { createWatcherLivenessCanary } from "./watcher-liveness-canary.js";
 
 const WORKSPACE_GIT_WATCH_DEBOUNCE_MS = 1_000;
-const BACKGROUND_GIT_FETCH_INTERVAL_MS = 180_000;
+export const BACKGROUND_GIT_FETCH_INTERVAL_MS = 180_000;
 const FETCH_METADATA_ECHO_TTL_MS = 5_000;
 export const WORKSPACE_GIT_OBSERVATION_REENSURE_INTERVAL_MS = 60_000;
 const FORGE_PR_STATUS_POLL_FAST_INTERVAL_MS = 20_000;
@@ -155,10 +156,13 @@ export interface WorkspaceGitRuntimeSnapshot {
     repoRoot: string | null;
     mainRepoRoot: string | null;
     currentBranch: string | null;
+    headSha?: string;
     remoteUrl: string | null;
     isPaseoOwnedWorktree: boolean;
     isDirty: boolean | null;
     baseRef: string | null;
+    baseRefExact?: string | null;
+    comparisonBaseRef?: string | null;
     aheadBehind: { ahead: number; behind: number } | null;
     upstreamRef: string | null;
     aheadOfOrigin: number | null;
@@ -185,6 +189,7 @@ export interface WorkspaceGitRuntimeSnapshot {
       state: string;
       baseRefName: string;
       headRefName: string;
+      headSha?: string;
       isMerged: boolean;
       isDraft?: boolean;
       mergeable?: PullRequestMergeable;
@@ -205,7 +210,10 @@ export interface WorkspaceGitService {
 
   /** Publishes computed snapshot changes independently of workspace UI subscriptions. */
   onSnapshotUpdated(listener: WorkspaceGitSnapshotUpdatedListener): WorkspaceGitSubscription;
-  getCheckout(cwd: string): Promise<ProjectCheckoutLitePayload>;
+  getCheckout(
+    cwd: string,
+    options?: WorkspaceGitCheckoutReadOptions,
+  ): Promise<ProjectCheckoutLitePayload>;
   getSnapshot(
     cwd: string,
     options?: WorkspaceGitSnapshotOptions,
@@ -294,6 +302,7 @@ export type WorkspaceGitReadOptions =
 export interface WorkspaceGitBranchSuggestionsOptions {
   query?: string;
   limit?: number;
+  refMode?: "exact";
 }
 
 export interface WorkspaceGitStashListOptions {
@@ -320,10 +329,32 @@ export type WorkspaceGitSnapshotOptions =
   | {
       force: true;
       includeForge?: boolean;
+      afterInFlight?: boolean;
       reason: string;
     };
 
+/**
+ * Who is waiting for a refresh. "demand" refreshes answer a caller; "observation"
+ * refreshes react to watchers, polls and fetches and run in the background Git
+ * lane so they never queue in front of interactive Git work.
+ */
+type WorkspaceGitRefreshOrigin = "demand" | "observation";
+
+export interface WorkspaceGitCheckoutReadOptions {
+  /** Git lane for the fresh checkout read; defaults to the caller's ambient lane. */
+  priority?: GitProcessPriority;
+}
+
+// A caller waiting on a merged refresh keeps it out of the background lane.
+function mergeRefreshOrigins(
+  pending: WorkspaceGitRefreshOrigin,
+  request: WorkspaceGitRefreshOrigin,
+): WorkspaceGitRefreshOrigin {
+  return pending === "demand" ? pending : request;
+}
+
 interface WorkspaceGitRefreshRequest {
+  origin: WorkspaceGitRefreshOrigin;
   force: boolean;
   refreshStructure: boolean;
   refreshWorktree: boolean;
@@ -335,6 +366,7 @@ interface WorkspaceGitRefreshRequest {
 }
 
 interface ScheduledWorkspaceGitRefreshOptions {
+  origin: WorkspaceGitRefreshOrigin;
   force?: boolean;
   scope?: "refs" | "structure" | "worktree";
   includeForge?: boolean;
@@ -384,6 +416,7 @@ interface WorkspaceGitServiceDependencies {
   runGitCommand: typeof runGitCommand;
   getWorkspaceGitSelfHealPhaseMs: typeof getWorkspaceGitObservationReensurePhaseMs;
   createWatcherLivenessCanary: typeof createWatcherLivenessCanary;
+  workspaceFolderExists: (cwd: string) => Promise<boolean>;
   now: () => Date;
 }
 
@@ -435,6 +468,8 @@ interface WorkspaceGitTarget {
   repoGitRoot: string | null;
   observationSetupPromise: Promise<void> | null;
   observationSetupComplete: boolean;
+  folderMissing: boolean;
+  folderRestorePromise: Promise<void> | null;
   closed: boolean;
 }
 
@@ -571,10 +606,21 @@ function buildDefaultWorkspaceGitServiceDeps(
     runGitCommand,
     getWorkspaceGitSelfHealPhaseMs: getWorkspaceGitObservationReensurePhaseMs,
     createWatcherLivenessCanary,
+    workspaceFolderExists,
     now: () => new Date(),
   };
 }
 
+export async function workspaceFolderExists(cwd: string): Promise<boolean> {
+  try {
+    await stat(cwd);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code !== "ENOENT" && code !== "ENOTDIR";
+  }
+}
+
 function resolveWorkspaceGitServiceDeps(
   subscribe: SubscribeToFileChanges,
   deps: Partial<WorkspaceGitServiceDependencies> | undefined,
@@ -600,6 +646,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   private readonly disposeController = new AbortController();
   private disposed = false;
   private disposePromise: Promise<void> | null = null;
+  private readonly pendingRefreshes = new Set<Promise<WorkspaceGitRuntimeSnapshot>>();
   private readonly snapshotUpdatedListeners = new Set<WorkspaceGitSnapshotUpdatedListener>();
   private readonly workspaceTargets = new Map<string, WorkspaceGitTarget>();
   private readonly repoTargets = new Map<string, RepoGitTarget>();
@@ -660,6 +707,9 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const cwd = resolve(params.cwd);
     const target = this.ensureWorkspaceTarget(cwd);
     target.listeners.add(listener);
+    if (target.folderMissing) {
+      void this.resumeWorkspaceIfFolderRestored(target);
+    }
     if (target.listeners.size === 1) {
       this.startWorkspaceSubscriptionTimers(target);
     }
@@ -751,17 +801,26 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     if (!request.force && target.latestSnapshot) {
       return target.latestSnapshot;
     }
+    if (target.folderMissing) {
+      await this.resumeWorkspaceIfFolderRestored(target);
+    }
 
     return this.requestWorkspaceSnapshot(target, request);
   }
 
-  async getCheckout(cwd: string): Promise<ProjectCheckoutLitePayload> {
+  async getCheckout(
+    cwd: string,
+    options?: WorkspaceGitCheckoutReadOptions,
+  ): Promise<ProjectCheckoutLitePayload> {
     this.assertNotDisposed();
     const normalizedCwd = resolve(cwd);
     const status = await this.deps.getCheckoutStatus(normalizedCwd, {
       paseoHome: this.paseoHome,
       worktreesRoot: this.worktreesRoot,
       logger: this.logger,
+      ...(options?.priority
+        ? { runGitCommand: createRunGitCommand("checkout-read", { priority: options.priority }) }
+        : {}),
     });
     const cached = this.getCachedSnapshot(normalizedCwd);
     if (cached && cached.git.isGit !== status.isGit) {
@@ -881,7 +940,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const normalizedCwd = resolve(cwd);
     const query = options?.query ?? "";
     const limit = options?.limit;
-    const key = JSON.stringify(["branch-suggestions", normalizedCwd, query, limit ?? null]);
+    const key = JSON.stringify([
+      "branch-suggestions",
+      normalizedCwd,
+      query,
+      limit ?? null,
+      options?.refMode,
+    ]);
     return this.readAuxiliaryCache(this.branchSuggestionsCache, key, readOptions, () =>
       this.deps.listBranchSuggestions(normalizedCwd, options),
     );
@@ -972,7 +1037,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     this.assertNotDisposed();
     cwd = resolve(cwd);
     const target = this.ensureWorkspaceTarget(cwd);
+    if (target.folderMissing) {
+      await this.resumeWorkspaceIfFolderRestored(target);
+    }
     await this.refreshWorkspaceTarget(target, {
+      origin: "demand",
       force: false,
       refreshStructure: true,
       refreshWorktree: true,
@@ -1005,9 +1074,14 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     this.assertNotDisposed();
     cwd = resolve(cwd);
     const target = this.workspaceTargets.get(cwd);
-    if (target) {
-      this.scheduleWorkspaceRefresh(target, { queueIfBusy: false });
+    if (!target) {
+      return;
     }
+    if (target.folderMissing) {
+      void this.resumeWorkspaceIfFolderRestored(target);
+      return;
+    }
+    this.scheduleWorkspaceRefresh(target, { origin: "demand", queueIfBusy: false });
   }
 
   onWorkspaceStateMayHaveChanged(cwd: string): void {
@@ -1018,7 +1092,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       return;
     }
     this.invalidateForge(normalizedCwd);
+    if (target.folderMissing) {
+      void this.resumeWorkspaceIfFolderRestored(target);
+      return;
+    }
     this.scheduleWorkspaceRefresh(target, {
+      origin: "demand",
       force: true,
       includeForge: true,
       reason: "external-state-change",
@@ -1060,7 +1139,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     this.workingTreeWatchResolutions.clear();
     this.workingTreeWatchAliases.clear();
     this.snapshotUpdatedListeners.clear();
-    this.disposePromise = this.fileObserver.close();
+    // Unsubscribing can remove a target while its Git command still owns the cwd.
+    // Stop admission first, then drain those refreshes before releasing the service.
+    this.disposePromise = Promise.all([
+      this.fileObserver.close(),
+      Promise.allSettled(this.pendingRefreshes),
+    ]).then(() => undefined);
     return this.disposePromise;
   }
 
@@ -1227,6 +1311,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       repoGitRoot: null,
       observationSetupPromise: null,
       observationSetupComplete: false,
+      folderMissing: false,
+      folderRestorePromise: null,
       closed: false,
     };
 
@@ -1240,6 +1326,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         return;
       }
       void this.refreshWorkspaceTarget(target, {
+        origin: "demand",
         force: false,
         refreshStructure: true,
         refreshWorktree: true,
@@ -1319,9 +1406,27 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     await this.ensureRepoTarget(target);
     if (this.isActiveObservedWorkspaceTarget(target)) {
       target.observationSetupComplete = true;
+      this.refreshAfterWorkingTreeCoverage(target);
     }
   }
 
+  // Watchers report only changes made after they subscribe, and the initial
+  // snapshot is read in parallel with observation setup, so an edit or branch
+  // switch in between reaches no watcher. Read the checkout once more now that
+  // every later change will. Degraded polling keeps its own cadence.
+  private refreshAfterWorkingTreeCoverage(target: WorkspaceGitTarget): void {
+    if (!target.workingTreeWatchTarget?.subscription) {
+      return;
+    }
+    void this.refreshWorkspaceTarget(
+      target,
+      this.buildScheduledRefreshRequest({
+        origin: "observation",
+        reason: "observation-established",
+      }),
+    );
+  }
+
   private async getFactsForObservation(target: WorkspaceGitTarget): Promise<CheckoutSnapshotFacts> {
     if (target.latestFacts) {
       return target.latestFacts;
@@ -1358,6 +1463,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   private isActiveObservedWorkspaceTarget(target: WorkspaceGitTarget): boolean {
     return (
       !target.closed &&
+      !target.folderMissing &&
       target.listeners.size > 0 &&
       this.workspaceTargets.get(target.cwd) === target
     );
@@ -1508,6 +1614,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     options?: { replaceFallback?: boolean },
   ): Promise<boolean> {
     const ignore = this.workingTreeIgnoreList(target);
+    let abandoned = false;
+    let activeSubscription: FileObserverSubscription | null = null;
     let watcherErrored = false;
     let subscribeSettled = false;
     const markSubscribeSettled = () => {
@@ -1520,6 +1628,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       const subscription = await this.subscribeWithDeadline(
         target.watchPath,
         (error, events) => {
+          if (
+            abandoned ||
+            target.closed ||
+            (activeSubscription && target.subscription !== activeSubscription)
+          ) {
+            return;
+          }
           if (error) {
             if (watcherErrored) {
               return;
@@ -1553,6 +1668,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         markSubscribeSettled,
       );
       if (watcherErrored) {
+        abandoned = true;
         await this.unsubscribeWatcherSubscription(subscription, target.watchPath);
         return false;
       }
@@ -1561,9 +1677,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         (target.fallbackPolling && !options?.replaceFallback) ||
         target.subscription
       ) {
+        abandoned = true;
         await this.unsubscribeWatcherSubscription(subscription, target.watchPath);
         return false;
       }
+      activeSubscription = subscription;
       target.subscription = subscription;
       target.appliedIgnoreList = ignore;
       // Do not reset `attemptCount` here — `subscribe()` resolving proves
@@ -1581,11 +1699,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       }
       return true;
     } catch (error) {
+      abandoned = true;
       if (watcherErrored) {
         return false;
       }
       if (this.disposed || target.closed) {
-        throw error;
+        return false;
       }
       this.logger.warn(
         { err: error, cwd: target.cwd },
@@ -1594,6 +1713,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       if (!options?.replaceFallback) {
         this.startWorkingTreeWatchFallback(target, "watcher_setup_failed");
       }
+      this.scheduleWorkingTreeWatchRecovery(target);
       return false;
     }
   }
@@ -1612,11 +1732,111 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     workspaceTarget: WorkspaceGitTarget,
     request: WorkspaceGitRefreshRequest,
   ): Promise<boolean> {
+    if (await this.suspendWorkspaceIfFolderMissing(workspaceTarget)) {
+      return false;
+    }
     const fingerprintBefore = workspaceTarget.latestFingerprint;
     await this.refreshWorkspaceTarget(workspaceTarget, request);
     return workspaceTarget.latestFingerprint !== fingerprintBefore;
   }
 
+  private async suspendWorkspaceIfFolderMissing(target: WorkspaceGitTarget): Promise<boolean> {
+    if (target.folderMissing) {
+      return true;
+    }
+    if (await this.deps.workspaceFolderExists(target.cwd)) {
+      return false;
+    }
+    this.suspendWorkspaceWithMissingFolder(target);
+    return true;
+  }
+
+  private suspendWorkspaceWithMissingFolder(target: WorkspaceGitTarget): void {
+    if (target.folderMissing || target.closed || this.workspaceTargets.get(target.cwd) !== target) {
+      return;
+    }
+    target.folderMissing = true;
+    if (target.refreshState.status === "in-flight") {
+      target.refreshState.queued = null;
+    }
+    this.detachWorkspaceFromRepoTarget(target);
+    target.repoGitRoot = null;
+    this.stopWorkspaceObservation(target);
+    target.observationSetupComplete = false;
+    this.scheduleMissingFolderProbe(target);
+    this.logger.warn(
+      { cwd: target.cwd },
+      "Workspace folder no longer exists; suspended git observation until it is back",
+    );
+  }
+
+  private isSuspendedWorkspaceTarget(target: WorkspaceGitTarget): boolean {
+    return (
+      target.folderMissing && !target.closed && this.workspaceTargets.get(target.cwd) === target
+    );
+  }
+
+  private scheduleMissingFolderProbe(target: WorkspaceGitTarget): void {
+    if (
+      !this.isSuspendedWorkspaceTarget(target) ||
+      target.observationReensureTimer ||
+      target.folderRestorePromise
+    ) {
+      return;
+    }
+    target.observationReensureTimer = setTimeout(() => {
+      target.observationReensureTimer = null;
+      void this.resumeWorkspaceIfFolderRestored(target);
+    }, WORKSPACE_GIT_OBSERVATION_REENSURE_INTERVAL_MS);
+  }
+
+  private resumeWorkspaceIfFolderRestored(target: WorkspaceGitTarget): Promise<void> {
+    if (!target.folderMissing) {
+      return Promise.resolve();
+    }
+    target.folderRestorePromise ??= this.resumeWorkspaceWithRestoredFolder(target).finally(() => {
+      target.folderRestorePromise = null;
+      this.scheduleMissingFolderProbe(target);
+    });
+    return target.folderRestorePromise;
+  }
+
+  private async resumeWorkspaceWithRestoredFolder(target: WorkspaceGitTarget): Promise<void> {
+    if (!(await this.deps.workspaceFolderExists(target.cwd))) {
+      return;
+    }
+    await target.observationSetupPromise;
+    if (target.refreshState.status === "in-flight") {
+      await target.refreshState.promise.catch(() => undefined);
+    }
+    if (!this.isSuspendedWorkspaceTarget(target)) {
+      return;
+    }
+    target.latestFacts = null;
+    target.folderMissing = false;
+    await this.refreshWorkspaceTarget(target, {
+      origin: "observation",
+      force: false,
+      refreshStructure: true,
+      refreshWorktree: true,
+      includeForge: false,
+      reason: "workspace-folder-restored",
+      queueIfBusy: true,
+      movedRemoteRefs: new Set(),
+    });
+    if (target.closed || this.workspaceTargets.get(target.cwd) !== target) {
+      return;
+    }
+    target.observationSetupComplete = false;
+    if (target.observationReensureTimer) {
+      clearTimeout(target.observationReensureTimer);
+      target.observationReensureTimer = null;
+    }
+    this.logger.info({ cwd: target.cwd }, "Workspace folder is back; resumed git observation");
+    this.startWorkspaceSubscriptionTimers(target);
+    this.scheduleWorkspaceObservationSetup(target);
+  }
+
   private startWorkingTreeWatchFallback(
     target: WorkingTreeWatchTarget,
     reason: WorkingTreeWatchFallbackReason,
@@ -1639,6 +1859,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
             return false;
           }
           const changed = await this.refreshDegradedPollTarget(workspaceTarget, {
+            origin: "observation",
             force: false,
             refreshStructure: target.repoRoot === null,
             refreshWorktree: true,
@@ -1654,7 +1875,9 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
           return changed;
         }),
       );
-      this.notifyWorkingTreeConsumers(target);
+      if (await this.deps.workspaceFolderExists(target.watchPath)) {
+        this.notifyWorkingTreeConsumers(target);
+      }
       if (!target.closed && (target.subscription === null || target.repoRoot === null)) {
         target.fallbackPollQuietTickCount = changes.some(Boolean)
           ? 0
@@ -1723,7 +1946,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const delayMs = this.advanceWatchRecoveryLadder(target.recovery);
     target.recovery.timer = setTimeout(() => {
       target.recovery.timer = null;
-      void this.recoverWorkingTreeWatch(target);
+      void this.recoverWorkingTreeWatch(target).catch((error) => {
+        if (this.disposed || target.closed) {
+          return;
+        }
+        this.logger.warn({ err: error }, "Git watcher recovery failed; retrying with backoff");
+        this.scheduleWorkingTreeWatchRecovery(target);
+      });
     }, delayMs);
   }
 
@@ -1731,6 +1960,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     if (target.closed || target.subscription) {
       return;
     }
+    if (!(await this.deps.workspaceFolderExists(target.watchPath))) {
+      this.scheduleWorkingTreeWatchRecovery(target);
+      return;
+    }
     await this.refreshWorkingTreeIgnoredDirectories(target);
     if (target.closed || target.subscription) {
       return;
@@ -2108,7 +2341,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     for (const workspaceKey of target.workspaceKeys) {
       const workspaceTarget = this.workspaceTargets.get(workspaceKey);
       if (workspaceTarget) {
-        this.scheduleWorkspaceRefresh(workspaceTarget, { scope: "worktree", reason });
+        this.scheduleWorkspaceRefresh(workspaceTarget, {
+          origin: "observation",
+          scope: "worktree",
+          reason,
+        });
       }
     }
   }
@@ -2225,6 +2462,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const matchesRepoGitRoot = paths.matches;
     const canary = this.deps.createWatcherLivenessCanary(target.repoGitRoot);
     let openedSubscription: FileObserverSubscription | null = null;
+    let abandoned = false;
+    let activeSubscription: FileObserverSubscription | null = null;
     let watcherErrored = false;
     let subscribeSettled = false;
     const markSubscribeSettled = () => {
@@ -2237,6 +2476,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       const subscription = await this.subscribeWithDeadline(
         target.repoGitRoot,
         (error, events) => {
+          if (
+            abandoned ||
+            target.closed ||
+            (activeSubscription && target.subscription !== activeSubscription)
+          ) {
+            return;
+          }
           const liveEvents = canary.filterEvents(
             events.map((event) => ({ ...event, path: paths.toWatchPath(event.path) })),
           );
@@ -2295,6 +2541,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       openedSubscription = subscription;
       await canary.verify(this.disposeController.signal);
       if (watcherErrored) {
+        abandoned = true;
         await this.unsubscribeWatcherSubscription(subscription, target.repoGitRoot);
         return false;
       }
@@ -2303,9 +2550,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         (target.fallbackPolling && !options?.replaceFallback) ||
         this.repoTargets.get(target.repoGitRoot) !== target
       ) {
+        abandoned = true;
         await this.unsubscribeWatcherSubscription(subscription, target.repoGitRoot);
         return false;
       }
+      activeSubscription = subscription;
       target.subscription = subscription;
       // See `advanceWatchRecoveryLadder`: do not reset `attemptCount` on
       // subscribe success alone, only record when this subscription was
@@ -2320,6 +2569,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       }
       return true;
     } catch (error) {
+      abandoned = true;
       if (openedSubscription) {
         await this.unsubscribeWatcherSubscription(openedSubscription, target.repoGitRoot);
       }
@@ -2327,7 +2577,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         return false;
       }
       if (this.disposed || target.closed) {
-        throw error;
+        return false;
       }
       this.logger.warn(
         { err: error, repoGitRoot: target.repoGitRoot },
@@ -2336,6 +2586,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       if (!options?.replaceFallback) {
         this.startRepoMetadataFallback(target);
       }
+      this.scheduleRepoMetadataWatchRecovery(target);
       return false;
     }
   }
@@ -2357,7 +2608,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const delayMs = this.advanceWatchRecoveryLadder(target.recovery);
     target.recovery.timer = setTimeout(() => {
       target.recovery.timer = null;
-      void this.recoverRepoMetadataWatch(target);
+      void this.recoverRepoMetadataWatch(target).catch((error) => {
+        if (this.disposed || target.closed) {
+          return;
+        }
+        this.logger.warn({ err: error }, "Git watcher recovery failed; retrying with backoff");
+        this.scheduleRepoMetadataWatchRecovery(target);
+      });
     }, delayMs);
   }
 
@@ -2371,6 +2628,8 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       return;
     }
     this.logger.info({ repoGitRoot: target.repoGitRoot }, "Repository metadata watcher recovered");
+    await this.refreshWorkingTreeIgnoresForWorkspaces(target.workspaceKeys);
+    this.scheduleRepoMetadataRefresh(target, "git-metadata-watch-recovered", true);
   }
 
   private routeRepoMetadataEvents(
@@ -2412,13 +2671,23 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         }
       }
     }
+    void this.refreshWorkingTreeIgnoresForWorkspaces(workspaceKeys);
+  }
+
+  private async refreshWorkingTreeIgnoresForWorkspaces(
+    workspaceKeys: Iterable<string>,
+  ): Promise<void> {
+    const targets = new Set<WorkingTreeWatchTarget>();
     for (const workspaceKey of workspaceKeys) {
       const workspaceTarget = this.workspaceTargets.get(workspaceKey);
       const workingTreeTarget = workspaceTarget
         ? this.getWorkingTreeWatchTargetForWorkspace(workspaceTarget)
         : null;
-      if (workingTreeTarget) void this.refreshWorkingTreeIgnoredDirectories(workingTreeTarget);
+      if (workingTreeTarget) targets.add(workingTreeTarget);
     }
+    await Promise.all(
+      [...targets].map((target) => this.refreshWorkingTreeIgnoredDirectories(target)),
+    );
   }
 
   private isFetchRemoteMetadataEvent(target: RepoGitTarget, event: FileChange): boolean {
@@ -2659,6 +2928,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
           }
         }
         this.scheduleWorkspaceRefresh(workspaceTarget, {
+          origin: "observation",
           scope,
           emitUnchanged: refresh.refreshBase,
           reason,
@@ -2699,6 +2969,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
             workingTreeTargets.add(workingTreeTarget);
           }
           return await this.refreshDegradedPollTarget(workspaceTarget, {
+            origin: "observation",
             force: false,
             refreshStructure: true,
             refreshWorktree: true,
@@ -2730,7 +3001,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
   private scheduleWorkspaceRefresh(
     targetOrCwd: WorkspaceGitTarget | string,
-    options?: ScheduledWorkspaceGitRefreshOptions,
+    options: ScheduledWorkspaceGitRefreshOptions,
   ): void {
     const target =
       typeof targetOrCwd === "string"
@@ -2786,7 +3057,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   }
 
   private updateForgePrStatusPollForTarget(target: WorkspaceGitTarget): void {
-    if (target.listeners.size === 0) {
+    if (!this.isActiveObservedWorkspaceTarget(target)) {
       this.stopForgePrStatusPollForTarget(target);
       return;
     }
@@ -3049,6 +3320,9 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     target: WorkspaceGitTarget,
     request: WorkspaceGitRefreshRequest,
   ): Promise<WorkspaceGitRuntimeSnapshot> {
+    if (target.folderMissing) {
+      return Promise.resolve(target.latestSnapshot ?? buildNotGitSnapshot(target.cwd));
+    }
     if (target.refreshState.status === "in-flight") {
       const active = target.refreshState.request;
       const addsWork =
@@ -3069,11 +3343,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     }
 
     const promise = this.runWorkspaceRefreshLoop(target, request).finally(() => {
+      this.pendingRefreshes.delete(promise);
       const state = target.refreshState;
       if (state.status === "in-flight" && state.promise === promise) {
         target.refreshState = { status: "idle" };
       }
     });
+    this.pendingRefreshes.add(promise);
     target.refreshState = {
       status: "in-flight",
       promise,
@@ -3094,12 +3370,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
     const force = options?.force === true;
     return {
+      origin: "demand",
       force,
       refreshStructure: true,
       refreshWorktree: true,
       includeForge: options?.includeForge ?? true,
       reason: options?.reason ?? defaultReason,
-      queueIfBusy: false,
+      queueIfBusy: force && options?.afterInFlight === true,
       movedRemoteRefs: new Set(),
     };
   }
@@ -3117,10 +3394,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   }
 
   private buildScheduledRefreshRequest(
-    options: ScheduledWorkspaceGitRefreshOptions | undefined,
+    options: ScheduledWorkspaceGitRefreshOptions,
   ): WorkspaceGitRefreshRequest {
     const scope = options?.scope;
     return {
+      origin: options.origin,
       force: options?.force === true,
       refreshStructure: scope !== "worktree" && scope !== "refs",
       refreshWorktree: scope !== "structure" && scope !== "refs",
@@ -3151,6 +3429,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       request.movedRemoteRefs,
     );
     return {
+      origin: mergeRefreshOrigins(pending.origin, request.origin),
       force,
       refreshStructure: pending.refreshStructure || request.refreshStructure,
       refreshWorktree: pending.refreshWorktree || request.refreshWorktree,
@@ -3189,13 +3468,25 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         });
       }
       try {
-        const runRefreshGitCommand = createRunGitCommand(`workspace-refresh:${request.reason}`);
+        // Demand refreshes keep the caller's lane, so a user action running at
+        // "high" is not demoted.
+        const runRefreshGitCommand = createRunGitCommand(`workspace-refresh:${request.reason}`, {
+          priority: request.origin === "observation" ? "background" : undefined,
+        });
         const admittedSnapshot = await this.workspaceRefreshLimit(() => {
-          if (target.closed || this.workspaceTargets.get(target.cwd) !== target) {
+          if (
+            target.closed ||
+            target.folderMissing ||
+            this.workspaceTargets.get(target.cwd) !== target
+          ) {
             return null;
           }
           return this.refreshSnapshot(target, request, runRefreshGitCommand);
         });
+        if (target.folderMissing) {
+          failure = null;
+          break;
+        }
         if (!admittedSnapshot) {
           break;
         }
@@ -3209,6 +3500,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         failure = { error };
       }
 
+      if (target.folderMissing) {
+        failure = null;
+        break;
+      }
       if (this.disposed || target.closed || this.workspaceTargets.get(target.cwd) !== target) {
         break;
       }
@@ -3355,6 +3650,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
     const cwd = target.cwd;
     const previousForgePrStatusPollKey = this.getForgePrStatusPollKey(target);
+    const previousBaseRef = target.latestFacts?.isGit ? target.latestFacts.resolvedBaseRef : null;
     const baseContext: CheckoutContext = {
       paseoHome: this.paseoHome,
       worktreesRoot: this.worktreesRoot,
@@ -3362,6 +3658,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       runGitCommand: runRefreshGitCommand,
     };
     const facts = await this.loadCheckoutFacts(target, baseContext);
+    if (facts.isGit && facts.resolvedBaseRef !== previousBaseRef) {
+      this.invalidateCheckoutDiffCache(cwd, "base");
+      this.invalidateCheckoutDiffCache(facts.worktreeRoot, "base");
+    }
     const context: CheckoutContext = { ...baseContext, facts };
     const checkoutStatus = await this.deps.getCheckoutStatus(cwd, context);
     if (!checkoutStatus.isGit) {
@@ -3387,12 +3687,15 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       repoRoot: checkoutStatus.repoRoot,
       mainRepoRoot: checkoutStatus.mainRepoRoot,
       currentBranch: checkoutStatus.currentBranch,
+      headSha: facts.isGit ? facts.pullRequestLookupTarget?.headSha : undefined,
       remoteUrl: checkoutStatus.remoteUrl,
       isPaseoOwnedWorktree: checkoutStatus.isPaseoOwnedWorktree,
       isDirty: refreshWorktree
         ? checkoutStatus.isDirty
         : (target.latestGit?.isDirty ?? checkoutStatus.isDirty),
       baseRef: checkoutStatus.baseRef,
+      baseRefExact: checkoutStatus.baseRefExact,
+      comparisonBaseRef: checkoutStatus.comparisonBaseRef,
       aheadBehind: checkoutStatus.aheadBehind,
       upstreamRef: checkoutStatus.upstreamRef,
       aheadOfOrigin: checkoutStatus.aheadOfOrigin,
@@ -3504,7 +3807,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     snapshot: WorkspaceGitRuntimeSnapshot,
     options?: { forceEmit?: boolean },
   ): void {
-    if (target.closed || this.workspaceTargets.get(target.cwd) !== target) {
+    if (target.closed || target.folderMissing || this.workspaceTargets.get(target.cwd) !== target) {
       return;
     }
     target.latestSnapshot = snapshot;
@@ -3557,7 +3860,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
               }
             },
           },
-          createRunGitCommand("background-fetch"),
+          createRunGitCommand("background-fetch", { priority: "background" }),
         );
       } catch (error) {
         this.logger.warn(
@@ -3660,21 +3963,25 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
   }
 
   private removeWorkspaceTarget(target: WorkspaceGitTarget): void {
-    if (target.repoGitRoot) {
-      const repoTarget = this.repoTargets.get(target.repoGitRoot);
-      repoTarget?.workspaceKeys.delete(target.cwd);
-      if (repoTarget && repoTarget.workspaceKeys.size === 0) {
-        this.closeRepoTarget(repoTarget);
-        this.repoTargets.delete(target.repoGitRoot);
-      } else if (repoTarget?.cwd === target.cwd) {
-        repoTarget.cwd = repoTarget.workspaceKeys.values().next().value ?? repoTarget.cwd;
-      }
-    }
-
+    this.detachWorkspaceFromRepoTarget(target);
     this.closeWorkspaceTarget(target);
     this.workspaceTargets.delete(target.cwd);
   }
 
+  private detachWorkspaceFromRepoTarget(target: WorkspaceGitTarget): void {
+    if (!target.repoGitRoot) {
+      return;
+    }
+    const repoTarget = this.repoTargets.get(target.repoGitRoot);
+    repoTarget?.workspaceKeys.delete(target.cwd);
+    if (repoTarget && repoTarget.workspaceKeys.size === 0) {
+      this.closeRepoTarget(repoTarget);
+      this.repoTargets.delete(target.repoGitRoot);
+    } else if (repoTarget?.cwd === target.cwd) {
+      repoTarget.cwd = repoTarget.workspaceKeys.values().next().value ?? repoTarget.cwd;
+    }
+  }
+
   private removeWorkingTreeWatchListener(cwd: string, listener: () => void): void {
     const target = this.workingTreeWatchTargets.get(cwd);
     if (!target) {
@@ -3719,6 +4026,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
   private closeWorkspaceTarget(target: WorkspaceGitTarget): void {
     target.closed = true;
+    this.stopWorkspaceObservation(target);
+    target.listeners.clear();
+  }
+
+  private stopWorkspaceObservation(target: WorkspaceGitTarget): void {
     if (target.workingTreeWatchTarget) {
       this.removeWorkspaceWorkingTreeLink(target.workingTreeWatchTarget, target.cwd);
       target.workingTreeWatchTarget = null;
@@ -3727,12 +4039,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       clearTimeout(target.debounceTimer);
       target.debounceTimer = null;
     }
+    target.pendingDebounceRequest = null;
     if (target.observationReensureTimer) {
       clearTimeout(target.observationReensureTimer);
       target.observationReensureTimer = null;
     }
     this.stopForgePrStatusPollForTarget(target);
-    target.listeners.clear();
   }
 
   private closeWorkingTreeWatchTarget(target: WorkingTreeWatchTarget): void {
diff --git a/packages/server/src/server/workspace-reconciliation-observation.test.ts b/packages/server/src/server/workspace-reconciliation-observation.test.ts
index 44bb9de08e..f8cd5f106a 100644
--- a/packages/server/src/server/workspace-reconciliation-observation.test.ts
+++ b/packages/server/src/server/workspace-reconciliation-observation.test.ts
@@ -80,7 +80,7 @@ class ObservedWorkspaceRegistry extends FileBackedWorkspaceRegistry {
     this.nextError = error;
   }
 
-  override async list() {
+  override async listActive() {
     if (this.nextRead) {
       const pending = this.nextRead;
       this.nextRead = null;
@@ -91,7 +91,7 @@ class ObservedWorkspaceRegistry extends FileBackedWorkspaceRegistry {
       this.nextError = null;
       throw error;
     }
-    return super.list();
+    return super.listActive();
   }
 }
 
diff --git a/packages/server/src/server/workspace-reconciliation-service.test.ts b/packages/server/src/server/workspace-reconciliation-service.test.ts
index b818804912..3d0057bcae 100644
--- a/packages/server/src/server/workspace-reconciliation-service.test.ts
+++ b/packages/server/src/server/workspace-reconciliation-service.test.ts
@@ -772,6 +772,62 @@ describe("WorkspaceReconciliationService", () => {
     expect(projects.get("p1")?.kind).toBe("git");
   });
 
+  test("reads sibling checkouts a few at a time in the background Git lane", async () => {
+    const projectRoot = "/reconcile/fan-out/root";
+    const { projects, workspaces, projectRegistry, workspaceRegistry } = createTestRegistries();
+    projects.set(
+      "p1",
+      createPersistedProjectRecord({
+        projectId: "p1",
+        rootPath: projectRoot,
+        kind: "git",
+        displayName: "fan-out",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      }),
+    );
+    const siblingCwds = Array.from({ length: 40 }, (_, index) => `${projectRoot}-${index}`);
+    for (const [index, cwd] of siblingCwds.entries()) {
+      workspaces.set(
+        `w${index}`,
+        createPersistedWorkspaceRecord({
+          workspaceId: `w${index}`,
+          projectId: "p1",
+          cwd,
+          kind: "worktree",
+          displayName: `sibling-${index}`,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        }),
+      );
+    }
+    const reads: Array<{ cwd: string; priority: string | undefined }> = [];
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const service = new WorkspaceReconciliationService({
+      projectRegistry,
+      workspaceRegistry,
+      logger: createTestLogger(),
+      inspectDirectory: async () => "directory",
+      workspaceGitService: {
+        async getCheckout(cwd, options) {
+          reads.push({ cwd, priority: options?.priority });
+          inFlight += 1;
+          maxInFlight = Math.max(maxInFlight, inFlight);
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          inFlight -= 1;
+          return createCheckout(cwd, { isGit: true, currentBranch: "main", worktreeRoot: cwd });
+        },
+      },
+    });
+
+    await service.runOnce();
+
+    expect(reads.map((read) => read.cwd).sort()).toEqual([projectRoot, ...siblingCwds].sort());
+    expect(new Set(reads.map((read) => read.priority))).toEqual(new Set(["background"]));
+    expect(maxInFlight).toBe(4);
+  });
+
   test("deduplicates equivalent project and workspace paths across legacy duplicate projects", async () => {
     const projectRoot = realpathSync(mkdtempSync(path.join(tmpdir(), "reconcile-global-root-")));
     const workspaceRoot = realpathSync(
@@ -1100,6 +1156,7 @@ describe("WorkspaceReconciliationService", () => {
       baseBranch: null,
       isPaseoOwnedWorktree: false,
       mainRepoRoot: null,
+      metadata: {},
       createdAt: timestamp,
       updatedAt: expect.any(String),
       archivedAt: expect.any(String),
diff --git a/packages/server/src/server/workspace-reconciliation-service.ts b/packages/server/src/server/workspace-reconciliation-service.ts
index 5333da8f83..f1fe5c9444 100644
--- a/packages/server/src/server/workspace-reconciliation-service.ts
+++ b/packages/server/src/server/workspace-reconciliation-service.ts
@@ -1,6 +1,7 @@
 import { watch as watchPath } from "node:fs";
 import { stat } from "node:fs/promises";
 import { setImmediate as yieldToLoop } from "node:timers/promises";
+import pLimit from "p-limit";
 import type { ProjectCheckoutLitePayload } from "@getpaseo/protocol/messages";
 import type pino from "pino";
 import type {
@@ -22,6 +23,9 @@ import { deriveProjectKey } from "./project-key.js";
 const DEFAULT_RESCAN_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_DEBOUNCE_MS = 100;
 const INSPECTION_CONCURRENCY = 2;
+// Each checkout read runs ~15 Git commands. Reading every sibling at once
+// queued ~1,300 commands per rescan on a project with ~90 worktrees.
+const CHECKOUT_READ_CONCURRENCY = 4;
 const DEFAULT_INSPECTION_TIMEOUT_MS = 5000;
 
 export type ProjectUpdate =
@@ -213,7 +217,7 @@ export class WorkspaceReconciliationService {
     const changes: ReconciliationChange[] = [];
     const [projects, workspaces] = await Promise.all([
       this.projectRegistry.list(),
-      this.workspaceRegistry.list(),
+      this.workspaceRegistry.listActive(),
     ]);
     const workspacesByProject = new Map<string, PersistedWorkspaceRecord[]>();
     const workspaceStates = await mapBounded(
@@ -245,7 +249,7 @@ export class WorkspaceReconciliationService {
     const changes: ReconciliationChange[] = [];
 
     const allProjects = await this.projectRegistry.list();
-    const allWorkspaces = await this.workspaceRegistry.list();
+    const allWorkspaces = await this.workspaceRegistry.listActive();
 
     const activeProjects = allProjects.filter((p) => !p.archivedAt);
     const activeProjectsById = new Map(
@@ -346,10 +350,11 @@ export class WorkspaceReconciliationService {
     changes: ReconciliationChange[],
   ): Promise<void> {
     const checkoutReads: CachedCheckoutRead[] = [];
+    const checkoutReadLimit = pLimit(CHECKOUT_READ_CONCURRENCY);
     const readCheckout = (cwd: string): Promise<ProjectCheckoutLitePayload> => {
       const existing = checkoutReads.find((read) => areEquivalentPaths(read.cwd, cwd));
       if (existing) return existing.checkout;
-      const checkout = this.readCheckout(cwd);
+      const checkout = checkoutReadLimit(() => this.readCheckout(cwd));
       checkoutReads.push({ cwd, checkout });
       return checkout;
     };
@@ -547,7 +552,7 @@ export class WorkspaceReconciliationService {
         if (change.kind === "project_updated") projectIds.add(change.projectId);
       }
       if (projectIds.size > 0) {
-        const workspaces = await this.workspaceRegistry.list();
+        const workspaces = await this.workspaceRegistry.listActive();
         for (const workspaceId of workspaceIdsForProjects(workspaces, projectIds)) {
           workspaceIds.add(workspaceId);
         }
@@ -581,7 +586,9 @@ export class WorkspaceReconciliationService {
         mainRepoRoot: null,
       };
     }
-    return this.workspaceGitService.getCheckout(cwd);
+    // Reconciliation converges in the background; it must not queue ahead of
+    // Git work a user is waiting for.
+    return this.workspaceGitService.getCheckout(cwd, { priority: "background" });
   }
 
   private wakeInspectionWaiters(): void {
diff --git a/packages/server/src/server/workspace-registry-bootstrap.test.ts b/packages/server/src/server/workspace-registry-bootstrap.test.ts
index a2a1ca5677..e8a6558b3f 100644
--- a/packages/server/src/server/workspace-registry-bootstrap.test.ts
+++ b/packages/server/src/server/workspace-registry-bootstrap.test.ts
@@ -87,7 +87,7 @@ describe("bootstrapWorkspaceRegistries", () => {
     });
 
     expect(await projectRegistry.list()).toEqual([]);
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
   });
 
   test("skips a legacy agent whose cwd is a file", async () => {
@@ -128,7 +128,7 @@ describe("bootstrapWorkspaceRegistries", () => {
     });
 
     expect(await projectRegistry.list()).toEqual([]);
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
   });
 
   test("propagates a Git failure for an existing legacy directory", async () => {
@@ -233,7 +233,7 @@ describe("bootstrapWorkspaceRegistries", () => {
       logger,
     });
 
-    const workspaces = await workspaceRegistry.list();
+    const workspaces = await workspaceRegistry.listAll();
     expect(workspaces).toHaveLength(1);
     expect(workspaces[0]?.workspaceId).toMatch(/^wks_[0-9a-f]{16}$/);
     expect(workspaces[0]?.cwd).toBe(NON_GIT_PROJECT);
@@ -307,8 +307,8 @@ describe("bootstrapWorkspaceRegistries", () => {
     });
 
     expect(await projectRegistry.list()).toHaveLength(1);
-    expect(await workspaceRegistry.list()).toHaveLength(1);
-    expect((await workspaceRegistry.list())[0]?.workspaceId).toBe("ws-existing");
+    expect(await workspaceRegistry.listAll()).toHaveLength(1);
+    expect((await workspaceRegistry.listAll())[0]?.workspaceId).toBe("ws-existing");
   });
 
   test("materializes legacy remote worktrees into one readable project", async () => {
@@ -366,7 +366,7 @@ describe("bootstrapWorkspaceRegistries", () => {
       displayName: "acme/legacy-project",
     });
 
-    const workspaces = await workspaceRegistry.list();
+    const workspaces = await workspaceRegistry.listAll();
     expect(
       workspaces
         .map(({ projectId, cwd, kind, displayName }) => ({ projectId, cwd, kind, displayName }))
@@ -449,7 +449,7 @@ describe("bootstrapWorkspaceRegistries", () => {
     });
 
     expect((await agentStorage.get("legacy-agent"))?.workspaceId).toBe("ws-older");
-    expect(await workspaceRegistry.list()).toHaveLength(2);
+    expect(await workspaceRegistry.listAll()).toHaveLength(2);
   });
 
   test("migrated legacy agents stay owned by the deterministic workspace when a same-cwd workspace is added later", async () => {
@@ -568,7 +568,7 @@ describe("bootstrapWorkspaceRegistries", () => {
       logger,
     });
 
-    const workspaces = await workspaceRegistry.list();
+    const workspaces = await workspaceRegistry.listAll();
     expect(workspaces).toHaveLength(1);
     expect(workspaces[0]?.workspaceId).toBe("ws-existing");
     expect(workspaces[0]?.cwd).toBe(NON_GIT_PROJECT);
diff --git a/packages/server/src/server/workspace-registry-bootstrap.ts b/packages/server/src/server/workspace-registry-bootstrap.ts
index 817853dad9..7b9770fff2 100644
--- a/packages/server/src/server/workspace-registry-bootstrap.ts
+++ b/packages/server/src/server/workspace-registry-bootstrap.ts
@@ -64,7 +64,7 @@ export async function bootstrapWorkspaceRegistries(options: {
   // COMPAT(worktree-branch-identity): added in v0.4.0 on 2026-08-15; remove after
   // 2027-02-15. Older worktrees did not pin branch-off/check-out branch identity.
   // Seed it from the registry value clients already display, never from live Git.
-  for (const workspace of await options.workspaceRegistry.list()) {
+  for (const workspace of await options.workspaceRegistry.listActive()) {
     if (
       workspace.archivedAt ||
       !workspace.isPaseoOwnedWorktree ||
@@ -89,12 +89,14 @@ export async function bootstrapWorkspaceRegistries(options: {
   }
 
   const existingWorkspaceIdsByCwd = new Map(
-    (await options.workspaceRegistry.list()).map((workspace) => [
+    // Startup backfill resolves workspace ownership across archived records too.
+    (await options.workspaceRegistry.listAll()).map((workspace) => [
       path.resolve(workspace.cwd),
       workspace.workspaceId,
     ]),
   );
-  const records = await options.agentStorage.list();
+  // Startup backfill repairs agents without workspace membership, including archived history.
+  const records = await options.agentStorage.listAll();
   // A legacy agent can outlive its working directory. Reconciliation treats a
   // missing directory as absent rather than asking Git about it; bootstrap must
   // do the same before materializing its first workspace record.
diff --git a/packages/server/src/server/workspace-registry-model.ts b/packages/server/src/server/workspace-registry-model.ts
index 181ec96eae..3170281d60 100644
--- a/packages/server/src/server/workspace-registry-model.ts
+++ b/packages/server/src/server/workspace-registry-model.ts
@@ -108,7 +108,7 @@ export function initialWorkspacePlacement(
 
 /**
  * Applies live placement facts without rewriting the workspace's durable name
- * or its creation-time base branch.
+ * or its selected base branch.
  *
  * A null checkout is an absence, not an observation: nothing was read at the
  * workspace directory, so the recorded placement stands. Only a directory that
diff --git a/packages/server/src/server/workspace-registry.test.ts b/packages/server/src/server/workspace-registry.test.ts
index 15031e7b69..c26a2fe447 100644
--- a/packages/server/src/server/workspace-registry.test.ts
+++ b/packages/server/src/server/workspace-registry.test.ts
@@ -500,7 +500,7 @@ describe("workspace registries", () => {
       workspace: archived,
     });
     expect(await workspaceRegistry.get("/tmp/repo")).toBeNull();
-    expect(await workspaceRegistry.list()).toEqual([]);
+    expect(await workspaceRegistry.listAll()).toEqual([]);
   });
 
   test("preserves the first workspace archive and reports whether a queued archive applied", async () => {
diff --git a/packages/server/src/server/workspace-registry.ts b/packages/server/src/server/workspace-registry.ts
index 61fcb4f720..fd376cc14c 100644
--- a/packages/server/src/server/workspace-registry.ts
+++ b/packages/server/src/server/workspace-registry.ts
@@ -1,3 +1,4 @@
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
 import { promises as fs } from "node:fs";
 
 import type { Logger } from "pino";
@@ -49,6 +50,7 @@ const PersistedProjectRecordSchema = z.object({
 });
 
 const PersistedWorkspaceRecordSchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -75,9 +77,9 @@ const PersistedWorkspaceRecordSchema = z.object({
   // archive and recovery do not need the directory to still exist in order to
   // recover placement.
   worktreeRoot: z.string().nullable().default(null),
-  // Comparison base preserved across worktree deletion and restore. New branch-off
+  // Current base preserved across worktree deletion and restore. New branch-off
   // workspaces store the resolved ref (e.g. refs/remotes/upstream/main); legacy and
-  // PR checkout records may contain a bare branch name. Ordinary checkouts use null.
+  // PR checkout records may contain a bare branch name. Null means no recorded base.
   baseBranch: z
     .string()
     .nullable()
@@ -101,6 +103,8 @@ const PersistedWorkspaceRecordSchema = z.object({
     .optional()
     .transform((value) => value ?? null),
   labels: z.array(z.string()).optional(),
+  // Plugin-owned data. Paseo stores it and never reads a key.
+  metadata: z.record(z.string(), z.custom<JsonValue>()).default({}),
   untrustedSource: UntrustedWorkspaceSourceSchema.optional(),
   // Public discovery visibility. Contents retain their ordinary lifecycle.
   background: z.boolean().optional().default(false),
@@ -156,7 +160,8 @@ export interface ProjectRegistry {
 export interface WorkspaceRegistry {
   initialize(): Promise<void>;
   existsOnDisk(): Promise<boolean>;
-  list(): Promise<PersistedWorkspaceRecord[]>;
+  listAll(): Promise<PersistedWorkspaceRecord[]>;
+  listActive(): Promise<PersistedWorkspaceRecord[]>;
   get(workspaceId: string): Promise<PersistedWorkspaceRecord | null>;
   update(
     workspaceId: string,
@@ -182,6 +187,7 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
   protected readonly logger: Logger;
   private readonly schema: z.ZodType<TRecord, unknown>;
   private readonly getId: (record: TRecord) => string;
+  private readonly activeIds = new Set<string>();
   private loaded = false;
   private readonly cache = new Map<string, TRecord>();
   private mutationQueue: Promise<void> = Promise.resolve();
@@ -219,11 +225,16 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
     }
   }
 
-  async list(): Promise<TRecord[]> {
+  async listAll(): Promise<TRecord[]> {
     await this.load();
     return Array.from(this.cache.values());
   }
 
+  async listActive(): Promise<TRecord[]> {
+    await this.load();
+    return Array.from(this.activeIds, (id) => this.cache.get(id)!);
+  }
+
   async get(id: string): Promise<TRecord | null> {
     await this.load();
     return this.cache.get(id) ?? null;
@@ -288,6 +299,7 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
         this.logger.error({ err: error, filePath: this.filePath }, "Failed to load registry file");
       }
     }
+    this.rebuildActiveIndex();
     this.loaded = true;
   }
 
@@ -335,6 +347,7 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
         this.cache.clear();
         for (const [id, record] of staged) this.cache.set(id, record);
       }
+      this.rebuildActiveIndex();
       hooks?.afterCommit?.();
       return result;
     } finally {
@@ -342,6 +355,11 @@ class FileBackedRegistry<TRecord extends RegistryRecord> {
     }
   }
 
+  private rebuildActiveIndex(): void {
+    this.activeIds.clear();
+    for (const [id, record] of this.cache) if (!record.archivedAt) this.activeIds.add(id);
+  }
+
   protected freezeMutationsUntilRestart(): void {
     this.mutationsBlockedUntilRestart = true;
   }
@@ -359,6 +377,10 @@ export class FileBackedProjectRegistry
   extends FileBackedRegistry<PersistedProjectRecord>
   implements ProjectRegistry
 {
+  async list(): Promise<PersistedProjectRecord[]> {
+    return this.listAll();
+  }
+
   private allocationQueue: Promise<void> = Promise.resolve();
   private readonly projectIdFactory: () => string;
   private readonly mutationListeners = new Set<
@@ -661,6 +683,7 @@ export function resolveProjectDisplayName(record: PersistedProjectRecord): strin
 }
 
 export function createPersistedWorkspaceRecord(input: {
+  parentWorkspaceId?: string;
   workspaceId: string;
   projectId: string;
   cwd: string;
@@ -678,6 +701,7 @@ export function createPersistedWorkspaceRecord(input: {
   autoArchivedChangeRequestUrl?: string | null;
   pinnedAt?: string | null;
   labels?: string[];
+  metadata?: Record<string, JsonValue>;
   untrustedSource?: UntrustedWorkspaceSource;
   background?: boolean;
 }): PersistedWorkspaceRecord {
diff --git a/packages/server/src/server/workspace-script-runtime-store.test.ts b/packages/server/src/server/workspace-script-runtime-store.test.ts
index 625d1f2fe9..8b33d4ea53 100644
--- a/packages/server/src/server/workspace-script-runtime-store.test.ts
+++ b/packages/server/src/server/workspace-script-runtime-store.test.ts
@@ -97,3 +97,16 @@ describe("WorkspaceScriptRuntimeStore", () => {
     ]);
   });
 });
+
+it("notifies terminal metadata consumers when script ownership changes", () => {
+  const store = new WorkspaceScriptRuntimeStore();
+  const observed: string[][] = [];
+  const release = store.subscribe(() =>
+    observed.push(store.listForWorkspace("workspace-101").map((entry) => entry.terminalId)),
+  );
+  store.set(createEntry());
+  store.remove({ workspaceId: "workspace-101", scriptName: "web" });
+  release();
+  store.set(createEntry());
+  expect(observed).toEqual([["terminal-1"], []]);
+});
diff --git a/packages/server/src/server/workspace-script-runtime-store.ts b/packages/server/src/server/workspace-script-runtime-store.ts
index a2f48199b6..f8f0ca0698 100644
--- a/packages/server/src/server/workspace-script-runtime-store.ts
+++ b/packages/server/src/server/workspace-script-runtime-store.ts
@@ -13,6 +13,17 @@ interface RuntimeEntryKey {
 }
 
 export class WorkspaceScriptRuntimeStore {
+  private readonly listeners = new Set<() => void>();
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  private changed(): void {
+    for (const listener of this.listeners) listener();
+  }
+
   private readonly entries = new Map<string, ScriptRuntimeEntry>();
   private readonly scriptsByWorkspace = new Map<string, Set<string>>();
 
@@ -31,6 +42,7 @@ export class WorkspaceScriptRuntimeStore {
 
     this.entries.set(entryKey, { ...entry });
     this.addScriptToWorkspaceIndex(workspaceKey, entry.scriptName);
+    this.changed();
   }
 
   remove(key: RuntimeEntryKey): void {
@@ -42,6 +54,7 @@ export class WorkspaceScriptRuntimeStore {
 
     this.entries.delete(entryKey);
     this.removeScriptFromWorkspaceIndex(existing.workspaceId, existing.scriptName);
+    this.changed();
   }
 
   listForWorkspace(workspaceId: string): ScriptRuntimeEntry[] {
@@ -70,6 +83,7 @@ export class WorkspaceScriptRuntimeStore {
       this.entries.delete(this.toEntryKey(entry));
     }
     this.scriptsByWorkspace.delete(this.toWorkspaceKey(workspaceId));
+    this.changed();
   }
 
   isRunning(key: RuntimeEntryKey): boolean {
diff --git a/packages/server/src/server/worktree-bootstrap.test.ts b/packages/server/src/server/worktree-bootstrap.test.ts
index ed43e02388..a32407f0a2 100644
--- a/packages/server/src/server/worktree-bootstrap.test.ts
+++ b/packages/server/src/server/worktree-bootstrap.test.ts
@@ -1,8 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, onTestFinished } from "vitest";
 import { execFileSync } from "child_process";
 import { mkdtempSync, realpathSync, rmSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+import { createServer } from "node:net";
+import { promisify } from "node:util";
 import {
   buildWorktreeSetupDetail,
   runWorktreeAutoTerminals,
@@ -943,6 +945,15 @@ describe("runWorktreeAutoTerminals", () => {
     });
     expect(routeStore.getRouteEntry("api--feature-respawn-service--repo.localhost")).toBeNull();
 
+    // A released ephemeral port can be allocated again. Occupy the old port so
+    // this journey requires a different port when the service is restarted.
+    const occupiedPort = createServer();
+    onTestFinished(() => promisify(occupiedPort.close.bind(occupiedPort))());
+    await new Promise<void>((resolve, reject) => {
+      occupiedPort.once("error", reject);
+      occupiedPort.listen(firstPort, "127.0.0.1", resolve);
+    });
+
     const secondResult = await spawnWorkspaceScript({
       repoRoot: repoDir,
       workspaceId: repoDir,
@@ -962,6 +973,7 @@ describe("runWorktreeAutoTerminals", () => {
     }
     expect(secondPort).not.toBe(firstPort);
     expect(secondPort).toEqual(expect.any(Number));
+    expect(createTerminalCalls[2]?.env?.PASEO_PORT).toBe(String(secondPort));
     expect(createTerminalCalls[2]?.env?.PASEO_SERVICE_WORKER_PORT).toBe(String(workerPort));
     expect(routeStore.getRouteEntry("api--feature-respawn-service--repo.localhost")).toMatchObject({
       hostname: "api--feature-respawn-service--repo.localhost",
diff --git a/packages/server/src/server/worktree-session.test.ts b/packages/server/src/server/worktree-session.test.ts
index 7117aa2501..845e8e0a75 100644
--- a/packages/server/src/server/worktree-session.test.ts
+++ b/packages/server/src/server/worktree-session.test.ts
@@ -331,7 +331,8 @@ function createPaseoWorktreeForTest(options: {
   const workspaceRegistry: WorkspaceRegistry = {
     initialize: async () => {},
     existsOnDisk: async () => true,
-    list: async () => Array.from(workspaces.values()),
+    listAll: async () => Array.from(workspaces.values()),
+    listActive: async () => Array.from(workspaces.values()).filter((w) => !w.archivedAt),
     get: async (workspaceId) => workspaces.get(workspaceId) ?? null,
     update: async (workspaceId, updater) => {
       const workspace = workspaces.get(workspaceId);
@@ -477,9 +478,9 @@ describe("create-agent worktree setup boundary", () => {
   });
 });
 
-function createAgentStorageStub(): Pick<AgentStorage, "list"> {
+function createAgentStorageStub(): Pick<AgentStorage, "listAll"> {
   return {
-    list: async (): Promise<StoredAgentRecord[]> => [],
+    listAll: async (): Promise<StoredAgentRecord[]> => [],
   };
 }
 
@@ -550,44 +551,45 @@ function createGitHubPrRemoteRepo() {
 
 describe("runWorktreeSetupInBackground", () => {
   const cleanupPaths: string[] = [];
+  let stopSetup: (() => Promise<void>) | undefined;
 
-  afterEach(() => {
+  afterEach(async () => {
+    await stopSetup?.();
+    stopSetup = undefined;
     for (const target of cleanupPaths.splice(0)) {
       rmSync(target, { recursive: true, force: true });
     }
   });
 
-  test("runs setup from an exact workspace subdirectory", async () => {
-    const { tempDir, repoDir } = createGitRepo();
+  function startSubdirectorySetup(command: string) {
+    const tempDir = realpathSync.native(mkdtempSync(path.join(tmpdir(), "worktree-setup-test-")));
     cleanupPaths.push(tempDir);
+    const repoDir = path.join(tempDir, "source");
     const sourceWorkspaceCwd = path.join(repoDir, "packages", "app");
+    const worktree: WorktreeConfig = {
+      branchName: "feature-subdirectory-setup",
+      worktreePath: path.join(tempDir, "worktree"),
+    };
+    const workspaceCwd = path.join(worktree.worktreePath, "packages", "app");
+    // Setup consumes an existing workspace. Git creation is covered by the workflow tests.
     mkdirSync(sourceWorkspaceCwd, { recursive: true });
+    mkdirSync(workspaceCwd, { recursive: true });
+    execFileSync("git", ["init", "-b", worktree.branchName], {
+      cwd: worktree.worktreePath,
+      stdio: "pipe",
+    });
     writeFileSync(
-      path.join(sourceWorkspaceCwd, "paseo.json"),
+      path.join(workspaceCwd, "paseo.json"),
       JSON.stringify({
         worktree: {
-          setup: ["pwd > setup-cwd.txt"],
+          setup: [command],
         },
       }),
     );
-    execFileSync("git", ["add", "."], { cwd: repoDir, stdio: "pipe" });
-    execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-m", "add app setup"], {
-      cwd: repoDir,
-      stdio: "pipe",
-    });
-
     const paseoHome = path.join(tempDir, ".paseo");
-    const createdWorktree = await createLegacyWorktreeForTest({
-      branchName: "feature-subdirectory-setup",
-      cwd: repoDir,
-      baseBranch: "main",
-      worktreeSlug: "feature-subdirectory-setup",
 
-      paseoHome,
-    });
-    const workspaceCwd = path.join(createdWorktree.worktreePath, "packages", "app");
-
-    await runWorktreeSetupInBackground(
+    const controller = new AbortController();
+    const completion = runWorktreeSetupInBackground(
       {
         paseoHome,
         emitWorkspaceUpdateForWorkspaceId: async () => {},
@@ -600,16 +602,62 @@ describe("runWorktreeSetupInBackground", () => {
         requestCwd: sourceWorkspaceCwd,
         repoRoot: repoDir,
         workspaceId: "ws-subdirectory-setup",
-        worktree: createdWorktree,
+        worktree,
         shouldBootstrap: true,
         slug: "feature-subdirectory-setup",
-        worktreePath: createdWorktree.worktreePath,
+        worktreePath: worktree.worktreePath,
         workspaceCwd,
       },
+      controller.signal,
     );
+    const stop = async () => {
+      controller.abort();
+      await completion;
+    };
+    stopSetup = stop;
+    return { tempDir, workspaceCwd, worktreePath: worktree.worktreePath, completion, stop };
+  }
 
-    expect(existsSync(path.join(workspaceCwd, "setup-cwd.txt"))).toBe(true);
-    expect(existsSync(path.join(createdWorktree.worktreePath, "setup-cwd.txt"))).toBe(false);
+  test("runs setup from an exact workspace subdirectory", async () => {
+    const setup = startSubdirectorySetup("pwd > setup-cwd.txt");
+    await setup.completion;
+
+    expect(existsSync(path.join(setup.workspaceCwd, "setup-cwd.txt"))).toBe(true);
+    expect(existsSync(path.join(setup.worktreePath, "setup-cwd.txt"))).toBe(false);
+  });
+
+  test("teardown stops unfinished setup before removing its workspace", async ({
+    onTestFinished,
+  }) => {
+    const setup = startSubdirectorySetup(
+      `node -e "require('fs').writeFileSync('setup-pid.txt', String(process.pid)); setInterval(()=>{},1000)"`,
+    );
+    let pid = 0;
+    const probeChild = () => process.kill(pid, 0);
+    onTestFinished(async () => {
+      try {
+        expect(pid).toBeGreaterThan(0);
+        expect(existsSync(setup.tempDir)).toBe(false);
+        expect(probeChild).toThrow(expect.objectContaining({ code: "ESRCH" }));
+      } finally {
+        // Keep a failing cleanup regression from leaking its deliberately live child.
+        await setup.stop();
+      }
+    });
+    await expect
+      .poll(
+        () => {
+          try {
+            pid = Number(readFileSync(path.join(setup.workspaceCwd, "setup-pid.txt"), "utf8"));
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+            pid = 0;
+          }
+          return pid;
+        },
+        { timeout: 30_000 },
+      )
+      .toBeGreaterThan(0);
   });
 
   test("emits running then completed snapshots for no-setup workspaces without auto-starting scripts", async () => {
diff --git a/packages/server/src/services/forge-service.ts b/packages/server/src/services/forge-service.ts
index 8499cc8756..d676304f79 100644
--- a/packages/server/src/services/forge-service.ts
+++ b/packages/server/src/services/forge-service.ts
@@ -128,6 +128,7 @@ export interface CurrentPullRequestStatus {
   state: string;
   baseRefName: string;
   headRefName: string;
+  headSha?: string;
   isMerged: boolean;
   isDraft?: boolean;
   mergeable: PullRequestMergeable;
diff --git a/packages/server/src/services/gitea-service.test.ts b/packages/server/src/services/gitea-service.test.ts
index 9e3a3ecc62..44d263791f 100644
--- a/packages/server/src/services/gitea-service.test.ts
+++ b/packages/server/src/services/gitea-service.test.ts
@@ -2064,7 +2064,7 @@ describe("createGiteaService", () => {
     ]);
   });
 
-  it("does not attach a stale Gitea-family PR after a same-name branch advances", async () => {
+  it("keeps a merged PR when its remote head advances beyond the checkout", async () => {
     const stale = currentPullRequestApi({
       number: 8,
       state: "closed",
@@ -2086,7 +2086,7 @@ describe("createGiteaService", () => {
         headRef: "dev",
         headSha: "2222222222222222222222222222222222222222",
       }),
-    ).resolves.toBeNull();
+    ).resolves.toMatchObject({ number: 8, state: "merged" });
   });
 
   it("returns null when no PR matches the current branch", async () => {
diff --git a/packages/server/src/services/gitea-service.ts b/packages/server/src/services/gitea-service.ts
index 892f9cc33a..ef1df9f888 100644
--- a/packages/server/src/services/gitea-service.ts
+++ b/packages/server/src/services/gitea-service.ts
@@ -162,6 +162,7 @@ const GiteaPrListItemSchema = z
     updated: z.string().optional(),
     labels: z.string().optional(),
     ci: z.string().optional(),
+    headSha: z.string().optional(),
   })
   .passthrough();
 
@@ -1010,6 +1011,7 @@ function currentPullRequestApiToListItem(item: GiteaCurrentPullRequestApi): Gite
     ...(item.mergeable != null ? { mergeable: String(item.mergeable) } : {}),
     base: item.base.ref,
     head,
+    headSha: item.head.sha,
     updated: item.updated_at,
     labels: item.labels.map((label) => label.name).join(","),
   };
@@ -1082,6 +1084,7 @@ function toCurrentPullRequestStatus(item: GiteaPrListItem): CurrentPullRequestSt
     state,
     baseRefName: item.base ?? "",
     headRefName: stripHeadOwner(item.head),
+    ...(item.headSha ? { headSha: item.headSha } : {}),
     isMerged: state === "merged",
     mergeable: mapGiteaMergeable(item),
     checks: [],
@@ -1653,6 +1656,7 @@ export function createGiteaService(options: CreateGiteaServiceOptions = {}): For
           input.headSha !== undefined &&
           item.head.sha === input.headSha,
       ) ??
+      candidates[0] ??
       null;
     return match ? currentPullRequestApiToListItem(match) : null;
   }
@@ -1718,7 +1722,12 @@ export function createGiteaService(options: CreateGiteaServiceOptions = {}): For
         combined,
         actionTasks,
       );
-      return applyGiteaChecks(status, combined, actionTasks, actionRequiredRunIds);
+      return applyGiteaChecks(
+        { ...status, headSha: pr.headSha },
+        combined,
+        actionTasks,
+        actionRequiredRunIds,
+      );
     } catch {
       return status;
     }
diff --git a/packages/server/src/services/github-service.test.ts b/packages/server/src/services/github-service.test.ts
index 3109bcc63c..0b97f551bb 100644
--- a/packages/server/src/services/github-service.test.ts
+++ b/packages/server/src/services/github-service.test.ts
@@ -23,7 +23,7 @@ const EXPECTED_GITHUB_FAST_POLL_MS = 20_000;
 const EXPECTED_GITHUB_SLOW_POLL_MS = 120_000;
 const EXPECTED_GITHUB_ERROR_BACKOFF_CAP_MS = 300_000;
 const CURRENT_PR_STATUS_BASE_FIELDS =
-  "number,url,title,state,isDraft,baseRefName,headRefName,headRefOid,mergedAt,reviewDecision,mergeable,headRepositoryOwner";
+  "number,url,title,state,isDraft,baseRefName,headRefName,headRefOid,updatedAt,mergedAt,reviewDecision,mergeable,headRepositoryOwner";
 const CURRENT_PR_STATUS_FIELDS = `${CURRENT_PR_STATUS_BASE_FIELDS},statusCheckRollup`;
 const FORK_PR_QUERY = "state=all&per_page=100&head=forkOwner%3Afeature%2Ffork";
 
@@ -3219,7 +3219,7 @@ describe("ForgeService", () => {
     });
   });
 
-  it("keeps a merged PR only when headRefOid matches the checkout HEAD", async () => {
+  it("keeps a merged PR when headRefOid matches the checkout HEAD", async () => {
     const headSha = "2222222222222222222222222222222222222222";
     const runner = createRunner([
       currentPullRequestJson({
@@ -3243,8 +3243,9 @@ describe("ForgeService", () => {
     expect(status?.state).toBe("merged");
   });
 
-  it("does not attach a stale merged PR after a same-name branch advances", async () => {
+  it("keeps a merged PR when its remote head advances beyond the checkout", async () => {
     const stale = currentPullRequestJson({
+      headRepositoryOwner: { login: "parentOwner" },
       state: "MERGED",
       mergedAt: "2026-07-17T12:00:00Z",
       headRefOid: "1111111111111111111111111111111111111111",
@@ -3265,12 +3266,105 @@ describe("ForgeService", () => {
         headRef: "feature/fork",
         headSha: "2222222222222222222222222222222222222222",
       }),
-    ).resolves.toBeNull();
+    ).resolves.toMatchObject({ state: "merged" });
     expect(runner.calls.some((call) => call.args[0] === "pr" && call.args[1] === "list")).toBe(
       true,
     );
   });
 
+  it("prefers an exact terminal head and otherwise the most recently updated terminal PR", async () => {
+    const owner = { login: "forkOwner" };
+    const terminal = ({
+      number,
+      headRefOid,
+      updatedAt,
+      state,
+    }: {
+      number: number;
+      headRefOid: string;
+      updatedAt: string;
+      state: string;
+    }) =>
+      JSON.parse(
+        currentPullRequestJson({
+          number,
+          headRefOid,
+          updatedAt,
+          state,
+          mergedAt: state === "MERGED" ? updatedAt : null,
+          headRepositoryOwner: owner,
+        }),
+      );
+    const older = terminal({
+      number: 41,
+      headRefOid: "old",
+      updatedAt: "2026-07-01T00:00:00Z",
+      state: "MERGED",
+    });
+    const newer = terminal({
+      number: 42,
+      headRefOid: "new",
+      updatedAt: "2026-07-02T00:00:00Z",
+      state: "CLOSED",
+    });
+    for (const [headSha, expected] of [
+      ["old", 41],
+      ["other", 42],
+    ] as const) {
+      const runner = createScriptedRunner([JSON.stringify(older), JSON.stringify([older, newer])]);
+      const service = createGitHubService({
+        runner: runner.runner,
+        resolveGhPath: async () => "/usr/bin/gh",
+      });
+      const status = await service.getCurrentPullRequestStatus({
+        cwd: "/repo",
+        headRef: "feature/fork",
+        headRepositoryOwner: "forkOwner",
+        headSha,
+      });
+      expect(status?.number).toBe(expected);
+    }
+  });
+
+  it("prefers an exact merged PR over a closed draft", async () => {
+    const owner = { login: "forkOwner" };
+    const closedDraft = JSON.parse(
+      currentPullRequestJson({
+        number: 1,
+        state: "CLOSED",
+        isDraft: true,
+        headRefOid: "old",
+        updatedAt: "2026-07-01T00:00:00Z",
+        headRepositoryOwner: owner,
+      }),
+    );
+    const merged = JSON.parse(
+      currentPullRequestJson({
+        number: 2,
+        state: "MERGED",
+        mergedAt: "2026-07-02T00:00:00Z",
+        headRefOid: "exact",
+        updatedAt: "2026-07-02T00:00:00Z",
+        headRepositoryOwner: owner,
+      }),
+    );
+    const runner = createScriptedRunner([
+      JSON.stringify(closedDraft),
+      JSON.stringify([closedDraft, merged]),
+    ]);
+    const service = createGitHubService({
+      runner: runner.runner,
+      resolveGhPath: async () => "/usr/bin/gh",
+    });
+    const status = await service.getCurrentPullRequestStatus({
+      cwd: "/repo",
+      headRef: "feature/fork",
+      headRepositoryOwner: "forkOwner",
+      headSha: "exact",
+    });
+    expect(status).toMatchObject({ number: 2, state: "merged" });
+  });
+
   it("prefers an open PR over an exact-SHA merged PR for the same head", async () => {
     const checkoutSha = "2222222222222222222222222222222222222222";
     const owner = { login: "forkOwner" };
@@ -3313,6 +3407,84 @@ describe("ForgeService", () => {
     expect(status).toMatchObject({ number: 43, state: "open" });
   });
 
+  it("keeps a merged PR targeting the fork itself", async () => {
+    const runner = createScriptedRunner([
+      currentPullRequestJson({
+        number: 7,
+        url: "https://github.com/alice/app/pull/7",
+        state: "MERGED",
+        mergedAt: "2026-07-17T12:00:00Z",
+        headRefOid: "checkout-head",
+        headRepositoryOwner: { login: "alice" },
+      }),
+      JSON.stringify({
+        owner: { login: "alice" },
+        name: "app",
+        parent: { owner: { login: "acme" }, name: "app" },
+      }),
+      "[]",
+    ]);
+    const service = createGitHubService({
+      runner: runner.runner,
+      resolveGhPath: async () => "/usr/bin/gh",
+    });
+    const status = await service.getCurrentPullRequestStatus({
+      cwd: "/repo",
+      headRef: "feature/fork",
+      headSha: "checkout-head",
+    });
+    expect(status).toMatchObject({ number: 7, repoOwner: "alice", state: "merged" });
+  });
+
+  it("compares the fork's terminal PR against parent PRs by state, head and update time", async () => {
+    const local = JSON.parse(
+      currentPullRequestJson({
+        number: 7,
+        url: "https://github.com/alice/app/pull/7",
+        state: "MERGED",
+        mergedAt: "2026-07-17T12:00:00Z",
+        updatedAt: "2026-07-17T12:00:00Z",
+        headRefOid: "local-head",
+        headRepositoryOwner: { login: "alice" },
+      }),
+    );
+    for (const [state, headSha, updatedAt, expected] of [
+      ["OPEN", "other", "2026-07-16T12:00:00Z", 8],
+      ["CLOSED", "other", "2026-07-18T12:00:00Z", 7],
+      ["CLOSED", "other", "2026-07-18T12:00:00Z", 8],
+    ] as const) {
+      const parent = {
+        ...local,
+        number: 8,
+        url: "https://github.com/acme/app/pull/8",
+        state,
+        mergedAt: null,
+        headRefOid: headSha,
+        updatedAt,
+      };
+      const runner = createScriptedRunner([
+        JSON.stringify(local),
+        JSON.stringify({
+          owner: { login: "alice" },
+          name: "app",
+          parent: { owner: { login: "acme" }, name: "app" },
+        }),
+        JSON.stringify([{ number: 8 }]),
+        JSON.stringify(parent),
+      ]);
+      const service = createGitHubService({
+        runner: runner.runner,
+        resolveGhPath: async () => "/usr/bin/gh",
+      });
+      const status = await service.getCurrentPullRequestStatus({
+        cwd: "/repo",
+        headRef: "feature/fork",
+        headSha: state === "OPEN" || expected === 7 ? "local-head" : "neither",
+      });
+      expect(status?.number).toBe(expected);
+    }
+  });
+
   it("resolves fork PR heads to the parent repository when gh pr view returns a stale branch match", async () => {
     const runner = createScriptedRunner([
       currentPullRequestJson({
diff --git a/packages/server/src/services/github-service.ts b/packages/server/src/services/github-service.ts
index 2dd3fdc269..04731b63d2 100644
--- a/packages/server/src/services/github-service.ts
+++ b/packages/server/src/services/github-service.ts
@@ -346,6 +346,7 @@ const CurrentPullRequestStatusSchema = z.object({
   baseRefName: z.string().catch(""),
   headRefName: z.string().catch(""),
   headRefOid: z.string().optional(),
+  updatedAt: z.string().optional(),
   mergedAt: z.string().nullable().optional(),
   statusCheckRollup: z.unknown().optional(),
   reviewDecision: z.unknown().optional(),
@@ -524,7 +525,7 @@ query PullRequestCheckoutTarget($owner: String!, $name: String!, $number: Int!)
 }`;
 
 const CURRENT_PR_STATUS_BASE_FIELDS =
-  "number,url,title,state,isDraft,baseRefName,headRefName,headRefOid,mergedAt,reviewDecision,mergeable,headRepositoryOwner";
+  "number,url,title,state,isDraft,baseRefName,headRefName,headRefOid,updatedAt,mergedAt,reviewDecision,mergeable,headRepositoryOwner";
 const CURRENT_PR_STATUS_FIELDS = `${CURRENT_PR_STATUS_BASE_FIELDS},statusCheckRollup`;
 
 const PULL_REQUEST_STATUS_FACTS_QUERY = `
@@ -640,6 +641,7 @@ const BatchPollPrNodeSchema = z.object({
   baseRefName: z.string().catch(""),
   headRefName: z.string().catch(""),
   headRefOid: z.string().catch(""),
+  updatedAt: z.string().optional(),
   mergedAt: z.string().nullable().optional(),
   mergeable: PullRequestMergeableSchema.optional().default("UNKNOWN"),
   reviewDecision: z.unknown().optional(),
@@ -744,6 +746,7 @@ fragment PaseoPollPullRequest on PullRequest {
   baseRefName
   headRefName
   headRefOid
+  updatedAt
   mergedAt
   mergeable
   reviewDecision
@@ -1118,6 +1121,7 @@ interface ResolvedPullRequestCandidate {
   status: CurrentPullRequestStatus;
   headSha?: string;
   headRepositoryOwner?: string;
+  updatedAt?: string;
 }
 
 export function createGitHubService(options: CreateGitHubServiceOptions = {}): GitHubService {
@@ -2968,7 +2972,7 @@ async function resolveCurrentPullRequestView(options: {
         headRepositoryOwner: options.headRepositoryOwner,
       })
     : null;
-  if (viewMatch) {
+  if (viewMatch?.status.state === "open") {
     return viewMatch.status;
   }
 
@@ -2980,12 +2984,13 @@ async function resolveCurrentPullRequestView(options: {
     const parentOwner = repo?.parent?.owner?.login;
     const parentName = repo?.parent?.name;
     if (!forkOwner) {
-      return null;
+      return viewMatch?.status ?? null;
     }
     if (parentOwner && parentName) {
       return resolveForkPullRequestView({
         ...options,
         forkOwner,
+        viewMatch,
         repo: `${parentOwner}/${parentName}`,
       });
     }
@@ -2998,7 +3003,7 @@ async function resolveCurrentPullRequestView(options: {
     run: options.run,
   });
   const match = pickPullRequestCandidate({
-    candidates,
+    candidates: viewMatch ? [...candidates, viewMatch] : candidates,
     headRef: options.headRef,
     headSha: options.headSha,
     headRepositoryOwner,
@@ -3019,6 +3024,7 @@ async function resolveForkPullRequestView(options: {
   headRef: string;
   headSha?: string;
   forkOwner: string;
+  viewMatch: ResolvedPullRequestCandidate | null;
   repo: string;
   run: (args: string[], options: GitHubCommandRunnerOptions) => Promise<string>;
 }): Promise<CurrentPullRequestStatus | null> {
@@ -3034,12 +3040,15 @@ async function resolveForkPullRequestView(options: {
     ),
   );
   const match = pickPullRequestCandidate({
-    candidates: candidates.filter(
-      (candidate): candidate is ResolvedPullRequestCandidate => candidate !== null,
-    ),
+    candidates: [
+      ...candidates.filter(
+        (candidate): candidate is ResolvedPullRequestCandidate =>
+          candidate !== null && candidate.headRepositoryOwner === options.forkOwner,
+      ),
+      ...(options.viewMatch ? [options.viewMatch] : []),
+    ],
     headRef: options.headRef,
     headSha: options.headSha,
-    headRepositoryOwner: options.forkOwner,
   });
   return match?.status ?? null;
 }
@@ -3337,6 +3346,7 @@ function toBatchCurrentPullRequestItem(
     baseRefName: node.baseRefName,
     headRefName: node.headRefName,
     ...(node.headRefOid ? { headRefOid: node.headRefOid } : {}),
+    updatedAt: node.updatedAt,
     mergedAt: node.mergedAt ?? null,
     ...(statusCheckRollup ? { statusCheckRollup } : {}),
     reviewDecision: node.reviewDecision,
@@ -3357,6 +3367,7 @@ function toCurrentPullRequestCandidate(
   const headSha = item.headRefOid;
   return {
     status,
+    updatedAt: item.updatedAt,
     ...(headSha ? { headSha } : {}),
     ...(headRepositoryOwner ? { headRepositoryOwner } : {}),
   };
@@ -3380,12 +3391,6 @@ function pickPullRequestCandidate(options: {
     if (!isCandidateForHeadRef(candidate, options.headRef)) {
       return false;
     }
-    if (
-      candidate.status.state !== "open" &&
-      (!options.headSha || candidate.headSha !== options.headSha)
-    ) {
-      return false;
-    }
     if (!options.headRepositoryOwner) {
       return true;
     }
@@ -3411,17 +3416,17 @@ function comparePullRequestCandidatePreference(
   if (leftExact !== rightExact) {
     return leftExact ? -1 : 1;
   }
-  return 0;
+  return (
+    (right.updatedAt ?? "").localeCompare(left.updatedAt ?? "") ||
+    (right.status.number ?? 0) - (left.status.number ?? 0)
+  );
 }
 
 function getPullRequestStateRank(status: CurrentPullRequestStatus): number {
-  if (status.state === "open" || status.isDraft) {
+  if (status.state === "open") {
     return 0;
   }
-  if (status.state === "merged") {
-    return 1;
-  }
-  return 2;
+  return 1;
 }
 
 type GitHubCloneProtocol = "https" | "ssh";
@@ -3969,6 +3974,7 @@ function toCurrentPullRequestStatus(
     state,
     baseRefName: item.baseRefName,
     headRefName: item.headRefName || fallbackHeadRefName,
+    ...(item.headRefOid ? { headSha: item.headRefOid } : {}),
     isMerged: mergedAt !== null,
     isDraft: item.isDraft ?? false,
     mergeable: item.mergeable,
diff --git a/packages/server/src/services/gitlab-service.test.ts b/packages/server/src/services/gitlab-service.test.ts
index b9b6d447d4..81e8bc966d 100644
--- a/packages/server/src/services/gitlab-service.test.ts
+++ b/packages/server/src/services/gitlab-service.test.ts
@@ -357,14 +357,16 @@ describe("createGitLabService", () => {
     expect(calls[1]).toEqual(["mr", "view", "270", "-F", "json"]);
   });
 
-  it("does not attach the latest historical merge request after a reused branch advances", async () => {
+  it("keeps a merged MR when its remote head advances beyond the checkout", async () => {
     const stale = {
       ...OPEN_MR,
       state: "merged",
       source_branch: "dev",
       sha: "1111111111111111111111111111111111111111",
     };
-    const { service, calls } = makeService(() => ok(JSON.stringify([stale])));
+    const { service, calls } = makeService((args) =>
+      ok(JSON.stringify(args[1] === "list" ? [stale] : stale)),
+    );
 
     await expect(
       service.getCurrentPullRequestStatus({
@@ -372,8 +374,8 @@ describe("createGitLabService", () => {
         headRef: "dev",
         headSha: "2222222222222222222222222222222222222222",
       }),
-    ).resolves.toBeNull();
-    expect(calls).toEqual([currentMrListArgs("dev")]);
+    ).resolves.toMatchObject({ state: "merged" });
+    expect(calls[0]).toEqual(currentMrListArgs("dev"));
   });
 
   it("looks up a numeric current branch through the source-branch list filter", async () => {
diff --git a/packages/server/src/services/gitlab-service.ts b/packages/server/src/services/gitlab-service.ts
index c5f54be2cb..4fde7173f9 100644
--- a/packages/server/src/services/gitlab-service.ts
+++ b/packages/server/src/services/gitlab-service.ts
@@ -728,6 +728,7 @@ function toCurrentPullRequestStatus(
     state: mapMergeRequestState(mr.state),
     baseRefName: mr.target_branch,
     headRefName: mr.source_branch,
+    ...(mr.sha ? { headSha: mr.sha } : {}),
     isMerged: mr.state === "merged" || mr.merged_at != null,
     isDraft: mr.draft ?? mr.work_in_progress ?? false,
     mergeable: mapMergeable(mr),
@@ -987,6 +988,7 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
         (mr) =>
           mapMergeRequestState(mr.state) !== "open" && headSha !== undefined && mr.sha === headSha,
       ) ??
+      candidates[0] ??
       null;
     return match ? viewMergeRequest(cwd, String(match.iid)) : null;
   }
diff --git a/packages/server/src/terminal/headless-terminal.test.ts b/packages/server/src/terminal/headless-terminal.test.ts
new file mode 100644
index 0000000000..d971f0d3f5
--- /dev/null
+++ b/packages/server/src/terminal/headless-terminal.test.ts
@@ -0,0 +1,60 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { createHeadlessTerminal } from "./headless-terminal.js";
+
+const EMOJI_ROW = "A😀👍❤️👋🏽🇰🇷👨‍👩‍👧B";
+// A, six two-column emoji clusters, B.
+const EMOJI_ROW_END_COL = 1 + 6 * 2 + 1;
+
+async function cursorColAfter(text: string): Promise<number> {
+  const terminal = createHeadlessTerminal({ rows: 2, cols: 40 });
+  try {
+    await new Promise<void>((resolve) => terminal.write(text, resolve));
+    return terminal.buffer.active.cursorX;
+  } finally {
+    terminal.dispose();
+  }
+}
+
+describe("createHeadlessTerminal", () => {
+  it("gives each emoji cluster one two-column cell", async () => {
+    expect(await cursorColAfter(EMOJI_ROW)).toBe(EMOJI_ROW_END_COL);
+  });
+
+  it("keeps ASCII and CJK widths", async () => {
+    expect(await cursorColAfter("ABC")).toBe(3);
+    expect(await cursorColAfter("中文")).toBe(4);
+  });
+
+  // The width table is decoded into a Node Buffer when the module loads. A
+  // Buffer carved out of Node's shared pool starts at a non-zero byteOffset,
+  // and an addon that reads the table header from offset 0 gets wrong widths
+  // or fails to load. Whether the pool offset is zero depends on earlier
+  // allocations, so the test forces a non-zero offset in a fresh process
+  // before the module loads. Zero bytes in front of the table make the
+  // misread header deterministic.
+  it("decodes widths correctly when Node's buffer pool offset is non-zero", () => {
+    const moduleUrl = new URL("./headless-terminal.ts", import.meta.url).href;
+    const script = `
+      Buffer.poolSize = 8 * 1024 * 1024;
+      const occupied = Buffer.from(new Uint8Array(3 * 1024 * 1024));
+      if (occupied.byteOffset !== 0 || occupied.buffer.byteLength !== Buffer.poolSize) {
+        throw new Error("expected a fresh shared pool");
+      }
+      const { createHeadlessTerminal } = await import(${JSON.stringify(moduleUrl)});
+      const terminal = createHeadlessTerminal({ rows: 2, cols: 40 });
+      await new Promise((resolve) => terminal.write(${JSON.stringify(EMOJI_ROW)}, resolve));
+      process.stdout.write(String(terminal.buffer.active.cursorX));
+      terminal.dispose();
+    `;
+    const result = spawnSync(
+      process.execPath,
+      ["--import", "tsx", "--input-type=module", "--eval", script],
+      { cwd: fileURLToPath(new URL(".", import.meta.url)), encoding: "utf8" },
+    );
+
+    expect(result.status, result.stderr).toBe(0);
+    expect(result.stdout).toBe(String(EMOJI_ROW_END_COL));
+  });
+});
diff --git a/packages/server/src/terminal/headless-terminal.ts b/packages/server/src/terminal/headless-terminal.ts
new file mode 100644
index 0000000000..4e106c243b
--- /dev/null
+++ b/packages/server/src/terminal/headless-terminal.ts
@@ -0,0 +1,22 @@
+import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
+import xterm, { type Terminal } from "@xterm/headless";
+
+export interface HeadlessTerminalOptions {
+  rows: number;
+  cols: number;
+  scrollback?: number;
+}
+
+/**
+ * A headless xterm that measures text the way Paseo clients render it.
+ *
+ * Grapheme-cluster widths give every emoji cluster (VS16, skin-tone, flags,
+ * ZWJ sequences) one two-column cell, matching color-emoji fonts. Clients
+ * replay this buffer's ANSI with the same table, so cells and the cursor line
+ * up after reconnect. See docs/terminal-rendering.md.
+ */
+export function createHeadlessTerminal(options: HeadlessTerminalOptions): Terminal {
+  const terminal = new xterm.Terminal({ ...options, allowProposedApi: true });
+  terminal.loadAddon(new UnicodeGraphemesAddon());
+  return terminal;
+}
diff --git a/packages/server/src/terminal/terminal-serializer.ts b/packages/server/src/terminal/terminal-serializer.ts
index 5f79064948..2b36dcbe7b 100644
--- a/packages/server/src/terminal/terminal-serializer.ts
+++ b/packages/server/src/terminal/terminal-serializer.ts
@@ -16,13 +16,13 @@ export function createTerminalSerializer(
     // absolutely; an x==cols cursor must keep its pending wrap for the next byte.
     const position =
       buffer.cursorX < terminal.cols ? `\x1b[${buffer.cursorY + 1};${buffer.cursorX + 1}H` : "";
-    return Buffer.from(data + position + serializeCursorPresentation(terminal), "utf8");
+    return Buffer.from(data + position + serializeAdditionalModes(terminal), "utf8");
   };
 }
 
-// Stable addon 0.14 serializes buffer/modes but omits DECSCUSR and cursor visibility.
-// xterm 6 keeps the program-selected presentation in coreService, not public options.
-function serializeCursorPresentation(terminal: TerminalType): string {
+// Addon 0.14 omits mouse encoding, DECSCUSR and cursor visibility. xterm 6
+// retains these in internal services rather than the public modes/options.
+function serializeAdditionalModes(terminal: TerminalType): string {
   const core = (
     terminal as unknown as {
       _core: {
@@ -30,13 +30,17 @@ function serializeCursorPresentation(terminal: TerminalType): string {
           isCursorHidden: boolean;
           decPrivateModes: { cursorStyle?: "block" | "underline" | "bar"; cursorBlink?: boolean };
         };
+        mouseStateService: { activeEncoding: string };
       };
     }
-  )._core.coreService;
-  const visibility = `\x1b[?25${core.isCursorHidden ? "l" : "h"}`;
-  const cursorStyle = core.decPrivateModes.cursorStyle;
+  )._core;
+  let mouseEncoding = "";
+  if (core.mouseStateService.activeEncoding === "SGR") mouseEncoding = "\x1b[?1006h";
+  else if (core.mouseStateService.activeEncoding === "SGR_PIXELS") mouseEncoding = "\x1b[?1016h";
+  const visibility = `${mouseEncoding}\x1b[?25${core.coreService.isCursorHidden ? "l" : "h"}`;
+  const cursorStyle = core.coreService.decPrivateModes.cursorStyle;
   // Unset presentation belongs to each renderer's configured defaults.
   if (cursorStyle === undefined) return visibility;
   const style = { block: 2, underline: 4, bar: 6 }[cursorStyle];
-  return `${visibility}\x1b[${style - (core.decPrivateModes.cursorBlink ? 1 : 0)} q`;
+  return `${visibility}\x1b[${style - (core.coreService.decPrivateModes.cursorBlink ? 1 : 0)} q`;
 }
diff --git a/packages/server/src/terminal/terminal-session-controller.test.ts b/packages/server/src/terminal/terminal-session-controller.test.ts
index ccb152aa23..c81cd2fbb5 100644
--- a/packages/server/src/terminal/terminal-session-controller.test.ts
+++ b/packages/server/src/terminal/terminal-session-controller.test.ts
@@ -93,6 +93,10 @@ function createLogger(): pino.Logger {
   } as unknown as pino.Logger;
 }
 
+function decodedTerminalFrames(frames: TerminalStreamFrame[]): string {
+  return frames.map((frame) => new TextDecoder().decode(frame.payload)).join("");
+}
+
 describe("terminal-session-controller restore", () => {
   test("delivers output produced while restore is in flight after the restore frame", async () => {
     let terminalListener: ((message: ServerMessage) => void) | null = null;
@@ -172,7 +176,10 @@ describe("terminal-session-controller restore", () => {
     terminalListener?.({ type: "output", data: "restore-after\n", revision: 2 });
     snapshot.resolve(terminalReplay("restore-before", 1, "\x1b[?1h\x1b[?2004h"));
     await snapshot.promise;
-    await new Promise((resolve) => setTimeout(resolve, 20));
+    await vi.waitFor(() => {
+      const output = decodedTerminalFrames(binaryFrames.slice(1));
+      expect(output).toBe("\x1b[?1h\x1b[?2004hrestore-after\n");
+    });
 
     expect(outboundMessages).toContainEqual({
       type: "subscribe_terminal_response",
@@ -183,14 +190,12 @@ describe("terminal-session-controller restore", () => {
         requestId: "req-1",
       },
     });
-    expect(binaryFrames.map((frame) => frame.opcode)).toEqual([
-      TerminalStreamOpcode.Restore,
-      TerminalStreamOpcode.Output,
-    ]);
+    expect(binaryFrames[0]?.opcode).toBe(TerminalStreamOpcode.Restore);
+    const outputFrames = binaryFrames.slice(1);
+    expect(outputFrames.length).toBeGreaterThan(0);
+    expect(outputFrames.every((frame) => frame.opcode === TerminalStreamOpcode.Output)).toBe(true);
     expect(new TextDecoder().decode(binaryFrames[0]?.payload)).toContain("restore-before");
-    expect(new TextDecoder().decode(binaryFrames[1]?.payload)).toBe(
-      "\x1b[?1h\x1b[?2004hrestore-after\n",
-    );
+    expect(decodedTerminalFrames(outputFrames)).toBe("\x1b[?1h\x1b[?2004hrestore-after\n");
   });
 });
 
@@ -387,8 +392,25 @@ describe("terminal-session-controller with terminals held by a newer Paseo", ()
     };
   }
 
+  test("reports incompatible workers to a legacy subscription without a request id", async () => {
+    const outboundMessages: SessionOutboundMessage[] = [];
+    const controller = createController({
+      terminalManager: incompatibleManager(),
+      emit: (message) => outboundMessages.push(message),
+      emitBinary: () => {},
+      hasBinaryChannel: () => true,
+      isPathWithinRoot: isSameOrDescendantPath,
+      sessionLogger: createLogger(),
+    });
+    await controller.dispatch({ type: "subscribe_terminals_request" });
+    expect(outboundMessages).toEqual([
+      { type: "status", payload: { status: "error", message: incompatible.message } },
+    ]);
+  });
+
   test.each([
     { type: "list_terminals_request" as const, requestId: "req-list" },
+    { type: "subscribe_terminals_request" as const, requestId: "req-observe" },
     { type: "list_terminals_request" as const, requestId: "req-list-cwd", cwd: "/work/repo" },
     {
       type: "create_terminal_request" as const,
@@ -500,8 +522,22 @@ describe("terminal-session-controller subdirectory aggregation", () => {
         payload: {
           cwd: rootCwd,
           terminals: [
-            { id: "root-term", name: "Terminal 1", workspaceId: "ws-test", activity: null },
-            { id: "subdir-term", name: "Mobile", workspaceId: "ws-test", activity: null },
+            {
+              id: "root-term",
+              name: "Terminal 1",
+              workspaceId: "ws-test",
+              activity: null,
+              createdAt: null,
+              isScript: false,
+            },
+            {
+              id: "subdir-term",
+              name: "Mobile",
+              workspaceId: "ws-test",
+              activity: null,
+              createdAt: null,
+              isScript: false,
+            },
           ],
         },
       },
@@ -571,6 +607,8 @@ describe("terminal-session-controller subdirectory aggregation", () => {
               cwd: rootCwd,
               workspaceId: "ws-test",
               activity: null,
+              createdAt: null,
+              isScript: false,
             },
           ],
           requestId: "req-root",
@@ -587,6 +625,8 @@ describe("terminal-session-controller subdirectory aggregation", () => {
               cwd: worktreeCwd,
               workspaceId: "ws-test",
               activity: null,
+              createdAt: null,
+              isScript: false,
             },
           ],
           requestId: "req-worktree",
@@ -672,7 +712,16 @@ describe("terminal-session-controller workspace-scoped subscriptions", () => {
         type: "terminals_changed",
         payload: {
           cwd,
-          terminals: [{ id: "a", name: "A", workspaceId: "ws-a", activity: null }],
+          terminals: [
+            {
+              id: "a",
+              name: "A",
+              workspaceId: "ws-a",
+              activity: null,
+              createdAt: null,
+              isScript: false,
+            },
+          ],
         },
       },
     ]);
diff --git a/packages/server/src/terminal/terminal-session-controller.ts b/packages/server/src/terminal/terminal-session-controller.ts
index 653524e54a..d047ee0c20 100644
--- a/packages/server/src/terminal/terminal-session-controller.ts
+++ b/packages/server/src/terminal/terminal-session-controller.ts
@@ -38,13 +38,12 @@ import type { TerminalSession } from "./terminal.js";
 import type { TerminalManager, TerminalsChangedEvent } from "./terminal-manager.js";
 import { applyTerminalSize } from "./terminal-size-ownership.js";
 import { TerminalWorkerIncompatibleError } from "./terminal-worker-pool.js";
-import type { TerminalActivity } from "@getpaseo/protocol/terminal-activity";
 import { terminalSubscriptionKey } from "@getpaseo/protocol/terminal-subscription-key";
 
 const MAX_TERMINAL_STREAM_SLOTS = 256;
 
 interface TerminalDirectorySubscription {
-  cwd: string;
+  cwd: string | undefined;
   workspaceId: string | undefined;
   owner: OwnedSubscription;
   refresh: Promise<void> | null;
@@ -87,6 +86,8 @@ export interface TerminalSessionControllerOptions {
   supportsChunkedReplay?: (source: object) => boolean;
   isPathWithinRoot: (rootPath: string, candidatePath: string) => boolean;
   sessionLogger: pino.Logger;
+  isScriptTerminal?: (terminal: TerminalSession) => boolean;
+  subscribeTerminalMetadata?: (listener: () => void) => () => void;
   listTerminalWorkspaceRefs?: () => Promise<readonly TerminalWorkspaceRef[]>;
   listTerminalWorkspaceRoots?: () => Promise<readonly string[]>;
   // Drives the snapshot catch-up fallback: a keeping-up client reports ~0 and
@@ -163,9 +164,17 @@ export class TerminalSessionController {
 
   start(): void {
     if (!this.terminalManager || this.unsubscribeTerminalsChanged) return;
-    this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) => {
+    const releaseManager = this.terminalManager.subscribeTerminalsChanged((event) => {
       void this.handleTerminalsChanged(event);
     });
+    const releaseMetadata = this.options.subscribeTerminalMetadata?.(() => {
+      for (const subscription of this.subscribedDirectories.values())
+        void this.emitTerminalsSnapshotForSubscription(subscription);
+    });
+    this.unsubscribeTerminalsChanged = () => {
+      releaseManager();
+      releaseMetadata?.();
+    };
   }
 
   getMetrics(): TerminalSessionControllerMetrics {
@@ -191,6 +200,7 @@ export class TerminalSessionController {
       ) {
         return false;
       }
+      if (subscription.cwd === undefined) return true;
       return this.terminalBelongsToRoot(subscription.cwd, input.cwd, workspaceRoots);
     });
   }
@@ -302,15 +312,7 @@ export class TerminalSessionController {
     }
   }
 
-  private toTerminalInfo(
-    terminal: Pick<TerminalSession, "id" | "name" | "workspaceId" | "getTitle" | "getActivity">,
-  ): {
-    id: string;
-    name: string;
-    workspaceId: string;
-    title?: string;
-    activity: TerminalActivity | null;
-  } {
+  private toTerminalInfo(terminal: TerminalSession) {
     const title = terminal.getTitle();
     const activity = terminal.getActivity();
     return {
@@ -319,6 +321,8 @@ export class TerminalSessionController {
       workspaceId: terminal.workspaceId,
       ...(title ? { title } : {}),
       activity,
+      createdAt: terminal.createdAt ?? null,
+      isScript: this.options.isScriptTerminal?.(terminal) ?? false,
     };
   }
 
@@ -329,7 +333,8 @@ export class TerminalSessionController {
     // aggregated list — so the client's cache replacement doesn't drop the
     // terminals that live directly at the root.
     const matchingSubscriptions = Array.from(this.subscribedDirectories.values()).filter(
-      (subscription) => this.isPathWithinRoot(subscription.cwd, event.cwd),
+      (subscription) =>
+        subscription.cwd === undefined || this.isPathWithinRoot(subscription.cwd, event.cwd),
     );
     for (const subscription of matchingSubscriptions) {
       await this.emitTerminalsSnapshotForSubscription(subscription);
@@ -368,6 +373,10 @@ export class TerminalSessionController {
       await this.emitTerminalsSnapshotForSubscription(subscription, msg.requestId);
     } catch (error) {
       await owner.release();
+      if (error instanceof TerminalWorkerIncompatibleError) {
+        this.emitIncompatible(msg, error);
+        return;
+      }
       throw error;
     }
   }
@@ -383,17 +392,26 @@ export class TerminalSessionController {
     const refresh = (async () => {
       do {
         subscription.pending = false;
-        const terminals = await this.getTerminalsForWorkspaceRoot(
-          subscription.cwd,
-          subscription.workspaceId,
-        );
+        const terminals =
+          subscription.cwd === undefined
+            ? (await this.getAllTerminalSessions()).filter(
+                (terminal) =>
+                  subscription.workspaceId === undefined ||
+                  terminal.workspaceId === subscription.workspaceId,
+              )
+            : await this.getTerminalsForWorkspaceRoot(subscription.cwd, subscription.workspaceId);
         if (subscription.owner.signal.aborted) return;
         subscription.owner.emit({
           type: "terminals_changed",
           payload: {
             cwd: subscription.cwd,
             workspaceId: subscription.workspaceId,
-            terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
+            terminals: terminals.map((terminal) =>
+              Object.assign(
+                this.toTerminalInfo(terminal),
+                subscription.cwd === undefined ? { cwd: terminal.cwd } : {},
+              ),
+            ),
             ...(requestId ? { requestId } : {}),
           },
         });
@@ -464,9 +482,13 @@ export class TerminalSessionController {
   // An empty list or a generic failure would read as "no terminals"; the client needs to know
   // they exist and why it cannot reach them.
   private emitIncompatible(
-    msg: { type: string; requestId: string },
+    msg: { type: string; requestId?: string },
     error: TerminalWorkerIncompatibleError,
   ): void {
+    if (msg.requestId === undefined) {
+      this.emit({ type: "status", payload: { status: "error", message: error.message } });
+      return;
+    }
     this.emit({
       type: "rpc_error",
       payload: {
@@ -482,6 +504,8 @@ export class TerminalSessionController {
     if (!this.terminalManager) {
       return [];
     }
+    const unavailable = this.terminalManager.getUnavailableError?.();
+    if (unavailable) throw unavailable;
     const directories = this.terminalManager.listDirectories();
     const manager = this.terminalManager;
     const terminalsByDirectory = await Promise.all(
diff --git a/packages/server/src/terminal/terminal-worker-client.test.ts b/packages/server/src/terminal/terminal-worker-client.test.ts
index 01a4dd91d3..119d339b18 100644
--- a/packages/server/src/terminal/terminal-worker-client.test.ts
+++ b/packages/server/src/terminal/terminal-worker-client.test.ts
@@ -4,7 +4,13 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { isPlatform } from "../test-utils/platform.js";
 import { encodeFrame, FrameDecoder, TerminalWorkerFrameError } from "./terminal-worker-frames.js";
-import { connectTerminalWorker, TerminalWorkerConnectError } from "./terminal-worker-client.js";
+import { createConnection, createServer, type Server } from "node:net";
+import { randomUUID } from "node:crypto";
+import {
+  connectTerminalWorker,
+  probeTerminalWorkerSocket,
+  TerminalWorkerConnectError,
+} from "./terminal-worker-client.js";
 import { launchTerminalWorker } from "./terminal-worker-launch.js";
 import { terminalWorkerRecordPath } from "./terminal-worker-record.js";
 
@@ -74,7 +80,6 @@ describe("terminal worker authentication", () => {
 });
 
 it("bounds a stalled framed writer to one chunk and resumes in order", async () => {
-  const { createServer, createConnection } = await import("node:net");
   const { attachFramedSocket } = await import("./terminal-worker-frames.js");
   const server = createServer();
   await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
@@ -115,3 +120,41 @@ it("bounds a stalled framed writer to one chunk and resumes in order", async ()
     await new Promise<void>((resolve) => server.close(() => resolve()));
   }
 });
+
+// The probe decides whether a live pid named by an unidentifiable worker record is still the
+// worker. A refused answer retires the record, so it must hold for a Windows named pipe too.
+describe("terminal worker socket probe", () => {
+  function socketPath(): string {
+    if (isPlatform("win32")) return `\\\\.\\pipe\\paseo-tw-probe-${randomUUID()}`;
+    const directory = mkdtempSync(path.join(tmpdir(), "tw-probe-"));
+    temporaryDirs.push(directory);
+    return path.join(directory, "w.sock");
+  }
+
+  async function serve(at: string): Promise<Server> {
+    const server = createServer((socket) => socket.on("error", () => {}));
+    await new Promise<void>((resolve) => server.listen(at, resolve));
+    return server;
+  }
+
+  it("answers accepting while a worker serves the socket", async () => {
+    const at = socketPath();
+    const server = await serve(at);
+    try {
+      expect(await probeTerminalWorkerSocket(at)).toBe("accepting");
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
+
+  it("answers refused for a socket nobody ever served", async () => {
+    expect(await probeTerminalWorkerSocket(socketPath())).toBe("refused");
+  });
+
+  it("answers refused once the worker that served the socket closed it", async () => {
+    const at = socketPath();
+    const server = await serve(at);
+    await new Promise((resolve) => server.close(resolve));
+    expect(await probeTerminalWorkerSocket(at)).toBe("refused");
+  });
+});
diff --git a/packages/server/src/terminal/terminal-worker-client.ts b/packages/server/src/terminal/terminal-worker-client.ts
index 532f3075c6..ac48293879 100644
--- a/packages/server/src/terminal/terminal-worker-client.ts
+++ b/packages/server/src/terminal/terminal-worker-client.ts
@@ -1,4 +1,5 @@
-import { EventEmitter } from "node:events";
+import { EventEmitter, once } from "node:events";
+import { setTimeout as delay } from "node:timers/promises";
 import { createConnection } from "node:net";
 import { attachFramedSocket, type FramedSocket } from "./terminal-worker-frames.js";
 import {
@@ -139,3 +140,34 @@ export function connectTerminalWorker(input: {
     });
   });
 }
+
+export type TerminalWorkerSocketProbe = "accepting" | "refused" | "unknown";
+
+const PROBE_TIMEOUT_MS = 1_000;
+// What a connect to a socket nobody listens on fails with: the unix socket file is left behind
+// (ECONNREFUSED) or gone, as a Windows pipe is once its server closes (ENOENT).
+const NO_LISTENER_ERRORS = new Set(["ECONNREFUSED", "ENOENT"]);
+
+/**
+ * Whether anything accepts connections on a worker's socket. It never authenticates, so the
+ * daemon controlling the worker keeps control: the worker drops a connection that closes
+ * before its hello.
+ */
+export async function probeTerminalWorkerSocket(
+  socketPath: string,
+): Promise<TerminalWorkerSocketProbe> {
+  const socket = createConnection(socketPath);
+  const timeout = new AbortController();
+  try {
+    return await Promise.race([
+      once(socket, "connect").then(() => "accepting" as const),
+      delay(PROBE_TIMEOUT_MS, "unknown" as const, { signal: timeout.signal }),
+    ]);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code && NO_LISTENER_ERRORS.has(code) ? "refused" : "unknown";
+  } finally {
+    timeout.abort();
+    socket.destroy();
+  }
+}
diff --git a/packages/server/src/terminal/terminal-worker-ownership.test.ts b/packages/server/src/terminal/terminal-worker-ownership.test.ts
index 7abbb9aa62..aefa364338 100644
--- a/packages/server/src/terminal/terminal-worker-ownership.test.ts
+++ b/packages/server/src/terminal/terminal-worker-ownership.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import type { ManagedProcessInspection } from "../server/managed-processes/managed-processes.js";
 import {
   classifyTerminalProgramProcess,
-  classifyTerminalWorkerProcess,
+  identifyTerminalWorker,
 } from "./terminal-worker-ownership.js";
 
 const BIRTH = "Wed Oct 21 18:12:49 2026";
@@ -12,14 +12,6 @@ function alive(startedAt: string | null, commandLine: string | null): ManagedPro
   return { status: "alive", snapshot: { pid: 4242, startedAt, commandLine } };
 }
 
-const workerRecord = {
-  recordId: "record-1",
-  identity: {
-    startedAt: BIRTH,
-    commandLine: "node terminal-worker-process.js --paseo-terminal-worker record-1",
-  },
-};
-
 describe("terminal program ownership", () => {
   it("owns a program that ran exec: same pid and birth time, new command line", () => {
     expect(
@@ -59,33 +51,15 @@ describe("terminal program ownership", () => {
 });
 
 describe("terminal worker ownership", () => {
-  it("owns the worker whose birth time matches and whose command line carries its record id", () => {
+  it("retires a live unrelated pid when its socket is absent without inspecting it", async () => {
     expect(
-      classifyTerminalWorkerProcess(workerRecord, alive(BIRTH, workerRecord.identity.commandLine)),
-    ).toEqual({ status: "owned" });
-  });
-
-  it("treats another worker reusing the pid in the same second as unrelated", () => {
-    expect(
-      classifyTerminalWorkerProcess(
-        workerRecord,
-        alive(BIRTH, "node terminal-worker-process.js --paseo-terminal-worker record-2"),
-      ),
-    ).toMatchObject({ status: "unrelated" });
-  });
-
-  it("treats a worker pid reused with another birth time as unrelated", () => {
-    expect(
-      classifyTerminalWorkerProcess(
-        workerRecord,
-        alive(OTHER_BIRTH, workerRecord.identity.commandLine),
-      ),
-    ).toMatchObject({ status: "unrelated" });
-  });
-
-  it("does not own a worker whose command line cannot be read", () => {
-    expect(classifyTerminalWorkerProcess(workerRecord, alive(BIRTH, null))).toMatchObject({
-      status: "unknown",
-    });
+      await identifyTerminalWorker({
+        pid: process.pid,
+        socketPath:
+          process.platform === "win32"
+            ? "\\\\.\\pipe\\paseo-absent-ownership-test"
+            : "/tmp/paseo-absent-ownership-test.sock",
+      }),
+    ).toEqual({ status: "gone" });
   });
 });
diff --git a/packages/server/src/terminal/terminal-worker-ownership.ts b/packages/server/src/terminal/terminal-worker-ownership.ts
index 9bd02b01cd..0f7033f1b3 100644
--- a/packages/server/src/terminal/terminal-worker-ownership.ts
+++ b/packages/server/src/terminal/terminal-worker-ownership.ts
@@ -1,5 +1,6 @@
 import type { ManagedProcessInspection } from "../server/managed-processes/managed-processes.js";
-import { TERMINAL_WORKER_MARKER_ARG, type TerminalWorkerRecord } from "./terminal-worker-record.js";
+import { connectTerminalWorker, probeTerminalWorkerSocket } from "./terminal-worker-client.js";
+import { type TerminalWorkerRecord } from "./terminal-worker-record.js";
 
 // Who a pid named in a terminal worker record belongs to, before anything signals it.
 //
@@ -15,20 +16,49 @@ export type ProcessOwnership =
   | { status: "owned" }
   | { status: "unknown"; reason: string };
 
-export function classifyTerminalWorkerProcess(
-  record: Pick<TerminalWorkerRecord, "recordId" | "identity">,
-  inspection: ManagedProcessInspection,
-): ProcessOwnership {
-  const birth = classifyBirth(record.identity.startedAt, inspection);
-  if (birth.status !== "owned" || inspection.status !== "alive") return birth;
-  const commandLine = inspection.snapshot.commandLine;
-  if (!commandLine) {
-    return { status: "unknown", reason: "command line unavailable" };
+/** The home lock owns these records; the record-specific socket proves a live worker. */
+export async function identifyTerminalWorker(
+  record: Pick<TerminalWorkerRecord, "pid" | "socketPath">,
+): Promise<ProcessOwnership> {
+  try {
+    process.kill(record.pid, 0);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ESRCH") return { status: "gone" };
   }
-  if (!hasWorkerMarker(commandLine, record.recordId)) {
-    return { status: "unrelated", reason: "command line lacks the worker marker" };
+  const socket = await probeTerminalWorkerSocket(record.socketPath);
+  if (socket === "refused") return { status: "gone" };
+  if (socket === "accepting") return { status: "owned" };
+  return { status: "unknown", reason: "worker socket probe inconclusive" };
+}
+
+/** Rechecks the live worker immediately before a forced termination. */
+export async function authorizeTerminalWorkerTermination(
+  record: TerminalWorkerRecord,
+): Promise<ProcessOwnership> {
+  const ownership = await identifyTerminalWorker(record);
+  if (ownership.status !== "owned") return ownership;
+  // COMPAT(terminal-worker-legacy-socket): added after v0.15.1, remove after 2027-02-06.
+  // Legacy names contain only home + pid. A stale record can reach a newer worker, so an
+  // accepting legacy socket requires proof of its secret before cleanup may signal it.
+  if (
+    record.socketPath.endsWith(`-${record.recordId}.sock`) ||
+    record.socketPath.endsWith(`-${record.recordId}`)
+  )
+    return ownership;
+  try {
+    const connection = await connectTerminalWorker({
+      socketPath: record.socketPath,
+      secret: record.secret,
+      timeoutMs: 1000,
+    });
+    const matches = connection.workerPid === record.pid;
+    connection.disconnect();
+    return matches
+      ? ownership
+      : { status: "unknown", reason: "legacy socket authenticated another pid" };
+  } catch {
+    return { status: "unknown", reason: "legacy socket ownership could not be authenticated" };
   }
-  return { status: "owned" };
 }
 
 export function classifyTerminalProgramProcess(
@@ -57,13 +87,3 @@ function classifyBirth(
   }
   return { status: "owned" };
 }
-
-function hasWorkerMarker(commandLine: string, recordId: string): boolean {
-  const tokens = commandLine.split(/\s+/);
-  for (let index = 0; index < tokens.length - 1; index += 1) {
-    if (tokens[index] === TERMINAL_WORKER_MARKER_ARG && tokens[index + 1] === recordId) {
-      return true;
-    }
-  }
-  return false;
-}
diff --git a/packages/server/src/terminal/terminal-worker-process.ts b/packages/server/src/terminal/terminal-worker-process.ts
index 855c39da59..c61ead0628 100644
--- a/packages/server/src/terminal/terminal-worker-process.ts
+++ b/packages/server/src/terminal/terminal-worker-process.ts
@@ -263,7 +263,12 @@ function runWorker(argv: string[]): void {
   }
 
   function terminalMetadata(session: LocalTerminalSession) {
-    return { ...session.getSize(), hasOutput: session.hasOutput(), title: session.getTitle() };
+    return {
+      ...session.getSize(),
+      createdAt: session.createdAt,
+      hasOutput: session.hasOutput(),
+      title: session.getTitle(),
+    };
   }
 
   function toTerminalInfo(session: LocalTerminalSession): WorkerTerminalInfo {
@@ -403,9 +408,10 @@ function runWorker(argv: string[]): void {
     ]);
   }
 
-  // A terminal enters the record only with its program's birth time, so cleanup can always
-  // tell the program from a later process that reuses its pid. A program that already exited
-  // needs no entry; one whose birth time cannot be read is killed and the create fails.
+  // A terminal enters the record with its program's birth time, so cleanup can tell the
+  // program from a later process that reuses its pid. A program that already exited needs no
+  // entry. One whose birth time cannot be read is recorded without it: it still runs, and
+  // cleanup never signals it.
   async function recordTerminalProgram(session: LocalTerminalSession): Promise<void> {
     if (session.getExitInfo()) return;
     // The manager drops a session as soon as its program exits, so only a live one has a pid.
@@ -413,14 +419,17 @@ function runWorker(argv: string[]): void {
     if (pid === null) {
       throw new Error(`Terminal ${session.id} has no program pid`);
     }
-    const inspection = await inspector.inspect(pid);
-    if (inspection.status === "not-found" || session.getExitInfo()) {
+    const inspection = inspector.reportsBirthTimes ? await inspector.inspect(pid) : null;
+    if (inspection?.status === "not-found" || session.getExitInfo()) {
       return;
     }
-    if (inspection.status === "error" || !inspection.snapshot.startedAt) {
+    const startedAt = inspection?.status === "alive" ? inspection.snapshot.startedAt : null;
+    if (inspector.reportsBirthTimes && !startedAt) {
       const reason =
-        inspection.status === "error" ? errorMessage(inspection.error) : "no birth time reported";
-      throw new Error(`Cannot identify terminal program ${pid}: ${reason}`);
+        inspection?.status === "error" ? errorMessage(inspection.error) : "no birth time reported";
+      console.error(
+        `Terminal worker cannot read the birth time of terminal program ${pid}; cleanup will never signal it: ${reason}`,
+      );
     }
     if (!record) {
       throw new Error("Terminal worker record is not written yet");
@@ -429,7 +438,7 @@ function runWorker(argv: string[]): void {
       ...record,
       terminals: [
         ...record.terminals.filter((entry) => entry.id !== session.id),
-        { id: session.id, pid, startedAt: inspection.snapshot.startedAt },
+        { id: session.id, pid, startedAt },
       ],
     };
     await persistRecord();
@@ -694,6 +703,7 @@ function runWorker(argv: string[]): void {
     const socketPath = resolveTerminalWorkerSocketPath({
       paseoHome: args.paseoHome,
       workerPid: process.pid,
+      recordId: args.recordId,
     });
     if (process.platform !== "win32") {
       rmSync(socketPath, { force: true });
@@ -711,21 +721,11 @@ function runWorker(argv: string[]): void {
       chmodSync(socketPath, PRIVATE_FILE_MODE);
     }
 
-    const self = await inspector.inspect(process.pid);
-    if (
-      self.status !== "alive" ||
-      !self.snapshot.startedAt ||
-      !self.snapshot.commandLine?.includes(args.recordId)
-    ) {
-      const reason = self.status === "error" ? errorMessage(self.error) : "no usable snapshot";
-      throw new Error(`Terminal worker cannot read its own process identity: ${reason}`);
-    }
     record = {
       recordId: args.recordId,
       pid: process.pid,
       bootId: currentBootId(),
       createdAt: new Date().toISOString(),
-      identity: { startedAt: self.snapshot.startedAt, commandLine: self.snapshot.commandLine },
       protocolVersion,
       paseoVersion: args.paseoVersion,
       socketPath,
diff --git a/packages/server/src/terminal/terminal-worker-processes.ts b/packages/server/src/terminal/terminal-worker-processes.ts
index b0c2e6d0cb..90de521bab 100644
--- a/packages/server/src/terminal/terminal-worker-processes.ts
+++ b/packages/server/src/terminal/terminal-worker-processes.ts
@@ -1,15 +1,13 @@
 import { readFile } from "node:fs/promises";
-import { z } from "zod";
 import { execCommand } from "../utils/spawn.js";
 import {
   createSystemManagedProcessTable,
   type ManagedProcessCommandRunner,
   type ManagedProcessInspection,
-  windowsPowerShellPath,
 } from "../server/managed-processes/managed-processes.js";
 
-// Process inspection for terminal worker ownership. Birth times are compared as the strings
-// `ps -o lstart` and Win32_Process.CreationDate print, so every reader must print them the same
+// POSIX terminal program birth times are compared as the strings `ps -o lstart` prints,
+// so every reader must print them the same
 // way: `ps` follows LC_TIME, and the worker, the daemon, the supervisor and the CLI can run
 // under different locales. Every `ps` here runs under LC_ALL=C.
 
@@ -27,6 +25,7 @@ export interface ProcessTableEntry {
 export interface TerminalWorkerProcessInspector {
   /** True where the process table names each process's session (Linux). */
   readonly reportsSessions: boolean;
+  readonly reportsBirthTimes: boolean;
   inspect(pid: number): Promise<ManagedProcessInspection>;
   /** One snapshot of every process, for walking descendants. Throws when it cannot be read. */
   listProcesses(): Promise<ProcessTableEntry[]>;
@@ -37,14 +36,6 @@ export interface TerminalWorkerProcessInspector {
   readEnvironment(pid: number): Promise<string[] | null>;
 }
 
-const WindowsProcessListSchema = z.array(
-  z.object({
-    ProcessId: z.number().int(),
-    ParentProcessId: z.number().int().nullable().optional(),
-    CreationDate: z.string().nullable().optional(),
-  }),
-);
-
 function createLocaleNeutralCommandRunner(): ManagedProcessCommandRunner {
   return {
     exec: (command, args) =>
@@ -65,11 +56,16 @@ export function createTerminalWorkerProcessInspector(
   const table = createSystemManagedProcessTable({ platform, commandRunner });
   return {
     reportsSessions: platform === "linux",
-    inspect: (pid) => table.inspect(pid),
-    listProcesses: () =>
+    reportsBirthTimes: platform !== "win32",
+    inspect: (pid) =>
       platform === "win32"
-        ? listWindowsProcesses(commandRunner)
-        : listPosixProcesses(commandRunner, platform),
+        ? Promise.resolve({
+            status: "error",
+            error: new Error("Windows terminal programs have no birth times"),
+          })
+        : table.inspect(pid),
+    listProcesses: () =>
+      platform === "win32" ? Promise.resolve([]) : listPosixProcesses(commandRunner, platform),
     readEnvironment: (pid) => readLinuxEnvironment(platform, pid),
   };
 }
@@ -121,33 +117,6 @@ async function listPosixProcesses(
   return entries;
 }
 
-async function listWindowsProcesses(
-  commandRunner: ManagedProcessCommandRunner,
-): Promise<ProcessTableEntry[]> {
-  const command =
-    "@(Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CreationDate) | ConvertTo-Json -Compress";
-  const { stdout } = await commandRunner.exec(windowsPowerShellPath(), [
-    "-NoProfile",
-    "-NonInteractive",
-    "-Command",
-    command,
-  ]);
-  const parsed: unknown = JSON.parse(stdout.trim());
-  const rows = WindowsProcessListSchema.parse(Array.isArray(parsed) ? parsed : [parsed]);
-  return rows.flatMap((row) =>
-    row.CreationDate
-      ? [
-          {
-            pid: row.ProcessId,
-            ppid: row.ParentProcessId ?? 0,
-            startedAt: row.CreationDate,
-            sessionId: null,
-          },
-        ]
-      : [],
-  );
-}
-
 /**
  * Every process below `rootPid` in the snapshot, plus (where the platform reports sessions)
  * every member of the session `rootPid` led and everything below those members. A PTY program
diff --git a/packages/server/src/terminal/terminal-worker-protocol.test.ts b/packages/server/src/terminal/terminal-worker-protocol.test.ts
index 6ea9a823db..9193a5dabd 100644
--- a/packages/server/src/terminal/terminal-worker-protocol.test.ts
+++ b/packages/server/src/terminal/terminal-worker-protocol.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { classifyTerminalWorkerProtocol } from "./terminal-worker-protocol.js";
+import {
+  classifyTerminalWorkerProtocol,
+  TERMINAL_WORKER_PROTOCOL_VERSION,
+} from "./terminal-worker-protocol.js";
 
 describe("classifyTerminalWorkerProtocol", () => {
   it("rejects the unreleased cell protocol without a draining adapter", () => {
@@ -23,3 +26,8 @@ describe("classifyTerminalWorkerProtocol", () => {
     expect(classifyTerminalWorkerProtocol(reported, 6)).toBe(fit);
   });
 });
+
+it("drains v5 terminals while v6 supplies creation timestamps", () => {
+  expect(TERMINAL_WORKER_PROTOCOL_VERSION).toBe(6);
+  expect(classifyTerminalWorkerProtocol(5)).toBe("previous");
+});
diff --git a/packages/server/src/terminal/terminal-worker-protocol.ts b/packages/server/src/terminal/terminal-worker-protocol.ts
index e781543697..62e731a4dc 100644
--- a/packages/server/src/terminal/terminal-worker-protocol.ts
+++ b/packages/server/src/terminal/terminal-worker-protocol.ts
@@ -1,6 +1,8 @@
 import type { TerminalExitInfo, ServerMessage, ClientMessage } from "./terminal.js";
 import type { TerminalReplayEvent, TerminalReplayOptions } from "./terminal-replay.js";
 export interface WorkerTerminalState {
+  /** COMPAT(terminal-created-at): v6; v5 draining workers omit this, remove after 2027-06. */
+  createdAt?: string;
   rows: number;
   cols: number;
   hasOutput: boolean;
@@ -43,7 +45,7 @@ export interface WorkerCreateTerminalOptions {
 // `shutdown`. A daemon drives a worker of its own version, drains one a version older (no new
 // terminals; it exits after its last terminal), shuts down anything older, and leaves a newer
 // worker running untouched. See docs/terminal-worker.md.
-export const TERMINAL_WORKER_PROTOCOL_VERSION = 5;
+export const TERMINAL_WORKER_PROTOCOL_VERSION = 6;
 
 // Test-only: the protocol version a worker reports, so tests can stand up older and newer
 // workers from one build.
diff --git a/packages/server/src/terminal/terminal-worker-reaper.test.ts b/packages/server/src/terminal/terminal-worker-reaper.test.ts
index a872325d31..ef8d4fe487 100644
--- a/packages/server/src/terminal/terminal-worker-reaper.test.ts
+++ b/packages/server/src/terminal/terminal-worker-reaper.test.ts
@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { Worker } from "node:worker_threads";
 import { isPlatform } from "../test-utils/platform.js";
+import { classifyTerminalProgramProcess } from "./terminal-worker-ownership.js";
 import { currentBootId } from "../server/pid-lock.js";
 import {
   createTerminalWorkerProcessInspector,
@@ -21,6 +22,7 @@ import {
   terminalCleanupRecordPath,
   terminalWorkerDirectory,
   writeTerminalWorkerRecord,
+  writeTerminalCleanupRecord,
   type TerminalWorkerRecord,
 } from "./terminal-worker-record.js";
 
@@ -118,6 +120,7 @@ function withSessionMember(input: {
 }): TerminalWorkerProcessInspector {
   return {
     reportsSessions: true,
+    reportsBirthTimes: true,
     inspect: (pid) => inspector.inspect(pid),
     listProcesses: async () => {
       // A fresh snapshot each call, so it is rewritten in place.
@@ -260,15 +263,29 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
   it("leaves a program alive when its pid now belongs to a process with another birth time", async () => {
     const home = makeHome();
     const unrelated = spawnIdle();
+    const original = { id: "t1", pid: unrelated.pid!, startedAt: "Thu Jan  1 00:00:00 1970" };
     const recordPath = writeRecord(home, {
       pid: await goneProcessPid(),
-      terminals: [{ id: "t1", pid: unrelated.pid!, startedAt: "Thu Jan  1 00:00:00 1970" }],
+      terminals: [original],
     });
 
     await reapTerminalWorkers({ paseoHome: home, inspector, gracefulMs: 0 });
 
     expect(isAlive(unrelated.pid!)).toBe(true);
+    // Completion means the recorded process is gone, even if its PID is occupied.
+    await expect
+      .poll(
+        async () =>
+          !isAlive(original.pid) ||
+          classifyTerminalProgramProcess(original, await inspector.inspect(original.pid)).status ===
+            "unrelated",
+        { timeout: 10000 },
+      )
+      .toBe(true);
     expect(existsSync(recordPath)).toBe(false);
+    expect(
+      classifyTerminalProgramProcess(original, await inspector.inspect(original.pid)),
+    ).toMatchObject({ status: "unrelated" });
   });
 
   it("retires a record from an earlier boot without signaling anything it names", async () => {
@@ -293,6 +310,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
     const killable = spawnIdle();
     const failing: TerminalWorkerProcessInspector = {
       reportsSessions: inspector.reportsSessions,
+      reportsBirthTimes: inspector.reportsBirthTimes,
       inspect: (pid) =>
         pid === uninspectable.pid
           ? Promise.resolve({ status: "error", error: new Error("ps unavailable") })
@@ -489,6 +507,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
     });
     const tableUnavailable: TerminalWorkerProcessInspector = {
       reportsSessions: inspector.reportsSessions,
+      reportsBirthTimes: inspector.reportsBirthTimes,
       inspect: (pid) => inspector.inspect(pid),
       listProcesses: () => Promise.reject(new Error("ps timed out")),
       readEnvironment: (pid) => inspector.readEnvironment(pid),
@@ -562,12 +581,19 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
       const home = makeHome();
       const worker = spawn(
         process.execPath,
-        ["-e", "setInterval(() => {}, 1e9)", "--", "--paseo-terminal-worker", "record-under-test"],
+        [
+          "-e",
+          `require("node:net").createServer(() => {}).listen(${JSON.stringify(path.join(home, "live-record-under-test.sock"))});setInterval(() => {}, 1e9)`,
+          "--",
+          "--paseo-terminal-worker",
+          "record-under-test",
+        ],
         { detached: true, stdio: "ignore" },
       );
       children.push(worker);
       const recordPath = writeRecord(home, {
         pid: worker.pid!,
+        socketPath: path.join(home, "live-record-under-test.sock"),
         identity: {
           startedAt: await birthOf(worker.pid!),
           commandLine: "node -e --paseo-terminal-worker record-under-test",
@@ -608,12 +634,19 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
       const home = makeHome();
       const worker = spawn(
         process.execPath,
-        ["-e", "setInterval(() => {}, 1e9)", "--", "--paseo-terminal-worker", "record-under-test"],
+        [
+          "-e",
+          `require("node:net").createServer(() => {}).listen(${JSON.stringify(path.join(home, "live-record-under-test.sock"))});setInterval(() => {}, 1e9)`,
+          "--",
+          "--paseo-terminal-worker",
+          "record-under-test",
+        ],
         { detached: true, stdio: "ignore" },
       );
       children.push(worker);
       const recordPath = writeRecord(home, {
         pid: worker.pid!,
+        socketPath: path.join(home, "live-record-under-test.sock"),
         identity: {
           startedAt: await birthOf(worker.pid!),
           commandLine: "node -e --paseo-terminal-worker record-under-test",
@@ -638,3 +671,128 @@ describe.skipIf(isPlatform("win32"))("terminal worker reaper", () => {
     });
   });
 });
+
+// Real sockets identify workers on every platform, independently of program birth times.
+describe("terminal worker reaper without process identity", () => {
+  const noIdentity = createTerminalWorkerProcessInspector();
+
+  // A live process standing in for a worker that cannot answer: it listens on the record's
+  // socket and never replies to the hello.
+  async function spawnSilentListener(socketPath: string): Promise<ChildProcess> {
+    const listener = spawnIdle(`
+      require("node:net").createServer(() => {}).listen(${JSON.stringify(socketPath)}, () => {
+        process.stdout.write("listening\\n");
+      });
+    `);
+    await new Promise((resolve) => listener.stdout!.once("data", resolve));
+    return listener;
+  }
+
+  it("retires the record of a gone worker and its gone programs without the identity query", async () => {
+    const home = makeHome();
+    const recordPath = writeRecord(home, {
+      pid: await goneProcessPid(),
+      terminals: [{ id: "t1", pid: await goneProcessPid(), startedAt: null }],
+    });
+
+    const result = await reapTerminalWorkers({ paseoHome: home, inspector: noIdentity });
+
+    expect(result).toEqual({ records: 1, retired: 1, signaled: [] });
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it("does not kill a newer legacy worker when a stale cleanup secret is rejected", async () => {
+    const home = makeHome();
+    const socketPath =
+      process.platform === "win32"
+        ? `\\\\.\\pipe\\paseo-legacy-${Date.now()}`
+        : path.join(home, "legacy.sock");
+    const listener = spawnIdle(`
+      require("node:net").createServer(socket => socket.on("data", () => socket.destroy())).listen(${JSON.stringify(socketPath)}, () => process.stdout.write("ready"));
+    `);
+    await new Promise((resolve) => listener.stdout!.once("data", resolve));
+    const stalePath = writeRecord(home, { pid: listener.pid!, socketPath, secret: "stale-secret" });
+    const stale = await readTerminalWorkerRecord(stalePath);
+    const cleanupPath = await writeTerminalCleanupRecord(home, {
+      ...stale,
+      closing: {
+        unresolved: [
+          { pid: listener.pid!, role: "worker", reason: "still alive", detail: "old cleanup" },
+        ],
+      },
+    });
+    writeRecord(home, {
+      pid: listener.pid!,
+      recordId: "newer-worker",
+      socketPath,
+      secret: "new-secret",
+    });
+    await expect(
+      reapTerminalWorkers({
+        paseoHome: home,
+        gracefulMs: 0,
+        confirmMs: 50,
+        recordPaths: [cleanupPath],
+      }),
+    ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+    expect(isAlive(listener.pid!)).toBe(true);
+  });
+
+  it("force kills a worker whose socket accepts but never answers", async () => {
+    const home = makeHome();
+    const socketPath =
+      process.platform === "win32"
+        ? `\\\\.\\pipe\\paseo-test-${Date.now()}-record-under-test`
+        : path.join(home, "w-record-under-test.sock");
+    const listener = await spawnSilentListener(socketPath);
+    writeRecord(home, {
+      pid: listener.pid!,
+      socketPath,
+    });
+
+    const result = await reapTerminalWorkers({
+      paseoHome: home,
+      inspector: noIdentity,
+      gracefulMs: 300,
+    });
+    expect(result.signaled).toContain(listener.pid);
+    await waitUntilGone(listener.pid!);
+    expect(isAlive(listener.pid!)).toBe(false);
+    expect(await readUnconfirmedTerminalCleanup(home)).toEqual([]);
+  });
+
+  it("treats a live pid with nothing on the worker's socket as another process, signals it never, and retires the record", async () => {
+    const home = makeHome();
+    const reusedWorkerPid = spawnIdle().pid!;
+    const recordPath = writeRecord(home, {
+      pid: reusedWorkerPid,
+    });
+
+    const result = await reapTerminalWorkers({ paseoHome: home, inspector: noIdentity });
+
+    expect(result).toEqual({ records: 1, retired: 1, signaled: [] });
+    expect(isAlive(reusedWorkerPid)).toBe(true);
+    expect(existsSync(recordPath)).toBe(false);
+  });
+
+  it.skipIf(isPlatform("win32"))(
+    "never signals a live terminal program recorded without a birth time",
+    async () => {
+      const home = makeHome();
+      const program = spawnIdle();
+      writeRecord(home, {
+        pid: await goneProcessPid(),
+        terminals: [{ id: "t1", pid: program.pid!, startedAt: null }],
+      });
+
+      await expect(
+        reapTerminalWorkers({ paseoHome: home, inspector, confirmMs: 200 }),
+      ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+
+      expect(isAlive(program.pid!)).toBe(true);
+      expect(await readUnconfirmedTerminalCleanup(home)).toEqual([
+        expect.objectContaining({ pid: program.pid!, role: "terminal program" }),
+      ]);
+    },
+  );
+});
diff --git a/packages/server/src/terminal/terminal-worker-reaper.ts b/packages/server/src/terminal/terminal-worker-reaper.ts
index 2647d4b25e..da229f9ddd 100644
--- a/packages/server/src/terminal/terminal-worker-reaper.ts
+++ b/packages/server/src/terminal/terminal-worker-reaper.ts
@@ -6,7 +6,8 @@ import { connectTerminalWorker } from "./terminal-worker-client.js";
 import { pruneTerminalWorkerRuntimes } from "./terminal-worker-runtime.js";
 import {
   classifyTerminalProgramProcess,
-  classifyTerminalWorkerProcess,
+  identifyTerminalWorker,
+  authorizeTerminalWorkerTermination,
   type ProcessOwnership,
 } from "./terminal-worker-ownership.js";
 import {
@@ -30,7 +31,8 @@ import {
 // uses for its own kill stop. Every kill intent (stop, quit, --force, a kill restart whose
 // shutdown hung, a dead or stopped worker, a program that ignores HUP) ends here:
 //
-// 1. Classify the worker and every terminal program of each record on its own, by birth time.
+// 1. Classify each record's worker by its pid and socket, and every terminal program on its
+//    own, by birth time (Windows records none; its programs end with their worker's console).
 //    A record from an earlier boot names only processes the reboot ended: retire it unsignaled.
 //    Descendants of owned programs (and, on Linux, members of their sessions) join the
 //    candidates from one process-table snapshot taken before anything is signaled. Once a
@@ -38,9 +40,10 @@ import {
 //    program's session joins only when its environment carries that terminal's id. When the
 //    table cannot be read, nothing in the record is signaled: ending a program would reparent
 //    the children only the table can find, and a retry could never reach them again.
-// 2. An owned worker gets an authenticated `shutdown`: it kills each terminal and waits for it.
-// 3. After `gracefulMs`, SIGKILL whatever owned process is left, re-inspecting right before
-//    each signal.
+// 2. A worker whose socket accepts is owned and gets an authenticated `shutdown`: it kills each
+//    terminal and waits for it.
+// 3. After `gracefulMs`, SIGKILL whatever owned process is left, checking its socket or birth
+//    time again right before each signal.
 // 4. Succeed only when every candidate is gone or proven unrelated. Otherwise keep a record of
 //    the unresolved entries, marked closing, in a cleanup record no worker rewrites, and throw
 //    TerminalCleanupNotConfirmedError. An unreadable record is never reported confirmed.
@@ -161,7 +164,7 @@ export interface ReapTerminalWorkersOptions {
 
 interface Candidate {
   pid: number;
-  startedAt: string;
+  startedAt: string | null;
   role: UnresolvedTerminalProcess["role"];
   terminalId: string;
   state: ProcessOwnership;
@@ -252,7 +255,7 @@ async function reapRecord(
     return { signaled: [], unresolved: [] };
   }
 
-  const worker = classifyTerminalWorkerProcess(record, await inspector.inspect(record.pid));
+  const worker = await identifyTerminalWorker(record);
   const discovery = await collectCandidates(record, inspector, log);
   const tracked: TrackedProcesses = {
     record,
@@ -265,13 +268,11 @@ async function reapRecord(
     return await keepUnresolved(input, tracked, [], `not signaled: ${discovery.tableError}`);
   }
 
-  if (tracked.worker.status === "owned" && input.gracefulMs > 0) {
-    await requestWorkerShutdown(record, input.gracefulMs, log);
+  const shutdownMs = shutdownWindow(tracked.worker, input.gracefulMs);
+  if (shutdownMs > 0) {
+    await requestWorkerShutdown(record, shutdownMs, log);
   }
-  await waitUntilSettled(
-    tracked,
-    Date.now() + (tracked.worker.status === "owned" ? input.gracefulMs : 0),
-  );
+  await waitUntilSettled(tracked, Date.now() + shutdownMs);
 
   let signaled: number[] = [];
   if (!isSettled(tracked)) {
@@ -282,6 +283,13 @@ async function reapRecord(
   return await keepUnresolved(input, tracked, signaled, null);
 }
 
+// Only an accepting socket authorizes shutdown and eventual forced termination.
+function shutdownWindow(worker: ProcessOwnership, gracefulMs: number): number {
+  if (worker.status === "owned") return gracefulMs;
+
+  return 0;
+}
+
 // Retires the record when every process it names is settled; otherwise writes the cleanup
 // record, marked closing, with only the unresolved entries. A live worker keeps rewriting its
 // own record, so the closing state never goes there. `notSignaled` explains open processes that
@@ -337,10 +345,7 @@ function isSettled(tracked: TrackedProcesses): boolean {
 
 async function refreshTracked(tracked: TrackedProcesses): Promise<void> {
   if (isOpen(tracked.worker)) {
-    tracked.worker = classifyTerminalWorkerProcess(
-      tracked.record,
-      await tracked.inspector.inspect(tracked.record.pid),
-    );
+    tracked.worker = await identifyTerminalWorker(tracked.record);
   }
   for (const candidate of tracked.candidates) {
     if (isOpen(candidate.state)) {
@@ -369,7 +374,7 @@ async function forceKillOwned(
   const { record, inspector } = tracked;
   const signaled: number[] = [];
   if (tracked.worker.status === "owned") {
-    tracked.worker = classifyTerminalWorkerProcess(record, await inspector.inspect(record.pid));
+    tracked.worker = await authorizeTerminalWorkerTermination(record);
     if (tracked.worker.status === "owned") {
       await forceKillWorker(record.pid);
       signaled.push(record.pid);
@@ -447,6 +452,7 @@ async function collectCandidates(
   log: NonNullable<ReapTerminalWorkersOptions["log"]>,
 ): Promise<CandidateDiscovery> {
   const candidates = new Map<number, Candidate>();
+  if (inspector.reportsBirthTimes === false) return { candidates: [], tableError: null };
   for (const entry of record.terminals) {
     candidates.set(entry.pid, {
       pid: entry.pid,
@@ -461,8 +467,12 @@ async function collectCandidates(
   // already gone: the kernel keeps a session id reserved while a member lives, so a job the
   // shell left behind is still found. A pid reused by another process (unrelated) leads someone
   // else's session and is never walked.
+  // A program recorded without a birth time is never walked: the worker could not read the
+  // process table when it started it, so the walk would only keep the cleanup unconfirmed.
   const roots = Array.from(candidates.values()).filter(
-    (c) => c.state.status === "owned" || (c.state.status === "gone" && inspector.reportsSessions),
+    (c) =>
+      c.state.status === "owned" ||
+      (c.state.status === "gone" && c.startedAt !== null && inspector.reportsSessions),
   );
   if (roots.length === 0) return { candidates: Array.from(candidates.values()), tableError: null };
 
@@ -564,7 +574,7 @@ async function requestWorkerShutdown(
       timeoutMs: Math.min(gracefulMs, 2_000),
     });
   } catch (error) {
-    // A worker that cannot be reached is escalated by birth time below; a failed connection
+    // A worker that cannot be reached is probed again below; a failed authentication
     // alone never authorizes a signal.
     log("Terminal worker did not accept a shutdown request", {
       pid: record.pid,
diff --git a/packages/server/src/terminal/terminal-worker-record.ts b/packages/server/src/terminal/terminal-worker-record.ts
index 3176d2ee8e..63ac0ddd91 100644
--- a/packages/server/src/terminal/terminal-worker-record.ts
+++ b/packages/server/src/terminal/terminal-worker-record.ts
@@ -4,14 +4,20 @@ import path from "node:path";
 import { z } from "zod";
 import { writePrivateFileAtomicSync, writePrivateFileAtomic } from "../server/private-files.js";
 
-// Owner-only metadata a detached terminal worker leaves in $PASEO_HOME so the next daemon can
-// find, authenticate and adopt it, and so cleanup can identify every process it is allowed to
-// signal. Process identity is the birth time `ps`/Win32_Process report, never the pid alone.
+// Owner-only metadata used to find and authenticate workers in the locked home.
 
 const TerminalWorkerTerminalEntrySchema = z.object({
   id: z.string().min(1),
   pid: z.number().int().positive(),
+  // Null when the program's birth time could not be read: it is never signaled.
+  startedAt: z.string().min(1).nullable(),
+});
+
+// The birth time and command line workers up to 0.15.1 recorded about themselves. Still read
+// from their records, never written, and never consulted: the socket identifies a worker.
+const LegacyTerminalWorkerIdentitySchema = z.object({
   startedAt: z.string().min(1),
+  commandLine: z.string().min(1),
 });
 
 // One process a cleanup could not confirm gone, kept so a later caller (a retry, or a remote
@@ -28,10 +34,7 @@ const TerminalWorkerRecordSchema = z.object({
   pid: z.number().int().positive(),
   bootId: z.string().nullable(),
   createdAt: z.string().min(1),
-  identity: z.object({
-    startedAt: z.string().min(1),
-    commandLine: z.string().min(1),
-  }),
+  identity: LegacyTerminalWorkerIdentitySchema.optional(),
   // Read loosely: a version this daemon cannot interpret marks a worker from a newer Paseo
   // (classifyTerminalWorkerProtocol), not an unreadable record.
   protocolVersion: z.union([z.number(), z.string()]),
diff --git a/packages/server/src/terminal/terminal-worker-runtime.test.ts b/packages/server/src/terminal/terminal-worker-runtime.test.ts
index feb4bf3309..257787b944 100644
--- a/packages/server/src/terminal/terminal-worker-runtime.test.ts
+++ b/packages/server/src/terminal/terminal-worker-runtime.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import {
+  chmodSync,
   existsSync,
   mkdirSync,
   mkdtempSync,
@@ -54,6 +55,7 @@ function makeSources(bundleSource = "export {};\n"): {
   mkdirSync(native, { recursive: true });
   writeFileSync(path.join(native, "pty.node"), "native");
   writeFileSync(path.join(native, "spawn-helper"), "#!/bin/sh\n", { mode: 0o755 });
+  chmodSync(path.join(native, "spawn-helper"), 0o755);
   // Another platform's build is not copied.
   mkdirSync(path.join(nodePtyDirectory, "prebuilds", "other-platform"));
   return { bundleDirectory, nodePtyDirectory };
diff --git a/packages/server/src/terminal/terminal-worker-socket-path.test.ts b/packages/server/src/terminal/terminal-worker-socket-path.test.ts
index 409cf60c81..6017177fcf 100644
--- a/packages/server/src/terminal/terminal-worker-socket-path.test.ts
+++ b/packages/server/src/terminal/terminal-worker-socket-path.test.ts
@@ -37,6 +37,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
     const home = makeDir("tw-h-", "/tmp");
     const socketPath = resolveTerminalWorkerSocketPath({
       paseoHome: home,
+      recordId: "test",
       workerPid: 4242,
       platform: "darwin",
     });
@@ -51,6 +52,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
     const uid = process.getuid!();
     const socketPath = resolveTerminalWorkerSocketPath({
       paseoHome: home,
+      recordId: "test",
       workerPid: 99999,
       platform: "darwin",
       tmpDir,
@@ -71,6 +73,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
     // also be refused, and /tmp/paseo-<uid> takes over.
     const socketPath = resolveTerminalWorkerSocketPath({
       paseoHome: home,
+      recordId: "test",
       workerPid: 7,
       platform: "darwin",
       tmpDir,
@@ -84,6 +87,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
       path.dirname(
         resolveTerminalWorkerSocketPath({
           paseoHome: home,
+          recordId: "test",
           workerPid: 7,
           platform: "darwin",
           tmpDir: wideTmp,
@@ -101,6 +105,7 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
     try {
       resolveTerminalWorkerSocketPath({
         paseoHome: home,
+        recordId: "test",
         workerPid: 7,
         platform: "darwin",
         tmpDir,
@@ -123,7 +128,11 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
 
   it("accepts a real listen on the chosen path", async () => {
     const home = makeDir("tw-l-", "/tmp");
-    const socketPath = resolveTerminalWorkerSocketPath({ paseoHome: home, workerPid: 5 });
+    const socketPath = resolveTerminalWorkerSocketPath({
+      paseoHome: home,
+      recordId: "test",
+      workerPid: 5,
+    });
     const server = createServer();
     await new Promise<void>((resolve, reject) => {
       server.once("error", reject);
@@ -132,3 +141,10 @@ describe.skipIf(isPlatform("win32"))("terminal worker socket path", () => {
     await new Promise<void>((resolve) => server.close(() => resolve()));
   });
 });
+
+it("uses a separate socket for each record even when its pid is reused", () => {
+  const paseoHome = makeDir("tw-id-");
+  const first = resolveTerminalWorkerSocketPath({ paseoHome, workerPid: 42, recordId: "old" });
+  const second = resolveTerminalWorkerSocketPath({ paseoHome, workerPid: 42, recordId: "new" });
+  expect(first).not.toBe(second);
+});
diff --git a/packages/server/src/terminal/terminal-worker-socket-path.ts b/packages/server/src/terminal/terminal-worker-socket-path.ts
index 99fce0e64c..d9a153c598 100644
--- a/packages/server/src/terminal/terminal-worker-socket-path.ts
+++ b/packages/server/src/terminal/terminal-worker-socket-path.ts
@@ -18,6 +18,7 @@ const OWNER_ONLY_MODE = 0o700;
 export interface TerminalWorkerSocketPathInput {
   paseoHome: string;
   workerPid: number;
+  recordId: string;
   platform?: NodeJS.Platform;
   tmpDir?: string;
   uid?: number;
@@ -60,7 +61,7 @@ export function terminalWorkerSocketId(paseoHome: string, workerPid: number): st
  */
 export function resolveTerminalWorkerSocketPath(input: TerminalWorkerSocketPathInput): string {
   const platform = input.platform ?? process.platform;
-  const id = terminalWorkerSocketId(input.paseoHome, input.workerPid);
+  const id = terminalWorkerSocketId(input.paseoHome, input.workerPid) + "-" + input.recordId;
   if (platform === "win32") {
     return `\\\\.\\pipe\\paseo-tw-${id}`;
   }
diff --git a/packages/server/src/terminal/terminal.test.ts b/packages/server/src/terminal/terminal.test.ts
index 69e6468673..d36e86d732 100644
--- a/packages/server/src/terminal/terminal.test.ts
+++ b/packages/server/src/terminal/terminal.test.ts
@@ -410,7 +410,12 @@ describe("createTerminal", () => {
           cwd: realpathSync(tmpdir()),
           cols: 500,
           command: process.execPath,
-          args: ["-e", "process.stdout.write(JSON.stringify(process.argv.slice(1)))", nastyPrompt],
+          // Keep the PTY alive until the screen assertion; exit disposes its parser.
+          args: [
+            "-e",
+            "process.stdout.write(JSON.stringify(process.argv.slice(1))); setInterval(() => {}, 100000)",
+            nastyPrompt,
+          ],
         }),
       );
 
@@ -563,6 +568,71 @@ describe("createTerminal", () => {
     expect(state.grid[0][1].char).toBe("");
   });
 
+  it("reports the cursor column after an emoji cluster in DSR replies", async () => {
+    // Programs that measure the cursor (prompts, TUIs) must see the same
+    // column the client renders: an emoji occupies two cells.
+    const program = `
+      process.stdin.setRawMode(true);
+      process.stdin.once("data", (reply) => {
+        process.stdout.write("\\r\\nREPLY " + JSON.stringify(reply.toString()).slice(2, -1));
+      });
+      process.stdout.write("A😀\\x1b[6n");
+      setInterval(() => {}, 100000);
+    `;
+    const session = trackSession(
+      await createTerminal({
+        workspaceId: "ws-test",
+        cwd: realpathSync(tmpdir()),
+        cols: 40,
+        rows: 5,
+        command: process.execPath,
+        args: ["-e", program],
+      }),
+    );
+
+    const state = await waitForState(session, (current) =>
+      getRowText(current, 1).startsWith("REPLY"),
+    );
+
+    expect(getRowText(state, 1)).toBe("REPLY u001b[1;4R");
+  });
+
+  it("replays emoji clusters at their columns with the cursor after them", async () => {
+    const text = "A😀B❤️C👋🏽D👨‍👩‍👧E";
+    const session = trackSession(
+      await createTerminal({
+        workspaceId: "ws-test",
+        cwd: realpathSync(tmpdir()),
+        cols: 40,
+        rows: 5,
+        command: process.execPath,
+        args: [
+          "-e",
+          `process.stdout.write(${JSON.stringify(text)}); setInterval(() => {}, 100000);`,
+        ],
+      }),
+    );
+
+    const state = await waitForState(session, (current) => rowHasChar(current.grid[0], "E"));
+
+    expect(state.grid[0].slice(0, 13).map((cell) => cell.char)).toEqual([
+      "A",
+      "😀",
+      "",
+      "B",
+      "❤️",
+      "",
+      "C",
+      "👋🏽",
+      "",
+      "D",
+      "👨‍👩‍👧",
+      "",
+      "E",
+    ]);
+    expect(state.cursor).toEqual({ row: 0, col: 13 });
+  });
+
   it("captures exit diagnostics from the terminal buffer", async () => {
     const session = trackSession(
       await createTerminal({
@@ -1632,6 +1702,52 @@ it.each([false, true])(
   },
 );
 
+it.each([
+  { name: "SGR", modes: "\x1b[?1006h", wheel: "\x1b[<64;10;5M" },
+  { name: "SGR pixels", modes: "\x1b[?1016h", wheel: "\x1b[<64;80;90M" },
+  { name: "disabled SGR", modes: "\x1b[?1006h\x1b[?1006l", wheel: "\x1b[M`*%" },
+])("preserves $name wheel reports across repeated terminal replays", async (input) => {
+  const source = new xterm.Terminal({ rows: 10, cols: 80, allowProposedApi: true });
+  const receiver = new xterm.Terminal({ rows: 10, cols: 80, allowProposedApi: true });
+  const serialize = createTerminalSerializer(source);
+  const wheel = {
+    button: 4,
+    action: 0,
+    col: 10,
+    row: 5,
+    x: 80,
+    y: 90,
+    ctrl: false,
+    alt: false,
+    shift: false,
+  };
+  // Mouse encoding is not exposed by xterm's public modes API.
+  const mouse = (
+    receiver as unknown as {
+      _core: {
+        mouseStateService: {
+          encodeMouseEvent(event: typeof wheel): string;
+        };
+      };
+    }
+  )._core.mouseStateService;
+  try {
+    await new Promise<void>((resolve) =>
+      source.write("\x1b[?1049h\x1b[?1002h" + input.modes + "TRANSCRIPT", resolve),
+    );
+    for (let replay = 0; replay < 2; replay++) {
+      receiver.reset();
+      await new Promise<void>((resolve) => receiver.write(serialize(), resolve));
+      expect(receiver.buffer.active.type).toBe("alternate");
+      expect(receiver.modes.mouseTrackingMode).toBe("drag");
+      expect(mouse.encodeMouseEvent(wheel)).toBe(input.wheel);
+    }
+  } finally {
+    receiver.dispose();
+    source.dispose();
+  }
+});
+
 it.each([
   { name: "unset", presentation: "", style: undefined, visible: true },
   {
diff --git a/packages/server/src/terminal/terminal.ts b/packages/server/src/terminal/terminal.ts
index 3294c11b93..183be5e8bf 100644
--- a/packages/server/src/terminal/terminal.ts
+++ b/packages/server/src/terminal/terminal.ts
@@ -1,5 +1,5 @@
 import * as pty from "node-pty";
-import xterm, { type Terminal as TerminalType } from "@xterm/headless";
+import type { Terminal as TerminalType } from "@xterm/headless";
 import { randomUUID } from "crypto";
 import {
   accessSync,
@@ -25,6 +25,7 @@ import {
   findExecutable,
   findExecutableWithoutProbing,
 } from "../executable-resolution/executable-resolution.js";
+import { createHeadlessTerminal } from "./headless-terminal.js";
 import { createTerminalSerializer } from "./terminal-serializer.js";
 import {
   captureTerminalLines,
@@ -36,7 +37,6 @@ import { TerminalInputModeTracker } from "@getpaseo/protocol/terminal-input-mode
 import { TerminalActivityTracker } from "./activity/terminal-activity-tracker.js";
 import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
 
-const { Terminal } = xterm;
 const require = createRequire(import.meta.url);
 let nodePtySpawnHelperChecked = false;
 const TERMINAL_TITLE_DEBOUNCE_MS = 150;
@@ -88,6 +88,8 @@ export interface TerminalActivityTransition {
 }
 
 export interface TerminalSession {
+  /** Absent on terminal workers started before creation timestamps were tracked. */
+  createdAt?: string;
   id: string;
   name: string;
   cwd: string;
@@ -796,13 +798,7 @@ export async function createTerminal(
   const activityChangeListeners = new Set<(transition: TerminalActivityTransition) => void>();
   let titleChangeSubscription: { dispose(): void } | null = null;
 
-  // Create xterm.js headless terminal
-  const terminal = new Terminal({
-    rows,
-    cols,
-    scrollback: 10000,
-    allowProposedApi: true,
-  });
+  const terminal = createHeadlessTerminal({ rows, cols, scrollback: 10000 });
 
   const serialize = createTerminalSerializer(terminal);
 
@@ -1384,6 +1380,7 @@ export async function createTerminal(
 
   return {
     id,
+    createdAt: new Date().toISOString(),
     pid: ptyProcess.pid,
     name,
     cwd,
diff --git a/packages/server/src/terminal/test-utils/terminal-state.ts b/packages/server/src/terminal/test-utils/terminal-state.ts
index 0fd4777b4c..fb5f5d610a 100644
--- a/packages/server/src/terminal/test-utils/terminal-state.ts
+++ b/packages/server/src/terminal/test-utils/terminal-state.ts
@@ -1,15 +1,14 @@
-import xterm from "@xterm/headless";
 import type { TerminalState } from "@getpaseo/protocol/messages";
+import { createHeadlessTerminal } from "../headless-terminal.js";
 import type { LocalTerminalSession } from "../terminal.js";
 
 /** Observe the public ANSI replay using a real receiver; no production cell extraction API. */
 export async function readTerminalState(session: LocalTerminalSession): Promise<TerminalState> {
   const { metadata, data } = session.serializeReplay();
-  const terminal = new xterm.Terminal({
+  const terminal = createHeadlessTerminal({
     rows: metadata.rows,
     cols: metadata.cols,
     scrollback: 10000,
-    allowProposedApi: true,
   });
   try {
     await new Promise<void>((resolve) => terminal.write(data, resolve));
diff --git a/packages/server/src/terminal/worker-terminal-manager.test.ts b/packages/server/src/terminal/worker-terminal-manager.test.ts
index 7d91ec180e..e57e413b4c 100644
--- a/packages/server/src/terminal/worker-terminal-manager.test.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.test.ts
@@ -50,6 +50,7 @@ import type {
   WorkerTerminalState,
   TerminalWorkerToParentMessage,
 } from "./terminal-worker-protocol.js";
+import { classifyTerminalProgramProcess } from "./terminal-worker-ownership.js";
 import { createTerminalWorkerProcessInspector } from "./terminal-worker-processes.js";
 import {
   readUnconfirmedTerminalCleanup,
@@ -61,15 +62,22 @@ import {
   readTerminalWorkerRecord,
   terminalWorkerDirectory,
   terminalWorkerRecordPath,
+  writeTerminalWorkerRecord,
+  writeTerminalCleanupRecord,
   type TerminalWorkerRecord,
 } from "./terminal-worker-record.js";
-import { TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV } from "./terminal-worker-protocol.js";
+import {
+  TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV,
+  TERMINAL_WORKER_PROTOCOL_VERSION,
+} from "./terminal-worker-protocol.js";
 import {
   NoTerminalWorkerAvailableError,
   TerminalWorkerIncompatibleError,
 } from "./terminal-worker-pool.js";
 import { connectTerminalWorker } from "./terminal-worker-client.js";
-import { launchTerminalWorker } from "./terminal-worker-launch.js";
+import { launchTerminalWorker, TerminalWorkerLaunchError } from "./terminal-worker-launch.js";
+import { currentBootId } from "../server/pid-lock.js";
+import { spawn } from "node:child_process";
 
 type TerminalRow = TerminalState["grid"][number];
 
@@ -439,26 +447,24 @@ it("creates a terminal through the worker and streams output", async () => {
     }),
   );
   const messages: string[] = [];
-  let readinessEvents = 0;
+  let snapshotReady = false;
   const unsubscribe = session.subscribe((message) => {
     if (message.type === "output") {
       messages.push(message.data);
     }
     if (message.type === "snapshotReady") {
-      readinessEvents += 1;
+      snapshotReady = true;
     }
   });
-  await new Promise((resolve) => setTimeout(resolve, 100));
-  expect(readinessEvents).toBe(1);
+  // Subscription and initial PTY output each announce readiness; their order depends on startup.
+  await waitForCondition(() => snapshotReady, 10000);
 
   session.send({ type: "input", data: "hello\r" });
 
   await waitForCondition(() => messages.join("").includes("worker-output:hello"), 10000);
-  await new Promise((resolve) => setTimeout(resolve, 100));
   unsubscribe();
 
   expect(messages.join("")).toContain("worker-output:hello");
-  expect(readinessEvents).toBe(1);
 });
 
 it("delivers rapid small writes complete and in order through worker coalescing", async () => {
@@ -811,7 +817,7 @@ async function recordedTerminalPids(paseoHome: string): Promise<Map<string, numb
 }
 
 it.each([false, true])(
-  "never adopts a live worker's terminals after a kill cleanup it could not finish, even once the worker rewrites its record (held reader: %s)",
+  "never adopts a closing worker's terminals even once it rewrites its record (held reader: %s)",
   async (holdReader) => {
     const paseoHome = createTemporaryHome();
     const cwd = mkdtempSync(join(tmpdir(), "worker-terminal-manager-unfinished-kill-"));
@@ -843,17 +849,22 @@ it.each([false, true])(
     const remainingPid = pids.get(remaining.id)!;
     const [record] = await workerRecords(paseoHome);
 
-    // A kill cleanup whose process table read fails signals nothing and leaves the worker live.
+    // Seed a retained cleanup through the same record interface the reaper writes. Windows
+    // does not read program birth times, so a process-table failure cannot create this state.
     const inspector = createTerminalWorkerProcessInspector();
-    await expect(
-      reapTerminalWorkers({
-        paseoHome,
-        inspector: {
-          ...inspector,
-          listProcesses: () => Promise.reject(new Error("ps timed out")),
-        },
-      }),
-    ).rejects.toBeInstanceOf(TerminalCleanupNotConfirmedError);
+    await writeTerminalCleanupRecord(paseoHome, {
+      ...record!,
+      closing: {
+        unresolved: [
+          {
+            pid: record!.pid,
+            role: "worker",
+            reason: "still alive",
+            detail: "shutdown was not confirmed",
+          },
+        ],
+      },
+    });
     expect((await readUnconfirmedTerminalCleanup(paseoHome)).length).toBeGreaterThan(0);
 
     // Keep an ordinary reader open until the worker delivers the terminal exit.
@@ -866,7 +877,18 @@ it.each([false, true])(
       writeFileSync(exitRequestPath, "");
       await waitForCondition(() => first.getTerminal(ending.id) === undefined, 10000);
       expect(existsSync(exitObservedPath)).toBe(true);
-      expect(isProcessAlive(endingPid)).toBe(false);
+      const originalEnding = record!.terminals.find((entry) => entry.id === ending.id)!;
+      // Exit delivery does not reserve the PID. Wait for the original process to
+      // disappear, allowing Windows to reuse its PID just as in the restart check below.
+      await expect
+        .poll(
+          async () =>
+            !isProcessAlive(endingPid) ||
+            classifyTerminalProgramProcess(originalEnding, await inspector.inspect(endingPid))
+              .status === "unrelated",
+          { timeout: 10000 },
+        )
+        .toBe(true);
     } finally {
       if (recordFd !== null) closeSync(recordFd);
     }
@@ -881,8 +903,19 @@ it.each([false, true])(
 
     expect(manager.getTerminal(remaining.id)).toBeUndefined();
     expect(await manager.getTerminals(cwd)).toEqual([]);
-    await waitForCondition(() => !isProcessAlive(remainingPid), 10000);
     expect(await readUnconfirmedTerminalCleanup(paseoHome)).toEqual([]);
+    const original = record!.terminals.find((entry) => entry.id === remaining.id)!;
+    // Startup can launch a new worker after cleanup and Windows can reuse the old PID.
+    // Require the original process to be gone, not the numeric PID to remain unused.
+    await expect
+      .poll(
+        async () =>
+          !isProcessAlive(remainingPid) ||
+          classifyTerminalProgramProcess(original, await inspector.inspect(remainingPid)).status ===
+            "unrelated",
+        { timeout: 10000 },
+      )
+      .toBe(true);
   },
 );
 
@@ -1611,29 +1644,41 @@ it.each([1, 4])(
   async (version) => {
     const paseoHome = createTemporaryHome();
     const old = await leaveWorkerWithTerminal(paseoHome, version);
+    const [record] = await workerRecords(paseoHome);
+    const program = record!.terminals.find((entry) => entry.id === old.terminalId)!;
+    const inspector = createTerminalWorkerProcessInspector();
 
     manager = await startRealWorkerManager({ paseoHome });
 
-    await waitForCondition(
-      () => !isProcessAlive(old.workerPid) && !isProcessAlive(old.programPid),
-      10000,
-    );
+    expect(await readUnconfirmedTerminalCleanup(paseoHome)).toEqual([]);
+    // Startup launches a replacement worker after cleanup. Either old PID may already
+    // belong to another process, so verify that the recorded birth identities are gone.
+    await waitForCondition(() => !isProcessAlive(record!.pid), 10000);
+    await expect
+      .poll(
+        async () =>
+          !isProcessAlive(program.pid) ||
+          classifyTerminalProgramProcess(program, await inspector.inspect(program.pid)).status ===
+            "unrelated",
+        { timeout: 10000 },
+      )
+      .toBe(true);
     expect(manager.getTerminal(old.terminalId)).toBeUndefined();
     const workers = await workerRecords(paseoHome);
     expect(workers).toHaveLength(1);
-    expect(workers[0]!.protocolVersion).toBe(5);
+    expect(workers[0]!.protocolVersion).toBe(6);
   },
 );
 
 it("leaves a worker from a newer Paseo running, reports it incompatible, and closes it on a kill stop", async () => {
   const paseoHome = createTemporaryHome();
-  const newer = await leaveWorkerWithTerminal(paseoHome, 6);
+  const newer = await leaveWorkerWithTerminal(paseoHome, 7);
 
   manager = await startRealWorkerManager({ paseoHome });
 
   const unavailable = manager.getUnavailableError?.();
   expect(unavailable).toBeInstanceOf(TerminalWorkerIncompatibleError);
-  expect(unavailable?.message).toContain("worker protocol 6");
+  expect(unavailable?.message).toContain("worker protocol 7");
   await expect(manager.getTerminals(newer.cwd)).rejects.toBeInstanceOf(
     TerminalWorkerIncompatibleError,
   );
@@ -1751,7 +1796,6 @@ it("replays bounded ANSI chunks independently of live output and reconstructs th
       rows: 8,
       cols: 120,
       ...nodeTerminalCommand(`
-      for (let i = 0; i < 800; i++) process.stdout.write("\\x1b[31m" + String(i).padStart(4, "0") + ":" + "x".repeat(100) + "\\x1b[0m\\r\\n");
       require("node:readline").createInterface({ input: process.stdin }).on("line", line => {
         if (line !== "before") { process.stdout.write("LIVE-AFTER-REPLAY\\r\\n"); return; }
         process.stdout.write("PRE-CUT");
@@ -1761,6 +1805,9 @@ it("replays bounded ANSI chunks independently of live output and reconstructs th
           process.stdout.write("\\r\\n");
         }, 5);
       });
+      // The last history row is the parent's readiness signal. Install input
+      // handling first so observing that row means the fixture can answer.
+      for (let i = 0; i < 800; i++) process.stdout.write("\\x1b[31m" + String(i).padStart(4, "0") + ":" + "x".repeat(100) + "\\x1b[0m\\r\\n");
       setInterval(() => {}, 1000);
     `),
     }),
@@ -1851,7 +1898,8 @@ it("completes a replay larger than the socket budget while a sibling stays usabl
       ...nodeTerminalCommand(`
       const row = Array.from({length: 1000}, (_, i) => "\\x1b[" + (31 + i % 2) + "mX").join("");
       for (let i = 0; i < 900; i++) process.stdout.write(row + "\\r\\n");
-      process.stdout.write("READY-WIDE\\r\\n");
+      // Seeing the marker must mean no trailing newline can still add history.
+      process.stdout.write("READY-WIDE");
       process.stdin.on("data", data => { if (data.toString().includes("small")) { process.stdout.write("SAME-TERMINAL-LIVE\\r\\n"); return; } process.stdout.write("q".repeat(8 * 1024 * 1024) + "\\r\\nRECOVERED-LIVE\\r\\n", () => require("node:fs").writeFileSync(${JSON.stringify(overflowProgress)}, "done")); });
       setInterval(() => {}, 1000);
     `),
@@ -2645,3 +2693,217 @@ it.each([false, true])(
   },
   45000,
 );
+
+// #8810: a worker that cannot start must not take the daemon down. An override that is not a
+// protocol version makes the worker fail before it writes its record, on every platform.
+it("starts without a worker when the worker cannot start, and launches one once it can", async () => {
+  const paseoHome = createTemporaryHome();
+  const previous = process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+  process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = "not-a-version";
+  try {
+    manager = await startRealWorkerManager({ paseoHome });
+    expect(await workerRecords(paseoHome)).toEqual([]);
+    await expect(
+      manager.createTerminal({ workspaceId: "ws-no-worker", cwd: paseoHome }),
+    ).rejects.toThrow(TerminalWorkerLaunchError);
+  } finally {
+    if (previous === undefined) delete process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV];
+    else process.env[TERMINAL_WORKER_PROTOCOL_OVERRIDE_ENV] = previous;
+  }
+
+  trackTerminal(await manager.createTerminal({ workspaceId: "ws-no-worker", cwd: paseoHome }));
+  expect(await workerRecords(paseoHome)).toHaveLength(1);
+}, 30000);
+
+function echoTerminalCommand(prefix: string) {
+  return nodeTerminalCommand(`
+    process.stdin.on("data", (chunk) => {
+      process.stdout.write(${JSON.stringify(prefix)} + chunk.toString());
+    });
+    setInterval(() => {}, 1000);
+  `);
+}
+
+async function expectEcho(session: TerminalSession, prefix: string, input: string): Promise<void> {
+  const messages: string[] = [];
+  const unsubscribe = session.subscribe((message) => {
+    if (message.type === "output") messages.push(message.data);
+  });
+  session.send({ type: "input", data: `${input}\r` });
+  try {
+    await waitForCondition(() => messages.join("").includes(`${prefix}${input}`), 10000);
+  } finally {
+    unsubscribe();
+  }
+}
+
+it("runs terminals without recording a worker process identity", async () => {
+  const paseoHome = createTemporaryHome();
+  manager = await startRealWorkerManager({ paseoHome });
+  const session = trackTerminal(
+    await manager.createTerminal({
+      workspaceId: "ws-no-identity",
+      cwd: paseoHome,
+      ...echoTerminalCommand("no-identity:"),
+    }),
+  );
+  await expectEcho(session, "no-identity:", "hello");
+
+  const [record, ...others] = await workerRecords(paseoHome);
+  expect(others).toEqual([]);
+  expect(record!.identity).toBeUndefined();
+  expect(record!.terminals).toEqual([
+    {
+      id: session.id,
+      pid: expect.any(Number),
+      startedAt: process.platform === "win32" ? null : expect.any(String),
+    },
+  ]);
+}, 30000);
+
+it("adopts terminals over the authenticated socket after a daemon restart", async () => {
+  const paseoHome = createTemporaryHome();
+  const first = await startRealWorkerManager({ paseoHome });
+  const created = await first.createTerminal({
+    workspaceId: "ws-no-identity",
+    cwd: paseoHome,
+    ...echoTerminalCommand("adopted:"),
+  });
+  await first.detach();
+
+  manager = await startRealWorkerManager({ paseoHome });
+
+  const adopted = manager.getTerminal(created.id);
+  expect(adopted).toBeDefined();
+  await expectEcho(adopted!, "adopted:", "after-restart");
+  expect(await workerRecords(paseoHome)).toHaveLength(1);
+}, 30000);
+
+it("closes terminals and their worker through authenticated shutdown", async () => {
+  const paseoHome = createTemporaryHome();
+  const stopping = await startRealWorkerManager({ paseoHome });
+  manager = stopping;
+  await stopping.createTerminal({
+    workspaceId: "ws-no-identity",
+    cwd: paseoHome,
+    ...nodeTerminalCommand("setInterval(() => {}, 1000);"),
+  });
+  const [record] = await workerRecords(paseoHome);
+  const programPid = record!.terminals[0]!.pid;
+
+  await stopping.closeTerminals();
+
+  // The worker closed its terminals before it answered; it stops listening as it exits.
+  expect(isProcessAlive(programPid)).toBe(false);
+  expect(await listTerminalWorkerRecords(paseoHome)).toEqual([]);
+  await waitForCondition(() => !isProcessAlive(record!.pid), 5000);
+}, 30000);
+
+// Startup cleanup and retries can request immediate forced termination.
+it("force closes a worker from cleanup without a grace period", async () => {
+  const paseoHome = createTemporaryHome();
+  const previous = await startRealWorkerManager({ paseoHome });
+  await previous.createTerminal({
+    workspaceId: "ws-no-identity",
+    cwd: paseoHome,
+    ...nodeTerminalCommand("setInterval(() => {}, 1000);"),
+  });
+  const [record] = await workerRecords(paseoHome);
+  const programPid = record!.terminals[0]!.pid;
+  await previous.detach();
+
+  const result = await reapTerminalWorkers({ paseoHome, gracefulMs: 0 });
+
+  expect(result.signaled).toContain(record!.pid);
+  expect(isProcessAlive(programPid)).toBe(false);
+  expect(await listTerminalWorkerRecords(paseoHome)).toEqual([]);
+  await waitForCondition(() => !isProcessAlive(record!.pid), 5000);
+}, 30000);
+
+it("launches past stale records without signaling an unrelated live pid", async () => {
+  const paseoHome = createTemporaryHome();
+  // One worker died; another died and its pid now runs an unrelated process, so nothing
+  // listens on its socket. Neither may count against the two-worker limit or be signaled.
+  const exited = spawn(process.execPath, ["-e", ""], { stdio: "ignore" });
+  await new Promise((resolve) => exited.once("exit", resolve));
+  const reused = spawn(process.execPath, ["-e", "setInterval(() => {}, 1e9)"], {
+    stdio: "ignore",
+  });
+  try {
+    for (const pid of [exited.pid!, reused.pid!]) {
+      writeTerminalWorkerRecord(paseoHome, {
+        recordId: `dead-worker-${pid}`,
+        pid,
+        bootId: currentBootId(),
+        createdAt: new Date().toISOString(),
+        protocolVersion: TERMINAL_WORKER_PROTOCOL_VERSION,
+        paseoVersion: "0.0.0-test",
+        socketPath: join(paseoHome, `gone-${pid}.sock`),
+        secret: "secret-of-a-gone-worker",
+        terminals: [],
+      });
+    }
+    manager = await startRealWorkerManager({ paseoHome });
+    trackTerminal(await manager.createTerminal({ workspaceId: "ws-no-identity", cwd: paseoHome }));
+
+    const records = await workerRecords(paseoHome);
+    expect(records.map((record) => record.pid)).not.toContain(exited.pid);
+    expect(records.map((record) => record.pid)).not.toContain(reused.pid);
+    expect(records).toHaveLength(1);
+    expect(isProcessAlive(reused.pid!)).toBe(true);
+  } finally {
+    reused.kill("SIGKILL");
+  }
+}, 30000);
+
+it("does not reach a newer worker through a stale record with its reused pid", async () => {
+  const paseoHome = createTemporaryHome();
+  manager = await startRealWorkerManager({ paseoHome });
+  const session = trackTerminal(
+    await manager.createTerminal({
+      workspaceId: "stale-worker-record",
+      cwd: paseoHome,
+      ...echoTerminalCommand("alive:"),
+    }),
+  );
+  const [record] = await workerRecords(paseoHome);
+  const staleHome = createTemporaryHome();
+  writeTerminalWorkerRecord(staleHome, {
+    ...record!,
+    recordId: "stale-record",
+    socketPath:
+      process.platform === "win32"
+        ? `\\\\.\\pipe\\paseo-stale-${Date.now()}`
+        : join(staleHome, "gone.sock"),
+    terminals: [],
+  });
+  expect(await reapTerminalWorkers({ paseoHome: staleHome, gracefulMs: 0 })).toMatchObject({
+    retired: 1,
+    signaled: [],
+  });
+  await expectEcho(session, "alive:", "untouched");
+}, 30000);
+
+it.skipIf(!isPlatform("win32"))(
+  "observes terminal program survival after a worker hard crash",
+  async () => {
+    const paseoHome = createTemporaryHome();
+    const previous = await startRealWorkerManager({ paseoHome });
+    await previous.createTerminal({
+      workspaceId: "worker-crash",
+      cwd: paseoHome,
+      ...nodeTerminalCommand("setInterval(() => {}, 1000)"),
+    });
+    const [record] = await workerRecords(paseoHome);
+    await previous.detach();
+    process.kill(record!.pid, "SIGKILL");
+    await waitForCondition(() => !isProcessAlive(record!.pid), 5000);
+    const program = record!.terminals[0]!.pid;
+    try {
+      await waitForCondition(() => !isProcessAlive(program), 5000);
+    } catch {}
+    console.log(`Windows orphaned-program check: ${isProcessAlive(program) ? "survived" : "died"}`);
+    if (isProcessAlive(program)) process.kill(program, "SIGKILL");
+  },
+  30000,
+);
diff --git a/packages/server/src/terminal/worker-terminal-manager.ts b/packages/server/src/terminal/worker-terminal-manager.ts
index 9a82826cec..097def78d3 100644
--- a/packages/server/src/terminal/worker-terminal-manager.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.ts
@@ -21,11 +21,8 @@ import { resolvePaseoCliExecutablePath } from "./paseo-cli-path.js";
 import type { CaptureTerminalLinesResult } from "./terminal-capture.js";
 import { connectTerminalWorker, type TerminalWorkerConnection } from "./terminal-worker-client.js";
 import { launchTerminalWorker } from "./terminal-worker-launch.js";
-import { classifyTerminalWorkerProcess } from "./terminal-worker-ownership.js";
-import {
-  createTerminalWorkerProcessInspector,
-  type TerminalWorkerProcessInspector,
-} from "./terminal-worker-processes.js";
+import { identifyTerminalWorker } from "./terminal-worker-ownership.js";
+import { createTerminalWorkerProcessInspector } from "./terminal-worker-processes.js";
 import { reapTerminalWorkers } from "./terminal-worker-reaper.js";
 import {
   listTerminalWorkerRecords,
@@ -268,6 +265,9 @@ export function createWorkerTerminalManager(
     };
 
     const session: TerminalSession = {
+      get createdAt() {
+        return record.state.createdAt;
+      },
       get id() {
         return record.info.id;
       },
@@ -373,6 +373,10 @@ export function createWorkerTerminalManager(
         for (const listener of Array.from(record.titleChangeListeners)) {
           listener(manualTitle);
         }
+        emitTerminalsChanged({
+          cwd: record.info.cwd,
+          terminals: listTerminalItemsForCwd(record.info.cwd),
+        });
       },
       getExitInfo(): TerminalExitInfo | null {
         return record.exitInfo;
@@ -1038,18 +1042,21 @@ export async function startWorkerTerminalManager(
       toReap.push(file.path);
       continue;
     }
-    const worker = classifyTerminalWorkerProcess(record, await inspector.inspect(record.pid));
-    if (worker.status === "owned") {
+    const worker = await identifyTerminalWorker(record);
+    if (worker.status === "owned" || worker.status === "unknown") {
+      if (worker.status === "unknown") {
+        // Its secret still proves it: only the worker that wrote the record can answer the
+        // hello below. An inconclusive probe does not authorize a signal.
+        logger.warn(
+          { recordPath: file.path, pid: record.pid, reason: worker.reason },
+          "Terminal worker socket probe inconclusive; attempting authentication",
+        );
+      }
       live.push({
         path: file.path,
         record,
         fit: classifyTerminalWorkerProtocol(record.protocolVersion),
       });
-    } else if (worker.status === "unknown") {
-      logger.warn(
-        { recordPath: file.path, pid: record.pid, reason: worker.reason },
-        "Cannot identify terminal worker; leaving its record",
-      );
     } else {
       // Its programs lost their PTY with the worker and cannot be adopted.
       toReap.push(file.path);
@@ -1142,10 +1149,7 @@ export async function startWorkerTerminalManager(
     const reconnect = () => {
       recovery ??= (async () => {
         while (!recoveryState.stopped) {
-          const ownership = classifyTerminalWorkerProcess(
-            record,
-            await inspector.inspect(record.pid),
-          );
+          const ownership = await identifyTerminalWorker(record);
           if (ownership.status === "gone" || ownership.status === "unrelated") {
             await reapTerminalWorkers({
               paseoHome: options.paseoHome,
@@ -1243,7 +1247,7 @@ export async function startWorkerTerminalManager(
   // Counted from the records rather than from what startup drove: a worker a cleanup could not
   // confirm gone keeps running, and a draining one exits on its own.
   const startCurrent = async (): Promise<TerminalWorkerPoolMember> => {
-    const running = await countRunningTerminalWorkers(options.paseoHome, inspector);
+    const running = await countRunningTerminalWorkers(options.paseoHome);
     if (running >= MAX_TERMINAL_WORKERS) {
       throw new NoTerminalWorkerAvailableError(
         `${running} terminal workers are already running in ${options.paseoHome}; new terminals can open once one of them exits`,
@@ -1269,8 +1273,17 @@ export async function startWorkerTerminalManager(
     try {
       current = await startCurrent();
     } catch (error) {
-      if (!(error instanceof NoTerminalWorkerAvailableError)) throw error;
-      logger.warn(error.message);
+      if (error instanceof NoTerminalWorkerAvailableError) {
+        logger.warn(error.message);
+      } else {
+        // The daemon starts without terminals rather than not at all. A worker that cannot start
+        // here is launched again by the first terminal creation, which reports the same error
+        // if it still cannot.
+        logger.error(
+          { err: error },
+          "Terminal worker did not start; terminals are unavailable until one starts",
+        );
+      }
     }
   }
 
@@ -1289,11 +1302,9 @@ export async function startWorkerTerminalManager(
 
 // Every worker that may still run in this home, one per record: a worker and its cleanup record
 // are listed as one. Unreadable records and workers that cannot be identified count; a worker
-// confirmed gone, or a pid reused by another process, does not.
-async function countRunningTerminalWorkers(
-  paseoHome: string,
-  inspector: TerminalWorkerProcessInspector,
-): Promise<number> {
+// confirmed gone, or a pid now running something else (another birth time, or nothing listening
+// on the worker's socket), does not.
+async function countRunningTerminalWorkers(paseoHome: string): Promise<number> {
   let running = 0;
   for (const file of await listTerminalWorkerRecords(paseoHome)) {
     if ("error" in file) {
@@ -1302,7 +1313,7 @@ async function countRunningTerminalWorkers(
     }
     const { record } = file;
     if (!writtenDuringThisBoot({ startedAt: record.createdAt, bootId: record.bootId })) continue;
-    const worker = classifyTerminalWorkerProcess(record, await inspector.inspect(record.pid));
+    const worker = await identifyTerminalWorker(record);
     if (worker.status === "owned" || worker.status === "unknown") running += 1;
   }
   return running;
diff --git a/packages/server/src/utils/checkout-git.commits.test.ts b/packages/server/src/utils/checkout-git.commits.test.ts
index ee29579f55..a19b81ded8 100644
--- a/packages/server/src/utils/checkout-git.commits.test.ts
+++ b/packages/server/src/utils/checkout-git.commits.test.ts
@@ -3,7 +3,12 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "fs"
 import { tmpdir } from "os";
 import { join } from "path";
 import { afterEach, describe, expect, it } from "vitest";
-import { listCheckoutCommits } from "./checkout-git.js";
+import {
+  getCommitFileDiff,
+  listCheckoutCommits,
+  getCheckoutStatus,
+  getCheckoutDiff,
+} from "./checkout-git.js";
 import { writePaseoWorktreeMetadata } from "./worktree-metadata.js";
 
 const tempDirs: string[] = [];
@@ -332,6 +337,50 @@ describe("listCheckoutCommits", () => {
     ]);
   });
 
+  it.each([
+    {
+      label: "without edits",
+      content: "one\ntwo\nthree\nfour\nfive\n",
+      additions: 0,
+      deletions: 0,
+    },
+    { label: "with edits", content: "one\nTWO\nthree\nfour\nfive\n", additions: 1, deletions: 1 },
+  ])(
+    "opens a file moved up out of a directory $label",
+    async ({ content, additions, deletions }) => {
+      const { repoDir } = initRepoOnMain();
+      git(["checkout", "-b", "feature"], repoDir);
+      mkdirSync(join(repoDir, "src", "nested"), { recursive: true });
+      commitFile(repoDir, "src/nested/a.txt", "one\ntwo\nthree\nfour\nfive\n", "Add nested file");
+      git(["mv", "src/nested/a.txt", "src/a.txt"], repoDir);
+      writeFileSync(join(repoDir, "src/a.txt"), content);
+      git(["add", "src/a.txt"], repoDir);
+      commit(repoDir, "Move file up");
+
+      const { commits } = await listCheckoutCommits({ cwd: repoDir });
+
+      const movedCommit = commits[0]!;
+      const movedFile = movedCommit.files[0]!;
+      expect(movedCommit.files).toEqual([
+        {
+          path: "src/a.txt",
+          additions,
+          deletions,
+          status: "renamed",
+        },
+      ]);
+      expect(
+        await getCommitFileDiff({ cwd: repoDir, sha: movedCommit.sha, path: movedFile.path }),
+      ).toMatchObject({
+        path: "src/a.txt",
+        isNew: false,
+        isDeleted: false,
+        additions,
+        deletions,
+      });
+    },
+  );
+
   it("derives status for modified and deleted files", async () => {
     const { repoDir } = initRepoOnMain();
     git(["checkout", "-b", "feature"], repoDir);
@@ -349,3 +398,45 @@ describe("listCheckoutCommits", () => {
     ]);
   });
 });
+
+it("compares tag-based worktrees in status, history and legacy diff modes", async () => {
+  const { repoDir: mainRepoDir, tempDir } = initRepoOnMain();
+  const worktreesRoot = join(tempDir, "worktrees");
+  const repoDir = join(worktreesRoot, "repo-hash", "tag-feature");
+  mkdirSync(join(worktreesRoot, "repo-hash"), { recursive: true });
+  const context = { worktreesRoot };
+  git(["tag", "v1"], mainRepoDir);
+  git(["worktree", "add", "-b", "tag-feature", repoDir, "v1"], mainRepoDir);
+  await writePaseoWorktreeMetadata(repoDir, { baseRefName: "refs/tags/v1" });
+  commitFile(repoDir, "tag.txt", "committed\n", "tag feature");
+  writeFileSync(join(repoDir, "tag.txt"), "edited\n");
+  const status = await getCheckoutStatus(repoDir, context);
+  expect(status).toMatchObject({
+    isGit: true,
+    comparisonBaseRef: "refs/tags/v1",
+    aheadBehind: { ahead: 1, behind: 0 },
+  });
+  const history = await listCheckoutCommits({ cwd: repoDir, context });
+  expect(history.baseRef).toBe("refs/tags/v1");
+  expect(history.commits[0].subject).toBe("tag feature");
+  const committed = await getCheckoutDiff(repoDir, { mode: "base", baseRef: "refs/tags/v1" });
+  expect(committed.diff).toContain("+committed");
+  const all = await getCheckoutDiff(repoDir, { mode: "all", baseRef: "refs/tags/v1" });
+  expect(all.diff).toContain("+edited");
+});
+
+it("announces a usable comparison base while checked out on the base branch", async () => {
+  const cwd = makeTempDir();
+  git(["init", "-b", "main"], cwd);
+  git(["config", "user.name", "Test"], cwd);
+  git(["config", "user.email", "test@example.com"], cwd);
+  writeFileSync(join(cwd, "a.txt"), "before\n");
+  git(["add", "."], cwd);
+  commit(cwd, "base");
+  writeFileSync(join(cwd, "a.txt"), "after\n");
+  const status = await getCheckoutStatus(cwd);
+  expect(status).toMatchObject({ isGit: true, comparisonBaseRef: "refs/heads/main" });
+  if (!status.isGit || !status.comparisonBaseRef) throw new Error("Missing comparison base");
+  const all = await getCheckoutDiff(cwd, { mode: "all", baseRef: status.comparisonBaseRef });
+  expect(all.diff).toContain("+after");
+});
diff --git a/packages/server/src/utils/checkout-git.test.ts b/packages/server/src/utils/checkout-git.test.ts
index bd52b0e49f..075f7ebda1 100644
--- a/packages/server/src/utils/checkout-git.test.ts
+++ b/packages/server/src/utils/checkout-git.test.ts
@@ -32,6 +32,7 @@ import {
   getCheckoutStatus,
   checkoutResolvedBranch,
   listBranchSuggestions,
+  setCheckoutBaseBranch,
   mergeToBase,
   mergeFromBase,
   MergeConflictError,
@@ -263,6 +264,56 @@ describe("checkout git utilities", () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
+  it("rejects changing the base of a local checkout without creating metadata", async () => {
+    await expect(setCheckoutBaseBranch({ cwd: repoDir, baseRef: "main" })).rejects.toThrow();
+    expect(existsSync(await getPaseoWorktreeMetadataPath(repoDir))).toBe(false);
+  });
+
+  it("changing a managed worktree base preserves its runtime and PR identity", async () => {
+    const worktree = await createLegacyWorktreeForTest({
+      cwd: repoDir,
+      branchName: "feature/base",
+      baseBranch: "main",
+      worktreeSlug: "base",
+      paseoHome,
+      runSetup: false,
+    });
+    const original = await readPaseoWorktreeMetadata(worktree.worktreePath);
+    execFileSync("git", ["branch", "release"], { cwd: repoDir });
+    await setCheckoutBaseBranch({
+      cwd: worktree.worktreePath,
+      baseRef: "release",
+      context: { paseoHome },
+    });
+    expect(await readPaseoWorktreeMetadata(worktree.worktreePath)).toEqual({
+      ...original,
+      baseRefName: "release",
+      baseRef: "refs/heads/release",
+    });
+    expect(await getCheckoutSnapshotFacts(worktree.worktreePath, { paseoHome })).toMatchObject({
+      storedBaseRef: "refs/heads/release",
+    });
+  });
+
+  it("lists exact local and all remote refs separately for the base picker", async () => {
+    execFileSync("git", ["branch", "release"], { cwd: repoDir });
+    execFileSync("git", ["update-ref", "refs/remotes/origin/release", "HEAD"], { cwd: repoDir });
+    execFileSync("git", ["update-ref", "refs/remotes/upstream/release", "HEAD"], { cwd: repoDir });
+    const suggestions = await listBranchSuggestions(repoDir, {
+      refMode: "exact",
+      query: "release",
+    });
+    expect(suggestions.map((entry) => entry.name).sort()).toEqual([
+      "refs/heads/release",
+      "refs/remotes/origin/release",
+      "refs/remotes/upstream/release",
+    ]);
+    expect(suggestions.find((entry) => entry.name === "refs/heads/release")).toMatchObject({
+      hasLocal: true,
+      hasRemote: false,
+    });
+  });
+
   it("throws NotGitRepoError for non-git directories", async () => {
     const nonGitDir = join(tempDir, "not-git");
     mkdirSync(nonGitDir, { recursive: true });
@@ -1920,6 +1971,13 @@ const x = 1;
     expect(status.currentBranch).toBe("feature/plain");
   });
 
+  it("rejects merging a branch into its own same-named remote base", async () => {
+    execFileSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: repoDir });
+    await expect(mergeToBase(repoDir, { baseRef: "refs/remotes/origin/main" })).rejects.toThrow(
+      "Cannot merge a branch into itself",
+    );
+  });
+
   it("merges the current branch into base from a worktree checkout", async () => {
     const worktree = await createLegacyWorktreeForTest({
       branchName: "main",
diff --git a/packages/server/src/utils/checkout-git.ts b/packages/server/src/utils/checkout-git.ts
index 358bd6eb69..2bb295b371 100644
--- a/packages/server/src/utils/checkout-git.ts
+++ b/packages/server/src/utils/checkout-git.ts
@@ -40,7 +40,7 @@ import {
 } from "../services/forge-cli-command.js";
 import { parseGitRevParsePath, resolveGitRevParsePath } from "./git-rev-parse-path.js";
 import { runGitCommand, type RunGitCommand } from "./run-git-command.js";
-import { readGitFileContents } from "./git-file-contents.js";
+import { readGitFileContents, readGitFileContentAtRef } from "./git-file-contents.js";
 import { unquoteGitPath } from "./git-quoted-path.js";
 import { isPaseoOwnedWorktreeCwd, resolvePaseoWorktreesBaseRoot } from "./worktree.js";
 import {
@@ -51,6 +51,7 @@ import {
   type PaseoWorktreeMetadata,
   readPaseoWorktreeMetadata,
   rebindPaseoWorktreeChangeRequestHint,
+  setPaseoWorktreeBaseRef,
 } from "./worktree-metadata.js";
 const READ_ONLY_GIT_ENV = {
   GIT_OPTIONAL_LOCKS: "0",
@@ -323,15 +324,30 @@ function sortBranchSuggestions(
 
 export async function listBranchSuggestions(
   cwd: string,
-  options?: { query?: string; limit?: number },
+  options: { query?: string; limit?: number; refMode?: "exact" } = {},
 ): Promise<BranchSuggestion[]> {
   await requireGitRepo(cwd);
 
-  const requestedLimit = options?.limit ?? 50;
+  const requestedLimit = options.limit ?? 50;
   const limit = Math.max(1, Math.min(200, requestedLimit));
-  const rawQuery = options?.query?.trim().toLowerCase() ?? "";
+  const rawQuery = options.query?.trim().toLowerCase() ?? "";
   const query = normalizeBranchSuggestionName(rawQuery) ?? rawQuery;
 
+  if (options.refMode === "exact") {
+    const refs = await listGitRefs(cwd, "refs");
+    const branches = refs.filter((ref) => {
+      const isBranch = ref.name.startsWith("refs/heads/") || ref.name.startsWith("refs/remotes/");
+      return isBranch && !ref.name.endsWith("/HEAD") && ref.name.toLowerCase().includes(rawQuery);
+    });
+    branches.sort((a, b) => b.committerDate - a.committerDate || a.name.localeCompare(b.name));
+    return branches.slice(0, limit).map((ref) => ({
+      name: ref.name,
+      committerDate: ref.committerDate,
+      hasLocal: ref.name.startsWith("refs/heads/"),
+      hasRemote: ref.name.startsWith("refs/remotes/"),
+    }));
+  }
+
   const [localRefs, remoteRefs] = await Promise.all([
     listGitRefs(cwd, "refs/heads"),
     listGitRefs(cwd, "refs/remotes/origin"),
@@ -597,22 +613,6 @@ async function listCheckoutFileChanges(
   return Array.from(byPath.values());
 }
 
-async function readGitFileContentAtRef(
-  cwd: string,
-  ref: string,
-  path: string,
-): Promise<string | null> {
-  try {
-    const { stdout } = await runGitCommand(["show", `${ref}:${path}`], {
-      cwd,
-      envOverlay: READ_ONLY_GIT_ENV,
-    });
-    return stdout;
-  } catch {
-    return null;
-  }
-}
-
 async function tryResolveMergeBase(cwd: string, baseRef: string): Promise<string | null> {
   try {
     const { stdout } = await runGitCommand(["merge-base", baseRef, "HEAD"], {
@@ -636,6 +636,11 @@ function normalizeNumstatPath(pathField: string): string {
   const braceRenameMatch = pathField.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
   if (braceRenameMatch) {
     const [, prefix, , renamed, suffix] = braceRenameMatch;
+    // Moving out of a directory prints `src/{nested => }/a.ts`, so an empty
+    // destination leaves a separator from each side behind.
+    if (!renamed) {
+      return unquoteGitPath(`${prefix}${suffix.slice(1)}`);
+    }
     return unquoteGitPath(`${prefix}${renamed}${suffix}`);
   }
 
@@ -648,7 +653,12 @@ function normalizeNumstatPath(pathField: string): string {
 }
 
 // Parsed patches need a stable wire format regardless of terminal presentation settings.
-const GIT_PATCH_FORMAT_ARGS = ["--no-ext-diff", "--no-color", "--src-prefix=a/", "--dst-prefix=b/"];
+export const GIT_PATCH_FORMAT_ARGS = [
+  "--no-ext-diff",
+  "--no-color",
+  "--src-prefix=a/",
+  "--dst-prefix=b/",
+] as const;
 
 function buildGitDiffArgs(args: { ignoreWhitespace?: boolean; extra: string[] }): string[] {
   return [
@@ -884,6 +894,8 @@ export interface CheckoutStatusGitNonPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string | null;
+  baseRefExact?: string | null;
+  comparisonBaseRef?: string | null;
   aheadBehind: AheadBehind | null;
   // Remote-tracking ref for currentBranch, e.g. "refs/remotes/origin/main". Null when the
   // branch has no upstream or git could not resolve it. aheadOfOrigin/behindOfOrigin are
@@ -903,6 +915,8 @@ export interface CheckoutStatusGitPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string;
+  baseRefExact?: string | null;
+  comparisonBaseRef?: string | null;
   aheadBehind: AheadBehind | null;
   upstreamRef: string | null;
   aheadOfOrigin: number | null;
@@ -1303,12 +1317,36 @@ async function getStoredBaseRefForCwd(
   if (context?.facts?.isGit) {
     return context.facts.storedBaseRef;
   }
-  const paseoWorktree = await getPaseoWorktreeForCwd(cwd, { context });
-  if (!paseoWorktree.isPaseoOwnedWorktree) {
-    return null;
-  }
+  const ownership = await getPaseoWorktreeForCwd(cwd, { context });
+  return ownership.isPaseoOwnedWorktree ? readPaseoWorktreeBaseRef(ownership.worktreeRoot) : null;
+}
 
-  return readPaseoWorktreeBaseRef(paseoWorktree.worktreeRoot);
+export async function setCheckoutBaseBranch(input: {
+  cwd: string;
+  baseRef: string;
+  context?: CheckoutContext;
+}): Promise<string> {
+  await requireGitRepo(input.cwd);
+  const ownership = await getPaseoWorktreeForCwd(input.cwd, { context: input.context });
+  if (!ownership.isPaseoOwnedWorktree) throw new Error("Workspace is not a Paseo worktree");
+  const requested = input.baseRef.trim();
+  const qualified = requested.startsWith("refs/");
+  const candidates = qualified
+    ? [requested]
+    : [`refs/heads/${requested}`, `refs/remotes/${requested}`, `refs/remotes/origin/${requested}`];
+  for (const candidate of candidates) {
+    if (!isQualifiedBranchRef(candidate) || candidate.endsWith("/HEAD")) continue;
+    const valid = await runGitCommand(["check-ref-format", candidate], {
+      cwd: input.cwd,
+      acceptExitCodes: [0, 1],
+    });
+    if (valid.exitCode !== 0 || !(await doesGitRefExist(input.cwd, candidate))) continue;
+    const worktreeRoot = await getWorktreeRoot(input.cwd);
+    if (!worktreeRoot) throw new NotGitRepoError(input.cwd);
+    await setPaseoWorktreeBaseRef({ worktreeRoot, baseRef: candidate });
+    return candidate;
+  }
+  throw new Error(`Base branch not found: ${requested}`);
 }
 
 async function getResolvedBaseRefForCwd(
@@ -1701,6 +1739,24 @@ function isQualifiedBranchRef(ref: string): boolean {
   return ref.startsWith("refs/heads/") || ref.startsWith("refs/remotes/");
 }
 
+async function resolveCommitComparisonRef(
+  cwd: string,
+  name: string,
+  context?: CheckoutContext,
+): Promise<string> {
+  await getRunGitCommand(context)(["rev-parse", "--verify", `${name}^{commit}`], {
+    cwd,
+    envOverlay: READ_ONLY_GIT_ENV,
+    logger: context?.logger,
+  });
+  const result = await getRunGitCommand(context)(["rev-parse", "--symbolic-full-name", name], {
+    cwd,
+    envOverlay: READ_ONLY_GIT_ENV,
+    logger: context?.logger,
+  });
+  return result.stdout.trim() || name;
+}
+
 async function resolveBestComparisonBaseRef(
   cwd: string,
   baseRef: string,
@@ -1727,11 +1783,17 @@ async function resolveBestComparisonBaseRef(
     return normalized.localName;
   }
 
-  const refName =
-    baseRef.startsWith("origin/") || baseRef.startsWith("refs/remotes/origin/")
-      ? normalized.originRef
-      : normalized.localName;
-  throw new Error(`Base branch not found locally or on origin: ${refName}`);
+  return resolveCommitComparisonRef(cwd, baseRef, context);
+}
+
+async function resolveQualifiedComparisonBaseRef(
+  cwd: string,
+  baseRef: string,
+  context: CheckoutContext,
+): Promise<string> {
+  const comparison = context.facts?.isGit ? context.facts.comparisonBaseRef : null;
+  const ref = comparison ?? (await resolveBestComparisonBaseRef(cwd, baseRef, context));
+  return resolveCommitComparisonRef(cwd, ref, context);
 }
 
 async function resolveMostAheadBaseRef(cwd: string, baseRef: string): Promise<string> {
@@ -1754,7 +1816,7 @@ async function resolveMostAheadBaseRef(cwd: string, baseRef: string): Promise<st
     return `origin/${normalizedBaseRef}`;
   }
   if (!hasLocal && !hasOrigin) {
-    throw new Error(`Base branch not found locally or on origin: ${normalizedBaseRef}`);
+    return resolveCommitComparisonRef(cwd, baseRef);
   }
 
   const { stdout } = await runGitCommand(
@@ -1781,7 +1843,11 @@ async function getAheadBehind(
   context?: CheckoutContext,
 ): Promise<AheadBehind | null> {
   const normalizedBaseRef = branchNameFromRef(baseRef);
-  if (!normalizedBaseRef || !currentBranch || normalizedBaseRef === currentBranch) {
+  if (
+    !normalizedBaseRef ||
+    !currentBranch ||
+    (!isQualifiedBranchRef(baseRef) && normalizedBaseRef === currentBranch)
+  ) {
     return null;
   }
   const comparisonBaseRef =
@@ -2123,7 +2189,8 @@ export async function getCheckoutSnapshotFacts(
   if (
     resolvedBaseRef &&
     inspected.currentBranch &&
-    branchNameFromRef(resolvedBaseRef) !== inspected.currentBranch
+    (isQualifiedBranchRef(resolvedBaseRef) ||
+      branchNameFromRef(resolvedBaseRef) !== inspected.currentBranch)
   ) {
     comparisonBaseRef = await resolveBestComparisonBaseRef(cwd, resolvedBaseRef, context).catch(
       () => null,
@@ -2187,8 +2254,8 @@ export async function getCheckoutSnapshotFacts(
   };
 }
 
-const PER_FILE_DIFF_MAX_BYTES = 1024 * 1024; // 1MB
-const TOTAL_DIFF_MAX_BYTES = 2 * 1024 * 1024; // 2MB
+export const PER_FILE_DIFF_MAX_BYTES = 1024 * 1024; // 1MB
+export const TOTAL_DIFF_MAX_BYTES = 2 * 1024 * 1024; // 2MB
 const CHECKOUT_DIFF_FRAME_HEADROOM_BYTES = 1024 * 1024;
 // Temporary until diffs load lazily per file. The Paseo relay's 32 MiB frame limit is
 // binding: string frames are encrypted and base64-encoded. Reserve 1 MiB plaintext for
@@ -2249,7 +2316,7 @@ async function isLikelyBinaryFile(absolutePath: string): Promise<boolean> {
   }
 }
 
-async function inspectUntrackedFile(
+export async function inspectUntrackedFile(
   cwd: string,
   relativePath: string,
 ): Promise<{ stat: FileStat; truncated: boolean }> {
@@ -2347,6 +2414,10 @@ export async function getCheckoutStatus(
   const baseRef = facts.resolvedBaseRef;
   const mainRepoRoot = facts.mainRepoRoot;
   const factsContext = { ...context, facts };
+  // Ref-derived counts skip the current base branch; the diff consumer still needs its ref.
+  const comparisonBaseRef = baseRef
+    ? await resolveQualifiedComparisonBaseRef(cwd, baseRef, factsContext).catch(() => null)
+    : null;
   const aheadBehind =
     baseRef && currentBranch
       ? await getAheadBehind(cwd, baseRef, currentBranch, factsContext)
@@ -2368,6 +2439,8 @@ export async function getCheckoutStatus(
       currentBranch,
       isDirty,
       baseRef: displayBaseRef ?? baseRef,
+      baseRefExact: baseRef,
+      comparisonBaseRef,
       aheadBehind,
       upstreamRef,
       aheadOfOrigin,
@@ -2386,6 +2459,8 @@ export async function getCheckoutStatus(
     currentBranch,
     isDirty,
     baseRef: displayBaseRef,
+    baseRefExact: baseRef,
+    comparisonBaseRef,
     aheadBehind,
     upstreamRef,
     aheadOfOrigin,
@@ -2600,7 +2675,10 @@ async function tryResolveCheckoutCommitsBaseRef(
     return null;
   }
   const normalizedBaseRef = branchNameFromRef(baseRef);
-  if (!normalizedBaseRef || normalizedBaseRef === currentBranch) {
+  if (
+    !normalizedBaseRef ||
+    (!isQualifiedBranchRef(baseRef) && normalizedBaseRef === currentBranch)
+  ) {
     return null;
   }
   try {
@@ -2747,6 +2825,7 @@ async function readCommitRenames(cwd: string, sha: string): Promise<ReadonlyMap<
  * binary-only (no textual hunks). Throws on git failure (e.g. an unknown sha),
  * which the caller maps to a typed checkout error.
  */
+// COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
 export async function getCommitFileDiff({
   cwd,
   sha,
@@ -3513,6 +3592,21 @@ async function resolveCheckoutDiffRefs(
   if (compare.mode === "uncommitted") {
     return { baseRef: "HEAD", includeUntracked: true };
   }
+  const bestBaseRef = await resolveCheckoutDiffBase(cwd, compare, context);
+  if (!bestBaseRef) return null;
+  return {
+    baseRef: (await tryResolveMergeBase(cwd, bestBaseRef)) ?? bestBaseRef,
+    targetRef: compare.mode === "base" ? "HEAD" : undefined,
+    includeUntracked: compare.mode === "all",
+  };
+}
+
+export async function resolveCheckoutDiffBase(
+  cwd: string,
+  compare: CheckoutDiffCompare,
+  context?: CheckoutContext,
+): Promise<string | null> {
+  if (compare.mode === "uncommitted") return "HEAD";
   const { storedBaseRef, resolvedBaseRef } = await resolveBaseRefForCwd(cwd, context);
   const baseRef = resolveOperationBaseRef({
     storedBaseRef,
@@ -3522,17 +3616,12 @@ async function resolveCheckoutDiffRefs(
   if (!baseRef) {
     return null;
   }
-  const bestBaseRef = await resolveBestComparisonBaseRef(cwd, baseRef);
-  return {
-    baseRef: (await tryResolveMergeBase(cwd, bestBaseRef)) ?? bestBaseRef,
-    targetRef: compare.mode === "base" ? "HEAD" : undefined,
-    includeUntracked: compare.mode === "all",
-  };
+  return resolveBestComparisonBaseRef(cwd, baseRef);
 }
 
 // Git's working-tree diff ignores files absent from the index, even when they
 // exist in the comparison tree. Restore those entries only in a private index.
-async function prepareAllChangesIndex(cwd: string, baseRef: string) {
+export async function prepareAllChangesIndex(cwd: string, baseRef: string) {
   const untracked = await runGitCommand(["ls-files", "-z", "--others", "--exclude-standard"], {
     cwd,
     envOverlay: READ_ONLY_GIT_ENV,
@@ -3555,21 +3644,41 @@ async function prepareAllChangesIndex(cwd: string, baseRef: string) {
     entries += result.stdout;
   }
   if (!entries) return null;
-  const directory = await mkdtemp(resolve(tmpdir(), "paseo-all-changes-"));
+  const snapshot = await snapshotComparisonIndex(cwd);
+  try {
+    await runGitCommand(["update-index", "-z", "--index-info"], {
+      cwd,
+      input: entries,
+      envOverlay: { ...READ_ONLY_GIT_ENV, GIT_INDEX_FILE: snapshot.indexFile },
+    });
+    return snapshot;
+  } catch (error) {
+    await snapshot.cleanup();
+    throw error;
+  }
+}
+
+// write-tree rewrites its index. A private snapshot prevents an index read from
+// invalidating the observation that requested it.
+export async function snapshotComparisonIndex(cwd: string) {
+  const directory = await mkdtemp(resolve(tmpdir(), "paseo-comparison-index-"));
   const indexFile = resolve(directory, "index");
   try {
     const index = await runGitCommand(["rev-parse", "--git-path", "index"], {
       cwd,
       envOverlay: READ_ONLY_GIT_ENV,
     });
-    const indexPath = resolveGitRevParsePath(cwd, index.stdout);
-    if (!indexPath) throw new Error("Git did not return an index path");
-    await copyFile(indexPath, indexFile);
-    await runGitCommand(["update-index", "-z", "--index-info"], {
-      cwd,
-      input: entries,
-      envOverlay: { ...READ_ONLY_GIT_ENV, GIT_INDEX_FILE: indexFile },
-    });
+    const source = resolveGitRevParsePath(cwd, index.stdout);
+    if (!source) throw new Error("Git did not return an index path");
+    try {
+      await copyFile(source, indexFile);
+    } catch (error) {
+      if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+      await runGitCommand(["read-tree", "--empty"], {
+        cwd,
+        envOverlay: { ...READ_ONLY_GIT_ENV, GIT_INDEX_FILE: indexFile },
+      });
+    }
     return { indexFile, cleanup: () => rm(directory, { recursive: true, force: true }) };
   } catch (error) {
     await rm(directory, { recursive: true, force: true });
@@ -3885,7 +3994,7 @@ export async function mergeToBase(
   const normalizedBaseRef = resolveMergeTargetBranch(baseRef);
   const currentWorktreeRoot = (await getWorktreeRoot(cwd, context)) ?? cwd;
   if (normalizedBaseRef === currentBranch) {
-    return currentWorktreeRoot;
+    throw new Error("Cannot merge a branch into itself");
   }
 
   const baseWorktree = await getWorktreePathForBranch(cwd, normalizedBaseRef);
@@ -4218,6 +4327,7 @@ export interface PullRequestStatus {
   state: string;
   baseRefName: string;
   headRefName: string;
+  headSha?: string;
   isMerged: boolean;
   isDraft?: boolean;
   mergeable?: PullRequestMergeable;
diff --git a/packages/server/src/utils/git-file-contents.ts b/packages/server/src/utils/git-file-contents.ts
index e42d3c6c83..04a314f17c 100644
--- a/packages/server/src/utils/git-file-contents.ts
+++ b/packages/server/src/utils/git-file-contents.ts
@@ -1,4 +1,4 @@
-import { runGitCommandBytes } from "./run-git-command.js";
+import { runGitCommandBytes, runGitCommand } from "./run-git-command.js";
 
 // Match the existing git-show ceiling. Oversized batches use bounded per-file reads.
 const MAX_CONTENT_BYTES = 20 * 1024 * 1024;
@@ -46,3 +46,17 @@ export async function readGitFileContents(
   if (offset !== result.stdout.length) throw new Error("Unexpected git object output");
   return contents;
 }
+
+export async function readGitFileContentAtRef(
+  cwd: string,
+  ref: string,
+  path: string,
+): Promise<string | null> {
+  const result = await runGitCommand(["show", `${ref}:${path}`], {
+    cwd,
+    envOverlay: { GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" },
+    acceptExitCodes: [0, 128],
+  });
+  if (result.exitCode !== 0 || result.truncated) return null;
+  return result.stdout;
+}
diff --git a/packages/server/src/utils/git-process-scheduler.test.ts b/packages/server/src/utils/git-process-scheduler.test.ts
index c8a72cd199..74ea99f273 100644
--- a/packages/server/src/utils/git-process-scheduler.test.ts
+++ b/packages/server/src/utils/git-process-scheduler.test.ts
@@ -68,6 +68,64 @@ describe("GitProcessScheduler", () => {
     expect(started).toEqual([0, 3, 2]);
   });
 
+  test("admits normal work before a queued background burst", async () => {
+    const scheduler = new GitProcessScheduler({
+      maxProcessesPerSecond: 100,
+      maxProcessConcurrency: 1,
+    });
+    const releases: Array<() => void> = [];
+    const started: number[] = [];
+
+    const activeBackground = scheduler.run(createConcurrencyTask(0, started, releases), {
+      priority: "background",
+    });
+    await vi.waitFor(() => expect(started).toEqual([0]));
+    const queuedBackground = [2, 3, 4].map((index) =>
+      scheduler.run(createConcurrencyTask(index, started, releases), { priority: "background" }),
+    );
+    const normalWork = scheduler.run(createConcurrencyTask(5, started, releases));
+    const highWork = scheduler.run(createConcurrencyTask(6, started, releases), {
+      priority: "high",
+    });
+
+    releases.shift()?.();
+    await Promise.all([activeBackground, ...queuedBackground, normalWork, highWork]);
+
+    expect(started).toEqual([0, 6, 5, 2, 3, 4]);
+  });
+
+  test("starts normal work at the next start slot when background work saturates the rate", async () => {
+    vi.useFakeTimers();
+    const scheduler = new GitProcessScheduler({
+      maxProcessesPerSecond: 2,
+      maxProcessConcurrency: 8,
+    });
+    const started: string[] = [];
+    const task = (name: string) => () => {
+      started.push(name);
+      const completed = Promise.resolve();
+      return { result: completed, exited: completed };
+    };
+    const background = Array.from({ length: 8 }, (_, index) =>
+      scheduler.run(task(`background-${index}`), { priority: "background" }),
+    );
+    // Admission yields a real event-loop turn per process; let every
+    // background job reach the start-rate limiter.
+    for (let turn = 0; turn < 10; turn += 1) {
+      await new Promise<void>((resolve) => scheduleImmediate(resolve));
+    }
+    expect(started).toEqual(["background-0", "background-1"]);
+
+    const normal = scheduler.run(task("normal"));
+    while (started.length < 3) {
+      await vi.advanceTimersToNextTimerAsync();
+    }
+
+    expect(started[2]).toBe("normal");
+    await vi.runAllTimersAsync();
+    await Promise.all([...background, normal]);
+  });
+
   test("yields to daemon liveness work between process starts", async () => {
     const scheduler = new GitProcessScheduler({
       maxProcessesPerSecond: 100,
diff --git a/packages/server/src/utils/git-process-scheduler.ts b/packages/server/src/utils/git-process-scheduler.ts
index cd5575d79e..a1897b22af 100644
--- a/packages/server/src/utils/git-process-scheduler.ts
+++ b/packages/server/src/utils/git-process-scheduler.ts
@@ -16,7 +16,10 @@ export interface ScheduledGitProcess<T> {
   exited: Promise<void>;
 }
 
-export type GitProcessPriority = "normal" | "high";
+// Lanes drain in this order. "background" is for daemon-initiated fan-out
+// (reconciliation, observation-driven refreshes, fetches) so it never sits in
+// front of work a user is waiting for.
+export type GitProcessPriority = "high" | "normal" | "background";
 
 function parsePositiveInteger(value: string | undefined): number | undefined {
   if (value === undefined) {
@@ -44,11 +47,19 @@ export function resolveGitProcessPolicy(input: {
   };
 }
 
+// Admission reserves a process slot and a start-rate token; the job runs only
+// once its token fires. The job is chosen when the token fires, not when the
+// slot is reserved, so work submitted while background jobs hold every reserved
+// slot still takes the next start.
 export class GitProcessScheduler {
   private readonly startThrottled;
-  private readonly highPriorityQueue: Array<() => void> = [];
-  private readonly normalPriorityQueue: Array<() => void> = [];
+  private readonly queues: Record<GitProcessPriority, Array<() => Promise<void>>> = {
+    high: [],
+    normal: [],
+    background: [],
+  };
   private admitted = 0;
+  private reservedStarts = 0;
   private running = 0;
   private waiting = 0;
   private drainScheduled = false;
@@ -59,7 +70,7 @@ export class GitProcessScheduler {
       interval: 1_000,
       strict: true,
     });
-    this.startThrottled = throttle((start: () => Promise<void>) => start());
+    this.startThrottled = throttle(() => this.startNext());
   }
 
   get activeCount(): number {
@@ -76,17 +87,7 @@ export class GitProcessScheduler {
   ): Promise<T> {
     this.waiting += 1;
     return new Promise<T>((resolve, reject) => {
-      const admit = () => {
-        void this.startThrottled(() => this.execute(start, resolve, reject)).catch((error) => {
-          this.waiting = Math.max(0, this.waiting - 1);
-          this.admitted = Math.max(0, this.admitted - 1);
-          reject(error);
-          this.scheduleDrain();
-        });
-      };
-      const queue =
-        options?.priority === "high" ? this.highPriorityQueue : this.normalPriorityQueue;
-      queue.push(admit);
+      this.queues[options?.priority ?? "normal"].push(() => this.execute(start, resolve, reject));
       if (this.admitted === 0 && !this.drainScheduled) {
         this.drainOne();
       } else {
@@ -95,11 +96,12 @@ export class GitProcessScheduler {
     });
   }
 
+  private canReserveStart(): boolean {
+    return this.admitted < this.policy.maxProcessConcurrency && this.waiting > this.reservedStarts;
+  }
+
   private scheduleDrain(): void {
-    if (this.drainScheduled || this.admitted >= this.policy.maxProcessConcurrency) {
-      return;
-    }
-    if (this.highPriorityQueue.length === 0 && this.normalPriorityQueue.length === 0) {
+    if (this.drainScheduled || !this.canReserveStart()) {
       return;
     }
     this.drainScheduled = true;
@@ -108,20 +110,28 @@ export class GitProcessScheduler {
 
   private drainOne(): void {
     this.drainScheduled = false;
-    if (this.admitted >= this.policy.maxProcessConcurrency) {
-      return;
-    }
-    const admit = this.highPriorityQueue.shift() ?? this.normalPriorityQueue.shift();
-    if (!admit) {
+    if (!this.canReserveStart()) {
       return;
     }
     this.admitted += 1;
-    admit();
+    this.reservedStarts += 1;
+    void this.startThrottled();
     // Spawning can be synchronous and expensive on a throttled host. Let timers,
     // sockets, and child exits run before admitting another Git process.
     this.scheduleDrain();
   }
 
+  private startNext(): Promise<void> {
+    this.reservedStarts -= 1;
+    // Every reservation is backed by a queued job: jobs leave the queues only here.
+    const next =
+      this.queues.high.shift() ?? this.queues.normal.shift() ?? this.queues.background.shift();
+    if (!next) {
+      throw new Error("Git process start fired without a queued process");
+    }
+    return next();
+  }
+
   private async execute<T>(
     start: () => ScheduledGitProcess<T>,
     resolve: (value: T | PromiseLike<T>) => void,
diff --git a/packages/server/src/utils/run-git-command.ts b/packages/server/src/utils/run-git-command.ts
index 3a3cbf5b4c..e1f6fc718b 100644
--- a/packages/server/src/utils/run-git-command.ts
+++ b/packages/server/src/utils/run-git-command.ts
@@ -20,7 +20,7 @@ import {
 } from "./git-process-scheduler.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_MAX_OUTPUT_BYTES = 20 * 1024 * 1024; // 20MB
+export const DEFAULT_MAX_OUTPUT_BYTES = 20 * 1024 * 1024; // 20MB
 const DEFAULT_STDERR_LIMIT = 2048;
 
 let gitProcessScheduler = new GitProcessScheduler(resolveGitProcessPolicy({ env: process.env }));
@@ -67,8 +67,17 @@ export type RunGitCommand = (
   options: GitCommandOptions,
 ) => Promise<GitCommandResult>;
 
-export function createRunGitCommand(provenance: string): RunGitCommand {
-  return (args, options) => runGitCommandWithProvenance(args, options, provenance);
+export interface GitCommandRunnerOptions {
+  /** Overrides the ambient `runWithGitCommandPriority` lane for every command this runner starts. */
+  priority?: GitProcessPriority;
+}
+
+export function createRunGitCommand(
+  provenance: string,
+  runnerOptions: GitCommandRunnerOptions = {},
+): RunGitCommand {
+  return (args, options) =>
+    executeGitCommand(args, options, decodeUtf8, { provenance, priority: runnerOptions.priority });
 }
 
 export interface GitCommandMetric {
@@ -97,6 +106,7 @@ export interface GitCommandMetricsSnapshot {
 export interface GitCommandSubmissionMetric {
   args: string[];
   cwd: string;
+  priority: GitProcessPriority;
 }
 
 interface GitCommandMetricsState {
@@ -188,8 +198,8 @@ function snapshotGitCommandMetricsState(state: GitCommandMetricsState): GitComma
   return {
     commands: [...state.commands],
     submissions: state.submissions.map((submission) => ({
+      ...submission,
       args: [...submission.args],
-      cwd: submission.cwd,
     })),
     submitted: state.submitted,
     started: state.started,
@@ -209,12 +219,16 @@ export function snapshotGitCommandRuntimeMetrics(): GitCommandRuntimeMetricsSnap
   });
 }
 
-function submitGitCommandMetric(args: string[], cwd: string): GitCommandMetricsState | null {
+function submitGitCommandMetric(
+  args: string[],
+  cwd: string,
+  priority: GitProcessPriority,
+): GitCommandMetricsState | null {
   const state = gitCommandMetricsState;
   if (!state) {
     return null;
   }
-  state.submissions.push({ args: [...args], cwd });
+  state.submissions.push({ args: [...args], cwd, priority });
   state.submitted += 1;
   state.lastSubmittedAtMs = Date.now();
   return state;
@@ -258,12 +272,13 @@ function getEnvOverlayKeys(envOverlay: ProcessEnvRecord | undefined): string[] {
   return Object.keys(envOverlay ?? {}).sort();
 }
 
-function runGitCommandWithProvenance(
-  args: string[],
-  options: GitCommandOptions,
-  provenance?: string,
-): Promise<GitCommandResult> {
-  return executeGitCommand(args, options, (output) => output.toString("utf8"), provenance);
+function decodeUtf8(output: Buffer): string {
+  return output.toString("utf8");
+}
+
+interface GitCommandSubmission {
+  provenance?: string;
+  priority?: GitProcessPriority;
 }
 
 /** Binary stdout preserves cat-file byte framing before text decoding. */
@@ -271,21 +286,22 @@ export function runGitCommandBytes(
   args: string[],
   options: GitCommandOptions,
 ): Promise<GitCommandResult<Buffer>> {
-  return executeGitCommand(args, options, (output) => output);
+  return executeGitCommand(args, options, (output) => output, {});
 }
 
 function executeGitCommand<Output>(
   args: string[],
   options: GitCommandOptions,
   decode: (output: Buffer) => Output,
-  provenance?: string,
+  submission: GitCommandSubmission,
 ): Promise<GitCommandResult<Output>> {
-  const metricsState = submitGitCommandMetric(args, options.cwd);
+  const priority = submission.priority ?? gitCommandPriority.getStore() ?? "normal";
+  const metricsState = submitGitCommandMetric(args, options.cwd, priority);
   const commandTrace = submitGitCommandTrace(args, options.cwd, {
     active: gitProcessScheduler.activeCount,
     pending: gitProcessScheduler.pendingCount,
   });
-  const runtimeMetric = gitRuntimeMetrics.submit(getGitOperation(args), provenance);
+  const runtimeMetric = gitRuntimeMetrics.submit(getGitOperation(args), submission.provenance);
   const startCommand = () => {
     let releaseProcessSlot!: () => void;
     const exited = new Promise<void>((resolve) => {
@@ -558,9 +574,7 @@ function executeGitCommand<Output>(
     });
     return { result: resultPromise, exited };
   };
-  const promise = gitProcessScheduler.run(startCommand, {
-    priority: gitCommandPriority.getStore() ?? "normal",
-  });
+  const promise = gitProcessScheduler.run(startCommand, { priority });
   gitRuntimeMetrics.observeLimiter(
     gitProcessScheduler.activeCount,
     gitProcessScheduler.pendingCount,
@@ -568,7 +582,8 @@ function executeGitCommand<Output>(
   return promise;
 }
 
-export const runGitCommand: RunGitCommand = runGitCommandWithProvenance;
+export const runGitCommand: RunGitCommand = (args, options) =>
+  executeGitCommand(args, options, decodeUtf8, {});
 
 function formatGitCommand(args: string[]): string {
   return ["git", ...args].join(" ");
diff --git a/packages/server/src/utils/worktree-metadata.ts b/packages/server/src/utils/worktree-metadata.ts
index fcb0454672..fc4488d742 100644
--- a/packages/server/src/utils/worktree-metadata.ts
+++ b/packages/server/src/utils/worktree-metadata.ts
@@ -14,7 +14,7 @@ const ChangeRequestLookupTargetSchema = z.object({
   localBranchName: z.string().min(1).optional(),
 });
 
-// baseRefName is the display name; baseRef is the exact ref the worktree was cut from
+// baseRefName is the display name; baseRef is the checkout's current exact base
 // ("refs/remotes/upstream/main"). baseRef is optional because worktrees written before it
 // existed only have the name — there are no migrations, so readers fall back.
 const PaseoWorktreeMetadataV1Schema = z.object({
@@ -249,6 +249,21 @@ export async function writePaseoWorktreeMetadata(
   });
 }
 
+export async function setPaseoWorktreeBaseRef(input: {
+  worktreeRoot: string;
+  baseRef: string;
+}): Promise<void> {
+  return mutateMetadata(input.worktreeRoot, async (root) => {
+    const current = await readMetadataFile(root);
+    if (!current) throw new Error("Cannot change base: missing worktree metadata");
+    await writePaseoWorktreeMetadataFile(root, {
+      ...current,
+      baseRefName: branchNameFromRef(input.baseRef),
+      baseRef: input.baseRef,
+    });
+  });
+}
+
 export async function writePaseoWorktreeRuntimeMetadata(
   worktreeRoot: string,
   options: { worktreePort: number },
diff --git a/packages/website/e2e/agent-icons.spec.ts b/packages/website/e2e/agent-icons.spec.ts
index 4bc828475e..27418a7c48 100644
--- a/packages/website/e2e/agent-icons.spec.ts
+++ b/packages/website/e2e/agent-icons.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test, type Page } from "playwright/test";
+import { expect, test, type Page } from "./fixtures";
 
 test("keeps unrelated agent artwork unchanged while adding the Hermes mark", async ({ page }) => {
   await openSupportedAgents(page);
diff --git a/packages/website/e2e/changelog.spec.ts b/packages/website/e2e/changelog.spec.ts
new file mode 100644
index 0000000000..c95b389544
--- /dev/null
+++ b/packages/website/e2e/changelog.spec.ts
@@ -0,0 +1,77 @@
+import { expect, test, type Locator, type Page } from "./fixtures";
+
+// The page renders the repository's CHANGELOG.md, so releases are found by shape, never by version:
+// a release with highlights has the toggle, a release without them does not.
+function releases(page: Page): Locator {
+  return page.getByRole("region");
+}
+
+// The router resets the scroll position when the page hydrates. A click sent before that is aimed
+// at where the control was, so wait for the page to be interactive: the language button is enabled
+// once it has hydrated.
+async function openChangelog(page: Page): Promise<void> {
+  await page.goto("/changelog");
+  await expect(page.getByRole("button", { name: /^Language/ }).first()).toBeEnabled();
+}
+
+function releaseWithHighlights(page: Page): Locator {
+  return releases(page)
+    .filter({ has: page.getByText("Show all changes", { exact: true }) })
+    .first();
+}
+
+function releaseWithoutHighlights(page: Page): Locator {
+  return releases(page)
+    .filter({ hasNot: page.getByText(/^(Show|Hide) all changes$/) })
+    .first();
+}
+
+function sectionHeadings(release: Locator): Locator {
+  return release.getByRole("heading", { level: 4 });
+}
+
+async function showAllChanges(release: Locator): Promise<void> {
+  await release.getByText("Show all changes", { exact: true }).click();
+  await expect(release.getByText("Hide all changes", { exact: true })).toBeVisible();
+}
+
+async function hideAllChanges(release: Locator): Promise<void> {
+  await release.getByText("Hide all changes", { exact: true }).click();
+  await expect(release.getByText("Show all changes", { exact: true })).toBeVisible();
+}
+
+test("shows each release's highlights and opens its sections on request", async ({ page }) => {
+  await openChangelog(page);
+  const highlighted = releaseWithHighlights(page);
+  const plain = releaseWithoutHighlights(page);
+
+  await test.step("tucks away the sections of a release with highlights", async () => {
+    await expect(highlighted.getByRole("listitem").first()).toBeVisible();
+    await expect(sectionHeadings(highlighted)).toHaveCount(0);
+  });
+
+  await test.step("opens and closes them again", async () => {
+    await showAllChanges(highlighted);
+    await expect(sectionHeadings(highlighted).first()).toBeVisible();
+
+    await hideAllChanges(highlighted);
+    await expect(sectionHeadings(highlighted)).toHaveCount(0);
+  });
+
+  await test.step("shows a release without highlights whole", async () => {
+    await expect(sectionHeadings(plain).first()).toBeVisible();
+  });
+});
+
+test("opens a release from a deep link with its highlights in view", async ({ page }) => {
+  await openChangelog(page);
+  const anchor = await releaseWithHighlights(page)
+    .getByRole("link", { name: /^Link to Paseo / })
+    .getAttribute("href");
+
+  await page.goto(`/changelog${anchor}`);
+
+  const linked = page.locator(`[id="${anchor!.slice(1)}"]`);
+  await expect(linked).toBeInViewport();
+  await expect(releaseWithHighlights(page).getByRole("listitem").first()).toBeVisible();
+});
diff --git a/packages/website/e2e/download-thanks.spec.ts b/packages/website/e2e/download-thanks.spec.ts
index bc33f8f087..dbbfe69a86 100644
--- a/packages/website/e2e/download-thanks.spec.ts
+++ b/packages/website/e2e/download-thanks.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test, type Page } from "playwright/test";
+import { expect, test, type Page } from "./fixtures";
 
 const APPLE_SILICON_DMG = /\/getpaseo\/paseo\/releases\/download\/v[^/]+\/Paseo-[^/]+-arm64\.dmg$/;
 
diff --git a/packages/website/e2e/fixtures.ts b/packages/website/e2e/fixtures.ts
new file mode 100644
index 0000000000..a0d0ed2e8f
--- /dev/null
+++ b/packages/website/e2e/fixtures.ts
@@ -0,0 +1,18 @@
+import { test as base } from "playwright/test";
+
+export { expect } from "playwright/test";
+export type { Locator, Page } from "playwright/test";
+
+export const test = base.extend({
+  page: async ({ page, baseURL }, run) => {
+    page.on("response", async (response) => {
+      if (response.status() < 500 || new URL(response.url()).origin !== new URL(baseURL!).origin)
+        return;
+      const body = await response.text().catch(() => "<response body unavailable>");
+      console.error(
+        `Website HTTP ${response.status()} ${response.url()}\n${JSON.stringify(body.slice(0, 4000))}`,
+      );
+    });
+    await run(page);
+  },
+});
diff --git a/packages/website/e2e/i18n.spec.ts b/packages/website/e2e/i18n.spec.ts
index d235c4209e..79fa1fa2bb 100644
--- a/packages/website/e2e/i18n.spec.ts
+++ b/packages/website/e2e/i18n.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test, type Page } from "playwright/test";
+import { expect, test, type Page } from "./fixtures";
 
 function languageButton(page: Page) {
   return page.getByRole("button", { name: /^(Language|语言)/ }).first();
@@ -9,6 +9,23 @@ async function chooseLanguage(page: Page, language: string) {
   await page.getByRole("menuitemradio", { name: language }).click();
 }
 
+async function withPageScriptsHeld(page: Page, run: (release: () => void) => Promise<void>) {
+  let releaseScripts!: () => void;
+  const scriptsReleased = new Promise<void>((resolve) => {
+    releaseScripts = resolve;
+  });
+  await page.route("**/*.js", async (route) => {
+    await scriptsReleased;
+    await route.continue();
+  });
+  try {
+    await run(releaseScripts);
+  } finally {
+    releaseScripts();
+    await page.unrouteAll({ behavior: "wait" });
+  }
+}
+
 function describeAlternates(links: Element[]): string[] {
   return links.map((link) => `${link.getAttribute("hreflang")} ${link.getAttribute("href")}`);
 }
@@ -114,6 +131,7 @@ test("shows the language as an abbreviation and lists every language by name", a
 
 test("switches language from the keyboard", async ({ page }) => {
   await page.goto("/");
+  await expect(languageButton(page)).toBeEnabled();
   await languageButton(page).focus();
   await page.keyboard.press("Enter");
   await expect(page.getByRole("menuitemradio", { name: "English" })).toBeFocused();
@@ -183,3 +201,15 @@ test("shows the changelog in Chinese", async ({ page }) => {
   await expect(page.getByRole("heading", { name: "新增" }).first()).toBeVisible();
   await expect(page.getByRole("note")).toHaveCount(0);
 });
+
+test("waits for scripts before enabling the language menu", async ({ page }) => {
+  await withPageScriptsHeld(page, async (releaseScripts) => {
+    await page.goto("/docs/cli#running-agents", { waitUntil: "commit" });
+    await expect(languageButton(page)).toBeVisible();
+    await expect(languageButton(page)).toBeDisabled();
+
+    releaseScripts();
+    await languageButton(page).click();
+    await expect(page.getByRole("menuitemradio", { name: "English" })).toBeVisible();
+  });
+});
diff --git a/packages/website/e2e/mockups.spec.ts b/packages/website/e2e/mockups.spec.ts
index 8b0ba65857..82a440fa1c 100644
--- a/packages/website/e2e/mockups.spec.ts
+++ b/packages/website/e2e/mockups.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test, type Locator, type Page } from "playwright/test";
+import { expect, test, type Locator, type Page } from "./fixtures";
 
 const desktopName =
   "Paseo desktop app with coding agents, a conversation, and a code diff open side by side";
@@ -6,7 +6,7 @@ const desktopName =
 async function openHomepage(page: Page) {
   await page.setViewportSize({ width: 1512, height: 930 });
   await page.goto("/");
-  await expect(page.getByRole("button", { name: "Build", exact: true })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Parallel agents", exact: true })).toBeVisible();
 }
 
 async function viewPhones(page: Page) {
@@ -59,3 +59,42 @@ test("desktop mockup corners shrink in proportion on a phone", async ({ page })
   await resizeToPhone(page);
   await expect.poll(() => cornerProportion(mockup)).toBeCloseTo(desktopCorner, 3);
 });
+
+/** Opacity as rendered: the element's own times every ancestor's. */
+async function renderedOpacity(locator: Locator) {
+  return locator.evaluate((element) => {
+    let opacity = 1;
+    for (let node: Element | null = element; node; node = node.parentElement) {
+      opacity *= Number.parseFloat(getComputedStyle(node).opacity);
+    }
+    return opacity;
+  });
+}
+
+test("the plugin demo plays through to the panel the agent built", async ({ page }) => {
+  await openHomepage(page);
+  const builtPanelRow = page.getByText("Add Gruvbox theme", { exact: true });
+  expect(await renderedOpacity(builtPanelRow)).toBe(0);
+
+  // Hydration can reset the scroll position, so keep the demo in view until it finishes.
+  const heading = page.getByRole("heading", { name: "Ask Paseo to change Paseo" });
+  await expect(async () => {
+    await heading.scrollIntoViewIfNeeded();
+    expect(await renderedOpacity(builtPanelRow)).toBe(1);
+  }).toPass({ timeout: 15_000 });
+  expect(await renderedOpacity(page.getByText("Review queue is in your sidebar."))).toBe(1);
+});
+
+test("the plugin demo shows its finished state when motion is reduced", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await openHomepage(page);
+  const builtPanelRow = page.getByText("Add Gruvbox theme", { exact: true });
+  const panel = builtPanelRow.locator("xpath=ancestor::div[contains(@class, 'md:border-l')]");
+  const heading = page.getByRole("heading", { name: "Ask Paseo to change Paseo" });
+
+  await expect(async () => {
+    await heading.scrollIntoViewIfNeeded();
+    expect(await renderedOpacity(builtPanelRow)).toBe(1);
+  }).toPass({ timeout: 2_000 });
+  expect(await panel.evaluate((element) => getComputedStyle(element).transform)).toBe("none");
+});
diff --git a/packages/website/e2e/plugins.spec.ts b/packages/website/e2e/plugins.spec.ts
index 22baf9e7f1..1b75a0ffa5 100644
--- a/packages/website/e2e/plugins.spec.ts
+++ b/packages/website/e2e/plugins.spec.ts
@@ -1,5 +1,5 @@
 import securityPlugin from "./overview.fixture.json" with { type: "json" };
-import { expect, test, type Page, type Locator } from "playwright/test";
+import { expect, test, type Page, type Locator } from "./fixtures";
 import registry from "./registry.fixture.json" with { type: "json" };
 import { CATEGORIES } from "../src/plugins/categories";
 import copy from "../src/i18n/resources/en.json" with { type: "json" };
@@ -181,6 +181,23 @@ test("keeps the directory's ranking window when searching", async ({ page }) =>
   );
 });
 
+test("submits the visible search term when its input event was missed", async ({ page }) => {
+  await page.goto("/plugins?window=month");
+  await expect(page.getByRole("button", { name: "Language: English" }).first()).toBeEnabled();
+  await fillSearchWithMissedInputEvent(page, "graphite");
+
+  await page.keyboard.press("Enter");
+
+  await expect(page).toHaveURL(/\/plugins\/all\?q=graphite&window=month$/);
+  await expect(
+    page.getByRole("heading", { level: 1, name: /^Results for “graphite”/ }),
+  ).toBeVisible();
+  await expect(page.getByRole("link", { name: "This month" })).toHaveAttribute(
+    "aria-current",
+    "true",
+  );
+});
+
 test("searches for a term typed before the page finished loading", async ({ page }) => {
   const loadScripts = await holdScripts(page);
   await page.goto("/plugins?window=month", { waitUntil: "domcontentloaded" });
@@ -419,6 +436,21 @@ async function searchPlugins(page: Page, term: string) {
   await page.getByRole("searchbox", { name: "Search plugins" }).fill(term);
 }
 
+/** Reproduce text entered before hydration's input listener can observe it, without a clock race. */
+async function fillSearchWithMissedInputEvent(page: Page, term: string) {
+  const search = page.getByRole("searchbox", { name: "Search plugins" });
+  await search.evaluate(() => {
+    for (const eventType of ["input", "change"]) {
+      document.addEventListener(eventType, (event) => event.stopImmediatePropagation(), {
+        capture: true,
+        once: true,
+      });
+    }
+  });
+  await search.fill(term);
+  await expect(search).toHaveValue(term);
+}
+
 async function submitSearch(page: Page, term: string) {
   await searchPlugins(page, term);
   await page.keyboard.press("Enter");
@@ -622,41 +654,41 @@ test.describe("registry fixture layout", () => {
     );
   });
 
-  test("features listed plugins above What's new in the registry's order", async ({ page }) => {
-    await openPlugins(page);
-    await expect(page.getByRole("heading", { level: 2 }).first()).toHaveText("Featured");
-    const featured = page.getByRole("region", { name: "Featured" });
-    await expect(featured).toContainText("A selection of hand picked plugins");
-    await expect(pluginCards(page, "Featured")).toHaveText([/Dracula/, /Herald/, /launchd Jobs/]);
-  });
-
-  test("lists the nine categories in order with counts, and the newest plugins first", async ({
+  test("browses featured, new, and recently updated plugins from the directory", async ({
     page,
   }) => {
     await openPlugins(page);
-    const categories = page.getByRole("region", { name: "Categories" });
-    await expect(categories.getByRole("link")).toHaveText(
-      CATEGORIES.map((slug) => new RegExp(`^${copy.plugins.categories[slug].label}\\s*\\d+$`)),
+
+    await test.step("features listed plugins above What's new in the registry's order", async () => {
+      await expect(page.getByRole("heading", { level: 2 }).first()).toHaveText("Featured");
+      const featured = page.getByRole("region", { name: "Featured" });
+      await expect(featured).toContainText("A selection of hand picked plugins");
+      await expect(pluginCards(page, "Featured")).toHaveText([/Dracula/, /Herald/, /launchd Jobs/]);
+    });
+
+    const categoriesWithCounts = CATEGORIES.map(
+      (slug) => new RegExp(`^${copy.plugins.categories[slug].label}\\s*\\d+$`),
     );
-    await expect(categories.getByRole("link", { name: /Extras/ })).toContainText("0");
-    await expect(pluginCards(page, "What’s new")).toHaveText([
-      /Base2Tone/,
-      /Sayr/,
-      /PromptKit/,
-      /Defer/,
-    ]);
-  });
+    await test.step("lists the nine categories in order with counts, and the newest plugins first", async () => {
+      const categories = page.getByRole("region", { name: "Categories" });
+      await expect(categories.getByRole("link")).toHaveText(categoriesWithCounts);
+      await expect(categories.getByRole("link", { name: /Extras/ })).toContainText("0");
+      await expect(pluginCards(page, "What’s new")).toHaveText([
+        /Base2Tone/,
+        /Sayr/,
+        /PromptKit/,
+        /Defer/,
+      ]);
+    });
 
-  test("lists only plugins updated since they were listed under Recently updated", async ({
-    page,
-  }) => {
-    await openPlugins(page);
-    await expect(pluginCards(page, "Recently updated")).toHaveText([/Defer/, /OMP/]);
-    await page
-      .getByRole("region", { name: "Recently updated" })
-      .getByRole("link", { name: "See all" })
-      .click();
-    await expect(page).toHaveURL(/\/plugins\/all\?sort=updated$/);
+    await test.step("lists only plugins updated since they were listed under Recently updated", async () => {
+      await expect(pluginCards(page, "Recently updated")).toHaveText([/Defer/, /OMP/]);
+      await page
+        .getByRole("region", { name: "Recently updated" })
+        .getByRole("link", { name: "See all" })
+        .click();
+      await expect(page).toHaveURL(/\/plugins\/all\?sort=updated$/);
+    });
   });
 });
 
diff --git a/packages/website/e2e/seed-cache.mjs b/packages/website/e2e/seed-cache.mjs
new file mode 100644
index 0000000000..67990be289
--- /dev/null
+++ b/packages/website/e2e/seed-cache.mjs
@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const state = process.env.WEBSITE_E2E_PERSIST_PATH;
+if (!state) throw new Error("WEBSITE_E2E_PERSIST_PATH is required");
+// Keep these local test records fresh for a full test run, even after the normal cache TTL.
+const fixtureTimestamp = Date.now() + 24 * 60 * 60 * 1000;
+const entries = [
+  { key: "github-stars:v1", value: "12.3k" },
+  {
+    key: "github-release:v2",
+    value: {
+      stable: {
+        version: "0.15.0",
+        linuxAppImageAsset: "Paseo-x86_64.AppImage",
+        windowsX64Asset: "Paseo-Setup-0.15.0-x64.exe",
+        windowsArm64Asset: "Paseo-Setup-0.15.0-arm64.exe",
+      },
+      beta: null,
+    },
+  },
+];
+mkdirSync(state, { recursive: true });
+const file = path.join(state, "fixtures.json");
+writeFileSync(
+  file,
+  JSON.stringify(
+    entries.map(({ key, value }) => ({
+      key,
+      value: JSON.stringify({ fetchedAt: fixtureTimestamp, value }),
+    })),
+  ),
+);
+execFileSync(
+  process.execPath,
+  [
+    path.join(
+      path.dirname(createRequire(import.meta.url).resolve("wrangler/package.json")),
+      "bin/wrangler.js",
+    ),
+    "kv",
+    "bulk",
+    "put",
+    file,
+    "--binding",
+    "WEBSITE_CACHE",
+    "--local",
+    "--persist-to",
+    state,
+  ],
+  { stdio: "inherit" },
+);
diff --git a/packages/website/e2e/sponsors.spec.ts b/packages/website/e2e/sponsors.spec.ts
index 7b42316d54..4aa15ec413 100644
--- a/packages/website/e2e/sponsors.spec.ts
+++ b/packages/website/e2e/sponsors.spec.ts
@@ -1,4 +1,4 @@
-import { expect, test } from "playwright/test";
+import { expect, test } from "./fixtures";
 
 const PAGES = ["/", "/docs/connectivity", "/changelog"];
 
diff --git a/packages/website/package.json b/packages/website/package.json
index 7e0635c2e9..6b955dee0f 100644
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/packages/website/playwright.config.ts b/packages/website/playwright.config.ts
index ebb29f0237..49e058ec32 100644
--- a/packages/website/playwright.config.ts
+++ b/packages/website/playwright.config.ts
@@ -1,3 +1,4 @@
+import path from "node:path";
 import { defineConfig, devices } from "playwright/test";
 
 const baseURL = process.env.WEBSITE_TEST_URL ?? "http://127.0.0.1:8187";
@@ -18,11 +19,16 @@ export default defineConfig({
           url: "http://127.0.0.1:8188/index.json",
         },
         {
-          command: "npm run build && npm run preview -- --host 127.0.0.1 --port 8187 --strictPort",
+          command:
+            "node e2e/seed-cache.mjs && npm run build && npm run preview -- --host 127.0.0.1 --port 8187 --strictPort",
           // Probe the server without running the homepage loader's live GitHub requests.
           url: new URL("/logo.svg", baseURL).href,
           stdout: "pipe",
           env: {
+            WEBSITE_E2E_PERSIST_PATH: path.resolve(
+              import.meta.dirname,
+              "../../.artifacts/website-e2e-cache",
+            ),
             CLOUDFLARE_INCLUDE_PROCESS_ENV: "true",
             PLUGINS_REGISTRY_URL: "http://127.0.0.1:8188",
           },
diff --git a/packages/website/public/schemas/paseo.config.v1.json b/packages/website/public/schemas/paseo.config.v1.json
index bae380d4c8..8ead791033 100644
--- a/packages/website/public/schemas/paseo.config.v1.json
+++ b/packages/website/public/schemas/paseo.config.v1.json
@@ -176,6 +176,13 @@
                 },
                 "additionalProperties": {}
               },
+              "options": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
+              },
               "notes": {
                 "type": "string"
               }
diff --git a/packages/website/src/changelog.test.ts b/packages/website/src/changelog.test.ts
index e4e6e44a1b..98ea851aee 100644
--- a/packages/website/src/changelog.test.ts
+++ b/packages/website/src/changelog.test.ts
@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import { getChangelogReleaseGroups, localizeReleases, parseChangelog } from "~/changelog";
 
@@ -16,6 +18,81 @@ const ENGLISH = parseChangelog(
   "en",
 );
 
+describe("parseChangelog", () => {
+  it("splits a release into the highlights it leads with and its sections", () => {
+    const [release] = parseChangelog(
+      [
+        "## 0.3.0 - 2026-05-03",
+        "",
+        "- **Faster diffs:** Diffs load sooner.",
+        "",
+        "### Added",
+        "",
+        "- Added a picker",
+        "",
+        "### Fixed",
+        "",
+        "- Fixed a crash",
+        "",
+      ].join("\n"),
+      "en",
+    );
+
+    expect(release).toEqual({
+      version: "0.3.0",
+      date: "2026-05-03",
+      highlights: "- **Faster diffs:** Diffs load sooner.",
+      sections: "### Added\n\n- Added a picker\n\n### Fixed\n\n- Fixed a crash",
+      locale: "en",
+    });
+  });
+
+  it("has no highlights when a release opens with a section", () => {
+    const [release] = parseChangelog("## 0.3.0 - 2026-05-03\n\n### Fixed\n\n- One\n", "en");
+
+    expect(release).toMatchObject({ highlights: "", sections: "### Fixed\n\n- One" });
+  });
+});
+
+/** The cases the app, the website and the release scripts must all split the same way. */
+interface ChangelogStructureCases {
+  document: string[];
+  releases: { version: string; date: string; highlights: string[]; sections: string[] }[];
+}
+
+const structureCases: ChangelogStructureCases = JSON.parse(
+  readFileSync(
+    fileURLToPath(
+      new URL("../../../scripts/test-support/changelog-structure.json", import.meta.url),
+    ),
+    "utf8",
+  ),
+);
+
+describe("the structure every changelog surface shares", () => {
+  for (const lineEnding of ["\n", "\r\n"]) {
+    it(`splits the shared cases with ${JSON.stringify(lineEnding)} line endings`, () => {
+      const releases = parseChangelog(structureCases.document.join(lineEnding), "en");
+
+      expect(
+        releases.map((release) => ({
+          version: release.version,
+          date: release.date,
+          highlights: release.highlights,
+          sections: release.sections,
+        })),
+      ).toEqual(
+        structureCases.releases.map((release) => ({
+          version: release.version,
+          date: release.date,
+          highlights: release.highlights.join("\n"),
+          sections: release.sections.join("\n"),
+        })),
+      );
+    });
+  }
+});
+
 describe("localizeReleases", () => {
   it("uses a translation whose version and date match the English entry", () => {
     const chinese = parseChangelog("## 0.1.0 - 2026-05-01\n\n- 旧\n", "zh-CN");
diff --git a/packages/website/src/changelog.ts b/packages/website/src/changelog.ts
index 9b3295639e..bf112c8a65 100644
--- a/packages/website/src/changelog.ts
+++ b/packages/website/src/changelog.ts
@@ -5,8 +5,11 @@ import { DEFAULT_LOCALE, type Locale, localizePath } from "~/i18n";
 export interface ChangelogRelease {
   version: string;
   date: string;
-  markdown: string;
-  /** The language of `markdown`; English when the release has no translation yet. */
+  /** Markdown before the first `###` section; empty when the release opens with a section. */
+  highlights: string;
+  /** Markdown from the first `###` section to the end of the release; the full record. */
+  sections: string;
+  /** The language of the notes; English when the release has no translation yet. */
   locale: Locale;
 }
 
@@ -15,7 +18,12 @@ export interface ChangelogReleaseGroup {
   releases: ChangelogRelease[];
 }
 
+// The app's What's new sheet and the release scripts parse the same file with their own code.
+// `scripts/test-support/changelog-structure.json` holds the cases all three must split the same
+// way; a change to the structure rules starts there.
 const releaseHeadingPattern = /^## (.+?) - (\d{4}-\d{2}-\d{2})$/;
+const sectionHeadingPattern = /^ {0,3}###(?:[ \t]|$)/;
+const fencePattern = /^\s*(`{3,}|~{3,})/;
 
 export function releaseAnchor(version: string): string {
   return `release-${version}`;
@@ -25,13 +33,31 @@ function minorVersion(version: string): string {
   return version.split(".").slice(0, 2).join(".");
 }
 
-export function parseChangelog(markdown: string, locale: Locale): ChangelogRelease[] {
-  const releases: ChangelogRelease[] = [];
-  const versions = new Set<string>();
-  let currentRelease: ChangelogRelease | null = null;
+interface ReleaseDraft {
+  version: string;
+  date: string;
+  highlights: string[];
+  sections: string[];
+}
 
-  for (const line of markdown.split("\n")) {
-    const heading = line.match(releaseHeadingPattern);
+export function parseChangelog(markdown: string, locale: Locale): ChangelogRelease[] {
+  const releases: ReleaseDraft[] = [];
+  const versions = new Set<string>();
+  let currentRelease: ReleaseDraft | null = null;
+  // A `##` or `###` inside a fenced code block is an example, so it starts nothing.
+  let fence: string | null = null;
+
+  for (const line of markdown.split(/\r?\n/)) {
+    const fenceEdge = line.match(fencePattern)?.[1];
+    if (fenceEdge) {
+      if (!fence) {
+        fence = fenceEdge;
+      } else if (fenceEdge[0] === fence[0] && fenceEdge.length >= fence.length) {
+        fence = null;
+      }
+    }
+
+    const heading = fence ? null : line.match(releaseHeadingPattern);
     if (heading) {
       const version = heading[1];
       if (versions.has(version)) {
@@ -40,20 +66,35 @@ export function parseChangelog(markdown: string, locale: Locale): ChangelogRelea
       versions.add(version);
 
       if (currentRelease) releases.push(currentRelease);
-      currentRelease = {
-        version,
-        date: heading[2],
-        markdown: "",
-        locale,
-      };
+      currentRelease = { version, date: heading[2], highlights: [], sections: [] };
       continue;
     }
 
-    if (currentRelease) currentRelease.markdown += `${line}\n`;
+    if (!currentRelease) continue;
+    const startsSection = !fence && sectionHeadingPattern.test(line);
+    if (currentRelease.sections.length > 0 || startsSection) {
+      currentRelease.sections.push(line);
+    } else {
+      currentRelease.highlights.push(line);
+    }
   }
 
   if (currentRelease) releases.push(currentRelease);
-  return releases;
+  return releases.map((release) => ({
+    version: release.version,
+    date: release.date,
+    highlights: joinWithoutBlankEdges(release.highlights),
+    sections: joinWithoutBlankEdges(release.sections),
+    locale,
+  }));
+}
+
+function joinWithoutBlankEdges(lines: string[]): string {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") start += 1;
+  while (end > start && lines[end - 1].trim() === "") end -= 1;
+  return lines.slice(start, end).join("\n");
 }
 
 /**
diff --git a/packages/website/src/components/landing-page.tsx b/packages/website/src/components/landing-page.tsx
index 93d43afa26..77869e7379 100644
--- a/packages/website/src/components/landing-page.tsx
+++ b/packages/website/src/components/landing-page.tsx
@@ -1,4 +1,6 @@
 import { PLUGINS_LINKED } from "~/plugins/launch";
+import { categoryHref } from "~/plugins/links";
+import type { CategorySlug } from "~/plugins/categories";
 import * as React from "react";
 import { Trans, useTranslation } from "react-i18next";
 import {
@@ -10,7 +12,7 @@ import {
   ExternalLink,
   Gem,
   GitFork,
-  LayoutPanelLeft,
+  GitPullRequest,
   Laptop,
   Lock,
   Merge,
@@ -19,16 +21,17 @@ import {
   Smartphone,
   Terminal,
   Users,
-  Workflow,
   type LucideIcon,
 } from "lucide-react";
 import {
   motion,
   AnimatePresence,
   useInView,
+  useReducedMotion,
   useScroll,
   useTransform,
   type Transition,
+  type Variants,
 } from "framer-motion";
 
 // Shared motion presets — hoisted so every JSX site receives the same object
@@ -86,7 +89,14 @@ import {
   PiIcon,
 } from "~/components/agent-icons";
 import { DiscordIcon, GitHubIcon, SlackIcon } from "~/components/brand-icons";
-import { MobileChat, MobileDiff, MobileSidebar, PhoneFrame } from "~/components/mockup";
+import {
+  MobileChat,
+  MobileDiff,
+  MobileSidebar,
+  PhoneFrame,
+  type ToolCall,
+  ToolCallRow,
+} from "~/components/mockup";
 import { FAQItem } from "~/components/faq-item";
 import { SiteFooter } from "~/components/site-footer";
 import { SponsorSection, SponsorsSection } from "~/components/sponsorship";
@@ -132,8 +142,8 @@ export function LandingPage({ title, subtitle }: LandingPageProps) {
             <SocialProofWall />
             <MultiProviderSection />
             <TurnkeySection />
-            <AutomationSection />
             <ExtensibleSection />
+            <AutomationSection />
             <SponsorsSection placement="page" />
             <SponsorSection />
             <PhilosophySection />
@@ -703,41 +713,50 @@ function AutomationDetail({ kind }: { kind: AutomationKind }) {
   );
 }
 
+const MCP_AGENT_CALLS: ToolCall[] = [
+  { kind: "paseo", label: "Create agent", detail: "Fix #412: retry flaky relay handshake" },
+  { kind: "paseo", label: "Create agent", detail: "Fix #417: group schedules by project" },
+];
+
 function McpAutomationTranscript() {
   const { t } = useTranslation();
+  return (
+    <AgentTurn request={t("landing.automation.transcriptRequest")}>
+      <AgentText>{t("landing.automation.transcriptPlan")}</AgentText>
+      <ToolCalls calls={MCP_AGENT_CALLS} />
+      <AgentText>{t("landing.automation.transcriptDone")}</AgentText>
+    </AgentTurn>
+  );
+}
+
+/** A user message and the agent's reply, laid out like the app's timeline. */
+function AgentTurn({ request, children }: { request: string; children: React.ReactNode }) {
   return (
     <div className="space-y-5">
-      <div className="ml-auto w-fit max-w-xl rounded-xl rounded-tr-none bg-white/[0.07] px-4 py-3">
-        <p className="text-sm leading-relaxed text-white/75">
-          {t("landing.automation.transcriptRequest")}
-        </p>
-      </div>
-      <div className="flex items-start gap-3">
-        <Bot className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" strokeWidth={1.5} />
-        <div className="min-w-0 flex-1 space-y-4">
-          <p className="text-sm leading-relaxed text-white/55">
-            {t("landing.automation.transcriptPlan")}
-          </p>
-          <div className="space-y-2 font-mono text-[11px]">
-            <McpAgentCall issue="#412" provider="claude/opus-4.6" />
-            <McpAgentCall issue="#417" provider="codex/gpt-5.6-sol" />
-          </div>
-          <p className="text-sm leading-relaxed text-white/55">
-            {t("landing.automation.transcriptDone")}
-          </p>
-        </div>
-      </div>
+      <UserMessage>{request}</UserMessage>
+      <div className="space-y-3">{children}</div>
     </div>
   );
 }
 
-function McpAgentCall({ issue, provider }: { issue: string; provider: string }) {
+function UserMessage({ children }: { children: React.ReactNode }) {
   return (
-    <div className="flex flex-wrap items-center gap-x-2 gap-y-1 rounded-md border border-white/[0.07] bg-white/[0.025] px-3 py-2">
-      <span className="text-sky-300/80">create_agent</span>
-      <span className="text-white/25">{issue}</span>
-      <span className="text-white/35">{provider}</span>
-      <span className="text-white/25">worktree</span>
+    <div className="ml-auto w-fit max-w-md rounded-xl bg-white/[0.07] px-4 py-3">
+      <p className="text-sm leading-relaxed text-white/80">{children}</p>
+    </div>
+  );
+}
+
+function AgentText({ children }: { children: React.ReactNode }) {
+  return <p className="text-sm leading-relaxed text-white/80">{children}</p>;
+}
+
+function ToolCalls({ calls }: { calls: ReadonlyArray<ToolCall> }) {
+  return (
+    <div>
+      {calls.map((call) => (
+        <ToolCallRow key={`${call.kind}:${call.detail}`} call={call} />
+      ))}
     </div>
   );
 }
@@ -842,17 +861,16 @@ function ExtensibleSection() {
       title={t("landing.plugins.title")}
       description={t("landing.plugins.description")}
     >
-      <div className="space-y-8">
-        <ProductLead icon={Puzzle} title={t("landing.plugins.lead")} actions={pluginActions} />
-        <div className="grid gap-4 md:grid-cols-3">
-          {PLUGIN_CAPABILITIES.map((capability) => (
-            <FeatureCard
-              key={capability.key}
-              icon={capability.icon}
-              title={t(`landing.plugins.${capability.key}Title`)}
-              description={t(`landing.plugins.${capability.key}Description`)}
-            />
-          ))}
+      <div className="space-y-12">
+        <SelfModifyDemo />
+        <div className="space-y-6">
+          <ProductLead
+            icon={Puzzle}
+            title={t("landing.plugins.libraryTitle")}
+            description={t("landing.plugins.libraryDescription")}
+            actions={pluginActions}
+          />
+          <PluginCategoryLinks />
         </div>
         <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
           <p className="text-sm text-white/45">{t("landing.plugins.license")}</p>
@@ -872,6 +890,156 @@ function ExtensibleSection() {
   );
 }
 
+const PLUGIN_BUILD_CALLS: ToolCall[] = [
+  { kind: "read", detail: "paseo-plugin/SKILL.md" },
+  { kind: "shell", detail: "paseo plugin init review-queue" },
+  { kind: "write", detail: "review-queue/index.ts" },
+  { kind: "write", detail: "review-queue/review-queue.client.tsx" },
+  { kind: "shell", detail: "paseo plugin install ./review-queue" },
+];
+
+// The demo plays once when it scrolls into view: the prompt, then each timeline
+// item in turn, then the panel the agent built slides in and fills.
+const DEMO_STEP_SECONDS = 0.45;
+const DEMO_STEPS = {
+  prompt: 0,
+  plan: 1.4,
+  firstCall: 2.2,
+} as const;
+const DEMO_DONE_STEP = DEMO_STEPS.firstCall + PLUGIN_BUILD_CALLS.length;
+const DEMO_PANEL_STEP = DEMO_DONE_STEP + 1;
+
+const DEMO_ITEM_VARIANTS: Variants = {
+  hidden: { opacity: 0, y: 6 },
+  shown: (step: number) => ({
+    opacity: 1,
+    y: 0,
+    transition: { delay: step * DEMO_STEP_SECONDS, duration: 0.35, ease: "easeOut" },
+  }),
+};
+const DEMO_PANEL_VARIANTS: Variants = {
+  hidden: { opacity: 0, x: "100%" },
+  shown: {
+    opacity: 1,
+    x: 0,
+    transition: {
+      delay: DEMO_PANEL_STEP * DEMO_STEP_SECONDS,
+      duration: 0.6,
+      ease: [0.22, 0.61, 0.36, 1],
+    },
+  },
+};
+
+/** One piece of the demo that fades in at its step. */
+function DemoItem({ step, children }: { step: number; children: React.ReactNode }) {
+  return (
+    <motion.div variants={DEMO_ITEM_VARIANTS} custom={step}>
+      {children}
+    </motion.div>
+  );
+}
+
+/** The ask on the left, the panel it produced on the right. */
+function SelfModifyDemo() {
+  const { t } = useTranslation();
+  // Visitors who ask for reduced motion get the finished demo, with no slide or staging.
+  const reduceMotion = useReducedMotion();
+  return (
+    <motion.div
+      initial={reduceMotion ? "shown" : "hidden"}
+      whileInView="shown"
+      viewport={VIEWPORT_60}
+      className="grid min-h-[22rem] grid-cols-[minmax(0,1fr)] overflow-hidden rounded-xl border border-white/10 bg-black/20 md:grid-cols-[minmax(0,1fr)_17rem]"
+    >
+      <div className="space-y-5 p-5 md:p-6">
+        <DemoItem step={DEMO_STEPS.prompt}>
+          <UserMessage>{t("landing.plugins.request")}</UserMessage>
+        </DemoItem>
+        <div className="space-y-3">
+          <DemoItem step={DEMO_STEPS.plan}>
+            <AgentText>{t("landing.plugins.plan")}</AgentText>
+          </DemoItem>
+          <div>
+            {PLUGIN_BUILD_CALLS.map((call, index) => (
+              <DemoItem key={`${call.kind}:${call.detail}`} step={DEMO_STEPS.firstCall + index}>
+                <ToolCallRow call={call} />
+              </DemoItem>
+            ))}
+          </div>
+          <DemoItem step={DEMO_DONE_STEP}>
+            <AgentText>{t("landing.plugins.done")}</AgentText>
+          </DemoItem>
+        </div>
+      </div>
+      <ReviewQueuePreview />
+    </motion.div>
+  );
+}
+
+const REVIEW_QUEUE = [
+  { number: "#418", title: "Retry flaky relay handshake", author: "ana", age: "12m" },
+  { number: "#415", title: "Group schedules by project", author: "kenji", age: "1h" },
+  { number: "#409", title: "Add Gruvbox theme", author: "lea", age: "3h" },
+] as const;
+
+/** The panel the agent just built, docked like a real sidebar panel. */
+function ReviewQueuePreview() {
+  const { t } = useTranslation();
+  return (
+    <motion.div
+      variants={DEMO_PANEL_VARIANTS}
+      className="border-t border-white/10 bg-white/[0.025] p-4 md:border-t-0 md:border-l"
+    >
+      <div className="mb-3 flex items-center gap-2">
+        <GitPullRequest className="h-4 w-4 text-muted-foreground" strokeWidth={1.5} />
+        <span className="text-sm font-medium text-white/85">{t("landing.plugins.panelTitle")}</span>
+        <span className="ml-auto rounded-full bg-white/[0.07] px-2 py-0.5 text-[10px] text-white/55">
+          {REVIEW_QUEUE.length}
+        </span>
+      </div>
+      <div className="space-y-1">
+        {REVIEW_QUEUE.map((pr, index) => (
+          <DemoItem key={pr.number} step={DEMO_PANEL_STEP + 1.2 + index * 0.4}>
+            <div className="rounded-md px-2 py-2 hover:bg-white/[0.04]">
+              <p className="truncate text-xs text-white/80">{pr.title}</p>
+              <p className="mt-0.5 font-mono text-[10px] text-white/35">
+                {pr.number} · {pr.author} · {pr.age}
+              </p>
+            </div>
+          </DemoItem>
+        ))}
+      </div>
+    </motion.div>
+  );
+}
+
+const SHOWCASE_CATEGORIES = [
+  "themes",
+  "sidebar",
+  "workspaces",
+  "providers",
+  "orchestration",
+  "git",
+] as const satisfies ReadonlyArray<CategorySlug>;
+
+function PluginCategoryLinks() {
+  const { t } = useTranslation();
+  const localize = useLocalizePath();
+  return (
+    <div className="flex flex-wrap gap-2">
+      {SHOWCASE_CATEGORIES.map((category) => (
+        <a
+          key={category}
+          href={localize(categoryHref(category))}
+          className="rounded-full border border-white/10 bg-white/[0.025] px-3 py-1.5 text-xs text-white/70 transition-colors hover:border-white/15 hover:bg-white/[0.06] hover:text-white"
+        >
+          {t(`plugins.categories.${category}.label`)}
+        </a>
+      ))}
+    </div>
+  );
+}
+
 const PLUGINS_BROWSE = PLUGINS_LINKED
   ? { href: "/plugins", external: false }
   : { href: "https://paseo.cafe", external: true };
@@ -899,12 +1067,6 @@ function PluginActions() {
   );
 }
 
-const PLUGIN_CAPABILITIES = [
-  { icon: LayoutPanelLeft, key: "ui" },
-  { icon: Workflow, key: "lifecycle" },
-  { icon: Bot, key: "providers" },
-] as const;
-
 const PRINCIPLES = [
   { icon: Lock, key: "private" },
   { icon: Compass, key: "independent" },
diff --git a/packages/website/src/components/language-selector.tsx b/packages/website/src/components/language-selector.tsx
index 9fb219fad5..601663f534 100644
--- a/packages/website/src/components/language-selector.tsx
+++ b/packages/website/src/components/language-selector.tsx
@@ -1,4 +1,4 @@
-import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useHydrated, useLocation, useNavigate } from "@tanstack/react-router";
 import { AnimatePresence, motion, type Transition } from "framer-motion";
 import { Check, ChevronDown, Languages } from "lucide-react";
 import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
@@ -33,6 +33,7 @@ type OpenFocus = "current" | "first" | "last";
  * the menu button pattern: arrows move between languages, Escape and outside presses close it.
  */
 export function LanguageSelector() {
+  const hydrated = useHydrated();
   const { t } = useTranslation();
   const locale = useLocale();
   const location = useLocation();
@@ -125,6 +126,7 @@ export function LanguageSelector() {
       <button
         ref={triggerRef}
         type="button"
+        disabled={!hydrated}
         aria-label={t("languageSelector.current", { language: LANGUAGE_NAMES[locale] })}
         aria-haspopup="menu"
         aria-expanded={open}
diff --git a/packages/website/src/components/mockup/chat.tsx b/packages/website/src/components/mockup/chat.tsx
index f944839cf8..dc951a8517 100644
--- a/packages/website/src/components/mockup/chat.tsx
+++ b/packages/website/src/components/mockup/chat.tsx
@@ -1,14 +1,14 @@
 import {
   AudioLines,
-  BookOpen,
   Brain,
   ChevronDown,
   CircleDot,
   Copy,
-  FilePenLine,
+  Eye,
   LoaderCircle,
   ListTodo,
   Mic,
+  Pencil,
   Plus,
   ShieldOff,
   Split,
@@ -18,7 +18,7 @@ import {
 import type * as React from "react";
 import { useTranslation } from "react-i18next";
 import { DiffStat } from "./atoms";
-import { CodexIcon } from "./icons";
+import { CodexIcon, PaseoMark } from "./icons";
 
 // Icons passed as props are hoisted so they are not rebuilt on every render.
 const MODEL_ICON = <CodexIcon size={13} />;
@@ -94,70 +94,62 @@ export function AgentTranscript() {
   );
 }
 
-interface PluginToolCall {
-  kind: "read" | "shell" | "write";
-  label: string;
-  detail: string;
+/**
+ * A collapsed tool call as the app's timeline shows it. Built-in tools carry a
+ * fixed label; Paseo MCP tools name their action, such as "Create agent".
+ */
+export type ToolCall =
+  | { kind: "read" | "write" | "shell"; detail: string }
+  | { kind: "paseo"; label: string; detail: string };
+
+const BUILT_IN_LABELS = { read: "Read", write: "Write", shell: "Shell" } as const;
+
+function toolCallLabel(call: ToolCall): string {
+  return call.kind === "paseo" ? call.label : BUILT_IN_LABELS[call.kind];
 }
 
-const PLUGIN_TOOL_CALLS: PluginToolCall[] = [
-  { kind: "read", label: "Read", detail: "paseo-plugin/SKILL.md" },
-  {
-    kind: "shell",
-    label: "Shell",
-    detail: "paseo plugin init ~/dev/release-radar",
-  },
-  {
-    kind: "write",
-    label: "Write",
-    detail: "~/dev/release-radar/index.ts",
-  },
-  {
-    kind: "write",
-    label: "Write",
-    detail: "~/dev/release-radar/release-radar.client.tsx",
-  },
-  {
-    kind: "shell",
-    label: "Shell",
-    detail: "npm install && npm run typecheck",
-  },
-  {
-    kind: "shell",
-    label: "Shell",
-    detail: "paseo plugin install ~/dev/release-radar",
-  },
+const PLUGIN_TOOL_CALLS: ToolCall[] = [
+  { kind: "read", detail: "paseo-plugin/SKILL.md" },
+  { kind: "shell", detail: "paseo plugin init ~/dev/release-radar" },
+  { kind: "write", detail: "~/dev/release-radar/index.ts" },
+  { kind: "write", detail: "~/dev/release-radar/release-radar.client.tsx" },
+  { kind: "shell", detail: "npm install && npm run typecheck" },
+  { kind: "shell", detail: "paseo plugin install ~/dev/release-radar" },
 ];
 
 const PLUGIN_DISCOVERY_CALLS = PLUGIN_TOOL_CALLS.slice(0, 1);
 const PLUGIN_BUILD_CALLS = PLUGIN_TOOL_CALLS.slice(1, 4);
 const PLUGIN_INSTALL_CALLS = PLUGIN_TOOL_CALLS.slice(4);
 
-function PluginToolIcon({ kind }: { kind: PluginToolCall["kind"] }) {
-  if (kind === "read") return <BookOpen size={14} />;
-  if (kind === "write") return <FilePenLine size={14} />;
+function ToolCallIcon({ kind }: { kind: ToolCall["kind"] }) {
+  if (kind === "read") return <Eye size={14} />;
+  if (kind === "write") return <Pencil size={14} />;
+  if (kind === "paseo") return <PaseoMark size={14} />;
   return <SquareTerminal size={14} />;
 }
 
-function PluginToolRow({ call }: { call: PluginToolCall }) {
+/**
+ * One tool call row, drawn like the app's collapsed timeline item
+ * (`packages/app/src/components/message.tsx`): icon, label, then the summary,
+ * all muted and in the UI font.
+ */
+export function ToolCallRow({ call }: { call: ToolCall }) {
   return (
-    <div className="flex items-center gap-[9px] py-[5px] text-[12.5px] leading-[18px]">
-      <span className="text-mock-fg-muted">
-        <PluginToolIcon kind={call.kind} />
-      </span>
-      <span className="shrink-0 text-mock-fg">{call.label}</span>
-      <span className="min-w-0 truncate font-mono text-[11.5px] text-mock-fg-muted">
-        {call.detail}
+    <div className="flex items-center gap-[8px] py-[5px] text-[12.5px] leading-[18px] text-mock-fg-muted">
+      <span className="shrink-0">
+        <ToolCallIcon kind={call.kind} />
       </span>
+      <span className="shrink-0">{toolCallLabel(call)}</span>
+      <span className="min-w-0 truncate">{call.detail}</span>
     </div>
   );
 }
 
-function PluginToolGroup({ calls }: { calls: PluginToolCall[] }) {
+function PluginToolGroup({ calls }: { calls: ToolCall[] }) {
   return (
     <div>
       {calls.map((call) => (
-        <PluginToolRow key={`${call.label}:${call.detail}`} call={call} />
+        <ToolCallRow key={`${call.kind}:${call.detail}`} call={call} />
       ))}
     </div>
   );
diff --git a/packages/website/src/components/mockup/index.ts b/packages/website/src/components/mockup/index.ts
index 71ffed8b8d..d07c4d1f56 100644
--- a/packages/website/src/components/mockup/index.ts
+++ b/packages/website/src/components/mockup/index.ts
@@ -1,4 +1,5 @@
 export { ClaudeIcon, CodexIcon, SourceControlIcon } from "./icons";
+export { type ToolCall, ToolCallRow } from "./chat";
 export { DESIGN_HEIGHT, DESIGN_WIDTH } from "./geometry";
 export { PhoneFrame } from "./mobile/frame";
 export { MobileChat } from "./mobile/chat";
diff --git a/packages/website/src/docs.ts b/packages/website/src/docs.ts
index 1325cd933f..896d86daf9 100644
--- a/packages/website/src/docs.ts
+++ b/packages/website/src/docs.ts
@@ -186,7 +186,13 @@ function insertDocByPath(nodes: DocsNavNode[], doc: Doc, stripTopDirectory = fal
 
   // A section's top-level directory and its category name the same thing, so
   // only directories below it become collapsible groups.
-  if (stripTopDirectory) directories.shift();
+  if (
+    stripTopDirectory &&
+    directories[0] &&
+    doc.frontmatter.category?.toLowerCase().endsWith(directories[0].toLowerCase())
+  ) {
+    directories.shift();
+  }
 
   let current = nodes;
   let parent: Extract<DocsNavNode, { type: "group" }> | undefined;
diff --git a/packages/website/src/i18n/resources/en.json b/packages/website/src/i18n/resources/en.json
index 055229ca47..b179f26326 100644
--- a/packages/website/src/i18n/resources/en.json
+++ b/packages/website/src/i18n/resources/en.json
@@ -375,19 +375,18 @@
       "otherHostComment": "# Target another host"
     },
     "plugins": {
-      "title": "Extend it with plugins",
-      "description": "Add new panels and functionality that work in desktop, web and mobile",
-      "lead": "Plugins",
+      "title": "Ask Paseo to change Paseo",
+      "description": "Agents in Paseo can change the whole UI without a restart, even on mobile.",
+      "request": "Add a sidebar panel with the PRs waiting on my review.",
+      "plan": "I'll build it as a local plugin and install it.",
+      "done": "Review queue is in your sidebar.",
+      "panelTitle": "Review queue",
+      "libraryTitle": "400+ community plugins",
+      "libraryDescription": "Built by developers on the same plugin API your agents use",
       "browse": "Browse plugins",
       "docs": "Plugin docs",
       "license": "Paseo is Apache 2.0.",
-      "fork": "Fork the repo",
-      "uiTitle": "UI",
-      "uiDescription": "Screens, workspace panels, sidebar items, slash commands, and themes",
-      "lifecycleTitle": "Agent lifecycle",
-      "lifecycleDescription": "Change config and MCP servers, answer permissions, and follow up",
-      "providersTitle": "Providers",
-      "providersDescription": "Add a coding agent as a provider, used like the built-in ones"
+      "fork": "Fork the repo"
     },
     "philosophy": {
       "title": "Philosophy",
@@ -447,10 +446,10 @@
     },
     "mockup": {
       "alt": "Paseo desktop app with coding agents, a conversation, and a code diff open side by side",
-      "build": "Build",
-      "review": "Review",
-      "ship": "Ship",
-      "extend": "Extend",
+      "build": "Parallel agents",
+      "review": "Code review",
+      "ship": "Pull requests",
+      "extend": "Plugins",
       "app": {
         "newWorkspace": "New workspace",
         "history": "History",
@@ -652,6 +651,8 @@
     "metaDescription": "Product updates, bug fixes, and improvements shipped in each Paseo release. Track new agent providers, mobile features, and daemon changes over time.",
     "title": "Changelog",
     "linkTo": "Link to Paseo {{version}}",
+    "showAllChanges": "Show all changes",
+    "hideAllChanges": "Hide all changes",
     "untranslatedRelease": "These release notes have not been translated yet, so they are shown in English."
   },
   "blog": {
diff --git a/packages/website/src/i18n/resources/zh-CN.json b/packages/website/src/i18n/resources/zh-CN.json
index 048d351e4d..cc20bdb43e 100644
--- a/packages/website/src/i18n/resources/zh-CN.json
+++ b/packages/website/src/i18n/resources/zh-CN.json
@@ -375,19 +375,18 @@
       "otherHostComment": "# 指定另一台主机"
     },
     "plugins": {
-      "title": "用插件扩展",
-      "description": "添加新的面板和功能，在桌面端、网页端和移动端都能使用",
-      "lead": "插件",
+      "title": "让 Paseo 修改 Paseo",
+      "description": "Paseo 里的 Agent 可以修改整个界面，无需重启，在移动端也一样。",
+      "request": "在侧边栏加一个面板，列出等待我审查的 PR。",
+      "plan": "我会把它做成本地插件并安装。",
+      "done": "审查队列已出现在你的侧边栏。",
+      "panelTitle": "审查队列",
+      "libraryTitle": "400 多个社区插件",
+      "libraryDescription": "开发者用的是和你的 Agent 相同的插件 API",
       "browse": "浏览插件",
       "docs": "插件文档",
       "license": "Paseo 采用 Apache 2.0 许可证。",
-      "fork": "Fork 仓库",
-      "uiTitle": "界面",
-      "uiDescription": "页面、工作区面板、侧边栏项目、斜杠命令和主题",
-      "lifecycleTitle": "Agent 生命周期",
-      "lifecycleDescription": "修改配置和 MCP 服务器、响应权限请求、发送后续消息",
-      "providersTitle": "Provider",
-      "providersDescription": "把编程 Agent 添加为 Provider，用法与内置 Provider 相同"
+      "fork": "Fork 仓库"
     },
     "philosophy": {
       "title": "理念",
@@ -447,10 +446,10 @@
     },
     "mockup": {
       "alt": "Paseo 桌面应用，并排打开了编程 Agent、一段对话和一份代码 diff",
-      "build": "构建",
-      "review": "审查",
-      "ship": "发布",
-      "extend": "扩展",
+      "build": "并行 Agent",
+      "review": "代码审查",
+      "ship": "Pull Request",
+      "extend": "插件",
       "app": {
         "newWorkspace": "新建工作区",
         "history": "历史",
@@ -652,6 +651,8 @@
     "metaDescription": "每个 Paseo 版本发布的产品更新、问题修复和改进。了解新的 Agent Provider、移动端功能和 daemon 变化。",
     "title": "更新日志",
     "linkTo": "链接到 Paseo {{version}}",
+    "showAllChanges": "显示全部变更",
+    "hideAllChanges": "收起全部变更",
     "untranslatedRelease": "此版本的发布说明尚未翻译，因此以英文显示。"
   },
   "blog": {
diff --git a/packages/website/src/plugin-docs-navigation.test.ts b/packages/website/src/plugin-docs-navigation.test.ts
index 93f0cf7736..a3e537620a 100644
--- a/packages/website/src/plugin-docs-navigation.test.ts
+++ b/packages/website/src/plugin-docs-navigation.test.ts
@@ -2,6 +2,25 @@ import { describe, expect, it } from "vitest";
 import { buildDocsNavTree, getDoc, getDocs, getLegacyDocsRedirect, parseHeadings } from "./docs";
 
 describe("plugin documentation", () => {
+  it.each(["en", "zh-CN"] as const)(
+    "nests local file copying under Git worktrees in %s",
+    (locale) => {
+      const workspaces = buildDocsNavTree(getDocs(locale)).find(
+        (node) => node.type === "category" && node.label === "Workspaces",
+      );
+      expect(workspaces).toMatchObject({
+        children: expect.arrayContaining([
+          expect.objectContaining({
+            type: "group",
+            href: "/docs/worktrees",
+            children: [expect.objectContaining({ href: "/docs/worktrees/worktreeinclude" })],
+          }),
+        ]),
+      });
+      expect(getDoc("worktrees/worktreeinclude", locale)).toBeDefined();
+    },
+  );
+
   it("groups current guides by task without version navigation", () => {
     const plugins = buildDocsNavTree(getDocs("en")).find(
       (node) => node.type === "category" && node.label === "Plugins",
diff --git a/packages/website/src/plugins/plugin-search.tsx b/packages/website/src/plugins/plugin-search.tsx
index 9279549918..da37d073aa 100644
--- a/packages/website/src/plugins/plugin-search.tsx
+++ b/packages/website/src/plugins/plugin-search.tsx
@@ -68,12 +68,16 @@ export function PluginSearch({
     input.current?.focus();
   }, [edit]);
   const handleSubmit = useCallback(
-    (event: FormEvent) => {
+    (event: FormEvent<HTMLFormElement>) => {
       event.preventDefault();
       // Live results already show the term.
-      if (!live) show(term, { replace: false });
+      if (!live) {
+        // Hydration can attach this handler before state adopts text already in the input.
+        const submittedTerm = String(new FormData(event.currentTarget).get("q") ?? "");
+        show(submittedTerm, { replace: false });
+      }
     },
-    [live, show, term],
+    [live, show],
   );
   return (
     <form
diff --git a/packages/website/src/routes/{-$locale}/changelog.tsx b/packages/website/src/routes/{-$locale}/changelog.tsx
index 5a71c51b24..54c9a2a127 100644
--- a/packages/website/src/routes/{-$locale}/changelog.tsx
+++ b/packages/website/src/routes/{-$locale}/changelog.tsx
@@ -41,14 +41,44 @@ function HeadingAnchor({ version }: { version: string }) {
   );
 }
 
+/**
+ * A release that has highlights shows only them; its sections, the full record, open on request.
+ * A release without highlights shows its sections, since nothing stands in for them.
+ */
+function ReleaseNotes({ release }: { release: ChangelogRelease }) {
+  const { t } = useTranslation();
+  if (!release.highlights) {
+    return <ReactMarkdown components={patchMarkdownComponents}>{release.sections}</ReactMarkdown>;
+  }
+  return (
+    <>
+      <ReactMarkdown components={patchMarkdownComponents}>{release.highlights}</ReactMarkdown>
+      {release.sections ? (
+        <details className="changelog-all-changes">
+          <summary className="changelog-all-changes-summary">
+            <span className="changelog-all-changes-show">{t("changelog.showAllChanges")}</span>
+            <span className="changelog-all-changes-hide">{t("changelog.hideAllChanges")}</span>
+          </summary>
+          <ReactMarkdown components={patchMarkdownComponents}>{release.sections}</ReactMarkdown>
+        </details>
+      ) : null}
+    </>
+  );
+}
+
 function PatchRelease({ release }: { release: ChangelogRelease }) {
   const { t } = useTranslation();
   const locale = useLocale();
   return (
-    <section className="changelog-patch">
+    <section
+      className="changelog-patch"
+      aria-labelledby={`${releaseAnchor(release.version)}-title`}
+    >
       <div id={releaseAnchor(release.version)} className="changelog-patch-heading">
         <HeadingAnchor version={release.version} />
-        <h3 className="changelog-patch-title">{release.version}</h3>
+        <h3 id={`${releaseAnchor(release.version)}-title`} className="changelog-patch-title">
+          {release.version}
+        </h3>
         <time dateTime={release.date} className="changelog-release-date">
           {formatDate(release.date, locale, "long")}
         </time>
@@ -58,7 +88,7 @@ function PatchRelease({ release }: { release: ChangelogRelease }) {
           contentLocale={release.locale}
           message={t("changelog.untranslatedRelease")}
         />
-        <ReactMarkdown components={patchMarkdownComponents}>{release.markdown}</ReactMarkdown>
+        <ReleaseNotes release={release} />
       </div>
     </section>
   );
diff --git a/packages/website/src/schedule-docs.test.ts b/packages/website/src/schedule-docs.test.ts
index 015d85fe6c..76fca93287 100644
--- a/packages/website/src/schedule-docs.test.ts
+++ b/packages/website/src/schedule-docs.test.ts
@@ -4,7 +4,7 @@ import { expect, it } from "vitest";
 
 const docsRoot = path.resolve(import.meta.dirname, "../../../public-docs");
 
-it.each(["schedules.md", "schedules-cli.md", "mcp.md", "worktrees.md"])(
+it.each(["schedules.md", "schedules-cli.md", "mcp.md", "worktrees/index.md"])(
   "%s makes schedule run retention discoverable",
   async (file) => {
     const markdown = await readFile(path.join(docsRoot, file), "utf8");
diff --git a/packages/website/src/styles.css b/packages/website/src/styles.css
index 815657b5e5..cadcce2b6d 100644
--- a/packages/website/src/styles.css
+++ b/packages/website/src/styles.css
@@ -277,6 +277,52 @@
   font-size: 0.875em;
 }
 
+.changelog-all-changes {
+  margin-top: 1rem;
+}
+
+.changelog-all-changes-summary {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  cursor: pointer;
+  list-style: none;
+  color: var(--color-muted-foreground);
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.changelog-all-changes-summary::-webkit-details-marker {
+  display: none;
+}
+
+.changelog-all-changes-summary::before {
+  content: "+";
+  color: rgba(255, 255, 255, 0.4);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+.changelog-all-changes-summary:hover {
+  color: var(--color-foreground);
+}
+
+.changelog-all-changes[open] > .changelog-all-changes-summary::before {
+  content: "−";
+}
+
+.changelog-all-changes[open] > .changelog-all-changes-summary {
+  margin-bottom: 1.25rem;
+}
+
+.changelog-all-changes-hide,
+.changelog-all-changes[open] .changelog-all-changes-show {
+  display: none;
+}
+
+.changelog-all-changes[open] .changelog-all-changes-hide {
+  display: inline;
+}
+
 /* Docs page prose styles — mirrors the original docs/*.tsx components */
 .docs-prose {
   color: rgba(255, 255, 255, 0.6);
diff --git a/packages/website/vite.config.ts b/packages/website/vite.config.ts
index 778378167b..fcdca7e610 100644
--- a/packages/website/vite.config.ts
+++ b/packages/website/vite.config.ts
@@ -129,7 +129,12 @@ export default defineConfig((): UserConfig => {
       },
     },
     plugins: [
-      cloudflare({ viteEnvironment: { name: "ssr" } }),
+      cloudflare({
+        viteEnvironment: { name: "ssr" },
+        ...(process.env.WEBSITE_E2E_PERSIST_PATH
+          ? { persistState: { path: process.env.WEBSITE_E2E_PERSIST_PATH } }
+          : {}),
+      }),
       tsConfigPaths({ projects: [path.join(__dirname, "tsconfig.json")] }),
       tanstackStart({
         router: {
diff --git a/patches/@gorhom+bottom-sheet+5.2.14.patch b/patches/@gorhom+bottom-sheet+5.2.14.patch
index e0af7b8dcb..13d7df0565 100644
--- a/patches/@gorhom+bottom-sheet+5.2.14.patch
+++ b/patches/@gorhom+bottom-sheet+5.2.14.patch
@@ -1,8 +1,18 @@
 diff --git a/node_modules/@gorhom/bottom-sheet/lib/commonjs/components/bottomSheetModal/BottomSheetModal.js b/node_modules/@gorhom/bottom-sheet/lib/commonjs/components/bottomSheetModal/BottomSheetModal.js
-index ee51e76..dc1bc17 100644
+index ee51e76..5fe8f75 100644
 --- a/node_modules/@gorhom/bottom-sheet/lib/commonjs/components/bottomSheetModal/BottomSheetModal.js
 +++ b/node_modules/@gorhom/bottom-sheet/lib/commonjs/components/bottomSheetModal/BottomSheetModal.js
-@@ -315,7 +315,9 @@ function BottomSheetModalComponent(props, ref) {
+@@ -272,6 +272,9 @@ function BottomSheetModalComponent(props, ref) {
+       });
+     }
+     if (statusRef.current === _constants.MODAL_STATUS.INITIAL) {
++      if (mountRef.current) {
++        unmount();
++      }
+       return;
+     }
+ 
+@@ -315,7 +318,9 @@ function BottomSheetModalComponent(props, ref) {
      }
      currentIndexRef.current = _index;
      nextIndexRef.current = null;
@@ -61,10 +71,20 @@ index e44ad86..96555ef 100644
  var _useGestureEventsHandlersDefault = require("./hooks/useGestureEventsHandlersDefault");
  var _useBottomSheetGestureHandlers = require("./hooks/useBottomSheetGestureHandlers");
 diff --git a/node_modules/@gorhom/bottom-sheet/lib/module/components/bottomSheetModal/BottomSheetModal.js b/node_modules/@gorhom/bottom-sheet/lib/module/components/bottomSheetModal/BottomSheetModal.js
-index 94fabdb..60ca66a 100644
+index 94fabdb..d870aa7 100644
 --- a/node_modules/@gorhom/bottom-sheet/lib/module/components/bottomSheetModal/BottomSheetModal.js
 +++ b/node_modules/@gorhom/bottom-sheet/lib/module/components/bottomSheetModal/BottomSheetModal.js
-@@ -308,7 +308,9 @@ function BottomSheetModalComponent(props, ref) {
+@@ -265,6 +265,9 @@ function BottomSheetModalComponent(props, ref) {
+       });
+     }
+     if (statusRef.current === MODAL_STATUS.INITIAL) {
++      if (mountRef.current) {
++        unmount();
++      }
+       return;
+     }
+ 
+@@ -308,7 +311,9 @@ function BottomSheetModalComponent(props, ref) {
      }
      currentIndexRef.current = _index;
      nextIndexRef.current = null;
@@ -122,10 +142,24 @@ index ffc6caa..550f1b3 100644
  export { useGestureEventsHandlersDefault } from './hooks/useGestureEventsHandlersDefault';
  export { useBottomSheetGestureHandlers } from './hooks/useBottomSheetGestureHandlers';
 diff --git a/node_modules/@gorhom/bottom-sheet/src/components/bottomSheetModal/BottomSheetModal.tsx b/node_modules/@gorhom/bottom-sheet/src/components/bottomSheetModal/BottomSheetModal.tsx
-index 2954b3f..7260656 100644
+index 2954b3f..936300b 100644
 --- a/node_modules/@gorhom/bottom-sheet/src/components/bottomSheetModal/BottomSheetModal.tsx
 +++ b/node_modules/@gorhom/bottom-sheet/src/components/bottomSheetModal/BottomSheetModal.tsx
-@@ -432,8 +432,15 @@ function BottomSheetModalComponent<T = never>(
+@@ -373,7 +373,13 @@ function BottomSheetModalComponent<T = never>(
+         });
+       }
+ 
++      // A modal that unmounts after presenting but before its first animation is still INITIAL;
++      // returning would leave its portal on the host, sliding open with nothing to close it.
++      // An INITIAL status with nothing mounted is this callback running after `unmount()`.
+       if (statusRef.current === MODAL_STATUS.INITIAL) {
++        if (mountRef.current) {
++          unmount();
++        }
+         return;
+       }
+ 
+@@ -432,8 +438,15 @@ function BottomSheetModalComponent<T = never>(
        currentIndexRef.current = _index;
        nextIndexRef.current = null;
  
diff --git a/patches/@legendapp+list+3.7.1.patch b/patches/@legendapp+list+3.7.1.patch
new file mode 100644
index 0000000000..936589394f
--- /dev/null
+++ b/patches/@legendapp+list+3.7.1.patch
@@ -0,0 +1,637 @@
+# LegendList 3.7.1 for the native chat timeline (docs/agent-stream-disclosure.md).
+# Upstream: https://github.com/LegendApp/legend-list/issues/593 covers every change below.
+# react-native.js and react-native.mjs carry the same hunks; each has a "Paseo patch" comment.
+#
+# 1. getEstimatedItemSize (react-native.d.ts, getItemSize, LegendListInner props): a per-item
+#    estimate for an unmeasured row wins over the running average for its type.
+# 2. MVCP anchor lock on native (canRestoreAnchorLock, resolveAnchorLock, updateAnchorLock,
+#    prepareMVCP): upstream enables it on web only. On native the lock ends when its row leaves
+#    the view or shouldRestorePosition rejects it, instead of after 300 ms.
+# 3. Preserved initial end only with maintainScrollAtEnd (finishScrollTo,
+#    finishBootstrapInitialScrollWithoutScroll): otherwise every data change re-arms the initial
+#    scroll to the end.
+# 4. Silent initial scroll retry in one task (checkFinishedScrollFallback): the nudge and the return
+#    to the target go out together, so Android does not reveal 1 dp short of the end.
+# 5. Layout noise against the floored known size (isNativeLayoutNoise, updateOneItemSize): a
+#    one-pixel snap change is not a resize.
+# 6. Content height from React state on the New Architecture (useContentSize, ContainersLayer):
+#    the Animated height mounts the estimated layout for a frame.
+# 7. Header and footer revealed with the rows (RevealedLayoutView, ListComponent).
+# 8. Top-padding shrink hold on iOS only (setPaddingTop): Android paints the held height as blank
+#    space at the end.
+# 9. Rows cut off at the top count as in view, and so does the row just past the end of the
+#    viewport (getIdsInVisibleRange): they follow the fully visible rows in idsInView, so a
+#    disclosure hold on a row whose top is above the viewport still anchors on that row instead
+#    of the row below it, and a hold on the row below a bottom-edge trigger anchors even when
+#    that row starts below the viewport.
+# 10. A size change keeps only a row shouldRestorePosition accepts in place (prepareMVCP), as a
+#    data change already does, so a disclosure that only grows (a todo card) holds the cut-off
+#    row instead of the first row in view.
+# 11. A 0 x 0 measurement is not a size (updateItemSizesBatch): rows of a hidden retained tab
+#    (display: none) still render and measure 0 x 0. Recording it collapsed the row, and a row
+#    whose frame was unchanged when the tab showed again got no layout event to correct it.
+# 12. No Android clamp prediction for a size change (prepareMVCP): upstream measures the adjustment
+#    of a shrink past the end from the new end, assuming the scroll view clamped first. The app's
+#    scroll view clamps after the adjustment on both platforms (modules/paseo-scroll), so a
+#    bottom-edge disclosure collapsing near the end landed at the end instead of in place.
+#
+# Upgrading: drop each hunk whose fix the new version ships, regenerate with
+# `npx patch-package @legendapp/list`, and copy this header back on top.
+diff --git a/node_modules/@legendapp/list/react-native.d.ts b/node_modules/@legendapp/list/react-native.d.ts
+index 983e937..970ba51 100644
+--- a/node_modules/@legendapp/list/react-native.d.ts
++++ b/node_modules/@legendapp/list/react-native.d.ts
+@@ -204,6 +204,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
+      * Change extraData when the fixed sizes returned by this callback change.
+      */
+     getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
++    /**
++     * Paseo patch: estimated size of an item that has not been measured yet. Return undefined to
++     * fall back to the average size for its type.
++     */
++    getEstimatedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
+     /**
+      * Returns a stable item type used for pooling and size estimation.
+      */
+diff --git a/node_modules/@legendapp/list/react-native.js b/node_modules/@legendapp/list/react-native.js
+index eeb3fb0..5ebd8e9 100644
+--- a/node_modules/@legendapp/list/react-native.js
++++ b/node_modules/@legendapp/list/react-native.js
+@@ -1497,7 +1497,15 @@ function getItemSize(ctx, key, index, data, useAverageSize, preferCachedSize, no
+     return renderedSize;
+   }
+   const itemType = (_b = resolved == null ? void 0 : resolved.itemType) != null ? _b : getItemType ? (_a3 = getItemType(data, index)) != null ? _a3 : "" : "";
+-  if (useAverageSize && !scrollingTo) {
++  // Paseo patch: a caller estimate for an unmeasured item wins over the running average for its
++  // type, so a row new to the list can be laid out near its real size before it is measured.
++  if (state.props.getEstimatedItemSize) {
++    const estimate = state.props.getEstimatedItemSize(data, index, itemType);
++    if (estimate !== void 0) {
++      size = estimate + ctx.scrollAxisGap;
++    }
++  }
++  if (size === void 0 && useAverageSize && !scrollingTo) {
+     const averageSizeForType = (_c = averageSizes[itemType]) == null ? void 0 : _c.avg;
+     if (averageSizeForType !== void 0) {
+       size = roundSize(averageSizeForType);
+@@ -1570,6 +1578,12 @@ var MVCP_POSITION_EPSILON = 0.1;
+ var MVCP_ANCHOR_LOCK_TTL_MS = 300;
+ var MVCP_ANCHOR_LOCK_QUIET_PASSES_TO_RELEASE = 2;
+ var NATIVE_END_CLAMP_EPSILON = 1;
++function canRestoreAnchorLock(state, id) {
++  const shouldRestorePosition = state.props.maintainVisibleContentPosition.shouldRestorePosition;
++  const index = state.indexByKey.get(id);
++  const data = state.props.data;
++  return !shouldRestorePosition || index !== void 0 && data[index] !== void 0 && shouldRestorePosition(data[index], index, data);
++}
+ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!enableMVCPAnchorLock) {
+     state.mvcpAnchorLock = void 0;
+@@ -1579,7 +1593,13 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!lock) {
+     return void 0;
+   }
+-  const isExpired = now > lock.expiresAt;
++  // Paseo patch: native keeps the anchor of a data change through the size passes that follow, as
++  // web does. Upstream limits the lock to web (d24a9d93 "feat: (web) add MVCP anchor lock") without a
++  // native reason. Without it, the pass that applies the measured sizes of prepended rows re-anchors
++  // on the first row in view, which can be one of those rows, and its growth moves the rows below.
++  // A wall-clock expiry is wrong on native, where the measurements arrive after the native mount
++  // and a slow render; the lock ends when its row leaves the view or may not be restored instead.
++  const isExpired = Platform.OS === "web" ? now > lock.expiresAt : !state.idsInView.includes(lock.id) || !canRestoreAnchorLock(state, lock.id);
+   const isMissing = state.indexByKey.get(lock.id) === void 0;
+   if (isExpired || isMissing || !mvcpData) {
+     state.mvcpAnchorLock = void 0;
+@@ -1588,7 +1608,7 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   return lock;
+ }
+ function updateAnchorLock(state, params) {
+-  if (Platform.OS === "web") {
++  {
+     const { anchorId, anchorPosition, dataChanged, now, positionDiff } = params;
+     const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+     const mvcpData = state.props.maintainVisibleContentPosition.data;
+@@ -1713,7 +1733,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+   } = props;
+   const isWeb = Platform.OS === "web";
+   const now = Date.now();
+-  const enableMVCPAnchorLock = isWeb && (!!dataChanged || !!state.mvcpAnchorLock);
++  const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+   const scrollingTo = state.scrollingTo;
+   if ((scrollingTo == null ? void 0 : scrollingTo.key) !== void 0) {
+     const nextIndex = state.indexByKey.get(scrollingTo.key);
+@@ -1723,7 +1743,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+     state.mvcpAnchorLock = void 0;
+     return void 0;
+   }
+-  const anchorLock = isWeb ? resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) : void 0;
++  const anchorLock = resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now);
+   let prevPosition;
+   let targetId;
+   const idsInViewWithPositions = [];
+@@ -1755,7 +1775,10 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+       }
+       targetId = (_b = scrollingTo == null ? void 0 : scrollingTo.key) != null ? _b : getId(state, scrollTarget);
+     } else if (idsInView.length > 0 && state.didContainersLayout && !dataChanged) {
+-      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0);
++      // Paseo patch: a size change keeps only a row shouldRestorePosition accepts in place, as a data
++      // change does. Upstream keeps the first row in view, so a disclosure hold on a row cut off at
++      // the top kept the row below it instead and moved the trigger by the row's size change.
++      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0 && canRestoreAnchorLock(state, id));
+     }
+     if (dataChanged && idsInView.length > 0 && state.didContainersLayout) {
+       for (let i = 0; i < idsInView.length; i++) {
+@@ -1874,15 +1897,11 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+         now,
+         positionDiff
+       });
+-      if (Platform.OS === "android" && !dataChanged && scrollTarget === void 0) {
+-        const maxScroll = getScrollRangeEnd(ctx);
+-        if (state.scroll > maxScroll + MVCP_POSITION_EPSILON) {
+-          const targetScroll = Math.max(0, Math.min(state.scroll + positionDiff, maxScroll));
+-          state.scroll = maxScroll;
+-          state.scrollPending = maxScroll;
+-          positionDiff = targetScroll - maxScroll;
+-        }
+-      }
++      // Paseo patch: no Android clamp prediction. Upstream assumes the scroll view clamped to the new
++      // end before React Native adds the anchor's movement, and measures the adjustment from that
++      // end. The app's scroll view defers the clamp until after the adjustment, as iOS does
++      // (modules/paseo-scroll), so an adjustment measured from the end moved a shrinking row's
++      // anchor back to the end instead of keeping it in place.
+       if (shouldQueueNativeMVCPAdjust(dataChanged, state, positionDiff, prevTotalSize, prevScroll, scrollTarget)) {
+         state.pendingNativeMVCPAdjust = {
+           amount: positionDiff,
+@@ -2371,7 +2390,10 @@ function finishScrollTo(ctx) {
+     };
+     if (scrollingTo.isInitialScroll || state.initialScroll) {
+       const isOffsetSession = ((_b = state.initialScrollSession) == null ? void 0 : _b.kind) === "offset";
+-      const shouldPreserveResizeTarget = !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
++      // Paseo patch: only a list that keeps its end keeps landing on the initial end after the
++      // initial scroll. Without maintainScrollAtEnd, the preserved target re-arms the initial scroll
++      // on every data change, footer layout and viewport resize, and a stream never lets it clear.
++      const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
+       finishInitialScroll(ctx, {
+         onFinished: complete,
+         preserveTarget: isOffsetSession && state.props.data.length === 0 || shouldPreserveResizeTarget,
+@@ -2515,11 +2537,12 @@ function checkFinishedScrollFallback(ctx) {
+         const targetOffset = (_d = (_c = (_b = initialScrollWatchdog.get(state)) == null ? void 0 : _b.targetOffset) != null ? _c : isStillScrollingTo.targetOffset) != null ? _d : 0;
+         const jiggleOffset = targetOffset >= SILENT_INITIAL_SCROLL_TARGET_EPSILON ? targetOffset - SILENT_INITIAL_SCROLL_TARGET_EPSILON : targetOffset + SILENT_INITIAL_SCROLL_TARGET_EPSILON;
+         initialScrollCompletion.markSilentInitialScrollRetry(state);
++        // Paseo patch: send the nudge and the return to the target in one task, so native applies both before
++        // it draws and the pair still emits the scroll event this retry exists for. Upstream returns on the next
++        // frame, but the 16 ms check below can run first, finish the scroll and cancel that frame; the list then
++        // revealed 1 dp short of its end and moved into place a frame later.
+         scrollToFallbackOffset(ctx, jiggleOffset);
+-        state.scheduledWork.frame(
+-          () => scrollToFallbackOffset(ctx, targetOffset),
+-          "checkFinishedScrollRetryFrame"
+-        );
++        scrollToFallbackOffset(ctx, targetOffset);
+         scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
+       } else if (shouldRetryUnalignedEndScroll) {
+         scrollToFallbackOffset(ctx, completionState.clampedTargetOffset, !!isStillScrollingTo.animated);
+@@ -3378,7 +3401,8 @@ function finishBootstrapInitialScrollWithoutScroll(ctx, resolvedOffset) {
+   var _a3;
+   const state = ctx.state;
+   clearBootstrapInitialScrollSession(state);
+-  const shouldPreserveResizeTarget = !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
++  // Paseo patch: see finishScrollTo; only a list that keeps its end preserves the initial end.
++  const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
+   finishInitialScroll(ctx, {
+     preserveTarget: shouldPreserveResizeTarget,
+     recalculateItems: true,
+@@ -4569,6 +4593,24 @@ function getIdsInVisibleRange(state, range) {
+       const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
+       idsInView.push(id);
+     }
++    // Paseo patch: a row whose top is above the viewport is still in view. Upstream starts the ids at
++    // the first fully visible row, so a disclosure hold on a row cut off at the top finds no anchor
++    // (shouldRestorePosition rejects every other row) and the next size pass keeps the row below it
++    // in place instead. The partly visible rows go last, so the first fully visible row stays the
++    // anchor of every pass that does not restrict it.
++    if (range.startNoBuffer !== null && range.startNoBuffer < firstVisibleAnchorIndex) {
++      for (let i = range.startNoBuffer; i < firstVisibleAnchorIndex; i++) {
++        const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
++        idsInView.push(id);
++      }
++    }
++    // Paseo patch: the row that starts at or below the end of the viewport goes last. A disclosure
++    // whose trigger sits on the bottom edge of its row holds the row below it, whose top is that
++    // edge, and that row is below the viewport whenever the held row's bottom is.
++    const belowIndex = range.endNoBuffer + 1;
++    if (belowIndex < state.props.data.length) {
++      idsInView.push((_b = state.idCache[belowIndex]) != null ? _b : getId(state, belowIndex));
++    }
+   }
+   return idsInView;
+ }
+@@ -5176,8 +5218,13 @@ var NATIVE_LAYOUT_MEASUREMENT_EPSILON = 1 / PixelRatio.get() + FLOATING_POINT_SL
+ function isWithinEpsilon(delta) {
+   return Math.abs(delta) <= NATIVE_LAYOUT_MEASUREMENT_EPSILON;
+ }
+-function isNativeLayoutNoise(delta) {
+-  return isWithinEpsilon(delta);
++// Paseo patch: sizesKnown holds roundSize values, floored to 1/8 dp, so the raw size behind a known
++// size lies in [known, known + 1/8). Upstream compares the raw size with the floored one, so a row
++// whose pixel-snapped height changes by one pixel, plus the floor, reads as a resize. On a cold open
++// that late resize moved every row a frame after the reveal.
++function isNativeLayoutNoise(rawSize, knownSize) {
++  const delta = rawSize - knownSize;
++  return delta >= -NATIVE_LAYOUT_MEASUREMENT_EPSILON && delta < NATIVE_LAYOUT_MEASUREMENT_EPSILON + 1 / 8;
+ }
+ 
+ // src/core/updateItemSizes.ts
+@@ -5291,6 +5338,11 @@ function updateItemSizesBatch(ctx, measurements) {
+   const result = {};
+   const previousTotalSize = state.totalSize;
+   for (const measurement of measurements) {
++    // Paseo patch: a view inside a display: none ancestor measures 0 x 0. That is no measurement: a
++    // laid-out row is as wide as the list even when it has no height. Recording 0 there collapsed
++    // the row, and when the list showed again a row whose frame had not changed got no layout event
++    // to correct it, so the next row overlapped it.
++    if (measurement.size.width === 0 && measurement.size.height === 0) continue;
+     const ownsMeasuredItem = measurement.containerId === void 0 || isContainerItemCurrent(ctx, measurement.containerId, measurement.itemKey);
+     if (ownsMeasuredItem) {
+       const index = state.indexByKey.get(measurement.itemKey);
+@@ -5414,7 +5466,7 @@ function updateOneItemSize(ctx, itemKey, sizeObj, resolvedMeasurementItem, notif
+     state.fixedItemSizeKeys.add(itemKey);
+   }
+   const prevSizeKnown = sizesKnown.get(itemKey);
+-  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize - prevSizeKnown)) {
++  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize, prevSizeKnown)) {
+     return 0;
+   }
+   const size = Platform.OS === "web" ? Math.round(rawSize) : roundSize(rawSize);
+@@ -6283,6 +6335,10 @@ function useFreshDataTransitionVisibility(readyToRender, transitionEpoch) {
+ 
+ // src/components/Containers.native.tsx
+ var useCommittedMinSize = IsNewArchitecture ? () => useArr$(["totalSize"])[0] : () => void 0;
++// Paseo patch: on the new architecture the content height comes from React state only. The
++// JS-driven Animated height writes through setNativeProps, which Fabric commits synchronously
++// mid-task, mounting React's estimated layout for a frame before the measured one.
++var useContentSize = IsNewArchitecture ? useCommittedMinSize : () => useValue$("totalSize");
+ var ContainersLayer = typedMemo(function ContainersLayer2({
+   children,
+   freshDataTransitionEpoch,
+@@ -6290,7 +6346,7 @@ var ContainersLayer = typedMemo(function ContainersLayer2({
+ }) {
+   const ctx = useStateContext();
+   const columnWrapperStyle = ctx.columnWrapperStyle;
+-  const size = useValue$("totalSize");
++  const size = useContentSize();
+   const minSize = useCommittedMinSize();
+   const [readyToRender, numColumns, otherAxisSize = 0] = useArr$(["readyToRender", "numColumns", "otherAxisSize"]);
+   const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
+@@ -6513,6 +6569,14 @@ var AlignItemsAtEndSpacer = typedMemo(function AlignItemsAtEndSpacer2({ horizont
+     null
+   );
+ });
++// Paseo patch: the header and footer reveal with the rows. Upstream hides only the containers until
++// readyToRender, so a cold open paints the header and footer at their estimated place a frame or more
++// before the rows appear around them.
++var RevealedLayoutView = function RevealedLayoutView2({ freshDataTransitionEpoch, style, ...rest }) {
++  const [readyToRender] = useArr$(["readyToRender"]);
++  const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
++  return /* @__PURE__ */ React2__namespace.createElement(LayoutView, { ...rest, pointerEvents: isVisible ? "auto" : "none", style: isVisible ? style : [style, { opacity: 0 }] });
++};
+ var ListComponent = typedMemo(function ListComponent2({
+   canRender,
+   freshDataTransitionEpoch,
+@@ -6651,7 +6715,7 @@ var ListComponent = typedMemo(function ListComponent2({
+       style: autoOtherAxisStyle ? [autoOtherAxisStyle, style] : style
+     },
+     /* @__PURE__ */ React2__namespace.createElement(ScrollAdjust, null),
+-    ListHeaderComponent && /* @__PURE__ */ React2__namespace.createElement(LayoutView, { onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
++    ListHeaderComponent && /* @__PURE__ */ React2__namespace.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
+     ListEmptyComponent && getComponent(ListEmptyComponent),
+     shouldRenderAlignItemsAtEndSpacer && /* @__PURE__ */ React2__namespace.createElement(AlignItemsAtEndSpacer, { horizontal }),
+     canRender && !ListEmptyComponent && /* @__PURE__ */ React2__namespace.createElement(
+@@ -6665,7 +6729,7 @@ var ListComponent = typedMemo(function ListComponent2({
+         stickyHeaderConfig
+       }
+     ),
+-    ListFooterComponent && /* @__PURE__ */ React2__namespace.createElement(LayoutView, { onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
++    ListFooterComponent && /* @__PURE__ */ React2__namespace.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
+     IS_DEV && ENABLE_DEVMODE
+   );
+ });
+@@ -7886,7 +7950,10 @@ function setPaddingTop(ctx, { stylePaddingTop }) {
+   const state = ctx.state;
+   if (stylePaddingTop !== void 0) {
+     const prevStylePaddingTop = peek$(ctx, "stylePaddingTop") || 0;
+-    if (stylePaddingTop < prevStylePaddingTop) {
++    // Paseo patch: only iOS compensates a shrinking top padding with a scroll adjust, which this
++    // keeps the native clamp from doubling. Elsewhere the held height paints as blank space at the
++    // end until the timer fires, and a scroll view that keeps its end scrolls into it.
++    if (stylePaddingTop < prevStylePaddingTop && Platform.OS === "ios") {
+       let prevTotalSize = peek$(ctx, "totalSize") || 0;
+       set$(ctx, "totalSize", prevTotalSize + prevStylePaddingTop);
+       state.timeoutSetPaddingTop = setTimeout(() => {
+@@ -7989,6 +8056,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8282,6 +8350,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     dataVersion,
+     drawDistance,
+     estimatedItemSize,
++    getEstimatedItemSize: useWrapIfItem(getEstimatedItemSize),
+     getFixedItemSize: useWrapIfItem(getFixedItemSize),
+     getItemType: useWrapIfItem(getItemType),
+     hasExternalScroll,
+diff --git a/node_modules/@legendapp/list/react-native.mjs b/node_modules/@legendapp/list/react-native.mjs
+index fe5f415..9788ce6 100644
+--- a/node_modules/@legendapp/list/react-native.mjs
++++ b/node_modules/@legendapp/list/react-native.mjs
+@@ -1476,7 +1476,15 @@ function getItemSize(ctx, key, index, data, useAverageSize, preferCachedSize, no
+     return renderedSize;
+   }
+   const itemType = (_b = resolved == null ? void 0 : resolved.itemType) != null ? _b : getItemType ? (_a3 = getItemType(data, index)) != null ? _a3 : "" : "";
+-  if (useAverageSize && !scrollingTo) {
++  // Paseo patch: a caller estimate for an unmeasured item wins over the running average for its
++  // type, so a row new to the list can be laid out near its real size before it is measured.
++  if (state.props.getEstimatedItemSize) {
++    const estimate = state.props.getEstimatedItemSize(data, index, itemType);
++    if (estimate !== void 0) {
++      size = estimate + ctx.scrollAxisGap;
++    }
++  }
++  if (size === void 0 && useAverageSize && !scrollingTo) {
+     const averageSizeForType = (_c = averageSizes[itemType]) == null ? void 0 : _c.avg;
+     if (averageSizeForType !== void 0) {
+       size = roundSize(averageSizeForType);
+@@ -1549,6 +1557,12 @@ var MVCP_POSITION_EPSILON = 0.1;
+ var MVCP_ANCHOR_LOCK_TTL_MS = 300;
+ var MVCP_ANCHOR_LOCK_QUIET_PASSES_TO_RELEASE = 2;
+ var NATIVE_END_CLAMP_EPSILON = 1;
++function canRestoreAnchorLock(state, id) {
++  const shouldRestorePosition = state.props.maintainVisibleContentPosition.shouldRestorePosition;
++  const index = state.indexByKey.get(id);
++  const data = state.props.data;
++  return !shouldRestorePosition || index !== void 0 && data[index] !== void 0 && shouldRestorePosition(data[index], index, data);
++}
+ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!enableMVCPAnchorLock) {
+     state.mvcpAnchorLock = void 0;
+@@ -1558,7 +1572,13 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!lock) {
+     return void 0;
+   }
+-  const isExpired = now > lock.expiresAt;
++  // Paseo patch: native keeps the anchor of a data change through the size passes that follow, as
++  // web does. Upstream limits the lock to web (d24a9d93 "feat: (web) add MVCP anchor lock") without a
++  // native reason. Without it, the pass that applies the measured sizes of prepended rows re-anchors
++  // on the first row in view, which can be one of those rows, and its growth moves the rows below.
++  // A wall-clock expiry is wrong on native, where the measurements arrive after the native mount
++  // and a slow render; the lock ends when its row leaves the view or may not be restored instead.
++  const isExpired = Platform.OS === "web" ? now > lock.expiresAt : !state.idsInView.includes(lock.id) || !canRestoreAnchorLock(state, lock.id);
+   const isMissing = state.indexByKey.get(lock.id) === void 0;
+   if (isExpired || isMissing || !mvcpData) {
+     state.mvcpAnchorLock = void 0;
+@@ -1567,7 +1587,7 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   return lock;
+ }
+ function updateAnchorLock(state, params) {
+-  if (Platform.OS === "web") {
++  {
+     const { anchorId, anchorPosition, dataChanged, now, positionDiff } = params;
+     const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+     const mvcpData = state.props.maintainVisibleContentPosition.data;
+@@ -1692,7 +1712,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+   } = props;
+   const isWeb = Platform.OS === "web";
+   const now = Date.now();
+-  const enableMVCPAnchorLock = isWeb && (!!dataChanged || !!state.mvcpAnchorLock);
++  const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+   const scrollingTo = state.scrollingTo;
+   if ((scrollingTo == null ? void 0 : scrollingTo.key) !== void 0) {
+     const nextIndex = state.indexByKey.get(scrollingTo.key);
+@@ -1702,7 +1722,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+     state.mvcpAnchorLock = void 0;
+     return void 0;
+   }
+-  const anchorLock = isWeb ? resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) : void 0;
++  const anchorLock = resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now);
+   let prevPosition;
+   let targetId;
+   const idsInViewWithPositions = [];
+@@ -1734,7 +1754,10 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+       }
+       targetId = (_b = scrollingTo == null ? void 0 : scrollingTo.key) != null ? _b : getId(state, scrollTarget);
+     } else if (idsInView.length > 0 && state.didContainersLayout && !dataChanged) {
+-      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0);
++      // Paseo patch: a size change keeps only a row shouldRestorePosition accepts in place, as a data
++      // change does. Upstream keeps the first row in view, so a disclosure hold on a row cut off at
++      // the top kept the row below it instead and moved the trigger by the row's size change.
++      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0 && canRestoreAnchorLock(state, id));
+     }
+     if (dataChanged && idsInView.length > 0 && state.didContainersLayout) {
+       for (let i = 0; i < idsInView.length; i++) {
+@@ -1853,15 +1876,11 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+         now,
+         positionDiff
+       });
+-      if (Platform.OS === "android" && !dataChanged && scrollTarget === void 0) {
+-        const maxScroll = getScrollRangeEnd(ctx);
+-        if (state.scroll > maxScroll + MVCP_POSITION_EPSILON) {
+-          const targetScroll = Math.max(0, Math.min(state.scroll + positionDiff, maxScroll));
+-          state.scroll = maxScroll;
+-          state.scrollPending = maxScroll;
+-          positionDiff = targetScroll - maxScroll;
+-        }
+-      }
++      // Paseo patch: no Android clamp prediction. Upstream assumes the scroll view clamped to the new
++      // end before React Native adds the anchor's movement, and measures the adjustment from that
++      // end. The app's scroll view defers the clamp until after the adjustment, as iOS does
++      // (modules/paseo-scroll), so an adjustment measured from the end moved a shrinking row's
++      // anchor back to the end instead of keeping it in place.
+       if (shouldQueueNativeMVCPAdjust(dataChanged, state, positionDiff, prevTotalSize, prevScroll, scrollTarget)) {
+         state.pendingNativeMVCPAdjust = {
+           amount: positionDiff,
+@@ -2350,7 +2369,10 @@ function finishScrollTo(ctx) {
+     };
+     if (scrollingTo.isInitialScroll || state.initialScroll) {
+       const isOffsetSession = ((_b = state.initialScrollSession) == null ? void 0 : _b.kind) === "offset";
+-      const shouldPreserveResizeTarget = !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
++      // Paseo patch: only a list that keeps its end keeps landing on the initial end after the
++      // initial scroll. Without maintainScrollAtEnd, the preserved target re-arms the initial scroll
++      // on every data change, footer layout and viewport resize, and a stream never lets it clear.
++      const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
+       finishInitialScroll(ctx, {
+         onFinished: complete,
+         preserveTarget: isOffsetSession && state.props.data.length === 0 || shouldPreserveResizeTarget,
+@@ -2494,11 +2516,12 @@ function checkFinishedScrollFallback(ctx) {
+         const targetOffset = (_d = (_c = (_b = initialScrollWatchdog.get(state)) == null ? void 0 : _b.targetOffset) != null ? _c : isStillScrollingTo.targetOffset) != null ? _d : 0;
+         const jiggleOffset = targetOffset >= SILENT_INITIAL_SCROLL_TARGET_EPSILON ? targetOffset - SILENT_INITIAL_SCROLL_TARGET_EPSILON : targetOffset + SILENT_INITIAL_SCROLL_TARGET_EPSILON;
+         initialScrollCompletion.markSilentInitialScrollRetry(state);
++        // Paseo patch: send the nudge and the return to the target in one task, so native applies both before
++        // it draws and the pair still emits the scroll event this retry exists for. Upstream returns on the next
++        // frame, but the 16 ms check below can run first, finish the scroll and cancel that frame; the list then
++        // revealed 1 dp short of its end and moved into place a frame later.
+         scrollToFallbackOffset(ctx, jiggleOffset);
+-        state.scheduledWork.frame(
+-          () => scrollToFallbackOffset(ctx, targetOffset),
+-          "checkFinishedScrollRetryFrame"
+-        );
++        scrollToFallbackOffset(ctx, targetOffset);
+         scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
+       } else if (shouldRetryUnalignedEndScroll) {
+         scrollToFallbackOffset(ctx, completionState.clampedTargetOffset, !!isStillScrollingTo.animated);
+@@ -3357,7 +3380,8 @@ function finishBootstrapInitialScrollWithoutScroll(ctx, resolvedOffset) {
+   var _a3;
+   const state = ctx.state;
+   clearBootstrapInitialScrollSession(state);
+-  const shouldPreserveResizeTarget = !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
++  // Paseo patch: see finishScrollTo; only a list that keeps its end preserves the initial end.
++  const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
+   finishInitialScroll(ctx, {
+     preserveTarget: shouldPreserveResizeTarget,
+     recalculateItems: true,
+@@ -4548,6 +4572,24 @@ function getIdsInVisibleRange(state, range) {
+       const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
+       idsInView.push(id);
+     }
++    // Paseo patch: a row whose top is above the viewport is still in view. Upstream starts the ids at
++    // the first fully visible row, so a disclosure hold on a row cut off at the top finds no anchor
++    // (shouldRestorePosition rejects every other row) and the next size pass keeps the row below it
++    // in place instead. The partly visible rows go last, so the first fully visible row stays the
++    // anchor of every pass that does not restrict it.
++    if (range.startNoBuffer !== null && range.startNoBuffer < firstVisibleAnchorIndex) {
++      for (let i = range.startNoBuffer; i < firstVisibleAnchorIndex; i++) {
++        const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
++        idsInView.push(id);
++      }
++    }
++    // Paseo patch: the row that starts at or below the end of the viewport goes last. A disclosure
++    // whose trigger sits on the bottom edge of its row holds the row below it, whose top is that
++    // edge, and that row is below the viewport whenever the held row's bottom is.
++    const belowIndex = range.endNoBuffer + 1;
++    if (belowIndex < state.props.data.length) {
++      idsInView.push((_b = state.idCache[belowIndex]) != null ? _b : getId(state, belowIndex));
++    }
+   }
+   return idsInView;
+ }
+@@ -5155,8 +5197,13 @@ var NATIVE_LAYOUT_MEASUREMENT_EPSILON = 1 / PixelRatio.get() + FLOATING_POINT_SL
+ function isWithinEpsilon(delta) {
+   return Math.abs(delta) <= NATIVE_LAYOUT_MEASUREMENT_EPSILON;
+ }
+-function isNativeLayoutNoise(delta) {
+-  return isWithinEpsilon(delta);
++// Paseo patch: sizesKnown holds roundSize values, floored to 1/8 dp, so the raw size behind a known
++// size lies in [known, known + 1/8). Upstream compares the raw size with the floored one, so a row
++// whose pixel-snapped height changes by one pixel, plus the floor, reads as a resize. On a cold open
++// that late resize moved every row a frame after the reveal.
++function isNativeLayoutNoise(rawSize, knownSize) {
++  const delta = rawSize - knownSize;
++  return delta >= -NATIVE_LAYOUT_MEASUREMENT_EPSILON && delta < NATIVE_LAYOUT_MEASUREMENT_EPSILON + 1 / 8;
+ }
+ 
+ // src/core/updateItemSizes.ts
+@@ -5270,6 +5317,11 @@ function updateItemSizesBatch(ctx, measurements) {
+   const result = {};
+   const previousTotalSize = state.totalSize;
+   for (const measurement of measurements) {
++    // Paseo patch: a view inside a display: none ancestor measures 0 x 0. That is no measurement: a
++    // laid-out row is as wide as the list even when it has no height. Recording 0 there collapsed
++    // the row, and when the list showed again a row whose frame had not changed got no layout event
++    // to correct it, so the next row overlapped it.
++    if (measurement.size.width === 0 && measurement.size.height === 0) continue;
+     const ownsMeasuredItem = measurement.containerId === void 0 || isContainerItemCurrent(ctx, measurement.containerId, measurement.itemKey);
+     if (ownsMeasuredItem) {
+       const index = state.indexByKey.get(measurement.itemKey);
+@@ -5393,7 +5445,7 @@ function updateOneItemSize(ctx, itemKey, sizeObj, resolvedMeasurementItem, notif
+     state.fixedItemSizeKeys.add(itemKey);
+   }
+   const prevSizeKnown = sizesKnown.get(itemKey);
+-  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize - prevSizeKnown)) {
++  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize, prevSizeKnown)) {
+     return 0;
+   }
+   const size = Platform.OS === "web" ? Math.round(rawSize) : roundSize(rawSize);
+@@ -6262,6 +6314,10 @@ function useFreshDataTransitionVisibility(readyToRender, transitionEpoch) {
+ 
+ // src/components/Containers.native.tsx
+ var useCommittedMinSize = IsNewArchitecture ? () => useArr$(["totalSize"])[0] : () => void 0;
++// Paseo patch: on the new architecture the content height comes from React state only. The
++// JS-driven Animated height writes through setNativeProps, which Fabric commits synchronously
++// mid-task, mounting React's estimated layout for a frame before the measured one.
++var useContentSize = IsNewArchitecture ? useCommittedMinSize : () => useValue$("totalSize");
+ var ContainersLayer = typedMemo(function ContainersLayer2({
+   children,
+   freshDataTransitionEpoch,
+@@ -6269,7 +6325,7 @@ var ContainersLayer = typedMemo(function ContainersLayer2({
+ }) {
+   const ctx = useStateContext();
+   const columnWrapperStyle = ctx.columnWrapperStyle;
+-  const size = useValue$("totalSize");
++  const size = useContentSize();
+   const minSize = useCommittedMinSize();
+   const [readyToRender, numColumns, otherAxisSize = 0] = useArr$(["readyToRender", "numColumns", "otherAxisSize"]);
+   const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
+@@ -6492,6 +6548,14 @@ var AlignItemsAtEndSpacer = typedMemo(function AlignItemsAtEndSpacer2({ horizont
+     null
+   );
+ });
++// Paseo patch: the header and footer reveal with the rows. Upstream hides only the containers until
++// readyToRender, so a cold open paints the header and footer at their estimated place a frame or more
++// before the rows appear around them.
++var RevealedLayoutView = function RevealedLayoutView2({ freshDataTransitionEpoch, style, ...rest }) {
++  const [readyToRender] = useArr$(["readyToRender"]);
++  const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
++  return /* @__PURE__ */ React2.createElement(LayoutView, { ...rest, pointerEvents: isVisible ? "auto" : "none", style: isVisible ? style : [style, { opacity: 0 }] });
++};
+ var ListComponent = typedMemo(function ListComponent2({
+   canRender,
+   freshDataTransitionEpoch,
+@@ -6630,7 +6694,7 @@ var ListComponent = typedMemo(function ListComponent2({
+       style: autoOtherAxisStyle ? [autoOtherAxisStyle, style] : style
+     },
+     /* @__PURE__ */ React2.createElement(ScrollAdjust, null),
+-    ListHeaderComponent && /* @__PURE__ */ React2.createElement(LayoutView, { onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
++    ListHeaderComponent && /* @__PURE__ */ React2.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
+     ListEmptyComponent && getComponent(ListEmptyComponent),
+     shouldRenderAlignItemsAtEndSpacer && /* @__PURE__ */ React2.createElement(AlignItemsAtEndSpacer, { horizontal }),
+     canRender && !ListEmptyComponent && /* @__PURE__ */ React2.createElement(
+@@ -6644,7 +6708,7 @@ var ListComponent = typedMemo(function ListComponent2({
+         stickyHeaderConfig
+       }
+     ),
+-    ListFooterComponent && /* @__PURE__ */ React2.createElement(LayoutView, { onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
++    ListFooterComponent && /* @__PURE__ */ React2.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
+     IS_DEV && ENABLE_DEVMODE
+   );
+ });
+@@ -7865,7 +7929,10 @@ function setPaddingTop(ctx, { stylePaddingTop }) {
+   const state = ctx.state;
+   if (stylePaddingTop !== void 0) {
+     const prevStylePaddingTop = peek$(ctx, "stylePaddingTop") || 0;
+-    if (stylePaddingTop < prevStylePaddingTop) {
++    // Paseo patch: only iOS compensates a shrinking top padding with a scroll adjust, which this
++    // keeps the native clamp from doubling. Elsewhere the held height paints as blank space at the
++    // end until the timer fires, and a scroll view that keeps its end scrolls into it.
++    if (stylePaddingTop < prevStylePaddingTop && Platform.OS === "ios") {
+       let prevTotalSize = peek$(ctx, "totalSize") || 0;
+       set$(ctx, "totalSize", prevTotalSize + prevStylePaddingTop);
+       state.timeoutSetPaddingTop = setTimeout(() => {
+@@ -7968,6 +8035,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8261,6 +8329,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     dataVersion,
+     drawDistance,
+     estimatedItemSize,
++    getEstimatedItemSize: useWrapIfItem(getEstimatedItemSize),
+     getFixedItemSize: useWrapIfItem(getFixedItemSize),
+     getItemType: useWrapIfItem(getItemType),
+     hasExternalScroll,
diff --git a/patches/react-native-enriched-markdown+1.2.0-nightly-20261014-766fc0e67.patch b/patches/react-native-enriched-markdown+1.2.0-nightly-20261014-766fc0e67.patch
index 1568bd6039..7607522924 100644
--- a/patches/react-native-enriched-markdown+1.2.0-nightly-20261014-766fc0e67.patch
+++ b/patches/react-native-enriched-markdown+1.2.0-nightly-20261014-766fc0e67.patch
@@ -3521,7 +3521,21 @@ diff --git a/node_modules/react-native-enriched-markdown/lib/module/normalizeMar
 diff --git a/node_modules/react-native-enriched-markdown/src/web/styles.ts b/node_modules/react-native-enriched-markdown/src/web/styles.ts
 --- a/node_modules/react-native-enriched-markdown/src/web/styles.ts
 +++ b/node_modules/react-native-enriched-markdown/src/web/styles.ts
-@@ -290,7 +290,7 @@
+@@ -260,9 +260,12 @@ function videoStyle(style: MarkdownStyleInternal): CSSProperties {
+ 
+ function inlineImageStyle(style: MarkdownStyleInternal): CSSProperties {
+   const size = style.inlineImage.size;
++  // Inline images match the line height and keep their aspect ratio, so wide
++  // badges stay legible instead of shrinking into a square.
+   return {
+-    width: size,
++    width: 'auto',
+     height: size,
++    maxWidth: '100%',
+     verticalAlign: 'middle',
+     display: 'inline',
+   };
+@@ -290,7 +293,7 @@ function codeStyle(style: MarkdownStyleInternal): CSSProperties {
    const code = style.code;
    return {
      fontFamily: normalizeFontFamily(code.fontFamily),
@@ -3533,7 +3547,21 @@ diff --git a/node_modules/react-native-enriched-markdown/src/web/styles.ts b/nod
 diff --git a/node_modules/react-native-enriched-markdown/lib/module/web/styles.js b/node_modules/react-native-enriched-markdown/lib/module/web/styles.js
 --- a/node_modules/react-native-enriched-markdown/lib/module/web/styles.js
 +++ b/node_modules/react-native-enriched-markdown/lib/module/web/styles.js
-@@ -271,7 +271,7 @@
+@@ -243,9 +243,12 @@ function videoStyle(style) {
+ }
+ function inlineImageStyle(style) {
+   const size = style.inlineImage.size;
++  // Inline images match the line height and keep their aspect ratio, so wide
++  // badges stay legible instead of shrinking into a square.
+   return {
+-    width: size,
++    width: 'auto',
+     height: size,
++    maxWidth: '100%',
+     verticalAlign: 'middle',
+     display: 'inline'
+   };
+@@ -271,7 +274,7 @@ function codeStyle(style) {
    const code = style.code;
    return {
      fontFamily: normalizeFontFamily(code.fontFamily),
@@ -3884,3 +3912,87 @@ diff --git a/node_modules/react-native-enriched-markdown/android/generated/jni/r
    }
    auto tmp_color = map.find("color");
    if (tmp_color != map.end()) {
+diff --git a/node_modules/react-native-enriched-markdown/src/web/utils.ts b/node_modules/react-native-enriched-markdown/src/web/utils.ts
+--- a/node_modules/react-native-enriched-markdown/src/web/utils.ts
++++ b/node_modules/react-native-enriched-markdown/src/web/utils.ts
+@@ -34,20 +34,32 @@ export function indexTaskItems(node: ASTNode, counter = { value: 0 }): void {
+  * Stamps Image nodes with `isInline` when they appear inside a paragraph
+  * that also contains other content (text, links, etc.).
+  * Matches native behavior: sole-child images are block-level, mixed are inline.
++ * A link wrapping only an image counts as an image, so `[![badge](x)](y) text`
++ * stamps the nested image inline while a lone `[![x](y)](z)` stays a block.
+  * Mutates the AST in-place (safe: called once on the freshly-parsed result).
+  */
+ export function markInlineImages(node: ASTNode): void {
+   if (node.type === 'Paragraph' && node.children) {
+-    const hasNonImageChild = node.children.some(
+-      (child) => child.type !== 'Image'
+-    );
+-    if (hasNonImageChild) {
+-      for (const child of node.children) {
+-        if (child.type === 'Image') {
+-          child.attributes = { ...child.attributes, isInline: true };
+-        }
+-      }
++    if (!node.children.every(isImageLike)) {
++      node.children.forEach(stampInlineImages);
+     }
+   }
+   node.children?.forEach(markInlineImages);
+ }
++
++function isImageLike(node: ASTNode): boolean {
++  if (node.type === 'Image') return true;
++  return (
++    node.type === 'Link' &&
++    node.children?.length === 1 &&
++    isImageLike(node.children[0]!)
++  );
++}
++
++function stampInlineImages(node: ASTNode): void {
++  if (node.type === 'Image') {
++    node.attributes = { ...node.attributes, isInline: true };
++    return;
++  }
++  node.children?.forEach(stampInlineImages);
++}
+diff --git a/node_modules/react-native-enriched-markdown/lib/module/web/utils.js b/node_modules/react-native-enriched-markdown/lib/module/web/utils.js
+--- a/node_modules/react-native-enriched-markdown/lib/module/web/utils.js
++++ b/node_modules/react-native-enriched-markdown/lib/module/web/utils.js
+@@ -40,18 +40,24 @@ export function indexTaskItems(node, counter = {
+  */
+ export function markInlineImages(node) {
+   if (node.type === 'Paragraph' && node.children) {
+-    const hasNonImageChild = node.children.some(child => child.type !== 'Image');
+-    if (hasNonImageChild) {
+-      for (const child of node.children) {
+-        if (child.type === 'Image') {
+-          child.attributes = {
+-            ...child.attributes,
+-            isInline: true
+-          };
+-        }
+-      }
++    if (!node.children.every(isImageLike)) {
++      node.children.forEach(stampInlineImages);
+     }
+   }
+   node.children?.forEach(markInlineImages);
+ }
++function isImageLike(node) {
++  if (node.type === 'Image') return true;
++  return node.type === 'Link' && node.children?.length === 1 && isImageLike(node.children[0]);
++}
++function stampInlineImages(node) {
++  if (node.type === 'Image') {
++    node.attributes = {
++      ...node.attributes,
++      isInline: true
++    };
++    return;
++  }
++  node.children?.forEach(stampInlineImages);
++}
+ //# sourceMappingURL=utils.js.map
+\ No newline at end of file
diff --git a/patches/react-native-gesture-handler+2.32.0.patch b/patches/react-native-gesture-handler+2.32.0.patch
index 7cdbc35d4a..b6e3a810f1 100644
--- a/patches/react-native-gesture-handler+2.32.0.patch
+++ b/patches/react-native-gesture-handler+2.32.0.patch
@@ -194,10 +194,37 @@ index 96c5227..cbf1a88 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js b/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
-index 76eb808..7c40526 100644
+index 76eb808..75a9d75 100644
 --- a/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
 +++ b/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
-@@ -58,7 +58,14 @@ class PointerEventManager extends _EventManager.default {
+@@ -35,9 +35,6 @@ class PointerEventManager extends _EventManager.default {
+     }
+     const adaptedEvent = this.mapEvent(event, _interfaces.EventTypes.DOWN);
+     const target = event.target;
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+     if (++this.activePointersCounter > 1) {
+@@ -46,6 +43,16 @@ class PointerEventManager extends _EventManager.default {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+   pointerUpCallback = event => {
+     // When we call reset on gesture handlers, it also resets their event managers
+@@ -58,7 +65,14 @@ class PointerEventManager extends _EventManager.default {
      const adaptedEvent = this.mapEvent(event, _interfaces.EventTypes.UP);
      const target = event.target;
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -213,6 +240,15 @@ index 76eb808..7c40526 100644
      }
      this.markAsOutOfBounds(adaptedEvent.pointerId);
      this.trackedPointers.delete(adaptedEvent.pointerId);
+@@ -85,7 +99,7 @@ class PointerEventManager extends _EventManager.default {
+     // incorporating it here seems stupid), so we just call it again here, every time
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+-    if (!target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
++    if (this.trackedPointers.has(event.pointerId) && !target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+       target.setPointerCapture(event.pointerId);
+     }
+     const inBounds = (0, _utils.isPointerInBounds)(this.view, {
 diff --git a/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js b/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js
 index 0791c66..2f41c77 100644
 --- a/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js
@@ -229,10 +265,37 @@ index 0791c66..2f41c77 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js b/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
-index 6ce3b8f..8fe28bc 100644
+index 6ce3b8f..65cc6c8 100644
 --- a/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
 +++ b/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
-@@ -53,7 +53,14 @@ export default class PointerEventManager extends EventManager {
+@@ -30,9 +30,6 @@ export default class PointerEventManager extends EventManager {
+     }
+     const adaptedEvent = this.mapEvent(event, EventTypes.DOWN);
+     const target = event.target;
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+     if (++this.activePointersCounter > 1) {
+@@ -41,6 +38,16 @@ export default class PointerEventManager extends EventManager {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+   pointerUpCallback = event => {
+     // When we call reset on gesture handlers, it also resets their event managers
+@@ -53,7 +60,14 @@ export default class PointerEventManager extends EventManager {
      const adaptedEvent = this.mapEvent(event, EventTypes.UP);
      const target = event.target;
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -248,6 +311,15 @@ index 6ce3b8f..8fe28bc 100644
      }
      this.markAsOutOfBounds(adaptedEvent.pointerId);
      this.trackedPointers.delete(adaptedEvent.pointerId);
+@@ -80,7 +94,7 @@ export default class PointerEventManager extends EventManager {
+     // incorporating it here seems stupid), so we just call it again here, every time
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+-    if (!target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
++    if (this.trackedPointers.has(event.pointerId) && !target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+       target.setPointerCapture(event.pointerId);
+     }
+     const inBounds = isPointerInBounds(this.view, {
 diff --git a/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts b/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts
 index ddb79a3..4e1274c 100644
 --- a/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts
@@ -264,10 +336,38 @@ index ddb79a3..4e1274c 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts b/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
-index 18d3627..769b0fe 100644
+index 18d3627..106b97c 100644
 --- a/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
 +++ b/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
-@@ -67,7 +67,14 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+@@ -39,10 +39,6 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     const adaptedEvent: AdaptedEvent = this.mapEvent(event, EventTypes.DOWN);
+     const target = event.target as HTMLElement;
+ 
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+-
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+ 
+@@ -52,6 +48,16 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+ 
+   private pointerUpCallback = (event: PointerEvent) => {
+@@ -67,7 +73,14 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
      const target = event.target as HTMLElement;
  
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -283,3 +383,11 @@ index 18d3627..769b0fe 100644
      }
  
      this.markAsOutOfBounds(adaptedEvent.pointerId);
+@@ -98,6 +111,7 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+     if (
++      this.trackedPointers.has(event.pointerId) &&
+       !target?.hasPointerCapture(event.pointerId) &&
+       !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
+     ) {
diff --git a/patches/react-native-svg+15.15.4.patch b/patches/react-native-svg+15.15.4.patch
index b6b4a85a90..90a30090d7 100644
--- a/patches/react-native-svg+15.15.4.patch
+++ b/patches/react-native-svg+15.15.4.patch
@@ -59,3 +59,130 @@ index 0c854d6..7dc2828 100644
    }
    return props.transform as TransformsStyle['transform'];
  }
+diff --git a/node_modules/react-native-svg/android/build.gradle b/node_modules/react-native-svg/android/build.gradle
+--- a/node_modules/react-native-svg/android/build.gradle
++++ b/node_modules/react-native-svg/android/build.gradle
+@@ -103,6 +103,7 @@
+     }
+ 
+     defaultConfig {
++        testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'
+         minSdkVersion safeExtGet('minSdkVersion', 16)
+         //noinspection OldTargetApi
+         targetSdkVersion safeExtGet('targetSdkVersion', 28)
+@@ -136,6 +137,8 @@
+ }
+ 
+ dependencies {
++    androidTestImplementation 'androidx.test:runner:1.6.2'
++    androidTestImplementation 'androidx.test.ext:junit:1.2.1'
+     implementation 'com.facebook.react:react-native:+'
+     implementation("com.facebook.fresco:fresco:${FRESCO_VERSION}") {
+         exclude group: 'com.facebook.soloader'
+diff --git a/node_modules/react-native-svg/android/src/main/java/com/horcrux/svg/SvgView.java b/node_modules/react-native-svg/android/src/main/java/com/horcrux/svg/SvgView.java
+--- a/node_modules/react-native-svg/android/src/main/java/com/horcrux/svg/SvgView.java
++++ b/node_modules/react-native-svg/android/src/main/java/com/horcrux/svg/SvgView.java
+@@ -159,6 +159,8 @@
+   @Override
+   protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+     super.onSizeChanged(w, h, oldw, oldh);
++    // Percentage lengths and paths depend on the canvas size, not just SVG props.
++    clearChildCache();
+     this.invalidate();
+   }
+ 
+diff --git a/node_modules/react-native-svg/android/src/androidTest/java/com/horcrux/svg/SvgResizeTest.java b/node_modules/react-native-svg/android/src/androidTest/java/com/horcrux/svg/SvgResizeTest.java
+new file mode 100644
+--- /dev/null
++++ b/node_modules/react-native-svg/android/src/androidTest/java/com/horcrux/svg/SvgResizeTest.java
+@@ -0,0 +1,90 @@
++package com.horcrux.svg;
++
++import static org.junit.Assert.assertEquals;
++import static org.junit.Assert.assertTrue;
++
++import android.graphics.Bitmap;
++import android.graphics.Canvas;
++import android.graphics.Color;
++import android.view.View;
++import androidx.test.ext.junit.runners.AndroidJUnit4;
++import androidx.test.platform.app.InstrumentationRegistry;
++import com.facebook.react.bridge.BridgeReactContext;
++import com.facebook.react.bridge.DynamicFromObject;
++import com.facebook.react.bridge.JavaOnlyArray;
++import com.facebook.react.bridge.JavaOnlyMap;
++import com.facebook.react.soloader.OpenSourceMergedSoMapping;
++import com.facebook.react.uimanager.DisplayMetricsHolder;
++import com.facebook.soloader.SoLoader;
++import org.junit.Test;
++import org.junit.runner.RunWith;
++
++@RunWith(AndroidJUnit4.class)
++public class SvgResizeTest {
++  @Test
++  public void percentageFadeFollowsCanvasGrowthAndShrinkage() {
++    InstrumentationRegistry.getInstrumentation().runOnMainSync(() -> {
++      android.content.Context app = InstrumentationRegistry.getInstrumentation().getTargetContext();
++      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(app);
++      try {
++        SoLoader.init(app, OpenSourceMergedSoMapping.INSTANCE);
++      } catch (java.io.IOException exception) {
++        throw new RuntimeException(exception);
++      }
++      BridgeReactContext context = new DrawingContext(app);
++      SvgView svg = new SvgView(context);
++      LinearGradientView gradient = new LinearGradientView(context);
++      gradient.setName("fade");
++      gradient.setX1(new DynamicFromObject("0%"));
++      gradient.setY1(new DynamicFromObject("0%"));
++      gradient.setX2(new DynamicFromObject("0%"));
++      gradient.setY2(new DynamicFromObject("100%"));
++      gradient.setGradientUnits(0);
++      gradient.setGradient(JavaOnlyArray.of(0.0, Color.RED, 1.0, Color.TRANSPARENT));
++      svg.addView(gradient);
++      // Exercise recursive invalidation as well as the direct child case.
++      GroupView group = new GroupView(context);
++      RectView rectangle = new RectView(context);
++      rectangle.setX(new DynamicFromObject(0.0));
++      rectangle.setY(new DynamicFromObject(0.0));
++      rectangle.setWidth(new DynamicFromObject("100%"));
++      rectangle.setHeight(new DynamicFromObject("100%"));
++      rectangle.setFill(JavaOnlyMap.of("type", 1, "brushRef", "fade"));
++      group.addView(rectangle);
++      svg.addView(group);
++
++      assertFade(svg, 80, 60);
++      assertFade(svg, 160, 120);
++      assertFade(svg, 60, 40);
++      assertFade(svg, 160, 120);
++    });
++  }
++
++  // Pixel rendering needs a React context but does not send layout events to JavaScript.
++  private static final class DrawingContext extends BridgeReactContext
++      implements com.facebook.react.uimanager.events.EventDispatcherProvider {
++    DrawingContext(android.content.Context context) { super(context); }
++
++    @Override
++    public com.facebook.react.uimanager.events.EventDispatcher getEventDispatcher() { return null; }
++  }
++
++  private static void assertFade(SvgView svg, int width, int height) {
++    svg.measure(View.MeasureSpec.makeMeasureSpec(width, View.MeasureSpec.EXACTLY),
++        View.MeasureSpec.makeMeasureSpec(height, View.MeasureSpec.EXACTLY));
++    svg.layout(0, 0, width, height);
++    Bitmap image = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
++    svg.draw(new Canvas(image));
++    try {
++      int middle = Color.alpha(image.getPixel(width / 2, height / 2));
++      int right = Color.alpha(image.getPixel(width - 2, height / 2));
++      assertTrue("Gradient midpoint must follow canvas height at " + width + "x" + height
++          + "; alpha=" + middle, middle >= 120 && middle <= 135);
++      assertEquals("Fade must reach the right edge at " + width + "x" + height, middle, right);
++      assertTrue("Fade must end at the new bottom edge",
++          Color.alpha(image.getPixel(width / 2, height - 2)) < 20);
++    } finally {
++      image.recycle();
++    }
++  }
++}
diff --git a/patches/react-native-unistyles+3.2.4.patch b/patches/react-native-unistyles+3.2.4.patch
index af825a6afa..c3da63a8ac 100644
--- a/patches/react-native-unistyles+3.2.4.patch
+++ b/patches/react-native-unistyles+3.2.4.patch
@@ -705,3 +705,59 @@ index a9c1804..f5a3c20 100644
  
          return Insets(
              this._insets.top / density,
+diff --git a/node_modules/react-native-unistyles/cxx/shadowTree/ShadowTreeManager.cpp b/node_modules/react-native-unistyles/cxx/shadowTree/ShadowTreeManager.cpp
+index 01026dc..3786ec4 100644
+--- a/node_modules/react-native-unistyles/cxx/shadowTree/ShadowTreeManager.cpp
++++ b/node_modules/react-native-unistyles/cxx/shadowTree/ShadowTreeManager.cpp
+@@ -17,13 +17,16 @@ void shadow::ShadowTreeManager::updateShadowTree(jsi::Runtime& rt) {
+         }
+ 
+ #if REACT_NATIVE_VERSION_MINOR >= 81
+-        std::unordered_map<Tag, folly::dynamic> tagToProps;
++        // Paseo backport of https://github.com/jpudysz/react-native-unistyles/pull/1357.
++        // UIManager::updateShadowTree commits a root cloned before the commit, so when a
++        // window-size commit (rotation, keyboard) lands in between, the retried Unistyles
++        // commit puts the previous layout constraints back and the app stays laid out for
++        // the old size. Commit here instead and clone from the root the commit hands us.
++        std::unordered_set<SurfaceId> affectedSurfaces;
+ 
+         for (const auto& [family, props] : updates) {
+             auto safeProps = props.isObject() ? props : folly::dynamic::object();
+ 
+-            tagToProps.insert({family->getTag(), safeProps});
+-
+             auto* mutableFamily = const_cast<ShadowNodeFamily*>(family);
+ 
+             if (mutableFamily->nativeProps_DEPRECATED && mutableFamily->nativeProps_DEPRECATED->isObject()) {
+@@ -31,9 +34,30 @@ void shadow::ShadowTreeManager::updateShadowTree(jsi::Runtime& rt) {
+             } else {
+                 mutableFamily->nativeProps_DEPRECATED = std::make_unique<folly::dynamic>(safeProps);
+             }
++
++            affectedSurfaces.insert(family->getSurfaceId());
+         }
+ 
+-        UIManagerBinding::getBinding(rt)->getUIManager().updateShadowTree(std::move(tagToProps));
++        const auto& shadowTreeRegistry = UIManagerBinding::getBinding(rt)->getUIManager().getShadowTreeRegistry();
++
++        shadowTreeRegistry.enumerate([&updates, &affectedSurfaces](const ShadowTree& shadowTree, bool&){
++            if (!affectedSurfaces.contains(shadowTree.getSurfaceId())) {
++                return;
++            }
++
++            auto transaction = [&updates](const RootShadowNode& oldRootShadowNode) -> RootShadowNode::Unshared {
++                auto affectedNodes = shadow::ShadowTreeManager::findAffectedNodes(oldRootShadowNode, updates);
++
++                return std::static_pointer_cast<RootShadowNode>(shadow::ShadowTreeManager::cloneShadowTree(
++                    oldRootShadowNode,
++                    updates,
++                    affectedNodes
++                ));
++            };
++
++            // mountSynchronously: this is an update from C++, not React
++            shadowTree.commit(transaction, {false, true});
++        });
+ #else
+         const auto& shadowTreeRegistry = UIManagerBinding::getBinding(rt)->getUIManager().getShadowTreeRegistry();
+ 
diff --git a/plugin-examples/buttons/README.md b/plugin-examples/buttons/README.md
index 111be3b08d..acb64c087e 100644
--- a/plugin-examples/buttons/README.md
+++ b/plugin-examples/buttons/README.md
@@ -4,16 +4,17 @@ Install this directory as a plugin, open an agent, and choose **Button examples:
 Command Center. One header button and one composer pill appear. Choose another mode to update
 those same registrations. Switching agents moves the example to that agent's workspace and composer.
 
-| Command Center command                | Header                                | Composer                        | Try                                                                                                                   |
-| ------------------------------------- | ------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Button examples: action**           | Refresh icon only                     | Refresh icon and label          | Refresh reads the workspace from the daemon and updates the label and tooltip. Paseo owns pending and error feedback. |
-| **Button examples: menu**             | Wrench, Tools, chevron                | Wrench and Tools                | Refresh, a separator, custom details, a Display submenu, and a disabled item.                                         |
-| **Button examples: popover**          | Reactive status dot, Details, chevron | Reactive status dot and Details | Workspace data updates through `useWorkspace`; Done closes the surface.                                               |
-| **Button examples: hide / show**      | Hide or restore the button            | Hide or restore the pill        | Visibility changes through `registration.update({ visible })`.                                                        |
-| **Button examples: disable / enable** | Disable or enable the button          | Disable or enable the pill      | Disabled state changes through `registration.update({ disabled })`.                                                   |
+| Command Center command                | Header                                | Composer                     | Try                                                                                                                   |
+| ------------------------------------- | ------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Button examples: action**           | Refresh icon only                     | Refresh icon and label       | Refresh reads the workspace from the daemon and updates the label and tooltip. Paseo owns pending and error feedback. |
+| **Button examples: menu**             | Wrench, Tools, chevron                | Wrench, Tools, chevron       | Refresh, a separator, custom details, a Display submenu, and a disabled item.                                         |
+| **Button examples: popover**          | Reactive status dot, Details, chevron | Status dot, Details, chevron | Workspace data updates through `useWorkspace`; Done closes the surface.                                               |
+| **Button examples: hide / show**      | Hide or restore the button            | Hide or restore the pill     | Visibility changes through `registration.update({ visible })`.                                                        |
+| **Button examples: disable / enable** | Disable or enable the button          | Disable or enable the pill   | Disabled state changes through `registration.update({ disabled })`.                                                   |
 
 On compact layouts the header button is borderless and icon-only. Menus and custom content open
-bottom sheets. Composer pills keep their icon and label, without a chevron, on every layout.
+bottom sheets. Composer pills keep their icon and label on every layout, and menus and popovers keep
+their chevron.
 
 The example contributes one header button at a time. Additional actions live under the named
 **Tools** button; the example does not add a three-dot control or trigger plugin overflow.
diff --git a/plugin-examples/composer-controls/README.md b/plugin-examples/composer-controls/README.md
new file mode 100644
index 0000000000..bd0e752ffb
--- /dev/null
+++ b/plugin-examples/composer-controls/README.md
@@ -0,0 +1,29 @@
+# Composer controls
+
+Install this directory as a plugin and open the agent, draft, or New workspace composer. Four
+controls appear beside the model and thinking controls.
+
+| Control              | Component | What it does                                                                             |
+| -------------------- | --------- | ---------------------------------------------------------------------------------------- |
+| **Context length**   | `Select`  | Saves `composer-controls.contextLength` in the agent's metadata.                         |
+| **Needs review**     | `Toggle`  | Sets or clears `composer-controls.needsReview` in the agent's metadata.                  |
+| **Plan first**       | `Toggle`  | Sets the provider option `plan_mode` with `composer.setOptions`; enabled for Codex only. |
+| **Insert checklist** | `Action`  | Inserts a task list at the cursor through `composer.insertText`.                         |
+
+Each component calls `useComposer()` and uses the same commands in every composer. Paseo draws the
+controls inline when the composer has room and as rows in the composer's overflow sheet when it
+does not, including on a phone.
+
+## Reaching a composer from outside it
+
+Two more contributions use a composer without sitting in one. Both name the agent instead of
+reading the composer they are mounted in, and neither needs the agent's tab to be open.
+
+| Contribution                         | What it does                                                                                             |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **Composer tools** (Explorer panel)  | `useComposers({ focused: true })` inserts the checklist into the focused agent's prompt.                 |
+| **Mark for review** (Command Center) | `composers({ agentId })` sets the same `needsReview` metadata as the toggle, for the agent you selected. |
+
+[client/controls.tsx](client/controls.tsx) holds the four composer components,
+[client/panel.tsx](client/panel.tsx) the panel, and [index.client.tsx](index.client.tsx) registers
+everything.
diff --git a/plugin-examples/composer-controls/client/controls.tsx b/plugin-examples/composer-controls/client/controls.tsx
new file mode 100644
index 0000000000..51d52991bb
--- /dev/null
+++ b/plugin-examples/composer-controls/client/controls.tsx
@@ -0,0 +1,80 @@
+import { useCallback } from "react";
+import { useComposer } from "@getpaseo/plugin/client";
+import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+
+type ContextLength = "short" | "long";
+
+const CONTEXT_OPTIONS = [
+  { value: "short", label: "Short", description: "Answer from the files you name." },
+  { value: "long", label: "Long", description: "Read the surrounding code first." },
+] as const;
+
+const CONTEXT_KEY = "composer-controls.contextLength";
+export const REVIEW_KEY = "composer-controls.needsReview";
+
+/** Reads and writes agent metadata, so the choice is saved with the agent. */
+export function ContextLength() {
+  const composer = useComposer();
+  const current: ContextLength = composer.agent.metadata[CONTEXT_KEY] === "long" ? "long" : "short";
+  const change = useCallback(
+    ({ value }: { value: ContextLength }) => composer.setMetadata({ [CONTEXT_KEY]: value }),
+    [composer],
+  );
+  return (
+    <Select
+      title="Context length"
+      icon="Gauge"
+      value={current}
+      options={CONTEXT_OPTIONS}
+      onValueChange={change}
+    />
+  );
+}
+
+export function ReviewFlag() {
+  const composer = useComposer();
+  const change = useCallback(
+    ({ value }: { value: boolean }) => composer.setMetadata({ [REVIEW_KEY]: value ? true : null }),
+    [composer],
+  );
+  return (
+    <Toggle
+      title="Needs review"
+      icon="Flag"
+      value={composer.agent.metadata[REVIEW_KEY] === true}
+      onValueChange={change}
+    />
+  );
+}
+
+/**
+ * Changes a provider option. Only Codex reports `plan_mode`, so the control is disabled for
+ * other providers. The promise it returns keeps the control pending, and a rejection reaches the
+ * user as a toast.
+ */
+export function PlanFirst() {
+  const composer = useComposer();
+  const change = useCallback(
+    ({ value }: { value: boolean }) => composer.setOptions({ plan_mode: value }),
+    [composer],
+  );
+  return (
+    <Toggle
+      title="Plan first"
+      icon="ListTodo"
+      disabled={composer.agent.provider !== "codex"}
+      value={composer.agent.options.plan_mode === true}
+      onValueChange={change}
+    />
+  );
+}
+
+/** Works the same in the agent, draft and New workspace composers. */
+export function Checklist() {
+  const composer = useComposer();
+  const insert = useCallback(async () => {
+    composer.insertText("- [ ] Tests\n- [ ] Docs\n");
+    await composer.focus();
+  }, [composer]);
+  return <Action title="Insert checklist" icon="ListChecks" onPress={insert} />;
+}
diff --git a/plugin-examples/composer-controls/client/panel.tsx b/plugin-examples/composer-controls/client/panel.tsx
new file mode 100644
index 0000000000..1c76219ee5
--- /dev/null
+++ b/plugin-examples/composer-controls/client/panel.tsx
@@ -0,0 +1,56 @@
+import { useCallback, useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+import { useComposers, type PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+import { REVIEW_KEY } from "./controls";
+
+/**
+ * Lives in the Explorer, away from any composer, and reaches the composer of the agent whose tab
+ * is focused. The agent's tab does not have to be open for the composer to exist: the text lands in
+ * its prompt either way.
+ */
+export function ComposerTools({ theme, layout }: PluginWorkspacePanelProps) {
+  const [focused] = useComposers({ focused: true });
+  const styles = useMemo(
+    () => ({
+      screen: {
+        flex: 1,
+        padding: layout.compact ? 16 : 24,
+        gap: 12,
+        backgroundColor: theme.colors.surface0,
+      },
+      label: { color: theme.colors.foregroundMuted },
+      button: {
+        padding: 12,
+        borderRadius: 8,
+        backgroundColor: focused ? theme.colors.accent : theme.colors.surface2,
+      },
+      buttonText: {
+        color: focused ? theme.colors.accentForeground : theme.colors.foregroundMuted,
+        textAlign: "center" as const,
+      },
+    }),
+    [focused, layout.compact, theme],
+  );
+  const insert = useCallback(() => focused?.insertText("- [ ] Tests\n- [ ] Docs\n"), [focused]);
+  return (
+    <View style={styles.screen}>
+      <Text style={styles.label}>
+        {focused ? `Focused agent: ${focused.agent.provider}` : "No agent is focused"}
+      </Text>
+      {focused ? (
+        <Text style={styles.label}>
+          {focused.agent.metadata[REVIEW_KEY] === true ? "Needs review: yes" : "Needs review: no"}
+        </Text>
+      ) : null}
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Insert checklist into the focused agent"
+        disabled={!focused}
+        onPress={insert}
+        style={styles.button}
+      >
+        <Text style={styles.buttonText}>Insert checklist into the focused agent</Text>
+      </Pressable>
+    </View>
+  );
+}
diff --git a/plugin-examples/composer-controls/index.client.tsx b/plugin-examples/composer-controls/index.client.tsx
new file mode 100644
index 0000000000..f8d5fd84ee
--- /dev/null
+++ b/plugin-examples/composer-controls/index.client.tsx
@@ -0,0 +1,30 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { Checklist, ContextLength, PlanFirst, REVIEW_KEY, ReviewFlag } from "./client/controls";
+import { ComposerTools } from "./client/panel";
+
+export default function contribute(client: PluginClientContext) {
+  client.addComposerItem({ id: "context-length", Component: ContextLength });
+  client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
+  client.addComposerItem({ id: "plan-first", Component: PlanFirst });
+  client.addComposerItem({ id: "checklist", Component: Checklist });
+  client.addWorkspacePanel({
+    id: "composer-tools",
+    title: "Composer tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component: ComposerTools,
+  });
+  client.addCommandCenterItem({
+    id: "mark-for-review",
+    title: "Composer controls: mark for review",
+    icon: "Flag",
+    context: "agent",
+    async onSelect({ agent, composers }) {
+      // The agent's tab does not have to be open.
+      for (const composer of composers({ agentId: agent.id })) {
+        await composer.setMetadata({ [REVIEW_KEY]: true });
+      }
+    },
+  });
+  return () => {};
+}
diff --git a/plugin-examples/composer-controls/paseo-plugin.json b/plugin-examples/composer-controls/paseo-plugin.json
new file mode 100644
index 0000000000..34107f376a
--- /dev/null
+++ b/plugin-examples/composer-controls/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "composer-controls-example",
+  "requirements": { "paseo": ">=0.8.0" }
+}
diff --git a/plugin-examples/diff-watch/OVERVIEW.md b/plugin-examples/diff-watch/OVERVIEW.md
new file mode 100644
index 0000000000..074803d34b
--- /dev/null
+++ b/plugin-examples/diff-watch/OVERVIEW.md
@@ -0,0 +1,7 @@
+# Live changes
+
+See which files differ from `HEAD` in a workspace panel that updates as you edit. The daemon watches the workspace and pushes the changed-file list to the panel; the panel never polls.
+
+Open **Open live changes** in the Command Center, or pick **Live changes** from the workspace tab menu. Each open panel runs its own watcher, which stops when you close the panel.
+
+The watcher reads the working tree recursively, so a checkout with very large ignored directories makes it slower to start.
diff --git a/plugin-examples/diff-watch/README.md b/plugin-examples/diff-watch/README.md
new file mode 100644
index 0000000000..1c8d1b7f25
--- /dev/null
+++ b/plugin-examples/diff-watch/README.md
@@ -0,0 +1,14 @@
+# Diff watch plugin example
+
+A workspace panel subscribes to a daemon-side watcher and lists the files that differ from `HEAD`,
+updating as files change.
+
+```bash
+paseo plugin add /absolute/path/to/paseo/plugin-examples/diff-watch
+```
+
+- `shared/diff.ts` defines the `diff.watch` subscription contract.
+- `index.server.ts` handles it: an async handler that loops until the subscriber leaves, pushing
+  the file list whenever it changes. A git failure rejects the handler and closes the subscription
+  with that error.
+- `client/diff-panel.tsx` calls `useSubscription` and renders the latest list.
diff --git a/plugin-examples/diff-watch/client/diff-panel.tsx b/plugin-examples/diff-watch/client/diff-panel.tsx
new file mode 100644
index 0000000000..f1ad4ed61f
--- /dev/null
+++ b/plugin-examples/diff-watch/client/diff-panel.tsx
@@ -0,0 +1,65 @@
+import {
+  useSubscription,
+  useWorkspace,
+  type PluginWorkspacePanelProps,
+} from "@getpaseo/plugin/client";
+import { useMemo, useState } from "react";
+import { ScrollView, StyleSheet, Text, View } from "react-native";
+import { diffWatch, type ChangedFile } from "../shared/diff";
+
+const BASE = "HEAD";
+
+export function DiffPanel({ workspaceId, theme, layout }: PluginWorkspacePanelProps) {
+  const cwd = useWorkspace(workspaceId, (workspace) => workspace.directory);
+  const styles = useStyles(theme, layout.compact);
+  if (!cwd) return <Text style={styles.muted}>Workspace unavailable</Text>;
+  return <ChangedFiles cwd={cwd} styles={styles} />;
+}
+
+function ChangedFiles({ cwd, styles }: { cwd: string; styles: ReturnType<typeof useStyles> }) {
+  const [files, setFiles] = useState<ChangedFile[] | null>(null);
+  const subscription = useSubscription(diffWatch, { cwd, from: BASE }, (event) => {
+    setFiles(event.files);
+  });
+  return (
+    <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
+      <Text style={styles.title}>Changes against {BASE}</Text>
+      <Text style={styles.muted}>{describe(subscription, files)}</Text>
+      {files?.map((file) => (
+        <View key={file.path} style={styles.row}>
+          <Text style={styles.status}>{file.status}</Text>
+          <Text style={styles.path} numberOfLines={1}>
+            {file.path}
+          </Text>
+        </View>
+      ))}
+    </ScrollView>
+  );
+}
+
+function describe(
+  subscription: ReturnType<typeof useSubscription>,
+  files: ChangedFile[] | null,
+): string {
+  if (subscription.status === "error") return subscription.error.message;
+  if (subscription.status === "closed") return "Stopped watching";
+  if (!files) return "Reading changes…";
+  if (files.length === 0) return "No changes";
+  return files.length === 1 ? "1 file changed" : `${files.length} files changed`;
+}
+
+function useStyles(theme: PluginWorkspacePanelProps["theme"], compact: boolean) {
+  return useMemo(
+    () =>
+      StyleSheet.create({
+        screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+        content: { padding: compact ? 16 : 24, gap: 8 },
+        title: { color: theme.colors.foreground, fontSize: 18, fontWeight: "600" },
+        muted: { color: theme.colors.foregroundMuted },
+        row: { flexDirection: "row", gap: 12, alignItems: "center" },
+        status: { color: theme.colors.foregroundMuted, width: 72 },
+        path: { color: theme.colors.foreground, flex: 1 },
+      }),
+    [theme, compact],
+  );
+}
diff --git a/plugin-examples/diff-watch/index.client.tsx b/plugin-examples/diff-watch/index.client.tsx
new file mode 100644
index 0000000000..e50175a8c8
--- /dev/null
+++ b/plugin-examples/diff-watch/index.client.tsx
@@ -0,0 +1,22 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { DiffPanel } from "./client/diff-panel";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "changes",
+    title: "Live changes",
+    icon: "GitCompare",
+    context: "workspace",
+    Component: DiffPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-changes",
+    title: "Open live changes",
+    icon: "GitCompare",
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel("changes");
+    },
+  });
+  return () => {};
+}
diff --git a/plugin-examples/diff-watch/index.server.ts b/plugin-examples/diff-watch/index.server.ts
new file mode 100644
index 0000000000..b8c0fcf749
--- /dev/null
+++ b/plugin-examples/diff-watch/index.server.ts
@@ -0,0 +1,19 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { readChangedFiles, watchDirectory } from "./server/diff";
+import { diffWatch } from "./shared/diff";
+
+export default function contribute(server: PluginServerContext) {
+  // The handler runs for as long as the panel is subscribed; a git failure closes it with the error.
+  server.handle(diffWatch, async (input, { push, signal }) => {
+    const directory = watchDirectory(input.cwd, signal);
+    let previous = "";
+    while (await directory.settled()) {
+      const files = await readChangedFiles(input);
+      const current = JSON.stringify(files);
+      if (current === previous) continue;
+      previous = current;
+      await push({ type: "changes", files });
+    }
+  });
+  return () => {};
+}
diff --git a/plugin-examples/diff-watch/paseo-plugin.json b/plugin-examples/diff-watch/paseo-plugin.json
new file mode 100644
index 0000000000..aa166b8374
--- /dev/null
+++ b/plugin-examples/diff-watch/paseo-plugin.json
@@ -0,0 +1,6 @@
+{
+  "id": "diff-watch",
+  "requirements": {
+    "paseo": ">=0.15.0-beta.2"
+  }
+}
diff --git a/plugin-examples/diff-watch/server/diff.ts b/plugin-examples/diff-watch/server/diff.ts
new file mode 100644
index 0000000000..2ca22b4298
--- /dev/null
+++ b/plugin-examples/diff-watch/server/diff.ts
@@ -0,0 +1,79 @@
+import { watch } from "node:fs";
+import type { SubscriptionInput } from "@getpaseo/plugin";
+import { execCommand } from "@getpaseo/plugin/server";
+import type { ChangedFile, diffWatch } from "../shared/diff";
+
+const SETTLE_MS = 150;
+
+const STATUSES: Record<string, ChangedFile["status"]> = {
+  A: "added",
+  M: "modified",
+  D: "deleted",
+  R: "renamed",
+};
+
+/** Lists changed files the way `git diff --name-status` does, plus untracked files. */
+export async function readChangedFiles({
+  cwd,
+  from,
+  to,
+}: SubscriptionInput<typeof diffWatch>): Promise<ChangedFile[]> {
+  const range = to ? [from, to] : [from];
+  const { stdout } = await execCommand("git", ["diff", "--name-status", "-z", ...range], { cwd });
+  const files = parseNameStatus(stdout);
+  if (!to) {
+    const untracked = await execCommand(
+      "git",
+      ["ls-files", "--others", "--exclude-standard", "-z"],
+      {
+        cwd,
+      },
+    );
+    for (const path of untracked.stdout.split("\0").filter(Boolean))
+      files.push({ path, status: "added" });
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function parseNameStatus(output: string): ChangedFile[] {
+  const fields = output.split("\0").filter(Boolean);
+  const files: ChangedFile[] = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const code = fields[index][0];
+    // Renames carry the old path before the new one.
+    if (code === "R") index += 1;
+    const path = fields[index + 1];
+    index += 1;
+    if (path) files.push({ path, status: STATUSES[code] ?? "modified" });
+  }
+  return files;
+}
+
+/** Resolves each time the directory settles after a change, and with false once `signal` aborts. */
+export function watchDirectory(cwd: string, signal: AbortSignal) {
+  let changed = true;
+  let wake: (() => void) | null = null;
+  const watcher = watch(cwd, { recursive: true }, () => {
+    changed = true;
+    wake?.();
+  });
+  signal.addEventListener(
+    "abort",
+    () => {
+      watcher.close();
+      wake?.();
+    },
+    { once: true },
+  );
+  return {
+    async settled(): Promise<boolean> {
+      // The watcher and the abort both wake a wait.
+      if (!changed && !signal.aborted) await new Promise<void>((resolve) => (wake = resolve));
+      wake = null;
+      if (signal.aborted) return false;
+      await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+      changed = false;
+      return !signal.aborted;
+    },
+  };
+}
diff --git a/plugin-examples/diff-watch/shared/diff.ts b/plugin-examples/diff-watch/shared/diff.ts
new file mode 100644
index 0000000000..adab27fc5c
--- /dev/null
+++ b/plugin-examples/diff-watch/shared/diff.ts
@@ -0,0 +1,16 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const ChangedFileSchema = z.object({
+  path: z.string(),
+  status: z.enum(["added", "modified", "deleted", "renamed"]),
+});
+
+export type ChangedFile = z.infer<typeof ChangedFileSchema>;
+
+/** Files that differ between `from` and `to`; without `to`, the working tree. */
+export const diffWatch = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ cwd: z.string(), from: z.string(), to: z.string().optional() }),
+  event: z.object({ type: z.literal("changes"), files: z.array(ChangedFileSchema) }),
+});
diff --git a/plugin-examples/media-stream/OVERVIEW.md b/plugin-examples/media-stream/OVERVIEW.md
new file mode 100644
index 0000000000..de9e784fc7
--- /dev/null
+++ b/plugin-examples/media-stream/OVERVIEW.md
@@ -0,0 +1,7 @@
+# Media stream
+
+Watch a moving test pattern and an audio level meter, streamed live from your machine into a workspace panel. Video and audio arrive together on one connection, and the counters show how many frames of each have played.
+
+Open **Open media stream** in the Command Center, or pick **Media stream** from the workspace tab menu. Closing the panel stops the stream.
+
+Press **Send this frame back** to upload the picture on screen to your machine. The panel shows the size and checksum your machine received. A 16 by 9 picture is 432 bytes.
diff --git a/plugin-examples/media-stream/README.md b/plugin-examples/media-stream/README.md
new file mode 100644
index 0000000000..941bd0fe96
--- /dev/null
+++ b/plugin-examples/media-stream/README.md
@@ -0,0 +1,17 @@
+# Media stream plugin example
+
+One subscription carries two binary streams. Each pushed `Uint8Array` is a binary frame; its first
+byte says whether it is video, a keyframe, or audio.
+
+```bash
+paseo plugin add /absolute/path/to/paseo/plugin-examples/media-stream
+```
+
+- `shared/media-frames.ts` owns the byte layout: `encodeMediaFrame`, `decodeMediaFrame`, and the
+  `media.stream` contract. `decodeMediaFrame` returns a view, so the panel never copies a payload.
+- `server/test-pattern.ts` is a synthetic source; replace it with a real capture.
+- `index.server.ts` pushes each source callback as a frame and stops the source when the
+  subscription's `signal` aborts.
+- `client/media-panel.tsx` decodes each frame and routes it by opcode.
+- `shared/frame-check.ts` is an RPC whose input is a `Uint8Array`: the panel uploads the picture
+  on screen and `server/frame-check.ts` reports its size and checksum.
diff --git a/plugin-examples/media-stream/client/media-panel.tsx b/plugin-examples/media-stream/client/media-panel.tsx
new file mode 100644
index 0000000000..d367f2148d
--- /dev/null
+++ b/plugin-examples/media-stream/client/media-panel.tsx
@@ -0,0 +1,196 @@
+import { useRpc, useSubscription, type PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+import type { RpcOutput } from "@getpaseo/plugin";
+import { type UseMutationResult, useMutation } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { checkFrame } from "../shared/frame-check";
+import {
+  decodeMediaFrame,
+  MediaOpcode,
+  mediaStream,
+  VIDEO,
+  type MediaFrame,
+} from "../shared/media-frames";
+
+interface Playback {
+  picture: Uint8Array | null;
+  level: number;
+  videoFrames: number;
+  keyframes: number;
+  audioChunks: number;
+  bytes: number;
+}
+
+const EMPTY: Playback = {
+  picture: null,
+  level: 0,
+  videoFrames: 0,
+  keyframes: 0,
+  audioChunks: 0,
+  bytes: 0,
+};
+
+export function MediaPanel({ theme, layout }: PluginWorkspacePanelProps) {
+  const styles = useStyles(theme, layout.compact);
+  const [playback, setPlayback] = useState(EMPTY);
+  const subscription = useSubscription(mediaStream, { source: "test-pattern" }, (bytes) => {
+    const frame = decodeMediaFrame(bytes);
+    if (frame) setPlayback((current) => play(current, frame, bytes.byteLength));
+  });
+  return (
+    <View style={styles.screen}>
+      <Text style={styles.title}>Test pattern</Text>
+      <Text style={styles.muted}>
+        {subscription.status === "error" ? subscription.error.message : subscription.status}
+      </Text>
+      <Picture pixels={playback.picture} cellSize={layout.compact ? 14 : 20} />
+      <LevelMeter level={playback.level} styles={styles} />
+      <Text style={styles.muted}>
+        {playback.videoFrames} video frames ({playback.keyframes} keyframes), {playback.audioChunks}{" "}
+        audio chunks, {(playback.bytes / 1024).toFixed(0)} KiB
+      </Text>
+      <SendFrameBack picture={playback.picture} styles={styles} />
+    </View>
+  );
+}
+
+/** Uploads the picture on screen and shows what the daemon received. */
+function SendFrameBack({
+  picture,
+  styles,
+}: {
+  picture: Uint8Array | null;
+  styles: ReturnType<typeof useStyles>;
+}) {
+  const sendFrame = useRpc(checkFrame);
+  const check = useMutation({ mutationFn: sendFrame });
+  const { mutate } = check;
+  const send = useCallback(() => {
+    if (picture) mutate(picture);
+  }, [mutate, picture]);
+  return (
+    <View style={styles.upload}>
+      <Pressable
+        accessibilityRole="button"
+        disabled={!picture || check.isPending}
+        onPress={send}
+        style={styles.button}
+      >
+        <Text style={styles.buttonText}>Send this frame back</Text>
+      </Pressable>
+      <Text style={styles.muted}>{describeCheck(check)}</Text>
+    </View>
+  );
+}
+
+function describeCheck(
+  check: UseMutationResult<RpcOutput<typeof checkFrame>, Error, Uint8Array>,
+): string {
+  if (check.status === "error") return check.error.message;
+  if (check.status === "success")
+    return `The daemon received ${check.data.bytes} bytes, sha256 ${check.data.sha256.slice(0, 12)}`;
+  return check.status === "pending" ? "Sending…" : "";
+}
+
+function play(current: Playback, frame: MediaFrame, bytes: number): Playback {
+  if (frame.opcode === MediaOpcode.Audio)
+    return {
+      ...current,
+      level: audioLevel(frame.payload),
+      audioChunks: current.audioChunks + 1,
+      bytes: current.bytes + bytes,
+    };
+  return {
+    ...current,
+    picture: frame.payload,
+    videoFrames: current.videoFrames + 1,
+    keyframes: current.keyframes + (frame.opcode === MediaOpcode.Keyframe ? 1 : 0),
+    bytes: current.bytes + bytes,
+  };
+}
+
+function audioLevel(samples: Uint8Array): number {
+  const view = new DataView(samples.buffer, samples.byteOffset, samples.byteLength);
+  let sum = 0;
+  const count = samples.byteLength / 2;
+  for (let index = 0; index < count; index += 1) sum += view.getInt16(index * 2, true) ** 2;
+  return Math.min(1, Math.sqrt(sum / Math.max(1, count)) / 16384);
+}
+
+function LevelMeter({ level, styles }: { level: number; styles: ReturnType<typeof useStyles> }) {
+  const fill = useMemo(
+    () => [styles.meter, { width: `${Math.round(level * 100)}%` as const }],
+    [level, styles],
+  );
+  return (
+    <View style={styles.meterTrack}>
+      <View style={fill} />
+    </View>
+  );
+}
+
+function Picture({ pixels, cellSize }: { pixels: Uint8Array | null; cellSize: number }) {
+  const rows = useMemo(() => pictureRows(pixels, cellSize), [pixels, cellSize]);
+  return (
+    <View accessibilityLabel="Test pattern video">
+      {rows.map((row) => (
+        <View key={row.key} style={pictureStyles.row}>
+          {row.cells.map((cell) => (
+            <View key={cell.key} style={cell.style} />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/** One style per pixel, row by row. */
+function pictureRows(pixels: Uint8Array | null, cellSize: number) {
+  const rows = [];
+  for (let y = 0; y < VIDEO.height; y += 1) {
+    const cells = [];
+    for (let x = 0; x < VIDEO.width; x += 1) {
+      const offset = (y * VIDEO.width + x) * 3;
+      const backgroundColor = pixels
+        ? `rgb(${pixels[offset]}, ${pixels[offset + 1]}, ${pixels[offset + 2]})`
+        : "transparent";
+      cells.push({ key: `${x}`, style: { width: cellSize, height: cellSize, backgroundColor } });
+    }
+    rows.push({ key: `${y}`, cells });
+  }
+  return rows;
+}
+
+const pictureStyles = StyleSheet.create({ row: { flexDirection: "row" } });
+
+function useStyles(theme: PluginWorkspacePanelProps["theme"], compact: boolean) {
+  return useMemo(
+    () =>
+      StyleSheet.create({
+        screen: {
+          flex: 1,
+          padding: compact ? 16 : 24,
+          gap: 12,
+          backgroundColor: theme.colors.surface0,
+        },
+        title: { color: theme.colors.foreground, fontSize: 18, fontWeight: "600" },
+        muted: { color: theme.colors.foregroundMuted },
+        meterTrack: {
+          height: 8,
+          borderRadius: 4,
+          overflow: "hidden",
+          backgroundColor: theme.colors.surface2,
+        },
+        meter: { height: 8, backgroundColor: theme.colors.accent },
+        upload: { gap: 8, alignItems: "flex-start" },
+        button: {
+          paddingVertical: 8,
+          paddingHorizontal: 14,
+          borderRadius: 8,
+          backgroundColor: theme.colors.accent,
+        },
+        buttonText: { color: theme.colors.accentForeground },
+      }),
+    [theme, compact],
+  );
+}
diff --git a/plugin-examples/media-stream/index.client.tsx b/plugin-examples/media-stream/index.client.tsx
new file mode 100644
index 0000000000..a8532b8d46
--- /dev/null
+++ b/plugin-examples/media-stream/index.client.tsx
@@ -0,0 +1,22 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { MediaPanel } from "./client/media-panel";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "media",
+    title: "Media stream",
+    icon: "MonitorPlay",
+    context: "workspace",
+    Component: MediaPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-media",
+    title: "Open media stream",
+    icon: "MonitorPlay",
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel("media");
+    },
+  });
+  return () => {};
+}
diff --git a/plugin-examples/media-stream/index.server.ts b/plugin-examples/media-stream/index.server.ts
new file mode 100644
index 0000000000..32c97f8192
--- /dev/null
+++ b/plugin-examples/media-stream/index.server.ts
@@ -0,0 +1,27 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { describeFrame } from "./server/frame-check";
+import { openTestPattern } from "./server/test-pattern";
+import { checkFrame } from "./shared/frame-check";
+import { encodeMediaFrame, MediaOpcode, mediaStream } from "./shared/media-frames";
+
+export default function contribute(server: PluginServerContext) {
+  // Two streams share one subscription; each frame's opcode says which one it belongs to.
+  server.handle(mediaStream, (_input, { push, signal }) => {
+    const source = openTestPattern({
+      video: (pixels, timestampMs, keyframe) =>
+        void push(
+          encodeMediaFrame({
+            opcode: keyframe ? MediaOpcode.Keyframe : MediaOpcode.Video,
+            timestampMs,
+            payload: pixels,
+          }),
+        ),
+      audio: (samples, timestampMs) =>
+        void push(encodeMediaFrame({ opcode: MediaOpcode.Audio, timestampMs, payload: samples })),
+    });
+    signal.addEventListener("abort", () => source.close(), { once: true });
+  });
+  // A Uint8Array input arrives as the bytes the panel sent.
+  server.handle(checkFrame, describeFrame);
+  return () => {};
+}
diff --git a/plugin-examples/media-stream/paseo-plugin.json b/plugin-examples/media-stream/paseo-plugin.json
new file mode 100644
index 0000000000..1a9eb4106a
--- /dev/null
+++ b/plugin-examples/media-stream/paseo-plugin.json
@@ -0,0 +1,6 @@
+{
+  "id": "media-stream",
+  "requirements": {
+    "paseo": ">=0.15.0-beta.2"
+  }
+}
diff --git a/plugin-examples/media-stream/server/frame-check.ts b/plugin-examples/media-stream/server/frame-check.ts
new file mode 100644
index 0000000000..0d25d19797
--- /dev/null
+++ b/plugin-examples/media-stream/server/frame-check.ts
@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { checkFrame } from "../shared/frame-check";
+
+export function describeFrame(frame: RpcInput<typeof checkFrame>): RpcOutput<typeof checkFrame> {
+  return { bytes: frame.byteLength, sha256: createHash("sha256").update(frame).digest("hex") };
+}
diff --git a/plugin-examples/media-stream/server/test-pattern.ts b/plugin-examples/media-stream/server/test-pattern.ts
new file mode 100644
index 0000000000..4bc05af827
--- /dev/null
+++ b/plugin-examples/media-stream/server/test-pattern.ts
@@ -0,0 +1,44 @@
+import { AUDIO, VIDEO } from "../shared/media-frames";
+
+export interface MediaSourceHandlers {
+  video(pixels: Uint8Array, timestampMs: number, keyframe: boolean): void;
+  audio(samples: Uint8Array, timestampMs: number): void;
+}
+
+/** A synthetic source: a moving gradient and a tone that rises and falls. */
+export function openTestPattern(handlers: MediaSourceHandlers): { close(): void } {
+  const started = Date.now();
+  let frame = 0;
+  let sample = 0;
+  const video = setInterval(() => {
+    const pixels = new Uint8Array(VIDEO.width * VIDEO.height * 3);
+    for (let y = 0; y < VIDEO.height; y += 1)
+      for (let x = 0; x < VIDEO.width; x += 1) {
+        const offset = (y * VIDEO.width + x) * 3;
+        pixels[offset] = ((x + frame) * 16) % 256;
+        pixels[offset + 1] = (y * 28) % 256;
+        pixels[offset + 2] = ((x + y + frame) * 8) % 256;
+      }
+    handlers.video(pixels, Date.now() - started, frame % VIDEO.keyframeInterval === 0);
+    frame += 1;
+  }, 1000 / VIDEO.framesPerSecond);
+  const audio = setInterval(() => {
+    const count = (AUDIO.sampleRate * AUDIO.chunkMs) / 1000;
+    const samples = new Uint8Array(count * 2);
+    const view = new DataView(samples.buffer);
+    const amplitude = 8000 + 7000 * Math.sin((Date.now() - started) / 700);
+    for (let index = 0; index < count; index += 1, sample += 1)
+      view.setInt16(
+        index * 2,
+        amplitude * Math.sin((2 * Math.PI * 440 * sample) / AUDIO.sampleRate),
+        true,
+      );
+    handlers.audio(samples, Date.now() - started);
+  }, AUDIO.chunkMs);
+  return {
+    close() {
+      clearInterval(video);
+      clearInterval(audio);
+    },
+  };
+}
diff --git a/plugin-examples/media-stream/shared/frame-check.ts b/plugin-examples/media-stream/shared/frame-check.ts
new file mode 100644
index 0000000000..1492bc347d
--- /dev/null
+++ b/plugin-examples/media-stream/shared/frame-check.ts
@@ -0,0 +1,9 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/** Sends one frame back to the daemon, which reports what arrived. */
+export const checkFrame = defineRpc({
+  name: "media.frame.check",
+  input: z.instanceof(Uint8Array),
+  output: z.object({ bytes: z.number(), sha256: z.string() }),
+});
diff --git a/plugin-examples/media-stream/shared/media-frames.ts b/plugin-examples/media-stream/shared/media-frames.ts
new file mode 100644
index 0000000000..761c41ed89
--- /dev/null
+++ b/plugin-examples/media-stream/shared/media-frames.ts
@@ -0,0 +1,47 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/** The first byte of every frame says which stream it belongs to. */
+export const MediaOpcode = { Video: 0x01, Audio: 0x02, Keyframe: 0x03 } as const;
+
+export type MediaFrame =
+  | {
+      opcode: typeof MediaOpcode.Video | typeof MediaOpcode.Keyframe;
+      timestampMs: number;
+      payload: Uint8Array;
+    }
+  | { opcode: typeof MediaOpcode.Audio; timestampMs: number; payload: Uint8Array };
+
+const HEADER_BYTES = 1 + 8;
+
+/** `[opcode u8][timestampMs f64][payload]` */
+export function encodeMediaFrame(frame: MediaFrame): Uint8Array {
+  const bytes = new Uint8Array(HEADER_BYTES + frame.payload.byteLength);
+  bytes[0] = frame.opcode;
+  new DataView(bytes.buffer).setFloat64(1, frame.timestampMs);
+  bytes.set(frame.payload, HEADER_BYTES);
+  return bytes;
+}
+
+/** Returns a view into `bytes`; the payload is not copied. */
+export function decodeMediaFrame(bytes: Uint8Array): MediaFrame | null {
+  if (bytes.byteLength < HEADER_BYTES) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const opcode = bytes[0];
+  const timestampMs = view.getFloat64(1);
+  const payload = bytes.subarray(HEADER_BYTES);
+  if (opcode === MediaOpcode.Audio) return { opcode, timestampMs, payload };
+  if (opcode === MediaOpcode.Video || opcode === MediaOpcode.Keyframe)
+    return { opcode, timestampMs, payload };
+  return null;
+}
+
+/** A video frame is `width * height` RGB pixels; audio is signed 16-bit mono PCM. */
+export const VIDEO = { width: 16, height: 9, framesPerSecond: 15, keyframeInterval: 30 } as const;
+export const AUDIO = { sampleRate: 8000, chunkMs: 20 } as const;
+
+export const mediaStream = defineSubscription({
+  name: "media.stream",
+  input: z.object({ source: z.enum(["test-pattern"]) }),
+  event: z.instanceof(Uint8Array),
+});
diff --git a/plugin-examples/new-workspace-issues/README.md b/plugin-examples/new-workspace-issues/README.md
new file mode 100644
index 0000000000..3ad55f49ca
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/README.md
@@ -0,0 +1,17 @@
+# New workspace issues
+
+Install this directory as a plugin and open New workspace. An **Issue** field appears beside the
+project, host, and branch pickers: a field on a phone, a badge on desktop.
+
+Choosing an issue:
+
+- Calls `newWorkspace.setBranch(issue.branch)`, so a worktree is created on that branch name.
+- Calls `newWorkspace.setMetadata({ "new-workspace-issues.issue": issue.id })`, so the created
+  workspace carries the issue id.
+
+`Combobox` runs `search` when the list opens and again as the user types. Paseo shows the loading
+and error states and drops results that a newer search replaced. The server handler in
+[server/issues.ts](server/issues.ts) filters a fixed list; a real plugin would call its tracker.
+
+[client/issue-field.tsx](client/issue-field.tsx) is the field; [index.client.tsx](index.client.tsx)
+registers it with `addNewWorkspaceItem`.
diff --git a/plugin-examples/new-workspace-issues/client/issue-field.tsx b/plugin-examples/new-workspace-issues/client/issue-field.tsx
new file mode 100644
index 0000000000..3786a1128f
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/client/issue-field.tsx
@@ -0,0 +1,31 @@
+import { useCallback, useMemo } from "react";
+import { useNewWorkspace, useRpc } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc, type Issue } from "../shared/issues";
+
+const ISSUE_KEY = "new-workspace-issues.issue";
+
+/** Starts the workspace on the issue's branch and records which issue it is for. */
+export function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata[ISSUE_KEY];
+  const value = useMemo(
+    () => (typeof issueId === "string" ? { id: issueId, label: issueId } : null),
+    [issueId],
+  );
+  const search = useCallback(
+    async ({ query }: { query: string }) => (await searchIssues({ query })).issues,
+    [searchIssues],
+  );
+  const select = useCallback(
+    async ({ item }: { item: Issue }) => {
+      await newWorkspace.setBranch(item.branch);
+      await newWorkspace.setMetadata({ [ISSUE_KEY]: item.id });
+    },
+    [newWorkspace],
+  );
+  return (
+    <Combobox title="Issue" icon="CircleDot" value={value} search={search} onSelect={select} />
+  );
+}
diff --git a/plugin-examples/new-workspace-issues/index.client.tsx b/plugin-examples/new-workspace-issues/index.client.tsx
new file mode 100644
index 0000000000..1d1132923e
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/index.client.tsx
@@ -0,0 +1,7 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { IssueField } from "./client/issue-field";
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}
diff --git a/plugin-examples/new-workspace-issues/index.server.ts b/plugin-examples/new-workspace-issues/index.server.ts
new file mode 100644
index 0000000000..544ab0081c
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/index.server.ts
@@ -0,0 +1,8 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { searchIssues } from "./server/issues";
+import { searchIssuesRpc } from "./shared/issues";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(searchIssuesRpc, searchIssues);
+  return () => {};
+}
diff --git a/plugin-examples/new-workspace-issues/paseo-plugin.json b/plugin-examples/new-workspace-issues/paseo-plugin.json
new file mode 100644
index 0000000000..7a1bb2513d
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "new-workspace-issues-example",
+  "requirements": { "paseo": ">=0.8.0" }
+}
diff --git a/plugin-examples/new-workspace-issues/server/issues.ts b/plugin-examples/new-workspace-issues/server/issues.ts
new file mode 100644
index 0000000000..a89ea0e3e3
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/server/issues.ts
@@ -0,0 +1,26 @@
+import type { RpcInput } from "@getpaseo/plugin";
+import { searchIssuesRpc, type Issue } from "../shared/issues";
+
+// A real plugin would ask its tracker. A fixed list keeps the example self-contained.
+const ISSUES: Issue[] = [
+  {
+    id: "PAS-101",
+    label: "PAS-101 Slow sidebar",
+    description: "Lists lag at 200 rows",
+    branch: "pas-101-slow-sidebar",
+  },
+  {
+    id: "PAS-102",
+    label: "PAS-102 Crash on resume",
+    description: "Agent resume throws",
+    branch: "pas-102-crash-on-resume",
+  },
+  { id: "PAS-103", label: "PAS-103 Dark theme contrast", branch: "pas-103-dark-theme-contrast" },
+];
+
+export async function searchIssues({ query }: RpcInput<typeof searchIssuesRpc>) {
+  const needle = query.trim().toLowerCase();
+  return {
+    issues: ISSUES.filter((issue) => issue.label.toLowerCase().includes(needle)),
+  };
+}
diff --git a/plugin-examples/new-workspace-issues/shared/issues.ts b/plugin-examples/new-workspace-issues/shared/issues.ts
new file mode 100644
index 0000000000..3f04c5afff
--- /dev/null
+++ b/plugin-examples/new-workspace-issues/shared/issues.ts
@@ -0,0 +1,18 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const IssueSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  /** The branch the issue's work goes on. */
+  branch: z.string(),
+});
+
+export type Issue = z.infer<typeof IssueSchema>;
+
+export const searchIssuesRpc = defineRpc({
+  name: "issues.search",
+  input: z.object({ query: z.string() }),
+  output: z.object({ issues: z.array(IssueSchema) }),
+});
diff --git a/plugin-examples/provider-direct/README.md b/plugin-examples/provider-direct/README.md
index 8bd5921330..dd360ac159 100644
--- a/plugin-examples/provider-direct/README.md
+++ b/plugin-examples/provider-direct/README.md
@@ -1,7 +1,8 @@
 # Direct provider example
 
 This plugin implements `ProviderRegistration` directly. It demonstrates connection negotiation,
-catalog and session listing, session creation, prompt and command disposition, settings,
+catalog and session listing, session creation, prompt and command disposition, option controls
+with icons (`controls` and `providerOptions`),
 persistence and replay, archive actions, and an ordinary child session.
 
 The provider emits versioned `provider-result` timeline items for its root and child sessions.
diff --git a/plugin-examples/provider-direct/server/provider.test.ts b/plugin-examples/provider-direct/server/provider.test.ts
index db7282df86..3fbbbdb35e 100644
--- a/plugin-examples/provider-direct/server/provider.test.ts
+++ b/plugin-examples/provider-direct/server/provider.test.ts
@@ -40,7 +40,7 @@ describe("direct provider example", () => {
     await connection.close();
   });
 
-  it("demonstrates settings, commands, persistence, and provider-rendered timeline items", async () => {
+  it("demonstrates option controls, commands, persistence, and provider-rendered timeline items", async () => {
     const connection = await createDirectExampleProvider().connect({
       versions: [1],
       capabilities: [
@@ -65,8 +65,8 @@ describe("direct provider example", () => {
         mcpServers: {},
         model: "example-1",
         mode: "build",
-        settings: { concise: true, voice: "calm" },
-        providerOptions: { privateValue: 1 },
+        settings: {},
+        providerOptions: { concise: true, voice: "calm", privateValue: 1 },
         persist: true,
       },
       history: "skip",
@@ -75,10 +75,11 @@ describe("direct provider example", () => {
       expect.objectContaining({
         type: "session.config",
         config: expect.objectContaining({
-          settings: expect.arrayContaining([
-            expect.objectContaining({ id: "concise", value: true }),
-            expect.objectContaining({ id: "voice", value: "calm" }),
-          ]),
+          controls: [
+            expect.objectContaining({ key: "concise", icon: "Zap" }),
+            expect.objectContaining({ key: "voice", icon: "Mic", defaultValue: "calm" }),
+          ],
+          providerOptions: { concise: true, voice: "calm" },
         }),
       }),
     );
@@ -88,7 +89,29 @@ describe("direct provider example", () => {
       type: "session.configure",
       requestId: "configure-complete",
       sessionId: "session-complete",
-      changes: { settings: { voice: "direct" } },
+      changes: { providerOptions: { voice: "direct", concise: null } },
+    });
+    expect(events.findLast((event) => event.type === "session.config")).toMatchObject({
+      config: { providerOptions: { voice: "direct" } },
+    });
+    await connection.send({
+      type: "session.configure",
+      requestId: "configure-refused",
+      sessionId: "session-complete",
+      changes: { model: "other-model", providerOptions: { voice: "loud" } },
+    });
+    expect(events).toContainEqual(
+      expect.objectContaining({ type: "request.failed", requestId: "configure-refused" }),
+    );
+    // A refused request changes nothing, the model it named included.
+    await connection.send({
+      type: "session.configure",
+      requestId: "configure-after-refused",
+      sessionId: "session-complete",
+      changes: {},
+    });
+    expect(events.findLast((event) => event.type === "session.config")).not.toMatchObject({
+      config: { model: "other-model" },
     });
     await connection.send({
       type: "session.prompt",
diff --git a/plugin-examples/provider-direct/server/provider.ts b/plugin-examples/provider-direct/server/provider.ts
index 31ea177dd6..d4c83bf3a1 100644
--- a/plugin-examples/provider-direct/server/provider.ts
+++ b/plugin-examples/provider-direct/server/provider.ts
@@ -1,7 +1,9 @@
 import {
   negotiateProviderCapabilities,
   requireProviderCapabilities,
+  type ProviderConfigChanges,
   type ProviderConfigState,
+  type ProviderOptionControl,
   type ProviderConnection,
   type ProviderEvent,
   type ProviderInput,
@@ -25,8 +27,29 @@ const CAPABILITIES = [
   "timeline.plugin",
 ] as const;
 
+const VOICES = [
+  { value: "calm", label: "Calm" },
+  { value: "direct", label: "Direct" },
+];
+
+// Which option keys get a composer control. The control holds no value: Paseo reads it from
+// `providerOptions`, in a draft as well as on a running session.
+const CONTROLS: ProviderOptionControl[] = [
+  { type: "toggle", key: "concise", label: "Concise responses", icon: "Zap" },
+  {
+    type: "select",
+    key: "voice",
+    label: "Voice",
+    icon: "Mic",
+    defaultValue: "calm",
+    choices: VOICES,
+  },
+];
+
 interface ExampleSession {
   config: ProviderSessionConfig;
+  /** What the session runs with. A key with no value runs its default. */
+  options: { concise?: boolean; voice?: string };
   persistence: ProviderPersistence;
   turn: number;
   activeTurnId: string | null;
@@ -175,8 +198,13 @@ function openSession(
     version: 1,
     data: { nativeSessionId: `example:${input.sessionId}` },
   };
+  const { concise, voice } = input.config.providerOptions ?? {};
   const session: ExampleSession = {
     config: input.config,
+    options: {
+      ...(typeof concise === "boolean" ? { concise } : {}),
+      ...(VOICES.some((candidate) => candidate.value === voice) ? { voice: voice as string } : {}),
+    },
     persistence,
     turn: 0,
     activeTurnId: null,
@@ -344,6 +372,19 @@ function configureSession(
 ): void {
   const session = requireSession(state, input.sessionId);
   const changes = input.changes;
+  // Work out everything first, so a refused request changes nothing.
+  let options: ExampleSession["options"];
+  try {
+    options = applyOptions(session.options, changes.providerOptions ?? {});
+  } catch (error) {
+    state.emit({
+      type: "request.failed",
+      requestId: input.requestId,
+      error: { message: error instanceof Error ? error.message : String(error) },
+    });
+    return;
+  }
+  session.options = options;
   session.config = {
     ...session.config,
     model: changes.model === null ? undefined : (changes.model ?? session.config.model),
@@ -352,14 +393,31 @@ function configureSession(
       changes.thinkingOption === null
         ? undefined
         : (changes.thinkingOption ?? session.config.thinkingOption),
-    settings: changes.settings
-      ? { ...session.config.settings, ...changes.settings }
-      : session.config.settings,
   };
   state.emit({ type: "session.config", sessionId: input.sessionId, config: configState(session) });
   state.emit({ type: "request.completed", requestId: input.requestId });
 }
 
+/** Apply the whole patch or throw. `null` returns a key to its default. */
+function applyOptions(
+  options: ExampleSession["options"],
+  patch: NonNullable<ProviderConfigChanges["providerOptions"]>,
+): ExampleSession["options"] {
+  const next = { ...options };
+  for (const [key, value] of Object.entries(patch)) {
+    if (key === "concise" && (value === null || typeof value === "boolean")) {
+      if (value === null) delete next.concise;
+      else next.concise = value;
+    } else if (key === "voice" && (value === null || VOICES.some((v) => v.value === value))) {
+      if (value === null) delete next.voice;
+      else next.voice = value as string;
+    } else {
+      throw new Error(`Cannot set ${key} to ${JSON.stringify(value)}`);
+    }
+  }
+  return next;
+}
+
 function configState(session: ExampleSession): ProviderConfigState {
   return {
     model: session.config.model ?? "example-1",
@@ -368,25 +426,9 @@ function configState(session: ExampleSession): ProviderConfigState {
     models: [{ id: "example-1", label: "Example 1" }],
     modes: [{ id: "build", label: "Build" }],
     thinkingOptions: [],
-    settings: [
-      {
-        type: "toggle",
-        id: "concise",
-        label: "Concise responses",
-        value: session.config.settings.concise === true,
-      },
-      {
-        type: "select",
-        id: "voice",
-        label: "Voice",
-        value:
-          typeof session.config.settings.voice === "string" ? session.config.settings.voice : null,
-        options: [
-          { label: "Calm", value: "calm" },
-          { label: "Direct", value: "direct" },
-        ],
-      },
-    ],
+    controls: CONTROLS,
+    // What the session ended up with, so Paseo stores what runs.
+    providerOptions: { ...session.options },
   };
 }
 
diff --git a/plugin-examples/settings/README.md b/plugin-examples/settings/README.md
index 45a896d63e..130ee94571 100644
--- a/plugin-examples/settings/README.md
+++ b/plugin-examples/settings/README.md
@@ -1,7 +1,7 @@
 # Settings example
 
 Install this directory with `paseo plugin install /absolute/path/to/plugin-examples/settings`.
-Open Settings → Plugins → settings-example → Display, or run **Configure agent monitor** in Command Center.
+Open Settings → Plugins and press the settings button (cog) on the settings-example row, or run **Configure agent monitor** in Command Center.
 
 The select and switch save immediately. The title editor keeps a draft and its original revision,
 so another client's save produces a conflict instead of overwriting its changes. Close and reopen
diff --git a/plugin-examples/sidebar-views/client/agents.tsx b/plugin-examples/sidebar-views/client/agents.tsx
new file mode 100644
index 0000000000..8d0d469121
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/agents.tsx
@@ -0,0 +1,34 @@
+import type { PluginAgentSnapshot } from "@getpaseo/plugin";
+import { ScrollView, View } from "react-native";
+import { useAgents, type PluginSidebarViewProps } from "@getpaseo/plugin/client";
+import { AgentRow, Heading } from "./rows";
+export function agentTask(agent: PluginAgentSnapshot) {
+  if (agent.attentionReason === "permission") return "Respond";
+  if (agent.requiresAttention || agent.status === "error") return "Review";
+  if (agent.status === "running" || agent.status === "initializing") return "Wait";
+  return "Start";
+}
+function Task({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => agentTask(item) === title,
+    orderBy: ["lastActivityAt", "desc"],
+  });
+  return (
+    <View>
+      <Heading title={title} view={view} />
+      {agents.map((reference) => (
+        <AgentRow key={reference.key} reference={reference} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Agents(view: PluginSidebarViewProps) {
+  return (
+    <ScrollView>
+      <Task title="Respond" view={view} />
+      <Task title="Review" view={view} />
+      <Task title="Wait" view={view} />
+      <Task title="Start" view={view} />
+    </ScrollView>
+  );
+}
diff --git a/plugin-examples/sidebar-views/client/labels.tsx b/plugin-examples/sidebar-views/client/labels.tsx
new file mode 100644
index 0000000000..da2e1ae7ab
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/labels.tsx
@@ -0,0 +1,191 @@
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import {
+  usePaseo,
+  useSettings,
+  useWorkspaces,
+  type WorkspaceRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { folders } from "../shared/preferences";
+import { Heading, WorkspaceRow } from "./rows";
+interface Move {
+  reference: WorkspaceRef;
+  from: string | null;
+}
+function folderLabel(key: string): string | null {
+  return key === "unlabelled" ? null : key.slice("label:".length);
+}
+function Movable({
+  reference,
+  folder,
+  view,
+  select,
+}: {
+  reference: WorkspaceRef;
+  folder: string | null;
+  view: PluginSidebarViewProps;
+  select: (move: Move) => void;
+}) {
+  const pick = useCallback(() => select({ reference, from: folder }), [select, reference, folder]);
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} onLongPress={pick} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Move workspace ${reference.id}`}
+        onPress={pick}
+      >
+        <Heading title="Move…" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+export function Labels(view: PluginSidebarViewProps) {
+  const paseo = usePaseo();
+  const settings = useSettings(folders);
+  const [selected, select] = useState<Move | null>(null);
+  const groups = useWorkspaces({
+    orderBy: "name",
+    groupBy: (item) =>
+      item.labels.length ? item.labels.map((label) => `label:${label}`) : ["unlabelled"],
+  });
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, paddingHorizontal: 12 }),
+    [view.theme],
+  );
+  const move = useMutation({
+    mutationFn: async (destination: string | null) => {
+      if (!selected) return;
+      const workspace = paseo.workspaces.ref(selected.reference);
+      // Add first: if adding fails the workspace keeps its original folder.
+      if (destination && destination !== selected.from)
+        await workspace.setLabel(destination, { assigned: true });
+      if (selected.from && selected.from !== destination)
+        await workspace.setLabel(selected.from, { assigned: false });
+      select(null);
+    },
+  });
+  const toggle = useCallback(
+    (folder: string) => {
+      if (settings.status !== "ready") return;
+      void settings.save(
+        {
+          collapsed: settings.values.collapsed.includes(folder)
+            ? settings.values.collapsed.filter((item) => item !== folder)
+            : [...settings.values.collapsed, folder],
+        },
+        settings.revision,
+      );
+    },
+    [settings],
+  );
+  const cancel = useCallback(() => select(null), []);
+  if (settings.status === "loading") return <Text style={style}>Loading folders…</Text>;
+  if (settings.status !== "ready")
+    return (
+      <View>
+        <Text style={style}>{settings.error}</Text>
+        <Pressable accessibilityRole="button" onPress={settings.reload}>
+          <Heading title="Reload folders" view={view} />
+        </Pressable>
+        {settings.status === "invalid" ? (
+          <Pressable accessibilityRole="button" onPress={settings.reset}>
+            <Heading title="Reset folders" view={view} />
+          </Pressable>
+        ) : null}
+      </View>
+    );
+  return (
+    <ScrollView>
+      {selected ? (
+        <View>
+          <Text style={style}>Choose a destination folder</Text>
+          <Pressable accessibilityRole="button" onPress={cancel}>
+            <Heading title="Cancel move" view={view} />
+          </Pressable>
+        </View>
+      ) : (
+        <Text style={style}>Long press a workspace or choose Move…</Text>
+      )}
+      {move.error ? <Text style={style}>{move.error.message}</Text> : null}
+      {Array.from(
+        new Set(["label:Inbox", "label:Later", "unlabelled", ...groups.map((group) => group.key)]),
+      ).map((folder) => (
+        <Folder
+          key={folder}
+          folder={folder}
+          view={view}
+          selected={!!selected}
+          pending={move.isPending}
+          move={move.mutate}
+          collapsed={settings.values.collapsed.includes(folder)}
+          toggle={toggle}
+        >
+          {groups
+            .find((group) => group.key === folder)
+            ?.items.map((reference) => (
+              <Movable
+                key={reference.key}
+                reference={reference}
+                folder={folderLabel(folder)}
+                view={view}
+                select={select}
+              />
+            ))}
+        </Folder>
+      ))}
+      {settings.saveError ? <Text style={style}>{settings.saveError}</Text> : null}
+    </ScrollView>
+  );
+}
+function Folder({
+  folder,
+  view,
+  selected,
+  pending,
+  move,
+  collapsed,
+  toggle,
+  children,
+}: {
+  folder: string;
+  view: PluginSidebarViewProps;
+  selected: boolean;
+  pending: boolean;
+  move: (folder: string | null) => void;
+  collapsed: boolean;
+  toggle: (folder: string) => void;
+  children: import("react").ReactNode;
+}) {
+  const toggleFolder = useCallback(() => toggle(folder), [toggle, folder]);
+  const label = folderLabel(folder);
+  const title = label ?? "Unlabelled";
+  const destination = useCallback(() => move(label), [move, label]);
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Toggle ${title}`}
+        onPress={toggleFolder}
+      >
+        <Heading title={`${collapsed ? "▸" : "▾"} ${title}`} view={view} />
+      </Pressable>
+      {selected ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={label === null ? "Remove current label" : `Move to ${title}`}
+          disabled={pending}
+          onPress={destination}
+        >
+          <Heading
+            title={label === null ? "Remove current label" : `Move to ${title}`}
+            view={view}
+          />
+        </Pressable>
+      ) : null}
+      {collapsed ? null : children}
+    </View>
+  );
+}
diff --git a/plugin-examples/sidebar-views/client/nested.tsx b/plugin-examples/sidebar-views/client/nested.tsx
new file mode 100644
index 0000000000..b6f4b84eb3
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/nested.tsx
@@ -0,0 +1,109 @@
+import { ScrollView, View } from "react-native";
+import {
+  useProjects,
+  useWorkspaces,
+  useAgents,
+  useAgent,
+  type AgentRef,
+  type WorkspaceRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { AgentRow, ProjectHeading, WorkspaceRow } from "./rows";
+const indent = { paddingLeft: 12 };
+function AgentTree({ reference, view }: { reference: AgentRef; view: PluginSidebarViewProps }) {
+  const agent = useAgent(reference);
+  const children = useAgents({
+    where: (item) =>
+      item.parentAgent?.key === reference.key && item.workspace.key === agent?.workspace.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <AgentRow reference={reference} view={view} />
+      <View style={indent}>
+        {children.map((child) => (
+          <AgentTree key={child.key} reference={child} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function RootWithParent({
+  reference,
+  parent,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  parent: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const parents = useAgents({
+    where: (item) => item.ref.key === parent.key && item.workspace.key === workspace.key,
+  });
+  return parents.length > 0 ? null : <AgentTree reference={reference} view={view} />;
+}
+function Root({
+  reference,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  if (!agent) return null;
+  return agent.parentAgent ? (
+    <RootWithParent
+      reference={reference}
+      parent={agent.parentAgent}
+      workspace={workspace}
+      view={view}
+    />
+  ) : (
+    <AgentTree reference={reference} view={view} />
+  );
+}
+function Workspace({ reference, view }: { reference: WorkspaceRef; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => item.workspace.key === reference.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} />
+      <View style={indent}>
+        {agents.map((agent) => (
+          <Root key={agent.key} reference={agent} workspace={reference} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key,
+    orderBy: "name",
+  });
+  return (
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <Workspace key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Nested(view: PluginSidebarViewProps) {
+  const projects = useProjects({ orderBy: "displayName" });
+  return (
+    <ScrollView>
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
+    </ScrollView>
+  );
+}
diff --git a/plugin-examples/sidebar-views/client/rows.tsx b/plugin-examples/sidebar-views/client/rows.tsx
new file mode 100644
index 0000000000..ef55333f15
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/rows.tsx
@@ -0,0 +1,139 @@
+import { useCallback, useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+import {
+  useWorkspace,
+  useAgent,
+  useProject,
+  type WorkspaceRef,
+  type AgentRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+
+export function Heading({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const style = useMemo(
+    () => ({
+      color: view.theme.colors.foregroundMuted,
+      fontSize: 11,
+      paddingHorizontal: 12,
+      paddingTop: 12,
+      paddingBottom: 4,
+    }),
+    [view.theme],
+  );
+  return (
+    <Text accessibilityRole="header" style={style}>
+      {title}
+    </Text>
+  );
+}
+export function WorkspaceRow({
+  reference,
+  view,
+  onLongPress,
+}: {
+  reference: WorkspaceRef;
+  view: PluginSidebarViewProps;
+  onLongPress?: () => void;
+}) {
+  const workspace = useWorkspace(reference);
+  const open = useCallback(
+    () => view.navigation.openWorkspace(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12, lineHeight: 16 }),
+    [view.theme],
+  );
+  const detail = useMemo(
+    () => ({ color: view.theme.colors.foregroundMuted, fontSize: 11 }),
+    [view.theme],
+  );
+  const background = useMemo(
+    () => ({
+      ...rowStyle,
+      backgroundColor:
+        view.active.workspace?.key === reference.key ? view.theme.colors.surface2 : undefined,
+    }),
+    [view.active.workspace, view.theme, reference],
+  );
+  if (!workspace) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open ${workspace.title ?? workspace.name}`}
+      onPress={open}
+      onLongPress={onLongPress}
+      style={background}
+    >
+      <Text numberOfLines={1} style={style}>
+        {workspace.title ?? workspace.name}
+      </Text>
+      <Text numberOfLines={1} style={detail}>
+        {workspace.indicatorLabel}
+      </Text>
+    </Pressable>
+  );
+}
+export function AgentRow({
+  reference,
+  view,
+}: {
+  reference: AgentRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  const open = useCallback(
+    () => view.navigation.openAgent(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12 }),
+    [view.theme],
+  );
+  if (!agent) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open agent ${agent.title ?? agent.provider}`}
+      onPress={open}
+      style={rowStyle}
+    >
+      <Text numberOfLines={1} style={style}>
+        {agent.title ?? agent.provider}
+      </Text>
+    </Pressable>
+  );
+}
+export function ProjectHeading({
+  reference,
+  view,
+}: {
+  reference: ProjectRef;
+  view: PluginSidebarViewProps;
+}) {
+  const project = useProject(reference);
+  const open = useCallback(
+    () => view.navigation.openProject(reference),
+    [view.navigation, reference],
+  );
+  if (!project) return null;
+  return (
+    <View>
+      <Heading title={project.displayName} view={view} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`New workspace in ${project.displayName}`}
+        onPress={open}
+      >
+        <Heading title="+ New workspace" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+const rowStyle = {
+  minHeight: 28,
+  paddingHorizontal: 12,
+  paddingVertical: 4,
+  justifyContent: "center",
+} as const;
diff --git a/plugin-examples/sidebar-views/client/terminals.tsx b/plugin-examples/sidebar-views/client/terminals.tsx
new file mode 100644
index 0000000000..2106e12130
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/terminals.tsx
@@ -0,0 +1,131 @@
+import { Component, useCallback, useMemo, useState, type ReactNode } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import { useMutation } from "@tanstack/react-query";
+import {
+  useHosts,
+  useTerminals,
+  useTerminal,
+  usePaseo,
+  type TerminalRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { Heading } from "./rows";
+
+class TerminalError extends Component<{ children: ReactNode }, { error: Error | null }> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  render() {
+    return this.state.error ? <Text>{this.state.error.message}</Text> : this.props.children;
+  }
+}
+function TerminalRow({
+  reference,
+  view,
+}: {
+  reference: TerminalRef;
+  view: PluginSidebarViewProps;
+}) {
+  const terminal = useTerminal(reference);
+  const paseo = usePaseo();
+  const focus = useCallback(() => paseo.terminals.ref(reference).focus(), [paseo, reference]);
+  const close = useMutation({ mutationFn: () => paseo.terminals.ref(reference).kill() });
+  const kill = useCallback(() => close.mutate(), [close]);
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12, padding: 12 }),
+    [view.theme],
+  );
+  if (!terminal) return null;
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Focus terminal ${terminal.title}`}
+        testID={`sidebar-terminal-open-${reference.id}`}
+        onPress={focus}
+      >
+        <Text style={style}>
+          {terminal.title}
+          {terminal.isScript ? " (script)" : ""}
+        </Text>
+      </Pressable>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Kill terminal ${terminal.title}`}
+        testID={`sidebar-terminal-kill-${reference.id}`}
+        disabled={close.isPending}
+        onPress={kill}
+      >
+        <Text style={style}>Close terminal</Text>
+      </Pressable>
+      {close.error ? <Text style={style}>{close.error.message}</Text> : null}
+    </View>
+  );
+}
+function HostTerminals({ hostId, view }: { hostId: string; view: PluginSidebarViewProps }) {
+  const terminals = useTerminals({ hosts: [hostId], orderBy: "createdAt" });
+  return (
+    <View>
+      {terminals.length ? (
+        terminals.map((reference) => (
+          <TerminalRow key={reference.key} reference={reference} view={view} />
+        ))
+      ) : (
+        <Heading title="No terminals" view={view} />
+      )}
+    </View>
+  );
+}
+function HostButton({
+  hostId,
+  label,
+  select,
+  view,
+}: {
+  hostId: string;
+  label: string;
+  select: (id: string) => void;
+  view: PluginSidebarViewProps;
+}) {
+  const choose = useCallback(() => select(hostId), [select, hostId]);
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Terminals on ${hostId}`}
+      onPress={choose}
+    >
+      <Heading title={label} view={view} />
+    </Pressable>
+  );
+}
+export function Terminals(view: PluginSidebarViewProps) {
+  const hosts = useHosts();
+  const [chosen, select] = useState<string | null>(null);
+  const selected = chosen;
+  return (
+    <ScrollView>
+      {hosts.map((host) => (
+        <HostButton
+          key={host.serverId}
+          hostId={host.serverId}
+          label={host.label}
+          select={select}
+          view={view}
+        />
+      ))}
+      {selected ? (
+        <TerminalError key={selected}>
+          <HostTerminals hostId={selected} view={view} />
+        </TerminalError>
+      ) : (
+        <Heading
+          title={
+            hosts.length ? "Choose a host to list terminals" : "Connect a host to list terminals"
+          }
+          view={view}
+        />
+      )}
+    </ScrollView>
+  );
+}
diff --git a/plugin-examples/sidebar-views/client/workspaces.tsx b/plugin-examples/sidebar-views/client/workspaces.tsx
new file mode 100644
index 0000000000..5c41eb4242
--- /dev/null
+++ b/plugin-examples/sidebar-views/client/workspaces.tsx
@@ -0,0 +1,37 @@
+import { ScrollView, View } from "react-native";
+import {
+  useProjects,
+  useWorkspaces,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { Heading, ProjectHeading, WorkspaceRow } from "./rows";
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key && !item.pinnedAt,
+    orderBy: "name",
+  });
+  return (
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <WorkspaceRow key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Workspaces(view: PluginSidebarViewProps) {
+  const projects = useProjects({ orderBy: "displayName" });
+  const pinned = useWorkspaces({ where: (item) => !!item.pinnedAt, orderBy: "name" });
+  return (
+    <ScrollView>
+      {pinned.length ? <Heading title="Pinned" view={view} /> : null}
+      {pinned.map((reference) => (
+        <WorkspaceRow key={reference.key} reference={reference} view={view} />
+      ))}
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
+    </ScrollView>
+  );
+}
diff --git a/plugin-examples/sidebar-views/index.client.tsx b/plugin-examples/sidebar-views/index.client.tsx
new file mode 100644
index 0000000000..3cf194c8a2
--- /dev/null
+++ b/plugin-examples/sidebar-views/index.client.tsx
@@ -0,0 +1,18 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { Workspaces } from "./client/workspaces";
+import { Agents } from "./client/agents";
+import { Nested } from "./client/nested";
+import { Terminals } from "./client/terminals";
+import { Labels } from "./client/labels";
+export default function contribute(client: PluginClientContext) {
+  const cleanups = [
+    client.addSidebarView({ id: "terminals", title: "Example terminals", Component: Terminals }),
+    client.addSidebarView({ id: "workspaces", title: "Example workspaces", Component: Workspaces }),
+    client.addSidebarView({ id: "agents", title: "Example agents", Component: Agents }),
+    client.addSidebarView({ id: "nested", title: "Example nested agents", Component: Nested }),
+    client.addSidebarView({ id: "labels", title: "Example label folders", Component: Labels }),
+  ];
+  return () => {
+    for (const cleanup of cleanups) void cleanup();
+  };
+}
diff --git a/plugin-examples/sidebar-views/paseo-plugin.json b/plugin-examples/sidebar-views/paseo-plugin.json
new file mode 100644
index 0000000000..1e66495a19
--- /dev/null
+++ b/plugin-examples/sidebar-views/paseo-plugin.json
@@ -0,0 +1,4 @@
+{
+  "id": "sidebar-views",
+  "requirements": { "paseo": ">=0.16.0" }
+}
diff --git a/plugin-examples/sidebar-views/shared/preferences.ts b/plugin-examples/sidebar-views/shared/preferences.ts
new file mode 100644
index 0000000000..69b65eb397
--- /dev/null
+++ b/plugin-examples/sidebar-views/shared/preferences.ts
@@ -0,0 +1,8 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+export const folders = defineSettings({
+  id: "folders",
+  scope: "device",
+  version: 1,
+  schema: z.object({ collapsed: z.array(z.string()).default([]) }),
+});
diff --git a/plugins/fx-provider/icon.svg b/plugins/fx-provider/icon.svg
new file mode 100644
index 0000000000..82849ca8d2
--- /dev/null
+++ b/plugins/fx-provider/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="166.241 0 155.861 155.75" fill="currentColor"><path d="M237.892 0C243.178 8.73262e-05 249.383 1.41857 253.025 3.07422L255.093 4.01367L250.076 18.6299L247.677 17.7461C244.901 16.7234 241.938 15.7998 238.491 15.7998C234.984 15.7998 232.787 16.5601 231.08 18.3213C229.231 20.2297 227.629 23.6395 226.229 29.7578L226.227 29.7617L226.228 29.7627L225.136 34.8506H241.669L260.432 34.9502L260.694 34.9512L260.842 35.1689L278.854 61.6328L296.736 34.9502H320.866L291.676 76.7402L322.102 119.75H299.331L299.182 119.546L241.144 40.4775L239.35 49.4004H222.069L205.688 127.208C203.927 135.709 201.185 142.838 196.777 147.866C192.27 153.008 186.201 155.75 178.342 155.75C174.181 155.75 170.746 155.109 167.909 154.107L166.241 153.519V137.182L166.899 137.4L169.531 138.278C172.182 139.162 174.414 139.8 177.142 139.8C178.528 139.8 179.703 139.526 180.732 138.98C181.764 138.434 182.677 137.6 183.52 136.442C185.304 133.989 186.716 130.135 187.897 124.672L203.76 49.4004H189.874L191.759 39.4375L192.039 39.3457L206.818 34.4668L208.154 28.6416C210.516 18.2065 213.772 10.9381 218.708 6.31836C223.737 1.61217 230.127 3.08752e-05 237.892 0ZM273.987 99.084L260.073 120.25H234.541L261.003 82.0215L273.987 99.084Z"/></svg>
diff --git a/plugins/fx-provider/index.server.ts b/plugins/fx-provider/index.server.ts
new file mode 100644
index 0000000000..564e989aba
--- /dev/null
+++ b/plugins/fx-provider/index.server.ts
@@ -0,0 +1,7 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { createFxProvider } from "./server/provider.js";
+
+export default function contribute(server: PluginServerContext) {
+  server.registerProvider(createFxProvider());
+  return () => {};
+}
diff --git a/plugins/fx-provider/paseo-plugin.json b/plugins/fx-provider/paseo-plugin.json
new file mode 100644
index 0000000000..2628ef32be
--- /dev/null
+++ b/plugins/fx-provider/paseo-plugin.json
@@ -0,0 +1 @@
+{ "id": "fx-provider", "requirements": { "paseo": ">=0.11.0" } }
diff --git a/plugins/fx-provider/server/file-tools.test.ts b/plugins/fx-provider/server/file-tools.test.ts
new file mode 100644
index 0000000000..23b4dafdee
--- /dev/null
+++ b/plugins/fx-provider/server/file-tools.test.ts
@@ -0,0 +1,47 @@
+import type { AcpToolCallSnapshot } from "@getpaseo/plugin/server/acp";
+import { describe, expect, it } from "vitest";
+import { fileToolTransformer } from "./file-tools.js";
+
+const context = { sessionId: "session-1" };
+
+// Shapes captured from `fx acp` 0.0.16.
+function fxToolCall(name: string, input: AcpToolCallSnapshot["input"]): AcpToolCallSnapshot {
+  return {
+    id: "call_1",
+    name,
+    title: "Writing",
+    kind: "edit",
+    status: "pending",
+    input,
+    output: null,
+    locations: [],
+  };
+}
+
+function transform(toolCall: AcpToolCallSnapshot): AcpToolCallSnapshot {
+  return fileToolTransformer.toolCall!(toolCall, context);
+}
+
+describe("fx file tool calls", () => {
+  it("presents write_file as a write to its path", () => {
+    expect(
+      transform(fxToolCall("write_file", { path: "hello.txt", content: "hi\n" })).input,
+    ).toEqual({ filePath: "hello.txt", newString: "hi\n" });
+  });
+
+  it("presents edit_file as a replacement in its path", () => {
+    expect(
+      transform(fxToolCall("edit_file", { path: "a.ts", old_string: "a", new_string: "b" })).input,
+    ).toEqual({ filePath: "a.ts", oldString: "a", newString: "b" });
+  });
+
+  it("keeps the presentation when a later update reaches the same call", () => {
+    const presented = transform(fxToolCall("write_file", { path: "hello.txt", content: "hi\n" }));
+    expect(transform({ ...presented, status: "completed" }).input).toEqual(presented.input);
+  });
+
+  it("leaves other tools alone", () => {
+    const shell = fxToolCall("shell", { path: "/tmp", command: "ls" });
+    expect(transform(shell)).toEqual(shell);
+  });
+});
diff --git a/plugins/fx-provider/server/file-tools.ts b/plugins/fx-provider/server/file-tools.ts
new file mode 100644
index 0000000000..e955b4b793
--- /dev/null
+++ b/plugins/fx-provider/server/file-tools.ts
@@ -0,0 +1,26 @@
+import type { AcpToolCallSnapshot, AcpTransformer } from "@getpaseo/plugin/server/acp";
+
+type ToolInput = AcpToolCallSnapshot["input"];
+
+// fx names its file arguments for the model (`path`, `old_string`), so its file tools need the
+// argument names Paseo's edit rows read. The adapter reapplies this to each update of a call.
+export const fileToolTransformer: AcpTransformer = {
+  toolCall(toolCall) {
+    const input = toEditRowInput(toolCall.name, toolCall.input);
+    return input ? { ...toolCall, input } : toolCall;
+  },
+};
+
+function toEditRowInput(tool: string | undefined, input: ToolInput): ToolInput | null {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
+  if (typeof input.path !== "string") return null;
+  if (tool === "write_file") return { filePath: input.path, newString: input.content ?? null };
+  if (tool === "edit_file") {
+    return {
+      filePath: input.path,
+      oldString: input.old_string ?? null,
+      newString: input.new_string ?? null,
+    };
+  }
+  return null;
+}
diff --git a/plugins/fx-provider/server/provider.ts b/plugins/fx-provider/server/provider.ts
new file mode 100644
index 0000000000..f7cc53526e
--- /dev/null
+++ b/plugins/fx-provider/server/provider.ts
@@ -0,0 +1,17 @@
+import { runAcpProvider } from "@getpaseo/plugin/server/acp";
+import type { ProviderRegistration } from "@getpaseo/plugin/server/provider";
+import { fileToolTransformer } from "./file-tools.js";
+
+export function createFxProvider(): ProviderRegistration {
+  return {
+    requiresConfiguration: true,
+    ...runAcpProvider({
+      id: "fx",
+      label: "fx",
+      description: "Vercel Labs' native coding agent through `fx acp`",
+      icon: "icon.svg",
+      command: ["fx", "acp"],
+      transformers: [fileToolTransformer],
+    }),
+  };
+}
diff --git a/plugins/package.json b/plugins/package.json
index aa09dfb568..902a1da3d0 100644
--- a/plugins/package.json
+++ b/plugins/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.14.0",
+  "version": "0.15.4",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/public-docs/browser-tools.md b/public-docs/browser-tools.md
index b97669e372..f1d586d3c0 100644
--- a/public-docs/browser-tools.md
+++ b/public-docs/browser-tools.md
@@ -33,7 +33,7 @@ Arguments marked `?` are optional.
 | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
 | `browser_snapshot`   | `browserId`                            | Return the page as an accessibility tree with element refs.                           |
 | `browser_screenshot` | `browserId, fullPage?`                 | Capture a PNG of the viewport, or the full page with `fullPage`.                      |
-| `browser_logs`       | `browserId, maxEntries?`               | Read recent console messages and network timing entries.                              |
+| `browser_logs`       | `browserId, maxEntries?`               | Read recent console messages and network entries: URL, timing, size and HTTP status.  |
 | `browser_wait`       | `browserId, text? \| url?, timeoutMs?` | Wait until the page contains text or reaches a URL fragment (exactly one of the two). |
 
 ## Interacting
diff --git a/public-docs/browser-tools.zh-CN.md b/public-docs/browser-tools.zh-CN.md
index b302a3267f..9b72216445 100644
--- a/public-docs/browser-tools.zh-CN.md
+++ b/public-docs/browser-tools.zh-CN.md
@@ -31,7 +31,7 @@ nav: 工具参考
 | -------------------- | -------------------------------------- | ------------------------------------------------------------------- |
 | `browser_snapshot`   | `browserId`                            | 以带元素引用的无障碍树形式返回页面。                                |
 | `browser_screenshot` | `browserId, fullPage?`                 | 截取视口的 PNG；传入 `fullPage` 时截取整个页面。                    |
-| `browser_logs`       | `browserId, maxEntries?`               | 读取最近的控制台消息和网络耗时条目。                                |
+| `browser_logs`       | `browserId, maxEntries?`               | 读取最近的控制台消息和网络条目：URL、耗时、大小和 HTTP 状态码。     |
 | `browser_wait`       | `browserId, text? \| url?, timeoutMs?` | 等待页面包含某段文本或到达某个 URL 片段（两者必须且只能提供一个）。 |
 
 ## 交互 {#interacting}
diff --git a/public-docs/cli.md b/public-docs/cli.md
index dd61ef60ae..700206e5a5 100644
--- a/public-docs/cli.md
+++ b/public-docs/cli.md
@@ -211,6 +211,8 @@ paseo workspace rename <workspace-id> --reset   # back to the branch or director
 paseo workspace archive <workspace-id>
 ```
 
+Inside an agent session, `PASEO_WORKSPACE_ID` holds the agent's own workspace ID, so an agent can run `paseo workspace rename "$PASEO_WORKSPACE_ID" "Auth rework"` or `paseo workspace archive "$PASEO_WORKSPACE_ID"` even when other workspaces share its directory.
+
 Add `--forge <name>` to PR checkout when Paseo cannot infer the forge from the source checkout. See [Git worktrees](/docs/worktrees) for setup hooks and services.
 
 ## Terminals
@@ -289,10 +291,10 @@ behavior.
 
 ```bash
 paseo ls                    # Non-archived agents in active workspaces
-paseo ls -a                 # Also include archived agents
+paseo ls -a                 # Also include archived and background agents, with a BACKGROUND column
 paseo ls -g                 # Non-archived agents across all workspaces
 paseo ls -a -g --json       # All agents, including archived, as JSON
-paseo ls --background       # Also include agents in background workspaces
+paseo ls --background       # Also include background agents and agents in background workspaces
 ```
 
 ## Streaming output
diff --git a/public-docs/cli.zh-CN.md b/public-docs/cli.zh-CN.md
index 4d2cec8372..29b8aec65f 100644
--- a/public-docs/cli.zh-CN.md
+++ b/public-docs/cli.zh-CN.md
@@ -202,6 +202,8 @@ paseo workspace rename <workspace-id> --reset   # back to the branch or director
 paseo workspace archive <workspace-id>
 ```
 
+在 Agent 会话中，`PASEO_WORKSPACE_ID` 保存该 Agent 自己的工作区 ID。即使其他工作区共享同一个目录，Agent 也可以运行 `paseo workspace rename "$PASEO_WORKSPACE_ID" "Auth rework"` 或 `paseo workspace archive "$PASEO_WORKSPACE_ID"`。
+
 当 Paseo 无法从源检出推断代码托管平台时，为 PR 检出添加 `--forge <name>`。setup 钩子和服务见 [Git worktree](/docs/worktrees)。
 
 ## 终端 {#terminals}
@@ -270,10 +272,10 @@ paseo plugin remove my-plugin
 
 ```bash
 paseo ls                    # Non-archived agents in active workspaces
-paseo ls -a                 # Also include archived agents
+paseo ls -a                 # Also include archived and background agents, with a BACKGROUND column
 paseo ls -g                 # Non-archived agents across all workspaces
 paseo ls -a -g --json       # All agents, including archived, as JSON
-paseo ls --background       # Also include agents in background workspaces
+paseo ls --background       # Also include background agents and agents in background workspaces
 ```
 
 ## 流式输出 {#streaming-output}
diff --git a/public-docs/mcp.md b/public-docs/mcp.md
index f90ae2a50b..68b484e852 100644
--- a/public-docs/mcp.md
+++ b/public-docs/mcp.md
@@ -87,18 +87,18 @@ MCP does not expose an agent-detach tool. Detaching is a manual user action in t
 
 ### Agents
 
-| Tool                 | Function                                                                                                                                                       |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create_agent`       | Create an agent, optionally placing it in an existing workspace with `workspaceId`. Use `initialPrompt` to start work; returns without waiting for completion. |
-| `send_agent_prompt`  | Send a prompt using `agentId` and `prompt`; returns without waiting for completion.                                                                            |
-| `get_agent_status`   | Return the latest snapshot for an agent.                                                                                                                       |
-| `list_agents`        | List recent agents as compact metadata; `includeBackground: true` includes background work.                                                                    |
-| `cancel_agent`       | Abort an agent's current run but keep the agent alive.                                                                                                         |
-| `archive_agent`      | Soft-delete an agent and remove it from the active list.                                                                                                       |
-| `kill_agent`         | Terminate an agent session permanently.                                                                                                                        |
-| `update_agent`       | Update an agent name, labels, or runtime settings such as mode/model/thinking/features.                                                                        |
-| `get_agent_activity` | Return recent agent timeline entries as a curated summary.                                                                                                     |
-| `set_agent_mode`     | Switch an agent's session mode.                                                                                                                                |
+| Tool                 | Function                                                                                                                                                                                                                                                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `create_agent`       | Create an agent, optionally placing it in an existing workspace with `workspaceId`. Use `initialPrompt` to start work; returns without waiting for completion. `background: true` hides it from tabs, default lists, your subagent track and notifications; you still get its finish notification. Omission inherits your own value. |
+| `send_agent_prompt`  | Send a prompt using `agentId` and `prompt`; returns without waiting for completion.                                                                                                                                                                                                                                                  |
+| `get_agent_status`   | Return the latest snapshot for an agent.                                                                                                                                                                                                                                                                                             |
+| `list_agents`        | List recent agents as compact metadata; `includeBackground: true` includes background work.                                                                                                                                                                                                                                          |
+| `cancel_agent`       | Abort an agent's current run but keep the agent alive.                                                                                                                                                                                                                                                                               |
+| `archive_agent`      | Soft-delete an agent and remove it from the active list.                                                                                                                                                                                                                                                                             |
+| `kill_agent`         | Terminate an agent session permanently.                                                                                                                                                                                                                                                                                              |
+| `update_agent`       | Update an agent name, labels, or runtime settings such as mode/model/thinking/features.                                                                                                                                                                                                                                              |
+| `get_agent_activity` | Return recent agent timeline entries as a curated summary.                                                                                                                                                                                                                                                                           |
+| `set_agent_mode`     | Switch an agent's session mode.                                                                                                                                                                                                                                                                                                      |
 
 Paseo agents receive finish, error, and permission notifications by default; set `notifyOnFinish: false` to disable them. External MCP clients use `get_agent_status` and `get_agent_activity` to check results.
 
diff --git a/public-docs/mcp.zh-CN.md b/public-docs/mcp.zh-CN.md
index 2cb81f4e30..36f0ff54d9 100644
--- a/public-docs/mcp.zh-CN.md
+++ b/public-docs/mcp.zh-CN.md
@@ -79,18 +79,18 @@ MCP 不提供解除 Agent 父子关系的工具。解除关系是用户在应用
 
 ### Agent {#agents}
 
-| 工具                 | 功能                                                                                                 |
-| -------------------- | ---------------------------------------------------------------------------------------------------- |
-| `create_agent`       | 创建 Agent，可用 `workspaceId` 把它放到已有的工作区。用 `initialPrompt` 开始工作；不等待完成就返回。 |
-| `send_agent_prompt`  | 用 `agentId` 和 `prompt` 发送提示词；不等待完成就返回。                                              |
-| `get_agent_status`   | 返回 Agent 的最新快照。                                                                              |
-| `list_agents`        | 以精简元数据列出最近的 Agent；`includeBackground: true` 会包含后台工作。                             |
-| `cancel_agent`       | 中止 Agent 当前的运行，但保留该 Agent。                                                              |
-| `archive_agent`      | 软删除 Agent，并把它从活动列表中移除。                                                               |
-| `kill_agent`         | 永久终止 Agent 会话。                                                                                |
-| `update_agent`       | 更新 Agent 的名称、标签或运行时设置，例如模式、模型、思考选项和功能。                                |
-| `get_agent_activity` | 以整理后的摘要返回 Agent 最近的时间线条目。                                                          |
-| `set_agent_mode`     | 切换 Agent 的会话模式。                                                                              |
+| 工具                 | 功能                                                                                                                                                                                                                             |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_agent`       | 创建 Agent，可用 `workspaceId` 把它放到已有的工作区。用 `initialPrompt` 开始工作；不等待完成就返回。`background: true` 会把它从标签页、默认列表、你的子 Agent 列表和通知中隐藏；你仍会收到它的完成通知。省略时继承你自己的设置。 |
+| `send_agent_prompt`  | 用 `agentId` 和 `prompt` 发送提示词；不等待完成就返回。                                                                                                                                                                          |
+| `get_agent_status`   | 返回 Agent 的最新快照。                                                                                                                                                                                                          |
+| `list_agents`        | 以精简元数据列出最近的 Agent；`includeBackground: true` 会包含后台工作。                                                                                                                                                         |
+| `cancel_agent`       | 中止 Agent 当前的运行，但保留该 Agent。                                                                                                                                                                                          |
+| `archive_agent`      | 软删除 Agent，并把它从活动列表中移除。                                                                                                                                                                                           |
+| `kill_agent`         | 永久终止 Agent 会话。                                                                                                                                                                                                            |
+| `update_agent`       | 更新 Agent 的名称、标签或运行时设置，例如模式、模型、思考选项和功能。                                                                                                                                                            |
+| `get_agent_activity` | 以整理后的摘要返回 Agent 最近的时间线条目。                                                                                                                                                                                      |
+| `set_agent_mode`     | 切换 Agent 的会话模式。                                                                                                                                                                                                          |
 
 Paseo Agent 默认会收到完成、错误和权限通知；设置 `notifyOnFinish: false` 可以关闭它们。外部 MCP 客户端使用 `get_agent_status` 和 `get_agent_activity` 查看结果。
 
diff --git a/public-docs/plugins/hooks.md b/public-docs/plugins/hooks.md
index b535821e62..a75600f942 100644
--- a/public-docs/plugins/hooks.md
+++ b/public-docs/plugins/hooks.md
@@ -49,22 +49,22 @@ Paseo only sees the returned promise, so detached work gets no error reporting a
 
 ## Hooks
 
-| Hook                      | Waits | Payload                                | Handler may change                             |
-| ------------------------- | ----- | -------------------------------------- | ---------------------------------------------- |
-| `workspace.create.before` | yes   | `{ request }`                          | Entire create request                          |
-| `workspace.create.after`  | no    | `{ workspace }`                        |                                                |
-| `workspace.archive.after` | no    | `{ workspace }`                        |                                                |
-| `worktree.create.before`  | yes   | `{ request }`                          | Creation options and destination               |
-| `worktree.create.after`   | yes   | `{ worktree }`                         | Files in the worktree; throw to abort creation |
-| `agent.create.before`     | yes   | `{ request: { config, env? } }`        | Saved config except `cwd`; `env`               |
-| `agent.create.after`      | no    | `{ agent }`                            |                                                |
-| `agent.open.before`       | yes   | `{ request }`                          | Launch-only `env`, `tools`, `mcpServers`       |
-| `agent.close.after`       | no    | `{ agent }`                            |                                                |
-| `agent.archive.after`     | no    | `{ agent, archivedAt }`                |                                                |
-| `agent.turn.before`       | no    | `{ agent, turnId }`                    |                                                |
-| `agent.turn.after`        | no    | `{ agent, turnId, outcome, timeline }` |                                                |
-| `agent.permission.before` | no    | `{ agent, request }`                   |                                                |
-| `agent.permission.after`  | no    | `{ agent, requestId, resolution }`     |                                                |
+| Hook                      | Waits | Payload                                   | Handler may change                             |
+| ------------------------- | ----- | ----------------------------------------- | ---------------------------------------------- |
+| `workspace.create.before` | yes   | `{ request }`                             | Entire create request                          |
+| `workspace.create.after`  | no    | `{ workspace }`                           |                                                |
+| `workspace.archive.after` | no    | `{ workspace }`                           |                                                |
+| `worktree.create.before`  | yes   | `{ request }`                             | Creation options and destination               |
+| `worktree.create.after`   | yes   | `{ worktree }`                            | Files in the worktree; throw to abort creation |
+| `agent.create.before`     | yes   | `{ request: { config, env?, metadata } }` | Saved config except `cwd`; `env`; `metadata`   |
+| `agent.create.after`      | no    | `{ agent }`                               |                                                |
+| `agent.open.before`       | yes   | `{ request }`                             | Launch-only `env`, `tools`, `mcpServers`       |
+| `agent.close.after`       | no    | `{ agent }`                               |                                                |
+| `agent.archive.after`     | no    | `{ agent, archivedAt }`                   |                                                |
+| `agent.turn.before`       | no    | `{ agent, turnId }`                       |                                                |
+| `agent.turn.after`        | no    | `{ agent, turnId, outcome, timeline }`    |                                                |
+| `agent.permission.before` | no    | `{ agent, request }`                      |                                                |
+| `agent.permission.after`  | no    | `{ agent, requestId, resolution }`        |                                                |
 
 ## Shared payloads
 
@@ -76,6 +76,7 @@ interface PluginHookAgent {
   provider: string;
   cwd: string;
   title: string | null;
+  metadata: Record<string, JsonValue>;
 }
 
 interface PluginHookWorkspace {
@@ -84,6 +85,7 @@ interface PluginHookWorkspace {
   cwd: string;
   name: string | null;
   archivedAt: string | null;
+  metadata: Record<string, JsonValue>;
 }
 
 type PluginTurnOutcome =
@@ -94,15 +96,35 @@ type PluginTurnOutcome =
 
 | Field        | Shape / meaning                                                                        |
 | ------------ | -------------------------------------------------------------------------------------- |
-| `turnId`     | Provider-reported `string` or `null`; can repeat after a session reopens               |
+| `turnId`     | Provider-reported `string` or `null`; unique across resumed sessions                   |
 | `timeline`   | Deprecated, always `[]`; fetch history with the SDK.                                   |
 | `request`    | SDK `AgentPermissionRequest`; `kind` is `tool`, `plan`, `question`, `mode`, or `other` |
 | `resolution` | SDK `AgentPermissionResponse`                                                          |
 | `archivedAt` | Timestamp string                                                                       |
 
+## Metadata
+
+Agents and workspaces carry a `metadata` record for plugin data. Keys are strings, values are any JSON value, and Paseo stores the record without reading a key. Prefix keys with your plugin id so plugins do not collide. Labels stay strings for filtering and tagging; use metadata for structured data.
+
+Set metadata when you create the agent or workspace, or change it later. `null` removes a key, and any other value replaces the key's whole value:
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  cwd: "/projects/shop",
+  metadata: { "linear.issue": { id: "ENG-123" } },
+});
+
+agent.metadata; // { "linear.issue": { id: "ENG-123" } }
+await agent.setMetadata({ "linear.issue": null });
+await paseo.workspaces.ref(workspaceId).setMetadata({ "linear.issue": { id: "ENG-123" } });
+```
+
+Metadata survives a daemon restart. Every hook payload carries it: `workspace.create.before` and `agent.create.before` receive the metadata the caller sent, and the `after` hooks and `agent.open.before` receive what is stored. Against a host that predates metadata, these calls throw "Update the host to use metadata."
+
 ## workspace.create.before
 
-Receives `{ request }` with `source`, optional `title`, and `firstAgentContext`. You may replace the entire explicit create request; a throw, invalid result, or timeout fails creation. Existing workspaces and directory lookup/import are unaffected.
+Receives `{ request }` with `source`, optional `title`, optional `metadata`, and `firstAgentContext`. You may replace the entire explicit create request; a throw, invalid result, or timeout fails creation. Existing workspaces and directory lookup/import are unaffected.
 
 ### Choose workspace isolation
 
@@ -202,18 +224,18 @@ server.addHook("worktree.create.after", async ({ worktree }) => {
 
 ## agent.create.before
 
-Receives `{ request: { config, env? } }`. Config changes are saved and remain after the plugin is disabled or removed; `env` applies to the initial launch and is not saved. You cannot change `config.cwd`. A throw, invalid result, or timeout fails creation.
+Receives `{ request: { config, env?, metadata } }`. Config and `metadata` changes are saved and remain after the plugin is disabled or removed; `env` applies to the initial launch and is not saved. You cannot change `config.cwd`. A throw, invalid result, or timeout fails creation.
 
 **`agent.create.before.config`** uses `AgentSessionConfig`:
 
-| Fields                                        | Constraint                                                                 |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `provider`, `model`                           | Separate fields; changing provider may require changing model/mode/options |
-| `modeId`, `thinkingOptionId`, `featureValues` | Provider-specific selections                                               |
-| `title`, `systemPrompt`                       | Agent configuration                                                        |
-| `providerOptions`                             | Opaque provider-specific options                                           |
-| `mcpServers`, `toolPolicy`                    | MCP configuration and exact-tool preapprovals                              |
-| `cwd`                                         | Cannot change                                                              |
+| Fields                       | Constraint                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `provider`, `model`          | Separate fields; changing provider may require changing model/mode/options |
+| `modeId`, `thinkingOptionId` | Provider-specific selections                                               |
+| `title`, `systemPrompt`      | Agent configuration                                                        |
+| `providerOptions`            | Provider options, including speed and auto-accept selections               |
+| `mcpServers`, `toolPolicy`   | MCP configuration and exact-tool preapprovals                              |
+| `cwd`                        | Cannot change                                                              |
 
 ### Change saved configuration
 
@@ -261,6 +283,17 @@ server.addHook("agent.create.after", async ({ agent }) => {
 
 Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open.
 
+Do not await a write to the agent being opened: `setMetadata`, `setLabels`, or an option, model, thinking or mode change. The write waits for the open to finish, the open waits for your hook, so the hook times out and the open fails. Start the write without awaiting it; it runs right after the open:
+
+```ts
+server.addHook("agent.open.before", async ({ request }, { paseo }) => {
+  void paseo.agents
+    .ref(request.agentId)
+    .setMetadata({ "my.plugin": { openedBy: "hook" } })
+    .catch((error) => console.error(error));
+});
+```
+
 **`agent.open.before` request example:**
 
 ```json
@@ -271,6 +304,7 @@ Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for th
   "cwd": "/projects/shop",
   "title": "Workspace notes",
   "labels": { "notes/enabled": "true" },
+  "metadata": { "linear.issue": { "id": "ENG-123" } },
   "tools": [],
   "mcpServers": {},
   "reason": "resume",
@@ -284,6 +318,7 @@ Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for th
 | `workspaceId` | String or `null`                                                                                                        |
 | `title`       | Read-only string or `null`; creation title on create, stored title on resume.                                           |
 | `labels`      | Read-only string map; creation labels on create, stored labels on resume.                                               |
+| `metadata`    | Read-only JSON map; the [metadata](#metadata) stored on the agent.                                                      |
 | `tools`       | Editable `AgentToolDefinition[]`, local to this plugin. See [Attach tools to agents](#attach-tools-to-agents).          |
 | `mcpServers`  | Editable launch-only server map, local to this plugin. See [Inject MCP servers](#inject-mcp-servers).                   |
 | `reason`      | `create`, `resume`, `refresh`, `import`                                                                                 |
@@ -588,7 +623,7 @@ server.addHook("agent.permission.after", async ({ agent, requestId, resolution }
 });
 ```
 
-Agent hooks exclude the daemon's private disposable helpers. Public background workspaces and their ordinary agents use the same hooks.
+Agent hooks exclude the daemon's private disposable helpers. Background agents and the agents in background workspaces use the same hooks.
 
 ## Ordering and returned values
 
@@ -598,7 +633,7 @@ Creation request
   → resolve defaults and validate provider configuration
   → derive launch configuration with Paseo runtime tools and daemon prompt
   → agent.open.before hooks (same ordering; env and plugin-local tools and MCP servers)
-  → set PASEO_AGENT_ID and PASEO_AGENT_CWD
+  → set PASEO_AGENT_ID, PASEO_AGENT_CWD, and PASEO_WORKSPACE_ID when the agent has a workspace
   → open provider session and save agent configuration
 ```
 
diff --git a/public-docs/plugins/hooks.zh-CN.md b/public-docs/plugins/hooks.zh-CN.md
index eecf370a29..adc8986632 100644
--- a/public-docs/plugins/hooks.zh-CN.md
+++ b/public-docs/plugins/hooks.zh-CN.md
@@ -47,22 +47,22 @@ Paseo 只观察返回的 Promise，因此独立任务没有错误报告，也没
 
 ## 钩子一览 {#hooks}
 
-| 钩子                      | 等待 | 载荷                                   | 可修改                                    |
-| ------------------------- | ---- | -------------------------------------- | ----------------------------------------- |
-| `workspace.create.before` | 是   | `{ request }`                          | 整个创建请求                              |
-| `workspace.create.after`  | 否   | `{ workspace }`                        |                                           |
-| `workspace.archive.after` | 否   | `{ workspace }`                        |                                           |
-| `worktree.create.before`  | 是   | `{ request }`                          | 创建选项和目标路径                        |
-| `worktree.create.after`   | 是   | `{ worktree }`                         | worktree 中的文件；抛出错误中止创建       |
-| `agent.create.before`     | 是   | `{ request: { config, env? } }`        | 除 `cwd` 外的已保存配置；`env`            |
-| `agent.create.after`      | 否   | `{ agent }`                            |                                           |
-| `agent.open.before`       | 是   | `{ request }`                          | 仅用于启动的 `env`、`tools`、`mcpServers` |
-| `agent.close.after`       | 否   | `{ agent }`                            |                                           |
-| `agent.archive.after`     | 否   | `{ agent, archivedAt }`                |                                           |
-| `agent.turn.before`       | 否   | `{ agent, turnId }`                    |                                           |
-| `agent.turn.after`        | 否   | `{ agent, turnId, outcome, timeline }` |                                           |
-| `agent.permission.before` | 否   | `{ agent, request }`                   |                                           |
-| `agent.permission.after`  | 否   | `{ agent, requestId, resolution }`     |                                           |
+| 钩子                      | 等待 | 载荷                                      | 可修改                                     |
+| ------------------------- | ---- | ----------------------------------------- | ------------------------------------------ |
+| `workspace.create.before` | 是   | `{ request }`                             | 整个创建请求                               |
+| `workspace.create.after`  | 否   | `{ workspace }`                           |                                            |
+| `workspace.archive.after` | 否   | `{ workspace }`                           |                                            |
+| `worktree.create.before`  | 是   | `{ request }`                             | 创建选项和目标路径                         |
+| `worktree.create.after`   | 是   | `{ worktree }`                            | worktree 中的文件；抛出错误中止创建        |
+| `agent.create.before`     | 是   | `{ request: { config, env?, metadata } }` | 除 `cwd` 外的已保存配置；`env`；`metadata` |
+| `agent.create.after`      | 否   | `{ agent }`                               |                                            |
+| `agent.open.before`       | 是   | `{ request }`                             | 仅用于启动的 `env`、`tools`、`mcpServers`  |
+| `agent.close.after`       | 否   | `{ agent }`                               |                                            |
+| `agent.archive.after`     | 否   | `{ agent, archivedAt }`                   |                                            |
+| `agent.turn.before`       | 否   | `{ agent, turnId }`                       |                                            |
+| `agent.turn.after`        | 否   | `{ agent, turnId, outcome, timeline }`    |                                            |
+| `agent.permission.before` | 否   | `{ agent, request }`                      |                                            |
+| `agent.permission.after`  | 否   | `{ agent, requestId, resolution }`        |                                            |
 
 ## 共享载荷 {#shared-payloads}
 
@@ -74,6 +74,7 @@ interface PluginHookAgent {
   provider: string;
   cwd: string;
   title: string | null;
+  metadata: Record<string, JsonValue>;
 }
 
 interface PluginHookWorkspace {
@@ -82,6 +83,7 @@ interface PluginHookWorkspace {
   cwd: string;
   name: string | null;
   archivedAt: string | null;
+  metadata: Record<string, JsonValue>;
 }
 
 type PluginTurnOutcome =
@@ -92,15 +94,35 @@ type PluginTurnOutcome =
 
 | 字段         | 结构 / 含义                                                                              |
 | ------------ | ---------------------------------------------------------------------------------------- |
-| `turnId`     | Provider 报告的 `string` 或 `null`；会话重新打开后可能重复                               |
+| `turnId`     | Provider 报告的 `string` 或 `null`；在会话恢复后仍保持唯一                               |
 | `timeline`   | 已弃用，始终为 `[]`；通过 SDK 获取历史。                                                 |
 | `request`    | SDK 的 `AgentPermissionRequest`；`kind` 为 `tool`、`plan`、`question`、`mode` 或 `other` |
 | `resolution` | SDK 的 `AgentPermissionResponse`                                                         |
 | `archivedAt` | 时间戳字符串                                                                             |
 
+## 元数据 {#metadata}
+
+Agent 和工作区带有 `metadata` 记录，用于保存插件数据。键是字符串，值可以是任意 JSON 值，Paseo 只保存、不读取任何键。给键加上插件 ID 前缀，避免不同插件冲突。标签仍是用于筛选和标记的字符串；结构化数据请用元数据。
+
+可以在创建 Agent 或工作区时设置元数据，也可以之后修改。`null` 删除该键，其他值会替换该键的整个值：
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  cwd: "/projects/shop",
+  metadata: { "linear.issue": { id: "ENG-123" } },
+});
+
+agent.metadata; // { "linear.issue": { id: "ENG-123" } }
+await agent.setMetadata({ "linear.issue": null });
+await paseo.workspaces.ref(workspaceId).setMetadata({ "linear.issue": { id: "ENG-123" } });
+```
+
+元数据在 daemon 重启后仍然保留。所有钩子载荷都带有元数据：`workspace.create.before` 和 `agent.create.before` 收到调用方发送的元数据，`after` 钩子和 `agent.open.before` 收到已保存的元数据。主机版本过旧时，这些调用会抛出 “Update the host to use metadata.”。
+
 ## workspace.create.before {#workspacecreatebefore}
 
-收到 `{ request }`，其中包含 `source`、可选的 `title` 和 `firstAgentContext`。可替换整个显式创建请求；抛出错误、无效返回或超时会让创建失败。已有工作区和目录查找、导入不受影响。
+收到 `{ request }`，其中包含 `source`、可选的 `title`、可选的 `metadata` 和 `firstAgentContext`。可替换整个显式创建请求；抛出错误、无效返回或超时会让创建失败。已有工作区和目录查找、导入不受影响。
 
 ### 选择工作区隔离方式 {#choose-workspace-isolation}
 
@@ -199,18 +221,18 @@ server.addHook("worktree.create.after", async ({ worktree }) => {
 
 ## agent.create.before {#agentcreatebefore}
 
-收到 `{ request: { config, env? } }`。配置修改会保存，即使插件以后被停用或移除；`env` 只用于首次启动，不会保存。不能修改 `config.cwd`。抛出错误、无效返回或超时会让创建失败。
+收到 `{ request: { config, env?, metadata } }`。配置和 `metadata` 的修改会保存，即使插件以后被停用或移除；`env` 只用于首次启动，不会保存。不能修改 `config.cwd`。抛出错误、无效返回或超时会让创建失败。
 
 **`agent.create.before.config`** 使用 `AgentSessionConfig`：
 
-| 字段                                          | 约束                                                     |
-| --------------------------------------------- | -------------------------------------------------------- |
-| `provider`, `model`                           | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
-| `modeId`, `thinkingOptionId`, `featureValues` | 特定于 Provider 的选择                                   |
-| `title`, `systemPrompt`                       | Agent 配置                                               |
-| `providerOptions`                             | 不透明的、特定于 Provider 的选项                         |
-| `mcpServers`, `toolPolicy`                    | MCP 配置和精确的工具预批准                               |
-| `cwd`                                         | 不能修改                                                 |
+| 字段                         | 约束                                                     |
+| ---------------------------- | -------------------------------------------------------- |
+| `provider`, `model`          | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
+| `modeId`, `thinkingOptionId` | 特定于 Provider 的选择                                   |
+| `title`, `systemPrompt`      | Agent 配置                                               |
+| `providerOptions`            | Provider 选项，包括速度和自动批准的选择                  |
+| `mcpServers`, `toolPolicy`   | MCP 配置和精确的工具预批准                               |
+| `cwd`                        | 不能修改                                                 |
 
 ### 修改已保存的配置 {#change-saved-configuration}
 
@@ -257,6 +279,17 @@ server.addHook("agent.create.after", async ({ agent }) => {
 
 收到 `{ request }`，只能修改 `env`、`tools` 和 `mcpServers`，修改只用于此次启动。其他字段只读。抛出错误、无效返回或超时会让打开操作失败。
 
+不要 await 对正在打开的 Agent 的写入，例如 `setMetadata`。该写入要等打开完成，而打开在等你的钩子，结果钩子超时，打开失败。启动写入但不要 await，它会在打开完成后立即执行：
+
+```ts
+server.addHook("agent.open.before", async ({ request }, { paseo }) => {
+  void paseo.agents
+    .ref(request.agentId)
+    .setMetadata({ "my.plugin": { openedBy: "hook" } })
+    .catch((error) => console.error(error));
+});
+```
+
 **`agent.open.before` 请求示例：**
 
 ```json
@@ -267,6 +300,7 @@ server.addHook("agent.create.after", async ({ agent }) => {
   "cwd": "/projects/shop",
   "title": "Workspace notes",
   "labels": { "notes/enabled": "true" },
+  "metadata": { "linear.issue": { "id": "ENG-123" } },
   "tools": [],
   "mcpServers": {},
   "reason": "resume",
@@ -280,6 +314,7 @@ server.addHook("agent.create.after", async ({ agent }) => {
 | `workspaceId` | 字符串或 `null`                                                                                          |
 | `title`       | 只读字符串或 `null`；创建时使用创建请求的标题，恢复时使用已保存的标题。                                  |
 | `labels`      | 只读的字符串映射；创建时使用创建请求的标签，恢复时使用已保存的标签。                                     |
+| `metadata`    | 只读的 JSON 映射；Agent 上已保存的[元数据](#metadata)。                                                  |
 | `tools`       | 可编辑的 `AgentToolDefinition[]`，仅包含此插件的工具。参阅[为 Agent 附加工具](#attach-tools-to-agents)。 |
 | `mcpServers`  | 可编辑的服务器映射，仅用于启动且仅包含本插件的条目。参阅[注入 MCP 服务器](#inject-mcp-servers)。         |
 | `reason`      | `create`、`resume`、`refresh`、`import`                                                                  |
@@ -571,7 +606,7 @@ server.addHook("agent.permission.after", async ({ agent, requestId, resolution }
 });
 ```
 
-Agent 钩子不包括 daemon 的私有临时辅助 Agent。公开的后台工作区及其普通 Agent 使用相同钩子。
+Agent 钩子不包括 daemon 的私有临时辅助 Agent。后台 Agent 和后台工作区中的 Agent 使用相同钩子。
 
 ## 顺序与返回值 {#ordering-and-returned-values}
 
@@ -581,7 +616,7 @@ Creation request
   → resolve defaults and validate provider configuration
   → derive launch configuration with Paseo runtime tools and daemon prompt
   → agent.open.before hooks (same ordering; env and plugin-local tools and MCP servers)
-  → set PASEO_AGENT_ID and PASEO_AGENT_CWD
+  → set PASEO_AGENT_ID, PASEO_AGENT_CWD, and PASEO_WORKSPACE_ID when the agent has a workspace
   → open provider session and save agent configuration
 ```
 
diff --git a/public-docs/plugins/index.md b/public-docs/plugins/index.md
index ce6b549bf9..d4d12cc238 100644
--- a/public-docs/plugins/index.md
+++ b/public-docs/plugins/index.md
@@ -14,6 +14,8 @@ A plugin is a TypeScript project installed into one Paseo daemon. It can add
 [file panels](/docs/plugins/reference#file-panels),
 [Command Center items](/docs/plugins/reference#command-center-items),
 [slash commands](/docs/plugins/reference#slash-commands),
+[composer items](/docs/plugins/reference#composer-items),
+[New workspace items](/docs/plugins/reference#new-workspace-items),
 [composer pills](/docs/plugins/reference#composer-pills),
 [timeline items](/docs/plugins/reference#timeline-items),
 [themes](/docs/plugins/reference#contribute-a-theme),
diff --git a/public-docs/plugins/index.zh-CN.md b/public-docs/plugins/index.zh-CN.md
index 2f6c1bccff..d1367dac47 100644
--- a/public-docs/plugins/index.zh-CN.md
+++ b/public-docs/plugins/index.zh-CN.md
@@ -6,7 +6,7 @@ nav: 快速上手
 
 # 插件快速上手 {#plugin-quickstart}
 
-插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。
+插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 项](/docs/plugins/reference#composer-items)、[新建工作区项](/docs/plugins/reference#new-workspace-items)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。
 
 浏览[已发布的插件](https://paseo.sh/plugins)，然后在你的 daemon 上安装一个：
 
diff --git a/public-docs/plugins/migration.md b/public-docs/plugins/migration.md
index fdefda5971..836a8e57b6 100644
--- a/public-docs/plugins/migration.md
+++ b/public-docs/plugins/migration.md
@@ -73,6 +73,7 @@ Use this table as the complete registration checklist.
 | `plugin.addSurface(id, Component)` in the old root entry                                      | `client.addScreen({ id, title, Component })` in `index.client.tsx`                                                          |
 | `plugin.addSidebarItem({ id, title, icon, surface })` in the old root entry                   | `client.addSidebarHeaderItem({ id, title, Component })` in `index.client.tsx`; see [sidebar items](reference#sidebar-items) |
 | New sidebar footer contribution                                                               | `client.addSidebarFooterItem({ id, title, Component })` in `index.client.tsx`                                               |
+| New sidebar replacement view                                                                  | `client.addSidebarView({ id, title, Component })` in `index.client.tsx`; see [sidebar views](sidebar-views)                 |
 | New file panel contribution                                                                   | `client.addFilePanel(panel)` in `index.client.tsx`                                                                          |
 | `plugin.addWorkspacePanel(panel)` in the old root entry                                       | `client.addWorkspacePanel(panel)` in `index.client.tsx`                                                                     |
 | Agent panel with `context: "agent"`                                                           | `client.addAgentPanel(panel)` in `index.client.tsx`; omit `context`                                                         |
@@ -80,6 +81,8 @@ Use this table as the complete registration checklist.
 | `plugin.addClientSlashCommand(command)` in the old root entry                                 | `client.addSlashCommand(command)` in `index.client.tsx`                                                                     |
 | `plugin.addClientSide(fn)` in the old root entry                                              | Delete the wrapper and move the body of `fn` into the default client entry function                                         |
 | `client.addComposerPill(pill)` inside the old client callback                                 | `client.addComposerPill(pill)` inside `index.client.tsx` or an imported `client/` function                                  |
+| New composer item contribution                                                                | `client.addComposerItem(item)` in `index.client.tsx`; see [composer items](reference#composer-items)                        |
+| New New workspace item contribution                                                           | `client.addNewWorkspaceItem(item)` in `index.client.tsx`; see [New workspace items](reference#new-workspace-items)          |
 | New header contribution                                                                       | `client.addHeaderButton({ id, workspaceId, button })`                                                                       |
 | `plugin.addAttachmentSource(source)` in the old root entry                                    | `client.addAttachmentSource(source)` in `index.client.tsx`                                                                  |
 | New settings screen contribution                                                              | `client.addSettingsScreen(screen)` in `index.client.tsx`; see [settings screens](reference#settings-screens)                |
@@ -144,8 +147,8 @@ pill.remove();
 ```
 
 Move dynamic text from the former component into updates from your model or SDK subscription.
-Custom icon components may still use hooks. Composer pills always show icon and label and never
-show chevrons. See [buttons](./reference.md#button-descriptor) for menus, popovers, and visibility.
+Custom icon components may still use hooks. Composer pills always show icon and label; menus and
+popovers add a chevron. See [buttons](./reference.md#button-descriptor) for menus, popovers, and visibility.
 
 ## 4. Separate imports
 
@@ -184,6 +187,26 @@ For paced timeline text, replace `useRevealedText(text, phase)` and the surround
 `<StreamedText text={text} phase={phase} style={style} />` from `/client/ui`.
 Use `SettingsSection` for plugin settings headings; `SettingsGroup` is deprecated.
 
+### Provider options in v0.15
+
+A provider plugin has one configuration record, `providerOptions`, and describes which keys get a
+composer control. A provider that still reports `settings` keeps working through v0.15: Paseo reads each
+setting `id` as an option key and each `value` as that option, and sends changes in both
+`changes.providerOptions` and `changes.settings`. Remove `settings` before the shim is deleted after
+2027-05-01.
+
+| Previous API                                   | Replacement                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| `session.config` `settings: ProviderSetting[]` | `controls: ProviderOptionControl[]` plus `providerOptions`                 |
+| Setting `id`                                   | Control `key`                                                              |
+| Setting `value`                                | `providerOptions[key]`; the control holds no value                         |
+| Select setting `options: { label, value }[]`   | Select control `choices: { value, label, description? }[]`                 |
+| Setting with no icon or default                | Control `icon` (a Lucide name) and `defaultValue`                          |
+| `session.configure` `changes.settings`         | `changes.providerOptions`; `null` returns a key to its default             |
+| `session.open` `config.settings`               | `config.providerOptions`                                                   |
+| `ProviderSetting` type                         | `ProviderOptionControl`                                                    |
+| `agent.create.before` `config.featureValues`   | `config.providerOptions`; a returned `featureValues` edit is still applied |
+
 ## 5. Recognize half-migration errors
 
 | Compiler or load error                                                                                                     | Meaning and fix                                                                                                           |
diff --git a/public-docs/plugins/migration.zh-CN.md b/public-docs/plugins/migration.zh-CN.md
index 600b65f4d9..216f2437b9 100644
--- a/public-docs/plugins/migration.zh-CN.md
+++ b/public-docs/plugins/migration.zh-CN.md
@@ -73,6 +73,8 @@ my-plugin/
 | 旧根入口中的 `plugin.addClientSlashCommand(command)`                                          | `index.client.tsx` 中的 `client.addSlashCommand(command)`                                                              |
 | 旧根入口中的 `plugin.addClientSide(fn)`                                                       | 删除这层包装，把 `fn` 的函数体移入默认的客户端入口函数                                                                 |
 | 旧客户端回调中的 `client.addComposerPill(pill)`                                               | `index.client.tsx` 或被导入的 `client/` 函数中的 `client.addComposerPill(pill)`                                        |
+| 新的编辑器项贡献                                                                              | `index.client.tsx` 中的 `client.addComposerItem(item)`;见[编辑器项](reference#composer-items)                          |
+| 新的“新建工作区”项贡献                                                                        | `index.client.tsx` 中的 `client.addNewWorkspaceItem(item)`;见[新建工作区项](reference#new-workspace-items)             |
 | 新的标题栏贡献                                                                                | `client.addHeaderButton({ id, workspaceId, button })`                                                                  |
 | 旧根入口中的 `plugin.addAttachmentSource(source)`                                             | `index.client.tsx` 中的 `client.addAttachmentSource(source)`                                                           |
 | 新的设置界面贡献                                                                              | `index.client.tsx` 中的 `client.addSettingsScreen(screen)`；见[设置界面](reference#settings-screens)                   |
@@ -152,6 +154,22 @@ pill.remove();
 
 对于逐步显示的时间线文本，把 `useRevealedText(text, phase)` 及其外层的 `Text` 换成 `/client/ui` 中的 `<StreamedText text={text} phase={phase} style={style} />`。插件设置的标题使用 `SettingsSection`；`SettingsGroup` 已弃用。
 
+### v0.15 中的 Provider 选项 {#provider-options-in-v015}
+
+Provider 插件只有一个配置记录 `providerOptions`，并用控件描述哪些键显示在 Composer 中。仍然报告 `settings` 的 Provider 在 v0.15 中继续可用：Paseo 把每个 setting 的 `id` 当作选项键，把 `value` 当作该选项的值，并同时在 `changes.providerOptions` 和 `changes.settings` 中发送修改。请在 2027-05-01 之后兼容层被删除之前移除 `settings`。
+
+| 之前的 API                                        | 替代方式                                                        |
+| ------------------------------------------------- | --------------------------------------------------------------- |
+| `session.config` 的 `settings: ProviderSetting[]` | `controls: ProviderOptionControl[]` 加 `providerOptions`        |
+| Setting 的 `id`                                   | 控件的 `key`                                                    |
+| Setting 的 `value`                                | `providerOptions[key]`；控件本身不保存值                        |
+| 选择类 setting 的 `options: { label, value }[]`   | 选择类控件的 `choices: { value, label, description? }[]`        |
+| 没有图标或默认值的 setting                        | 控件的 `icon`（Lucide 名称）和 `defaultValue`                   |
+| `session.configure` 的 `changes.settings`         | `changes.providerOptions`；`null` 表示恢复该键的默认值          |
+| `session.open` 的 `config.settings`               | `config.providerOptions`                                        |
+| `ProviderSetting` 类型                            | `ProviderOptionControl`                                         |
+| `agent.create.before` 的 `config.featureValues`   | `config.providerOptions`；返回的 `featureValues` 修改仍会被应用 |
+
 ## 5. 识别只迁移了一半的错误 {#5-recognize-half-migration-errors}
 
 | 编译器或加载错误                                                                                                           | 含义与修复方法                                                                                     |
diff --git a/public-docs/plugins/providers.md b/public-docs/plugins/providers.md
index 6fbe766c61..5495405bfd 100644
--- a/public-docs/plugins/providers.md
+++ b/public-docs/plugins/providers.md
@@ -22,7 +22,7 @@ Choose one implementation path:
 
 The examples are:
 
-- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct): sessions, settings, prompts, persistence, child sessions, and a provider-owned timeline renderer;
+- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct): sessions, option controls, prompts, persistence, child sessions, and a provider-owned timeline renderer;
 - [`provider-acp-transformer`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-acp-transformer): an ACP command template with a Zod-validated vendor edit transformer. Replace `example-acp --stdio` with an installed ACP agent before loading it;
 - [`inline-thinking`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/inline-thinking): a renderer-only plugin that does not implement a provider.
 
@@ -138,7 +138,7 @@ later through `session.config`.
 ## Open a session
 
 `session.open` contains the complete launch configuration: working directory, environment, system
-prompt, MCP servers, tool policy, model, mode, settings, opaque provider options, and persistence
+prompt, MCP servers, tool policy, model, mode, `providerOptions`, and persistence
 preference.
 
 For persisted host-scoped plugin settings, use the handle returned by `server.registerSettings()`.
@@ -177,7 +177,8 @@ emit({
     models,
     modes,
     thinkingOptions,
-    settings: [],
+    controls: [],
+    providerOptions: {},
   },
 });
 emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
@@ -229,10 +230,16 @@ terminal `completed`, `failed`, or `canceled` event.
 At this point the provider is usable: users can select a model, open a session, send a message, and
 see the response.
 
-## Add session-specific composer controls
+## Add composer controls for provider options
 
-Add `session.configure` only when the native agent has settings users should change after opening a
-session. Publish them in `session.config` as toggle or select controls:
+`providerOptions` is the provider's own configuration: one record of JSON values that Paseo
+stores per agent and hands to `session.open`. It includes the defaults a user set in `config.json`
+for your provider. Validate every key you read.
+
+Add `controls` only when users should see and change some of those options in the composer. A
+control draws one top-level key of `providerOptions` as a toggle or a select. It holds no value:
+Paseo reads the value from `providerOptions`. Publish the controls and the values you run with in
+`session.config`:
 
 ```ts
 emit({
@@ -243,35 +250,48 @@ emit({
     models: [{ id: "agent-large", label: "Agent Large" }],
     modes: [],
     thinkingOptions: [],
-    settings: [
-      {
-        type: "toggle",
-        id: "fast",
-        label: "Fast mode",
-        value: nativeSession.fast,
-      },
+    controls: [
+      { type: "toggle", key: "fast", label: "Fast mode", icon: "Zap", defaultValue: false },
       {
         type: "select",
-        id: "approval",
+        key: "approval",
         label: "Approvals",
-        value: nativeSession.approval,
-        options: [
-          { label: "Ask", value: "ask" },
-          { label: "Auto accept", value: "auto" },
+        icon: "Shield",
+        defaultValue: "ask",
+        choices: [
+          { value: "ask", label: "Ask" },
+          { value: "auto", label: "Auto accept" },
         ],
       },
     ],
+    providerOptions: { fast: nativeSession.fast, approval: nativeSession.approval },
   },
 });
 ```
 
-Paseo renders these controls in the composer. A user change arrives as `session.configure`; apply it
-and publish the committed `session.config` before `request.completed`. The provider may change the
-available controls at runtime, including after a model change.
+`icon` is a Lucide icon name. `defaultValue` is what a control shows for a key that has no value.
+Paseo stores every value you report when a session opens or a change is applied, including values
+at the default and values nobody set. The same controls appear in the New workspace screen, in draft
+tabs, and on running agents. Offer a control only for a key you can change on a running session.
+The provider may change its controls at runtime, including after a model change.
 
-`settings` are user-facing controls. `providerOptions` is opaque JSON supplied at session creation
-for provider-specific configuration that Paseo does not render. A provider-specific token budget
-belongs in one of those two places; it is not a dedicated prompt field.
+A change arrives as `session.configure` with `changes.providerOptions` holding only the keys
+that changed, whether or not they have a control. Apply every key and publish the committed
+`session.config` before `request.completed`. Fail the request with `request.failed` and leave
+every key as it was when you cannot apply one, for example a key you read only when a session
+opens. A
+value of `null` returns that key to the provider's default. Publish what the session ended up
+with, not a copy of the request: Paseo stores your published values so the stored options match
+what runs.
+
+If the provider changes an option on its own, for example a model switch turns Fast off, publish
+a new `session.config` with the new values. Paseo stores them and does not set the old ones
+back.
+
+Not every option needs a control. A provider-specific token budget, for example, belongs in
+`providerOptions` and is not a dedicated prompt field. It is delivered in `session.open`, a caller
+can change it on a running agent, and your `session.configure` handler decides whether it can
+apply it live. Report it in `providerOptions` so Paseo stores what runs.
 
 ## Add persistence and replay
 
@@ -287,6 +307,11 @@ Paseo refreshes an agent by closing its current provider session and opening it
 configuration and persistence. Re-read credentials, environment, global configuration, and MCP
 servers during `session.open`. There is no separate reload operation.
 
+Conversation and combined rewind require a core-restored session with persistence. After a
+successful rewind, Paseo closes the session and reopens its latest persistence value with
+`history: "replay"`. Publish the retained native branch before `session.ready`, including its
+children. File-only rewind keeps the current session and conversation history.
+
 Use `restoration: "core"` when Paseo can reopen a session from persistence. A provider-owned child
 uses `restoration: "parent"`; emit it as another `session.opened` event with `parentSessionId` and
 recreate it while restoring the parent.
@@ -462,7 +487,7 @@ export const vendorEdits: AcpTransformer = {
 Test the provider against the real agent, not only mocked frames:
 
 1. install the plugin as a directory source;
-2. confirm its SVG, models, modes, and settings appear;
+2. confirm its SVG, models, modes, and option controls appear;
 3. create a session and complete a real prompt;
 4. exercise permissions, steering, cancellation, persistence, and replay when supported;
 5. render every custom timeline item on desktop and mobile-width layouts;
diff --git a/public-docs/plugins/providers.zh-CN.md b/public-docs/plugins/providers.zh-CN.md
index 6cc0a2cb14..e917ba0538 100644
--- a/public-docs/plugins/providers.zh-CN.md
+++ b/public-docs/plugins/providers.zh-CN.md
@@ -19,7 +19,7 @@ Provider 插件把一个编程 Agent 接入 Paseo，而无需把它加入 Paseo
 
 示例有：
 
-- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct)：会话、设置、提示词、持久化、子会话，以及一个由 Provider 拥有的时间线渲染器；
+- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct)：会话、选项控件、提示词、持久化、子会话，以及一个由 Provider 拥有的时间线渲染器；
 - [`provider-acp-transformer`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-acp-transformer)：一个 ACP 命令模板，带有一个用 Zod 校验的厂商编辑转换器。加载之前，请把 `example-acp --stdio` 替换为一个已安装的 ACP Agent；
 - [`inline-thinking`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/inline-thinking)：一个只包含渲染器、不实现 Provider 的插件。
 
@@ -125,7 +125,7 @@ if (input.type === "catalog") {
 
 ## 打开会话 {#open-a-session}
 
-`session.open` 包含完整的启动配置：工作目录、环境变量、系统提示词、MCP 服务器、工具策略、模型、模式、设置、不透明的 Provider 选项以及持久化偏好。
+`session.open` 包含完整的启动配置：工作目录、环境变量、系统提示词、MCP 服务器、工具策略、模型、模式、`providerOptions` 以及持久化偏好。
 
 对于持久化的、作用于主机的插件设置，请使用 `server.registerSettings()` 返回的句柄。在目录和会话回调中读取它；当 Provider 在内存中保留配置时，订阅它。`read()` 和 `subscribe()` 的契约见[设置](./reference.md#persisted-values)。
 
@@ -160,7 +160,8 @@ emit({
     models,
     modes,
     thinkingOptions,
-    settings: [],
+    controls: [],
+    providerOptions: {},
   },
 });
 emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
@@ -207,9 +208,11 @@ emit({ type: "session.turn", sessionId, turnId, state: "completed" });
 
 到这一步，Provider 已经可用：用户可以选择模型、打开会话、发送消息并看到回复。
 
-## 添加会话专属的 Composer 控件 {#add-session-specific-composer-controls}
+## 为 Provider 选项添加 Composer 控件 {#add-composer-controls-for-provider-options}
 
-只有当原生 Agent 有用户在打开会话后需要修改的设置时，才添加 `session.configure`。在 `session.config` 中以开关或选择控件的形式发布它们：
+`providerOptions` 是 Provider 自己的配置：一个由 JSON 值组成的记录，Paseo 按 Agent 保存它，并在 `session.open` 中交给你。它包含用户在 `config.json` 中为你的 Provider 设置的默认值。请校验你读取的每个键。
+
+只有当用户需要在 Composer 中查看并修改其中一部分选项时，才添加 `controls`。一个控件把 `providerOptions` 的一个顶层键绘制为开关或选择器。控件本身不保存值：Paseo 从 `providerOptions` 读取值。在 `session.config` 中发布控件，以及你正在使用的值：
 
 ```ts
 emit({
@@ -220,31 +223,32 @@ emit({
     models: [{ id: "agent-large", label: "Agent Large" }],
     modes: [],
     thinkingOptions: [],
-    settings: [
-      {
-        type: "toggle",
-        id: "fast",
-        label: "Fast mode",
-        value: nativeSession.fast,
-      },
+    controls: [
+      { type: "toggle", key: "fast", label: "Fast mode", icon: "Zap", defaultValue: false },
       {
         type: "select",
-        id: "approval",
+        key: "approval",
         label: "Approvals",
-        value: nativeSession.approval,
-        options: [
-          { label: "Ask", value: "ask" },
-          { label: "Auto accept", value: "auto" },
+        icon: "Shield",
+        defaultValue: "ask",
+        choices: [
+          { value: "ask", label: "Ask" },
+          { value: "auto", label: "Auto accept" },
         ],
       },
     ],
+    providerOptions: { fast: nativeSession.fast, approval: nativeSession.approval },
   },
 });
 ```
 
-Paseo 会在 Composer 中渲染这些控件。用户的修改会以 `session.configure` 的形式到达；应用它，并在 `request.completed` 之前发布已确定的 `session.config`。Provider 可以在运行时改变可用的控件，包括在模型变化之后。
+`icon` 是 Lucide 图标名称。`defaultValue` 是控件在键没有值时显示的值。会话打开或应用修改时，你报告的每个值（包括处于默认值的值和无人设置过的值）Paseo 都会保存。相同的控件会出现在“新建工作区”界面、草稿标签页和运行中的 Agent 上。只为你能在运行中的会话里修改的键提供控件。Provider 可以在运行时改变控件，包括在模型变化之后。
 
-`settings` 是面向用户的控件。`providerOptions` 是在创建会话时提供的不透明 JSON，用于 Paseo 不会渲染的 Provider 专属配置。Provider 专属的 token 预算应放在这两处之一；它不是一个专门的提示词字段。
+修改会以 `session.configure` 的形式到达，`changes.providerOptions` 只包含发生变化的键，无论这些键是否有控件。应用每一个键，并在 `request.completed` 之前发布已确定的 `session.config`。如果无法应用其中某个键（例如只在会话打开时读取的键），用 `request.failed` 使请求失败，并让每个键保持原样。值为 `null` 表示把该键恢复为 Provider 的默认值。请发布会话最终实际使用的值，而不是请求的副本：Paseo 会保存你发布的值，使保存的选项与实际运行的一致。
+
+如果 Provider 自行改变了某个选项（例如切换模型后关闭了 Fast），请发布带有新值的 `session.config`。Paseo 会保存它们，不会把旧值设置回去。
+
+并非每个选项都需要控件。例如 Provider 专属的 token 预算应放在 `providerOptions` 中，它不是一个专门的提示词字段。它会在 `session.open` 中交付，调用方可以在运行中的 Agent 上修改它，由你的 `session.configure` 处理程序决定能否实时应用。请在 `providerOptions` 中报告它，使 Paseo 保存实际运行的值。
 
 ## 添加持久化与重放 {#add-persistence-and-replay}
 
@@ -405,7 +409,7 @@ export const vendorEdits: AcpTransformer = {
 用真实的 Agent 测试 Provider，而不只是模拟的数据帧：
 
 1. 以目录来源安装插件；
-2. 确认它的 SVG、模型、模式和设置都会显示；
+2. 确认它的 SVG、模型、模式和选项控件都会显示；
 3. 创建会话并完成一段真实的提示词；
 4. 在支持的情况下，试用权限、引导、取消、持久化和重放；
 5. 在桌面和移动端宽度的布局中渲染每一种自定义时间线条目；
diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md
index a5565b71c7..c3f60393cd 100644
--- a/public-docs/plugins/reference.md
+++ b/public-docs/plugins/reference.md
@@ -73,16 +73,16 @@ The required root manifest is `paseo-plugin.json`:
 }
 ```
 
-| Field          | Required | Behavior                                                                                                                                     |
-| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`           | Yes      | Default installation ID.                                                                                                                     |
-| `name`         | No       | Non-empty display name for the registry and website; independent of the installation ID.                                                     |
-| `icon`         | No       | Relative path to a PNG inside the plugin package.                                                                                            |
-| `media`        | No       | Array of image or video paths inside the package, or HTTPS URLs. An empty array is valid.                                                    |
-| `description`  | No       | Non-empty summary shown below the plugin ID in **Settings → Plugins**.                                                                       |
-| `translations` | No       | Listing text in other languages, read by the registry and ignored by Paseo. See [other languages](/docs/plugins/publishing#other-languages). |
-| `requirements` | No       | Supported Paseo versions, described below.                                                                                                   |
-| `build`        | No       | Preparation commands, described in the CLI reference.                                                                                        |
+| Field          | Required | Behavior                                                                                                                                            |
+| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`           | Yes      | Default installation ID.                                                                                                                            |
+| `name`         | No       | Non-empty display name for the registry, the website, your row in **Settings → Plugins**, and your settings header. Without it, Paseo shows the ID. |
+| `icon`         | No       | Relative path to a PNG inside the plugin package.                                                                                                   |
+| `media`        | No       | Array of image or video paths inside the package, or HTTPS URLs. An empty array is valid.                                                           |
+| `description`  | No       | Non-empty summary shown below the plugin name in **Settings → Plugins**.                                                                            |
+| `translations` | No       | Listing text in other languages, read by the registry and ignored by Paseo. See [other languages](/docs/plugins/publishing#other-languages).        |
+| `requirements` | No       | Supported Paseo versions, described below.                                                                                                          |
+| `build`        | No       | Preparation commands, described in the CLI reference.                                                                                               |
 
 Paths are relative to `paseo-plugin.json`, use forward slashes, and cannot contain `..`
 segments. Registry listings for visual plugins require an interface image even though `media` is
@@ -409,7 +409,7 @@ process, credential, and other machine-local work under `server/`. A plugin with
 ### Providers
 
 Follow [Build a provider plugin](/docs/plugins/providers) for direct and ACP implementations,
-session lifecycle, composer settings, timeline renderers, testing, and distribution.
+session lifecycle, option controls, timeline renderers, testing, and distribution.
 
 Call `server.registerProvider()` with a `ProviderRegistration` from
 `@getpaseo/plugin/server/provider`. Its connection accepts inputs with `send()` and emits complete state
@@ -420,10 +420,12 @@ Use the single `session.prompt` input for messages, structured commands, steerin
 effects. Repeat `clientMessageId` on the live user timeline item and publish exactly one matching
 `session.prompt_result`. Publish provider-created children as sessions with `parentSessionId`.
 
-Provider settings are toggle/select descriptors that Paseo renders in the composer. Keep
-provider-private options under `ProviderSessionConfig.providerOptions` on `session.open`.
-This record includes configured defaults and per-agent overrides; validate and apply it in your
-provider. See [Provider options](/docs/sdk/provider-options) for configuration and merge semantics.
+Provider options are one record, `ProviderSessionConfig.providerOptions` on `session.open`. It
+includes configured defaults and per-agent overrides; validate and apply it in your provider. Report
+`controls` in `session.config` for the top-level keys that get a toggle or select in the composer,
+with the values the session runs under `providerOptions`. A running-session change arrives as
+`session.configure` with `changes.providerOptions`. See [Provider options](/docs/sdk/provider-options)
+for configuration and merge semantics.
 Host tools arrive as MCP servers in the complete
 session config.
 
@@ -634,6 +636,13 @@ Cleanup can be async. Release timers, watchers, sockets, and other resources cre
 
 Register async handlers with `server.addHook(name, handler)`. See [Hooks](/docs/plugins/hooks) for names, payloads, ordering, errors, and complete examples.
 
+## Sidebar views
+
+`addSidebarView({ id, title, description?, Component })` registers an optional replacement for the
+sidebar content region. It returns cleanup. The user selects one view in Settings > Sidebar;
+registration does not activate it. See [Build a sidebar view](sidebar-views.md) for the props,
+ref-based queries and actions, device state and theme tokens.
+
 ## Screens and sidebar items
 
 A screen is a full page of plugin UI. A sidebar item is a component Paseo renders in the sidebar
@@ -1302,8 +1311,11 @@ Themes need a host that supports them. A client released before `addTheme` canno
 ## Settings screens
 
 Register a component with `client.addSettingsScreen({ id, title, icon, Component })` in
-`index.client.tsx`. It appears under **Settings → Plugins → your plugin** on that host.
-`id` is unique within the installation; `icon` is any [icon](#icons) form. Registration returns an
+`index.client.tsx`. Your plugin's row in **Settings → Plugins** on that host then shows a settings
+button (cog) that opens your first screen. When you register several screens, the settings page shows
+one tab per screen, labeled with its `title` and `icon`, in registration order. With one screen there
+are no tabs. The page header shows your manifest `name`, or your plugin ID when you leave `name`
+out; it never includes a screen title. `id` is unique within the installation; `icon` is any [icon](#icons) form. Registration returns an
 idempotent remover, and plugin teardown removes remaining screens.
 
 Call `client.openSettings(id)` or a Command Center callback's `openSettings(id)` to open one
@@ -1384,13 +1396,13 @@ export default function contribute(server: PluginServerContext) {
 }
 ```
 
-| Definition field               | Contract                                                                                                                             |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`                           | Lowercase identifier matching `[a-z][a-z0-9_-]*`; unique within the installation.                                                    |
-| `scope`                        | Required `"host"`. All authorized clients of that host share the document. No per-user, device-local, or cross-host synchronization. |
-| `version`                      | Required positive integer describing the schema, independent of the write revision.                                                  |
-| `schema`                       | Zod schema for JSON values. Supply defaults so parsing `{}` produces a complete document.                                            |
-| `migrate(values, fromVersion)` | Optional synchronous or asynchronous conversion from an older stored version. Its output must pass the current schema.               |
+| Definition field               | Contract                                                                                                                                                                                        |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                           | Lowercase identifier matching `[a-z][a-z0-9_-]*`; unique within the installation.                                                                                                               |
+| `scope`                        | Required `"host"` or `"device"`. Host documents are shared by authorized clients. Device documents stay on this device, keyed by installation and settings ID; use them for layout preferences. |
+| `version`                      | Required positive integer describing the schema, independent of the write revision.                                                                                                             |
+| `schema`                       | Zod schema for JSON values. Supply defaults so parsing `{}` produces a complete document.                                                                                                       |
+| `migrate(values, fromVersion)` | Optional synchronous or asynchronous conversion from an older stored version. Its output must pass the current schema.                                                                          |
 
 Call `useSettings(preferences)` in any contributed component. It returns a discriminated state:
 
@@ -1892,12 +1904,274 @@ header has no room for plugin buttons, so each one is a row of the workspace men
 icon and title; its menus and popovers open as pages of that sheet. Placement and overflow are host
 decisions.
 
+## Composer items
+
+`client.addComposerItem({ id, Component })` puts a component in the composer: the agent composer,
+the draft composer for a new agent, and the composer on the New workspace screen. `useComposer()`
+reads and changes what the composer configures, and `Toggle`, `Select` and `Action` from
+`@getpaseo/plugin/client/ui` draw the controls.
+
+```tsx
+import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+
+function ReviewFlag() {
+  const composer = useComposer();
+  return (
+    <Toggle
+      title="Needs review"
+      icon="Flag"
+      value={composer.agent.metadata["review.needsReview"] === true}
+      onValueChange={({ value }) =>
+        composer.setMetadata({ "review.needsReview": value ? true : null })
+      }
+    />
+  );
+}
+
+function Checklist() {
+  const composer = useComposer();
+  return (
+    <Action
+      title="Insert checklist"
+      icon="ListChecks"
+      onPress={() => composer.insertText("- [ ] Tests\n- [ ] Docs\n")}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
+  client.addComposerItem({ id: "checklist", Component: Checklist });
+  return () => {};
+}
+```
+
+`useComposer()` returns the composer the item sits in:
+
+| Field or command                                    | Meaning                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context`                                           | `"agent"` for a running agent, `"draft"` for a new agent in a workspace, `"new-workspace"` for the New workspace screen.                                                                                                                                                                                  |
+| `prompt`, `setPrompt(text)`, `insertText(text)`     | The prompt. `insertText` replaces the selection or inserts at the cursor.                                                                                                                                                                                                                                 |
+| `focus(options?)`                                   | Puts the cursor in this composer, ready to type, and resolves when it is there. `selection: { start, end }` places the cursor or selects text, as offsets into `prompt` clamped to its length; omit it to keep the cursor where it is. See [focus a composer](#focus-a-composer).                         |
+| `attachments`, `addAttachment`, `removeAttachment`  | Items from [your own attachment sources](#add-a-composer-attachment-source). Attachments from other plugins and Paseo's own are not listed.                                                                                                                                                               |
+| `agent.provider`, `model`, `mode`, `thinking`       | What the agent runs with, or what the draft will create.                                                                                                                                                                                                                                                  |
+| `agent.options`                                     | The provider options in effect, defaults included. In a draft: the options the agent will be created with, including your changes.                                                                                                                                                                        |
+| `agent.metadata`                                    | The agent's [metadata](/docs/plugins/hooks#metadata). In New workspace, the first agent's.                                                                                                                                                                                                                |
+| `setProvider`, `setModel`, `setMode`, `setThinking` | Return promises. `setProvider` resets the model like the provider picker. It rejects on `context: "agent"`, which keeps its provider, and for a provider the host does not offer. `setModel` and `setThinking` pass the value on as given; on a running agent the provider's refusal rejects the promise. |
+| `setOptions(patch)`, `setMetadata(patch)`           | Top-level keys replace; `null` removes the key. Metadata set in a draft is sent when the agent is created and cleared once the prompt is sent.                                                                                                                                                            |
+
+The same call does the same thing in every composer; a plugin does not choose a composer's
+implementation. `setMetadata` on a running agent needs a host that supports metadata. On an older
+host the promise rejects with "Update the host to use metadata."
+
+`Toggle` takes `value` and `onValueChange({ value })`. `Select` takes `value`, `options` (`{ value, label,
+description? }`) and `onValueChange({ value })`. `Action` takes `onPress(event)`. All three take `title`,
+`icon` (a [Lucide name, SVG or component](#icons)) and `disabled`. A callback may return a promise:
+the control stays disabled until it settles, and Paseo shows a rejection to the user as an error
+toast, the way it does for its own controls. Paseo owns where each control sits: inline in the
+toolbar when the composer has room, and a row in the composer's overflow sheet when it does not,
+which is always the case on a phone. A `Select` opens its list in place of the sheet row. A
+`Component` that renders something other than these controls draws it where its item is placed; in
+the overflow sheet that is the sheet.
+
+Each command acts on the composer's state when it runs, not on the render that created your
+callback, so `await composer.setProvider("codex")` followed by `await composer.setModel("gpt")`
+changes both. A command's promise resolves once the change has taken effect, and `composer.agent`
+shows it on the next render.
+
+While the New workspace screen creates the workspace and its agent, the composer is locked. Your
+controls render disabled, `setPrompt` and `insertText` throw, and the agent commands reject with
+"The composer is locked while the agent is being created." `composer.agent.options` and
+`composer.agent.metadata` are frozen copies; change them through `setOptions` and `setMetadata`.
+
+Paseo measures what an item renders in the toolbar to decide what fits, so an item that renders
+nothing takes no room and adds no overflow button. On wide composers the item stays mounted while
+it is in the overflow, and the overflow sheet mounts a second instance while it is open, so keep
+effects safe to run twice. On a phone an item mounts only while the overflow sheet is open.
+
+The [composer controls example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)
+registers a `Select`, two `Toggle`s (one writes a provider option) and an `Action`, plus an
+Explorer panel and a Command Center item that reach a composer by reference.
+
+### Focus a composer
+
+`insertText` and `setPrompt` do not move the cursor. Call `focus()` after them so the user can keep
+typing:
+
+```tsx
+composer.insertText("- [ ] Tests\n");
+await composer.focus();
+```
+
+`await composer.focus({ selection: { start: 0, end: composer.prompt.length } })` selects the prompt.
+
+You do not need to know where the user is. On a running agent's composer, Paseo navigates to the
+agent's tab or workspace when it is not on screen, closes a phone's agent list or Explorer panel
+that covers it, and moves focus to the agent's pane, then focuses the input. When the input is
+already on screen and focused in its pane, `focus()` only puts the cursor there. Every composer also
+closes the sheets, menus, pickers and image previews it opened over itself first, such as the
+controls sheet that holds your items on a phone. A phone opens its keyboard.
+
+`focus()` rejects when the composer cannot take focus: the agent was archived, its composer did not
+come on screen within 15 seconds, or the input refused focus, as it does on a phone while dictation
+is running. When calls overlap, the latest one decides where the cursor goes and the earlier ones
+settle with it. A rejected promise returned from a button's `onPress` or a Command Center item's
+`onSelect` shows the user an error toast.
+
+Drafts and the New workspace composer are only reachable from an item inside them, so `focus()` does
+not navigate to them. It works while the composer is on screen, and rejects with "The composer is
+not on screen." when the user has already moved on. A locked composer accepts focus.
+
+### Reach a composer by reference
+
+A running agent has a composer whether or not its tab is open. `useComposers(selector)` in any plugin
+component, `composers(selector)` on every command context, and `client.composers(selector)` on the
+client context return the same `PluginComposer` that `useComposer()` gives an item, for an agent you
+name or for the focused one. Use `client.composers` in a callback that receives no context, such as a
+[pill's `onPress`](#composer-pills):
+
+```tsx
+import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
+
+function InsertChecklist() {
+  const [focused] = useComposers({ focused: true });
+  return (
+    <Pressable disabled={!focused} onPress={() => focused?.insertText("- [ ] Tests\n")}>
+      <Text>Insert checklist</Text>
+    </Pressable>
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "tools",
+    title: "Tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component: InsertChecklist,
+  });
+  client.addCommandCenterItem({
+    id: "mark-for-review",
+    title: "Mark for review",
+    icon: "Flag",
+    context: "agent",
+    async onSelect({ agent, composers }) {
+      for (const composer of composers({ agentId: agent.id })) {
+        await composer.setMetadata({ "review.needsReview": true });
+      }
+    },
+  });
+  return () => {};
+}
+```
+
+| Selector            | Result                                                                                                                                                                                                                                                                                       |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ agentId }`       | The composer of that agent on this host. Empty for an agent that is unknown or archived.                                                                                                                                                                                                     |
+| `{ focused: true }` | The composer of the agent the Command Center hands to agent items: the focused agent tab of the workspace on screen. Empty when the screen is not a workspace, such as a plugin screen or New workspace, or when the focused tab is not an agent. It follows focus as the user changes tabs. |
+
+The result is always an array, empty or with one composer, so the same code reads either selector.
+`useComposers` re-renders when a composer changes. A composer from `composers()` is the state at the
+call; call `composers()` again for the next state.
+
+The commands are those of [`useComposer()`](#composer-items), with these differences for a composer
+you reach from outside:
+
+- `insertText` inserts at the cursor while the agent's composer is on screen. While it is not, for
+  example when the user is in another workspace, it appends to the agent's saved prompt, and the text
+  is in the input when the user returns. `setPrompt` replaces the saved prompt the same way.
+- A running agent's composer is never locked.
+- `setProvider` rejects, as it does inside the agent's own composer.
+- `setModel` and `setThinking` send the value to the provider unchecked. A value the provider refuses
+  rejects with the provider's message. `model` and `thinking` read what the model picker
+  shows at that moment: until the provider's catalog loads that is the id the agent reports or was
+  created with, which may be an alias, and once it loads the catalog's own id.
+- `focus()` reveals the composer first, as [described above](#focus-a-composer).
+- Drafts and the New workspace screen are not addressable by reference. Only an item inside one
+  reaches its composer, through `useComposer()`.
+
+## New workspace items
+
+`client.addNewWorkspaceItem({ id, Component })` puts a field on the New workspace screen, beside
+the project, host and branch pickers. `useNewWorkspace()` reads and changes what the screen will
+create, and `Combobox`, `Select`, `Toggle` and `Action` from `@getpaseo/plugin/client/ui` draw the
+fields. On desktop an item is a badge in the setup row; on a phone it is a full-width field.
+
+```tsx
+import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc } from "../shared/issues";
+
+function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata["issues.id"];
+  return (
+    <Combobox
+      title="Issue"
+      icon="CircleDot"
+      value={typeof issueId === "string" ? { id: issueId, label: issueId } : null}
+      search={async ({ query }) => (await searchIssues({ query })).issues}
+      onSelect={async ({ item }) => {
+        await newWorkspace.setBranch(item.branch);
+        await newWorkspace.setMetadata({ "issues.id": item.id });
+      }}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}
+```
+
+`useNewWorkspace()` returns the setup the item sits in:
+
+| Field or command            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`, `project`           | The user's choices, `{ id, label }` and `{ id, name } \| null`. Read-only: an item cannot switch host or project.                                                                                                                                                                                                                                                                                                                                     |
+| `isolation`, `setIsolation` | `"local"` or `"worktree"`. A project that cannot make worktrees reads `"local"`, and `setIsolation("worktree")` rejects.                                                                                                                                                                                                                                                                                                                              |
+| `baseRef`, `setBaseRef`     | What a new worktree starts from: `{ type: "branch", name }`, `{ type: "change-request", number }`, or `null` until the default is known. A branch's `name` is the exact ref creation uses, such as `refs/remotes/origin/main`, so `setBaseRef(newWorkspace.baseRef)` changes nothing. `setBaseRef` takes any ref the Base picker offers, or a bare branch name, which Paseo resolves as it does anywhere else. It rejects while no project is chosen. |
+| `branch`, `setBranch`       | The name of the branch a new worktree is created on. `null` lets Paseo pick one. It is kept while isolation is local or the base is a change request, and it names the new branch of any worktree that cuts one, from the default base or a chosen branch. It does not apply to a worktree that checks out an existing branch or change request.                                                                                                      |
+| `metadata`, `setMetadata`   | The created workspace's [metadata](/docs/plugins/hooks#metadata), not the first agent's. Top-level keys replace; `null` removes a key. Rejects on a host that does not support metadata with "Update the host to use metadata."                                                                                                                                                                                                                       |
+
+Commands follow the [composer item](#composer-items) rules: each one acts on the screen's state
+when it runs, so `await newWorkspace.setBranch(name)` followed by `newWorkspace.setMetadata(patch)`
+changes both, and its promise resolves once the change has taken effect. A command works from your component's first effect, including a mount effect. Payloads are JSON values.
+Your items are mounted for one project on one host. When the user changes either, Paseo remounts them and clears `branch` and `metadata`, so state and `Combobox` results for the previous project do not carry over; an item that sets up in a mount effect sets up again for the new project. A command called after its project or host has been left, such as the end of a lookup the user abandoned by switching, rejects with "The New workspace screen moved to another project or host; this item belongs to the previous one." and changes nothing; the items mounted for the new project are not affected.
+`host`, `project`, `baseRef` and `metadata` are frozen. While the screen creates the workspace it is locked: your fields render
+disabled and every command rejects with "The New workspace screen is locked while the workspace is
+being created." A callback that returns a promise keeps the control disabled until it settles, and a
+rejection reaches the user as an error toast.
+
+`Combobox` is a field with a searchable list whose results come from your code:
+
+| Prop       | Meaning                                                                                                                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `{ id, label, description? } \| null`, what the field shows. It need not be among the search results, so it can show a choice made earlier.                                           |
+| `search`   | `({ query }) => Promise<Item[]>`. Called with `""` when the list opens and again, debounced, as the user types. Each `Item` is `{ id, label, description? }` plus any fields you add. |
+| `onSelect` | `({ item }) => void \| Promise<void>`. `item` is the object `search` returned.                                                                                                        |
+
+Paseo shows "Searching…" while a search runs, "Search failed" with the error message when it
+rejects, and an empty state for no results. It keeps the previous results while a newer search runs
+and ignores a search that a newer one replaced, so `search` needs no cancellation of its own.
+`Combobox` takes the same `title`, `icon` and `disabled` as the other controls, and draws as a row
+with a list in the composer's overflow sheet too.
+
+The [New workspace issues example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)
+searches a fixed issue list from a daemon handler and sets the branch and metadata from the choice.
+
 ## Composer pills
 
 `client.addComposerPill({ id, workspaceId, agentId, button })` uses the same [button descriptor](#button-descriptor)
 and returns the same registration. It targets one agent's composer track alongside Tasks and
 Subagents. Composer pills always show the icon and `label` (or `title` when `label` is omitted).
-They never show a chevron, including for menus and popovers.
+Menus and popovers add an upward chevron on every layout, because their surface opens above the
+pill; actions show none, so a pill that runs on tap reads differently from one that opens something.
+The track keeps its space above the composer whether or not it has pills, so adding and removing
+pills does not move the transcript.
 
 ```tsx
 const pill = client.addComposerPill({
@@ -1918,6 +2192,31 @@ const pill = client.addComposerPill({
 });
 ```
 
+A pill's `onPress` receives no arguments. Reach its agent's composer with
+[`client.composers`](#reach-a-composer-by-reference):
+
+```tsx
+const pill = client.addComposerPill({
+  id: "hello",
+  workspaceId,
+  agentId,
+  button: {
+    title: "Add HELLO to the composer",
+    icon: "Hand",
+    label: "Hello",
+    behavior: {
+      kind: "action",
+      async onPress() {
+        for (const composer of client.composers({ agentId })) {
+          composer.insertText("HELLO");
+          await composer.focus();
+        }
+      },
+    },
+  },
+});
+```
+
 For pills that follow the agent directory, use an explicit [owned list subscription](/docs/sdk/events#follow-one-agents-status).
 The [local plugin example](https://github.com/getpaseo/paseo/blob/main/plugin-examples/local-plugin/client/main.tsx)
 replaces registrations on each snapshot and aborts the observation during entry cleanup, including pending bootstrap.
@@ -2078,6 +2377,8 @@ function PullRequestAction({ theme }: PluginSurfaceProps) {
 
 The returned API covers projects, workspaces, agents, terminals, providers, and daemon config. See the [SDK API reference](/docs/sdk/reference) for its methods. Connection lifecycle methods are intentionally absent because Paseo owns the connection.
 
+To run a helper the user shouldn't see, such as a classifier or summarizer, create it as a [background agent](/docs/sdk/agents#run-a-helper-as-a-background-agent) in an existing workspace.
+
 ### Discover hosts and target another host
 
 Use `useHosts()` to display configured hosts and `getPaseoClient(serverId)` in an action callback
@@ -2222,10 +2523,168 @@ export default function contribute(server: PluginServerContext) {
 }
 ```
 
-Inputs and outputs are validated on both sides. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations.
+Inputs are parsed once in the plugin process; outputs are parsed once on the client. Send schema inputs from the client and return output-schema inputs from the handler; schema transforms run at the receiving side. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations.
 
 Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](/docs/sdk/events) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory.
 
+## Stream events from the daemon {#subscriptions}
+
+A subscription runs a daemon handler for as long as one client listens and sends that client typed
+events. Use it for watchers, tails, and live media; use plugin RPC for a single answer.
+
+Define the contract in `shared/`:
+
+```ts
+// shared/diff.ts
+import { defineSubscription } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const diffWatch = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ cwd: z.string(), from: z.string() }),
+  event: z.object({ type: z.literal("changes"), files: z.array(z.string()) }),
+});
+```
+
+Handle it in `index.server.ts`. The handler receives `push` and an abort `signal` next to `paseo`:
+
+```ts
+server.handle(diffWatch, ({ cwd, from }, { push, signal }) => {
+  const watcher = watchChanges(cwd, from, (files) => void push({ type: "changes", files }));
+  signal.addEventListener("abort", () => watcher.close(), { once: true });
+});
+```
+
+Subscribe from a surface with `useSubscription(contract, input, onEvent)`:
+
+```tsx
+const [files, setFiles] = useState<string[]>([]);
+const subscription = useSubscription(diffWatch, { cwd, from: "HEAD" }, (event) => {
+  setFiles(event.files);
+});
+if (subscription.status === "error") return <Text>{subscription.error.message}</Text>;
+```
+
+Outside React, `client.subscribe` takes the same arguments plus options and returns a remover:
+
+```ts
+const stop = client.subscribe(diffWatch, { cwd, from: "HEAD" }, onChanges, { signal });
+await stop.ready; // the daemon accepted the subscription
+stop(); // or await stop.release()
+```
+
+RPCs and subscriptions share one name space; registering the same name for both fails the plugin
+load.
+
+### Handler lifetime
+
+| The handler...                                | Result                                                       |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| Throws synchronously, or the input is invalid | The subscribe call fails with the error. No events are sent. |
+| Returns nothing                               | The subscription stays open until the client releases it.    |
+| Returns a promise that resolves               | The subscription closes.                                     |
+| Returns a promise that rejects                | The subscription closes with the error.                      |
+
+`signal` aborts when the client releases the subscription, unmounts the hook, changes its input,
+disconnects, or the plugin stops. Pushes after the abort are dropped. `push` validates the event
+against the contract and resolves once the event has left the plugin process; await it in a loop
+to pace a producer.
+
+Each subscriber runs its own handler. Paseo does not share one handler between clients and does
+not replay missed events: after a reconnect or a plugin reload, mounted surfaces subscribe again and
+the handler starts from the beginning. Share an
+expensive watcher inside your plugin when several subscribers need it.
+
+`useSubscription` returns a union on `status`:
+
+| Status       | Meaning                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------- |
+| `connecting` | Sent; the daemon has not accepted it yet.                                                      |
+| `live`       | The handler is running. Events arrive through `onEvent`.                                       |
+| `closed`     | The handler finished.                                                                          |
+| `error`      | The subscribe failed, the handler failed, an event failed the contract, or the plugin stopped. |
+
+The hook subscribes again when `input` changes by shallow equality. `onEvent` is always the latest
+render's callback, so an inline function does not resubscribe. `client.subscribe` takes
+`{ signal, onClosed }`; `onClosed` receives `{ error? }`.
+
+### Bytes
+
+A top-level `Uint8Array` crosses the wire as binary, without JSON or base64. Everything else is
+JSON. The rule applies to subscription events, RPC outputs, and RPC inputs. A Node `Buffer` is a
+`Uint8Array`.
+
+```ts
+export const thumbnail = defineRpc({
+  name: "thumbnail.render",
+  input: z.object({ path: z.string(), width: z.number() }),
+  output: z.instanceof(Uint8Array),
+});
+
+// index.server.ts
+server.handle(thumbnail, ({ path, width }) => renderPng(path, width));
+
+// client
+const renderThumbnail = useRpc(thumbnail);
+const png = await renderThumbnail({ path, width }); // Uint8Array
+```
+
+Declare bytes with `z.instanceof(Uint8Array)`. An event can be bytes or JSON per push: declare a
+union and branch with `event instanceof Uint8Array`. A `Uint8Array` nested in an object fails
+validation on the sending side with an error that names the rule; send the bytes as their own
+event or RPC value and the metadata as a separate JSON event.
+
+One event or RPC value carries at most 100 MiB less 65 KiB of framing. Push large payloads in
+chunks of a few hundred KiB; each `push` waits for the previous one to leave the plugin process.
+Uploads from a phone have a lower limit: Android closes the connection when one send exceeds
+16 MiB, so split a larger upload into several RPCs.
+
+### Several streams on one subscription
+
+Put a header byte in front of each payload to multiplex streams. Keep the layout in `shared/`, so
+the handler and the surface call named functions:
+
+```ts
+// shared/media-frames.ts
+export const MediaOpcode = { Video: 0x01, Audio: 0x02 } as const;
+
+export function encodeMediaFrame(opcode: number, payload: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(1 + payload.byteLength);
+  bytes[0] = opcode;
+  bytes.set(payload, 1);
+  return bytes;
+}
+
+export function decodeMediaFrame(bytes: Uint8Array) {
+  return { opcode: bytes[0], payload: bytes.subarray(1) }; // a view, not a copy
+}
+
+export const mediaStream = defineSubscription({
+  name: "media.stream",
+  input: z.object({ source: z.string() }),
+  event: z.instanceof(Uint8Array),
+});
+```
+
+```ts
+useSubscription(mediaStream, { source }, (bytes) => {
+  const frame = decodeMediaFrame(bytes);
+  if (frame.opcode === MediaOpcode.Audio) audio.enqueue(frame.payload);
+  else video.draw(frame.payload);
+});
+```
+
+Events from one subscription arrive in push order, JSON and binary alike.
+`plugin-examples/media-stream` streams video and audio this way and uploads a frame back through
+an RPC with a `Uint8Array` input; `plugin-examples/diff-watch` watches a working tree.
+
+### Older hosts
+
+Subscriptions and binary RPC values need a host that advertises them. Against an older host,
+`useSubscription` reports `error` asking to update the host, `client.subscribe` rejects `ready`
+with the same message, and an RPC with a `Uint8Array` input or output fails. Raise your plugin's
+`requirements.paseo` to the release that ships subscriptions.
+
 ## Debug backend output
 
 Backend contributions can write to stdout and stderr with normal Node logging:
diff --git a/public-docs/plugins/reference.zh-CN.md b/public-docs/plugins/reference.zh-CN.md
index 5375b98c68..7331cb086b 100644
--- a/public-docs/plugins/reference.zh-CN.md
+++ b/public-docs/plugins/reference.zh-CN.md
@@ -73,10 +73,10 @@ my-plugin/
 | 字段           | 是否必填 | 行为                                                                                                       |
 | -------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
 | `id`           | 是       | 默认的安装 ID。                                                                                            |
-| `name`         | 否       | 注册表和网站使用的非空显示名称；与安装 ID 无关。                                                           |
+| `name`         | 否       | 注册表、网站、**设置 → 插件** 中的插件行以及插件设置页标题使用的非空显示名称。没有 `name` 时显示插件 ID。  |
 | `icon`         | 否       | 插件包内 PNG 文件的相对路径。                                                                              |
 | `media`        | 否       | 包内图片或视频路径的数组，或 HTTPS URL。空数组是有效的。                                                   |
-| `description`  | 否       | 在 **设置 → 插件** 中显示在插件 ID 下方的非空摘要。                                                        |
+| `description`  | 否       | 在 **设置 → 插件** 中显示在插件名称下方的非空摘要。                                                        |
 | `translations` | 否       | 其他语言的展示文本，由注册表读取，Paseo 会忽略它。见[其他语言](/docs/plugins/publishing#other-languages)。 |
 | `requirements` | 否       | 支持的 Paseo 版本，见下文。                                                                                |
 | `build`        | 否       | 准备命令，见 CLI 参考。                                                                                    |
@@ -353,13 +353,13 @@ Paseo 为服务端代码提供 `@getpaseo/plugin`、`@getpaseo/plugin/server`、
 
 ### Provider {#providers}
 
-直接实现和 ACP 实现、会话生命周期、Composer 设置、时间线渲染器、测试和分发，见[构建 Provider 插件](/docs/plugins/providers)。
+直接实现和 ACP 实现、会话生命周期、选项控件、时间线渲染器、测试和分发，见[构建 Provider 插件](/docs/plugins/providers)。
 
 使用来自 `@getpaseo/plugin/server/provider` 的 `ProviderRegistration` 调用 `server.registerProvider()`。它的连接通过 `send()` 接收输入，并通过 `onEvent()` 发出完整的状态快照。`send()` 只报告是否接受；提示词的处理结果、轮次、配置、持久化、权限和失败都是事件。
 
 消息、结构化命令、引导和命令副作用都使用同一个 `session.prompt` 输入。在实时的用户时间线条目上重复 `clientMessageId`，并恰好发布一个与之匹配的 `session.prompt_result`。把 Provider 创建的子会话发布为带有 `parentSessionId` 的会话。
 
-Provider 设置是 Paseo 在 Composer 中渲染的开关/选择描述符。把 Provider 私有的选项保留在 `session.open` 的 `ProviderSessionConfig.providerOptions` 中。这个记录包含配置的默认值和针对单个 Agent 的覆盖值；请在你的 Provider 中校验并应用它。配置和合并语义见 [Provider 选项](/docs/sdk/provider-options)。宿主工具以 MCP 服务器的形式出现在完整的会话配置中。
+Provider 选项是一个记录，即 `session.open` 中的 `ProviderSessionConfig.providerOptions`。它包含配置的默认值和针对单个 Agent 的覆盖值；请在你的 Provider 中校验并应用它。在 `session.config` 中为需要在 Composer 里显示开关或选择器的顶层键报告 `controls`，并在 `providerOptions` 下报告会话正在使用的值。运行中会话的修改会以 `session.configure` 的形式到达，内容在 `changes.providerOptions` 中。配置和合并语义见 [Provider 选项](/docs/sdk/provider-options)。宿主工具以 MCP 服务器的形式出现在完整的会话配置中。
 
 Paseo 刷新 Agent 的方式是关闭它当前的 Provider 会话，再用当前的配置和持久化值打开它。Provider 在 `session.open` 期间重新读取外部状态。
 
@@ -510,6 +510,10 @@ export default function contribute(client: PluginClientContext) {
 
 使用 `server.addHook(name, handler)` 注册异步处理函数。请参阅[钩子](/docs/plugins/hooks)，了解命名、载荷、顺序、错误处理和完整示例。
 
+## 侧边栏视图 {#sidebar-views}
+
+`addSidebarView({ id, title, description?, Component })` 注册可替换侧边栏内容区域的视图，并返回清理函数。用户在设置的侧边栏页面中选择视图；注册不会激活它。视图属性、基于引用的查询与操作、设备状态和主题令牌见[构建侧边栏视图](sidebar-views.md)。
+
 ## 界面和侧边栏项 {#screens-and-sidebar-items}
 
 界面是一整页的插件 UI。侧边栏项是 Paseo 在侧边栏顶部或底部渲染的组件；按下它时做什么由它决定。先注册界面，再注册一个打开它的项：
@@ -1087,7 +1091,7 @@ export default function contribute(client: PluginClientContext) {
 
 ## 设置界面 {#settings-screens}
 
-在 `index.client.tsx` 中用 `client.addSettingsScreen({ id, title, icon, Component })` 注册一个组件。它会出现在该主机的 **设置 → 插件 → 你的插件** 下。`id` 在同一次安装中唯一；`icon` 可以是任意一种[图标](#icons)形式。注册返回一个幂等的移除函数，插件销毁时会移除剩余的界面。
+在 `index.client.tsx` 中用 `client.addSettingsScreen({ id, title, icon, Component })` 注册一个组件。之后，该主机 **设置 → 插件** 中你的插件行会显示一个设置按钮（齿轮），点击后打开你的第一个界面。注册多个界面时，设置页面会按注册顺序为每个界面显示一个标签页，使用其 `title` 和 `icon`；只有一个界面时不显示标签页。页面标题显示 manifest 中的 `name`；没有 `name` 时显示插件 ID，且从不包含界面标题。`id` 在同一次安装中唯一；`icon` 可以是任意一种[图标](#icons)形式。注册返回一个幂等的移除函数，插件销毁时会移除剩余的界面。
 
 调用 `client.openSettings(id)` 或 Command Center 回调中的 `openSettings(id)` 可以打开你自己的某个界面。即使多台主机安装了同一个插件，每次安装也有各自的值和路由。
 
@@ -1157,13 +1161,13 @@ export default function contribute(server: PluginServerContext) {
 }
 ```
 
-| 定义字段                       | 契约                                                                                          |
-| ------------------------------ | --------------------------------------------------------------------------------------------- |
-| `id`                           | 匹配 `[a-z][a-z0-9_-]*` 的小写标识符；在同一次安装中唯一。                                    |
-| `scope`                        | 必须为 `"host"`。该主机所有获得授权的客户端共享这份文档。没有按用户、设备本地或跨主机的同步。 |
-| `version`                      | 必填的正整数，描述 schema 的版本，与写入修订号无关。                                          |
-| `schema`                       | JSON 值的 Zod schema。请提供默认值，使解析 `{}` 能得到一份完整的文档。                        |
-| `migrate(values, fromVersion)` | 可选的同步或异步函数，从较旧的存储版本转换。它的输出必须通过当前的 schema。                   |
+| 定义字段                       | 契约                                                                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `id`                           | 匹配 `[a-z][a-z0-9_-]*` 的小写标识符；在同一次安装中唯一。                                                              |
+| `scope`                        | 必填 `"host"` 或 `"device"`。主机文档由授权客户端共享。设备文档以插件安装和设置 ID 为键保存在当前设备上，用于布局偏好。 |
+| `version`                      | 必填的正整数，描述 schema 的版本，与写入修订号无关。                                                                    |
+| `schema`                       | JSON 值的 Zod schema。请提供默认值，使解析 `{}` 能得到一份完整的文档。                                                  |
+| `migrate(values, fromVersion)` | 可选的同步或异步函数，从较旧的存储版本转换。它的输出必须通过当前的 schema。                                             |
 
 在任何贡献的组件中调用 `useSettings(preferences)`。它返回一个可区分的状态：
 
@@ -1600,6 +1604,201 @@ review.remove();
 贡献移入一个共享的溢出菜单。在手机和较窄的窗口中，标题栏没有空间放置插件按钮，因此每个按钮都会成为工作区
 菜单（`···`）中的一行，显示它的图标和标题；它的菜单和弹出框以该底部面板中的页面打开。位置和溢出由宿主决定。
 
+## Composer 项 {#composer-items}
+
+`client.addComposerItem({ id, Component })` 把一个组件放进 composer：Agent composer、为新 Agent 准备的草稿 composer，以及新建工作区界面上的 composer。`useComposer()` 读取并修改 composer 所配置的内容，`@getpaseo/plugin/client/ui` 中的 `Toggle`、`Select` 和 `Action` 负责绘制控件。
+
+```tsx
+import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+
+function ReviewFlag() {
+  const composer = useComposer();
+  return (
+    <Toggle
+      title="Needs review"
+      icon="Flag"
+      value={composer.agent.metadata["review.needsReview"] === true}
+      onValueChange={({ value }) =>
+        composer.setMetadata({ "review.needsReview": value ? true : null })
+      }
+    />
+  );
+}
+
+function Checklist() {
+  const composer = useComposer();
+  return (
+    <Action
+      title="Insert checklist"
+      icon="ListChecks"
+      onPress={() => composer.insertText("- [ ] Tests\n- [ ] Docs\n")}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
+  client.addComposerItem({ id: "checklist", Component: Checklist });
+  return () => {};
+}
+```
+
+`useComposer()` 返回该项所在的 composer：
+
+| 字段或命令                                          | 含义                                                                                                                                                                                                                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `context`                                           | `"agent"` 表示运行中的 Agent，`"draft"` 表示工作区中的新 Agent，`"new-workspace"` 表示新建工作区界面。                                                                                                                                                       |
+| `prompt`、`setPrompt(text)`、`insertText(text)`     | 提示词。`insertText` 会替换选区，或在光标处插入。                                                                                                                                                                                                            |
+| `focus(options?)`                                   | 把光标放进这个 composer，准备输入，光标就位后完成。`selection: { start, end }` 放置光标或选中文本，为 `prompt` 中的偏移量，并限制在其长度内；省略时光标保持原位。参见[聚焦 composer](#focus-a-composer)。                                                    |
+| `attachments`、`addAttachment`、`removeAttachment`  | 来自[你自己的附件来源](#add-a-composer-attachment-source)的项目。其他插件和 Paseo 自身的附件不会列出。                                                                                                                                                       |
+| `agent.provider`、`model`、`mode`、`thinking`       | Agent 当前使用的配置，或草稿将要创建的配置。                                                                                                                                                                                                                 |
+| `agent.options`                                     | 当前生效的 Provider 选项，包含默认值。在草稿中：创建 Agent 时将使用的选项，包含你所做的修改。                                                                                                                                                                |
+| `agent.metadata`                                    | Agent 的[元数据](/docs/plugins/hooks#metadata)。在新建工作区中是第一个 Agent 的元数据。                                                                                                                                                                      |
+| `setProvider`、`setModel`、`setMode`、`setThinking` | 返回 Promise。`setProvider` 会像 Provider 选择器一样重置模型。在 `context: "agent"` 下（运行中的 Agent 保持其 Provider）以及主机不提供该 Provider 时会被拒绝。`setModel` 和 `setThinking` 原样传递该值；对运行中的 Agent，Provider 拒绝时 Promise 会被拒绝。 |
+| `setOptions(patch)`、`setMetadata(patch)`           | 顶层键替换，`null` 删除该键。草稿中设置的元数据在创建 Agent 时发送，发送提示词后清空。                                                                                                                                                                       |
+
+同一个调用在每个 composer 中行为一致，插件不需要选择 composer 的实现。在运行中的 Agent 上调用 `setMetadata` 需要支持元数据的主机；主机过旧时，Promise 会以 “Update the host to use metadata.” 拒绝。
+
+`Toggle` 接收 `value` 和 `onValueChange({ value })`。`Select` 接收 `value`、`options`（`{ value, label, description? }`）和 `onValueChange({ value })`。`Action` 接收 `onPress(event)`。三者都接收 `title`、`icon`（[Lucide 名称、SVG 或组件](#icons)）和 `disabled`。回调可以返回 Promise：在它完成之前控件保持禁用，被拒绝时 Paseo 会像对待自身控件一样，以错误提示向用户显示。控件的位置由 Paseo 决定：composer 空间足够时显示在工具栏中，不够时（手机上始终如此）成为 composer 溢出面板中的一行。`Select` 会就地打开列表，而不是替换面板中的行。`Component` 如果渲染这些控件以外的内容，会在其所在位置绘制；在溢出面板中，该位置就是面板。
+
+每个命令都按运行时 composer 的当前状态执行，而不是按创建回调的那次渲染，所以 `await composer.setProvider("codex")` 之后再 `await composer.setModel("gpt")` 会同时生效。命令的 Promise 在更改生效后完成，`composer.agent` 在下一次渲染时反映它。
+
+新建工作区界面在创建工作区及其 Agent 期间会锁定 composer。你的控件显示为禁用，`setPrompt` 和 `insertText` 会抛出错误，Agent 命令会以 "The composer is locked while the agent is being created." 拒绝。`composer.agent.options` 和 `composer.agent.metadata` 是冻结的副本；请通过 `setOptions` 和 `setMetadata` 修改它们。
+
+在 Paseo 知道渲染结果之前，composer 项就已计入可容纳的数量。不渲染任何内容的项仍可能在窄 composer 上留下空的溢出面板，所以请始终渲染一个控件。
+
+[Composer 控件示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)注册了一个 `Select`、两个 `Toggle`（其中一个写入 Provider 选项）和一个 `Action`，还有一个资源管理器面板和一个 Command Center 条目，它们按引用访问 composer。
+
+### 聚焦 composer {#focus-a-composer}
+
+`insertText` 和 `setPrompt` 不会移动光标。在它们之后调用 `focus()`，用户就可以继续输入：
+
+```tsx
+composer.insertText("- [ ] Tests\n");
+await composer.focus();
+```
+
+`await composer.focus({ selection: { start: 0, end: composer.prompt.length } })` 会选中提示词。
+
+你不需要知道用户在哪里。对于运行中 Agent 的 composer，当它不在屏幕上时，Paseo 会导航到该 Agent 的标签页或工作区，关闭手机上遮挡它的 Agent 列表或资源管理器面板，并把焦点移到该 Agent 的窗格，然后聚焦输入框。输入框已在屏幕上且其窗格已聚焦时，`focus()` 只放置光标。每个 composer 也会先关闭它在自身上方打开的面板、菜单、选择器和图片预览，例如手机上放置你的项的控件面板。手机会弹出键盘。
+
+composer 无法获得焦点时 `focus()` 会被拒绝：Agent 已归档、其 composer 未在 15 秒内出现在屏幕上，或输入框拒绝获得焦点（例如手机上正在听写时）。多次调用重叠时，由最后一次决定光标位置，之前的调用随其一起完成。按钮的 `onPress` 或命令中心项的 `onSelect` 返回被拒绝的 promise 时，会向用户显示错误提示。
+
+草稿和新建工作区 composer 只能从其中的项访问，所以 `focus()` 不会导航到它们。composer 在屏幕上时可用，用户已离开时会以 “The composer is not on screen.” 拒绝。锁定的 composer 接受聚焦。
+
+### 按引用访问 composer {#reach-a-composer-by-reference}
+
+运行中的 Agent 无论标签页是否打开，都有自己的 composer。任意插件组件中的 `useComposers(selector)`、每个命令上下文中的 `composers(selector)`，以及客户端上下文中的 `client.composers(selector)`，都会返回与 `useComposer()` 给 composer 项的相同的 `PluginComposer`，对象可以是你指定的 Agent，也可以是当前聚焦的 Agent。在不接收上下文的回调中（例如[胶囊的 `onPress`](#composer-pills)）使用 `client.composers`：
+
+```tsx
+import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
+
+function InsertChecklist() {
+  const [focused] = useComposers({ focused: true });
+  return (
+    <Pressable disabled={!focused} onPress={() => focused?.insertText("- [ ] Tests\n")}>
+      <Text>Insert checklist</Text>
+    </Pressable>
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "tools",
+    title: "Tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component: InsertChecklist,
+  });
+  client.addCommandCenterItem({
+    id: "mark-for-review",
+    title: "Mark for review",
+    icon: "Flag",
+    context: "agent",
+    async onSelect({ agent, composers }) {
+      for (const composer of composers({ agentId: agent.id })) {
+        await composer.setMetadata({ "review.needsReview": true });
+      }
+    },
+  });
+  return () => {};
+}
+```
+
+| 选择器              | 结果                                                                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ agentId }`       | 此主机上该 Agent 的 composer。Agent 未知或已归档时为空。                                                                                                                                             |
+| `{ focused: true }` | Command Center 交给 Agent 项的那个 Agent 的 composer：屏幕上工作区中聚焦的 Agent 标签页。当前界面不是工作区（例如插件界面或新建工作区），或聚焦的标签页不是 Agent 时为空，并随用户切换标签页而变化。 |
+
+结果始终是数组，为空或只含一个 composer，所以同一段代码可以读取任一选择器。composer 变化时 `useComposers` 会重新渲染。`composers()` 返回的 composer 是调用时的状态，要获取下一个状态请再次调用 `composers()`。
+
+命令与 [`useComposer()`](#composer-items) 相同，从外部访问时有以下差异：
+
+- Agent 的 composer 在屏幕上时，`insertText` 在光标处插入。不在屏幕上时（例如用户在另一个工作区），它会追加到该 Agent 已保存的提示词，用户回来时文本就在输入框里。`setPrompt` 以同样的方式替换已保存的提示词。
+- 运行中 Agent 的 composer 从不锁定。
+- `setProvider` 会被拒绝，与在 Agent 自己的 composer 内一样。
+- `setModel` 和 `setThinking` 不加检查地把值发给 Provider。Provider 拒绝的值会以 Provider 的消息拒绝。`model` 和 `thinking` 读取的是模型选择器此刻显示的值：在 Provider 的模型目录加载完成之前，是 Agent 上报或创建时使用的 id（可能是别名），加载完成后是目录中的 id。
+- `focus()` 会先让 composer 显示出来，如[上文所述](#focus-a-composer)。
+- 草稿和新建工作区界面不能按引用访问，只有其中的项能通过 `useComposer()` 访问其 composer。
+
+## 新建工作区项 {#new-workspace-items}
+
+`client.addNewWorkspaceItem({ id, Component })` 在新建工作区界面上放置一个字段，位于项目、主机和分支选择器旁边。`useNewWorkspace()` 读取并修改界面将要创建的内容，`@getpaseo/plugin/client/ui` 中的 `Combobox`、`Select`、`Toggle` 和 `Action` 负责绘制字段。桌面端的项是设置行中的徽章；手机上是整行宽度的字段。
+
+```tsx
+import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc } from "../shared/issues";
+
+function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata["issues.id"];
+  return (
+    <Combobox
+      title="Issue"
+      icon="CircleDot"
+      value={typeof issueId === "string" ? { id: issueId, label: issueId } : null}
+      search={async ({ query }) => (await searchIssues({ query })).issues}
+      onSelect={async ({ item }) => {
+        await newWorkspace.setBranch(item.branch);
+        await newWorkspace.setMetadata({ "issues.id": item.id });
+      }}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}
+```
+
+`useNewWorkspace()` 返回该项所在的设置：
+
+| 字段或命令                  | 含义                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`、`project`           | 用户的选择，分别是 `{ id, label }` 和 `{ id, name } \| null`。只读：项不能切换主机或项目。                                                                                                                                                                                                                                                                              |
+| `isolation`、`setIsolation` | `"local"` 或 `"worktree"`。无法创建 worktree 的项目读取为 `"local"`，此时 `setIsolation("worktree")` 会被拒绝。                                                                                                                                                                                                                                                         |
+| `baseRef`、`setBaseRef`     | 新 worktree 的起点：`{ type: "branch", name }`、`{ type: "change-request", number }`，默认值未知时为 `null`。分支的 `name` 是创建时实际使用的完整 ref，例如 `refs/remotes/origin/main`，所以 `setBaseRef(newWorkspace.baseRef)` 不会改变任何内容。`setBaseRef` 接受 Base 选择器提供的任何 ref，或一个裸分支名，Paseo 会按其他地方一贯的方式解析。未选择项目时会被拒绝。 |
+| `branch`、`setBranch`       | 新 worktree 所创建的分支名称。`null` 表示由 Paseo 选择名称。隔离为本地或起点为变更请求时会保留该值，它为任何新建分支的 worktree 命名，起点可以是默认基线或所选分支；检出已有分支或变更请求的 worktree 不适用。                                                                                                                                                          |
+| `metadata`、`setMetadata`   | 所创建工作区的[元数据](/docs/plugins/hooks#metadata)，而不是第一个 Agent 的元数据。顶层键替换，`null` 删除该键。主机不支持元数据时以 “Update the host to use metadata.” 拒绝。                                                                                                                                                                                          |
+
+命令遵循 [Composer 项](#composer-items)的规则：每个命令都按界面运行时的状态执行，所以 `await newWorkspace.setBranch(name)` 之后再调用 `newWorkspace.setMetadata(patch)` 会同时生效，命令的 Promise 在更改生效后完成。命令从组件的第一个 effect 起即可使用，包括挂载时的 effect。载荷是 JSON 值。你的项针对某一台主机上的某一个项目挂载。用户更改其中任何一个时，Paseo 会重新挂载你的项并清除 `branch` 和 `metadata`，因此上一个项目的状态和 `Combobox` 结果不会保留；在挂载 effect 中做初始化的项会针对新项目再次初始化。在其项目或主机已被离开之后才调用的命令（例如用户切换项目时被放弃的查询最终返回）会以 "The New workspace screen moved to another project or host; this item belongs to the previous one." 拒绝，并且不做任何更改；为新项目挂载的项不受影响。`host`、`project`、`baseRef` 和 `metadata` 是冻结的。界面创建工作区期间会被锁定：你的字段显示为禁用，所有命令都会以 "The New workspace screen is locked while the workspace is being created." 拒绝。返回 Promise 的回调在完成之前会让控件保持禁用，被拒绝时会以错误提示向用户显示。
+
+`Combobox` 是带可搜索列表的字段，结果由你的代码提供：
+
+| 属性       | 含义                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `{ id, label, description? } \| null`，字段显示的内容。它不必出现在搜索结果中，因此可以显示之前所做的选择。                                       |
+| `search`   | `({ query }) => Promise<Item[]>`。列表打开时以 `""` 调用，之后随用户输入防抖调用。每个 `Item` 是 `{ id, label, description? }` 加上你添加的字段。 |
+| `onSelect` | `({ item }) => void \| Promise<void>`。`item` 就是 `search` 返回的对象。                                                                          |
+
+搜索进行时 Paseo 显示 “Searching…”，搜索被拒绝时显示 “Search failed” 和错误信息，没有结果时显示空状态。新搜索进行期间会保留之前的结果，并忽略已被更新搜索取代的结果，所以 `search` 不需要自己处理取消。`Combobox` 接收与其他控件相同的 `title`、`icon` 和 `disabled`。
+
+[新建工作区 Issue 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)通过守护进程处理器搜索一个固定的 Issue 列表，并根据所选项设置分支和元数据。
+
 ## Composer 胶囊 {#composer-pills}
 
 `client.addComposerPill({ id, workspaceId, agentId, button })` 使用同样的[按钮描述符](#button-descriptor)，
@@ -1625,6 +1824,30 @@ const pill = client.addComposerPill({
 });
 ```
 
+胶囊的 `onPress` 不接收参数。通过 [`client.composers`](#reach-a-composer-by-reference) 访问其 Agent 的 composer：
+
+```tsx
+const pill = client.addComposerPill({
+  id: "hello",
+  workspaceId,
+  agentId,
+  button: {
+    title: "Add HELLO to the composer",
+    icon: "Hand",
+    label: "Hello",
+    behavior: {
+      kind: "action",
+      async onPress() {
+        for (const composer of client.composers({ agentId })) {
+          composer.insertText("HELLO");
+          await composer.focus();
+        }
+      },
+    },
+  },
+});
+```
+
 对于随 Agent 目录变化的胶囊，请使用显式的[自有列表订阅](/docs/sdk/events#follow-one-agents-status)。
 [本地插件示例](https://github.com/getpaseo/paseo/blob/main/plugin-examples/local-plugin/client/main.tsx)
 会在每次快照时替换注册，并在入口清理时中止观察，包括尚未完成的引导过程。
@@ -1779,6 +2002,8 @@ function PullRequestAction({ theme }: PluginSurfaceProps) {
 
 返回的 API 涵盖项目、工作区、Agent、终端、Provider 和 daemon 配置。其方法请参阅 [SDK API 参考](/docs/sdk/reference)。这里刻意没有连接生命周期方法，因为连接由 Paseo 负责。
 
+如果要运行用户不需要看到的辅助任务，例如分类或摘要，请在已有工作区中把它创建为[后台 Agent](/docs/sdk/agents#run-a-helper-as-a-background-agent)。
+
 ### 发现主机并指定另一台主机 {#discover-hosts-and-target-another-host}
 
 使用 `useHosts()` 显示已配置的主机，并在操作回调中使用 `getPaseoClient(serverId)` 对其中一台主机
@@ -1924,6 +2149,140 @@ export default function contribute(server: PluginServerContext) {
 
 后端处理函数以 `{ paseo }` 的形式收到同样的 `PaseoApi`。它们的连接属于子进程，并在插件停止时关闭。在插件代码订阅之前，它不会订阅时间线或目录事件。清理和时间线替换请遵循 [SDK 事件契约](/docs/sdk/events)。后端代码可以使用 Node API 以及安装在插件目录中的依赖。
 
+## 从 daemon 推送事件 {#subscriptions}
+
+订阅会在一个客户端监听期间运行 daemon 处理函数，并向该客户端发送带类型的事件。监听文件、追踪日志和实时媒体使用订阅；只需要一次应答时使用插件 RPC。
+
+在 `shared/` 中定义契约：
+
+```ts
+// shared/diff.ts
+import { defineSubscription } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const diffWatch = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ cwd: z.string(), from: z.string() }),
+  event: z.object({ type: z.literal("changes"), files: z.array(z.string()) }),
+});
+```
+
+在 `index.server.ts` 中处理它。处理函数除了 `paseo`，还会收到 `push` 和一个中止 `signal`：
+
+```ts
+server.handle(diffWatch, ({ cwd, from }, { push, signal }) => {
+  const watcher = watchChanges(cwd, from, (files) => void push({ type: "changes", files }));
+  signal.addEventListener("abort", () => watcher.close(), { once: true });
+});
+```
+
+在界面中用 `useSubscription(contract, input, onEvent)` 订阅：
+
+```tsx
+const [files, setFiles] = useState<string[]>([]);
+const subscription = useSubscription(diffWatch, { cwd, from: "HEAD" }, (event) => {
+  setFiles(event.files);
+});
+if (subscription.status === "error") return <Text>{subscription.error.message}</Text>;
+```
+
+在 React 之外，`client.subscribe` 接受同样的参数和一个选项对象，并返回一个移除函数：
+
+```ts
+const stop = client.subscribe(diffWatch, { cwd, from: "HEAD" }, onChanges, { signal });
+await stop.ready; // the daemon accepted the subscription
+stop(); // or await stop.release()
+```
+
+RPC 和订阅共用一个名称空间；同一个名称同时注册为 RPC 和订阅会导致插件加载失败。
+
+### 处理函数的生命周期 {#handler-lifetime}
+
+| 处理函数……               | 结果                                         |
+| ------------------------ | -------------------------------------------- |
+| 同步抛出错误，或输入无效 | 订阅调用失败并返回该错误，不会发送任何事件。 |
+| 不返回任何值             | 订阅保持打开，直到客户端释放它。             |
+| 返回一个兑现的 Promise   | 订阅关闭。                                   |
+| 返回一个拒绝的 Promise   | 订阅关闭并带上该错误。                       |
+
+当客户端释放订阅、卸载 hook、更改输入、断开连接，或者插件停止时，`signal` 会中止。中止之后的推送会被丢弃。`push` 会按契约校验事件，并在事件离开插件进程后兑现；在循环中 await 它可以控制生产者的速度。
+
+每个订阅者运行各自的处理函数。Paseo 不会在多个客户端之间共享同一个处理函数，也不会重放错过的事件：重新连接或重新加载插件之后，已挂载的界面会重新订阅，处理函数从头开始运行。多个订阅者需要同一个昂贵的监听器时，请在插件内部共享它。
+
+`useSubscription` 返回一个以 `status` 区分的联合类型：
+
+| 状态         | 含义                                                     |
+| ------------ | -------------------------------------------------------- |
+| `connecting` | 已发送，daemon 尚未接受。                                |
+| `live`       | 处理函数正在运行，事件通过 `onEvent` 送达。              |
+| `closed`     | 处理函数已结束。                                         |
+| `error`      | 订阅失败、处理函数失败、事件不符合契约，或者插件已停止。 |
+
+`input` 按浅比较发生变化时，hook 会重新订阅。`onEvent` 始终是最近一次渲染的回调，所以内联函数不会导致重新订阅。`client.subscribe` 接受 `{ signal, onClosed }`；`onClosed` 会收到 `{ error? }`。
+
+### 字节 {#bytes}
+
+顶层的 `Uint8Array` 以二进制形式传输，不经过 JSON 或 base64，其他值都是 JSON。这条规则适用于订阅事件、RPC 输出和 RPC 输入。Node 的 `Buffer` 也是 `Uint8Array`。
+
+```ts
+export const thumbnail = defineRpc({
+  name: "thumbnail.render",
+  input: z.object({ path: z.string(), width: z.number() }),
+  output: z.instanceof(Uint8Array),
+});
+
+// index.server.ts
+server.handle(thumbnail, ({ path, width }) => renderPng(path, width));
+
+// client
+const renderThumbnail = useRpc(thumbnail);
+const png = await renderThumbnail({ path, width }); // Uint8Array
+```
+
+用 `z.instanceof(Uint8Array)` 声明字节。事件可以在每次推送时选择字节或 JSON：声明一个联合类型，并用 `event instanceof Uint8Array` 分支。嵌套在对象中的 `Uint8Array` 会在发送端校验失败，错误信息会说明这条规则；把字节作为单独的事件或 RPC 值发送，元数据作为另一个 JSON 事件发送。
+
+一个事件或 RPC 值最多 100 MiB（减去 65 KiB 的帧头）。大载荷请按几百 KiB 分块推送；每次 `push` 都会等待上一次离开插件进程。手机上传的上限更低：一次发送超过 16 MiB 时 Android 会关闭连接，所以较大的上传请拆成多个 RPC。
+
+### 在一个订阅中传输多条流 {#several-streams-on-one-subscription}
+
+在每个载荷前加一个头字节即可复用多条流。把布局放在 `shared/` 中，让处理函数和界面调用有名字的函数：
+
+```ts
+// shared/media-frames.ts
+export const MediaOpcode = { Video: 0x01, Audio: 0x02 } as const;
+
+export function encodeMediaFrame(opcode: number, payload: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(1 + payload.byteLength);
+  bytes[0] = opcode;
+  bytes.set(payload, 1);
+  return bytes;
+}
+
+export function decodeMediaFrame(bytes: Uint8Array) {
+  return { opcode: bytes[0], payload: bytes.subarray(1) }; // a view, not a copy
+}
+
+export const mediaStream = defineSubscription({
+  name: "media.stream",
+  input: z.object({ source: z.string() }),
+  event: z.instanceof(Uint8Array),
+});
+```
+
+```ts
+useSubscription(mediaStream, { source }, (bytes) => {
+  const frame = decodeMediaFrame(bytes);
+  if (frame.opcode === MediaOpcode.Audio) audio.enqueue(frame.payload);
+  else video.draw(frame.payload);
+});
+```
+
+同一个订阅的事件按推送顺序到达，JSON 和二进制都一样。`plugin-examples/media-stream` 用这种方式传输视频和音频，并通过一个输入为 `Uint8Array` 的 RPC 把一帧上传回去；`plugin-examples/diff-watch` 监听工作树。
+
+### 旧版主机 {#older-hosts}
+
+订阅和二进制 RPC 值需要主机声明支持。连接旧版主机时，`useSubscription` 会报告 `error` 并提示更新主机，`client.subscribe` 的 `ready` 会以同样的信息拒绝，带有 `Uint8Array` 输入或输出的 RPC 会失败。请把插件的 `requirements.paseo` 提高到包含订阅功能的版本。
+
 ## 调试后端输出 {#debug-backend-output}
 
 后端贡献可以用普通的 Node 日志写入 stdout 和 stderr：
diff --git a/public-docs/plugins/sidebar-views.md b/public-docs/plugins/sidebar-views.md
new file mode 100644
index 0000000000..542c0f6166
--- /dev/null
+++ b/public-docs/plugins/sidebar-views.md
@@ -0,0 +1,177 @@
+# Build a sidebar view
+
+A sidebar view replaces the content between Paseo's header and footer. You receive theme tokens,
+active entity refs and navigation methods, then render your own React Native UI. Install the
+[sidebar-views example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/sidebar-views)
+to try projects, task-based agents, nested agents and label folders.
+
+## Register a view
+
+```tsx
+import type {
+  PluginClientContext,
+  PluginSidebarViewProps,
+  WorkspaceRef,
+} from "@getpaseo/plugin/client";
+import { useWorkspaces, useWorkspace } from "@getpaseo/plugin/client";
+import { Pressable, ScrollView, Text } from "react-native";
+
+function WorkspaceRow({
+  reference,
+  navigation,
+  theme,
+}: {
+  reference: WorkspaceRef;
+  navigation: PluginSidebarViewProps["navigation"];
+  theme: PluginSidebarViewProps["theme"];
+}) {
+  const workspace = useWorkspace(reference);
+  if (!workspace) return null;
+  return (
+    <Pressable onPress={() => navigation.openWorkspace(reference)}>
+      <Text style={{ color: theme.colors.foreground }}>{workspace.title ?? workspace.name}</Text>
+    </Pressable>
+  );
+}
+function Workspaces({ navigation, theme }: PluginSidebarViewProps) {
+  const workspaces = useWorkspaces({ orderBy: "name" });
+  return (
+    <ScrollView>
+      {workspaces.map((reference) => (
+        <WorkspaceRow
+          key={reference.key}
+          reference={reference}
+          navigation={navigation}
+          theme={theme}
+        />
+      ))}
+    </ScrollView>
+  );
+}
+export default function contribute(client: PluginClientContext) {
+  return client.addSidebarView({ id: "workspaces", title: "My workspaces", Component: Workspaces });
+}
+```
+
+Registration adds an option under **Settings > Sidebar > Sidebar view**. The user selects it;
+installing the plugin leaves the current view selected. Header navigation, plugin header items,
+the callout and footer stay visible. A missing or disabled view falls back to Default view.
+A view that throws shows a placeholder with **Use default view**.
+
+The view renders once across connected hosts. `active.workspace` and `active.agent` are refs or
+`null`. Use `navigation.openWorkspace`, `openAgent`, `openTerminal` or `openProject` with a ref;
+`openProject` starts the new workspace flow. Navigation closes the compact sidebar. Call
+`dismiss()` after navigation you implement yourself.
+
+## Query refs, read each row
+
+`useWorkspaces`, `useAgents`, `useProjects` and `useTerminals` return immutable arrays of refs.
+A ref has `kind`, `hostId`, `id` and a cross-host `key`. The same entity keeps the same frozen
+ref for the app session. Pass it to `useWorkspace`, `useAgent`, `useProject` or `useTerminal`
+inside the row. A deleted entity returns `null`.
+
+```tsx
+const projects = useProjects({ orderBy: "displayName" }); // Includes empty projects.
+const agents = useAgents({
+  hosts: [hostId],
+  where: (agent) => agent.workspace.key === workspaceRef.key,
+  orderBy: ["lastActivityAt", "desc"],
+});
+const folders = useWorkspaces({
+  groupBy: (workspace) => workspace.labels, // A workspace can appear in several folders.
+});
+```
+
+Every query accepts `hosts` (server IDs), `where`, `orderBy` and `groupBy`. Omit `hosts` to query
+every connected host. `orderBy` accepts a snapshot field, `[field, "asc" | "desc"]`, or a
+comparator. Null fields sort last. Keep comparators cheap; they run when data changes.
+`groupBy` returns a string, `{ key, title?, color? }`, or an array of these. Grouped results have
+`key`, `title`, `color` and `items`. Groups follow first appearance after sorting; duplicate keys
+use the first title. An empty array puts an item in no group.
+
+An unchanged ref sequence keeps its array identity. Groups keep their identity when their
+metadata and item sequence stay the same. A workspace status change updates that row without
+rendering the list again. A grouping change updates the affected groups. Inline query objects
+and functions work without managing subscriptions yourself.
+
+Entity hooks accept a selector and optional equality function:
+
+```tsx
+const workspace = useWorkspace(ref); // Interned snapshot, compared by identity.
+const name = useWorkspace(ref, (item) => ({ title: item.title })); // Shallow equality.
+const selected = useWorkspace(ref, selector, equals);
+```
+
+Without a selector, custom equality receives snapshots. With a selector, it receives selections.
+Existing workspace panels can continue passing a host-local string ID to `useWorkspace` and
+`useAgent`. Prefer refs for a view spanning hosts. `useHosts()` retains its existing
+`serverId`, `label` and connection `status` fields.
+
+Workspace snapshots include `project`, `pinnedAt`, `labels`, `background`, `branch`,
+`lastPromptAt`, `parentAgent` and `createdAt` (null on older hosts). Use `indicator` and the
+localized `indicatorLabel` to display the status Paseo shows. `status` remains the raw daemon
+status. Agent snapshots include their workspace and parent refs. Project snapshots provide
+`displayName`, `rootPath`, `kind` and `iconRevision`.
+
+## List terminals
+
+The terminals example selects a host, lists its terminals, focuses a terminal tab and closes a
+terminal through its handle. `useTerminals({ hosts: [hostId] })` requires a host advertising
+`terminalCollection`. A terminal reader throws an update-host error for an unsupported queried
+host; other entity hooks continue working. Keep host selection outside an error boundary so the
+user can select another host. Omit `hosts` to require the capability on every connected host.
+
+Terminal snapshots contain `workspace`, `title`, `isScript` and `createdAt`. A terminal kept alive
+by a worker from before timestamp tracking has `createdAt: null`. Script ownership follows
+workspace script runtime entries. The host observation follows terminal creation, closure, title
+changes and reconnects, and releases when its last plugin subscriber leaves.
+
+## Act on a ref
+
+`usePaseo()` routes ref-based actions to the ref's host:
+
+```tsx
+const paseo = usePaseo();
+await paseo.workspaces.ref(workspaceRef).setPinned(true);
+await paseo.workspaces.ref(workspaceRef).setLabel("Later", { assigned: true });
+await paseo.workspaces.ref(workspaceRef).setLabel("Inbox", { assigned: false });
+paseo.projects.ref(projectRef).open();
+await paseo.projects.ref(projectRef).createWorkspace();
+paseo.terminals.ref(terminalRef).focus();
+await paseo.terminals.ref(terminalRef).kill();
+```
+
+Workspace and agent handles retain their existing methods. Assigning a new label creates it;
+assigning an existing label keeps its color. The label-folder example adds the destination
+before removing the source, so a failed assignment preserves the original folder. It owns the
+move gesture and error display.
+
+## Keep layout choices on the device
+
+Define a [settings document](reference.md#settings-screens) with `scope: "device"` for collapsed
+folders or manual order. `useSettings` reads and writes it through the same revision-based API
+as host settings. Device documents belong to the installation and settings ID, persist across
+app launches, and are shared across that installation's client surfaces. They are not synced
+to other devices. Use `scope: "host"` for data clients should share through the daemon.
+
+## Match the app's density
+
+Render with React Native primitives. The SDK exports no sidebar-view rows, sections, lists,
+badges or drag helpers. The existing header/footer item kit is a separate surface.
+
+For a dense row use a minimum height of 28, horizontal padding of 12, a 12-point primary label
+with 16-point line height and an 11-point secondary label. Use these supplied tokens:
+
+| Row element                      | Theme token              |
+| -------------------------------- | ------------------------ |
+| Primary label                    | `colors.foreground`      |
+| Secondary label, section heading | `colors.foregroundMuted` |
+| Selected row fill                | `colors.surface2`        |
+| Separator                        | `colors.border`          |
+| Action or focus accent           | `colors.accent`          |
+| Success indicator                | `colors.statusSuccess`   |
+| Needs input indicator            | `colors.statusWarning`   |
+| Failure indicator                | `colors.statusDanger`    |
+
+Give pressable rows an accessible label and show controls on touch layouts. The examples use
+only plugin-owned components and the tokens passed to the view.
diff --git a/public-docs/plugins/sidebar-views.zh-CN.md b/public-docs/plugins/sidebar-views.zh-CN.md
new file mode 100644
index 0000000000..0c6ab89d33
--- /dev/null
+++ b/public-docs/plugins/sidebar-views.zh-CN.md
@@ -0,0 +1,135 @@
+# 构建侧边栏视图 {#build-a-sidebar-view}
+
+侧边栏视图替换 Paseo 页眉与页脚之间的内容。插件接收主题令牌、当前实体引用和导航方法，使用 React Native 绘制自己的界面。安装[侧边栏视图示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/sidebar-views)，体验项目列表、按任务分组的 Agent、嵌套 Agent 和标签文件夹。
+
+## 注册视图 {#register-a-view}
+
+```tsx
+import type {
+  PluginClientContext,
+  PluginSidebarViewProps,
+  WorkspaceRef,
+} from "@getpaseo/plugin/client";
+import { useWorkspaces, useWorkspace } from "@getpaseo/plugin/client";
+import { Pressable, ScrollView, Text } from "react-native";
+
+function WorkspaceRow({
+  reference,
+  navigation,
+  theme,
+}: {
+  reference: WorkspaceRef;
+  navigation: PluginSidebarViewProps["navigation"];
+  theme: PluginSidebarViewProps["theme"];
+}) {
+  const workspace = useWorkspace(reference);
+  if (!workspace) return null;
+  return (
+    <Pressable onPress={() => navigation.openWorkspace(reference)}>
+      <Text style={{ color: theme.colors.foreground }}>{workspace.title ?? workspace.name}</Text>
+    </Pressable>
+  );
+}
+function Workspaces({ navigation, theme }: PluginSidebarViewProps) {
+  const workspaces = useWorkspaces({ orderBy: "name" });
+  return (
+    <ScrollView>
+      {workspaces.map((reference) => (
+        <WorkspaceRow
+          key={reference.key}
+          reference={reference}
+          navigation={navigation}
+          theme={theme}
+        />
+      ))}
+    </ScrollView>
+  );
+}
+export default function contribute(client: PluginClientContext) {
+  return client.addSidebarView({ id: "workspaces", title: "My workspaces", Component: Workspaces });
+}
+```
+
+注册后，用户可以在**设置 → 侧边栏 → 侧边栏视图**中选择该视图。安装插件不会切换当前视图。页眉导航、插件页眉项、提示区域和页脚保持可见。所选视图缺失或被禁用时，显示默认视图。视图抛出异常时，显示带有**使用默认视图**按钮的占位界面。
+
+视图同时展示所有已连接主机的数据。`active.workspace` 和 `active.agent` 是引用或 `null`。将引用传给 `navigation.openWorkspace`、`openAgent`、`openTerminal` 或 `openProject`；`openProject` 打开新建工作区流程。导航会关闭紧凑布局的侧边栏。如果插件自行执行导航，完成后调用 `dismiss()`。
+
+## 查询引用，逐行读取 {#query-refs-read-each-row}
+
+`useWorkspaces`、`useAgents`、`useProjects` 和 `useTerminals` 返回不可变的引用数组。引用包含 `kind`、`hostId`、`id` 和跨主机唯一的 `key`。在一次应用会话中，同一实体使用同一个冻结引用。在行组件内将它传给 `useWorkspace`、`useAgent`、`useProject` 或 `useTerminal`。实体删除后返回 `null`。
+
+```tsx
+const projects = useProjects({ orderBy: "displayName" }); // Includes empty projects.
+const agents = useAgents({
+  hosts: [hostId],
+  where: (agent) => agent.workspace.key === workspaceRef.key,
+  orderBy: ["lastActivityAt", "desc"],
+});
+const folders = useWorkspaces({
+  groupBy: (workspace) => workspace.labels, // A workspace can appear in several folders.
+});
+```
+
+每个查询都支持 `hosts`（服务器 ID）、`where`、`orderBy` 和 `groupBy`。省略 `hosts` 时查询所有已连接主机。`orderBy` 接受快照字段、`[field, "asc" | "desc"]` 或比较函数。空值排在最后。比较函数会在数据变化时执行，应保持开销较小。
+
+`groupBy` 返回字符串、`{ key, title?, color? }` 或这些值组成的数组。分组结果包含 `key`、`title`、`color` 和 `items`。分组按排序后首次出现的顺序排列；重复的键使用第一个标题。返回空数组表示该项不属于任何分组。
+
+引用序列不变时，数组对象保持不变。分组的元数据和项序列不变时，分组对象保持不变。工作区状态变化只更新对应行，不会重新渲染整个列表。分组变化会更新受影响的分组。查询对象和函数可以内联编写，无需自行管理订阅。
+
+实体钩子支持选择器和可选的相等比较函数：
+
+```tsx
+const workspace = useWorkspace(ref); // Interned snapshot, compared by identity.
+const name = useWorkspace(ref, (item) => ({ title: item.title })); // Shallow equality.
+const selected = useWorkspace(ref, selector, equals);
+```
+
+没有选择器时，自定义相等比较函数接收快照；有选择器时接收选择结果。现有工作区面板仍可向 `useWorkspace` 和 `useAgent` 传入主机本地的字符串 ID。跨主机视图应使用引用。`useHosts()` 保留现有的 `serverId`、`label` 和连接 `status` 字段。
+
+工作区快照包含 `project`、`pinnedAt`、`labels`、`background`、`branch`、`lastPromptAt`、`parentAgent` 和 `createdAt`（旧主机上为 null）。使用 `indicator` 和本地化的 `indicatorLabel` 显示 Paseo 的状态。`status` 保持 daemon 原始状态。Agent 快照包含工作区和父 Agent 引用。项目快照提供 `displayName`、`rootPath`、`kind` 和 `iconRevision`。
+
+## 列出终端 {#list-terminals}
+
+终端示例支持选择主机、列出终端、聚焦终端标签页，以及通过句柄关闭终端。`useTerminals({ hosts: [hostId] })` 要求主机声明 `terminalCollection` 能力。查询不支持该能力的主机时，终端读取会抛出要求更新主机的错误；其他实体钩子继续工作。将主机选择器放在错误边界之外，方便用户切换主机。省略 `hosts` 时，所有已连接主机都必须支持该能力。
+
+终端快照包含 `workspace`、`title`、`isScript` 和 `createdAt`。在时间戳跟踪引入前启动的 worker 所保留的终端，其 `createdAt` 为 null。脚本归属来自工作区脚本运行时条目。主机观察跟踪终端创建、关闭、标题变化和重新连接，并在最后一个终端读取订阅者离开时释放。
+
+## 通过引用执行操作 {#act-on-a-ref}
+
+`usePaseo()` 将基于引用的操作发送到引用所属的主机：
+
+```tsx
+const paseo = usePaseo();
+await paseo.workspaces.ref(workspaceRef).setPinned(true);
+await paseo.workspaces.ref(workspaceRef).setLabel("Later", { assigned: true });
+await paseo.workspaces.ref(workspaceRef).setLabel("Inbox", { assigned: false });
+paseo.projects.ref(projectRef).open();
+await paseo.projects.ref(projectRef).createWorkspace();
+paseo.terminals.ref(terminalRef).focus();
+await paseo.terminals.ref(terminalRef).kill();
+```
+
+工作区和 Agent 句柄保留现有方法。分配新标签会创建该标签；分配已有标签会保留其颜色。标签文件夹示例先添加目标标签，再移除源标签，因此分配失败时仍保留原文件夹。插件负责移动手势和错误显示。
+
+## 在设备上保存布局选择 {#keep-layout-choices-on-the-device}
+
+定义 `scope: "device"` 的[设置文档](reference.md#settings-screens)，保存折叠文件夹或手动排序。`useSettings` 通过与主机设置相同的修订版本 API 读取和写入。设备文档属于插件安装和设置 ID，在应用重启后保留，并由该安装的客户端界面共享。它们不会同步到其他设备。需要由客户端通过 daemon 共享的数据使用 `scope: "host"`。
+
+## 匹配应用的信息密度 {#match-the-apps-density}
+
+使用 React Native 原语绘制界面。SDK 不导出侧边栏视图的行、分区、列表、徽标或拖拽辅助组件。现有页眉和页脚组件包属于独立界面。
+
+紧凑行的最小高度为 28，水平内边距为 12；主标签字号为 12、行高为 16，次标签字号为 11。使用以下主题令牌：
+
+| 行元素           | 主题令牌                 |
+| ---------------- | ------------------------ |
+| 主标签           | `colors.foreground`      |
+| 次标签、分区标题 | `colors.foregroundMuted` |
+| 选中行背景       | `colors.surface2`        |
+| 分隔线           | `colors.border`          |
+| 操作或焦点强调色 | `colors.accent`          |
+| 成功指示         | `colors.statusSuccess`   |
+| 需要输入指示     | `colors.statusWarning`   |
+| 失败指示         | `colors.statusDanger`    |
+
+为可点击行提供无障碍标签，并在触摸布局中显示操作控件。示例仅使用插件自己的组件和传给视图的主题令牌。
diff --git a/public-docs/sdk/agents.md b/public-docs/sdk/agents.md
index 87d3e993cf..4d9a9a5b68 100644
--- a/public-docs/sdk/agents.md
+++ b/public-docs/sdk/agents.md
@@ -130,6 +130,29 @@ use `client.agents.list({ filter: { includeBackground: true } })` to include the
 Exact-ID handles work normally. See [workspace creation](./workspaces.md#create-a-fresh-workspace)
 for defaults and caller inheritance.
 
+## Run a helper as a background agent
+
+Pass `background: true` to run a helper in a workspace the user may have open. A background agent
+opens no tab, stays out of its parent's subagent track and the sidebar status, and raises no
+notifications. Default lists leave it out.
+
+```ts
+const helper = await client.workspaces.ref(workspaceId).agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  prompt: "Summarize the last turn in one line.",
+  background: true,
+});
+const result = await helper.waitForFinish();
+console.log(result.lastMessage);
+await helper.archive();
+```
+
+An agent created under a background `parent` is background unless you pass `background: false`.
+A parent on another host passes this on only as a handle; with a bare address, pass `background`.
+Placing a background agent in an existing workspace or under a parent requires
+`features.backgroundAgents`; on an older host the SDK throws "Update the host to use background
+agents." before sending.
+
 ## Request structured output
 
 ```ts
diff --git a/public-docs/sdk/agents.zh-CN.md b/public-docs/sdk/agents.zh-CN.md
index dd2997f61b..8731ed03e2 100644
--- a/public-docs/sdk/agents.zh-CN.md
+++ b/public-docs/sdk/agents.zh-CN.md
@@ -124,6 +124,23 @@ const workspace = await client.workspaces.create({
 
 后台 Agent 会保留历史记录，并在 daemon 重启后继续存在。默认的发现结果会隐藏它们；使用 `client.agents.list({ filter: { includeBackground: true } })` 可以包含它们。精确 ID 的句柄可以正常使用。默认值和调用方继承规则见[创建工作区](./workspaces.md#create-a-fresh-workspace)。
 
+## 以后台 Agent 运行辅助任务 {#run-a-helper-as-a-background-agent}
+
+传入 `background: true`，可以在用户可能正打开的工作区中运行辅助 Agent。后台 Agent 不会打开标签页，不会出现在父 Agent 的子 Agent 列表和侧边栏状态中，也不会触发通知。默认列表不包含它。
+
+```ts
+const helper = await client.workspaces.ref(workspaceId).agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  prompt: "Summarize the last turn in one line.",
+  background: true,
+});
+const result = await helper.waitForFinish();
+console.log(result.lastMessage);
+await helper.archive();
+```
+
+在后台 `parent` 下创建的 Agent 默认也是后台 Agent，除非传入 `background: false`。位于其他主机的父 Agent 只有以句柄传入时才会传递该设置；只传地址时，请显式传入 `background`。把后台 Agent 放到已有工作区或某个父 Agent 下需要 `features.backgroundAgents`；在较旧的主机上，SDK 会在发送前抛出 "Update the host to use background agents."。
+
 ## 请求结构化输出 {#request-structured-output}
 
 ```ts
diff --git a/public-docs/sdk/events.md b/public-docs/sdk/events.md
index 477177d9e1..25e524d56d 100644
--- a/public-docs/sdk/events.md
+++ b/public-docs/sdk/events.md
@@ -42,6 +42,25 @@ await directory.subscription.release();
 
 `client.agents.subscribe()` and agent-handle `subscribe()` add local listeners to observations owned by that API instance. They do not request data. Use the returned subscription's callbacks when multiple filtered views need separate updates.
 
+## Follow an agent's background work
+
+Background work is what an agent left running after its tool call returned: a Claude shell started with `run_in_background`, a `Monitor` watch, or another task that is not a subagent. Subagents and workflows stay in the agent's subagents.
+
+```ts
+const agent = client.agents.ref(agentId);
+
+const unsubscribe = agent.backgroundWork.subscribe((items) => render(items));
+
+// When this view closes:
+unsubscribe();
+```
+
+`subscribe()` calls the listener with the current list once the subscription is established, again after each reconnect, then with the whole list on every change. Use `list()` for a one-shot read. Each item has `id`, `kind` (`"shell"`, `"monitor"`, or `"other"`; treat unknown values as `"other"`), `description` (or `null`), optional `command`, and `startedAt`, the time Paseo first observed it. Inventory is scoped to the current provider session and is not persisted. When its runtime is lost, its old items are discarded. An unavailable inventory is reported as an error rather than an empty list.
+
+Pass `subscribe(listener, { onError })` to receive setup or list errors. After a setup failure, create a new subscription; after a list failure, the list is read again on the next reconnect. Without `onError`, the error is logged.
+
+`list()` rejects and `subscribe()` throws when the host does not advertise `features.agentBackgroundWork`; ask the user to update the host. For an item with `canStop`, call `backgroundWork.stop(item)` to wait for provider confirmation. Stop requires `features.agentBackgroundWorkStop`.
+
 ## Follow timeline events
 
 ```ts
diff --git a/public-docs/sdk/events.zh-CN.md b/public-docs/sdk/events.zh-CN.md
index 3888d3d784..c506d351e9 100644
--- a/public-docs/sdk/events.zh-CN.md
+++ b/public-docs/sdk/events.zh-CN.md
@@ -40,6 +40,25 @@ await directory.subscription.release();
 
 `client.agents.subscribe()` 和 Agent 句柄上的 `subscribe()` 会为该 API 实例持有的观察添加本地监听器。它们不会请求数据。当多个带过滤条件的视图需要各自的更新时，请使用返回的订阅上的回调。
 
+## 跟踪 Agent 的后台工作 {#follow-an-agents-background-work}
+
+后台工作是 Agent 的工具调用返回后仍在运行的工作，例如使用 `run_in_background` 启动的 Claude shell 或 `Monitor` 监控。子 Agent 和 workflow 显示在子 Agent 中。
+
+```ts
+const agent = client.agents.ref(agentId);
+
+const unsubscribe = agent.backgroundWork.subscribe((items) => render(items));
+
+// When this view closes:
+unsubscribe();
+```
+
+订阅建立后，`subscribe()` 会向监听器投递当前列表；每次重连后和每次变化时，也会投递完整列表。用 `list()` 执行单次读取。每项包含 `id`、`kind`（`"shell"`、`"monitor"` 或 `"other"`，未知值按 `"other"` 处理）、可为 `null` 的 `description`、可选的 `command`，以及 Paseo 首次观察到该项的时间 `startedAt`。列表属于当前 Provider 会话，不会持久化。运行时丢失后，旧项会被清除。列表不可用时会报告错误，而不是返回空列表。
+
+传入 `subscribe(listener, { onError })` 可接收读取当前列表失败的错误；此时不会调用监听器，下次重连时会重新读取。未提供 `onError` 时会记录错误。
+
+主机未声明 `features.agentBackgroundWork` 时，`list()` 会 reject，`subscribe()` 会抛出错误；请让用户更新主机。对具有 `canStop` 的项目调用 `backgroundWork.stop(item)`，等待提供方确认。停止操作需要 `features.agentBackgroundWorkStop`。
+
 ## 跟踪时间线事件 {#follow-timeline-events}
 
 ```ts
diff --git a/public-docs/sdk/reference.md b/public-docs/sdk/reference.md
index 17716d685a..f090346213 100644
--- a/public-docs/sdk/reference.md
+++ b/public-docs/sdk/reference.md
@@ -61,8 +61,9 @@ Creation options include `config`, `cwd`, `parent`, `title`, `prompt`, `env`, `o
 
 `parent` accepts a host-local agent ID, an `AgentAddress` (`{ serverId, agentId }`), or an agent handle. A handle’s `address` keeps its host identity after disconnect. When creating through `hosts.client(serverId)`, pass the parent handle or complete address; the SDK carries parent metadata to the destination.
 
-`background` is workspace creation intent. It cannot accompany an existing `workspaceId`.
-See [background workspaces](./workspaces.md) for caller inheritance and inclusive discovery.
+`background` creates a [background agent](./agents.md#run-a-helper-as-a-background-agent). A
+workspace the call creates is background too. With a `parent` and no value, the parent's own
+`background` applies. See [background workspaces](./workspaces.md) for inclusive discovery.
 
 `config` accepts:
 
@@ -79,32 +80,35 @@ See [background workspaces](./workspaces.md) for caller inheritance and inclusiv
 
 ### Agent handle
 
-| Member                         | Result                            | Behavior                                                                                                |
-| ------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `id`                           | `string`                          | Stable daemon agent ID.                                                                                 |
-| `address`                      | `AgentAddress`                    | Complete `{ serverId, agentId }` identity; requires a connected host to establish it.                   |
-| `workspaceId`                  | `string \| null`                  | Current workspace placement.                                                                            |
-| `cwd`                          | `string \| null`                  | Current working directory.                                                                              |
-| `status`                       | Agent status or `null`            | Current lifecycle status.                                                                               |
-| `capabilities`                 | Capability flags or `null`        | What the provider session supports.                                                                     |
-| `availableModes`               | Agent modes or `null`             | Modes the session can switch to.                                                                        |
-| `pendingPermissions`           | Permission requests or `null`     | Requests waiting on an answer.                                                                          |
-| `activeTurn`                   | Active turn or `null`             | The turn in flight, with `turnId` and `startedAt`.                                                      |
-| `lastUsage`                    | Usage or `null`                   | Token counts, cost, and context-window use from the last turn.                                          |
-| `lastError`                    | `string \| null`                  | Last error the daemon recorded for the agent.                                                           |
-| `features`                     | Agent features or `null`          | Provider feature toggles and selects with their current values.                                         |
-| `runtimeInfo`                  | Runtime info or `null`            | Live provider, session ID, model, thinking option, and mode.                                            |
-| `archivedAt`                   | `string \| null`                  | Archive timestamp; `null` while the agent is active.                                                    |
-| `current()`                    | `PaseoAgent \| null`              | Current detailed value observed by this handle; never fetches.                                          |
-| `refresh(requestId?)`          | `PaseoAgentRefetchResult \| null` | Fetches the current agent and project placement.                                                        |
-| `send(text, options?)`         | `Promise<void>`                   | Resolves when the daemon accepts the prompt.                                                            |
-| `respondToPermission(options)` | `Promise<void>`                   | Answers a pending permission by `requestId` with an allow or deny `response`.                           |
-| `run(text, options?)`          | `PaseoAgentRunResult`             | Sends a prompt and waits for that turn. `timeoutMs` controls the wait; it defaults to 10 minutes.       |
-| `waitForFinish(timeoutMs?)`    | `PaseoAgentRunResult`             | Waits for the active turn, including an initial prompt. Default timeout: 10 minutes.                    |
-| `commands(options?)`           | `PaseoAgentCommandsResult`        | Asks the live session for its slash commands and skills, including built-in ones. Options: `requestId`. |
-| `subscribe(handler)`           | Unsubscribe function              | Filters agent-directory updates to this ID and refreshes the handle properties.                         |
-| `archive()`                    | `{ archivedAt }`                  | Soft-deletes the agent and closes its runtime.                                                          |
-| `detach()`                     | `Promise<void>`                   | Removes the parent relationship without stopping the agent.                                             |
+| Member                                         | Result                                    | Behavior                                                                                                                                                                                                                       |
+| ---------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                                           | `string`                                  | Stable daemon agent ID.                                                                                                                                                                                                        |
+| `address`                                      | `AgentAddress`                            | Complete `{ serverId, agentId }` identity; requires a connected host to establish it.                                                                                                                                          |
+| `workspaceId`                                  | `string \| null`                          | Current workspace placement.                                                                                                                                                                                                   |
+| `cwd`                                          | `string \| null`                          | Current working directory.                                                                                                                                                                                                     |
+| `status`                                       | Agent status or `null`                    | Current lifecycle status.                                                                                                                                                                                                      |
+| `capabilities`                                 | Capability flags or `null`                | What the provider session supports.                                                                                                                                                                                            |
+| `availableModes`                               | Agent modes or `null`                     | Modes the session can switch to.                                                                                                                                                                                               |
+| `pendingPermissions`                           | Permission requests or `null`             | Requests waiting on an answer.                                                                                                                                                                                                 |
+| `activeTurn`                                   | Active turn or `null`                     | The turn in flight, with `turnId` and `startedAt`.                                                                                                                                                                             |
+| `lastUsage`                                    | Usage or `null`                           | Token counts, cost, and context-window use from the last turn.                                                                                                                                                                 |
+| `lastError`                                    | `string \| null`                          | Last error the daemon recorded for the agent.                                                                                                                                                                                  |
+| `features`                                     | Agent features or `null`                  | Provider feature toggles and selects with their current values.                                                                                                                                                                |
+| `runtimeInfo`                                  | Runtime info or `null`                    | Live provider, session ID, model, thinking option, and mode.                                                                                                                                                                   |
+| `archivedAt`                                   | `string \| null`                          | Archive timestamp; `null` while the agent is active.                                                                                                                                                                           |
+| `current()`                                    | `PaseoAgent \| null`                      | Current detailed value observed by this handle; never fetches.                                                                                                                                                                 |
+| `refresh(requestId?)`                          | `PaseoAgentRefetchResult \| null`         | Fetches the current agent and project placement.                                                                                                                                                                               |
+| `send(text, options?)`                         | `Promise<void>`                           | Resolves when the daemon accepts the prompt.                                                                                                                                                                                   |
+| `respondToPermission(options)`                 | `Promise<void>`                           | Answers a pending permission by `requestId` with an allow or deny `response`.                                                                                                                                                  |
+| `run(text, options?)`                          | `PaseoAgentRunResult`                     | Sends a prompt and waits for that turn. `timeoutMs` controls the wait; it defaults to 10 minutes.                                                                                                                              |
+| `waitForFinish(timeoutMs?)`                    | `PaseoAgentRunResult`                     | Waits for the active turn, including an initial prompt. Default timeout: 10 minutes.                                                                                                                                           |
+| `commands(options?)`                           | `PaseoAgentCommandsResult`                | Asks the live session for its slash commands and skills, including built-in ones. Options: `requestId`.                                                                                                                        |
+| `subscribe(handler)`                           | Unsubscribe function                      | Filters agent-directory updates to this ID and refreshes the handle properties.                                                                                                                                                |
+| `archive()`                                    | `{ archivedAt }`                          | Soft-deletes the agent and closes its runtime.                                                                                                                                                                                 |
+| `detach()`                                     | `Promise<void>`                           | Removes the parent relationship without stopping the agent.                                                                                                                                                                    |
+| `backgroundWork.list(options?)`                | `Promise<PaseoAgentBackgroundWorkItem[]>` | Reads the agent's current background work once. Requires `features.agentBackgroundWork`. Options: `requestId`, `timeout`.                                                                                                      |
+| `backgroundWork.stop(item, options?)`          | `Promise<void>`                           | Stops a stoppable item and waits for provider confirmation. Pass the item returned by `list` or `subscribe`. Requires `features.agentBackgroundWorkStop`.                                                                      |
+| `backgroundWork.subscribe(listener, options?)` | `() => void`                              | Calls `listener` with the current list, again after each reconnect, then with the full list on every change. `onError` receives a failed list read. Requires `features.agentBackgroundWork`. Returns the unsubscribe function. |
 
 `workspaceId` through `archivedAt` mirror the last snapshot the handle observed. A handle from `ref()` reads `null` for all of them until `refresh()`, `run()`, `waitForFinish()`, a timeline refetch, or `subscribe()` delivers a snapshot. Optional values in an observed snapshot also read as `null`. Call `current()` when you need the whole snapshot or need to distinguish those states.
 
diff --git a/public-docs/sdk/reference.zh-CN.md b/public-docs/sdk/reference.zh-CN.md
index cc8a39360f..3ff36d9ff5 100644
--- a/public-docs/sdk/reference.zh-CN.md
+++ b/public-docs/sdk/reference.zh-CN.md
@@ -59,7 +59,7 @@ nav: API 参考
 
 `parent` 接受主机本地的 Agent ID、`AgentAddress`（`{ serverId, agentId }`）或 Agent 句柄。句柄的 `address` 在断开连接后仍保留其主机身份。通过 `hosts.client(serverId)` 创建时，请传入父 Agent 句柄或完整地址；SDK 会把父级元数据带到目标主机。
 
-`background` 表示创建工作区的意图。它不能与已有的 `workspaceId` 一起使用。调用方继承规则和包含后台的发现方式见[后台工作区](./workspaces.md)。
+`background` 会创建一个[后台 Agent](./agents.md#run-a-helper-as-a-background-agent)。本次调用创建的工作区也是后台工作区。带 `parent` 且省略该值时，沿用父 Agent 自己的 `background`。包含后台的发现方式见[后台工作区](./workspaces.md)。
 
 `config` 接受：
 
@@ -76,32 +76,35 @@ nav: API 参考
 
 ### Agent 句柄 {#agent-handle}
 
-| 成员                           | 结果                              | 行为                                                                    |
-| ------------------------------ | --------------------------------- | ----------------------------------------------------------------------- |
-| `id`                           | `string`                          | 稳定的 daemon Agent ID。                                                |
-| `address`                      | `AgentAddress`                    | 完整的 `{ serverId, agentId }` 身份；需要连接到主机才能确定。           |
-| `workspaceId`                  | `string \| null`                  | 当前所在的工作区。                                                      |
-| `cwd`                          | `string \| null`                  | 当前工作目录。                                                          |
-| `status`                       | Agent 状态或 `null`               | 当前的生命周期状态。                                                    |
-| `capabilities`                 | 能力标志或 `null`                 | Provider 会话支持的能力。                                               |
-| `availableModes`               | Agent 模式或 `null`               | 会话可以切换到的模式。                                                  |
-| `pendingPermissions`           | 权限请求或 `null`                 | 等待回应的请求。                                                        |
-| `activeTurn`                   | 当前轮次或 `null`                 | 正在进行的轮次，包含 `turnId` 和 `startedAt`。                          |
-| `lastUsage`                    | 用量或 `null`                     | 上一轮的 token 数、费用和上下文窗口用量。                               |
-| `lastError`                    | `string \| null`                  | daemon 为该 Agent 记录的最后一个错误。                                  |
-| `features`                     | Agent 功能或 `null`               | Provider 的功能开关和选择项及其当前值。                                 |
-| `runtimeInfo`                  | 运行时信息或 `null`               | 实时的 Provider、会话 ID、模型、思考选项和模式。                        |
-| `archivedAt`                   | `string \| null`                  | 归档时间戳；Agent 处于活动状态时为 `null`。                             |
-| `current()`                    | `PaseoAgent \| null`              | 此句柄观察到的当前详细值；从不发起请求。                                |
-| `refresh(requestId?)`          | `PaseoAgentRefetchResult \| null` | 获取当前的 Agent 及其所在项目。                                         |
-| `send(text, options?)`         | `Promise<void>`                   | 在 daemon 接受提示词后 resolve。                                        |
-| `respondToPermission(options)` | `Promise<void>`                   | 按 `requestId` 以允许或拒绝的 `response` 回应一个待处理的权限请求。     |
-| `run(text, options?)`          | `PaseoAgentRunResult`             | 发送提示词并等待该轮结束。`timeoutMs` 控制等待时间，默认 10 分钟。      |
-| `waitForFinish(timeoutMs?)`    | `PaseoAgentRunResult`             | 等待当前轮次结束，包括初始提示词。默认超时：10 分钟。                   |
-| `commands(options?)`           | `PaseoAgentCommandsResult`        | 向正在运行的会话查询它的斜杠命令和技能，包括内置的。选项：`requestId`。 |
-| `subscribe(handler)`           | 取消订阅函数                      | 把 Agent 目录更新过滤到此 ID，并刷新句柄的属性。                        |
-| `archive()`                    | `{ archivedAt }`                  | 软删除 Agent 并关闭它的运行时。                                         |
-| `detach()`                     | `Promise<void>`                   | 解除父子关系，但不停止 Agent。                                          |
+| 成员                                           | 结果                                      | 行为                                                                                                                                          |
+| ---------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                                           | `string`                                  | 稳定的 daemon Agent ID。                                                                                                                      |
+| `address`                                      | `AgentAddress`                            | 完整的 `{ serverId, agentId }` 身份；需要连接到主机才能确定。                                                                                 |
+| `workspaceId`                                  | `string \| null`                          | 当前所在的工作区。                                                                                                                            |
+| `cwd`                                          | `string \| null`                          | 当前工作目录。                                                                                                                                |
+| `status`                                       | Agent 状态或 `null`                       | 当前的生命周期状态。                                                                                                                          |
+| `capabilities`                                 | 能力标志或 `null`                         | Provider 会话支持的能力。                                                                                                                     |
+| `availableModes`                               | Agent 模式或 `null`                       | 会话可以切换到的模式。                                                                                                                        |
+| `pendingPermissions`                           | 权限请求或 `null`                         | 等待回应的请求。                                                                                                                              |
+| `activeTurn`                                   | 当前轮次或 `null`                         | 正在进行的轮次，包含 `turnId` 和 `startedAt`。                                                                                                |
+| `lastUsage`                                    | 用量或 `null`                             | 上一轮的 token 数、费用和上下文窗口用量。                                                                                                     |
+| `lastError`                                    | `string \| null`                          | daemon 为该 Agent 记录的最后一个错误。                                                                                                        |
+| `features`                                     | Agent 功能或 `null`                       | Provider 的功能开关和选择项及其当前值。                                                                                                       |
+| `runtimeInfo`                                  | 运行时信息或 `null`                       | 实时的 Provider、会话 ID、模型、思考选项和模式。                                                                                              |
+| `archivedAt`                                   | `string \| null`                          | 归档时间戳；Agent 处于活动状态时为 `null`。                                                                                                   |
+| `current()`                                    | `PaseoAgent \| null`                      | 此句柄观察到的当前详细值；从不发起请求。                                                                                                      |
+| `refresh(requestId?)`                          | `PaseoAgentRefetchResult \| null`         | 获取当前的 Agent 及其所在项目。                                                                                                               |
+| `send(text, options?)`                         | `Promise<void>`                           | 在 daemon 接受提示词后 resolve。                                                                                                              |
+| `respondToPermission(options)`                 | `Promise<void>`                           | 按 `requestId` 以允许或拒绝的 `response` 回应一个待处理的权限请求。                                                                           |
+| `run(text, options?)`                          | `PaseoAgentRunResult`                     | 发送提示词并等待该轮结束。`timeoutMs` 控制等待时间，默认 10 分钟。                                                                            |
+| `waitForFinish(timeoutMs?)`                    | `PaseoAgentRunResult`                     | 等待当前轮次结束，包括初始提示词。默认超时：10 分钟。                                                                                         |
+| `commands(options?)`                           | `PaseoAgentCommandsResult`                | 向正在运行的会话查询它的斜杠命令和技能，包括内置的。选项：`requestId`。                                                                       |
+| `subscribe(handler)`                           | 取消订阅函数                              | 把 Agent 目录更新过滤到此 ID，并刷新句柄的属性。                                                                                              |
+| `archive()`                                    | `{ archivedAt }`                          | 软删除 Agent 并关闭它的运行时。                                                                                                               |
+| `detach()`                                     | `Promise<void>`                           | 解除父子关系，但不停止 Agent。                                                                                                                |
+| `backgroundWork.list(options?)`                | `Promise<PaseoAgentBackgroundWorkItem[]>` | 单次读取 Agent 当前的后台工作。需要 `features.agentBackgroundWork`；选项为 `requestId` 和 `timeout`。                                         |
+| `backgroundWork.stop(item, options?)`          | `Promise<void>`                           | 停止可停止的项目并等待提供方确认。传入 `list` 或 `subscribe` 返回的项目。需要 `features.agentBackgroundWorkStop`。                            |
+| `backgroundWork.subscribe(listener, options?)` | `() => void`                              | 向监听器投递当前列表，并在每次重连和变化时投递完整列表。`onError` 接收读取失败的错误；需要 `features.agentBackgroundWork`。返回取消订阅函数。 |
 
 从 `workspaceId` 到 `archivedAt` 的属性反映句柄最近观察到的快照。由 `ref()` 得到的句柄在 `refresh()`、`run()`、`waitForFinish()`、时间线重新获取或 `subscribe()` 投递快照之前，这些属性都读作 `null`。已观察到的快照中的可选值也读作 `null`。当你需要整个快照，或需要区分这些状态时，请调用 `current()`。
 
diff --git a/public-docs/sdk/workspaces.md b/public-docs/sdk/workspaces.md
index 2bf1dd7ee3..e62d30ffcd 100644
--- a/public-docs/sdk/workspaces.md
+++ b/public-docs/sdk/workspaces.md
@@ -61,10 +61,10 @@ remain durable, with ordinary history, lifecycle hooks, archive, and exact-ID ac
 sidebar offers **Show background** without dropping replicated state.
 
 `background` is creation-only. Omission defaults to false; when `callerAgentId` identifies an agent
-creating a new workspace, omission inherits its workspace's value. Explicit false or true overrides
-inheritance. Agent creation with `workspaceId` rejects explicit background creation intent; configure
-visibility when creating the workspace. SDK/RPC implicit agent creation also accepts `background`
-as workspace creation intent, never as an agent property.
+creating a new workspace, omission inherits the caller's visibility: true when the caller agent or
+its workspace is background. Explicit false or true overrides inheritance. Agent creation that
+creates its workspace applies `background` to both the workspace and the agent. To hide one agent
+in an existing workspace, see [background agents](./agents.md#run-a-helper-as-a-background-agent).
 
 Creation and inclusive discovery require `features.backgroundWorkspaces`; the client rejects an
 unsupported host with an update-host message.
@@ -135,8 +135,8 @@ do {
 
 Background workspaces are left out unless `filter.includeBackground` is true. Use
 `client.workspaces.list({ filter: { includeBackground: true } })` or
-`client.agents.list({ filter: { includeBackground: true } })`. Workspace descriptors carry
-`background`; agents derive visibility from their workspace and have no separate setting.
+`client.agents.list({ filter: { includeBackground: true } })`. Workspace and agent snapshots carry
+`background`. An agent is hidden when it or its workspace is background.
 
 ## Refresh and archive a handle
 
diff --git a/public-docs/sdk/workspaces.zh-CN.md b/public-docs/sdk/workspaces.zh-CN.md
index 0fb887b4e9..c61ff30d80 100644
--- a/public-docs/sdk/workspaces.zh-CN.md
+++ b/public-docs/sdk/workspaces.zh-CN.md
@@ -54,7 +54,7 @@ const workspace = await client.workspaces.create({
 
 传入 `background: true` 可以让工作区不出现在默认的发现结果中。它的 Agent 和终端仍然是持久的，有正常的历史记录、生命周期钩子、归档和精确 ID 访问。应用侧边栏提供 **显示后台工作区**，不会丢弃已同步的状态。
 
-`background` 只能在创建时设置。省略时默认为 false；当 `callerAgentId` 指明是某个 Agent 在创建新工作区时，省略则继承该 Agent 所在工作区的值。显式的 false 或 true 会覆盖继承。带 `workspaceId` 创建 Agent 时会拒绝显式的后台创建意图；请在创建工作区时配置可见性。SDK/RPC 的隐式 Agent 创建也接受 `background`，但它表示工作区的创建意图，而不是 Agent 的属性。
+`background` 只能在创建时设置。省略时默认为 false；当 `callerAgentId` 指明是某个 Agent 在创建新工作区时，省略则继承调用方的可见性：调用方 Agent 或其工作区为后台时即为 true。显式的 false 或 true 会覆盖继承。同时创建工作区的 Agent 创建请求会把 `background` 同时应用到工作区和 Agent。要在已有工作区中隐藏单个 Agent，见[后台 Agent](./agents.md#run-a-helper-as-a-background-agent)。
 
 创建和包含后台工作区的发现都需要 `features.backgroundWorkspaces`；对于不支持的主机，客户端会拒绝并提示更新主机。
 
@@ -122,7 +122,7 @@ do {
 } while (cursor);
 ```
 
-除非 `filter.includeBackground` 为 true，否则后台工作区不会被列出。使用 `client.workspaces.list({ filter: { includeBackground: true } })` 或 `client.agents.list({ filter: { includeBackground: true } })`。工作区描述符带有 `background`；Agent 的可见性来自它所在的工作区，没有单独的设置。
+除非 `filter.includeBackground` 为 true，否则后台工作区不会被列出。使用 `client.workspaces.list({ filter: { includeBackground: true } })` 或 `client.agents.list({ filter: { includeBackground: true } })`。工作区和 Agent 快照都带有 `background`。Agent 本身或其工作区为后台时，Agent 会被隐藏。
 
 ## 刷新和归档句柄 {#refresh-and-archive-a-handle}
 
diff --git a/public-docs/supported-providers.md b/public-docs/supported-providers.md
index 1aa981ba29..1fe249a1e0 100644
--- a/public-docs/supported-providers.md
+++ b/public-docs/supported-providers.md
@@ -78,6 +78,7 @@ Pick any of these from the in-app provider catalog. Each entry is a one-click in
 - [Dirac](https://dirac.run), open-source agent with hash-anchored parallel edits.
 - [Factory Droid](https://factory.ai/product/cli), Factory AI's coding agent.
 - [fast-agent](https://fast-agent.ai/acp/), multi-provider coding agent.
+- [fx](#fx), Vercel Labs' native coding agent.
 - [Gajae Code](https://gajae-code.com), subscription-based coding agent with plan-before-mutation workflows.
 - [Gemini CLI](https://geminicli.com), Google's official Gemini CLI.
 - [GitHub Copilot](https://github.com/features/copilot/cli/), GitHub's AI pair programmer via ACP.
@@ -102,6 +103,20 @@ Pick any of these from the in-app provider catalog. Each entry is a one-click in
 
 The in-app catalog is the canonical, version-pinned source. Anything not listed here can still be added manually, see [Custom providers](/docs/custom-providers).
 
+### fx
+
+[Install fx](https://fx.sh/docs/getting-started/installation) on your daemon host and
+[connect a provider](https://fx.sh/docs/getting-started/authentication), for example with
+`fx login`. In **Settings → Hosts → your host → Providers**, find **fx** in the catalog and
+choose **Add**. Paseo launches `fx acp` and uses your fx credentials and settings. Until fx has
+credentials, the provider reports the sign-in message from fx.
+
+The model list comes from your active fx provider, so run `fx provider` to change the list a new
+agent starts from. Changing an agent's permission mode also changes fx's saved permission mode.
+See [fx's ACP guide](https://fx.sh/docs/using-fx/acp) for what fx supports. Use a
+[command override](/docs/custom-providers) if `fx` is outside your daemon's PATH; keep `acp` in
+the arguments.
+
 ### Hoplite
 
 Install the [Hoplite CLI](https://hoplite.sh/docs/cli) on your daemon host and run
diff --git a/public-docs/supported-providers.zh-CN.md b/public-docs/supported-providers.zh-CN.md
index d57505f0a6..afb7538431 100644
--- a/public-docs/supported-providers.zh-CN.md
+++ b/public-docs/supported-providers.zh-CN.md
@@ -68,6 +68,7 @@ Paseo MCP 工具和引导功能不可用。你自己为 `agy` 配置的 MCP 服
 - [Dirac](https://dirac.run)：开源 Agent，支持基于哈希锚点的并行编辑。
 - [Factory Droid](https://factory.ai/product/cli)：Factory AI 的编程 Agent。
 - [fast-agent](https://fast-agent.ai/acp/)：支持多家 Provider 的编程 Agent。
+- [fx](#fx)：Vercel Labs 的原生编程 Agent。
 - [Gajae Code](https://gajae-code.com)：订阅制编程 Agent，采用先规划再修改的工作流。
 - [Gemini CLI](https://geminicli.com)：Google 官方的 Gemini CLI。
 - [GitHub Copilot](https://github.com/features/copilot/cli/)：通过 ACP 接入的 GitHub AI 结对编程助手。
@@ -92,6 +93,12 @@ Paseo MCP 工具和引导功能不可用。你自己为 `agy` 配置的 MCP 服
 
 应用内目录是权威的、固定版本的来源。这里未列出的 Agent 仍然可以手动添加，参见[自定义 Provider](/docs/custom-providers)。
 
+### fx {#fx}
+
+在 daemon 主机上[安装 fx](https://fx.sh/docs/getting-started/installation)，并[连接一个模型提供方](https://fx.sh/docs/getting-started/authentication)，例如运行 `fx login`。在 **设置 → Hosts → 你的主机 → Providers** 中，在目录里找到 **fx** 并选择 **Add**。Paseo 会启动 `fx acp`，并使用你的 fx 凭据和设置。在 fx 拿到凭据之前，该 provider 会显示 fx 给出的登录提示。
+
+模型列表来自当前的 fx 提供方，运行 `fx provider` 可以更改新 Agent 使用的列表。更改 Agent 的权限模式也会更改 fx 保存的权限模式。fx 支持的功能见 [fx 的 ACP 指南](https://fx.sh/docs/using-fx/acp)。如果 `fx` 不在 daemon 的 PATH 中，请使用[命令覆盖](/docs/custom-providers)，并在参数中保留 `acp`。
+
 ### Hoplite {#hoplite}
 
 在 daemon 主机上安装 [Hoplite CLI](https://hoplite.sh/docs/cli) 并运行 `hoplite login`。在 **设置 → Hosts → 你的主机 → Providers** 中，在目录里找到 **Hoplite** 并选择 **添加**。Paseo 会通过通用 ACP 适配器启动 `hoplite acp`。
diff --git a/public-docs/worktrees.md b/public-docs/worktrees/index.md
similarity index 91%
rename from public-docs/worktrees.md
rename to public-docs/worktrees/index.md
index baaea2e177..faabb2d81f 100644
--- a/public-docs/worktrees.md
+++ b/public-docs/worktrees/index.md
@@ -84,16 +84,7 @@ Add `--forge <name>` when Paseo cannot infer the forge from the source checkout.
 
 ## Copy local files with .worktreeinclude
 
-Create `.worktreeinclude` at the root of your source checkout to copy selected gitignored files into new worktrees:
-
-```gitignore
-.env
-config/*.local.json
-```
-
-Patterns use gitignore syntax. A file must match `.worktreeinclude` and be gitignored to be copied. Tracked files are never copied, and existing destination files are never overwritten. Without `.worktreeinclude`, no local files are copied. Symlinked directories and nested repositories inside an included path cause the copy to fail and abort worktree creation.
-
-The built-in `worktree-include` plugin copies from the checkout you create the worktree from, including when that checkout is another worktree. Copying finishes before setup, terminals, and the first agent. A copy failure aborts creation and removes the new worktree. Copies use copy-on-write clones on APFS and btrfs when supported, with a regular copy elsewhere.
+Use [`.worktreeinclude`](/docs/worktrees/worktreeinclude) to copy selected gitignored files, such as `.env`, from your source checkout before setup runs.
 
 ## paseo.json
 
diff --git a/public-docs/worktrees.zh-CN.md b/public-docs/worktrees/index.zh-CN.md
similarity index 92%
rename from public-docs/worktrees.zh-CN.md
rename to public-docs/worktrees/index.zh-CN.md
index e84d0a8a25..cce65fc090 100644
--- a/public-docs/worktrees.zh-CN.md
+++ b/public-docs/worktrees/index.zh-CN.md
@@ -82,16 +82,7 @@ paseo workspace create \
 
 ## 使用 .worktreeinclude 复制本地文件 {#copy-local-files-with-worktreeinclude}
 
-在源检出的根目录创建 `.worktreeinclude`，将选定的 Git 忽略文件复制到新的 worktree：
-
-```gitignore
-.env
-config/*.local.json
-```
-
-模式使用 gitignore 语法。只有同时匹配 `.worktreeinclude` 且被 Git 忽略的文件才会复制。已跟踪的文件不会被复制，目标中已存在的文件不会被覆盖。没有 `.worktreeinclude` 时，不会复制任何本地文件。包含路径中的符号链接目录和嵌套仓库会导致复制失败，并中止 worktree 创建。
-
-内置的 `worktree-include` 插件从你创建 worktree 时所选的检出复制文件，即使源检出本身也是 worktree。复制会在 setup、终端和第一个 Agent 运行之前完成。复制失败会中止创建并删除新的 worktree。支持时会在 APFS 和 btrfs 上使用写时复制克隆，否则执行普通复制。
+使用 [`.worktreeinclude`](/docs/worktrees/worktreeinclude)，在 setup 运行前将 `.env` 等选定的 Git 忽略文件从源检出复制到新 worktree。
 
 ## paseo.json {#paseojson}
 
diff --git a/public-docs/worktrees/worktreeinclude.md b/public-docs/worktrees/worktreeinclude.md
new file mode 100644
index 0000000000..50c5f0370a
--- /dev/null
+++ b/public-docs/worktrees/worktreeinclude.md
@@ -0,0 +1,61 @@
+---
+title: .worktreeinclude
+description: Copy gitignored local files into new Paseo worktrees.
+nav: .worktreeinclude
+order: 12
+category: Workspaces
+---
+
+# .worktreeinclude
+
+Add `.worktreeinclude` at the root of your source checkout to copy local configuration into new [Git worktrees](/docs/worktrees). Paseo copies matching gitignored files before setup, terminals, and the first Agent start.
+
+## Copy your local configuration
+
+For a project whose `.gitignore` includes `.env` and `config/*.local.json`, create this `.worktreeinclude`:
+
+```gitignore
+.env
+config/*.local.json
+```
+
+When you create a worktree through Paseo, an existing `.env` and matching files such as `config/dev.local.json` are copied to the same relative paths in the new worktree. Their contents stay out of Git.
+
+Commit `.worktreeinclude` to share the patterns with your team. Each teammate supplies their own ignored files in the checkout they create worktrees from.
+
+## Pattern syntax
+
+Use gitignore syntax, with one pattern per line. Comments start with `#`. Prefix a pattern with `!` to exclude a match:
+
+```gitignore
+# Local environment and configuration
+.env
+config/*.local.json
+!config/production.local.json
+```
+
+A pattern only selects files that Git already ignores. Adding a path here does not ignore it, so also configure `.gitignore` when needed. Tracked files and untracked files that Git does not ignore are excluded.
+
+## When files are copied
+
+The built-in `worktree-include` plugin reads the file from the checkout you create the worktree from. That source can itself be another worktree. Keep the plugin enabled for copying to run.
+
+- Without `.worktreeinclude`, the plugin copies nothing.
+- Matching files must exist in the source checkout.
+- Existing destination files are skipped, preserving their contents.
+- Copies happen during creation, with no ongoing synchronization between checkouts.
+- A copy error aborts creation and removes the new worktree. Avoid including symlinked directories or nested repositories, which cannot be copied as files.
+
+## Run commands during setup
+
+Use `.worktreeinclude` for files that already exist locally. Use a [setup hook](/docs/worktrees#setup-and-teardown) to install dependencies, generate files, or fetch secrets:
+
+```json
+{
+  "worktree": {
+    "setup": "npm ci"
+  }
+}
+```
+
+Put this configuration in `paseo.json` on the base branch used for the new worktree. Copied files are available when setup runs.
diff --git a/public-docs/worktrees/worktreeinclude.zh-CN.md b/public-docs/worktrees/worktreeinclude.zh-CN.md
new file mode 100644
index 0000000000..e80e386a01
--- /dev/null
+++ b/public-docs/worktrees/worktreeinclude.zh-CN.md
@@ -0,0 +1,61 @@
+---
+title: .worktreeinclude
+description: 将 Git 忽略的本地文件复制到新的 Paseo worktree。
+nav: .worktreeinclude
+order: 12
+category: Workspaces
+---
+
+# .worktreeinclude
+
+在源检出的根目录添加 `.worktreeinclude`，将本地配置复制到新的 [Git worktree](/docs/worktrees)。Paseo 会在 setup、终端和首个 Agent 启动之前复制匹配的 Git 忽略文件。
+
+## 复制本地配置 {#copy-your-local-configuration}
+
+如果项目的 `.gitignore` 包含 `.env` 和 `config/*.local.json`，创建以下 `.worktreeinclude`：
+
+```gitignore
+.env
+config/*.local.json
+```
+
+通过 Paseo 创建 worktree 时，已有的 `.env` 和 `config/dev.local.json` 等匹配文件会被复制到新 worktree 中的相同相对路径。文件内容仍不会纳入 Git。
+
+提交 `.worktreeinclude`，与团队共享这些模式。每位团队成员在用于创建 worktree 的检出中提供自己的忽略文件。
+
+## 模式语法 {#pattern-syntax}
+
+使用 gitignore 语法，每行一个模式。注释以 `#` 开头。模式前加 `!` 可排除匹配项：
+
+```gitignore
+# Local environment and configuration
+.env
+config/*.local.json
+!config/production.local.json
+```
+
+模式只会选择 Git 已忽略的文件。在此添加路径不会使 Git 忽略该文件，需要时还应配置 `.gitignore`。已跟踪的文件和未被 Git 忽略的未跟踪文件都不会被复制。
+
+## 文件复制时机 {#when-files-are-copied}
+
+内置的 `worktree-include` 插件从用于创建 worktree 的检出读取该文件。源检出也可以是另一个 worktree。保持该插件启用才能执行复制。
+
+- 没有 `.worktreeinclude` 时，插件不会复制任何文件。
+- 匹配的文件必须存在于源检出中。
+- 目标中已存在的文件会被跳过，保留原有内容。
+- 复制发生在创建期间，之后不会在检出之间持续同步。
+- 复制错误会中止创建并删除新 worktree。避免包含符号链接目录或嵌套仓库，因为它们无法作为文件复制。
+
+## 在 setup 期间运行命令 {#run-commands-during-setup}
+
+使用 `.worktreeinclude` 复制本地已有文件。使用 [setup 钩子](/docs/worktrees#setup-and-teardown) 安装依赖、生成文件或获取密钥：
+
+```json
+{
+  "worktree": {
+    "setup": "npm ci"
+  }
+}
+```
+
+将此配置放入新 worktree 所用基准分支的 `paseo.json` 中。setup 运行时，复制的文件已可使用。
diff --git a/scripts/changelog-utils.mjs b/scripts/changelog-utils.mjs
index a3ae0017a7..2c554f37f6 100644
--- a/scripts/changelog-utils.mjs
+++ b/scripts/changelog-utils.mjs
@@ -1,18 +1,24 @@
 // One definition of how CHANGELOG.md is structured. Consumed by the GitHub release
 // notes sync and by the F-Droid changelog sync, which need the same section bodies
 // rendered two different ways.
+//
+// The app's What's new sheet and the website parse the same file with their own
+// code. `test-support/changelog-structure.json` holds the cases all three must
+// split the same way; a change to the structure rules starts there.
 const headingPattern = /^##\s+\[?([^\]\s]+)\]?\s*-\s*([0-9]{4}-[0-9]{2}-[0-9]{2})\s*$/;
-const sectionHeadingPattern = /^###\s+(.+?)\s*$/;
+const sectionHeadingPattern = /^ {0,3}###(?:[ \t]+(.*?))?[ \t]*$/;
+const fencePattern = /^\s*(`{3,}|~{3,})/;
 const bulletPattern = /^\s*[-*]\s+(.+?)\s*$/;
 const blockquotePattern = /^\s*>\s?(.*)$/;
 
 // Returns entries newest-first, matching the order they appear in the file.
 export function parseChangelogEntries(changelogText) {
   const lines = changelogText.split(/\r?\n/);
+  const fenced = markFencedLines(lines);
   const headings = [];
 
   for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(headingPattern);
+    const match = fenced[index] ? null : lines[index].match(headingPattern);
     if (!match) {
       continue;
     }
@@ -47,6 +53,47 @@ export function parseChangelogEntries(changelogText) {
   });
 }
 
+// Splits an entry body at its first `### ` section. What comes before it is the
+// release's highlights; the sections after it are the full record. Either part is
+// empty when the entry has none.
+export function splitChangelogHighlights(bodyLines) {
+  const fenced = markFencedLines(bodyLines);
+  const firstSection = bodyLines.findIndex(
+    (line, index) => !fenced[index] && sectionHeadingPattern.test(line),
+  );
+  const split = firstSection === -1 ? bodyLines.length : firstSection;
+  return {
+    highlightLines: trimBlankLines(bodyLines.slice(0, split)),
+    sectionLines: trimBlankLines(bodyLines.slice(split)),
+  };
+}
+
+// Flags the lines that belong to a fenced code block, edges included. A `##` or
+// `###` in there is an example, so it starts neither a release nor a section.
+function markFencedLines(lines) {
+  let fence = null;
+  return lines.map((line) => {
+    const edge = line.match(fencePattern)?.[1];
+    if (!edge) {
+      return fence !== null;
+    }
+    if (fence === null) {
+      fence = edge;
+    } else if (edge[0] === fence[0] && edge.length >= fence.length) {
+      fence = null;
+    }
+    return true;
+  });
+}
+
+function trimBlankLines(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") start += 1;
+  while (end > start && lines[end - 1].trim() === "") end -= 1;
+  return lines.slice(start, end);
+}
+
 // Turns `[label](url)` into `label` and drops the trailing PR/attribution
 // parenthetical, which is pure noise in a store changelog with a 500 char budget.
 export function stripChangelogMarkup(text) {
@@ -134,7 +181,7 @@ export function parseChangelogBody(bodyLines) {
       if (current.bullets.length > 0) {
         sections.push(current);
       }
-      current = { bullets: [], title: stripChangelogMarkup(sectionMatch[1]) };
+      current = { bullets: [], title: stripChangelogMarkup(sectionMatch[1] ?? "") };
       continue;
     }
 
diff --git a/scripts/changelog-utils.test.mjs b/scripts/changelog-utils.test.mjs
new file mode 100644
index 0000000000..4ab8eec44b
--- /dev/null
+++ b/scripts/changelog-utils.test.mjs
@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { parseChangelogEntries, splitChangelogHighlights } from "./changelog-utils.mjs";
+
+// The cases the app, the website and the release scripts must all split the same way.
+const structureCases = JSON.parse(
+  readFileSync(new URL("./test-support/changelog-structure.json", import.meta.url), "utf8"),
+);
+
+for (const lineEnding of ["\n", "\r\n"]) {
+  test(`splits the shared cases with ${JSON.stringify(lineEnding)} line endings`, () => {
+    const entries = parseChangelogEntries(structureCases.document.join(lineEnding));
+
+    assert.deepEqual(
+      entries.map((entry) => {
+        const { highlightLines, sectionLines } = splitChangelogHighlights(entry.bodyLines);
+        return {
+          version: entry.version,
+          date: entry.date,
+          highlights: highlightLines,
+          sections: sectionLines,
+        };
+      }),
+      structureCases.releases.map((release) => ({
+        version: release.version,
+        date: release.date,
+        highlights: release.highlights,
+        sections: release.sections,
+      })),
+    );
+  });
+}
+
+test("finds an entry for every release heading line in the repository's CHANGELOG.md", () => {
+  for (const file of ["CHANGELOG.md", "CHANGELOG.zh-CN.md"]) {
+    const changelog = readFileSync(new URL(`../${file}`, import.meta.url), "utf8");
+    const headingLines = changelog.split("\n").filter((line) => line.startsWith("## "));
+    assert.equal(parseChangelogEntries(changelog).length, headingLines.length, file);
+  }
+});
diff --git a/scripts/ci-workflow.test.mjs b/scripts/ci-workflow.test.mjs
index 73a9003312..a96cbcba8b 100644
--- a/scripts/ci-workflow.test.mjs
+++ b/scripts/ci-workflow.test.mjs
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
-import { readFileSync, readdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync, readdirSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { relative as relativePath } from "node:path";
@@ -140,6 +140,43 @@ test("change gating allows superseded workflow runs to cancel", () => {
   }
 });
 
+test("published npm packages declare and ship the repository license", () => {
+  const rootManifest = JSON.parse(readFileSync(new URL("package.json", repoRoot), "utf8"));
+  const workspaceArgs = rootManifest.scripts["release:publish"].match(/--workspace=\S+/g);
+  assert.notEqual(workspaceArgs, null, "release:publish must select public packages");
+  const packed = JSON.parse(
+    execFileSync("npm", ["pack", "--dry-run", "--ignore-scripts", "--json", ...workspaceArgs], {
+      cwd: repoRoot,
+      encoding: "utf8",
+    }),
+  );
+  const manifests = new Map(
+    rootManifest.workspaces.map((workspace) => {
+      const directory = new URL(`${workspace}/`, repoRoot);
+      const manifest = JSON.parse(readFileSync(new URL("package.json", directory), "utf8"));
+      return [manifest.name, { directory, manifest }];
+    }),
+  );
+  const licenses = packed.map(({ name, files }) => ({
+    name,
+    license: manifests.get(name).manifest.license,
+    files: files.filter((file) => file.path === "LICENSE").map((file) => file.path),
+  }));
+  assert.deepEqual(
+    licenses,
+    workspaceArgs.map((workspace) => ({
+      name: workspace.slice("--workspace=".length),
+      license: "Apache-2.0",
+      files: ["LICENSE"],
+    })),
+  );
+  const repositoryLicense = readFileSync(new URL("LICENSE", repoRoot), "utf8");
+  for (const { name } of packed) {
+    const { directory } = manifests.get(name);
+    assert.equal(readFileSync(new URL("LICENSE", directory), "utf8"), repositoryLicense, name);
+  }
+});
+
 test("focused contracts stay inside existing required checks", () => {
   const jobs = jobBlocks(readFileSync(ciWorkflowPath, "utf8"));
   const changes = jobs.get("changes")?.join("\n") ?? "";
@@ -679,3 +716,48 @@ test("macOS jobs use latest runners while preserving release architectures", ()
   // GitHub has no standard macos-latest-intel alias; use the newest Intel image.
   assert.match(release, /runner: macos-26-intel\n\s+electron_arch: x64/);
 });
+
+test("Nix desktop packaging resolves the workspace-local builder", () => {
+  const source = readFileSync(new URL("nix/desktop-package.nix", repoRoot), "utf8");
+  const invocation = source.match(/^\s+([^\n]*electron-builder) \\\n/m)?.[1];
+  assert.ok(invocation, "Nix invokes the desktop packaging tool");
+  const directory = mkdtempSync(join(tmpdir(), "nix-builder-resolution-"));
+  try {
+    const desktop = join(directory, "packages/desktop");
+    mkdirSync(join(desktop, "node_modules/.bin"), { recursive: true });
+    mkdirSync(join(desktop, "node_modules/electron-builder"));
+    writeFileSync(
+      join(desktop, "node_modules/electron-builder/package.json"),
+      JSON.stringify({
+        name: "electron-builder",
+        version: "1.0.0",
+        bin: { "electron-builder": "../.bin/electron-builder" },
+      }),
+    );
+    writeFileSync(
+      join(directory, "package.json"),
+      JSON.stringify({ private: true, workspaces: ["packages/desktop"] }),
+    );
+    writeFileSync(
+      join(desktop, "package.json"),
+      JSON.stringify({
+        name: "desktop-fixture",
+        private: true,
+        devDependencies: { "electron-builder": "1.0.0" },
+      }),
+    );
+    writeFileSync(
+      join(desktop, "node_modules/.bin/electron-builder"),
+      '#!/bin/sh\nprintf "workspace-builder\\n"\n',
+      { mode: 0o755 },
+    );
+    const result = spawnSync("sh", ["-c", `${invocation} --version`], {
+      cwd: desktop,
+      encoding: "utf8",
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout.trim(), "workspace-builder");
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/postinstall-patches.mjs b/scripts/postinstall-patches.mjs
index 312bb90724..b67cd113aa 100644
--- a/scripts/postinstall-patches.mjs
+++ b/scripts/postinstall-patches.mjs
@@ -28,6 +28,9 @@ const patchedPackages = [
   // withUnistyles: also keep the uniProps filter until upstream consumes its control prop.
   // Android configuration: backport 3.5.3; remove the two NativePlatform hunks at >= 3.5.3.
   // https://github.com/jpudysz/react-native-unistyles/compare/v3.5.2...v3.5.3
+  // Layout constraints: backport of https://github.com/jpudysz/react-native-unistyles/pull/1357
+  // (commit from the root the commit hands us, so a concurrent window-size commit is kept).
+  // Remove the ShadowTreeManager hunk when the installed release includes that PR.
   {
     nodeModulesPath: "node_modules/react-native-unistyles",
     patchPrefix: "react-native-unistyles+",
@@ -40,10 +43,18 @@ const patchedPackages = [
     nodeModulesPath: "node_modules/react-native-reanimated",
     patchPrefix: "react-native-reanimated+",
   },
+  // The native chat timeline. The patch's header lists its hunks and the upstream issue.
+  {
+    nodeModulesPath: "node_modules/@legendapp/list",
+    patchPrefix: "@legendapp+list+",
+  },
   {
     nodeModulesPath: "node_modules/react-native-draggable-flatlist",
     patchPrefix: "react-native-draggable-flatlist+",
   },
+  // Web pointer capture: capture only pointers the handler still tracks after pointer-down, so a
+  // touch-only pan that fails the mouse leaves browser text selection alone. Keep until upstream
+  // stops capturing pointers a handler has rejected.
   {
     nodeModulesPath: "node_modules/react-native-gesture-handler",
     patchPrefix: "react-native-gesture-handler+",
@@ -51,7 +62,8 @@ const patchedPackages = [
   // Exports BottomSheetModalInternalProvider so a subtree can host its own sheets on the shared
   // modal stack (see packages/app/src/components/ui/isolated-bottom-sheet-modal/host-scope.tsx), and
   // keeps a dismissing modal's status through its final onChange(-1), so a modal with
-  // enableDismissOnClose=false that unmounts while presented still leaves the portal.
+  // enableDismissOnClose=false that unmounts while presented still leaves the portal, and removes
+  // the portal of a modal that unmounts before its opening animation starts.
   // Dimensions subscription cleanup: https://github.com/gorhom/react-native-bottom-sheet/issues/2734
   // and https://github.com/gorhom/react-native-bottom-sheet/pull/2751. Remove the useAnimatedLayout
   // hunks once an installed release includes the cleanup; retain the other local hunks.
@@ -59,6 +71,8 @@ const patchedPackages = [
     nodeModulesPath: "node_modules/@gorhom/bottom-sheet",
     patchPrefix: "@gorhom+bottom-sheet+",
   },
+  // Android resize: retain until upstream clears descendant geometry when the SVG canvas resizes.
+  // The native pixel regression is included in the patch; preserve the separate transform hunks.
   {
     nodeModulesPath: "packages/app/node_modules/react-native-svg",
     patchPrefix: "react-native-svg+",
diff --git a/scripts/sync-fdroid-changelogs.test.mjs b/scripts/sync-fdroid-changelogs.test.mjs
index 26eb4631b7..f583b7b7d6 100644
--- a/scripts/sync-fdroid-changelogs.test.mjs
+++ b/scripts/sync-fdroid-changelogs.test.mjs
@@ -275,6 +275,28 @@ test("preserves the standalone 0.1.96 Android notice", () => {
   assert.equal(contents.includes("_This release"), false);
 });
 
+test("leads with an entry's highlights and spends the budget on them first", () => {
+  const highlight = (name) =>
+    `- **${name}:** ${"A highlight a user would name first. ".repeat(4).trim()} ([#1](https://github.com/getpaseo/paseo/pull/1))`;
+  const contents = formatFdroidChangelog(
+    [
+      highlight("First"),
+      highlight("Second"),
+      highlight("Third"),
+      "",
+      "### Fixed",
+      "",
+      "- Fixed a crash",
+    ],
+    { limit: CHANGELOG_CHARACTER_LIMIT },
+  );
+
+  assert.match(contents, /^- First: A highlight a user would name first\./);
+  assert.match(contents, /\n- Second: /);
+  assert.equal(contents.includes("Fixed a crash"), false);
+  assert.ok(contents.length <= CHANGELOG_CHARACTER_LIMIT);
+});
+
 test("--check fails when the generated files are missing or stale", () => {
   const changelog = "## 0.2.3 - 2026-07-27\n\n### Fixed\n\n- Something broke.\n";
   withTempRepo(
diff --git a/scripts/sync-release-notes-from-changelog.mjs b/scripts/sync-release-notes-from-changelog.mjs
index 95c9baec4c..1931461a0c 100644
--- a/scripts/sync-release-notes-from-changelog.mjs
+++ b/scripts/sync-release-notes-from-changelog.mjs
@@ -2,7 +2,7 @@ import { execFileSync as nodeExecFileSync } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { parseChangelogEntries } from "./changelog-utils.mjs";
+import { parseChangelogEntries, splitChangelogHighlights } from "./changelog-utils.mjs";
 import { getGitHubRelease } from "./github-release.mjs";
 import {
   getReleaseInfoFromSourceTag,
@@ -69,17 +69,38 @@ function parseArgs(argv) {
 }
 
 function parseChangelog(changelogText) {
-  return parseChangelogEntries(changelogText).map((entry) => {
-    const notesParts = [`## ${entry.version} - ${entry.date}`];
-    if (entry.bodyLines.length > 0) {
-      notesParts.push("", ...entry.bodyLines);
-    }
-
-    return Object.assign({}, entry, {
+  return parseChangelogEntries(changelogText).map((entry) =>
+    Object.assign({}, entry, {
       tag: `v${entry.version}`,
-      notes: `${notesParts.join("\n").trim()}\n`,
-    });
-  });
+      notes: formatReleaseNotes(entry),
+    }),
+  );
+}
+
+// A release body leads with the entry's highlights and folds its sections, the
+// full record, into one collapsed block. GitHub renders `<details>` in release
+// bodies; CHANGELOG.md itself stays plain Markdown because the app and the
+// website render it without HTML. An entry without highlights keeps its sections
+// in view, since nothing stands in for them.
+function formatReleaseNotes(entry) {
+  const { highlightLines, sectionLines } = splitChangelogHighlights(entry.bodyLines);
+  const notesParts = [`## ${entry.version} - ${entry.date}`];
+  if (highlightLines.length > 0 && sectionLines.length > 0) {
+    notesParts.push(
+      "",
+      ...highlightLines,
+      "",
+      "<details>",
+      "<summary>All changes</summary>",
+      "",
+      ...sectionLines,
+      "",
+      "</details>",
+    );
+  } else if (entry.bodyLines.length > 0) {
+    notesParts.push("", ...entry.bodyLines);
+  }
+  return `${notesParts.join("\n").trim()}\n`;
 }
 
 function runGh(args, execFileSync = nodeExecFileSync) {
diff --git a/scripts/sync-release-notes-from-changelog.test.mjs b/scripts/sync-release-notes-from-changelog.test.mjs
index 5cb172df2e..c95289a56d 100644
--- a/scripts/sync-release-notes-from-changelog.test.mjs
+++ b/scripts/sync-release-notes-from-changelog.test.mjs
@@ -193,17 +193,10 @@ test("creates missing beta releases as drafts", () => {
   });
 });
 
-test("converts contributor profile links to mentions in synced release notes", () => {
-  const changelogText = [
-    "## 0.1.60-beta.1 - 2026-04-20",
-    "",
-    "- Beta notes. ([#526](https://github.com/getpaseo/paseo/pull/526) by [@therainisme](https://github.com/therainisme))",
-    "",
-  ].join("\n");
-
+// Syncs the v0.1.60-beta.1 entry of `changelogText` and returns the body GitHub would receive.
+function syncedReleaseBody(changelogText) {
+  let syncedNotes = "";
   withTempChangelog(() => {
-    let syncedNotes = "";
-
     const execFileSync = (command, args) => {
       if (args[0] === "api" && args[1] === "repos/getpaseo/paseo/releases/tags/v0.1.60-beta.1") {
         return JSON.stringify({ id: 311163621, draft: false });
@@ -222,8 +215,76 @@ test("converts contributor profile links to mentions in synced release notes", (
     syncReleaseNotes(["--repo", "getpaseo/paseo", "--tag", "v0.1.60-beta.1"], {
       execFileSync,
     });
-
-    assert.match(syncedNotes, /by @therainisme\)/);
-    assert.doesNotMatch(syncedNotes, /\[@therainisme\]\(https:\/\/github\.com\/therainisme\)/);
   }, changelogText);
+  return syncedNotes;
+}
+
+test("converts contributor profile links to mentions in synced release notes", () => {
+  const syncedNotes = syncedReleaseBody(
+    [
+      "## 0.1.60-beta.1 - 2026-04-20",
+      "",
+      "- Beta notes. ([#526](https://github.com/getpaseo/paseo/pull/526) by [@therainisme](https://github.com/therainisme))",
+      "",
+    ].join("\n"),
+  );
+
+  assert.match(syncedNotes, /by @therainisme\)/);
+  assert.doesNotMatch(syncedNotes, /\[@therainisme\]\(https:\/\/github\.com\/therainisme\)/);
+});
+
+test("leads with the highlights and folds the sections into one collapsed block", () => {
+  const syncedNotes = syncedReleaseBody(
+    [
+      "## 0.1.60-beta.1 - 2026-04-20",
+      "",
+      "- **Faster diffs:** Diffs load sooner.",
+      "",
+      "### Added",
+      "",
+      "- Added a picker",
+      "",
+      "### Fixed",
+      "",
+      "- Fixed a crash",
+      "",
+      "## 0.1.59 - 2026-04-10",
+      "",
+      "### Fixed",
+      "",
+      "- Fixed an older thing",
+      "",
+    ].join("\n"),
+  );
+
+  assert.equal(
+    syncedNotes,
+    [
+      "## 0.1.60-beta.1 - 2026-04-20",
+      "",
+      "- **Faster diffs:** Diffs load sooner.",
+      "",
+      "<details>",
+      "<summary>All changes</summary>",
+      "",
+      "### Added",
+      "",
+      "- Added a picker",
+      "",
+      "### Fixed",
+      "",
+      "- Fixed a crash",
+      "",
+      "</details>",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("keeps the sections in view when an entry has no highlights", () => {
+  const syncedNotes = syncedReleaseBody(
+    "## 0.1.60-beta.1 - 2026-04-20\n\n### Fixed\n\n- Fixed a crash\n",
+  );
+
+  assert.equal(syncedNotes, "## 0.1.60-beta.1 - 2026-04-20\n\n### Fixed\n\n- Fixed a crash\n");
 });
diff --git a/scripts/test-support/changelog-structure.json b/scripts/test-support/changelog-structure.json
new file mode 100644
index 0000000000..479dd69e9c
--- /dev/null
+++ b/scripts/test-support/changelog-structure.json
@@ -0,0 +1,167 @@
+{
+  "document": [
+    "# Changelog",
+    "",
+    "Text above the first release belongs to no release.",
+    "",
+    "## 4.0.0 - 2026-04-04",
+    "",
+    "- **First highlight:** One sentence. A second one. ([#1](https://example.com/1))",
+    "- **Nested content:** A highlight with a nested list.",
+    "  - Nested item",
+    "",
+    "  A second paragraph inside the item.",
+    "",
+    "- **Markdown example:** A fenced block whose contents look like headings.",
+    "",
+    "  ```markdown",
+    "  ## 9.9.9 - 2026-09-09",
+    "  ### Not a section",
+    "  ```",
+    "",
+    "```",
+    "## 9.9.8 - 2026-09-08",
+    "### Not a section either",
+    "```",
+    "",
+    "#### A deeper heading is not a section",
+    "",
+    "###Unspaced hashes are text",
+    "",
+    "### Added  ",
+    "",
+    "- Added a thing ([#2](https://example.com/2))",
+    "",
+    "#### A sub-heading stays in its section",
+    "",
+    "~~~~",
+    "### Still code",
+    "~~~",
+    "## 9.9.7 - 2026-09-07",
+    "~~~~",
+    "",
+    "###\tChanged",
+    "",
+    "- Changed a thing",
+    "",
+    "### 修复",
+    "",
+    "- 修复了一个问题",
+    "",
+    "## 3.0.0 - 2026-03-03",
+    "",
+    "### Fixed",
+    "",
+    "- Fixed one thing",
+    "",
+    "## 3.0.0-beta.1 - 2026-03-01",
+    "",
+    "> **Notice**",
+    ">",
+    "> A quoted notice opens this entry.",
+    "",
+    "A summary paragraph follows it.",
+    "",
+    "### Added",
+    "",
+    "- Added another thing",
+    "",
+    "## 2.0.0 - 2026-02-02",
+    "",
+    "- **Only a highlight:** No sections follow.",
+    "",
+    "## 1.0.0 - 2026-01-01",
+    "",
+    "Text before a heading with no title.",
+    "",
+    "###",
+    "",
+    "- The first section has no title",
+    ""
+  ],
+  "releases": [
+    {
+      "version": "4.0.0",
+      "date": "2026-04-04",
+      "highlights": [
+        "- **First highlight:** One sentence. A second one. ([#1](https://example.com/1))",
+        "- **Nested content:** A highlight with a nested list.",
+        "  - Nested item",
+        "",
+        "  A second paragraph inside the item.",
+        "",
+        "- **Markdown example:** A fenced block whose contents look like headings.",
+        "",
+        "  ```markdown",
+        "  ## 9.9.9 - 2026-09-09",
+        "  ### Not a section",
+        "  ```",
+        "",
+        "```",
+        "## 9.9.8 - 2026-09-08",
+        "### Not a section either",
+        "```",
+        "",
+        "#### A deeper heading is not a section",
+        "",
+        "###Unspaced hashes are text"
+      ],
+      "sections": [
+        "### Added  ",
+        "",
+        "- Added a thing ([#2](https://example.com/2))",
+        "",
+        "#### A sub-heading stays in its section",
+        "",
+        "~~~~",
+        "### Still code",
+        "~~~",
+        "## 9.9.7 - 2026-09-07",
+        "~~~~",
+        "",
+        "###\tChanged",
+        "",
+        "- Changed a thing",
+        "",
+        "### 修复",
+        "",
+        "- 修复了一个问题"
+      ],
+      "sectionTitles": ["Added", "Changed", "修复"]
+    },
+    {
+      "version": "3.0.0",
+      "date": "2026-03-03",
+      "highlights": [],
+      "sections": ["### Fixed", "", "- Fixed one thing"],
+      "sectionTitles": ["Fixed"]
+    },
+    {
+      "version": "3.0.0-beta.1",
+      "date": "2026-03-01",
+      "highlights": [
+        "> **Notice**",
+        ">",
+        "> A quoted notice opens this entry.",
+        "",
+        "A summary paragraph follows it."
+      ],
+      "sections": ["### Added", "", "- Added another thing"],
+      "sectionTitles": ["Added"]
+    },
+    {
+      "version": "2.0.0",
+      "date": "2026-02-02",
+      "highlights": ["- **Only a highlight:** No sections follow."],
+      "sections": [],
+      "sectionTitles": []
+    },
+    {
+      "version": "1.0.0",
+      "date": "2026-01-01",
+      "highlights": ["Text before a heading with no title."],
+      "sections": ["###", "", "- The first section has no title"],
+      "sectionTitles": [""]
+    }
+  ]
+}
diff --git a/skills/paseo-plugin/SKILL.md b/skills/paseo-plugin/SKILL.md
index b54938ad53..53a301eeb6 100644
--- a/skills/paseo-plugin/SKILL.md
+++ b/skills/paseo-plugin/SKILL.md
@@ -27,22 +27,23 @@ public docs; this skill indexes the references and examples.
 
 Pick the contribution that matches the request. Each row names the registration, when it fits, and where the full contract lives. Most plugins combine several: a slash command that calls an RPC, which appends a timeline row, which a renderer draws.
 
-| Contribution              | Registration                                                | Use it when                                                                                                                                                      | Reference                                                                                          |
-| ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| Screen and sidebar item   | `addScreen` + `addSidebarHeaderItem`/`addSidebarFooterItem` | A full screen of plugin UI, or sidebar header or footer rows that open a screen or popover                                                                       | reference.md → Screens and sidebar items                                                           |
-| Workspace panel           | `addWorkspacePanel`                                         | UI that lives as a tab beside agents, terminals, files, and diffs; `locations: ["explorer"]` for the Explorer                                                    | reference.md → Workspace panels                                                                    |
-| File panel                | `addFilePanel`                                              | View or edit a matching file inside the file tab through its file handle                                                                                         | reference.md → File panels; `plugin-examples/pdf-panel`, `plugin-examples/markdown-panel`          |
-| Command Center item       | `addCommandCenterItem`                                      | A global, workspace, or agent action reachable from ⌘K                                                                                                           | reference.md → Command Center items                                                                |
-| Client slash command      | `addSlashCommand`                                           | A `/command args` in the composer that runs plugin code instead of prompting the agent                                                                           | reference.md → Slash commands                                                                      |
-| Composer pill             | `addComposerPill`                                           | A per-agent button in the composer track bar next to Tasks and Subagents                                                                                         | reference.md → Composer pills                                                                      |
-| Timeline transformer      | `addTimelineTransformer` + `addTimelineRenderer`            | Replace, explode, or hide a built-in timeline item, including while it streams                                                                                   | reference.md → Timeline items; `plugin-examples/timeline-items`, `plugin-examples/inline-thinking` |
-| Timeline row              | `paseo.agents.ref(id).timeline.append(...)`                 | Push a plugin-owned row into an agent timeline from a server handler and update it later                                                                         | reference.md → Append a timeline row from the daemon                                               |
-| Attachment source         | `client.addAttachmentSource` + `server.handle`              | Let the user attach a searchable external resource, such as an issue, to a prompt                                                                                | reference.md → Add a composer attachment source; `plugin-examples/linear`                          |
-| Theme                     | `addTheme`                                                  | A light or dark palette under Settings → Appearance                                                                                                              | reference.md → Contribute a theme; `plugin-examples/catppuccin`                                    |
-| Plugin RPC                | `defineRpc` + `server.handle` + `useRpc`                    | Daemon-side work that is not a normal Paseo operation: vendor APIs, credentials, local files                                                                     | reference.md → Add plugin-specific backend behavior                                                |
-| Lifecycle events          | `server.on`                                                 | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests                                                                           | [Lifecycle hooks](https://paseo.sh/docs/plugins/reference.md#lifecycle-hooks)                      |
-| Creation and launch hooks | `server.before`                                             | `agent.create` edits saved config; `agent.session_open` contributes launch-only `env`, `tools`, `mcpServers` on every open; `workspace.create` chooses isolation | [Before hooks](https://paseo.sh/docs/plugins/reference.md#before-hooks)                            |
-| Paseo SDK                 | `usePaseo()` / handler `{ paseo }`                          | Normal Paseo operations: workspaces, agents, providers, config                                                                                                   | reference.md → Use the Paseo SDK                                                                   |
+| Contribution              | Registration                                                | Use it when                                                                                                                                                      | Reference                                                                                                  |
+| ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Screen and sidebar item   | `addScreen` + `addSidebarHeaderItem`/`addSidebarFooterItem` | A full screen of plugin UI, or sidebar header or footer rows that open a screen or popover                                                                       | reference.md → Screens and sidebar items                                                                   |
+| Workspace panel           | `addWorkspacePanel`                                         | UI that lives as a tab beside agents, terminals, files, and diffs; `locations: ["explorer"]` for the Explorer                                                    | reference.md → Workspace panels                                                                            |
+| File panel                | `addFilePanel`                                              | View or edit a matching file inside the file tab through its file handle                                                                                         | reference.md → File panels; `plugin-examples/pdf-panel`, `plugin-examples/markdown-panel`                  |
+| Command Center item       | `addCommandCenterItem`                                      | A global, workspace, or agent action reachable from ⌘K                                                                                                           | reference.md → Command Center items                                                                        |
+| Client slash command      | `addSlashCommand`                                           | A `/command args` in the composer that runs plugin code instead of prompting the agent                                                                           | reference.md → Slash commands                                                                              |
+| Composer pill             | `addComposerPill`                                           | A per-agent button in the composer track bar next to Tasks and Subagents                                                                                         | reference.md → Composer pills                                                                              |
+| Timeline transformer      | `addTimelineTransformer` + `addTimelineRenderer`            | Replace, explode, or hide a built-in timeline item, including while it streams                                                                                   | reference.md → Timeline items; `plugin-examples/timeline-items`, `plugin-examples/inline-thinking`         |
+| Timeline row              | `paseo.agents.ref(id).timeline.append(...)`                 | Push a plugin-owned row into an agent timeline from a server handler and update it later                                                                         | reference.md → Append a timeline row from the daemon                                                       |
+| Attachment source         | `client.addAttachmentSource` + `server.handle`              | Let the user attach a searchable external resource, such as an issue, to a prompt                                                                                | reference.md → Add a composer attachment source; `plugin-examples/linear`                                  |
+| Theme                     | `addTheme`                                                  | A light or dark palette under Settings → Appearance                                                                                                              | reference.md → Contribute a theme; `plugin-examples/catppuccin`                                            |
+| Plugin RPC                | `defineRpc` + `server.handle` + `useRpc`                    | Daemon-side work that is not a normal Paseo operation: vendor APIs, credentials, local files                                                                     | reference.md → Add plugin-specific backend behavior                                                        |
+| Plugin subscription       | `defineSubscription` + `server.handle` + `useSubscription`  | A daemon handler that pushes events while a surface listens: watchers, tails, live media; a top-level `Uint8Array` rides as binary                               | reference.md → Stream events from the daemon; `plugin-examples/diff-watch`, `plugin-examples/media-stream` |
+| Lifecycle events          | `server.on`                                                 | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests                                                                           | [Lifecycle hooks](https://paseo.sh/docs/plugins/reference.md#lifecycle-hooks)                              |
+| Creation and launch hooks | `server.before`                                             | `agent.create` edits saved config; `agent.session_open` contributes launch-only `env`, `tools`, `mcpServers` on every open; `workspace.create` chooses isolation | [Before hooks](https://paseo.sh/docs/plugins/reference.md#before-hooks)                                    |
+| Paseo SDK                 | `usePaseo()` / handler `{ paseo }`                          | Normal Paseo operations: workspaces, agents, providers, config                                                                                                   | reference.md → Use the Paseo SDK                                                                           |
 
 | Lifecycle task                                                         | Example                                                                                                |
 | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -374,7 +375,7 @@ function Greeting() {
 }
 ```
 
-Inputs and outputs are validated on both sides. Backend handlers receive the same `PaseoApi` as `{ paseo }`; their IPC-backed daemon session lives exactly as long as the subprocess. Backend code can use Node APIs and installed dependencies. Keep credentials, filesystem access, shell commands, and vendor API calls in the handler rather than the client surface.
+Inputs and outputs are validated on both sides. A top-level `Uint8Array` input or output (declared `z.instanceof(Uint8Array)`) crosses as binary; a nested one fails validation. For a stream of events, use `defineSubscription` and `useSubscription`; see [subscriptions](https://paseo.sh/docs/plugins/reference.md#subscriptions). Backend handlers receive the same `PaseoApi` as `{ paseo }`; their IPC-backed daemon session lives exactly as long as the subprocess. Backend code can use Node APIs and installed dependencies. Keep credentials, filesystem access, shell commands, and vendor API calls in the handler rather than the client surface.
 
 Use TanStack Query for async request state, caching, and mutations.